WRITE-only Registers

[Poofjunior]

I think there's some utility in having WRITE-only registers.

Here's an example for configuring a row of 8 digital outputs via bitmasks:

struct app_registers
{
    uint8_t DO_Set;  // bitmask. Writing 1 to any bit turns on the corresponding digital output
    uint8_t DO_Clear;  // bitmask. Writing 1 to any bit turns off the corresponding digital output
    uint8_t DO_State;  // bitmask. Writing 1 to any bit turns on the corresponding digital output, while
                        // writing 0 to any bit turns off the corresponding digital output.
};

Here, it's ambiguous as to what it means to perform a Harp READ on DO_Set and DO_Clear. Do they reflect the raw value of the 8 GPIOs? Do they represent the last value set?

Here's where a WRITE-ONLY register makes sense for DO_Set and DO_Clear. Writing to this register would return a WRITE_REPLY of what was actually written, but reading this register would result in a READ_ERROR reply.

Benefits/Implications

I think the main change is being able to more directly attach functions to registers where the corresponding register size/content has nothing to do with the device behavior, like triggering a void function (function that returns nothing) with multiple input parameters.

This change asks us to reconsider what's on the other side of a Harp Register. Currently, although not explicitly, the Register abstraction invites us to think about registers as data, i.e: "Registers" represent some sort of actual memory location on the device. Having write-only registers loosens this abstraction, and enables us to think about registers either as data, or more broadly as endpoints that trigger device behaviors (i.e: function pointers, remote procedure calls, etc.).

Other Changes

We would need to change the DUMP core register to not dump write-only registers.

[bruno-f-cruz]

Comments from SRM 27022025

harp json-schema

• The READ is currently automatically appended. To make it backward compatible, we should probably have an extra value: WRITE_ONLY that excludes this default behavior. @glopesdev Makes a point that WRITE_ONLY is more explicit.

• The alternative could be to have a NO_READ value that could be re-used for a potential EVENT message that does not have a corresponding read functionality. This could also be solved by an additional EVENT_ONLY value that can be combined with the previous WRITE_ONLY

Alternatives

Instead of disabling reads, we could be explicit of what the default value should be for these registers.

[PathogenDavid]

It wasn't my focus, but I found another example of this type of register existing in the Harp Soundcard. Specifically the REG_COMMANDS register. It's used for toggling the secondary processor's bootloader mode and deleting sounds.

The written value chooses between those functions, they appear to always read as 0. (Implementation here.)

[PathogenDavid]

Another example, GPIOs in the behavior board: https://github.com/harp-tech/device.behavior/blob/ddf71cfbec248f1cd7b7abaa9c477ac58e4a4dae/device.yml#L21-L38