rpkbin — Core IC Design & Verification Utilities

rpkbin is a practical toolbox for hardware design and verification work. It includes small, focused utilities for bit-true modeling, spreadsheet extraction, control-flow modeling, and long-running batch workflows.

If you are new here, start with the task you want to solve:

I want to...	Start with
Run many shell/Python jobs and watch them live	Wave
Run commands/functions in parallel from Python	Job Manager
Model registers and bit fields	MapBV
Simulate fixed-point arithmetic	NumBV
Extract structured data from Excel files	Excel Extractor
Sketch or validate low-level control flow	CFG
Compile high-level IR (HIR) to pseudo ASM for MCU targets	Codegen

Core Features

1. MapBV — BitVector with Bidirectional Mapping

MapBV allows you to define a hierarchy of bit-fields that stay synchronized automatically.

• Hierarchical Slicing: Define a 32-bit register and slice it into named fields.
• Bidirectional Linking: Use concat to build a new view from existing variables; updating the view updates the sources.
• Symbolic Evaluation: Use .eval() to test "what-if" scenarios without changing actual values.

Learn more in MapBV Documentation

2. NumBV — Bit-True Fixed-Point Arithmetic

Bit-exact fixed-point simulation for DSP pipeline verification. Pure NumPy, with no external fixed-point dependency.

• Two-layer API: Operator layer (+, *) for convenience; function layer (nbv.add(), nbv.mul()) for explicit pipeline staging.
• Five Rounding Modes: trunc, round, round_half_even (convergent, Xilinx DSP48), ceil, round_to_zero.
• Unified Operations: One NumBV class handles both scalar and array computations. Backed by NumPy by default, with an optional JAX backend for XLA acceleration.

Learn more in NumBV Documentation

3. Excel Extractor — Template-Based Extraction

Intelligently extract data from complex spreadsheets.

• Layout Description: Define the "shape" of data instead of hardcoded coordinates.
• Fuzzy Matching: Matches headers even with slight spelling variations.
• Merged Cell Support: Correctly resolves values spanning across merged rows/cols.

Learn more in Excel Extractor Documentation

4. CFG — Low-Level Control Flow Toolkit

Organize assembly-like flows, FSM state machines, and MCU branch layouts before writing target-specific code.

• Explicit Flow Modeling: Build labeled blocks and priority-ordered branch edges without committing to an ISA.
• Readable Checks & Layouts: Validate common control-flow mistakes, print text layouts, and choose deterministic block emission order.
• Program Call Checks: Mark subroutine calls with CallRef and check call depth against hardware or coding-rule limits.

Learn more in CFG Documentation

5. Job Manager

A practical, cross-platform job manager for running shell commands and Python callables safely in parallel.

• One API for Common Workloads: Run local functions (FuncJob) and CLI tasks (CmdJob) with the same manager.
• Resource-Aware Scheduling: Limit concurrency by global resources such as GPU count or license tokens.
• Operationally Friendly: Built-in cancellation, retries, live logs, and callbacks for automation pipelines.

Job Manager Documentation

6. Wave — Batch Workflow Orchestration with Live TUI

A workflow layer built on top of Job Manager for declaring and observing long-running batch flows.

• Plain Python wave files: declare jobs, parsers, hooks, and actions in a normal .py file.
• Live TUI by default: dashboard, per-job logs, parsed data, events, system messages, and a command bar.
• Headless mode when needed: use --no-tui for CI or script-only environments.
• Operational controls: rerun jobs, stop/cancel by job or tag, send stdin, send OS signals, or send PTY terminal keys.
• Automation hooks: react to log patterns, parsed data, elapsed time, lifecycle events, or user-defined actions.

Wave Documentation

7. Codegen — MCU Compiler Backend Framework

A target-agnostic compiler backend that translates High-level IR (HIR) to pseudo assembly. Supports pattern rewrite optimizations, graph-coloring register allocation, and safe variable spilling.

• HIR Lowering: Lowers structured control flow (if/while/for/poll) and volatile memory loads/stores.
• Physical Register Alias Resolution: Supports overlapping registers (e.g. 16-bit register composed of two 8-bit aliases).
• Safe Variable Spilling: Automatically spills live variables to configured SRAM locations when registers are exhausted.

Codegen Documentation

Quick Start: Wave

Install Wave support:

pip install -e .[wave]

Create hello.wave.py:

from rpkbin.wave import session, CmdJob

session.configure(max_workers=2)

session.add(CmdJob("hello", "python -c \"print('hello from wave')\""))
session.add(CmdJob("list", "python -c \"import os; print(os.getcwd())\""))

Run it:

rpk-wave run hello.wave.py

Useful TUI commands:

status
logs hello
show hello
rerun hello
stop hello

For CI or plain terminal output:

rpk-wave run hello.wave.py --no-tui

Installation

# Core (installs NumPy)
pip install -e .

# Optional NumBV JAX backend
pip install -e .[jax]

# Install specific features
pip install -e .[wave]   # Installs textual, prompt_toolkit, rich
pip install -e .[excel]  # Installs openpyxl, xlrd, rapidfuzz
pip install -e .[cfg]    # Installs networkx
pip install -e .[dot]    # Enables CFG.export_dot()

# Install everything
pip install -e .[all]

Testing

Run tests using pytest from the root directory:

pytest tests/ -v

(All tests require only numpy — no optional dependencies needed.)