ram: register-file options for generate_ram

[oharboe]

This replaces #11669.

This PR adds the options a register file needs to generate_ram and generate_ram_netlist, one commit per option, so each can be reviewed on its own. Every option is off by default: with none given, generate_ram builds exactly what it builds today, and the existing ram tests are unchanged.

Each option comes from a register file in a real design: the ORFS designs (riscv32i, ibex, cva6, coralnpu, swerv) and XiangShan's (IntRegFile has 12 read and 9 write ports, banked reads and an x0 word). The commits are in dependency order, and each commit message says what its option does and why.

#	Commit	Test
1	ram: generate_ram with more than one write port	write_ports_nangate45
2	ram: generate_ram reads through AND-OR trees without tristates	and_or_read_asap7
3	ram: generate_ram -zero_word, a word that reads 0	zero_word_asap7
4	ram: generate_ram -reset_value, an asynchronous reset	reset_asap7
5	ram: generate_ram -banks, -bank_columns, -bank_order	banks_asap7
6	ram: generate_ram -rb_ports, banked read ports	banked_read_ports_asap7
7	ram: generate_ram -read_latency, registered read addresses	register_read_address_asap7 (renamed in 19)
8	ram: generate_ram -write_style mux, a hold mux per bit	write_mux_asap7
9	ram: generate_ram_netlist -periphery unplaced	periphery_unplaced_asap7
10	ram: generate_ram -cells and -name	cells_name_asap7
11	ram: generate_ram -decoder word, a balanced tree per word	decoder_word_asap7
12	ram: generate_ram -bit_folds, a word's slices in rows	bit_folds_asap7
13	ram: generate_ram_netlist -periphery verilog	periphery_verilog_asap7
14	ram: generate_ram -write_priority or, colliding writes OR'd	write_priority_or_asap7
15	ram: generate_ram -service_columns, room in the array	service_columns_asap7
16	ram: generate_ram -bank_column_layout, a word's bits contiguous	bank_column_layout_asap7
17	ram: stop on out-of-range option values	option_errors_asap7
18	ram: test BUILD's per-test data in sorted order
19	ram: -read_latency is -register_read_address	register_read_address_asap7
20	ram: generate_ram routes on asap7	the asap7 tests, routed
21	ram: generate_ram -periphery verilog, the core routed	periphery_verilog_asap7
22	ram: the option tests route their blocks through generate_ram	all 21
23	ram: generate_ram's help lists its options

Testing. Each option has a test of what it is meant to do, not a snapshot of the netlist. Since commit 22 each test builds its block with generate_ram, so the block is placed and routed, and checks that every net is routed with no DRC violations before it simulates the routed block. src/ram/test/ram_sim.tcl simulates the generated block cycle by cycle: combinational cells from their Liberty functions, and the few flops and clock gates the tests use from a one-line model each. The tests then write and read random words against a model of what the RAM should hold. Examples: word 0 reads 0 with -zero_word 0; every word reads the reset value after -reset_value; colliding writes give the last port's data, or their OR with -write_priority or; with -register_read_address 1 the data follows a clock after its address. Layout options also check placement: rows per word, empty service columns, contiguous words, pins on the pin layer's tracks. Each test was checked to fail when its option is removed or reversed. The existing tests are unchanged.

The commits are split one per option for reading. They were built and tested together, at the last commit, not one by one.

The integration test is The-OpenROAD-Project/bazel-orfs#1239 (before it, The-OpenROAD-Project/bazel-orfs#1234): it carries these commits and the ORFS side, and runs register files from ORFS designs through simulation, equivalence checks and placement. It is being extended to XiangShan. The ORFS changes that use these options (AUTO_MEMORIES_REGFILES through generate_ram, The-OpenROAD-Project/OpenROAD-flow-scripts#4651) are carried as patches in bazel-orfs until OpenROAD has this support and ORFS is bumped onto it.

🤖 Generated with Claude Code

[github-actions]

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

[gemini-code-assist]

Code Review

