AXI4 Dialect

This dialect provides operations and types to describe AXI4 connections and networks.

Rationale ¶

Designing AXI networks can be high-effort and fraught with the risk of creating networks that allow for invalid requests. This dialect aims to provide a high-level representation of AXI networks that uses types and verifiers to catch cases where an invalid or non-compliant network has been specified.

This dialect is designed to target three primary use-cases:

• Using the AXI dialect (or more practically some front-end that compiles to it) as a high-level description language; Once you have RTL specifications of your endpoints, you can use the dialect or front-end to describe your desired network and lower to RTL to generate an implementation.
• Using the AXI dialect to abstractly model an architecture; the dialect is designed to allow a network to be specified without concrete RTL sources. This allows the dialect to be used to specify a network early in the design process and validate that it meets sanity checks and validation criteria. A later lowering could also use such a description to generate an interconnect-only RTL implementation with top-level ports corresponding to the abstract ports given in the model.
• Extracting existing full RTL models to the AXI dialect; from an RTL system design with a sufficiently identifiable structure for AXI interfaces, it would theoretically be possible to produce a higher-level description raised to the AXI dialect. This allows users with existing RTL to benefit from the static analysis provided by the dialect, along with other tooling as it develops.

Attributes ¶

BurstSetAttr ¶

Describes a non-empty set of burst specs supported by an endpoint

Syntax:

#axi4.burst_set<
  ::llvm::ArrayRef<::circt::axi4::BurstSpecAttr>   # burstSpecs
>

A non-empty set of burst specs, e.g. #axi4.burst_set<<fixed, len = 4>> or #axi4.burst_set<<fixed, len = 4>, <incr, len = 8>>.

To avoid functionally equivalent types (e.g. types containing burst_sets with the same specs in different orders) being structurally inequivalent, this is sorted on construction, with the specs of each kind merged into the longest of them.

Parameters: ¶

BurstSpecAttr ¶

Describes the burst capabilities of an endpoint

Syntax:

#axi4.burst_spec<
  `fixed` | `incr` | `wrap`,   # kind
  uint32_t   # len
>

Consists of a burst kind and a maximum burst length in beats, e.g. #axi4.burst_spec<fixed, len = 4> or #axi4.burst_spec<incr, len = 256>.

AXI4 permits 1-16 beats for fixed, 1-256 for incr, and only 2, 4, 8, or 16 for wrap.

Parameters: ¶

WindowAttr ¶

Describes an access window supported by an endpoint

Syntax:

#axi4.window<
  uint64_t,   # base
  uint64_t,   # last
  ::circt::axi4::BurstSetAttr   # burstSpecs
>

Consists of a base address, an inclusive last address, and the burst specs supported within the window, e.g. #axi4.window<base = 0x4000, last = 0x40ff, burst_specs = <<fixed, len = 4>>>.

Parameters: ¶

WindowSetAttr ¶

Describes a non-empty set of access windows supported by an endpoint

Syntax:

#axi4.window_set<
  ::llvm::ArrayRef<::circt::axi4::WindowAttr>   # windows
>

A non-empty set of access windows, e.g. #axi4.window_set<<base = 0x0, last = 0xff, burst_specs = <<fixed, len = 4>>>>.

The capabilities at an address are the union of those of every window covering it, so windows may overlap. To avoid functionally equivalent types being structurally unequal, the windows are normalized on construction into the maximal disjoint windows describing the same capabilities, sorted by base address. Gaps between windows are preserved.

Parameters: ¶

Enums ¶

BurstKind ¶

AXI4 burst kind

Cases: ¶

Types ¶

PortType ¶

An AXI4 port interface

Syntax:

!axi4.port<
  uint32_t,   # addr_width
  uint32_t,   # data_width
  uint32_t,   # write_id_width
  uint32_t,   # read_id_width
  uint32_t,   # user_width
  ::circt::axi4::WindowSetAttr,   # windows
  uint32_t,   # outstanding_writes
  uint32_t   # outstanding_reads
