|Home > Iris APIs > Resources API > Writing a resource|
The semantics of writing a resource are poke rather than bus write.
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:
STATUS_CLEARregister whose only purpose is to clear another register when written should have this effect when written with
STATUSregister 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.
TIMERregister 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:
TIMERfor architectural writes.
TIMER_valueto modify the timer value only.
TIMER_reloadto modify the shadow timer reload register only.
Writing a resource should not be limited in any way. All bits that can
architecturally change their value under certain conditions should be modifiable
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:
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.
resource_write() returns one
ResourceWriteResult object. Errors that occurred while updating resources are returned in the
resource_write() never fails with an error when writing existing resources.
For examples of
strings arguments, see 5.6.5 Reading a resource. If the values array is too long or too short for the specified resources,
E_data_size_error. In this case, the implementation might have updated any, or none of the specified resources.