C to RTL:
Co-Simulating an RL
Inference Control Plane

A standalone C runtime and a standalone RTL block can both lie to themselves.

When you test them separately, each side controls its own assumptions. The C runtime can write a test that assumes the device always accepts descriptors. The RTL testbench can write a stimulus that drives host_comp_ready high every cycle. Both tests pass. Both are wrong.

Co-simulation removes that escape hatch. When the C++ bridge drives the Verilated RTL model directly, the C side must handle the case where push_ready is low. The RTL side must handle the case where the host holds pop_ready low for many cycles. Neither side can invent capacity the other doesn't have.

The practical consequence: when the co-sim tests pass, you have a proof that the descriptor layout is correct, the valid/ready handshakes work in both directions, the FSM reaches every completion state, and backpressure propagates end-to-end. That proof is cheap to get now and expensive to discover missing in silicon.

The repo now spans runtime code, RTL, and a co-simulation bridge.

Each layer has a single job. The C/CUDA runtime focuses on efficient descriptor construction and completion polling. The RTL engine owns queue mechanics and FSM progression. The Verilator bridge is the adhesive — a thin, boring piece of code whose only job is to faithfully map one side's types onto the other's port signals.

    
co-sim path
sim/run_sim.cpp
    submit_decode(rollout_id, seq_len, max_tokens, ...)
  ↓  bridge maps C++ → RTL input ports
Verilated rl_runtime_top::eval()          // advance one clock
  ↓  mmio_regs: doorbell_pulse asserted
  ↓  desc_ring: push_valid && push_ready → latch descriptor
  ↓  worker_fsm: S_IDLE → S_DECODE → token_count++
  ↓  worker_fsm: token_count >= max_tokens → S_COMPLETE
  ↓  completion_ring: comp_valid; stall if !comp_ready
  ↓  bridge reads output ports
poll_completion() → RtlCompletion{ rollout_id, status, final_seq_len }
  

The bridge should be small, boring, and contract-focused.

The bridge class has five responsibilities and nothing else: initialize the Verilated model, drive reset, tick the clock, map descriptors onto input ports, and read completions from output ports. Any logic beyond that belongs in either the C runtime layer or the RTL layer.

    
C++
sim/cosim_bridge.h
    struct RtlCompletion {
    uint16_t rollout_id;
    uint8_t  status;           // 0x01=DONE, 0x02=REWARD_NEEDED, 0xFF=ERROR
    uint16_t final_seq_len;
    uint16_t reward_id;
};

class RtlRuntimeBridge {
public:
    RtlRuntimeBridge();                         // construct + allocate Verilated model
    ~RtlRuntimeBridge();                        // delete Verilated model

    void reset(unsigned cycles = 5);            // drive rst_n=0 for N ticks, then release
    void tick();                                  // advance clk 0→1→0, call eval() each edge

    bool submit_decode(
        uint16_t rollout_id,
        uint16_t seq_len,
        uint16_t max_tokens,
        uint16_t reward_model_id,
        uint16_t kv_arena_id   = 0,
        uint16_t prefix_id     = 0,
        uint32_t kv_offset     = 0,
        uint32_t delta_offset  = 0
    );                                            // returns false if push_ready=0 (ring full)

    bool     poll_completion(RtlCompletion *out); // returns true + fills *out if pop_valid=1
    uint64_t cycles() const;                     // monotonic cycle counter for timing budgets
private:
    Vrl_runtime_top  *top_;                      // Verilator-generated model class
    VerilatedContext *ctx_;                      // Verilator simulation context
    uint64_t          cycle_;
};
  

The inner loop is three lines. The discipline is in the handshakes.

Most of the bridge implementation is mechanical field mapping. The interesting parts are the handshake discipline in submit_decode, the clock-edge sequencing inside tick, and the backpressure behavior that prevents lost completions.

    
C++
sim/cosim_bridge.cpp — tick()
    // One full clock cycle: rising edge eval, then falling edge eval.
