Add ability to trigger firmware update mode from Harp protocol

[bruno-f-cruz]

Summary

This PR proposes modifying the core Harp protocol to include standardized semantics for updating the firmware of Harp-compliant devices.

Motivation

All devices that implement the Harp protocol require regular firmware updates to fix bugs and add new functionality. Currently, the update process varies depending on the hardware vendor and specific implementation. This variability could be abstracted from the user by exposing a common firmware update interface through the Harp protocol.

Standardizing this process would enable developers to target a unified update mechanism, facilitating reusability of tools (e.g., Harp CLI and Bonsai) and eliminating the need for one-off “incantations” that must otherwise be documented and communicated to users.

Detailed Design

Option 1 (The one included in the PR)

• Use R_RESET_DEV bit 5 to trigger firmware update mode. (proposed bit name: FIRMWARE_UPDATE ). This decision is justified since:
  • The register is already write-only in functionality
  • Flashing firmware will likely always require a reset of the device anyway. The function seems to “fit in”
• The implementation of this bit would be considered Optional under the current protocol, but strongly recommended for boards that support it.
• After triggering the firmware update, the device is no longer expected to maintain a behavior consistent with Harp Protocol, and instead, implementation-specific firmware update routines are expected to take over.

Pros

Very simple change to the protocol and generalizable across different SDKs

Fully backward compatible (the bit was not used)

No extra register needed

Cons

No way to know what the device “supports”

Not a lot of room for additional features in this register.

Option 2

This proposal has been summarized in Issue 18

Add two registers

• R/O U32 R_FIRMWARE_UPDATE_CAPABILITIES
• W/O U32 R_FIRMWARE_UPDATE_START_COMMAND

R_FIRMWARE_UPDATE_CAPABILITIES is a bitfield that communicates the well-known firmware update strategies supported by the device.

For example bit 0 is defined as FIRMWARE_UPDATE_PICO_BOOTSEL, which indicates the strategy of the device rebooting into the BOOTSEL mode provided by the RP2040/RP2350 hardware bootloader and being programmed using the picoboot protocol.

R_FIRMWARE_UPDATE_START_COMMAND is a bitfield with the same layout. Writing to a bit instructs the device to initiate that firmware update scheme. So writing FIRMWARE_UPDATE_PICO_BOOTSEL to it causes the device to reboot into BOOTSEL mode. (Similar to what Sonya is doing with RST_DFU.)

Pros

Easy discoverability of update functionality

Extensible (see #18 (comment))

Cons

2 extra registers must be added to core

The core may become contaminated with sdk-specific functionality (e.g. in the cited example bit 0 seems specific for pico). There may not be a good way around this unless we go back to the idea of maintaining two cores.

Option 3 (both?)

It should be noted that, until we are sure about option 2, we could go with option 1 for the near future while we test its functionality. Option 2 could then be implemented by deprecating the previous bit (e.g. writing to the previous bit would instead trigger the functionality of bit 0 of the new register).

[filcarv]

Option 1

[artursilva0]

Option 1