diff --git a/air/Cargo.toml b/air/Cargo.toml index d6b22c3ed3..8972679399 100644 --- a/air/Cargo.toml +++ b/air/Cargo.toml @@ -46,4 +46,6 @@ p3-merkle-tree.workspace = true serde.workspace = true [dev-dependencies] +criterion.workspace = true +insta.workspace = true proptest.workspace = true diff --git a/air/src/trace/mod.rs b/air/src/trace/mod.rs index 8ac1bb1f0f..65d8dc13a5 100644 --- a/air/src/trace/mod.rs +++ b/air/src/trace/mod.rs @@ -3,19 +3,19 @@ use core::ops::Range; use chiplets::hasher::RATE_LEN; use miden_core::utils::range; +pub mod aux_trace; pub mod chiplets; pub mod decoder; +pub mod main_trace; pub mod range; +pub mod rows; pub mod stack; -mod rows; -pub use rows::{RowIndex, RowIndexError}; - -mod main_trace; -pub use main_trace::{MainTrace, MainTraceRow}; - -mod aux_trace; pub use aux_trace::AuxTraceBuilder; +pub use main_trace::{MainTrace, MainTraceRow}; +pub use rows::{RowIndex, RowIndexError}; +#[cfg(test)] +mod tests; // CONSTANTS // ================================================================================================ diff --git a/air/src/trace/snapshots/miden_air__trace__tests__ace_chiplet_layout.snap b/air/src/trace/snapshots/miden_air__trace__tests__ace_chiplet_layout.snap new file mode 100644 index 0000000000..0d5645aad4 --- /dev/null +++ b/air/src/trace/snapshots/miden_air__trace__tests__ace_chiplet_layout.snap @@ -0,0 +1,34 @@ +--- +source: air/src/trace/tests.rs +expression: layout +--- +ACE CHIPLET LAYOUT +===================== + +Chiplet Selectors: + Number of ACE selectors: 4 + +Column Indices (ordered by index): + - 0: Selector start + - 1: Selector block + - 2: Context + - 3: Pointer + - 4: Clock + - 5: Eval operation + - 6: ID 0 + - 7: Value 0_0 + - 8: Value 0_1 + - 9: ID 1 + - 10: Value 1_0 + - 11: Value 1_1 + - 12: ID 2 + - 12: Read num eval + - 13: Value 2_0 + - 14: Value 2_1 + - 14: Multiplicity 1 + - 15: Multiplicity 0 + +Other Constants: + Number of columns: 16 + ACE init label: 8 + Instruction ID2 offset: 1152921504606846976 diff --git a/air/src/trace/snapshots/miden_air__trace__tests__all_chiplet_column_ranges.snap b/air/src/trace/snapshots/miden_air__trace__tests__all_chiplet_column_ranges.snap new file mode 100644 index 0000000000..0d8e4b3749 --- /dev/null +++ b/air/src/trace/snapshots/miden_air__trace__tests__all_chiplet_column_ranges.snap @@ -0,0 +1,34 @@ +--- +source: air/src/trace/tests.rs +expression: layout +--- +ALL CHIPLET COLUMN RANGES +================================ + +Chiplet Selector Counts: + - Hasher selectors: 1 + - Bitwise selectors: 2 + - Memory selectors: 3 + - ACE selectors: 4 + - Kernel ROM selectors: 5 + +Hasher Chiplet: + Trace offset: 52 + Selector range: 52..55 (width 3) + State range: 55..67 (width 12) + Capacity range: 55..59 (width 4) + Rate range: 59..67 (width 8) + Node index: 67 + +Bitwise Chiplet: + Trace offset: 53 + Selector index: 53 + Input A range: 56..60 (width 4) + Input B range: 60..64 (width 4) + Trace range: 53..66 (width 13) + +Memory Chiplet: + Trace offset: 54 + Value range: 61..65 (width 4) + +Note: All column indices are relative to the main trace (not relative to the chiplet trace). diff --git a/air/src/trace/snapshots/miden_air__trace__tests__aux_trace_layout.snap b/air/src/trace/snapshots/miden_air__trace__tests__aux_trace_layout.snap new file mode 100644 index 0000000000..86e724f550 --- /dev/null +++ b/air/src/trace/snapshots/miden_air__trace__tests__aux_trace_layout.snap @@ -0,0 +1,39 @@ +--- +source: air/src/trace/tests.rs +expression: layout +--- +AUXILIARY TRACE LAYOUT +========================== + +Decoder Auxiliary Trace: + Offset: 0 + Width: 3 + Range: 0..3 + +Stack Auxiliary Trace: + Offset: 3 + Width: 1 + Range: 3..4 + +Range Check Auxiliary Trace: + Offset: 4 + Width: 1 + Range: 4..5 + +Hasher/Kernel ROM Virtual Table Auxiliary Trace: + Offset: 5 + Width: 1 + Range: 5..6 + +Chiplets Bus Auxiliary Trace: + Offset: 6 + Width: 1 + Range: 6..7 + +ACE Chiplet Wiring Bus: + Offset: 7 + Width: 1 + Range: 7..8 + +Total Auxiliary Trace Width: 8 +Auxiliary Trace Random Elements: 16 diff --git a/air/src/trace/snapshots/miden_air__trace__tests__bitwise_chiplet_layout.snap b/air/src/trace/snapshots/miden_air__trace__tests__bitwise_chiplet_layout.snap new file mode 100644 index 0000000000..feb83ddda7 --- /dev/null +++ b/air/src/trace/snapshots/miden_air__trace__tests__bitwise_chiplet_layout.snap @@ -0,0 +1,30 @@ +--- +source: air/src/trace/tests.rs +expression: layout +--- +BITWISE CHIPLET LAYOUT +=========================== + +Chiplet Selectors: + Number of bitwise selectors: 2 + Trace offset: 53 + Selector column index: 53 + +Input Columns: + Input A column index: 54 + Input B column index: 55 + Input A bit decomposition range: 56..60 + Input B bit decomposition range: 60..64 + +Output Columns: + Previous output column index: 64 + Output column index: 65 + +Trace Range: + Bitwise trace range: 53..66 + +Other Constants: + Number of selectors: 1 + Trace width: 13 + Operation cycle length: 8 + Number of decomposed bits per row: 4 diff --git a/air/src/trace/snapshots/miden_air__trace__tests__decoder_trace_layout.snap b/air/src/trace/snapshots/miden_air__trace__tests__decoder_trace_layout.snap new file mode 100644 index 0000000000..e3718ebefb --- /dev/null +++ b/air/src/trace/snapshots/miden_air__trace__tests__decoder_trace_layout.snap @@ -0,0 +1,39 @@ +--- +source: air/src/trace/tests.rs +expression: layout +--- +DECODER TRACE LAYOUT +====================== + +Hasher State: + Offset: 8 + Number of columns: 8 + Range: 8..16 + +Operation Bits: + Offset: 1 + Number of bits: 7 + Range: 1..8 + +Operation Bits Extra Columns (for degree reduction): + Offset: 22 + Number of columns: 2 + Range: 22..24 + +User Operation Helpers: + Offset: 10 + Number of helpers: 6 + +Operation Batch Flags: + Offset: 19 + Number of flags: 3 + Range: 19..22 + +Column Indices (ordered by index): + - 12: Is loop body flag + - 13: Is loop flag + - 14: Is call flag + - 15: Is syscall flag + - 16: In span column + - 17: Group count column + - 18: Operation index column diff --git a/air/src/trace/snapshots/miden_air__trace__tests__hasher_chiplet_layout.snap b/air/src/trace/snapshots/miden_air__trace__tests__hasher_chiplet_layout.snap new file mode 100644 index 0000000000..202c038b5f --- /dev/null +++ b/air/src/trace/snapshots/miden_air__trace__tests__hasher_chiplet_layout.snap @@ -0,0 +1,32 @@ +--- +source: air/src/trace/tests.rs +expression: layout +--- +HASHER CHIPLET LAYOUT +========================== + +Chiplet Selectors: + Number of hasher selectors: 1 + Trace offset: 52 + Selector column range: 52..55 + +Hasher State: + State width: 12 + State column range: 55..67 + +Capacity Portion (RPO): + Capacity length: 4 + Capacity column range: 55..59 + Capacity domain index: 1 + +Rate Portion (RPO): + Rate length: 8 + Rate column range: 59..67 + +Other Constants: + Digest length: 4 + Number of rounds: 7 + Hash cycle length: 8 + Number of selectors: 3 + Hasher trace width: 16 + Node index column: 67 diff --git a/air/src/trace/snapshots/miden_air__trace__tests__kernel_rom_chiplet_layout.snap b/air/src/trace/snapshots/miden_air__trace__tests__kernel_rom_chiplet_layout.snap new file mode 100644 index 0000000000..ac9b71fc1c --- /dev/null +++ b/air/src/trace/snapshots/miden_air__trace__tests__kernel_rom_chiplet_layout.snap @@ -0,0 +1,14 @@ +--- +source: air/src/trace/tests.rs +expression: layout +--- +KERNEL ROM CHIPLET LAYOUT +================================ + +Chiplet Selectors: + Number of kernel ROM selectors: 5 + +Other Constants: + Trace width: 5 + Kernel procedure call label: 0b001111 + 1 (16) + Kernel procedure init label: 0b101111 + 1 (48) diff --git a/air/src/trace/snapshots/miden_air__trace__tests__main_trace_layout.snap b/air/src/trace/snapshots/miden_air__trace__tests__main_trace_layout.snap new file mode 100644 index 0000000000..b1449ac753 --- /dev/null +++ b/air/src/trace/snapshots/miden_air__trace__tests__main_trace_layout.snap @@ -0,0 +1,40 @@ +--- +source: air/src/trace/tests.rs +expression: layout +--- +MAIN TRACE LAYOUT +=================== + +Minimum trace length: 2048 + +System Trace: + Offset: 0 + Width: 6 + Range: 0..6 + - Clock column index: 0 + - Context column index: 1 + - Function hash offset: 2 + - Function hash range: 2..6 + +Decoder Trace: + Offset: 6 + Width: 24 + Range: 6..30 + +Stack Trace: + Offset: 30 + Width: 19 + Range: 30..49 + +Range Check Trace: + Offset: 49 + Width: 2 + Range: 49..51 + +Chiplets Trace: + Offset: 51 + Width: 20 + Range: 51..71 + +Total Trace Width: 71 +Padded Trace Width: 72 diff --git a/air/src/trace/snapshots/miden_air__trace__tests__memory_chiplet_layout.snap b/air/src/trace/snapshots/miden_air__trace__tests__memory_chiplet_layout.snap new file mode 100644 index 0000000000..4148a31420 --- /dev/null +++ b/air/src/trace/snapshots/miden_air__trace__tests__memory_chiplet_layout.snap @@ -0,0 +1,25 @@ +--- +source: air/src/trace/tests.rs +expression: layout +--- +MEMORY CHIPLET LAYOUT +========================== + +Chiplet Selectors: + Number of memory selectors: 3 + Trace offset: 54 + Trace width: 15 + +Column Indices (ordered by index): + - 54: Is read column + - 55: Is word access column + - 56: Context column + - 57: Word column + - 58: Index 0 column + - 59: Index 1 column + - 60: Clock column + - 61..65: Value columns + - 65: Delta 0 column + - 66: Delta 1 column + - 67: Delta inverse column + - 68: Same context and word flag diff --git a/air/src/trace/snapshots/miden_air__trace__tests__range_check_trace_layout.snap b/air/src/trace/snapshots/miden_air__trace__tests__range_check_trace_layout.snap new file mode 100644 index 0000000000..951b199653 --- /dev/null +++ b/air/src/trace/snapshots/miden_air__trace__tests__range_check_trace_layout.snap @@ -0,0 +1,19 @@ +--- +source: air/src/trace/tests.rs +expression: layout +--- +RANGE CHECK TRACE LAYOUT +============================ + +Main Trace: + Offset: 49 + Width: 2 + Range: 49..51 + - M column (multiplicity): 49 + - V column (values being range-checked): 50 + +Auxiliary Trace: + Offset: 4 + Width: 1 + Range: 4..5 + - B column (running product): 4 diff --git a/air/src/trace/snapshots/miden_air__trace__tests__stack_trace_layout.snap b/air/src/trace/snapshots/miden_air__trace__tests__stack_trace_layout.snap new file mode 100644 index 0000000000..96beac0cd8 --- /dev/null +++ b/air/src/trace/snapshots/miden_air__trace__tests__stack_trace_layout.snap @@ -0,0 +1,15 @@ +--- +source: air/src/trace/tests.rs +expression: layout +--- +STACK TRACE LAYOUT +==================== + +Stack Top: + Offset: 0 + +Helper Columns: + Number of helper columns: 3 + - b0 column (stack depth): 16 + - b1 column (overflow table address): 17 + - h0 column (1 / (b0 - 16)): 18 diff --git a/air/src/trace/tests.rs b/air/src/trace/tests.rs new file mode 100644 index 0000000000..dbcb746f91 --- /dev/null +++ b/air/src/trace/tests.rs @@ -0,0 +1,494 @@ +//! Tests documenting the values of trace layout constants. +//! +//! This module uses `insta` snapshot testing to document the actual computed values of constants +//! that are defined programmatically. This makes it easy to understand the trace structure without +//! needing to manually compute values or rely on IDE evaluation. +//! +//! The documentation can reference this test when explaining the VM's trace structure. + +use std::vec::Vec; + +use crate::trace::{ + chiplets::{ + ace, bitwise, hasher, kernel_rom, memory, + BITWISE_A_COL_IDX, BITWISE_A_COL_RANGE, BITWISE_B_COL_IDX, BITWISE_B_COL_RANGE, + BITWISE_OUTPUT_COL_IDX, BITWISE_PREV_OUTPUT_COL_IDX, BITWISE_SELECTOR_COL_IDX, + BITWISE_TRACE_OFFSET, BITWISE_TRACE_RANGE, HASHER_CAPACITY_COL_RANGE, + HASHER_NODE_INDEX_COL_IDX, HASHER_RATE_COL_RANGE, HASHER_SELECTOR_COL_RANGE, + HASHER_STATE_COL_RANGE, HASHER_TRACE_OFFSET, MEMORY_CLK_COL_IDX, MEMORY_CTX_COL_IDX, + MEMORY_D0_COL_IDX, MEMORY_D1_COL_IDX, MEMORY_D_INV_COL_IDX, + MEMORY_FLAG_SAME_CONTEXT_AND_WORD, MEMORY_IDX0_COL_IDX, MEMORY_IDX1_COL_IDX, + MEMORY_IS_READ_COL_IDX, MEMORY_IS_WORD_ACCESS_COL_IDX, MEMORY_TRACE_OFFSET, + MEMORY_V_COL_RANGE, MEMORY_WORD_COL_IDX, NUM_ACE_SELECTORS, NUM_BITWISE_SELECTORS, + NUM_HASHER_SELECTORS, NUM_KERNEL_ROM_SELECTORS, NUM_MEMORY_SELECTORS, + }, + decoder::{ + GROUP_COUNT_COL_IDX, HASHER_STATE_OFFSET, HASHER_STATE_RANGE, IN_SPAN_COL_IDX, + IS_CALL_FLAG_COL_IDX, IS_LOOP_BODY_FLAG_COL_IDX, IS_LOOP_FLAG_COL_IDX, + IS_SYSCALL_FLAG_COL_IDX, NUM_HASHER_COLUMNS, NUM_OP_BATCH_FLAGS, NUM_OP_BITS, + NUM_OP_BITS_EXTRA_COLS, NUM_USER_OP_HELPERS, OP_BATCH_FLAGS_OFFSET, OP_BATCH_FLAGS_RANGE, + OP_BITS_EXTRA_COLS_OFFSET, OP_BITS_EXTRA_COLS_RANGE, OP_BITS_OFFSET, OP_BITS_RANGE, + OP_INDEX_COL_IDX, USER_OP_HELPERS_OFFSET, + }, + range::{B_RANGE_COL_IDX, M_COL_IDX, V_COL_IDX}, + stack::{B0_COL_IDX, B1_COL_IDX, H0_COL_IDX, NUM_STACK_HELPER_COLS, STACK_TOP_OFFSET}, + ACE_CHIPLET_WIRING_BUS_OFFSET, ACE_CHIPLET_WIRING_BUS_RANGE, ACE_CHIPLET_WIRING_BUS_WIDTH, + AUX_TRACE_RAND_ELEMENTS, AUX_TRACE_WIDTH, CHIPLETS_BUS_AUX_TRACE_OFFSET, + CHIPLETS_BUS_AUX_TRACE_RANGE, CHIPLETS_BUS_AUX_TRACE_WIDTH, CHIPLETS_OFFSET, + CHIPLETS_RANGE, CHIPLETS_WIDTH, CLK_COL_IDX, CTX_COL_IDX, DECODER_AUX_TRACE_OFFSET, + DECODER_AUX_TRACE_RANGE, DECODER_AUX_TRACE_WIDTH, DECODER_TRACE_OFFSET, + DECODER_TRACE_RANGE, DECODER_TRACE_WIDTH, FN_HASH_OFFSET, FN_HASH_RANGE, + HASHER_AUX_TRACE_RANGE, HASHER_AUX_TRACE_WIDTH, HASH_KERNEL_VTABLE_AUX_TRACE_OFFSET, + MIN_TRACE_LEN, PADDED_TRACE_WIDTH, RANGE_CHECK_AUX_TRACE_OFFSET, + RANGE_CHECK_AUX_TRACE_RANGE, RANGE_CHECK_AUX_TRACE_WIDTH, RANGE_CHECK_TRACE_OFFSET, + RANGE_CHECK_TRACE_RANGE, RANGE_CHECK_TRACE_WIDTH, STACK_AUX_TRACE_OFFSET, + STACK_AUX_TRACE_RANGE, STACK_AUX_TRACE_WIDTH, STACK_TRACE_OFFSET, STACK_TRACE_RANGE, + STACK_TRACE_WIDTH, SYS_TRACE_OFFSET, SYS_TRACE_RANGE, SYS_TRACE_WIDTH, TRACE_WIDTH, +}; + +/// Documents all trace widths and offsets for the main execution trace. +/// +/// This test captures the computed values of all trace segment widths and their offsets, +/// making it easy to understand the overall trace layout. +#[test] +fn document_main_trace_layout() { + let layout = format!( + r#"MAIN TRACE LAYOUT +=================== + +Minimum trace length: {MIN_TRACE_LEN} + +System Trace: + Offset: {SYS_TRACE_OFFSET} + Width: {SYS_TRACE_WIDTH} + Range: {SYS_TRACE_RANGE:?} + - Clock column index: {CLK_COL_IDX} + - Context column index: {CTX_COL_IDX} + - Function hash offset: {FN_HASH_OFFSET} + - Function hash range: {FN_HASH_RANGE:?} + +Decoder Trace: + Offset: {DECODER_TRACE_OFFSET} + Width: {DECODER_TRACE_WIDTH} + Range: {DECODER_TRACE_RANGE:?} + +Stack Trace: + Offset: {STACK_TRACE_OFFSET} + Width: {STACK_TRACE_WIDTH} + Range: {STACK_TRACE_RANGE:?} + +Range Check Trace: + Offset: {RANGE_CHECK_TRACE_OFFSET} + Width: {RANGE_CHECK_TRACE_WIDTH} + Range: {RANGE_CHECK_TRACE_RANGE:?} + +Chiplets Trace: + Offset: {CHIPLETS_OFFSET} + Width: {CHIPLETS_WIDTH} + Range: {CHIPLETS_RANGE:?} + +Total Trace Width: {TRACE_WIDTH} +Padded Trace Width: {PADDED_TRACE_WIDTH} +"# + ); + + insta::assert_snapshot!("main_trace_layout", layout); +} + +/// Documents all auxiliary trace widths and offsets. +/// +/// This test captures the computed values of all auxiliary trace segment widths and their offsets. +#[test] +fn document_aux_trace_layout() { + let layout = format!( + r#"AUXILIARY TRACE LAYOUT +========================== + +Decoder Auxiliary Trace: + Offset: {DECODER_AUX_TRACE_OFFSET} + Width: {DECODER_AUX_TRACE_WIDTH} + Range: {DECODER_AUX_TRACE_RANGE:?} + +Stack Auxiliary Trace: + Offset: {STACK_AUX_TRACE_OFFSET} + Width: {STACK_AUX_TRACE_WIDTH} + Range: {STACK_AUX_TRACE_RANGE:?} + +Range Check Auxiliary Trace: + Offset: {RANGE_CHECK_AUX_TRACE_OFFSET} + Width: {RANGE_CHECK_AUX_TRACE_WIDTH} + Range: {RANGE_CHECK_AUX_TRACE_RANGE:?} + +Hasher/Kernel ROM Virtual Table Auxiliary Trace: + Offset: {HASH_KERNEL_VTABLE_AUX_TRACE_OFFSET} + Width: {HASHER_AUX_TRACE_WIDTH} + Range: {HASHER_AUX_TRACE_RANGE:?} + +Chiplets Bus Auxiliary Trace: + Offset: {CHIPLETS_BUS_AUX_TRACE_OFFSET} + Width: {CHIPLETS_BUS_AUX_TRACE_WIDTH} + Range: {CHIPLETS_BUS_AUX_TRACE_RANGE:?} + +ACE Chiplet Wiring Bus: + Offset: {ACE_CHIPLET_WIRING_BUS_OFFSET} + Width: {ACE_CHIPLET_WIRING_BUS_WIDTH} + Range: {ACE_CHIPLET_WIRING_BUS_RANGE:?} + +Total Auxiliary Trace Width: {AUX_TRACE_WIDTH} +Auxiliary Trace Random Elements: {AUX_TRACE_RAND_ELEMENTS} +"# + ); + + insta::assert_snapshot!("aux_trace_layout", layout); +} + +/// Documents decoder trace column ranges and offsets. +/// +/// This test captures the computed values of decoder-specific column indices and ranges. +#[test] +fn document_decoder_trace_layout() { + let layout = format!( + r#"DECODER TRACE LAYOUT +====================== + +Hasher State: + Offset: {HASHER_STATE_OFFSET} + Number of columns: {NUM_HASHER_COLUMNS} + Range: {HASHER_STATE_RANGE:?} + +Operation Bits: + Offset: {OP_BITS_OFFSET} + Number of bits: {NUM_OP_BITS} + Range: {OP_BITS_RANGE:?} + +Operation Bits Extra Columns (for degree reduction): + Offset: {OP_BITS_EXTRA_COLS_OFFSET} + Number of columns: {NUM_OP_BITS_EXTRA_COLS} + Range: {OP_BITS_EXTRA_COLS_RANGE:?} + +User Operation Helpers: + Offset: {USER_OP_HELPERS_OFFSET} + Number of helpers: {NUM_USER_OP_HELPERS} + +Operation Batch Flags: + Offset: {OP_BATCH_FLAGS_OFFSET} + Number of flags: {NUM_OP_BATCH_FLAGS} + Range: {OP_BATCH_FLAGS_RANGE:?} + +Column Indices (ordered by index): + - {IS_LOOP_BODY_FLAG_COL_IDX}: Is loop body flag + - {IS_LOOP_FLAG_COL_IDX}: Is loop flag + - {IS_CALL_FLAG_COL_IDX}: Is call flag + - {IS_SYSCALL_FLAG_COL_IDX}: Is syscall flag + - {IN_SPAN_COL_IDX}: In span column + - {GROUP_COUNT_COL_IDX}: Group count column + - {OP_INDEX_COL_IDX}: Operation index column +"# + ); + + insta::assert_snapshot!("decoder_trace_layout", layout); +} + +/// Documents stack trace column ranges and offsets. +/// +/// This test captures the computed values of stack-specific column indices. +#[test] +fn document_stack_trace_layout() { + let layout = format!( + r#"STACK TRACE LAYOUT +==================== + +Stack Top: + Offset: {STACK_TOP_OFFSET} + +Helper Columns: + Number of helper columns: {NUM_STACK_HELPER_COLS} + - b0 column (stack depth): {B0_COL_IDX} + - b1 column (overflow table address): {B1_COL_IDX} + - h0 column (1 / (b0 - 16)): {H0_COL_IDX} +"# + ); + + insta::assert_snapshot!("stack_trace_layout", layout); +} + +/// Documents range check trace column ranges and offsets. +/// +/// This test captures the computed values of range check-specific column indices. +#[test] +fn document_range_check_trace_layout() { + let layout = format!( + r#"RANGE CHECK TRACE LAYOUT +============================ + +Main Trace: + Offset: {RANGE_CHECK_TRACE_OFFSET} + Width: {RANGE_CHECK_TRACE_WIDTH} + Range: {RANGE_CHECK_TRACE_RANGE:?} + - M column (multiplicity): {M_COL_IDX} + - V column (values being range-checked): {V_COL_IDX} + +Auxiliary Trace: + Offset: {RANGE_CHECK_AUX_TRACE_OFFSET} + Width: {RANGE_CHECK_AUX_TRACE_WIDTH} + Range: {RANGE_CHECK_AUX_TRACE_RANGE:?} + - B column (running product): {B_RANGE_COL_IDX} +"# + ); + + insta::assert_snapshot!("range_check_trace_layout", layout); +} + +/// Documents hasher chiplet column ranges, especially the capacity portion of RPO. +/// +/// This test captures the computed values of hasher chiplet column indices and ranges, +/// with special focus on the capacity portion of the Rescue Prime Optimized (RPO) state +/// inside the hasher chiplet, as this is specifically mentioned in the issue. +#[test] +fn document_hasher_chiplet_layout() { + let layout = format!( + r#"HASHER CHIPLET LAYOUT +========================== + +Chiplet Selectors: + Number of hasher selectors: {NUM_HASHER_SELECTORS} + Trace offset: {HASHER_TRACE_OFFSET} + Selector column range: {HASHER_SELECTOR_COL_RANGE:?} + +Hasher State: + State width: {} + State column range: {HASHER_STATE_COL_RANGE:?} + +Capacity Portion (RPO): + Capacity length: {} + Capacity column range: {HASHER_CAPACITY_COL_RANGE:?} + Capacity domain index: {} + +Rate Portion (RPO): + Rate length: {} + Rate column range: {HASHER_RATE_COL_RANGE:?} + +Other Constants: + Digest length: {} + Number of rounds: {} + Hash cycle length: {} + Number of selectors: {} + Hasher trace width: {} + Node index column: {HASHER_NODE_INDEX_COL_IDX} +"#, + hasher::STATE_WIDTH, + hasher::CAPACITY_LEN, + hasher::CAPACITY_DOMAIN_IDX, + hasher::RATE_LEN, + hasher::DIGEST_LEN, + hasher::NUM_ROUNDS, + hasher::HASH_CYCLE_LEN, + hasher::NUM_SELECTORS, + hasher::TRACE_WIDTH + ); + + insta::assert_snapshot!("hasher_chiplet_layout", layout); +} + +/// Documents bitwise chiplet column ranges and offsets. +#[test] +fn document_bitwise_chiplet_layout() { + let layout = format!( + r#"BITWISE CHIPLET LAYOUT +=========================== + +Chiplet Selectors: + Number of bitwise selectors: {NUM_BITWISE_SELECTORS} + Trace offset: {BITWISE_TRACE_OFFSET} + Selector column index: {BITWISE_SELECTOR_COL_IDX} + +Input Columns: + Input A column index: {BITWISE_A_COL_IDX} + Input B column index: {BITWISE_B_COL_IDX} + Input A bit decomposition range: {BITWISE_A_COL_RANGE:?} + Input B bit decomposition range: {BITWISE_B_COL_RANGE:?} + +Output Columns: + Previous output column index: {BITWISE_PREV_OUTPUT_COL_IDX} + Output column index: {BITWISE_OUTPUT_COL_IDX} + +Trace Range: + Bitwise trace range: {BITWISE_TRACE_RANGE:?} + +Other Constants: + Number of selectors: {} + Trace width: {} + Operation cycle length: {} + Number of decomposed bits per row: {} +"#, + bitwise::NUM_SELECTORS, + bitwise::TRACE_WIDTH, + bitwise::OP_CYCLE_LEN, + bitwise::NUM_DECOMP_BITS + ); + + insta::assert_snapshot!("bitwise_chiplet_layout", layout); +} + +/// Documents memory chiplet column ranges and offsets. +#[test] +fn document_memory_chiplet_layout() { + let layout = format!( + r#"MEMORY CHIPLET LAYOUT +========================== + +Chiplet Selectors: + Number of memory selectors: {NUM_MEMORY_SELECTORS} + Trace offset: {MEMORY_TRACE_OFFSET} + Trace width: {} + +Column Indices (ordered by index): + - {MEMORY_IS_READ_COL_IDX}: Is read column + - {MEMORY_IS_WORD_ACCESS_COL_IDX}: Is word access column + - {MEMORY_CTX_COL_IDX}: Context column + - {MEMORY_WORD_COL_IDX}: Word column + - {MEMORY_IDX0_COL_IDX}: Index 0 column + - {MEMORY_IDX1_COL_IDX}: Index 1 column + - {MEMORY_CLK_COL_IDX}: Clock column + - {MEMORY_V_COL_RANGE:?}: Value columns + - {MEMORY_D0_COL_IDX}: Delta 0 column + - {MEMORY_D1_COL_IDX}: Delta 1 column + - {MEMORY_D_INV_COL_IDX}: Delta inverse column + - {MEMORY_FLAG_SAME_CONTEXT_AND_WORD}: Same context and word flag +"#, + memory::TRACE_WIDTH + ); + + insta::assert_snapshot!("memory_chiplet_layout", layout); +} + +/// Documents ACE chiplet column ranges and offsets. +#[test] +fn document_ace_chiplet_layout() { + // Collect all column indices with their labels, sorted by index + let mut columns = vec![ + (ace::SELECTOR_START_IDX, "Selector start"), + (ace::SELECTOR_BLOCK_IDX, "Selector block"), + (ace::CTX_IDX, "Context"), + (ace::PTR_IDX, "Pointer"), + (ace::CLK_IDX, "Clock"), + (ace::EVAL_OP_IDX, "Eval operation"), + (ace::ID_0_IDX, "ID 0"), + (ace::V_0_0_IDX, "Value 0_0"), + (ace::V_0_1_IDX, "Value 0_1"), + (ace::ID_1_IDX, "ID 1"), + (ace::V_1_0_IDX, "Value 1_0"), + (ace::V_1_1_IDX, "Value 1_1"), + (ace::ID_2_IDX, "ID 2"), + (ace::READ_NUM_EVAL_IDX, "Read num eval"), + (ace::V_2_0_IDX, "Value 2_0"), + (ace::V_2_1_IDX, "Value 2_1"), + (ace::M_1_IDX, "Multiplicity 1"), + (ace::M_0_IDX, "Multiplicity 0"), + ]; + columns.sort_by_key(|(idx, _)| *idx); + + let column_list = columns + .iter() + .map(|(idx, label)| format!(" - {}: {}", idx, label)) + .collect::>() + .join("\n"); + + let layout = format!( + r#"ACE CHIPLET LAYOUT +===================== + +Chiplet Selectors: + Number of ACE selectors: {NUM_ACE_SELECTORS} + +Column Indices (ordered by index): +{column_list} + +Other Constants: + Number of columns: {} + ACE init label: {} + Instruction ID2 offset: {} +"#, + ace::ACE_CHIPLET_NUM_COLS, + ace::ACE_INIT_LABEL.as_int(), + ace::ACE_INSTRUCTION_ID2_OFFSET.as_int() + ); + + insta::assert_snapshot!("ace_chiplet_layout", layout); +} + +/// Documents kernel ROM chiplet constants. +#[test] +fn document_kernel_rom_chiplet_layout() { + let layout = format!( + r#"KERNEL ROM CHIPLET LAYOUT +================================ + +Chiplet Selectors: + Number of kernel ROM selectors: {NUM_KERNEL_ROM_SELECTORS} + +Other Constants: + Trace width: {} + Kernel procedure call label: 0b001111 + 1 ({}) + Kernel procedure init label: 0b101111 + 1 ({}) +"#, + kernel_rom::TRACE_WIDTH, + kernel_rom::KERNEL_PROC_CALL_LABEL.as_int(), + kernel_rom::KERNEL_PROC_INIT_LABEL.as_int() + ); + + insta::assert_snapshot!("kernel_rom_chiplet_layout", layout); +} + +/// Documents all chiplet column ranges in a single comprehensive view. +/// +/// This test provides a complete overview of all chiplet column ranges, making it easy +/// to understand how chiplets are laid out within the main trace. +#[test] +fn document_all_chiplet_column_ranges() { + let hasher_selector_width = HASHER_SELECTOR_COL_RANGE.end - HASHER_SELECTOR_COL_RANGE.start; + let hasher_state_width = HASHER_STATE_COL_RANGE.end - HASHER_STATE_COL_RANGE.start; + let hasher_capacity_width = HASHER_CAPACITY_COL_RANGE.end - HASHER_CAPACITY_COL_RANGE.start; + let hasher_rate_width = HASHER_RATE_COL_RANGE.end - HASHER_RATE_COL_RANGE.start; + let bitwise_a_width = BITWISE_A_COL_RANGE.end - BITWISE_A_COL_RANGE.start; + let bitwise_b_width = BITWISE_B_COL_RANGE.end - BITWISE_B_COL_RANGE.start; + let bitwise_trace_width = BITWISE_TRACE_RANGE.end - BITWISE_TRACE_RANGE.start; + let memory_v_width = MEMORY_V_COL_RANGE.end - MEMORY_V_COL_RANGE.start; + + let layout = format!( + r#"ALL CHIPLET COLUMN RANGES +================================ + +Chiplet Selector Counts: + - Hasher selectors: {NUM_HASHER_SELECTORS} + - Bitwise selectors: {NUM_BITWISE_SELECTORS} + - Memory selectors: {NUM_MEMORY_SELECTORS} + - ACE selectors: {NUM_ACE_SELECTORS} + - Kernel ROM selectors: {NUM_KERNEL_ROM_SELECTORS} + +Hasher Chiplet: + Trace offset: {HASHER_TRACE_OFFSET} + Selector range: {HASHER_SELECTOR_COL_RANGE:?} (width {hasher_selector_width}) + State range: {HASHER_STATE_COL_RANGE:?} (width {hasher_state_width}) + Capacity range: {HASHER_CAPACITY_COL_RANGE:?} (width {hasher_capacity_width}) + Rate range: {HASHER_RATE_COL_RANGE:?} (width {hasher_rate_width}) + Node index: {HASHER_NODE_INDEX_COL_IDX} + +Bitwise Chiplet: + Trace offset: {BITWISE_TRACE_OFFSET} + Selector index: {BITWISE_SELECTOR_COL_IDX} + Input A range: {BITWISE_A_COL_RANGE:?} (width {bitwise_a_width}) + Input B range: {BITWISE_B_COL_RANGE:?} (width {bitwise_b_width}) + Trace range: {BITWISE_TRACE_RANGE:?} (width {bitwise_trace_width}) + +Memory Chiplet: + Trace offset: {MEMORY_TRACE_OFFSET} + Value range: {MEMORY_V_COL_RANGE:?} (width {memory_v_width}) + +Note: All column indices are relative to the main trace (not relative to the chiplet trace). +"# + ); + + insta::assert_snapshot!("all_chiplet_column_ranges", layout); +} + diff --git a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_1.snap b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_1.snap index 278ad59536..ab1d700ae4 100644 --- a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_1.snap +++ b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_1.snap @@ -1,6 +1,5 @@ --- source: core/src/mast/node/basic_block_node/tests.rs -assertion_line: 16 expression: batches --- [ diff --git a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_2.snap b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_2.snap index 7aa2d6032c..b40b2df688 100644 --- a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_2.snap +++ b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_2.snap @@ -1,6 +1,5 @@ --- source: core/src/mast/node/basic_block_node/tests.rs -assertion_line: 30 expression: batches --- [ diff --git a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_3.snap b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_3.snap index 7af7a80b76..85e9409fd5 100644 --- a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_3.snap +++ b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_3.snap @@ -1,6 +1,5 @@ --- source: core/src/mast/node/basic_block_node/tests.rs -assertion_line: 44 expression: batches --- [ diff --git a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_5.snap b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_5.snap index 44ed6ac46d..bdab46c361 100644 --- a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_5.snap +++ b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_5.snap @@ -1,6 +1,5 @@ --- source: core/src/mast/node/basic_block_node/tests.rs -assertion_line: 101 expression: batches --- [ diff --git a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_6.snap b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_6.snap index 3a4935201c..6ea1e0ee31 100644 --- a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_6.snap +++ b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_6.snap @@ -1,6 +1,5 @@ --- source: core/src/mast/node/basic_block_node/tests.rs -assertion_line: 139 expression: batches --- [ diff --git a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_7.snap b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_7.snap index cd940c0e2f..a9d6357fef 100644 --- a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_7.snap +++ b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_7.snap @@ -1,6 +1,5 @@ --- source: core/src/mast/node/basic_block_node/tests.rs -assertion_line: 171 expression: batches --- [ diff --git a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_8.snap b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_8.snap index 26017b0a87..8010107a09 100644 --- a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_8.snap +++ b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_8.snap @@ -1,6 +1,5 @@ --- source: core/src/mast/node/basic_block_node/tests.rs -assertion_line: 203 expression: batches --- [ diff --git a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_9.snap b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_9.snap index da7e882355..30b6465cad 100644 --- a/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_9.snap +++ b/core/src/mast/node/basic_block_node/snapshots/miden_core__mast__node__basic_block_node__tests__batch_ops_9.snap @@ -1,6 +1,5 @@ --- source: core/src/mast/node/basic_block_node/tests.rs -assertion_line: 246 expression: batches --- [