runtime_core/docs/code_metainfo.md

# Compiled Code Metainfo

## Overview

Metainfo is an information that aims to provide reg-to-stack mapping for virtual registers. It is needed for stack
unwinding process to restore CFrame at specific PC.

When native code calls runtime or another code that can call runtime, we must provide approach to restore virtual
registers which are live during this call instruction. Since all virtual regisetrs should be saved on the stack before
we call the runtime, we can save information in which stack slot specific vreg is live.

Metainfo is placed together with compiled code:
```
 +-------------+
 | CodePrefix  |
 |             +-------------------+
 |             |  magic            |
 |             |  code_info_offset |
 |             |  code_info_size   |
 +-------------+-------------------+
 |             | <-- Method::CompiledCodeEntrypoint
 | Code        |
 |             |
 +-------------+-----------------+
 | CodeInfo    | CodeInfoHeader  |
 |             |-----------------+----------------------+
 |             |                 |  StackMap            |
 |             |                 |  InlineInfo          |
 |             |                 |  Roots Reg Mask      |
 |             |                 |  Roots Stack Mask    |
 |             |   Bit Tables    |  Method indexes      |
 |             |                 |  VRegs mask          |
 |             |                 |  VRegs map           |
 |             |                 |  VRegs catalogue     |
 |             |                 |  Implicit Nullchecks |
 |             |                 |  Constants           |
 |-------------+-----------------+----------------------+
```

## Bit table

Columns width is in a bits.

First row is a BitTable's header, that describe rows count and columns width.

```
+------------+----------------+----------------+----------------+
| Rows count | Column 0 width |      . . .     | Column N width |
+------------+----------------+----------------+----------------+
```
Header is followed by data, which is a rows with fixed length. Row length is equal to sum of columns width.

Column width can't be greater than 32 bits, because `BitTableBuilder` class, that aims to build bit tables,
use `uint32_t` for a single table element.

Example:
```
 Rows
 count         Columns
+-----+-----+-----+-------+-----+
|  5  |  2  |  0  |  15   |  8  |  ; Header
+-----+-----+-----+-------+-----+
      |  2  |  -  | 31547 |  23 |  ; 0 row
      |  1  |  -  |    12 | 241 |  ; 1 row
      |  1  |  -  |   128 |   1 |  ; 2 row
      |  2  |  -  |     0 |  24 |  ; 3 row
      |  0  |  -  |  4587 |   0 |  ; 4 row
      +-----+-----+-------+-----+
```
Here, we have 4 columns and 5 rows. Number of rows is defeined in the first digit in a header,
number of columns is determined in compile time.

Row size is 25 bits, that is sum of columns width: 2 + 0 + 15 + 8.
Column width is determined by maximum value in a table, e.g. for 2th column it is zero row, that has value 31547. This value fits in 15 bits.

So, the size of this table's data is 25 * 5 = 125 bits = 15.625 bytes.

## Bitmap table

Bitmap table is a Bit table with one column, that doesn't have 32-bits limitation for the width.

## Numbers packing

For number compressisng following approach is used.

The first four bits determine the variable length of the encoded number:
- Values 0..11 represent the result as-is, with no further following bits.
- Values 12..15 mean the result is in the next 8/16/24/32-bits respectively.

Example for numbers (2, 0, 15, 254874):
```
+---------+---------+---------+---------+---------+---------+
| 0 byte  | 1 byte  | 2 byte  | 3 byte  | 4 byte  | 5 byte  |
+---------+---------+---------+---------+---------+---------+
|  2 |  0 | 12 | 14 |    15   |            254874           |
+---------+---------+---------+---------+---------+---------+
```

## Code header

Code headers describes structure of the compiled code and metainfo.

| Field | Description |
|-----|----|
| PROPERTIES | Properties of the code info (e.g. frame size) |
| CALLEE_REG_MASK | Specifies registers mask that is saved in the method |
| CALLEE_FP_REG_MASK | Specifies fp registers mask that is saved in the method |
| TABLE_MASK | Bit mask of existing bit tables |
| VREGS_COUNT | Number of virtual registers in reg map |

## Tables

### 1. StackMap

| Field | Description |
|-----|----|
| PROPERTIES | Define properties of the stackmap, currently, it contains only one flag: is_osr |
| NATIVE_PC | Native address to which this stackmap corresponds |
| BYTECODE_PC | Bytecode address to which this stackmap corresponds |
| ROOTS_REG_MASK_INDEX | Mask of the CPU registers that hold managed objects |
| ROOTS_STACK_MASK_INDEX | Mask of the stack slots that hold managed objects |
| INLINE_INFO_INDEX | Inline information for the stackmap |
| VREG_MASK_INDEX | Mask of the virtual registers, that are modified from the last stackmap to the current one |
| VREG_MAP_INDEX | Map of the virtual registers, that are modified from the last stackmap to the current one |

> NOTE: fields with `_INDEX` in the end of the name contain only index of the record in the corresponding table.

### 2. InlineInfo

| Field | Description |
|-----|----|
| IS_LAST | Whether this inlined method is a last, i.e. is it a leaf |
| BYTECODE_PC | Bytecode address to which this inline info corresponds |
| METHOD_ID_INDEX | Index of the method id in the Methods table |
| METHOD_HI | Hi 32-bit part of the method pointer (actual only for jit) |
| METHOD_LOW | Low 32-bit part of the method pointer (actual only for jit)  |
| VREGS_COUNT | Number of virtual registers, that belongs to this inlined method |

Stackmap and all its inlined infos use same Virtual registers map, but separate it via `VREGS_COUNT` field of inline infoes.

Example for inline chain `method 0` -> `inlines 1` -> `inlines 3`:
```
-------------
vreg 0
vreg 1  ; method 0: CodeInfoHeader::VREGS_COUNT=3
vreg 2
---------------
vreg 3  ; method 1: InlineInfo::VREGS_COUNT=1
---------------
vreg 4
vreg 5  ; method 3: InlineInfo::VREGS_COUNT=2
```

### 3. Roots Reg Mask

This is a Bitmap table, where column is a bit mask, that determines which CPU register holds a managed object.

### 4. Roots Stack Mask

This is a Bitmap table, where column is a bit mask, that determines which stack slot holds a managed object.

### 5. Method indexes

Holds single column - method index within a pandafile. It was moved to the separate table due to better deduplication.

### 6. VRegs mask

This is a Bitmap table, where column is a bit mask, that determines which virtual register is modified in the StackMap.

### 7. VRegs map

Holds single column - index of the VReg description in the `VRegs catalogue` table.

### 8. VRegs catalogue

| Field | Description |
|-----|----|
| INFO | Virtual register description |
| VALUE | Virtual register value |

Virtual register description has the following fields:
- **Location** - where vreg is stored: stack slot, CPU register or constant.
- **Type** - type of the value: OBJECT, INT32, INT64, FLOAT32, FLOAT64, BOOL.
- **IsAccumulator** - whethre vreg is accumulator.
- **Index** - index of the virtual register.

Value of the `VALUE` field depends on the value of `Location` field:
- CPU register: number of CPU register
- stack slot: number of the slot within a frame
- constant: index of a row within `Constants` table

### 9. Implicit nullchecks

This is a table with offsets: removed NullCheck instruction position and corresponding SlowPath position.
The table helps the signal handler to find the SlowPath address to continue execution after a segmentation fault.

| Field | Description |
|-----|----|
| INST_NATIVE_PC | NullCheck instruction position. |
| SLOW_PATH_NATIVE_PC | NullCheck SlowPath position. |

### 10. Constants

This table contains only one column - constant value.