Struct LutBuilder 

pub struct LutBuilder { /* private fields */ }

Builder for generating a function-pointer LUT and handler stubs, with optional grouping of instructions under shared const-generic handlers.

Use this when you want multiple instructions to share one handler function via a const OP: u32 generic parameter. See the crate documentation for the full pattern.

Example (build.rs)

chipi::LutBuilder::new("cpu.chipi")
    .handler_mod("crate::cpu::interpreter")
    .ctx_type("crate::Cpu")
    .lut_mod("crate::cpu::lut")
    .group("alu", ["addi", "addis", "ori", "oris"])
    .group("mem", ["lwz", "stw", "lbz", "stb"])
    .build_lut(out_dir.join("cpu_lut.rs").to_str().unwrap())?;

Implementations

impl LutBuilder

pub fn new(input: impl Into<String>) -> Self

Create a new builder targeting the given .chipi spec file.

pub fn handler_mod(self, m: impl Into<String>) -> Self

Set the Rust module path where handler functions live (e.g. "crate::cpu::interpreter").

pub fn ctx_type(self, t: impl Into<String>) -> Self

Set the mutable context type passed to every handler (e.g. "crate::Cpu").

pub fn lut_mod(self, path: impl Into<String>) -> Self

Set the Rust module path where the generated OP_* constants live (e.g. "crate::cpu::lut"). Required when using groups so that stubs can use {lut_mod}::* to import the constants.

pub fn instr_type(self, t: impl Into<String>) -> Self

Override the type of the second parameter of every handler function.

Defaults to u32 (raw opcode word). Set to a wrapper type such as "crate::cpu::semantics::Instruction" to have handlers receive a richer type instead. You must also call Self::raw_expr to tell chipi how to extract the underlying u32 for table indexing.

pub fn raw_expr(self, expr: impl Into<String>) -> Self

Expression that yields a u32 from the instr local inside a generated dispatch function. Only meaningful when Self::instr_type is set.

For a newtype struct Instruction(pub u32) this is "instr.0" (the default when instr_type is set). For a struct with a raw() method use "instr.raw()".

pub fn dispatch(self, strategy: Dispatch) -> Self

Set the dispatch strategy.

• Dispatch::FnPtrLut (default): static [Handler; N] arrays with indirect calls. Each tree level gets its own table.
• Dispatch::JumpTable: a single #[inline(always)] function with nested match statements. The compiler can inline handler calls for zero-overhead dispatch when handlers are also #[inline(always)].

pub fn group( self, name: impl Into<String>, instrs: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Register a group: name is the shared handler function name (e.g. "alu"), instrs lists the instruction names that route to it.

Each instruction in instrs will appear in the LUT as handler_mod::alu::<{ OP_INSTR }> instead of handler_mod::instr. The generated stub is pub fn alu<const OP: u32>(...) with a match OP body.

pub fn from_config(target: &LutTarget) -> Self

Create a LutBuilder from a config::LutTarget.

pub fn run_target(target: &LutTarget) -> Result<(), Box<dyn Error>>

Run all outputs defined in a config::LutTarget.

Generates the LUT file, and optionally the instruction type and stubs if configured. Stubs are only generated if the target file does not exist.

pub fn build_lut(&self, output: &str) -> Result<(), Box<dyn Error>>

Generate the LUT source file.

pub fn build_instr_type(&self, output: &str) -> Result<(), Box<dyn Error>>

Generate an instruction newtype with field accessor methods.

Collects all unique fields from the spec and generates a pub struct Name(pub u32) with one #[inline] accessor per field.

The struct name is derived from the last path segment of .instr_type() (e.g., "crate::cpu::Instruction" -> "Instruction"), or defaults to "Instruction" if .instr_type() was not called.

Fields with conflicting definitions across instructions generate separate accessors with bit range suffixes (e.g., d_15_0 and d_11_0).

Example

chipi::LutBuilder::new("cpu.chipi")
    .instr_type("crate::cpu::Instruction")
    .build_instr_type(out_dir.join("instruction.rs").to_str().unwrap())?;

pub fn build_subdecoder_instr_type( &self, sd_name: &str, output: &str, ) -> Result<(), Box<dyn Error>>

Generate an instruction newtype for a sub-decoder.

Collects all unique fields from the sub-decoder’s instructions and generates a pub struct Name(pub u8/u16/u32) with accessor methods.

Trait Implementations

impl Default for LutBuilder

fn default() -> LutBuilder

Returns the “default value” for a type.