Struct StackMapSection

pub struct StackMapSection { /* private fields */ }

Builder for the ELF_WASMTIME_STACK_MAP section in compiled executables.

This format is parsed by crate::stack_map.

The current layout of the format is:

┌─────────────────────┬───── 0x00 (relative, not necessarily aligned)
│ count: 4-byte LE    │
├─────────────────────┼───── 0x04
│ pc1: 4-byte LE      │
│ pc2: 4-byte LE      │
│ ...                 │
│ pcN: 4-byte LE      │
├─────────────────────┼───── 0x04 + 4 * count
│ offset1: 4-byte LE  │
│ offset1: 4-byte LE  │
│ ...                 │
│ offsetN: 4-byte LE  │
├─────────────────────┼───── 0x04 + 8 * count
│ data[0]: 4-byte LE  │
│ data[1]: 4-byte LE  │
│ ...                 │
│ data[M]: 4-byte LE  │
└─────────────────────┴───── 0x04 + 8 * count + 4 * M

Here count is the size of the pcN and offsetN arrays. The two arrays are the same size and have corresponding entries in one another. When looking up a stack map for a particular program counter:

• A binary search is performed on the pcN array.
• The corresponding offsetM value is looked up once the pcM entry, matching the lookup pc, is found.
• The offsetM value is used to access data[offsetM] which is an array of 4-byte entries located after the offset* array. This stack map is then encoded as below.

This encoding scheme is chosen so parsing this data structure effectively isn’t required. It’s usable at-rest from a compiled artifact in a section of an executable. Notably having offsets into the data array means that a stack map is just a slice into the data array, and the entire data structure can be “parsed” by reading count and otherwise just making sure various offsets are in-bounds.

A stack map located at data[offsetM] is encoded as:

┌───────────────────────────────────────────────────────┐
│ data[offsetM + 0]: frame_size: 4-byte LE              │
├───────────────────────────────────────────────────────┤
│ data[offsetM + 1]: count: 4-byte LE                   │
├───────────────────────────────────────────────────────┤
│ data[offsetM + 2 + 0]: bitmap: 4-byte LE              │
│ data[offsetM + 2 + 1]: bitmap: 4-byte LE              │
│ ...                                                   │
│ data[offsetM + 2 + count - 1]: bitmap: 4-byte LE      │
└───────────────────────────────────────────────────────┘

Here frame_size and count are always greater than 0. Entries in the bit map represent stack_slot / 4 so must be multiplied by 4 to get the actual stack offset entry. This is because all stack slots are aligned at 4 bytes so by dividing them all by 4 we’re able to compress the bit map that much more.

Implementations

impl StackMapSection

pub fn push( &mut self, code_offset: u64, frame_size: u32, frame_offsets: impl ExactSizeIterator<Item = u32>, )

Appends stack map information for code_offset which has the specified frame_size and frame_offsets are the active GC references.

pub fn append_to(self, obj: &mut Object<'_>)

Finishes encoding this section into the Object provided.

Trait Implementations

impl Default for StackMapSection

fn default() -> StackMapSection

Returns the “default value” for a type.