This pull request significantly expands the RAM generator's capabilities by introducing several new configuration options, such as read styles, banked configurations, asynchronous resets, custom decoders, bit folding, and Verilog wrapper generation. It also adds a cycle simulator and extensive test cases to verify these features. The code review feedback is highly constructive, suggesting robust input validation for the newly introduced parameters (such as -zero_word, -banks, -bank_columns, -service_columns, -bit_folds, -read_latency, and -rb_ports) to prevent potential runtime errors like division-by-zero, out-of-bounds access, or infinite loops, as well as addressing a potential check bypass when -rb_ports is explicitly set to 0.

[oharboe]

@rovinski FYI

[oharboe]

@maliberty @rovinski pr-merge green, if pr-head fails then that's not important.

[oharboe]

Mmm.... green. 😌

[rovinski]

None of the tests actually check that the rams are routable. generate_ram_netlist should be avoided as it is an internal command - only generate_ram should be used.

[rovinski]

I have a lot of concerns and I don't have time to review a 4k line PR.

You should really take a look at this paper as it covers several strategies for high performance RAMs that we are looking to implement.

ram: generate_ram reads through AND-OR trees without tristates

Use De Morgan's Law and convert to NAND-NOR tree for reduced delay and size

ram: generate_ram -zero_word, a word that reads 0

I would want to see an experiment showing that this is better than implementing the functionality in RTL outside of the RAM. I am not convinced that putting in a 0 row in the RAM is the best methodology.

ram: generate_ram -reset_value, an asynchronous reset

For reasons mentioned in #11669 I am opposed to implementing this feature. I have not seen any convincing use case that this is a good feature.

ram: generate_ram -read_latency, registered read addresses

The feature is ok but I don't like the naming. Either the output should be registered or unregistered. There is not really a reason why the latency would be anything other than 0 or 1. So maybe change the flag to -register_outputs (default unregistered)

See #11669 for other comments

It would be very helpful to see screenshots of the layout(s) generated to review.

[oharboe]

@rovinski thank you for taking the time to go through this, here and on #11669. You're under no obligation to, and a little direction from you goes a long way.

