How-to guides › Generate register maps

How-to guides

Register maps

A register map says where each hardware register of a part is, and what each of its bits means. archec gen --target regmap writes it from the part's memory blocks that have an address. It writes it once for each side that has to agree on it: the software that reads and writes the registers, the hardware that holds them, and the tools and documents in between. All of them come from the same blocks, so a change in the model is a change everywhere at once.

A first map#

enum TimerMode { ONE_SHOT, PERIODIC, PWM = 3 }

component Timer "Timer peripheral" {
  /// Control: start, mode and the interrupt enable.
  memory CTRL @ 0x4300_0000 : uint32 rw {
    enable:   bool bits "0"
    mode:     TimerMode = PERIODIC bits "2:1"
    prescale: uint8 = 4 bits "23:16"
  }
  memory STATUS @ 0x4300_0004 : uint32 r { running: bool bits "0" }
  memory COMPARE @ 0x4300_0010 : uint16[4] rw
  memory BUFFER @ 0x4300_0100 : uint32[128] rw
}
Diagram: Timer peripheral
What archec draws from this code: Timer peripheral
archec gen main.arche --target regmap -o generated
  generated/regmap/timer/timer_regs.h
  generated/regmap/timer/timer_regs.vhd
  generated/regmap/timer/timer_regs.sv
  generated/regmap/timer/timer.xml
  generated/regmap/timer/timer.rdl
  generated/regmap/timer/timer.md

The C header gives each field's position, and macros to read and write it:

#define TIMER_CTRL_MODE_SHIFT 1u
#define TIMER_CTRL_MODE_MASK 0x6u
#define TIMER_CTRL(base) (*TIMER_CTRL_PTR(base))
#define TIMER_COMPARE(base, i) (*TIMER_COMPARE_PTR(base, i))

timer.md is the map as a document:

Offset Address Block Access Size Reset In the bank Description
0x0000 0x43000000 CTRL rw 4 B 0x40002 register Control: start, mode and the interrupt enable.
0x0004 0x43000004 STATUS r 4 B 0x0 register
0x0010 0x43000010 COMPARE rw 4 × 2 B 0x0 register
0x0100 0x43000100 BUFFER rw 128 × 4 B 0x0 memory port

The files#

For each map, in regmap/<part>/:

File What it is
<part>_regs.h C, for C11 and C++ (see below).
<part>_regs.vhd VHDL-93: a package of the offsets and field positions, and the register bank, an AXI4-Lite slave.
<part>_regs.sv SystemVerilog: the same bank, port for port.
<part>.xml IP-XACT (IEEE 1685-2014): the memory map. It has the registers with their fields, resets, access and enumerated values. The memories are address blocks of their own.
<part>.rdl SystemRDL 2.0: the address map, for PeakRDL and the other RDL tools.
<part>.md The memory map as a document: a table of the blocks, then each block's fields.

The C header has:

  • the base, TIMER_BASE. You can define it before you include the header;
  • each block's offset, address, element size, count and reset;
  • each field's _SHIFT, _WIDTH, _MASK, _GET(v) and _SET(v, x);
  • the values of an enum field;
  • access macros that take a base pointer: TIMER_CTRL(base), TIMER_COMPARE(base, i). A read-only block is const volatile;
  • a struct of the whole map, to lay over the base;
  • static asserts that put each block of that struct at its offset.

A record of whole-byte fields is a struct of its own, and its size is asserted. A shared-memory block laid out byte by byte is an example.

A map is named after its part. When two parts have the same name, it is also named after the parts around them (kria_shm, kriakr260_shm). Its base is the first block's address, on a 4 KiB page. Offsets are from there.

The model#

  • A memory block is one element (: uint32) or several (: uint16[4], or count 80). It is at the address after @.
  • Its element has its type's size, or size bytes. A record of fields whose bits are all given is 4 bytes.
  • After the type, rw, r (ro) or w (wo) says who may read or write it on the bus. With no access, it is rw.
  • reset 0x… is the element's value at reset. A field's own value (mode: TimerMode = PERIODIC) goes over it.
  • A field is at bits "hi:lo", or bits "3" for one bit.
  • A field with no bits is the bytes after the field before it: its size, else its type's size. So a record laid out byte by byte, such as a shared memory, needs no bits.
  • A block with no address is not in the map. A note says so.

archec check warns about what would make two sides disagree:

Code When
memory-overlap two blocks of a part overlap
memory-misaligned a block of 2-, 4- or 8-byte elements is not on a multiple of its element size. A bus would read or write it in two accesses, not at once.
memory-field-width a field goes past the bits of one element, or is wider than its type (uint8 bits "15:4"), or its bits do not read as "hi:lo"
memory-field-overlap two fields share a bit

The bank#

The register bank is the hardware side: the registers in VHDL or SystemVerilog, behind a bus. The bus is AXI4-Lite.

Why AXI4-Lite rather than a simple generic bus? In practice, the parts that have register maps sit on a Zynq or a Kria. There the processor side (PS) reaches the programmable logic (PL) over AXI. Vivado's IP packager and its interconnects speak AXI, and so do the other FPGA vendors' tools. A generic bus would need a bridge written by hand on each side. AXI4-Lite is also small: one read and one write at a time, 32-bit data, byte strobes.

  • Each byte of each element is a byte lane of a 32-bit word. So 8-, 16-, 32- and 64-bit registers are written and read in the same way, packed together or not. WSTRB writes only the bytes it names.

  • rw: a register the bus writes and reads back, on <block>_o.

  • w: a register the bus writes and reads as 0, on <block>_o.

  • r: a value the hardware drives on <block>_i. Writes are ignored.

  • A writable block has a write strobe per element, <block>_wr. It is high for one cycle after a write to the element.

  • A block of more than 16 elements, or of elements larger than 8 bytes, is a memory, not registers. The bank decodes its range and hands each access to a port of its own, as a synchronous dual-port RAM takes them:

    • <block>_waddr, _wdata, _wstrb and _we to write;
    • <block>_raddr, _re and _rdata to read. The read data comes one cycle after _re.

    The addresses are byte offsets in the memory.

  • Registers come out of reset (s_axi_aresetn low) at their reset values.

  • An address the map does not have answers SLVERR.

  • Addresses are from the map's base: the interconnect strips the base. So s_axi_awaddr is only as wide as the map needs.

Verified#

The tests (test/regmap.test.js):

  • compile the headers of the fixture and of examples/autonomous-car as C11 and C++17 with -Wall -Wextra -Werror, so the static asserts hold. A private project's headers are compiled too, when the test is given its folder;
  • build every SystemVerilog bank with iverilog;
  • simulate the fixture's bank against AXI4-Lite reads and writes: resets, byte strobes, a read-only input in the upper lanes, a memory port, SLVERR;
  • analyse the VHDL with ghdl when it is installed;
  • check the IP-XACT with xmllint.

The SystemRDL and the IP-XACT of these maps were also read back by systemrdl-compiler and by PeakRDL's IP-XACT importer. Both found the blocks, the fields and the resets the model gives.

In an FPGA component#

A component with a clock (fpga.md) reads and drives its registers by their names in its bodies. archec gen --target vhdl writes the same VHDL bank beside the component and wires it in the system's top: the rw and w registers into the component, the r registers out of it, the AXI4-Lite pins on the top. A test case that sets a register writes it over that bus.

Limits#

  • The model cannot say field-level access yet (a read-only field in a read-write register), nor write-1-to-clear or read-to-clear fields.
  • The bank's bus is AXI4-Lite only, 32-bit. There is no APB, Avalon or Wishbone.
  • A part's map has no base of its own in the model: the base is where its first block is.