Sequential Register Writing/Reading

[Poofjunior]

Hi everyone,

I'd like to propose a minor feature tweak to the existing (and future) harp protocol.

For register reads and writes, I propose that if we read/write more than the specified number of bytes, we simply continue reading/writing sequentially from the next register.

The main benefit is that we can read/write groups of sequential registers. For future harp devices, we can then group related registers together, which enables us to read/write structs.

In C++, this is straightforward to implement if the register data is stored in a packed struct.

// Example register values stored contiguously in memory with a packed struct (i.e no padding).
#pragma pack(push, 1)
struct RegValues
{
    const int16_t R_POSITION_X;
    const int16_t R_POSITION_Y;
    const int16_t R_POSITION_Z;
    const uint8_t R_RESET_POSITION;
};
#pragma pack(pop)

Suppose we want to read out the x,y, and z position as a single harp read request, instead of 3 register read requests. Then, on the client side, we simply ask for 6 bytes. Since they're stored contiguously in memory with no padding, the embedded device can just memcpy it into the outgoing packet. In fact, if the data on the harp device is already stored contiguously in memory, then little-to-no changes on the embedded device need to be adjusted.

Here's some "client-side" pseudocode.

dev = harp_device("3D_JOYSTICK")
x = dev.read_request(reg=R_POSITION_X, bytes=2).payload.unpack('<l')
y = dev.read_request(reg=R_POSITION_Y, bytes=2).payload.unpack('<l')
z = dev.read_request(reg=R_POSITION_Z, bytes=2).payload.unpack('<l')

# versus

position_xyz = dev.read_request(reg=R_POSITION_X, bytes=6).payload.unpack('<lll')  # Returns a payload of 6 bytes, aka: 3-little-endian ints

For reference, this is a common way of interacting with a number of ASICs with a register map on serial interfaces like i2c or SPI. Examples include sensors from Bosch like the BMA180, BNO085, etc.

Overall, I think this small tweak lets you basically send/receive groups of data in of mixed payload sizes that can be then reinterpreted from the client side as a struct. This feature is also backward-compatible with existing systems without necessitating any changes. They can simply ignore this feature.

LMK what y'all think!

[glopesdev]

@Poofjunior Thanks for the great input and raising this requirement, I agree having more flexibility in passing around packed custom structures with possibly heterogeneous types is important.

Following the meeting, I was playing around with the YAML schema and actually there is a small kink that doesn't allow it to represent heterogeneous types out-of-the-box (yet). It is definitely fixable though and this is a use case we should indeed support so I will flag an issue to fix it. Nevertheless, for aligned types, you could do:

%YAML 1.1
---
# yaml-language-server: $schema=https://raw.githubusercontent.com/harp-tech/reflex-generator/main/schema/device.json
device: harpy
whoAmI: 0000
firmwareVersion: "0.1"
hardwareTargets: "0.0"
registers:
  Accelerometer:
    address: 32
    type: S16
    length: 3
    access: Event
    payloadSpec:
      X:
        offset: 0
        description: Represents the x-coordinate of the payload.
      Y:
        offset: 1
        description: Represents the y-coordinate of the payload.
      Z:
        offset: 2
        description: Represents the z-coordinate of the payload.

This will generate in the high-level interface the type AccelerometerPayload with the following signature (edited for conciseness):

public struct AccelerometerPayload
{
    public AccelerometerPayload(short x, short y, short z)
    {
        X = x;
        Y = y;
        Z = z;
    }

    public short X;
    public short Y;
    public short Z;
}

And the auto-generated converters:

static AccelerometerPayload ParsePayload(short[] payload)
{
    AccelerometerPayload result;
    result.X = payload[0];
    result.Y = payload[1];
    result.Z = payload[2];
    return result;
}

static short[] FormatPayload(AccelerometerPayload value)
{
    short[] result;
    result = new short[3];
    result[0] = value.X;
    result[1] = value.Y;
    result[2] = value.Z;
    return result;
}

It is actually possible using the message manipulation API to marshal arbitrary payload structs directly (with the equivalent of memcpy), and having an easy way to specify something like this in the spec is definitely interesting. I think I have a solution but need to go through a few edge cases more carefully to make sure it will be workable. Thanks for the push! I'll post here once I have something more complete.