// Verilator requires eval() on each edge for registered outputs to propagate.
void RtlRuntimeBridge::tick() {
    top_->clk = 1;
    top_->eval();                 // rising edge: flip-flops sample inputs
    top_->clk = 0;
    top_->eval();                 // falling edge: combinational logic re-resolves
    ++cycle_;
}
  

    
C++
sim/cosim_bridge.cpp — submit_decode()
    bool RtlRuntimeBridge::submit_decode(
    uint16_t rollout_id, uint16_t seq_len, uint16_t max_tokens,
    uint16_t reward_model_id, uint16_t kv_arena_id,
    uint16_t prefix_id, uint32_t kv_offset, uint32_t delta_offset)
{
    // 1. Check backpressure — do not drive valid if ring is full
    if (!top_->push_ready) return false;

    // 2. Map C++ arguments onto RTL descriptor input ports
    top_->host_desc_opcode          = DESC_OP_DECODE;   // 8'd1
    top_->host_desc_flags           = 0;
    top_->host_desc_rollout_id       = rollout_id;
    top_->host_desc_kv_arena_id      = kv_arena_id;
    top_->host_desc_prefix_id        = prefix_id;
    top_->host_desc_kv_offset        = kv_offset;
    top_->host_desc_delta_offset     = delta_offset;
    top_->host_desc_seq_len          = seq_len;
    top_->host_desc_max_tokens       = max_tokens;
    top_->host_desc_reward_model_id  = reward_model_id;
    top_->host_desc_reserved         = 0;

    // 3. Assert push_valid for one clock — descriptor is latched on rising edge
    top_->host_push_valid = 1;
    tick();
    top_->host_push_valid = 0;       // de-assert; ring owns the slot now
    tick();                           // one idle tick before next operation
    return true;
}
  

    
C++
sim/cosim_bridge.cpp — poll_completion()
    bool RtlRuntimeBridge::poll_completion(RtlCompletion *out) {
    // 1. Check if RTL has a completion ready — non-blocking poll
    if (!top_->host_comp_valid) return false;

    // 2. Read completion fields from RTL output ports
    out->rollout_id     = top_->host_comp_rollout_id;
    out->status         = top_->host_comp_status;
    out->final_seq_len  = top_->host_comp_final_seq_len;
    out->reward_id      = top_->host_comp_reward_id;

    // 3. Acknowledge — assert pop_ready for one cycle to advance ring head
    top_->host_comp_ready = 1;
    tick();
    top_->host_comp_ready = 0;
    tick();
    return true;
    // If this function is NOT called: comp_valid stays high, worker stays
    // in S_COMPLETE, desc_ring fills up, push_ready goes low. Correct.
}
  

Descriptor field mapping

The tests prove the control-plane loop — all the way around.

Three tests cover the three protocol behaviors that matter: the happy path, the RL-specific reward transition, and the backpressure case that software tests almost always skip.

    
C++
sim/run_sim.cpp — test runner sketch
    // test 1: basic decode
bridge.reset();
bool ok = bridge.submit_decode(/*rollout_id=*/7, /*seq_len=*/0, /*max_tokens=*/10, /*reward_model_id=*/1);
ASSERT(ok, "submit failed — push_ready was low?");

RtlCompletion c{};
for (int i = 0; i < 200 && !bridge.poll_completion(&c); ++i)
    bridge.tick();                           // tick until completion or timeout
ASSERT(c.status        == 0x01, "expected DONE");
ASSERT(c.rollout_id    == 7,    "rollout_id mismatch");
ASSERT(c.final_seq_len == 10,   "seq_len mismatch");

// test 3: backpressure — hold comp_ready low for 20 ticks
bridge.reset();
bridge.submit_decode(42, 0, 5, 1);
for (int i = 0; i < 100; ++i) bridge.tick();   // wait for worker to reach S_COMPLETE
bridge.top_->host_comp_ready = 0;               // hold backpressure
for (int i = 0; i < 20; ++i) {
    bridge.tick();
    ASSERT(bridge.top_->host_comp_valid, "comp_valid must stay high");
}
bridge.top_->host_comp_ready = 1;               // release — completion arrives
RtlCompletion c2{};
bool got = bridge.poll_completion(&c2);
ASSERT(got && c2.rollout_id == 42,             "completion lost under backpressure");
  

What this does and does not prove.

It is easy to over-claim what a co-simulation result means. The bridge tests the control-plane protocol, not the inference computation. Here is the precise scope.

Unify the descriptor into a 64-byte shared physical contract.

Right now the bridge maps fields one-by-one onto individual RTL ports. This validates the logical contract — the field names, widths, and opcode values are consistent. What it does not validate is the physical layout: are the bits in the same position in the C struct as in the RTL packed descriptor?

In a real hardware system this matters. The CPU writes a cache-line-sized descriptor into DRAM. The DMA engine reads it. The hardware queue engine parses it. If the C struct and the RTL struct have different field ordering, endianness assumptions, or padding, the hardware will misparse every work order. The next milestone closes this gap.

    
target contract
shared physical layout — v0.6 goal
    // Both sides must agree on every bit of this layout

C:   __attribute__((packed, aligned(64))) hw_desc_t   → 64 bytes, little-endian
RTL: typedef struct packed { ... } desc_t            → 512 bits, same field order

Validation strategy:
  1. Static assert: sizeof(hw_desc_t) == 64
  2. Static assert: offsetof(hw_desc_t, rollout_id) == 2  // after opcode + flags
  3. Verilator bridge: single DPI call with raw uint8_t[64] bus instead of N ports
  4. Co-sim test: write known byte pattern, assert RTL parses fields correctly
  5. Reverse test: RTL emits completion; assert C struct parses it correctly
  

The repo is becoming a contract lab.

After building the co-simulation bridge, the relationship between the C runtime and the RTL engine changes. They are no longer two separate things that happen to use the same vocabulary. They are two implementations of one contract — and the bridge is the test harness that proves they agree.