Skip to content

asap7/chi_async_bridge: XiangShan's asynchronous CHI bridge, to replace mock-cpu - #4600

Merged
maliberty merged 10 commits into
The-OpenROAD-Project:masterfrom
oharboe:asap7-chi-async-bridge
Oct 8, 2026
Merged

maliberty merged 10 commits into
The-OpenROAD-Project:masterfrom
oharboe:asap7-chi-async-bridge

Conversation

@oharboe

@oharboe oharboe commented Oct 1, 2026 •

Copy link
Copy Markdown
Collaborator

What

asap7/chi_async_bridge is a new test design, replacing mock-cpu, with one concern: an asynchronous clock crossing, constrained the way the rest of a macro flow constrains its boundaries, and implemented by the flow as constrained.

It is XiangShan's CHI bridge between its tile and its network-on-chip: six CHI flit channels, each a rocket-chip async queue (Gray-coded pointers, 3-flop synchronisers, the queue memory read by a mux on the far clock), their link credits and handshakes, and a reset synchroniser per domain. Both halves are in one block, so timing analysis sees both ends of every crossing.

RTL Readable, parameterised SystemVerilog (REQ_W, RSP_W, DAT_W, SNP_W, DEPTH, SYNC), read by slang; each file cites the Chisel it models
Constraints Two asynchronous clocks; every crossing bounded by set_max_delay -ignore_clock_latency at one period of its launching clock, no hold across; ports budgeted per domain as $PLATFORM_DIR/constraints.sdc budgets a macro's; synchroniser hops kept short
Self-check constraint.sdc verifies the names it constrains against the synthesised netlist and stops the flow if they are wrong, rather than letting OpenSTA drop the constraint with a warning
Flow ORFS defaults, all three asap7 Vt's, the full flow, no waivers
Variants FLOW_VARIANT=small|medium; base is XiangShan's bridge as it is

Results

The core clock is 300 ps: given 420, 380 or 340 ps the flow closes, each time within a few picoseconds of the target; given 300 ps the worst path just fails. It is the core half's async queue sink, from the read pointer through the read-mux select, buffered out to every bit of a 385-bit data flit: the queue's own logic.

It reproduces XiangShan. XiangShan's own CHIAsyncBridgeSource and CHIAsyncBridgeSink, elaborated from its Chisel with its parameters and hardened alone, run through the same flow and constraints:

at global route target this design XiangShan's bridge
core clock, min period 340 ps 339.7 ps 340.0 ps
core clock, min period 300 ps 305.9 ps 301.4 ps
worst path at 300 ps async queue sink read, rx dat the same
its logic / inserted buffers / wire 163 / 80 / 22 ps 159 / 76 / 22 ps
flops 35,106 35,043
FLOW_VARIANT flops core min period at 300 ps, grt to grt final
base 35,106 305.9 ps, fails 30 min worst slack -23.1 ps (323.1 ps), 149 max-slew violations on 9 entry-enable and read-select broadcasts; 57 min to final
medium 21,846 299.5 ps, closes 20 min
small 4,621 298.5 ps, closes 5 min

Try this

cd flow
make DESIGN_CONFIG=./designs/asap7/chi_async_bridge/config.mk
make DESIGN_CONFIG=./designs/asap7/chi_async_bridge/config.mk FLOW_VARIANT=small

The constraints check themselves. Rename the sync register in src/chi_async_bridge/sync_shift_reg.sv, or put a gate between two of its flops, and synthesis stops:

constraint.sdc: synchronisers: unexpected cell name sink.asyncQSink_dat_flit.widx_gray.bit_[0].stage[0]$_DFF_PP0_
constraint.sdc: synchronisers: sink.asyncQSink_dat_flit.widx_gray.bit_[0].sync[2]$_DFF_PP0_ does not drive sink.asyncQSink_dat_flit.widx_gray.bit_[0].sync[1]$_DFF_PP0_ alone

mock-cpu should be retired

