Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 25 additions & 18 deletions docs/user/AutoMemories.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,10 @@ itself a welcome signal that someone is using it.

## What it does

With `AUTO_MEMORIES=1`, a pre-synthesis step runs
`scripts/memories/gen_memories.py` over `VERILOG_FILES` and writes:
With `AUTO_MEMORIES=1`, a pre-synthesis yosys pass
(`scripts/memories/extract_memories.tcl`) elaborates `VERILOG_FILES`
into `$(RESULTS_DIR)/memories_inferred.json`, and
`scripts/memories/gen_memories.py` reads that netlist and writes:

| File | Content |
| --- | --- |
Expand All @@ -39,23 +41,26 @@ flip-flops, like any other RTL.

## How memories are detected

Detection is a fast Python scan (`scripts/memories/detect.py`) for
modules whose entire port list follows the firtool (CIRCT) memory port
convention: every port named `<R|W|RW><n>_<function>`, e.g. `R0_addr`,
`W0_en`, `RW0_wdata`, including the subword-split forms `RW0_wdata_3` /
`W0_mask_2`. This is what Chisel/firtool emits for module-separated
memories, and what the rocket-chip generation of Chisel emitted (the
in-tree tinyRocket design).
Yosys infers the memories. `scripts/memories/extract_memories.tcl`
reads the design sources with the design's frontend, runs `hierarchy`,
`proc` and `memory -nomap`, and writes the netlist as JSON.
`scripts/memories/detect.py` then takes each `$mem_v2` cell in it:

- depth and width from `SIZE` and `WIDTH`, read and write port counts
from `RD_PORTS` and `WR_PORTS`, and write-mask lanes from the width
of `WR_EN`. Read-write ports are not inferred; a `.memories` override
can describe them (see below).
- pins named `R<n>_clk/addr/en/data` and `W<n>_clk/addr/en/data`, plus
`W<n>_mask` when there are mask lanes.
- the module's name when the `$mem_v2` is the only cell in its module,
otherwise the cell's name.

Two consequences, documented as deliberate scope:

