Contract GCInfo

This contract is for fetching information related to GCInfo associated with native code. Currently, this contract does not support x86 architecture.

APIs of contract

public interface IGCInfoHandle { }

// Decodes GCInfo using the platform-specific encoding for the target architecture
IGCInfoHandle DecodePlatformSpecificGCInfo(TargetPointer gcInfoAddress, uint gcVersion);

// Decodes GCInfo using the interpreter encoding, regardless of target architecture
IGCInfoHandle DecodeInterpreterGCInfo(TargetPointer gcInfoAddress, uint gcVersion);

/* Methods to query information from the GCInfo */

// Fetches length of code as reported in GCInfo
uint GetCodeLength(IGCInfoHandle handle);

Version 1

Data descriptors used:

Contracts used:

Constants:

Implementation

The GCInfo contract has platform specific implementations as GCInfo differs per architecture. With the exception of x86, all platforms have a common encoding scheme with different encoding lengths and normalization functions for data. x86 uses an entirely different scheme which is not currently supported by this contract.

GCInfo Format

The GCInfo format consists of a header structure and following data types. The header is either 'slim' for simple methods that can use the compact encoding scheme or a 'fat' header containing more details.

GCInfo Header

Slim Header

All other values are assumed to be 0.

Fat Header

The fat header is used for methods that cannot be encoded using the compact slim header format. It contains additional flags and optional fields based on method characteristics.

Header Flags

The HeaderFlags field contains the following bit flags:

GCInfo Body

Following the header, the GCInfo body contains several data sections in the following order:

1. Call Sites Offsets - Encoded offsets of call sites/safe points (if PARTIALLY_INTERRUPTIBLE_GC_SUPPORTED)
2. Interruptible Ranges - Ranges where the method can be interrupted for GC
3. Slot Table - Information about GC-tracked slots (registers and stack locations)

The rest of the GCInfo body is not yet decoded in the cDAC.

Interruptible Ranges

Interruptible ranges define code regions where garbage collection can safely occur. Each range is encoded as:

• StartOffset - Normalized code offset where the range begins
• Length - Normalized length of the interruptible region

The ranges are encoded using delta compression, where each range's start offset is relative to the previous range's end offset.

Slot Table

The slot table describes all GC-tracked locations (registers and stack slots) used by the method. It consists of three sections:

1. Register Slots - GC-tracked CPU registers
2. Stack Slots - GC-tracked stack locations
3. Untracked Slots - Stack locations that are not GC-tracked

Each slot entry contains:

• Location - Register number or stack offset
• Flags - GC slot type (base pointer, interior pointer, pinned, untracked)
• Base - For stack slots: caller SP relative, SP relative, or frame register relative

Slots use delta encoding where consecutive entries encode only the difference from the previous entry when flags match.

Platform specific constants

AMD64

AMD64 Normalization/Denormalization Rules

ARM64

ARM64 Normalization/Denormalization Rules

ARM (32-bit)

ARM (32-bit) Normalization/Denormalization Rules

Interpreter (WASM / FEATURE_INTERPRETER)

The interpreter uses a platform-independent encoding where all normalization and denormalization functions are identity (no transformation). This encoding is used for WASM targets (where TargetGcInfoEncoding is InterpreterGcInfoEncoding) and on any architecture when FEATURE_INTERPRETER is enabled.

Interpreter Normalization/Denormalization Rules

All normalization and denormalization operations are identity functions (no transformation):

The interpreter does not have a fixed stack parameter scratch area (HAS_FIXED_STACK_PARAMETER_SCRATCH_AREA = false).

Encoding Scheme

GCInfo uses a variable-length encoding scheme to efficiently store numeric values. The encoding is designed to use fewer bits for smaller, more common values.

Variable Length Unsigned Encoding

Numbers are encoded using a base number of bits plus extension bits when needed:

1. Base Encoding: Use base bits to store the value
2. Extension Bit: If the value doesn't fit in base bits, set bit base to 1 and use base+1 additional bits
3. Continuation: This process continues until the value fits

The minimum encoding uses base+1 bits, where bit base indicates if more bits follow.

Example with base=3:

• Value 0-6: Encoded in 4 bits as 0XXX (where XXX is the 3-bit value)
• Value 7-14: Encoded in 8 bits as 1XXX YYYY (where XXX are the low 3 bits, YYYY are the next 4 bits)
• Value 15+: Uses additional extension groups

Variable Length Signed Encoding

Signed values use the same encoding as unsigned, but with sign considerations:

• A number fits in base bits if the topmost bit of the base-bit chunk matches the sign of the entire number
• This ensures proper sign extension when decoding

Implementation

The GCInfo contract implementation follows this process:

IGCInfoHandle DecodePlatformSpecificGCInfo(TargetPointer gcInfoAddress, uint gcVersion)
{
    // Create a new decoder instance for the specified platform traits
    return new GcInfoDecoder<PlatformTraits>(target, gcInfoAddress, gcVersion);
}

IGCInfoHandle DecodeInterpreterGCInfo(TargetPointer gcInfoAddress, uint gcVersion)
{
    // Create a new decoder instance using the interpreter encoding
    return new GcInfoDecoder<InterpreterGCInfoTraits>(target, gcInfoAddress, gcVersion);
}

uint GetCodeLength(IGCInfoHandle handle)
{
    // Cast to the appropriate decoder type and return the decoded code length
    GcInfoDecoder<PlatformTraits> decoder = (GcInfoDecoder<PlatformTraits>)handle;
    return decoder.GetCodeLength();
}

The decoder reads and parses the GCInfo data structure sequentially, using the platform-specific encoding bases and normalization rules to reconstruct the original method metadata.