asap7/mock-cpu was meant to test this. Once CI's design list points at asap7/chi_async_bridge, mock-cpu and designs/src/fifo can be deleted in a follow-up. The list is not in this repository: nothing outside mock-cpu's own directory names it.

What mock-cpu cannot show:

  • both halves of each FIFO sit inside one block, with no synchroniser between a crossing and a pin, and no reset synchroniser: the raw resets reach both domains;
  • rdata is combinational from the FIFO memory to a port and declared a false path, which hides the data crossing it exists to test;
  • its one CDC budget covers pointers and data alike and names no synchroniser, and a renamed pin silently unconstrains its IO targets: OpenSTA warns (STA-0101, STA-0471) and drops the whole constraint;
  • it reports a hold WNS of 1e+42;
  • its RTL comments describe 4 pipeline stages and a multiply; the code has 1024 stages and an add.

Appendix

A. Why: the boundary of a hardened core

XiangShan's tile is the block a XiangShan SoC hardens, and the CHI bridge is what sits immediately outside its pins: XSTileWrap puts the tile half beside it on the core clock, XSNoCTop the NoC half on the NoC clock. The bridge terminates every path the tile's CHI pins carry at a flop. That is why a block like the tile is constrained with set_max_delay budgets on its ports rather than with input and output delays, and why only its register-to-register paths can fail timing closure. This design is the other side of that argument: the crossing itself, constrained without exceptions that hide a path, and checked.

B. Names before and after synthesis

A constraint that names an instance is written against the RTL and read against the synthesised netlist. On this design the flattened name of a synchroniser flop gains yosys's cell type (...ridx_gray.bit_[2].sync[1]$_DFF_PP0_); a flop takes the name of the net it drives, not of the variable that held it (async_ridx, not ridx_gray); ODB escapes the brackets and timing analysis does not; and asap7's flop with asynchronous set and reset has only an inverted output, so each synchroniser step is flop, inverter, flop. constraint.sdc counts the chains it names (134), checks each step is exactly that and nothing else, and only then constrains them.

C. How the period was found

The flow tracks its target: at 420, 380 and 340 ps both this design and XiangShan's bridge close, each landing within 4 ps of the target on the same path classes. At 300 ps both fail by a few picoseconds, on the same path. The NoC half is not calibrated: XiangShan's NoC link layer (link-state machines, credit managers), left out here as NoC-domain logic beyond the bridge, is in its NoC domain's worst path; both NoC domains keep more than 200 ps of slack at the 1021 ps NoC period.

The clock trees are OpenROAD CTS's H-trees, 261 ps deep on the core clock at final: an ordinary tree at a 1,000 ps period, not the mesh a 300 ps core would get. The crossing is timed without clock latency or hold, so the tree's depth does not enter what this design tests; it does move the same-clock paths and so the 300 ps, which is why XiangShan's bridge was measured through the same flow.

🤖 Generated with Claude Code

@oharboe
oharboe marked this pull request as ready for review October 1, 2026 13:32

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces the chi_async_bridge design, which models XiangShan's asynchronous CHI bridge between the core and network-on-chip clock domains. It includes SystemVerilog implementations for the queue source and sink, shadow buffers, reset generators, and synchronizers, along with SDC constraints and documentation. The review feedback recommends adding parameter validation assertions (initial assert) across several modules (async_queue_source, async_queue_sink, shadow_buffer, sync_shift_reg, and reset_gen) to guarantee that parameters like DEPTH, ENTRIES, and SYNC are valid (e.g., powers of two or at least 2), thereby preventing potential compilation errors or runtime functional failures.

A new test design with one concern: an asynchronous clock crossing,
constrained without exceptions that hide a path, and implemented by the
flow as constrained. It is XiangShan's CHI bridge between its tile and
its network-on-chip, both halves in one block: six flit channels, each
a rocket-chip async queue, with their link credits, handshakes and a
reset synchroniser per domain, as readable parameterised SystemVerilog
read by slang.

