Crate chipi_core 

chipi-core

Core library for the chipi instruction decoder generator.

This crate provides the parser, validation, IR, and code generation backends. It is consumed by chipi-cli (the standalone CLI tool) and chipi-build (the build.rs helper for Rust projects).

Crate structure

• parser: parses .chipi files into a raw AST (types::DecoderDef)
• validate: validates and lowers the AST into a language-agnostic IR (types::ValidatedDef)
• tree: builds an optimal decision tree for instruction dispatch
• backend: code generation backends (currently Rust only)
• config: TOML config schema and config::Dispatch enum
• codegen: Rust decoder/disassembler code generation
• lut_gen: Rust emulator dispatch LUT generation
• instr_gen: Rust instruction newtype generation

Quick start

For build.rs usage, prefer chipi-build which wraps this library with cargo:rerun-if-changed support. For CLI usage, use chipi-cli. Use chipi-core directly only when you need low-level control.

// Decoder/disassembler generation
chipi_core::CodegenBuilder::new("dsp.chipi")
    .type_map("reg5", "crate::dsp::DspReg")
    .decoder_dispatch("GcDspExt", chipi_core::Dispatch::JumpTable)
    .output("out.rs")
    .run()?;

// Emulator dispatch LUT (programmatic)
chipi_core::LutBuilder::new("cpu.chipi")
    .handler_mod("crate::cpu::interpreter")
    .ctx_type("crate::Cpu")
    .group("alu", ["addi", "addis"])
    .build_lut("out/lut.rs")?;

// Emulator dispatch LUT (from chipi.toml config)
let cfg = chipi_core::config::load_config(Path::new("chipi.toml"))?;
for target in &cfg.lut {
    chipi_core::LutBuilder::run_target(target)?;
}

Re-exports

pub use config::Dispatch;

Modules

backend

Code generation backends.

codegen

Rust code generation from validated definitions and decision trees.

codegen_binja

Binary Ninja Architecture plugin code generation.

codegen_cpp

C++ code generation from validated definitions and decision trees.

codegen_ida

IDA Pro processor module code generation.

codegen_python

Shared Python code generation helpers.

config

Configuration types for chipi code generation.

error

Error types and reporting for parsing and validation.

format_parser

Character-level parser for format string internals.

instr_gen

Instruction type generation - produces a newtype with field accessor methods.

lut_gen

Function-pointer LUT generation from a validated definition and dispatch tree.

parser

DSL parsing for instruction definitions.

tree

Decision tree construction for optimal instruction dispatch.

types

Core type definitions for the intermediate representation.

validate

Semantic validation for instruction definitions.

Structs

CodegenBuilder

Builder for generating a decoder with type mappings and dispatch strategy control.

LutBuilder

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

Functions

emit

Validate a parsed definition and write generated Rust code to a file.

generate

Full pipeline: parse a .chipi file and generate a Rust decoder.

generate_from_str

Parse, validate, and generate code from source text. Returns the generated Rust code as a String.

generate_instr_type

Generate an instruction newtype with field accessor methods from a .chipi spec.

generate_lut

Generate a function-pointer LUT from a .chipi spec file.

parse

Parse a .chipi file from a file path and return the decoder definition.

parse_str

Parse source text directly without reading from a file.