Skip to content
vowstarPublic

About

An open-source on-chip interconnect generator.

Resources

Stars

7 stars

Watchers

0 watching

Forks

Repository files navigation

NocLoom

NocLoom. Weave your interconnect.

Build

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.

A mixed-protocol SoC network with two clock domains.

See soc_mixed.yaml for this network.

A 4x4 mesh network from a declared graph and explicit routes.

Quick start

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 build

To 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/generated

validate 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.

Integration

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.

Features

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.

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.

Documentation

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

Development

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 cppcheck

The 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.

License

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.

About

An open-source on-chip interconnect generator.

Resources

Stars

7 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages