performance(casm): Made casm builder build-alg linear. #9489

orizi · 2026-01-17T08:07:41Z

Summary

Refactored the CASM builder to improve label handling and instruction relocation. The PR replaces the Statement enum with a more direct approach that separates instructions from relocations, making the code more maintainable. It introduces a dedicated LabelRelocation struct and Offset type to track and apply relocations more efficiently, eliminating the need to compute label offsets in a separate pass.

Type of change

Please check one:

Bug fix (fixes incorrect behavior)
New feature
Performance improvement
Documentation change with concrete technical impact
Style, wording, formatting, or typo-only change

Why is this change needed?

The previous implementation used a complex approach with a Statement enum that mixed instructions, jumps, and labels. This required a separate pass to compute label offsets and apply relocations. The new implementation is more direct, tracking instructions and relocations separately, which simplifies the code and improves performance by eliminating the need for the extra computation pass.

What was the behavior or documentation before?

The builder used a Statement enum with three variants (Final, Jump, Label) and required a separate pass to compute label offsets before applying relocations to jump instructions.

What is the behavior or documentation after?

The builder now directly stores instructions and tracks relocations separately with a dedicated LabelRelocation struct. Label offsets are tracked in the LabelInfo struct with an Offset type, allowing for more efficient relocation handling without requiring a separate computation pass.

Additional context

This refactoring maintains the same functionality while making the code more maintainable and potentially more efficient by eliminating unnecessary computation steps. The change is internal to the CASM builder and doesn't affect its public API.

orizi · 2026-01-17T08:07:57Z

This stack of pull requests is managed by Graphite. Learn more about stacking.

reviewable-StarkWare · 2026-01-17T08:08:03Z

This change is

eytan-starkware

Please add tests checking multiple branches, and something that tests future_label

@eytan-starkware reviewed all commit messages and made 9 comments.
Reviewable status: 0 of 1 files reviewed, 8 unresolved discussions (waiting on @orizi and @TomerStarkware).

crates/cairo-lang-casm/src/builder.rs line 104 at r1 (raw file):

    /// The index of the instruction that needs to be relocated.
    instruction_index: usize,
    /// The code offset if the instruction to be relocated.

Fix comment

crates/cairo-lang-casm/src/builder.rs line 121 at r1 (raw file):

    state: State,
    /// The offset of the label. If not set means not yet reached (and not read-only).
    offset: Offset,

If it might not yet be set shouldnt it just be option?

crates/cairo-lang-casm/src/builder.rs line 128 at r1 (raw file):

impl Offset {
    /// The value for an unset offset.
    const UNSET: Offset = Offset(usize::MAX);

Should be u32, as later you assume it fits i32. Even better to keep it i32

crates/cairo-lang-casm/src/builder.rs line 172 at r1 (raw file):

        let mut branch_relocations: [Vec<usize>; BRANCH_COUNT] =
            core::array::from_fn(|_| Vec::new());
        for r in self.relocations {

relocation

Code quote:

crates/cairo-lang-casm/src/builder.rs line 179 at r1 (raw file):

                relocate_instruction(
                    &mut self.instructions[r.instruction_index],
                    label_offset.0 as i32 - r.instruction_offset as i32,

I assume this will never overflow, but how big can we get here?

crates/cairo-lang-casm/src/builder.rs line 442 at r1 (raw file):

        );
        let state = core::mem::take(&mut self.main_state);
        self.set_or_test_label(label, state);

You are taking state and not returning it on purpose?

crates/cairo-lang-casm/src/builder.rs line 742 at r1 (raw file):

/// Relocates an instruction by updating its jump offset.
fn relocate_instruction(instruction: &mut Instruction, updated: i32) {

#[inline(always)]
fn relocate_instruction(

Code quote:

fn relocate_instruction(

crates/cairo-lang-casm/src/builder.rs line 749 at r1 (raw file):

        })
        | InstructionBody::Jump(JumpInstruction {
            target: DerefOrImmediate::Immediate(value),

Does jump target really need to be bigint?

orizi

@orizi made 8 comments.
Reviewable status: 0 of 1 files reviewed, 8 unresolved discussions (waiting on @eytan-starkware and @TomerStarkware).

crates/cairo-lang-casm/src/builder.rs line 104 at r1 (raw file):