constraint.sdc bounds every crossing with set_max_delay
-ignore_clock_latency, budgets the ports per domain as the platform's
constraints.sdc budgets a macro's, keeps synchroniser hops short, and
checks the names it constrains against the synthesised netlist,
stopping the flow if they are wrong.

The core period, 300 ps, is where XiangShan's own bridge, elaborated
from its Chisel and hardened alone through this flow, just fails at
global route; this design fails there on the same path, within 1.5 %.
README.md has the numbers. base is XiangShan's bridge as it is;
FLOW_VARIANT=small|medium are faster rungs.

Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@oharboe
oharboe requested a review from precisionmoon October 1, 2026 13:38
@oharboe
oharboe force-pushed the asap7-chi-async-bridge branch from 3a36af1 to 478cc0c Compare October 1, 2026 14:09
@openroad-ci

openroad-ci commented Oct 1, 2026 •

Copy link
Copy Markdown
Member

🔍 QoR check

Metrics reflect the PR merge build — i.e. what will land on the target branch.

Commit 50ec73e · Jenkins build #5 · Baseline: build · View build on dashboard

62 design(s) checked — 0 with regression(s), 0 without a comparable baseline.

@oharboe

oharboe commented Oct 1, 2026

Copy link
Copy Markdown
Collaborator Author

@precisionmoon pr-merge works so pr-head we can ignore

@precisionmoon

Copy link
Copy Markdown
Contributor

I asked @maliberty to review this PR.

@maliberty

Copy link
Copy Markdown
Member

Does the sv code come with a license file?

@oharboe

oharboe commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator Author

Does the sv code come with a license file?

Claude rewrote and stripped the generated verilog from XIangShan Chisel to SystemVerilog so that everything is human-readable.

I don't think generated verilog is helpful for an idiomatic example of a clock crossing bridge.

