4.3.3 Writing a resource

The semantics of writing a resource are poke rather than bus write.

Side effects

Writing a resource should generally cause the side effect that a debugger user would expect when modifying the resource value. Side effects should be useful and intuitive, and should be kept to a minimum.

For most register resources, the side effect is the same as an architectural write.

For all resources where writes have side effects, these side effects, or the absence of them, must be documented in the resource description. For resources that expose multiple useful layers of side effects, multiple resources with intuitive but different names should be exposed. For example:

  • A STATUS_CLEAR register whose only purpose is to clear another register when written should have this effect when written with resource_write().
  • A STATUS register which clears itself when written to should not clear itself, but instead accept the value written to it. To clear the register, zero can be written to it.
  • A TIMER register which you can modify to change the current timer value or which you can write to set a new reload value is best represented by three resources with different side effects:
    • TIMER for architectural writes.
    • TIMER_value to modify the timer value only.
    • TIMER_reload to modify the shadow timer reload register only.

Permissions and updating resources

Writing a resource should not be limited in any way. All bits that can architecturally change their value under certain conditions should be modifiable through resource_write(). However, writes that are architecturally forbidden and would lead to inconsistencies in the simulation state, should be ignored.

For example the following registers should be freely writable at all times:

  • An EEPROM register containing a serial number which can normally only be programmed during a special reset procedure.
  • A read-only flags register in which the flags can only be affected by executing instructions.
  • A read-only cycle counter register, unless an update would cause inconsistent simulation state.
  • An internal register that is architecturally inaccessible, for example an internal buffer or a shadow register.

Writing read-only

Some or all bits of a resource might be read-only. Writes to these bits are ignored without error. If the whole resource is read-only, the ResourceWriteResult.error array should indicate this.

Write errors

resource_write() returns one ResourceWriteResult object. Errors that occurred while updating resources are returned in the ResourceWriteResult.error array. resource_write() never fails with an error when writing existing resources.

For examples of data and strings arguments, see 4.3.2 Reading a resource. If the values array is too long or too short for the specified resources, resource_write() returns E_data_size_error. In this case, the implementation might have updated any, or none of the specified resources.

Non-ConfidentialPDF file icon PDF version101196_0100_00_en
Copyright © 2018 Arm Limited or its affiliates. All rights reserved.