Binary Format

Code Metadata

A Code Metadata item is a piece of information logically attached to an instruction.

An item is associated with a format, which defines the item’s payload.

All code metadata items of a format named T are grouped under a custom section named ‘metadata.code.T’. The following parametrized grammar rules define the generic structure of a code metadata section of format T.

\[\begin{split}\begin{array}{llcll} \def\mathdef1#1{{}}\mathdef1{code metadata section} & \href{binary.html#binary-codemetadata}{\mathtt{codemetadatasec}}(\mathtt{T}) &::=& \href{../../core/binary/modules.html#binary-section}{\mathtt{section}}_0(\href{binary.html#binary-codemetadata}{\mathtt{codemetadata}}(\mathtt{T})) \\ \def\mathdef1#1{{}}\mathdef1{code metadata} & \href{binary.html#binary-codemetadata}{\mathtt{codemetadata}}(\mathtt{T}) &::=& n{:}\href{../../core/binary/values.html#binary-name}{\mathtt{name}} & (\mathrel{\mbox{if}} n = \def\mathdef40#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef40{metadata.code.T}) \\ &&& \href{../../core/binary/conventions.html#binary-vec}{\mathtt{vec}}(\href{binary.html#binary-codemetadata}{\mathtt{codemetadatafunc}}(\mathtt{T})) \\ \def\mathdef1#1{{}}\mathdef1{code metadata function} & \href{binary.html#binary-codemetadata}{\mathtt{codemetadatafunc}}(\mathtt{T}) &::=& x{:}\href{../../core/binary/modules.html#binary-funcidx}{\mathtt{funcidx}}~\href{../../core/binary/conventions.html#binary-vec}{\mathtt{vec}}(\href{binary.html#binary-codemetadata}{\mathtt{codemetadataitem}}(\mathtt{T})) \\ \def\mathdef1#1{{}}\mathdef1{code metadata item} & \href{binary.html#binary-codemetadata}{\mathtt{codemetadataitem}}(\mathtt{T}) &::=& \mathit{off}{:}\href{../../core/binary/values.html#binary-int}{\def\mathdef6#1{{\mathtt{u}#1}}\mathdef6{\mathtt{32}}} ~~ \mathit{size}{:}\href{../../core/binary/values.html#binary-int}{\def\mathdef6#1{{\mathtt{u}#1}}\mathdef6{\mathtt{32}}} & (\mathrel{\mbox{if}} \mathit{size} = ||\mathtt{T}||) \\ &&& \mathit{data}{:}\mathtt{T} \\ \end{array}\end{split}\]

Where \(\mathit{off}\) is the byte offset of the attached instruction, relative to the beginning of the \(\href{../../core/binary/modules.html#binary-func}{\mathtt{func}}\) declaration, and \(\mathit{data}\) is a further payload, whose content depends on the format \(T\).

\(\href{binary.html#binary-codemetadata}{\mathtt{codemetadatafunc}}\) entries must appear in order of increasing \(x\), and duplicate id values are not allowed. \(\href{binary.html#binary-codemetadata}{\mathtt{codemetadata}}\) entries must appear in order of increasing \(\mathit{off}\), and duplicate offset values are not allowed.

Branch Hints

A Branch Hint is a code metadata item with format branch_hint.

It can only be attached to \(\href{../../core/syntax/instructions.html#syntax-instr-control}{\mathsf{br\_if}}\) and \(\href{../../core/syntax/instructions.html#syntax-instr-control}{\mathsf{if}}\) instructions.

Its payload indicates whether the branch is likely or unlikely to be taken.

All branch hints for a module are contained in a single code metadata section with name ‘metadata.code.branch_hint’.

\[\begin{split}\begin{array}{llcll} \def\mathdef1#1{{}}\mathdef1{branch hint section} & \href{binary.html#binary-branchhints}{\mathtt{branchhintsec}} &::=& \href{binary.html#binary-codemetadata}{\mathtt{codemetadatasec}}(\href{binary.html#binary-branchhints}{\mathtt{branchhint}}) \\ \def\mathdef1#1{{}}\mathdef1{branch hint} & \href{binary.html#binary-branchhints}{\mathtt{branchhint}} &::=& \href{binary.html#binary-branchhints}{\mathtt{unlikely}} \\ &&|& \href{binary.html#binary-branchhints}{\mathtt{likely}} \\ \def\mathdef1#1{{}}\mathdef1{unlikely} & \href{binary.html#binary-branchhints}{\mathtt{unlikely}} &::=& \def\mathdef41#1{\mathtt{0x#1}}\mathdef41{00} \\ \def\mathdef1#1{{}}\mathdef1{likely} & \href{binary.html#binary-branchhints}{\mathtt{likely}} &::=& \def\mathdef42#1{\mathtt{0x#1}}\mathdef42{01} \\ \end{array}\end{split}\]

A value of \(\href{binary.html#binary-branchhints}{\mathtt{likely}}\) means that the branch is likely to be taken, while a value of \(\href{binary.html#binary-branchhints}{\mathtt{unlikely}}\) means the opposite. A branch with no hints is considered equally likely to be taken or not.