CKB VM

The Snapshot2Context manages the relationship between a VM's memory and an external DataSource. It tracks which memory pages are backed by the DataSource versus which pages are "dirty" (modified and requiring full storage).

Key Workflows:

1. Loading a Program efficiently

To reduce snapshot size, you should track memory pages belonging to the program using mark_program. This requires parsing the ELF first to get ProgramMetadata.

// 1. Parse ELF to get metadata
let metadata = elf::parse_elf(elf_data)?;
// 2. Load program into machine
machine.load_program_with_metadata(metadata.clone(), ...)?;
// 3. Mark pages in context to track them as coming from the DataSource
context.mark_program(&mut machine, &metadata, &program_id, program_offset)?;

2. Creating a Snapshot

Use make_snapshot to capture the current state of a SupportMachine. The resulting Snapshot2 contains:

• pages_from_source: Pages that can be reconstructed from the DataSource.
• dirty_pages: Pages that have been modified and must be stored as raw bytes.
• Machine state: registers, pc, cycles, and max_cycles.

3. Resuming from a Snapshot

Use resume to restore a machine to a previously captured state. This clears the current context's page tracking and restores registers, PC, and memory (both from the source and dirty pages).

// Example: Creating a snapshot
let snapshot = context.make_snapshot(&mut machine)?;

// Example: Resuming a machine
context.resume(&mut machine, &snapshot)?;

Macro-Operation Fusion (MOP) is an optimization where the decoder identifies a sequence of adjacent instructions that can be treated as a single, more complex instruction. This reduces the overhead of the execution loop.

When calling decode_mop, the decoder:

1. Decodes the instruction at the current pc using decode_raw.
2. Checks the opcode of the decoded instruction against known fusion rules (e.g., OP_ADD, OP_SUB, OP_LUI, OP_AUIPC).
3. If a pattern matches (e.g., an ADD followed by an SLTU and another ADD that forms a specific arithmetic chain), it returns a single fused Instruction with a combined length.
4. If no pattern matches, it falls back to returning the single instruction decoded by decode_raw.

Common fusion patterns include:

• Arithmetic chains: Combining ADD, SLTU, and ADD into OP_ADD3A, OP_ADD3B, or OP_ADD3C.
• Jump optimizations: Combining LUI + JALR into OP_FAR_JUMP_ABS or AUIPC + JALR into OP_FAR_JUMP_REL.
• Immediate loading: Combining LUI + ADDIW into OP_CUSTOM_LOAD_IMM.

The FlatMemory<R> struct provides a contiguous chunk of memory for a RISC-V machine. It is designed for simplicity and lacks permission checking logic. It implements the Memory trait, allowing for standard load/store operations.

Key characteristics:

• Memory Layout: A single Vec<u8> representing the entire address space.
• Endianness: Follows the RISC-V ISA standard of little-endian memory.
• Page Management: Uses RISCV_PAGESIZE to manage flags and dirty status for pages.
• Constraints: The memory_size must be a multiple of RISCV_PAGESIZE.

Note that FlatMemory implements Deref and DerefMut to Vec<u8>, allowing you to access the underlying raw byte buffer directly.

// Example conceptual usage
let mut memory = FlatMemory::<MyRegisterType>::new(RISCV_PAGESIZE * 1024);

// Storing data
memory.store_bytes(0x1000, &[0xDE, 0xAD, 0xBE, 0xEF]).unwrap();

// Loading data
let val = memory.load32(&MyRegisterType::from_u64(0x1000)).unwrap();

The CKB VM decoder implements instruction fusion, where specific sequences of instructions are combined into a single, more efficient internal instruction (a "fuze" instruction). This is an optimization performed during the decoding stage.

Common fusion patterns include:

• Immediate Loading: Combining multiple instructions to load a large immediate value into a register using OP_CUSTOM_LOAD_IMM.
• Wide Arithmetic: Combining multiplication and division/remainder operations into single wide operations. For example:
  • OP_MULH + OP_MUL $\rightarrow$ OP_WIDE_MUL (R4type)
  • OP_MULHU + OP_MUL $\rightarrow$ OP_WIDE_MULU (R4type)
  • OP_MULHSU + OP_MUL $\rightarrow$ OP_WIDE_MULSU (R4type)
  • OP_DIV + OP_REM $\rightarrow$ OP_WIDE_DIV (R4type)
  • OP_DIVU + OP_REMU $\rightarrow$ OP_WIDE_DIVU (R4type)

Fusion occurs only when specific register constraints are met (e.g., ensuring the destination register does not overlap with source registers in a way that violates the fusion logic) and the subsequent instruction is the expected operand for the fusion.

To create a functional VM instance, use the AbstractDefaultMachineBuilder (or RustDefaultMachineBuilder for Rust-based VMs). The builder allows you to inject custom syscalls, a debugger, a pause mechanism, and a custom instruction cycle function to control how many cycles each instruction consumes.

Key builder methods:

• instruction_cycle_func(Box<dyn Fn(Instruction) -> u64 + Send + Sync>): Sets a function to determine the cycle cost of an instruction.
• syscall(Box<dyn Syscalls<Inner>>): Adds a custom syscall implementation.
• debugger(Box<dyn Debugger<Inner>>): Attaches a debugger.
• pause(Pause): Sets the interruption mechanism.
• build(): Finalizes the construction of the DefaultMachine.

// Example pattern for building a machine
let machine = AbstractDefaultMachineBuilder::new(inner_machine)
    .instruction_cycle_func(Box::new(|_| 1))
    .syscall(Box::new(my_custom_syscall))
    .debugger(Box::new(my_debugger))
    .build();