Base address and address range¶
A module answers for an address range: a block of 2**G_MODULE_ADDR_WIDTH
addresses that starts at its base address. You set both with generics when
you instantiate the module. Inside the range, each register sits at its
register offset, its distance from the base address. The address keys in the
JSON file are register offsets, and so are the C_<MODULE>_<REG>_OFFSET
constants in the VHDL and the <MODULE>_<REG>_OFFSET constants in the headers. An address on
the bus is the base address plus a register offset.
Three generics of the bus endpoint control how the module decodes an address. The register file and the starter top level have the same three:
Generic |
Default |
What it sets |
|---|---|---|
|
0 |
Where the address range starts. An |
|
|
Whether the module compares the high address bits of each access with |
|
|
How many low address bits the module decodes. The address range is |
addr_width in the JSON file is the width of the address on the bus. Of
those bits, the low G_MODULE_ADDR_WIDTH belong to the module’s address range,
and the bits above them to the base address. C_<MODULE>_MODULE_ADDR_WIDTH,
in <module>_regfile_pkg, is the number of low bits that select a register. The
registers need all of them, so G_MODULE_ADDR_WIDTH cannot be smaller.
How an address is decoded¶
The register file splits each address into three parts. The figure shows the
timer from Getting started, whose registers sit at
register offsets 0x0 to 0xC, so C_TIMER_MODULE_ADDR_WIDTH is 4. The bit numbers
at the top are for G_MODULE_ADDR_WIDTH => 12, a 4 KiB address range.
Register select, the low
C_<MODULE>_MODULE_ADDR_WIDTHbits, picks the register.Above the registers, bits
C_<MODULE>_MODULE_ADDR_WIDTHtoG_MODULE_ADDR_WIDTH - 1, must be 0. An address where one of them is set is in the address range but above the registers. There are no such bits whenG_MODULE_ADDR_WIDTHhas its default.Base address, bit
G_MODULE_ADDR_WIDTHand up, must equal the same bits ofG_BASE_ADDRESSwhenG_CHECK_BASE_ADDRESSistrue. When it isfalse, the module does not look at them.
An access that fails a check gets an error response, and so
does an access to an unused register offset, such as 0x8 in a module with
registers at 0x0, 0x4 and 0xC. A failed write changes nothing,
and a failed read returns G_UNMAPPED_READ_DATA, 0 by default.
Choosing the settings¶
Two questions decide the settings.
Does the interconnect check the base address? Many interconnects, such as
an AXI4-Lite crossbar or the IPBus fabric, forward an access to a module only
when its address falls in the module’s address range. The base address is then
checked already, so set G_CHECK_BASE_ADDRESS => false. The module then does
not use G_BASE_ADDRESS, and you can leave it out. On a bus where every module
sees every access, nothing else checks the base address. Set
G_CHECK_BASE_ADDRESS => true and give the module its base address with
G_BASE_ADDRESS.
How large is the module’s address range? Set G_MODULE_ADDR_WIDTH to
match the address range your system gives the module, for example 12 for
4 KiB. An access to an address in that range where no register sits then gets
an error, so a wrong address in software shows up as an error instead of
reaching a register. The default decodes only the bits the registers need. It
is safe only when no access can reach an address above the registers, which is
the case with G_CHECK_BASE_ADDRESS => true, or with an interconnect that
forwards exactly the 2**C_<MODULE>_MODULE_ADDR_WIDTH addresses of the
registers. When in doubt, set G_MODULE_ADDR_WIDTH.
With the timer at base address x"4000_1000" in a 4 KiB address range, the
settings in the figure answer these accesses:
|
|
|
|
|
|
|---|---|---|---|---|---|
A |
|
4, the default |
|
error |
error |
B |
|
12 |
|
error |
|
C |
|
4, the default |
|
|
|
A is for a bus where every module sees every access. The module compares every address bit, so only its own 16 bytes answer. With
G_MODULE_ADDR_WIDTH => 12as well, it answers the same, and the base address must then be a multiple of 4 KiB.B is for an interconnect that forwards the timer’s 4 KiB to it. Every address in the range where no register sits gets an error. The module leaves the base address bits to the interconnect, so it would answer
0x5000_1004too, but the interconnect never forwards that address.C is B with the default module address width. The module decodes only the low 4 bits, so
0x4000_1014reachesloadthrough those bits,0x4, with no error. A wrong address in software can then hit a pulse or clear-on-read register. Use B instead.
Alignment¶
With G_CHECK_BASE_ADDRESS set to true, G_BASE_ADDRESS must be a multiple
of 2**G_MODULE_ADDR_WIDTH, so the address range starts on a boundary of its
own size. Otherwise the register file stops the simulation with an assertion
failure. For the timer, x"4000_1000" works with any module address width up
to 12, and x"4000_1010" only with the default of 4. With
G_CHECK_BASE_ADDRESS set to false, the module does not use
G_BASE_ADDRESS.
G_MODULE_ADDR_WIDTH must be at least C_<MODULE>_MODULE_ADDR_WIDTH and at
most addr_width. Another value also stops the simulation with an assertion
failure.
Byte and word addresses¶
The register file compares every low address bit with the register offsets.
With 32-bit data on a bus whose addresses count bytes, the timer’s registers
sit at 0x0, 0x4, 0x8 and 0xC. An access to an address between them,
such as 0x4000_1005, matches no register and gets an error, as an unused
register offset does. On AXI4-Lite a read of 0x1 with a register at 0x0
gets SLVERR, not the register.
byte_addressable in the module changes only how far apart bust places the
registers that have no address, which register offsets it accepts in the JSON
file, and which addresses the generated testbench tries. The generated HDL is
the same either way. See
Byte and word addresses.
On IPBus, addresses count 32-bit words. The IPBus endpoint passes the low
addr_width bits of ipb_addr to the register file, and the IPBus fabric
decodes the higher bits. IPBus has the details.
Why the base address is a generic¶
The base address describes where you place the module, not the module itself, so it is not a key in the JSON file. You can instantiate one register map several times at different base addresses, and you can move a module without generating it again. The headers give register offsets for the same reason, and your software adds the base address.
Field offsets in the headers¶
In the headers, _OFFSET also names the lowest bit of a field, as in
<MODULE>_<REG>_<FIELD>_OFFSET. That is a bit position inside the register,
not an address. Headers and documentation
lists the constants.