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
27 changes: 15 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@
An open-source on-chip interconnect generator.

NocLoom is a command-line tool (CLI) and a C++20 library. You define a network
of AXI4, AXI3, AXI4-Lite, APB and AHB-Lite interfaces in YAML or C++. NocLoom
generates synthesizable Verilog-2001 with switches, protocol adapters, width
converters and clock domain crossings (CDC).
of AXI4, AXI3, AXI4-Lite, APB, AHB-Lite and AHB5 interfaces in YAML or C++.
NocLoom generates synthesizable Verilog-2001 with switches, protocol adapters,
width converters and clock domain crossings (CDC).

NocLoom 0.1.0 is the first public release.

Expand Down Expand Up @@ -72,7 +72,7 @@ requests to APB for `uart`.
| `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`, `apb4` and `ahb_v3` targets must set it. With `amba`, the CACHE, PROT or HPROT outputs of the target follow the Arm® AMBA® attributes of the request. With `zero`, these outputs are constants |
| `attributes` | `axi4`, `axi3`, `axi4_lite`, `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.

Expand Down Expand Up @@ -141,30 +141,33 @@ traffic crosses its boundary.

| Area | Supported |
| --- | --- |
| Initiator protocols | `axi4`, `axi3`, `axi4_lite`, `apb4`, `apb3` and `ahb_v3` (AHB-Lite) |
| Target protocols | `axi4`, `axi3`, `axi4_lite`, `apb4`, `apb3`, `apb2` and `ahb_v3` (AHB-Lite) |
| Initiator protocols | `axi4`, `axi3`, `axi4_lite`, `apb4`, `apb3`, `ahb_v3` (AHB-Lite) and `ahb5` |
| Target protocols | `axi4`, `axi3`, `axi4_lite`, `apb4`, `apb3`, `apb2`, `ahb_v3` (AHB-Lite) and `ahb5` |
| 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 and AHB-Lite: 32, 64, 128, 256, 512 or 1024 bits. AXI4-Lite: 32 or 64 bits. APB: 8, 16 or 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 endpoint or AHB-Lite 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 and AHB-Lite initiators need at least 12 bits. APB initiators use at most 32 bits. APB, AHB-Lite and AXI4-Lite targets use at most 32 bits |
| 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 |
| 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 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 and AHB initiators need at least 12 bits. APB initiators use at most 32 bits. APB, AHB 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 |
| Transactions | Several AXI transactions in flight, exclusive access, target timeouts and an error response on a decode miss |
| Scheduling | AxQOS levels and bandwidth limits. Scheduling needs a network of only AXI4 and AXI3 endpoints, or of only 32-bit APB endpoints. It excludes exclusive access, target timeouts and targets wider than the network |
| 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](#documentation) for the definition fields and their value
limits.
See [Documentation](#documentation) for field definitions and limits.

## Limits

| Not supported | Detail |
| --- | --- |
| Other protocols | For example AXI5, ACE and APB2 initiators |
| AHB5 optional signals | HEXCL, HEXOKAY and HAUSER, HWUSER, HRUSER and HBUSER are unsupported. See [AHB5 properties](docs/ahb.md#ahb5-basic-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 |
| 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 |
| 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](docs/width-conversion.md#width-transformation-details) |
Expand Down
100 changes: 89 additions & 11 deletions docs/ahb.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# AHB-Lite
# AHB-Lite and AHB5

## AHB-Lite initiators

Expand Down Expand Up @@ -40,17 +40,24 @@ in its first data phase until the network accepts it. Ending an undefined INCR
waits only for its committed transfer before starting another data phase. HRDATA
is valid only on successful read completion.

HPROT bits 3:2 become AxCACHE bits 1:0. HPROT bit 1 becomes AxPROT bit 0.
Inverted HPROT bit 0 becomes AxPROT bit 2, and AxPROT bit 1 is set. AxID and
AxLOCK are zero. A request waits for earlier write responses, so reads observe
earlier bufferable writes.
With target `attributes: amba`, HPROT bits 3:2 select the cache values below.

| HPROT[3:2] | ARCACHE | AWCACHE |
| --- | --- | --- |
| `00` | `0000` | `0000` |
| `01` | `0001` | `0001` |
| `10` | `1010` | `0110` |
| `11` | `1011` | `0111` |

AxPROT is `{~HPROT[0], 1, HPROT[1]}`. AxID and AxLOCK are zero. A request
waits for earlier write responses, so reads observe earlier bufferable writes.

Bufferable writes never report target errors. Other writes report the piece's
accumulated error on its last beat only. Holding BUSY inside a write holds its
request path.

An AHB initiator rejects pair packet-limit overrides and any capacity above one.
It has no AHB5 exclusive, security, manager-ID or user signals. Common reset
An `ahb_v3` initiator has no AHB5 security or manager-ID ports. Common reset
cancels its burst, and the external manager must restart it.

## Dedicated AHB targets
Expand Down Expand Up @@ -83,10 +90,10 @@ HREADYOUT, HRDATA and HRESP using the accepted address phase. Feed the selected
response into the network and distribute `hready` to every slave.

With multiple target flows, the adapter selects `hreadyout_<flow>` for the
current data-phase flow. It records that flow when its address phase is accepted.
It broadcasts the selected ready value on every `hready_<flow>`.
current data-phase flow. It records that flow when its address phase is
accepted. It broadcasts the selected ready value on every `hready_<flow>`.
With no data-phase flow selected, the selected ready value is high.
The `hready` outputs are zero during reset.
During common reset, `hready` follows HREADYOUT and HTRANS is IDLE.

These connections follow the slave and multiplexor signals in
[AMBA 3 AHB-Lite, IHI 0033A, sections 2.3 and 2.5](https://documentation-service.arm.com/static/5f914801f86e16515cdc2a27).
Expand Down Expand Up @@ -158,8 +165,8 @@ responses already offered and returns zero data with errors for the remaining
words of that packet. Other packets keep their results. A cancelled address of
another packet restarts with NONSEQ.

Use two-cycle responses. HMASTER, HSPLIT and full RETRY/SPLIT arbitration are
unsupported.
Use two-cycle responses. An `ahb_v3` target has no HMASTER port. HSPLIT and
full RETRY/SPLIT arbitration are unsupported.

ERROR becomes SLVERR. Remaining burst transfers continue and side effects are
not rolled back. The outgoing HPROT low bit is inverted instruction, bit 1
Expand All @@ -169,3 +176,74 @@ use the same merging and clamping rules as AXI, with at most 16 words and 1 KiB
per packet.

A FIXED beat wider than the target fails even with `fixed_bursts: single`.

## AHB5 basic properties

Set `protocol: ahb5` on either endpoint. AHB5 follows the transfer, burst,
wait, ordering and two-cycle ERROR rules on this page. Targets require
`attributes: amba` and one-bit HRESP.

| Field in the optional `ahb5` object | Values | Default |
| --- | --- | --- |
| `hprot_width` | 4 or 7 bits | 4 |
| `hnonsec` | Boolean, includes HNONSEC when true | `false` |
| `hmaster_width` | 0 to 32 bits | 0, no HMASTER port |
| `exclusive` | `false` only | `false` |
| `hauser_width`, `hwuser_width`, `hruser_width`, `hbuser_width` | 0 only | 0 |

Other protocols reject the object. Unsupported values and per-bit attribute
maps produce `NCL_AHB5_PROPERTIES`. HEXCL, HEXOKAY and user ports are absent.
HMASTLOCK returns ERROR without target access. Multi-manager arbitration,
HSPLIT and full RETRY/SPLIT are unsupported.

HMASTER is an initiator input and a target output, preserved through packet
splitting, width conversion and clock crossings. A nonzero target width must
hold all reaching initiator values, with zero extension where needed.
Endpoints with width zero omit the port, and sources without HMASTER supply
zero. HMASTER does not select routes or arbitration and does not use AXI IDs.

HNONSEC is an initiator input and a target output. It maps to AxPROT[1],
with 0 for Secure and 1 for Non-secure. AHB sources without an HNONSEC input
supply 1. AXI sources supply AxPROT[1].

AHB5 pairs preserve HPROT. Four-bit sources extend HPROT[4] from HPROT[3]
and set HPROT[6:5] to zero. Four-bit targets use the low four bits.

| Attribute | AHB to AXI4 | AXI4 to AHB5 |
| --- | --- | --- |
| HPROT[0], Data | Invert into AxPROT[2] | Invert AxPROT[2] |
| HPROT[1], Privileged | AxPROT[0] | AxPROT[0] |
| HPROT[2], Bufferable | AxCACHE[0] | AxCACHE[0]. Seven-bit targets use zero for AxCACHE `0011` |
| HPROT[3], Modifiable | AxCACHE[1] | AxCACHE[1] |
| HPROT[4], Lookup | ARCACHE[3], AWCACHE[2] | AxCACHE[2] OR AxCACHE[3] |
| HPROT[5], Allocate | ARCACHE[2], AWCACHE[3] | ARCACHE[2] on reads, AWCACHE[3] on writes |
| HPROT[6], Shareable | No AXI4 port | Zero |

For four-bit AHB, Lookup follows HPROT[3] and Allocate is zero.
Seven-bit HPROT[6:2] permits only the memory types below. Other encodings
must not be driven. Shareable writes wait for target completion and errors.

| Memory type | HPROT[6:2] (decimal) |
| --- | --- |
| Device without early response | 0 |
| Device with early response | 1 |
| Normal non-cacheable | 2, 18 |
| Write-through | 6, 14, 22, 30 |
| Write-back | 7, 15, 23, 31 |

On seven-bit targets, AxCACHE `0011` maps to Normal non-cacheable.
With AxPROT `000`, it gives HPROT `0001001`. Four-bit targets map
AxCACHE[1:0] directly to HPROT[3:2], giving `1101` for that request.
Reads use ARCACHE and ARPROT. Writes use AWCACHE and AWPROT.

The map records the endpoint protocol as `ahb5`. Under
`definition.ahb5_properties`, `initiators` and `targets` list each endpoint's
`hprot_width`, `hnonsec` and `hmaster_width` by name.
IP-XACT uses the AMBA3 AHBLite subset and maps four-bit HPROT on the bus.
Seven-bit HPROT, HNONSEC and HMASTER are plain model ports outside that mapping.

The rules follow [AMBA AHB, IHI 0033C, sections 3.8 to 3.10][ahb5-spec]
and [AMBA AXI, IHI 0022E, table A4-5][axi-memory].

[ahb5-spec]: https://documentation-service.arm.com/static/6141bf0d674a052ae36ca811
[axi-memory]: https://documentation-service.arm.com/static/5f915b62f86e16515cdc3b1c
21 changes: 20 additions & 1 deletion docs/definition.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Use YAML or C++ `nocloom::Definition`. Both use the same validator.
| --- | --- |
| Schema | `schema_version: 10` is required |
| Names | Names start with a letter and contain only letters, digits and underscores, with at most 128 characters. Names cannot start with `nl_` or `nocloom_` and cannot be a Verilog-2001 keyword. Names within one kind are unique |
| Required endpoint fields | `name`, `clock_domain`, `protocol`, `data_width`. Targets also need `mappings`. `axi4`, `axi3`, `axi4_lite`, `apb4` and `ahb_v3` targets also need `attributes` |
| Required endpoint fields | `name`, `clock_domain`, `protocol`, `data_width`. Targets also need `mappings`. `axi4`, `axi3`, `axi4_lite`, `apb4`, `ahb_v3` and `ahb5` targets also need `attributes` |
| Unknown fields | The YAML parser rejects unknown fields with `NCL_SCHEMA_UNKNOWN_FIELD` |
| Duplicate YAML keys | The YAML parser rejects duplicate keys |
| Integers | Unquoted decimal integers without leading zeros, such as `64`. Other forms produce `NCL_SCHEMA_TYPE` |
Expand Down Expand Up @@ -92,6 +92,25 @@ Verilog-2001 and asynchronous reset.

CLI switches select optional output files. See [output files](outputs.md).

## AHB5 endpoint fields

`protocol: ahb5` has four-bit HPROT by default. The optional `ahb5` object
accepts `hprot_width: 4` or `7`, `hnonsec: false` or `true`, and
`hmaster_width` from 0 to 32. HNONSEC defaults to false and HMASTER width to
zero. The object also accepts `exclusive: false`
and zero `hauser_width`, `hwuser_width`, `hruser_width` and `hbuser_width`.
Other values produce `NCL_AHB5_PROPERTIES`. The object is rejected on other
protocols, including explicit defaults.

AHB5 targets require `attributes: amba` and `hresp_width: 1`, or an omitted
`hresp_width`. See [AHB5 basic properties](ahb.md#ahb5-basic-properties).
C++ endpoints use `Protocol::Ahb5` and optional `Ahb5Properties ahb5`.

```yaml
protocol: ahb5
ahb5: {hprot_width: 7, hnonsec: true, hmaster_width: 32}
```

## Endpoint templates

A template contains endpoint fields under `templates.initiators` or
Expand Down
5 changes: 3 additions & 2 deletions docs/diagnostics.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,8 @@ The codes of the C++ tree helper are in
| `NCL_AXI4_TRANSPORT_WORD` | `transport_word_bytes` is not 4, 8, 16 or 32 |
| `NCL_TARGET_TIMEOUT` | `timeout.cycles` is not a power of two from 16 to 1048576, or the target protocol has no timeout |
| `NCL_TARGET_APB_ACCESS`, `NCL_TARGET_FIXED_BURSTS` | Back-to-back access on a target that is not APB, or an invalid `fixed_bursts` value |
| `NCL_TARGET_AHB_BURSTS`, `NCL_TARGET_AHB_HRESP` | Burst shaping or `hresp_width` on a target that is not `ahb_v3`, or an invalid value |
| `NCL_AHB5_PROPERTIES` | The `ahb5` object requires AHB5. HPROT width must be 4 or 7. HMASTER width must be 0 to 32. A nonzero target width must hold each reaching source. Exclusive and user signals are unsupported. Targets accept only `attributes: amba`, without per-bit overrides |
| `NCL_TARGET_AHB_BURSTS`, `NCL_TARGET_AHB_HRESP` | Burst shaping or `hresp_width` on a target that is not AHB, an invalid value, or two-bit HRESP on AHB5 |
| `NCL_ENDPOINT_ACCESS` | `access` is not `read_write`, `read_only` or `write_only` |
| `NCL_APB_INITIATOR`, `NCL_AHB_INITIATOR` | Unsupported options on a dedicated initiator |
| `NCL_UNSUPPORTED_PROTOCOL` | Unsupported protocol or endpoint role |
Expand Down Expand Up @@ -128,7 +129,7 @@ See [address maps](address-map.md) and [definition shorthand](definition.md).
| `NCL_CDC_EDGE_ALIGNED_RELATION` | Missing fixed-ratio ancestry or integer edge ratio |
| `NCL_QOS_LEVEL`, `NCL_QOS_MAP` | Invalid fixed level or AxQOS map, or incompatible initiator options |
| `NCL_QOS_SHAPER`, `NCL_QOS_SCHEDULER` | Invalid byte budgets, levels, threshold or required companion configuration |
| `NCL_QOS_PROFILE` | Unsupported endpoint, width, whole-burst or scheduler-pipe combination |
| `NCL_QOS_PROFILE` | Unsupported endpoint, width, whole-burst or scheduler-pipe combination. AHB sources accept fixed levels only, to full AXI targets when nonzero |

See [clocks and resets](clocks-and-resets.md) and [scheduling](scheduling.md).

Expand Down
6 changes: 5 additions & 1 deletion docs/protocols.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Byte lanes use little-endian ordering. The manuals use full AXI for AXI4 and
AXI3, and Lite for AXI4-Lite.

Related manuals: [AHB-Lite](ahb.md),
Related manuals: [AHB-Lite and AHB5](ahb.md),
[APB and AXI4-Lite targets](dedicated-targets.md),
[Widths and AXI target interfaces](width-conversion.md),
[Attributes and user signals](user-signals.md).
Expand All @@ -19,6 +19,7 @@ Related manuals: [AHB-Lite](ahb.md),
| `apb3` | Initiator or target | 8, 16, 32 |
| `apb2` | Target only | 8, 16, 32 |
| `ahb_v3` | AHB-Lite initiator or target | 32, 64, 128, 256, 512, 1024 |
| `ahb5` | AHB5 initiator or target with basic properties | 32, 64, 128, 256, 512, 1024 |

APB endpoints require a 32-bit network.

Expand All @@ -42,6 +43,9 @@ A target refuses the direction it does not support without bus access. Refused
writes return one error after consuming W. Refused reads return zero data and an
error on every beat.

AHB5 supports four-bit or seven-bit HPROT, optional HNONSEC and HMASTER. See
[AHB5 basic properties](ahb.md#ahb5-basic-properties) for mappings and limits.

## AXI4 initiators

| Field | Contract |
Expand Down
16 changes: 14 additions & 2 deletions docs/scheduling.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,21 @@ higher-level traffic can starve lower levels.

There is no global wait bound.

Scheduling requires either full AXI endpoints or 32-bit APB endpoints. It
excludes targets wider than the network, exclusives, target timeouts and
Nonzero levels support the following networks. All-zero fixed levels without
other scheduling options use the ordinary protocol capability checks.

| Sources | Targets | Scheduling options |
| --- | --- | --- |
| AXI4 and AXI3 | Full AXI4 or AXI3 | Fixed levels, AxQOS maps, shapers and schedulers |
| AHB-Lite and AHB5, also alongside AXI4 and AXI3 | Full AXI4 or AXI3 | Fixed read and write levels from 0 to 7 |
| 32-bit APB | 32-bit APB | Fixed levels, shapers and schedulers |

Nonzero levels exclude AHB targets, other mixed protocol networks, targets
wider than the network, exclusives and target timeouts. AXI graphs also exclude
one-direction endpoints.
AHB sources have no AWQOS or ARQOS ports and cannot set `qos.axqos_map`.
They cannot set `qos.shaper` or `qos.scheduler`. AHB5 HMASTER identifies a
manager and does not select a scheduling level.

## AxQOS maps

Expand Down
6 changes: 5 additions & 1 deletion docs/user-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@

## Target attributes

Targets with attribute signals declare `attributes: amba` or `attributes: zero`.
AHB5 targets require `attributes: amba`. Their HPROT and optional HNONSEC
follow the [AHB5 mappings](ahb.md#ahb5-basic-properties).

Other targets with attribute signals declare `attributes: amba` or
`attributes: zero`.
The object form maps `read_cache`, `write_cache`, `prot` and `hprot` bit by bit.
Bit lists run from least significant to most significant.

Expand Down
Loading