README.md

metadata

title: ChipForge RTL Debugging Environment
emoji: 🔧
colorFrom: purple
colorTo: green
sdk: docker
pinned: false
app_port: 8000
base_path: /web
tags:
  - openenv
  - verilog
  - rtl
  - semiconductor

ChipForge — RTL Debugging Environment

An OpenEnv environment where an AI agent debugs buggy Verilog RTL code using real EDA tools (Verilator for simulation/lint, Yosys for synthesis).

The agent receives buggy Verilog, inspects code, runs tools, reads error logs, edits lines to fix bugs, and submits the corrected design for grading.

Quick Start

from chipforge import ChipforgeAction, ChipforgeEnv

try:
    env = ChipforgeEnv.from_docker_image("chipforge-env:latest")

    # Start a new episode (loads a random buggy RTL task)
    result = env.reset()
    print(f"Task: {result.observation.task_description}")

    # View the buggy RTL
    result = env.step(ChipforgeAction(action_type="view_rtl"))
    print(result.observation.rtl_code)

    # Run simulation to see errors
    result = env.step(ChipforgeAction(action_type="run_simulation"))
    print(f"Status: {result.observation.sim_status}")
    print(f"Error: {result.observation.error_summary}")

    # Fix the bug
    result = env.step(ChipforgeAction(
        action_type="edit_line",
        line_number=13,
        new_content="assign sum = x1 ^ cin;"
    ))

    # Verify the fix
    result = env.step(ChipforgeAction(action_type="run_simulation"))
    print(f"Status: {result.observation.sim_status}")

    # Submit solution
    result = env.step(ChipforgeAction(action_type="submit"))
    print(f"Reward: {result.observation.reward}")

finally:
    env.close()

Action Space

Action	Parameters	Description
view_design	—	View current RTL code with line numbers
view_testbench	—	View the testbench code
view_simulation_log	—	View output from last simulation run
view_synthesis_log	—	View output from last synthesis run
view_lint_log	—	View output from last lint run
run_simulation	—	Compile + simulate with Verilator
run_synthesis	—	Synthesize with Yosys
run_lint	—	Run Verilator lint checks
edit_line	target, line_number, new_content	Replace a single line in target ("design" / "testbench")
append_line	target, new_content	Append a single line to target ("design" / "testbench")
insert_lines	target, line_number, new_content	Insert multiple lines at target ("design" / "testbench")
replace_lines	target, line_number, end_line_number, new_content	Replace multiple lines in target ("design" / "testbench")
submit	—	Submit fix and get final reward

Observation Space

Field	Type	Description
rtl_code	str	Current RTL (always populated)
testbench_code	str	Testbench (populated by view_testbench)
log_output	str	Tool output (populated by view_*_log)
sim_status	str	not_run / pass / fail / error
synth_status	str	not_run / pass / warning / error
lint_status	str	not_run / clean / warning / error
error_summary	str	One-line error hint
task_description	str	Description of the current task
step_count	int	Steps taken so far
max_steps	int	Maximum allowed steps (20)

Reward

Component	Value	Condition
Compiles	+0.2	No syntax errors
Simulation passes	+0.3	Output matches expected truth table
Synthesis clean	+0.3	No warnings (e.g., no latches)
Lint clean	+0.2	No lint warnings
Step penalty	-0.01/step	Encourages efficiency

Maximum reward: 1.0 (all checks pass, minimal steps).

Tasks

#	Name	Difficulty	Bug Type
1	task_easy_syntax	Easy	Incomplete XOR expression
2	task_easy_missing_semicolon	Easy	Missing semicolon on wire declaration
3	task_medium_logic_bug	Medium	Wrong operator in sum computation
4	task_medium_wrong_operator	Medium	XOR instead of AND in carry logic
5	task_hard_latch_inference	Hard	Missing else branch → latch inferred

Tools Used

Tool	Role	Installed via
Verilator	Simulation + Linting	OSS CAD Suite
Yosys	Synthesis	OSS CAD Suite

Both tools are bundled in the Docker image via OSS CAD Suite.

Building & Running

# Build Docker image
docker build -t chipforge-env:latest -f server/Dockerfile .

# Run locally (for development)
uvicorn chipforge.server.app:app --reload

# Deploy to Hugging Face Spaces
openenv push

Project Structure

chipforge/
├── __init__.py              # Module exports
├── models.py                # Action + Observation models
├── client.py                # ChipforgeEnv client
├── openenv.yaml             # OpenEnv manifest
├── pyproject.toml           # Dependencies
└── server/
    ├── app.py               # FastAPI application
    ├── chipforge_environment.py  # Core environment logic
    ├── Dockerfile           # Container with Verilator + Yosys
    └── tasks/               # RTL debugging tasks
        ├── task_easy_syntax/
        ├── task_easy_missing_semicolon/
        ├── task_medium_logic_bug/
        ├── task_medium_wrong_operator/
        └── task_hard_latch_inference/

Example Agent Episode

reset()  →  Task: "Fix the syntax error in the full adder RTL"

view_rtl  →  see buggy code with line numbers
run_simulation  →  sim_status="error", error_summary="syntax error near '^'"
edit_line(13, "assign sum = x1 ^ cin;")  →  "Line 13 updated"
run_simulation  →  sim_status="pass"
run_synthesis  →  synth_status="pass"
submit  →  reward=0.93