An open-source on-chip interconnect generator.
NocLoom is a command-line tool (CLI) and a C++20 library. Define AXI4, AXI3, AXI4-Lite, APB, AHB-Lite, AHB5, Wishbone and TileLink networks in YAML or C++. NocLoom generates synthesizable Verilog-2001 with switches, protocol adapters, width converters and clock domain crossings (CDC).
NocLoom 0.4.0 is the latest release.
See soc_mixed.yaml for this network.
Run from the repository root. The build needs CMake, Ninja, a C++20 compiler, nlohmann_json, yaml-cpp and CLI11. Ubuntu 24.04, Debian 13 and Fedora 43 have suitable packages. See build requirements for versions and install commands.
cmake -S . -B build -G Ninja -DNOCLOOM_BUILD_TESTS=OFF -DNOCLOOM_BUILD_EXAMPLES=OFF
cmake --build buildTo install the library and the CLI, run
cmake --install build --prefix "$PWD/build/install", or name another prefix.
See Build and install.
Write this definition to build/soc_fabric.yaml. An initiator connects to an
external bus manager, and a target connects to an external bus subordinate.
schema_version: 10
name: soc_fabric
address_width: 32
reset_ports: [{name: reset_n}]
test_ports: [{name: test}]
clock_domains: [{name: main, clock_port: clk_main, reset_port: reset_n, test_port: test}]
initiators:
- {name: cpu, clock_domain: main, protocol: axi4, data_width: 64, len_width: 8}
- {name: dbg, clock_domain: main, protocol: axi4_lite, data_width: 32}
targets:
- {name: mem, clock_domain: main, protocol: axi4, data_width: 32, len_width: 8,
attributes: amba, mappings: [{base: '0x0', size: '0x10000'}]}
- {name: uart, clock_domain: main, protocol: apb4, data_width: 32, attributes: amba,
mappings: [{base: '0x10000', size: '0x1000'}]}
connectivity:
cpu: [mem, uart]
dbg: [uart]
output: {backend: verilog, language: verilog_2001}The cpu initiator is 64 bits wide and the mem target is 32 bits wide, so the
network converts the data width. The network also converts AXI4 and AXI4-Lite
requests to APB for uart.
| Field | Meaning |
|---|---|
schema_version |
The schema version must be 10 |
reset_ports |
reset_n is the active-low reset input of the network |
test_ports |
test is an input that opens the clock gates during testing. Domains have clock gates by default |
id_width |
The example does not set it. The AXI ID ports then have the default width of 4 bits |
len_width |
The width of the AxLEN ports. The default is 4 bits. A standard AXI4 port has 8 bits |
attributes |
axi4, axi3, axi4_lite, apb5, apb4, ahb_v3 and ahb5 targets must set it. With amba, the CACHE, PROT or HPROT outputs of the target follow the Arm® AMBA® attributes of the request. AHB5 requires amba. Other targets can use zero for constant outputs |
Validate the definition. Then generate the output files into a new directory.
build/nocloom validate build/soc_fabric.yaml
build/nocloom generate build/soc_fabric.yaml --out-dir build/generatedvalidate prints Definition is valid. generate prints Generated 6 files.
If the output directory exists, generate stops with NCL_IO_EXISTS and exit
code 3. Remove that directory or use another one. See
CLI for the output path rules.
Top module nocloom_soc_fabric is in build/generated/nocloom_soc_fabric.v.
Simulation also needs nocloom_clock_gate.v and nocloom_synchronizer.v from
that directory. Initiator ports have names such as nl_i_cpu_awaddr, and target
ports have names such as nl_t_mem_awaddr.
More definitions are in examples. Start with apb_domains.yaml for
two clock domains and axi4_graph.yaml for a declared topology.
wishbone_registered_feedback.yaml shows a Wishbone target with burst tags.
tilelink_uh_target.yaml shows a TL-UH target with three packet contexts.
The bundle nocloom_<name>.bundle.json lists the output files. Compile its
simulation_sources for simulation and its synthesis_sources for synthesis.
See Output files for each output file and its metadata.
Without cells bindings, both lists contain behavioral models of the clock gate
and the synchronizer. These models are for simulation only. For synthesis, bind
the cells of your technology library as
Technology cells describes. A simulation with bound
cells also needs the library_cell_models of the bundle or the models of your
library.
Top-level clock_gating: none removes clock gates and keeps synchronizers.
For an FPGA, set it because the behavioral clock gate model contains a latch.
The flat top module contains only clock gate and synchronizer instances. Its
internal signals use nl_internal_v<N>. To find the signals of an endpoint or
switch, read the map. value/<N> in the map is the signal nl_internal_v<N>,
except for a stage inside a synchronizer. For example, network.storage lists
the signals of each resource, such as source/cpu/pipe/aw. See
Map fields.
With its default warning settings, Verilator reports CMPCONST and UNSIGNED
warnings for most generated networks and exits with a nonzero code. Add
-Wno-CMPCONST -Wno-UNSIGNED to the Verilator command.
For clock domain crossings, use generate --cdc-constraints and apply the
CDC constraints.
The external managers and subordinates must meet the progress requirements. A manager must deliver every W beat of a write it started and accept R beats in finite time. A violation can stop the network until reset.
Reset all domains together. If you reset one domain alone, make sure that no traffic crosses its boundary.
| Area | Supported |
|---|---|
| Initiator protocols | axi4, axi3, axi4_lite, apb5, apb4, apb3, ahb_v3 (AHB-Lite), ahb5, wishbone, tl_ul and tl_uh |
| Target protocols | axi4, axi3, axi4_lite, apb5, apb4, apb3, apb2, ahb_v3 (AHB-Lite), ahb5, wishbone, tl_ul and tl_uh |
| Wishbone cycles | 32-bit classic and pipelined reads and writes, byte SEL, ERR, optional target RTY as error, explicit byte or word addresses. Classic targets can send registered feedback bursts with CTI and BTE. Classic initiators accept these ports and ignore their values |
| TileLink | TL-UL initiators and targets: 32-bit single-beat Get, PutFullData and PutPartialData, with AccessAck and AccessAckData. TL-UL initiators can keep multiple sources in flight. TL-UH initiators and targets: multibeat Get and Put of up to 4096 bytes. Initiators complete Intent locally. Targets share 1 to 16 packet contexts between reads and writes |
| AHB5 properties | HPROT is 4 bits by default or 7 bits. HNONSEC is optional and defaults to absent. HMASTER is 0 to 32 bits |
| Endpoint count | 1 to 256 initiators, 1 to 256 targets |
| Topology | One generated request switch and one generated response switch, or declared request and response graphs of 1 to 128 switches each |
| Endpoint data width | AXI4, AXI3, AHB-Lite and AHB5: 32, 64, 128, 256, 512 or 1024 bits. AXI4-Lite: 32 or 64 bits. APB: 8, 16 or 32 bits. Wishbone and TileLink: 32 bits |
| Network data width | 32 or 64 bits (transport.data_width). The default is the narrowest endpoint data width, where APB counts as 32 bits and the maximum is 64 bits. A 64-bit network accepts only 64-bit initiators, and no APB, Wishbone or TileLink endpoint or AHB target. Other definitions need a 32-bit network. Therefore, an initiator wider than 64 bits needs transport.data_width: 32, unless a 32-bit or APB endpoint already makes 32 bits the default |
| Address width | 2 to 48 bits. AXI4, AXI3, AHB and Wishbone initiators need at least 12 bits. TL-UH initiators need at least log2(max_transfer_bytes) bits. APB initiators use at most 32 bits. APB, AHB, Wishbone, TileLink and AXI4-Lite targets use at most 32 bits |
| Clock domains | 1 to 64. More than one domain needs a topology whose switches name their clock domains. Clock domain crossings connect asynchronous clocks, or related clocks divided from one root |
| Endpoint clock gating | Separate protocol and transport gates, one shared gate, or a transport gate with the protocol side on the domain clock |
| Transactions | Several AXI transactions in flight, exclusive access, target timeouts and an error response on a decode miss |
| Scheduling | Fixed levels from 0 to 7 on AXI4, AXI3, AHB-Lite and AHB5 sources to full AXI4 or AXI3 targets, or on 32-bit APB networks. AXI4 and AXI3 sources also support AxQOS maps. AXI4, AXI3 and 32-bit APB sources support bandwidth limits |
| Routing | NocLoom fixes each route at generation |
| Output files | Always: Verilog-2001 RTL and three JSON files, which are the map, the bundle and the dependency graph. Optional: IP-XACT (--ipxact), address table (--address-table), CDC constraints (--cdc-constraints) and C headers (--c-header) |
| C++ library | In-memory generation, tree and mesh topology helpers, and a CMake package. The core library does no file I/O and prints nothing |
See Documentation for field definitions and limits.
| Not supported | Detail |
|---|---|
| Wishbone options | No LOCK or user tags. Burst tags require classic cycles. A tagged target cannot use timeout. Pipelined targets accept one request at a time. See Wishbone |
| Other protocols | For example AXI5, ACE and APB2 initiators |
| TileLink | TL-UL targets support one message in flight and one flow. TL-UH targets support 1 to 16 packet contexts and one flow. Coherent channels are unsupported. TL-UH initiators deny atomic operations, so they do not conform to TL-UH. See TileLink for error and progress rules |
| AHB5 optional signals | HEXCL, HEXOKAY and HAUSER, HWUSER, HRUSER and HBUSER are unsupported. See AHB5 properties |
| AHB arbitration and responses | No multi-manager arbitration or HSPLIT. RETRY and SPLIT on two-bit ahb_v3 targets fail the packet |
| Other RTL languages | The output is Verilog-2001 only |
| Adaptive routing | A route does not change with the load |
| Source flow admission | Within one 4 KiB page, each flow of an initiator that reaches a sub-page routing window must reach all such windows of the initiator. The flow need not reach windows of the initiator's default target. This rule applies to AXI4 and AXI3 initiators with max_outstanding above 1. See Address map |
| Scheduling | Nonzero levels exclude AHB targets, other mixed protocol networks, exclusive access, target timeouts and targets wider than the network. AXI graphs also exclude one-direction endpoints. AHB sources have no AxQOS map, shaper or scheduler |
| APB5 optional signals | PWAKEUP, parity check signals and RME PNSE are unsupported. PAUSER, PBUSER and per-byte PWUSER and PRUSER groups of 1 to 4 bits are supported |
| AxREGION | AXI endpoints have no AxREGION ports |
| AXI3 locked writes and write data interleaving | An AXI3 target receives neither |
| Unchanged non-modifiable narrow bursts | With the default narrow_bursts: merge, an AXI target that is wider than the beats of a burst merges them regardless of AxCACHE. This can change non-modifiable transactions beyond the transformations that AXI A4.3 permits. See width transformation details |
The CLI rejects an invalid definition before it writes files. It reports a field path, a message, the file line and column when known, and a diagnostic code.
| Manual | Content |
|---|---|
| Definition | Top-level fields, YAML shorthand, C++ types and value limits |
| Clocks and resets | Domains, resets, gates, cells, crossings and CDC constraints |
| Network | Connectivity, graphs, routes, flows, arbitration and pipes |
| Address map | Mappings, address inputs, decode misses and error responses |
| Protocols | Initiator and target protocols, width conversion and packets |
| TileLink | TL-UL and TL-UH endpoint fields, error and progress rules, option table and protocol mappings |
| Transactions | Bursts in flight, target IDs, read interleaving, exclusive access and timeouts |
| Scheduling | Levels, AxQOS maps, bandwidth shapers and bandwidth schedulers |
| Output files | Map, bundle, dependency graph, IP-XACT, address table, CDC constraints and C headers |
| C headers | Address and error log register macros |
| Error logging | Register windows, capture, filters and alarms |
| Library | Build requirements, CMake packages, C++ API, tree and mesh topology helpers |
| CLI | Validation, generation, semantic diff and exit codes |
| Diagnostics | Diagnostic codes and the conditions that produce them |
Tests also need Catch2, Python 3, Make, Icarus Verilog, Yosys, Verilator,
clang-format, cppcheck and a second C++20 compiler. A test builds the CLI with
that compiler and compares outputs. Set -DNOCLOOM_DETERMINISM_COMPILERS=OFF
to omit the test and its compiler requirement.
cmake -S . -B build -G Ninja -DNOCLOOM_BUILD_TESTS=ON -DNOCLOOM_BUILD_EXAMPLES=ON
cmake --build build
ctest --test-dir build -L quick --output-on-failure
cmake --build build --target clang-format
cmake --build build --target cppcheckThe quick label selects a short subset of the tests. The ci label selects
the sample that the Build workflow runs. ctest --test-dir build runs all
tests. The tests with the formal label also need SymbiYosys (sby) with the
Z3 solver, and Lean 4.24.0 with lake. The clang-format target reformats the
sources in place.
tests/SUITES.md describes the daily and the full test runs and their resource limits. The suite runner plans 8 GiB of memory for each test slot and keeps 16 GiB or more free. tests/VERIFICATION_POLICY.md describes which tests a change needs, and formal/lean/README.md describes the Lean model of the transport and its theorems.
Commit messages follow
Conventional Commits. Add a
Signed-off-by line to each commit with git commit -s. This line states that
you agree to the
Developer Certificate of Origin.
Contributions are licensed under the Apache License 2.0. A contribution to the content that NocLoom supplies in the output files is also licensed under the NocLoom Output Permission 1.0.
The generator is under the Apache License 2.0. The content that NocLoom supplies in the output files is under the NocLoom Output Permission 1.0. That permission lets you use, modify and distribute the content under terms of your choice, without attribution or notices.
Dependency licenses and trademark notices are in Attribution.