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{array}{r} \begin{array}{llcll} codemetadatasec (T) & ::= & {section}_{0} (codemetadata (T)) \\ codemetadata (T) & ::= & n : name & (if n = ‘ metadata . code . T ’) \\ vec (codemetadatafunc (T)) \\ codemetadatafunc (T) & ::= & x : funcidx vec (codemetadataitem (T)) \\ codemetadataitem (T) & ::= & off : u 32 size : u 32 & (if size = | | T | |) \\ data : T \end{array} \end{array}

Where $off$ is the byte offset of the attached instruction, relative to the beginning of the $func$ declaration, and $data$ is a further payload, whose content depends on the format $T$ .

$codemetadatafunc$ entries must appear in order of increasing $x$ , and duplicate id values are not allowed. $codemetadata$ entries must appear in order of increasing $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 $br_if$ and $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{array}{r} \begin{array}{llcll} branchhintsec & ::= & codemetadatasec (branchhint) \\ branchhint & ::= & unlikely \\ | & likely \\ unlikely & ::= & 0 x 00 \\ likely & ::= & 0 x 01 \end{array} \end{array}

A value of $likely$ means that the branch is likely to be taken, while a value of $unlikely$ means the opposite. A branch with no hints is considered equally likely to be taken or not.