- **Module boundary only.** A memory embedded inside a larger module
(a bare `reg [7:0] mem [0:255]` next to other logic) is not detected.
Yosys's memory-inference pass sees those; FPGA tools extract them
into block RAMs. Wiring yosys up as the detector — or growing such a
pass in OpenROAD SYN, which currently has no memory inference and
therefore cannot be leaned on here either — is future work; this
feature punts on it with the simple scanner.
- **Module boundary only.** Synthesis blackboxes converted memories by
module name, so only a memory alone in its module is replaced by a
macro. A memory inferred next to other logic is named after its
cell, which matches no module.
- **No banking.** Each detected memory maps to exactly one macro. A
memory too wide, too deep, or too ported for a single sensible macro
is not decomposed across several macros — a future extension.
Expand Down Expand Up @@ -133,12 +138,14 @@ clear error.
make DESIGN_CONFIG=designs/asap7/tinyRocket/config.mk synth floorplan
```

The generator can also be run standalone to inspect what it would do:
The generator can also be run standalone, on the
`memories_inferred.json` that run leaves in the results directory, to
inspect what it would do:

```shell
python3 flow/scripts/memories/gen_memories.py \
--platform asap7 --out-dir /tmp/mems --json /tmp/memories.json \
--verilog flow/designs/src/tinyRocket/freechips.rocketchip.system.TinyConfig.v
--yosys-json flow/results/asap7/tinyRocket/base/memories_inferred.json
```

## Consuming from bazel-orfs
Expand Down
2 changes: 1 addition & 1 deletion docs/user/FlowVariables.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ configuration file.
| <a name="ADDITIONAL_MEMORIES"></a>ADDITIONAL_MEMORIES| Experimental. Space-separated list of user-supplied `.memories` files (the memories.json JSON schema) merged onto the set AUTO_MEMORIES detects — to force-convert a memory the idiomatic gate rejects, or to describe one the scanner cannot find. See docs/user/AutoMemories.md.| |
| <a name="ADDITIONAL_SITES"></a>ADDITIONAL_SITES| Passed as -additional_sites to initialize_floorplan.| |
| <a name="ASAP7_USE_VT"></a>ASAP7_USE_VT| A space separated list of VT options to use with the ASAP7 standard cell library: RVT, LVT, SLVT.| RVT|
| <a name="AUTO_MEMORIES"></a>AUTO_MEMORIES| Experimental. When set to 1, memory-shaped modules in the RTL (firtool/CIRCT `R*/W*/RW*_` port convention, module boundary only) are detected pre-synthesis, inventoried in `$(RESULTS_DIR)/memories.json`, and — when idiomatic as an SRAM macro — given generated .lib/.lef views under `$(RESULTS_DIR)/memories/`. Synthesis blackboxes those modules and all later stages read the generated views, so an existing design gets macro-based results without a memory compiler. Supported for the asap7 platform only. See docs/user/AutoMemories.md.| 0|
| <a name="AUTO_MEMORIES"></a>AUTO_MEMORIES| Experimental. When set to 1, memories that yosys infers in the RTL (`$mem_v2` cells, module boundary only) are detected pre-synthesis, inventoried in `$(RESULTS_DIR)/memories.json`, and — when idiomatic as an SRAM macro — given generated .lib/.lef views under `$(RESULTS_DIR)/memories/`. Synthesis blackboxes those modules and all later stages read the generated views, so an existing design gets macro-based results without a memory compiler. Supported for the asap7 platform only. See docs/user/AutoMemories.md.| 0|
| <a name="BALANCE_ROWS"></a>BALANCE_ROWS| Balance rows during placement.| 0|
| <a name="BLOCKS"></a>BLOCKS| Blocks used as hard macros in a hierarchical flow. Do note that you have to specify block-specific inputs file in the directory mentioned by Makefile.| |
| <a name="BUFFER_PORTS_ARGS"></a>BUFFER_PORTS_ARGS| Specify arguments to the buffer_ports call during placement. Only used if DONT_BUFFER_PORTS=0.| |
Expand Down
1 change: 0 additions & 1 deletion flow/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -285,7 +285,6 @@ do-auto-memories: $(RESULTS_DIR)/memories_inferred.json
--yosys-json $(RESULTS_DIR)/memories_inferred.json \
--out-dir $(RESULTS_DIR)/memories \
--json $(RESULTS_DIR)/memories.json \
$(foreach file,$(VERILOG_FILES),--verilog $(file)) \
$(foreach file,$(ADDITIONAL_MEMORIES),--memories $(file))

$(RESULTS_DIR)/memories.json: $(RESULTS_DIR)/memories_inferred.json $(ADDITIONAL_MEMORIES) \
Expand Down
14 changes: 1 addition & 13 deletions flow/scripts/memories/detect.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,7 @@ def parse_param_int(val) -> int:
def scan_yosys_json(data: dict | str | Path) -> list[schema.Memory]:
"""Extract memory modules from a Yosys netlist JSON output ($mem_v2 cells)."""
if isinstance(data, (str, Path)):
p = Path(data)
if not p.is_file():
return []
data = json.loads(p.read_text())
data = json.loads(Path(data).read_text())
Comment thread
oharboe marked this conversation as resolved.
Resolved

out: list[schema.Memory] = []
modules = data.get("modules", {})
Expand Down Expand Up @@ -176,12 +173,3 @@ def scan_yosys_json(data: dict | str | Path) -> list[schema.Memory]:
out.append(mem)

return out


def scan_files(paths: list[Path]) -> list[schema.Memory]:
"""Scan Yosys netlist JSON files; later definitions of a name win."""
found: dict[str, schema.Memory] = {}
for path in paths:
for memory in scan_yosys_json(path):
found[memory.name] = memory
return list(found.values())
25 changes: 7 additions & 18 deletions flow/scripts/memories/gen_memories.py
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
#!/usr/bin/env python3
"""AUTO_MEMORIES driver: detect memories, judge them, emit macro views.

Run pre-synthesis (before canonicalization). Scans the design's Verilog
for memory-shaped modules, merges user-supplied `.memories` files
Run pre-synthesis (before canonicalization). Reads the netlist JSON
that extract_memories.tcl writes after yosys `proc; memory -nomap`,
collects its $mem_v2 cells, merges user-supplied `.memories` files
(ADDITIONAL_MEMORIES), applies the idiomatic-macro gate, then writes:

<json> full inventory, converted or not (memories.json)
Expand Down Expand Up @@ -45,21 +46,17 @@ def find_fakeram_run() -> str | None:


def run(
verilog: list[Path],
yosys_json: Path,
memories_files: list[Path],
platform: str,
out_dir: Path,
json_path: Path,
yosys_json: Path | None = None,
) -> int:
if platform != "asap7":
sys.stderr.write(f"gen_memories: unsupported platform {platform}\n")
return 1

if yosys_json and yosys_json.is_file():
found = detect.scan_yosys_json(yosys_json)
else:
found = detect.scan_files(verilog)
found = detect.scan_yosys_json(yosys_json)

idiomatic.apply(found)

Expand Down Expand Up @@ -108,17 +105,10 @@ def run(

def main(argv: list[str] | None = None) -> int:
p = argparse.ArgumentParser(description=__doc__)
p.add_argument(
"--verilog",
action="append",
default=[],
type=Path,
help="Verilog source file to scan (repeatable).",
)
p.add_argument(
"--yosys-json",
required=True,
type=Path,
default=None,
help="Yosys netlist JSON file containing $mem_v2 primitives.",
)
p.add_argument(
Expand All @@ -144,12 +134,11 @@ def main(argv: list[str] | None = None) -> int:
)
args = p.parse_args(argv)
return run(
args.verilog,
args.yosys_json,
args.memories,
args.platform,
args.out_dir,
args.json,
args.yosys_json,
)


Expand Down
16 changes: 16 additions & 0 deletions flow/scripts/memories/gen_memories_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,22 @@ def test_bad_memories_file_fails(self):
with self.assertRaises(json.JSONDecodeError):
self.run_generator(memories_files=[bad])

def test_missing_yosys_json_fails(self):
d = Path(self.tmp.name)
with self.assertRaises(FileNotFoundError):
gen_memories.main(
[
"--platform",
"asap7",
"--out-dir",
str(d / "memories"),
"--json",
str(d / "memories.json"),
"--yosys-json",
str(d / "missing.json"),
]
)

def test_no_memories_still_writes_contract_files(self):
d = Path(self.tmp.name)
empty_netlist = d / "empty.json"
Expand Down
2 changes: 1 addition & 1 deletion flow/scripts/variables.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions flow/scripts/variables.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -192,9 +192,9 @@ SYNTH_USE_SYN:
default: 0
AUTO_MEMORIES:
description: >
Experimental. When set to 1, memory-shaped modules in the RTL
(firtool/CIRCT `R*/W*/RW*_` port convention, module boundary only)
are detected pre-synthesis, inventoried in
Experimental. When set to 1, memories that yosys infers in the RTL
(`$mem_v2` cells, module boundary only) are detected
pre-synthesis, inventoried in
`$(RESULTS_DIR)/memories.json`, and — when idiomatic as an SRAM
macro — given generated .lib/.lef views under
`$(RESULTS_DIR)/memories/`. Synthesis blackboxes those modules and
Expand Down
Loading