Access modes¶
Every field has a software access, sw, which says what the bus can do with
it, and a hardware access, hw, which says what your logic can do with it.
Side effects and modifiers on top of these make a field clear when read, set by
hardware, pulse for one cycle, and so on. The keywords follow SystemRDL 2.0.
This page describes what each access key does in the generated register file. Register map format shows where the keys go in the JSON file.
The VHDL on this page was generated by bust from the examples in the
repository, mostly
example_prototype.json.
Its registers reg0 to reg11 each show one group of access modes.
Software access¶
|
A bus read |
A bus write |
|---|---|---|
|
returns the field |
updates the field |
|
returns the field |
has no effect |
|
returns 0 |
updates the field |
|
returns 0 |
has no effect |
A bus write always covers the whole register, because the generated bus endpoints have no byte enables. It updates every field of the register that software can write. See Bus accesses for what the bus sees when an access has no effect.
Hardware access¶
Your logic reaches the fields through two record ports: to_hw carries values
from the register file to your logic, and from_hw carries values from your
logic to the register file.
|
Member in |
Member in |
|---|---|---|
|
the field’s value |
none |
|
none |
the field’s value |
|
the field’s value |
the field’s value |
|
none |
none |
The records are nested by register and then by field, so a field is
to_hw.<register>.<field> or from_hw.<register>.<field>. A register without
fields is to_hw.<register> or from_hw.<register> itself. A bit field is a
std_logic, a vector field a std_logic_vector, and an enumerated field has
its own type. Here are reg0 (sw rw, hw r) and reg1 (sw ro, hw w)
of the prototype:
type t_prototype_reg0_to_hw is record
field0 : std_logic;
field1 : std_logic_vector(1 downto 0);
end record t_prototype_reg0_to_hw;
type t_prototype_reg1_from_hw is record
field0 : t_prototype_reg1_field0_in;
field1 : std_logic;
field2 : t_prototype_reg1_field2_in;
end record t_prototype_reg1_from_hw;
reg1.field1 is a plain input. field0 and field2 have a write enable, so
each gets a record of its own. See Hardware modifiers.
A register appears in the module’s to_hw record only when at least one of its
fields has a member there, and the same goes for from_hw. When no field of
the module has a member, the module has no to_hw or from_hw port at all.
With hw w or rw and no we or wel, hardware writes the field on every
clock cycle. The register file stores the from_hw value at each rising edge,
so the field follows the input one clock cycle later.
Common combinations¶
|
|
Use |
|---|---|---|
|
|
Control. Software writes a setting and your logic reads it. |
|
|
Status. Your logic drives a value and software reads it. |
|
|
Command or argument. |
|
|
Scratch register for software only. |
|
|
Constant, such as an ID or a version. See Constant fields. |
|
|
Both sides write. Your logic overrides the value while |
Constant fields¶
A field that nothing can change holds no state. That is a field with sw ro
or na, hw r or na, and no onread, hwset or hwclr. bust generates
it as a constant at its reset value. Here is the identity register of
example_access_matrix.json,
where id resets to 0xA5:
to_hw.identity <=
(
id => 8x"A5",
pwr_default => t_access_matrix_identity_pwr_default'(PWR_ON),
pwr_spare => t_access_matrix_identity_pwr_spare'(PWR_OFF)
);
Software side effects¶
onread¶
onread changes the field after software reads it. The read returns the value
from before the change.
|
After a software read, the field is |
|---|---|
|
all 0 |
|
all 1 |
The field needs software read access, sw rw or ro. The prototype’s
reg5 has one field of each:
-- reg5 onread effects.
if rd_service and reg_addr_match(reg_offset, C_PROTOTYPE_REG5_OFFSET) then
regs.reg5.field0 <= (others => '0');
regs.reg5.field1 <= (others => '1');
end if;
onwrite¶
onwrite combines the written data w with the field’s current value f.
Without onwrite, the field takes the written data.
|
Write data 1 |
Write data 0 |
New value |
|---|---|---|---|
|
sets the bit |
no change |
|
|
clears the bit |
no change |
|
|
toggles the bit |
no change |
|
|
no change |
sets the bit |
|
|
no change |
clears the bit |
|
|
no change |
toggles the bit |
|
|
clears the bit |
clears the bit |
all 0 |
|
sets the bit |
sets the bit |
all 1 |
The field needs software write access, sw rw or wo. The prototype’s
reg6:
if sw_write and reg_addr_match(reg_offset, C_PROTOTYPE_REG6_OFFSET) then
regs.reg6.field0 <= regs.reg6.field0 or lb_m2s.wdata(3 downto 0);
regs.reg6.field1 <= regs.reg6.field1 and not lb_m2s.wdata(7 downto 4);
regs.reg6.field2 <= regs.reg6.field2 xor lb_m2s.wdata(11 downto 8);
end if;
A field that hardware sets with hwset and software clears with
onwrite: woclr is a sticky event flag. Software clears a flag by writing 1 to
its bit, and writing 0 leaves a flag as it is. In a register of such flags,
software can then clear one flag without touching the others.
singlepulse¶
With "singlepulse": true, a field returns to its reset value one clock cycle
after a software write. Hardware sees the written value for exactly one clock
cycle. Use it for commands such as start or flush. The prototype’s reg10:
regs.reg10.field0 <= (others => '0');
if sw_write and reg_addr_match(reg_offset, C_PROTOTYPE_REG10_OFFSET) then
regs.reg10.field0 <= lb_m2s.wdata(3 downto 0);
end if;
The field rests at its reset value, which need not be 0. A write of the reset value gives no visible pulse. A software read after the pulse returns the reset value.
A singlepulse field needs software write access (sw rw or wo) and
hardware read access (hw r or rw). It cannot have onwrite or onread,
and hardware cannot write it on every cycle, so hw: rw needs we or wel.
Hardware modifiers¶
Key |
The field needs |
Member |
Effect |
|---|---|---|---|
|
|
|
Hardware writes |
|
|
|
The same, in cycles where |
|
any access |
|
|
|
any access |
|
|
|
|
|
|
|
|
|
|
we and wel cannot be used together.
A field with we, wel, hwset or hwclr gets its own from_hw record. If
hardware can write the field, its value moves to the value member. From the
prototype, reg1.field0 (hw w, we) and reg4.field1 (hw r, hwset,
hwclr):
type t_prototype_reg1_field0_in is record
value : std_logic_vector(3 downto 0);
we : std_logic;
end record t_prototype_reg1_field0_in;
type t_prototype_reg4_field1_in is record
set : std_logic;
clr : std_logic;
end record t_prototype_reg4_field1_in;
Your logic drives from_hw.reg1.field0.value and from_hw.reg1.field0.we.
A field with swmod or swacc gets its own to_hw record, with the field’s
value in value. The prototype’s reg9.field0 has swmod:
type t_prototype_reg9_field0_out is record
value : std_logic_vector(3 downto 0);
swmod : std_logic;
end record t_prototype_reg9_field0_out;
Your logic reads to_hw.reg9.field0.value and to_hw.reg9.field0.swmod.
The swmod and swacc strobes are registered. After a write, the strobe is
high in the same clock cycle as the new value first shows on to_hw. After a
read, swacc is high in the cycle after the register file takes the read,
which is also when an onread effect shows. swmod pulses on every software
write to the register, even when the value does not change. It does not pulse
when an onread effect changes the field.
Inheritance¶
Every access key can sit on a register, as the default for the register’s
fields. A field takes each key from itself first, then from its register.
When neither sets a key, the field gets sw: rw, hw: r and no side effects
or modifiers.
{
"name": "pulses",
"sw": "rw",
"hw": "r",
"singlepulse": true,
"type": "fields",
"fields": [
{ "name": "go", "type": "bit" },
{ "name": "kick", "type": "vector", "width": 4, "swmod": true }
]
}
Both fields of pulses are sw rw, hw r and singlepulse, and kick also
has swmod. A field switches off an inherited modifier with false, as in
"singlepulse": false.
bust checks each field after inheritance, so a register default must suit every
field that does not override it. In this register, rx_count inherits
onwrite but cannot be written by software:
{
"name": "irq",
"type": "fields",
"sw": "rw",
"hw": "r",
"onwrite": "woclr",
"fields": [
{ "name": "rx_done", "type": "bit", "hwset": true },
{ "name": "tx_done", "type": "bit", "hwset": true },
{ "name": "rx_count", "type": "vector", "width": 4, "sw": "ro", "hw": "w" }
]
}
Could not parse register irq: Invalid field format: onwrite requires a software-writable field (sw rw or wo) (field rx_count in reg irq)
Give rx_count the key "onwrite": null to remove the inherited side effect.
null removes an inherited onread in the same way.
Same-cycle precedence¶
When several sources update a field in the same clock cycle, the register file applies them in a fixed order. The first one in this list wins:
hwclrhwsetA hardware write with
weorwelA software write, or an
onreadside effectA hardware write without
weorwel, which happens on every cycle
The register file handles one bus access at a time, so a software write and a read side effect never happen in the same cycle. Each field is handled on its own, so fields of the same register do not affect each other. bust has no key that changes the order.
The order comes out as an if/elsif chain in the register file. Here it is
for the prototype’s reg4.field1, which has hwset and hwclr:
if from_hw.reg4.field1.clr = '1' then
regs.reg4.field1 <= '0';
elsif from_hw.reg4.field1.set = '1' then
regs.reg4.field1 <= '1';
elsif sw_write and reg_addr_match(reg_offset, C_PROTOTYPE_REG4_OFFSET) then
regs.reg4.field1 <= lb_m2s.wdata(8);
end if;
Two cases follow from the order:
A field with
hwsetandonread: rclrkeeps an event that arrives during a read. The read returns the old value, thehwsetwins over the clear, and the next read sees the field set.When hardware writes a field on every cycle, a software write or an
onreadeffect lasts one clock cycle, and then the hardware value replaces it. Ahwsetorhwclron such a field lasts as long as the strobe is held. Useweorwelwhen software and hardware should both be able to keep a value in the field.
Bus accesses¶
Fields software cannot reach¶
Fields that software cannot read, with sw wo or na, read as 0. So do the
bits that no field covers. A write has no effect on fields that software
cannot write, with sw ro or na. In both cases the access completes
normally. The bus only gets an error response for an address where no register
sits, see Unmapped addresses. The prototype’s reg2 has
a single wo field, so a read of it returns 0:
elsif reg_addr_match(reg_offset, C_PROTOTYPE_REG2_OFFSET) then
rd_ack <= '1';
An instance with G_ERR_ON_BAD_ACCESS => true also answers with an error a
write to a register that has no field software can write, and a read of a
register that has no field software can read. Such a read returns
G_UNMAPPED_READ_DATA. Nothing else about the access changes.
Unmapped addresses¶
An access to a register offset where no register sits gets an error response.
That includes an address inside a register, such as 0x1 when a register sits
at 0x0 on a bus whose addresses count bytes. So does an address above the
registers in the module’s address range, and an address with another base
address, unless the module was instantiated with
G_CHECK_BASE_ADDRESS => false. A write to such an address has no effect, and
a read returns G_UNMAPPED_READ_DATA, which is 0 unless the instance sets it.
Base address and address range explains these checks. How the error reaches the bus master depends on the bus:
Bus |
Error response |
|---|---|
AXI4-Lite |
|
IPBus |
|
APB |
|
Wishbone |
|
SBI |
none, the access completes as usual |
Avalon-MM |
none, the access completes as usual |
Buses describes each protocol, and Generated HDL the base address generics.
Enumerated fields¶
A field with enums gets a VHDL enumeration type named
t_<module>_<register>_<field>, with the literals in the order of the enums list, and
two conversion functions. Here is the enum_vector.mode field of
example_access_matrix.json,
which names the values 0 (MODE_SLOW) and 3 (MODE_FAST):
type t_access_matrix_enum_vector_mode is (MODE_SLOW, MODE_FAST);
function to_slv (
v : t_access_matrix_enum_vector_mode
) return std_logic_vector is
variable slv : std_logic_vector(1 downto 0);
begin
case v is
when MODE_SLOW =>
slv := "00";
when MODE_FAST =>
slv := "11";
end case;
return slv;
end function to_slv;
function to_access_matrix_enum_vector_mode (
s : std_logic_vector(1 downto 0)
) return t_access_matrix_enum_vector_mode is
begin
case s is
when "00" =>
return MODE_SLOW;
when "11" =>
return MODE_FAST;
when others =>
return MODE_SLOW;
end case;
end function to_access_matrix_enum_vector_mode;
The encoding is the
valuefrom the JSON file, not the position of the literal in the type.The register file stores the field as the enumeration type, and its
to_hwandfrom_hwmembers have that type too. Your logic compares and assigns literals, as into_hw.enum_vector.mode = MODE_FAST.A software write is decoded with
to_<register>_<field>. An encoding without a name decodes to the first literal in the list, so writing"01"tomodestoresMODE_SLOW, and a read then returns"00".A software read returns the encoding, through
to_slv.The reset value is the literal for the field’s
reset. Without areset, it is the literal with value 0, or the first literal when no value is 0. See Register map format.A
bitfield can be enumerated too. Its encodings arestd_logic_vector(0 downto 0).
Literal names can repeat across fields. example_access_matrix.json has
PWR_OFF and PWR_ON in several fields, and each field still gets its own
type. VHDL tells the literals apart by type. Where the type is not clear from
the context, qualify the literal, as in t_enum_bit_power'(PWR_ON).
An enumerated field cannot have onread, onwrite, singlepulse, hwset or
hwclr, because these act on single bits. It can have we, wel, swmod and
swacc.
Combinations bust rejects¶
bust stops when a field combines access keys that have no consistent meaning. It names the register and the field:
Could not parse register ctrl: Invalid field format: onread and singlepulse are mutually exclusive: the field self-clears, so rclr has no effect and rset fires a pulse on every read (field flush in reg ctrl)
The reason after Invalid field format: is one of these:
Combination |
Reason |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When a field breaks more than one rule, bust reports the first one in this table. Register-level keys count as well, see Inheritance.