(This continues the discussion from #11669 (comment).)

Before I roll up my sleeves, here is how I read your comments and what I plan to do about each one.

First, I apologize for my ignorance on memories. I'm not trying to become an expert. As my open PRs show, I'm trying to get the whole flow in place, from RTL to XiangShan-sized designs, so that experts can work on the individual pieces one concern at a time, from an OpenROAD+ORFS baseline, warts and all.

That's what this PR is: a new baseline of features. Some will be replaced by something better, some made automatic, some removed. None of that can be tried against OpenROAD, ORFS and real designs until the features are in master; out of tree, the turnaround is too long. So I'll keep this as one PR and address the concerns in it.

Routing and generate_ram_netlist. I'll switch the tests to generate_ram, so every test routes the block it checks. OpenROAD used to run flows, but that required bazel-orfs and didn't add enough value to break ORFS's separation of concerns. The compromise is that an OpenROAD bump can break a flow in ORFS, and in exchange OpenROAD CI doesn't run every ORFS flow. Full-flow integration tests on tiny designs, one for every generate_ram option, will go into The-OpenROAD-Project/bazel-orfs#1234.

Screenshots. I'll commit them in bazel-orfs#1234 and embed them here.

NAND/NOR read tree. I'll measure it against the AND-OR tree and post delay and area.

-read_latency will become -register_read_address (0 or 1). It registers the read address, as a flow-through synchronous SRAM does, and the decoder and read tree come after the flop. A register on the output data, as in a pipelined SRAM, is a different circuit and would be its own feature.

-write_style mux. Each bit has a mux that feeds back the stored value unless that word is written, instead of a clock gate per word. I'll make the commit message say so.

-zero_word and -reset_value stay in the baseline. The designs ask for them: x0 is RISC-V, and ibex, cva6, coralnpu and swerv reset their register files for their own reasons. We take the RTL as it is. Whether a zero row beats tie-lo cells, or ibex's ECC bits are better split from the data bits, is the experiment you describe. With the baseline in master, anyone can run it against these designs.

On swerv, you're right, I worded that badly: I meant the flop cell swerv's RTL instantiates, which always has a reset, not a PDK.

-decoder word. Choosing the strategy automatically is the goal. The explicit option is the baseline an automatic choice gets measured against.

12 read and 9 write ports. Register files like that are normal in high-performance CPUs, and XiangShan is where this is headed. Synthesized flops are what the generated register file is compared against.

The paper. I couldn't get it. IEEE has it behind a paywall, and the open-access listing for the journal version (ACM TODAES 2016) at EPFL has no PDF attached. What in it do you think applies here? That's exactly the kind of direction that goes a long way. It's also another reason to put a baseline into OpenROAD and ORFS master: people who have that knowledge can then improve the generator against real designs, one concern at a time.

[oharboe]

@rovinski on the bigger question this PR raises: you asked for these features to go into generate_ram rather than sit beside it, and that's what #11723 does. Looking at the result, do you still think it should be one command?

generate_ram sounded more general than it was. It solved one problem, a routed RAM block, in one particular way. With the options added here it does several different things. The code shows it: RamGen::generate is a single function of about 1,300 lines that handles every option, and the parts around it hardly depend on each other:

Part	What it does	Shared with
Cell selection (findMasters, ~330 lines)	finds the cells for each role in the libraries	everything
Array construction (makeBit, makeSlice, makeWord, decoders, read trees)	word rows by bit columns, placed by construction	RAM and register file
Register-file logic	several write ports and write priority, zero word, reset, banks and banked read ports, registered read address, write mux, word decoder, bit folds, service columns	register file only
Physical finish (ramPdngen, ramPinplacer, ramFiller, ramRouting, ~260 lines)	power grid, pins, filler, routing	any placed block
Periphery for a parent flow (splitPeriphery, unplacePeriphery, ~280 lines)	leaves the periphery to the parent's placer, or writes it as Verilog for the parent's synthesis	a flow that places the block itself (ORFS)
Behavioral Verilog	the model	RAM and register file

OpenROAD already splits commands where the steps are separate: macro placement and detailed routing are two commands. Here a list is less obvious. A split could look like this, with cleaner syntax per command and the code above shared behind them:

• generate_ram: what it was, a routed RAM block, with its own options and its existing tests unchanged.
• generate_register_file: the register-file options, on the same array construction and cell selection.
• A finishing command (power grid, pins, filler, routing) that both of them call, and that anything else that builds a placed block could call too.
• The periphery handling as its own step, for a flow like ORFS that places and optimizes the periphery with the parent.

What I found on XiangShan is that the details of the RAM weren't the problem. Global placement was: long wires. If the array isn't placed where it needs to be, there's nothing the RAM can do about it. To help global placement, this PR separates the periphery from the regular structure, and it also lets a flow take the netlist only and leave the placement to global placement. Which is best depends on the context; no single option is best everywhere. By its own QoR function, generate_ram builds an optimal block, and you become what you measure. I think that QoR function is a good one, and in many cases it will also turn out to be optimal in the system.

Memories are one case of a wider pattern: a repeating structure the general flow doesn't handle well. CAMs are another, and so are design-specific structures. XiangShan's reorder buffer is hundreds of copies of one entry, each decoding the same wide bus locally. That's a very large number of broadcast pins and thousands of cells to hold a few dozen bits of state. Synthesis can't share that decode across entries, and global placement can't spread it. The aim is a large cut in synthesis time along with better QoR.

Those structures don't belong in generate_ram. They don't have to be in the OpenROAD binary either, at least not yet. I'm tinkering with them as a separate binary in bazel-orfs, built against OpenROAD's database, with the user injecting the netlist of one tile: tools/structured_gen. I'd be surprised, and flattered, if anyone is interested in it at this point. It could become part of OpenROAD later, reusing the array construction, cell selection and finishing step above, but not until there are interesting results and I've learned more.

I don't think we'll get the split right on the first try. Reworking the code for a split is cheap now. The real cost is the cognitive load on users each time the API changes.

These features are experimental until they're stable. OpenROAD has no releases, and anyone can see from the git history how mature a feature is. A note in the docs saying "experimental" would be out of date as soon as it was written, and less true than the history.

A cross-cutting change such as read_db -hier needs an explicit experimental toggle. A separate command doesn't, because the command is the toggle. The options in this PR work the same way: each is off by default.

My main concern is a baseline that supports the features in this PR, so contributors can work on it one concern at a time, as their interest and resources allow. Given that, I'm flexible on the split: one command now, the split above, or another you prefer.

[oharboe]

@rovinski about that paper: I never read it, I never saw it, and I don't know anybody who has. But I may have overheard some people talking about it, and then I happened to be looking at the code.

Word is it describes how to build a small standard-cell memory with controlled placement:

• latches as storage,
• a NAND/NOR tree for the read path,
• registered read addresses,
• a clock gate per word on the write path,
• gaps left in the array for buffers and for the synthesized decoders and clock tree.

It places those cells by construction, then lets the standard flow finish. The way I hear it, the scope is low-power, low-voltage, two-port (one read, one write) memories from 32×32 to 128×32 in 28 nm FD-SOI. Each block is measured on its own: area, wirelength, power and runtime, against the same RTL placed without control. Beyond about 256 rows it goes to banks.

If that's right, it's a clear result within that scope, and much of it is already in generate_ram. The and_or read path is that tree: an AOI22 over each pair of rows, then NAND2 and NOR2 levels. -register_read_address is the read address register. -service_columns gives the buffer gaps, the default write style is a clock gate per word, and -banks is the banking.

From what I'm told, the paper puts the whole flow into making a macro. That's the right choice for what it measures, but it can't show what the general flow would do with the same cells in context, or whether that would be the better solution there. I want to keep that signal. So this PR keeps both paths: a block placed by construction, and a netlist, or a placed core with its periphery, that the parent's flow places and optimizes with its surroundings. On XiangShan the comparison between the two is the interesting part.

The latch storage, I hear, relies on its latch-to-output path having 1.5 cycles. In XiangShan, the only multicycle path I know of is on L2's data SRAMs, which the RTL reads over two cycles. A 1.5-cycle path would fit inside that on timing. But an L2 data array is far beyond the sizes the paper targets, so it isn't a strong fit.

This PR is aimed at the cases outside that scope:

• register files with many read and write ports, as in high-performance CPUs;
• flops with what RTL register files carry: reset, a zero word, write priority between ports, banked reads;
• the block placed in the context of its parent, where the periphery can be flattened and optimized with its surroundings.

[oharboe]

@rovinski five new commits on top, no force-push, so the review history stays.

Commit	What
ram: -read_latency is -register_read_address	The option registers the read address. The decoders and read trees come after the flop. 0 and 1 only.
ram: generate_ram routes on asap7	-tracks <file>: asap7's LEF M2 track offset is negative (IFP-0039), so the tracks come from the file asap7's flows use. Pins are kept off generate_ram's own power straps: on asap7 the M4 straps start at the bottom edge and covered the first pin track (DRT-0255). The existing sky130 and Nangate45 blocks keep their pins where they were.
ram: generate_ram -periphery verilog, the core routed	generate_ram takes -periphery verilog: the routed core, with its pins on its edges, and the periphery as Verilog for the parent's synthesis. -periphery unplaced stays generate_ram_netlist's, for a flow that places the periphery itself: the "structured placement group" item in the ram feature tracker, #9392.
ram: the option tests route their blocks through generate_ram	Every option test now builds with generate_ram, checks that every net is routed with zero DRC violations, then simulates the routed block.
ram: generate_ram's help lists its options	help generate_ram now lists the register-file options.

Routing. Routing the tests found the two asap7 problems above. A thin banked strip, 8 words in four banks two wide (36 × 1.35 µm), can't be routed: its East edge has six pin slots for nine address pins. It fails loudly (PPL-0111/DRT-0255), and the bank tests use 32 words. On one thread, three tests spend 5–12 minutes in detailed route (banks, bank_column_layout, write_priority_or). Changing the power straps or limiting the routing layers didn't shorten it. The rest take seconds to two minutes.

NAND/NOR read tree. It's already that: -read_style and_or builds an AOI22 over each pair of rows, then NAND2 and NOR2 levels by turns. The commit title "AND-OR trees" named the function, not the gates.

Integration test: The-OpenROAD-Project/bazel-orfs#1239. It carries these 23 commits and runs each option through the ORFS flow to detailed route on a small design (12 designs, all routed clean). Routed blocks across asap7, Nangate45 and sky130hd, a sample of the options:

All 14, with the options each shows: https://github.com/The-OpenROAD-Project/bazel-orfs/blob/c2481240914d97010eef8d89a23b040e38decb90/test/regfile/images/README.md

[oharboe]

The insight behind generate_ram, and behind the paper referenced earlier in this thread, is that a repeating structure is generated faster and better by explicit code than by general-purpose synthesis and placement. To reach real designs, that structure has to match the abstractions the RTL already uses.

For design space exploration, a memory gets used when it fits the flow people already trust. That means formal equivalence with open-source tools, static timing (flip-flops are better supported there than latches), a match to the RTL as written, and an SDC users can write. Asking RTL authors to write for a new memory works when a tapeout pays for it. For small memories like register files, where a memory compiler is too expensive or not available, the memory has to come to the RTL. That is where generate_ram shines.

This study maps that reach for the designs in ORFS: which register files yosys plus Verilog surgery can hand to generate_ram today, and what QoR that buys.

• Already matching by shape: picorv32's picorv32_regs and tinyRocket's register file are both 31×32 2r1w with x0 handled outside, the shape generate_ram listed. On asap7, which has no tristate cell, they needed a read path built from AND-OR gates.
• Needing this PR's options: riscv32i (x0 inside the module) and ibex (asynchronous reset). swerv, cva6 and coralnpu (more ports, reset, write priority) are prepared, with numbers to follow.
• Surgery, on the books: where the flow cannot reach a register file, a script beside the design's config moves it into a module of its own. That is either a change the RTL might make for a tapeout, or a stand-in for a feature yosys does not have yet. It is checked and never changes function. For coralnpu's FRegfile, a simulation of 20k cycles against the original showed 0 mismatches.

Results through detailed route on asap7 with RCX extraction, best shape against flip-flops. Min period = clock period − WNS; reg→reg is the same for register-to-register paths alone:

design	shape	Δ min period	Δ reg→reg	Δ std-cell area	Δ power
tinyRocket	verilog periphery	−5.8 %	−5.8 %	−7.0 %	−15.4 %
riscv32i	netlist	−3.1 %	−2.0 %	−27.7 %	−0.3 %
ibex	netlist	−2.2 %	−2.2 %	−13.4 %	−23.4 %
picorv32	verilog periphery	+3.8 %	+0.8 %	−11.0 %	−43.6 %

• tinyRocket: every shape is faster, smaller and lower in power: period −3.8 to −5.8 %, area −3 to −7 %, power −12 to −22 %.
• ibex and riscv32i: a shape is better or within noise on all three.
• picorv32: register-to-register paths are within noise in every shape, area falls 4–12 % and power 19–47 %. Its full period is set by flop-to-mem_la_addr output paths that do not pass through the register file.
• Run time: the netlist and Verilog-periphery shapes roughly halve the flow's run time at the ORFS clock.

One run per arm. Name and hierarchy perturbation alone moves results by more than 7 % (Kahng and Mantik, ISQED 2002), and routed wirelength by more than 10 % (Chan, Kahng and Woo, SLIP 2020). Differences of a few percent are within noise.

Full tables, stage times and the harness: The-OpenROAD-Project/bazel-orfs#1250

Try it, from bazel-orfs with that PR:

bazelisk run @orfs//flow/designs/asap7/ibex-regfile:ibex_core_route web_route

Claude made the changes and stared at paint drying.