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
}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 isconst 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
memoryblock is one element (: uint32) or several (: uint16[4], orcount 80). It is at the address after@. - Its element has its type's size, or
sizebytes. A record of fields whosebitsare all given is 4 bytes. - After the type,
rw,r(ro) orw(wo) says who may read or write it on the bus. With no access, it isrw. 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", orbits "3"for one bit. - A field with no
bitsis the bytes after the field before it: itssize, else its type's size. So a record laid out byte by byte, such as a shared memory, needs nobits. - 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.
WSTRBwrites 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,_wstrband_weto write;<block>_raddr,_reand_rdatato read. The read data comes one cycle after_re.
The addresses are byte offsets in the memory.
Registers come out of reset (
s_axi_aresetnlow) 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_awaddris 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.