@maliberty maliberty left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From Claude (AI-generated review, posted at @maliberty's request)

Correctness issues in constraint.sdc:

  1. Port budgets don't match the platform file they cite (constraint.sdc:39-70). The comment says ports are budgeted "as $PLATFORM_DIR/constraints.sdc budgets a single-clock macro's ... with that file's ratio", but flow/platforms/asap7/constraints.sdc has no ratio: it uses a fixed 80 ps for in2reg, reg2out and in2out. This file uses 0.8 * period, i.e. 240 ps (core) and ~817 ps (NoC). Either match the platform file or fix the comment (and the README line that repeats it).

  2. No in2out budget, so port-to-port paths are unconstrained (constraint.sdc:64-70). noc_tx_{req,rsp,dat}_ready reaches noc_tx_*_flitv combinationally (chi_async_bridge_sink.sv: assign tx_flitv = valid && tx_ready). The platform file covers this with its in2out set_max_delay; this file omits it.

  3. Nit: NoC clock comment (constraint.sdc:11). "about half the core's frequency": 1021 ps vs 300 ps is ~0.29x, not half.

  4. Question: SYNC is hardcoded in the check (constraint.sdc:95-101). DEPTH is parsed from VERILOG_TOP_PARAMS, but sync_stages is fixed at 3, so overriding SYNC via params would trip the check. It fails explicitly, which is fine, but should SYNC be parsed the same way?

  5. Nit: scope of the self-check (README, "fails the build when it stops being true"). SDC_FILE is only read at synthesis; after that write_sdc canonicalizes it into 1_synth.sdc. So the check guards against yosys renaming/restructuring, not against later resizer/hold-fix edits inside a synchroniser hop. Worth stating.

oharboe and others added 6 commits October 6, 2026 07:25
… platform's

The comment and README said the ports are budgeted with
$PLATFORM_DIR/constraints.sdc's ratio. That file has no ratio: it gives
a single-clock macro a fixed 80 ps per port path. The budgets here are
80 % of each domain's period, a choice of this file; say so. The
constraints themselves are unchanged, so the README's results stand.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
noc_tx_{req,rsp,dat}_ready reach noc_tx_*_flitv through one gate
(chi_async_bridge_sink.sv: tx_flitv = valid && tx_ready), and nothing
constrained them: on the small variant's synthesised netlist they were
the only port-to-port paths, required INF. Give each domain an in2out
budget as the platform's constraints.sdc does, at the same 80 % of that
domain's period as its other port paths, and an in2out path group.

Now required 816.8 ps, met by 804 ps; every other path is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
1021 ps against 300 ps is 0.29 times the frequency, not half. Only the
comment changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
The synchroniser check parsed DEPTH from VERILOG_TOP_PARAMS but fixed
the stage count at 3, so a flow that set SYNC stopped at synthesis:

  constraint.sdc: synchronisers: sink.asyncQSink_dat_flit.widx_gray.bit_[0] has 4 stages, not 3

Parse SYNC the same way, with the RTL's default. The small variant with
SYNC 2, 3 and 4 now passes the check; with SYNC 4 it stopped before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
constraint.sdc is read once, by synth_odb.tcl against yosys's netlist;
later stages read what write_sdc made of it, one set_max_delay per hop
by cell name (172 on the small variant). So the check catches what
synthesis does to a synchroniser, not a buffer that resizing or hold
repair puts inside a hop afterwards, which the hop's budget still
bounds. The README now says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
The SystemVerilog is rewritten from XiangShan's Chisel rather than
generated from it, but it is still derived from that source and keeps
its licenses. The async queue and synchroniser come from rocket-chip
(Apache-2.0, LICENSE.SiFive); the bridge halves, shadow buffer, reset
synchroniser and top-level wiring from XSCache, Utility and XiangShan
(Mulan PSL v2).

As picorv32 does: LICENSES/ holds both texts verbatim, SOURCE.md names
each file's source, commit and license, and each file starts with its
SPDX identifier, the upstream copyright lines and a note of what
changed. The README points at them. No RTL changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
@oharboe

oharboe commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

From Claude, at @oharboe's request

Thanks, @maliberty, all five hold up; I checked each against the code before changing anything. Each is its own commit on top, so the review history is intact.

  1. Port budgets vs the platform file — d8069b1. Right: flow/platforms/asap7/constraints.sdc has a fixed 80 ps and never had a ratio. The 80 % of each domain's period is this file's own choice, and the comment and README now say so. I fixed the comment rather than the budgets because the README's results were calibrated against XiangShan's own bridge under these exact constraints; the constraints themselves are unchanged.
  2. No in2out budget — 762750f. Confirmed on the small variant's synthesised netlist: noc_tx_{req,rsp,dat}_ready -> noc_tx_*_flitv were the only port-to-port paths, with required = INF. Each domain now has an in2out set_max_delay at the same 80 % as its other port paths, plus an in2out path group: required 816.8 ps, met by 804 ps. Nothing else moves.
  3. "About half" — b3cc97b. 1021 vs 300 ps is 0.29, and the comment now says about 0.3.
  4. SYNC hardcoded — af424a0. Yes. With SYNC 4 in VERILOG_TOP_PARAMS, synthesis stopped with ... widx_gray.bit_[0] has 4 stages, not 3. SYNC is now parsed like DEPTH, with the RTL's default; the small variant passes the check at SYNC 2, 3 and 4.
  5. Scope of the self-check — 4ae1925. Correct: synth_odb.tcl reads constraint.sdc once, and later stages read the write_sdc output, one set_max_delay per hop by cell name (172 of them on the small variant). The README now says the check guards what synthesis does; a buffer that resizing or hold repair later puts inside a hop is still held to the hop's budget, but the hop isn't re-checked.

License (your question above) — 1923012. The SystemVerilog is rewritten from XiangShan's Chisel rather than generated, but it is still derived from it, so it keeps its licenses. Following picorv32's layout:

  • src/chi_async_bridge/LICENSES/ holds rocket-chip's LICENSE.SiFive (Apache-2.0, for the async queue and synchroniser) and XSCache's LICENSE (Mulan PSL v2, for the rest), both verbatim.
  • SOURCE.md names each file's upstream source, commit and license.
  • Each .sv starts with an SPDX identifier, the upstream copyright lines and a note of what changed.

There are no RTL changes.

@oharboe
oharboe requested a review from maliberty October 6, 2026 05:35
@maliberty

Copy link
Copy Markdown
Member

Slack goes positive at grt. It would be good to slightly tighten the clock period so that optimization doesn't stop.

4_1_cts.json:31: "cts__timing__setup__ws": -0.41378,
5_1_grt.json:330: "globalroute__timing__setup__ws": 0.00105471,
6_report.json:32: "finish__timing__setup__ws": -14.8036,

oharboe and others added 3 commits October 6, 2026 08:22
OPENROAD_HIERARCHICAL=1, the -hier mode that is to become the default.
A flat netlist gives -hier nothing to link, so SYNTH_KEEP_MODULES keeps
what a clock-crossing bridge is usually kept as: the two clock-domain
halves, their asynchronous queues and their shadow buffers.

The synchroniser check in constraint.sdc now finds the chains with
get_cells -hierarchical; their names are the kept instances joined
with '/', e.g. sink/asyncQSink_dat_flit/widx_gray.bit_[0].sync[1]. On
the small variant all 172 hops are found and written back by name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
…n does

An integration test: a timed asynchronous crossing, a self-checking
constraint file, slang with SYNTH_KEEP_MODULES under -hier, instance
names resolved through the hierarchy, three threshold voltages on a
multi-clock design, and the top's parameters set from the flow. Checked
against every config.mk and SDC under flow/designs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
… grt

At 300 ps the worst slack reached +0.001 ps at global route (flat
netlist), so repair stopped there. At 290 ps, linked hierarchically,
the worst slack is -35.8 ps at CTS, -35.5 ps at global route and
-30.1 ps at final, on the core half's async queue sink read, as in
XiangShan. README.md's Results say so; the XiangShan calibration there
is marked as measured on the flat netlist.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
@oharboe

oharboe commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Thanks, agreed. The core clock is now 290 ps, so repair keeps working through global route instead of stopping at zero slack.

Two more changes came with it: the design is now linked hierarchically (OPENROAD_HIERARCHICAL=1, with the bridge's clock-domain halves, async queues and shadow buffers kept by SYNTH_KEEP_MODULES), and the README lists what this design tests that no other design in flow/designs does. The SDC's synchroniser check now finds its flops through the hierarchy.

Worst setup slack for the base variant, linked hierarchically, with only clk_period in constraint.sdc changed. To pick a different period, set clk_period to any row:

core clock CTS global route final final, of the period
300 ps -13.3 ps -19.4 ps -11.1 ps 3.7 %
290 ps -35.8 ps -35.5 ps -30.1 ps 10.4 %
280 ps -35.6 ps -35.0 ps -31.3 ps 11.2 %
270 ps -53.0 ps -53.8 ps -51.2 ps 19.0 %

With the hierarchy kept, 300 ps already stays negative at global route; 290 ps leaves more room for repair, and 280 ps buys nothing over it. At 290 ps the worst path at final is the core half's async queue sink read, the same path class XiangShan's own bridge fails on. These were measured outside CI, so CI's numbers may differ by a few picoseconds.

@oharboe

oharboe commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

fixed

@maliberty maliberty left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vvbandeira please add to the CI

@oharboe do you plan to remove mock-cpu?

@maliberty
maliberty merged commit 517d105 into The-OpenROAD-Project:master Oct 8, 2026
12 checks passed
@oharboe

oharboe commented Oct 8, 2026

Copy link
Copy Markdown
Collaborator Author

@vvbandeira please add to the CI

@oharboe do you plan to remove mock-cpu?

Yes, but first it must be removed from CI.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants