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

sw

A bus read

A bus write

rw

returns the field

updates the field

ro

returns the field

has no effect

wo

returns 0

updates the field

na

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.

hw

Member in to_hw

Member in from_hw

r

the field’s value

none

w

none

the field’s value

rw

the field’s value

the field’s value

na

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

sw

hw

Use

rw

r

Control. Software writes a setting and your logic reads it.

ro

w

Status. Your logic drives a value and software reads it.

wo

r

Command or argument. to_hw holds the last value written, and reads return 0.

rw

na

Scratch register for software only.

ro

r or na

Constant, such as an ID or a version. See Constant fields.

rw

rw with we

Both sides write. Your logic overrides the value while we is high.

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.

onread

After a software read, the field is

rclr

all 0

rset

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.

onwrite

Write data 1

Write data 0

New value

woset

sets the bit

no change

f or w

woclr

clears the bit

no change

f and not w

wot

toggles the bit

no change

f xor w

wzs

no change

sets the bit

f or not w

wzc

no change

clears the bit

f and w

wzt

no change

toggles the bit

f xor not w

wclr

clears the bit

clears the bit

all 0

wset

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

we

hw w or rw

from_hw.<reg>.<field>.we

Hardware writes .value into the field only in cycles where .we is '1'.

wel

hw w or rw

from_hw.<reg>.<field>.wel

The same, in cycles where .wel is '0'.

hwset

any access

from_hw.<reg>.<field>.set

'1' sets every bit of the field.

hwclr

any access

from_hw.<reg>.<field>.clr

'1' clears every bit of the field.

swmod

sw rw or wo, hw r or rw

to_hw.<reg>.<field>.swmod

'1' for one clock cycle after each software write to the register.

swacc

sw rw, ro or wo, hw r or rw

to_hw.<reg>.<field>.swacc

'1' for one clock cycle after each software read or write of the register.

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:

  1. hwclr

  2. hwset

  3. A hardware write with we or wel

  4. A software write, or an onread side effect

  5. A hardware write without we or wel, 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 hwset and onread: rclr keeps an event that arrives during a read. The read returns the old value, the hwset wins over the clear, and the next read sees the field set.

  • When hardware writes a field on every cycle, a software write or an onread effect lasts one clock cycle, and then the hardware value replaces it. A hwset or hwclr on such a field lasts as long as the strobe is held. Use we or wel when 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

SLVERR on bresp or rresp

IPBus

ipb_err

APB

pslverr

Wishbone

err_o instead of ack_o

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 value from 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_hw and from_hw members have that type too. Your logic compares and assigns literals, as in to_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" to mode stores MODE_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 a reset, it is the literal with value 0, or the first literal when no value is 0. See Register map format.

  • A bit field can be enumerated too. Its encodings are std_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

sw: na and hw: na

field has neither software nor hardware access

we and wel

we and wel are mutually exclusive

we or wel with hw r or na

we/wel require a hardware-writable field (hw w or rw)

onread with sw wo or na

onread requires a software-readable field (sw rw or ro)

onwrite with sw ro or na

onwrite requires a software-writable field (sw rw or wo)

onwrite and singlepulse

onwrite and singlepulse are mutually exclusive

singlepulse with sw ro or na

singlepulse requires a software-writable field (sw rw or wo)

swmod with sw ro or na

swmod requires a software-writable field (sw rw or wo)

swacc with sw: na

swacc requires software access (sw not na)

swmod, swacc or singlepulse with hw w or na

<keys> is delivered through to_hw, so the field needs hw r or rw, not hw <hw>, or are delivered for more than one key

singlepulse with hw: rw and no we or wel

singlepulse cannot self-clear a field hardware writes every cycle (hw rw needs we or wel)

singlepulse and onread

onread and singlepulse are mutually exclusive: the field self-clears, so rclr has no effect and rset fires a pulse on every read

enums with onread, onwrite, singlepulse, hwset or hwclr

enums cannot be combined with <keys>: bit-level side effects and hardware set/clear have no meaning for an enumerated value

When a field breaks more than one rule, bust reports the first one in this table. Register-level keys count as well, see Inheritance.