>

The primary interface passed between endpoints and interconnect primitives. Carries the address, data, write/read ID and user widths, the access windows the port supports, and the maximum outstanding writes and reads, e.g. !axi4.port<addr_width = 32, data_width = 64, write_id_width = 4, read_id_width = 4, user_width = 0, windows = <<base = 0x0, last = 0xfff, burst_specs = <<fixed, len = 4>>>>, outstanding_writes = 4, outstanding_reads = 4>.

The fields may be given in any order. AXI4 permits address widths up to 64 bits, data widths that are a power of two between 8 and 1024, and ID widths up to 32 bits. The outstanding request counts must not exceed the number of distinct IDs available.

Parameters: ¶

Operations ¶

axi4.abstract_manager (::circt::axi4::AbstractManagerOp) ¶

A stand-alone AXI4 manager endpoint

Syntax:

operation ::= `axi4.abstract_manager` $clock `,` $reset attr-dict `:` qualified(type($port))

Models a manager endpoint with no concrete implementation, for abstract network modelling. Returns the !axi4.port it drives.

Example:

%mgr = axi4.abstract_manager %clk, %rst_ni : !axi4.port<...>

Traits: PortResultsAtMostOneUse

Operands: ¶

Results: ¶

axi4.abstract_subordinate (::circt::axi4::AbstractSubordinateOp) ¶

A stand-alone AXI4 subordinate endpoint

Syntax:

operation ::= `axi4.abstract_subordinate` $clock `,` $reset `,` $upstream attr-dict `:` qualified(type($upstream))

Models a subordinate endpoint with no concrete implementation, for abstract network modelling. Takes the upstream !axi4.port it responds to.

Example:

axi4.abstract_subordinate %clk, %rst_ni, %mgr : !axi4.port<...>

Operands: ¶

axi4.channel_structs_to_port (::circt::axi4::ChannelStructsToPortOp) ¶

Converts a HW expression of an AXI4 interface to a port

Syntax:

operation ::= `axi4.channel_structs_to_port` $clock `,` $reset
              `aw` $aw `,` $aw_valid `w` $w `,` $w_valid `b` $b_ready
              `ar` $ar `,` $ar_valid `r` $r_ready
              attr-dict `:` qualified(type($port))

Bridges from a HW dialect expression of an AXI4 interface to an !axi4.port. Takes the AW, W and AR channel payloads and valids, and the B and R readys; returns the port along with the AW, W and AR readys and the B and R payloads and valids.

Example:

%port, %aw_ready, %w_ready, %b, %b_valid, %ar_ready, %r, %r_valid =
  axi4.channel_structs_to_port %clk, %rst_ni
    aw %aw, %aw_valid w %w, %w_valid b %b_ready
    ar %ar, %ar_valid r %r_ready
  : !axi4.port<...>

Traits: PortResultsAtMostOneUse

Operands: ¶

Results: ¶

axi4.port_to_channel_structs (::circt::axi4::PortToChannelStructsOp) ¶

Converts an AXI4 port to a HW expression of an AXI4 interface

Syntax:

operation ::= `axi4.port_to_channel_structs` $clock `,` $reset `,` $port
              `aw` $aw_ready `w` $w_ready `b` $b `,` $b_valid
              `ar` $ar_ready `r` $r `,` $r_valid
              attr-dict `:` qualified(type($port))

Bridges from an !axi4.port to a HW dialect expression of an AXI4 interface. Takes the port, the AW, W and AR channel readys, and the B and R payloads and valids; returns the AW, W and AR payloads and valids, and the B and R readys.

Example:

%aw, %aw_valid, %w, %w_valid, %b_ready, %ar, %ar_valid, %r_ready =
  axi4.port_to_channel_structs %clk, %rst_ni, %port
    aw %aw_ready w %w_ready b %b, %b_valid
    ar %ar_ready r %r, %r_valid
  : !axi4.port<...>

Operands: ¶

Results: ¶