UPDATE carries five ops against one target chip. Every frame leads with the op and the chip it addresses. Opcode 0x17.

UPDATE 0x17 · payload 2..508 bytes

Returns UPDATE_RESP

  BEGIN --> DATA --> DATA --> ... --> END --> (staged, inert)
    |                                          |
    +-- ABORT ---------------------------------+--> ACTIVATE --> reboot

A target can be staged, left alone, and activated later, and both chips may be staged before a single ACTIVATE commits them together. Read what each chip is running with QUERY(FIRMWARE). Each op below carries its own example. Library binding: update_firmware.

UPDATE op 0 · [target u8][size u32][sha256 u8[32]]

Puts the whole box in update mode: injection and clip playback stop, the host chip stops polling the real device, and the clone disconnects from the game PC. Then it erases the entire target slot before answering READY with the credit in arg. Library binding: stage_firmware.

The erase happens here, up front, and not lazily as bytes arrive. A 64 KB block erase disables the cache for tens of milliseconds, which no receive buffer on either wire can absorb mid-stream.

Open a 364784-byte device-chip image (size is 0x000590F0):

+--------+--------+--------+--------+--------+--------+-------------+----------+--------+
| A5     | 17     | 00     | 26 00  | 00     | 00     | F0 90 05 00 | 32 bytes | lo hi  |
+--------+--------+--------+--------+--------+--------+-------------+----------+--------+
| SOF    | TYPE   | SEQ    | LEN    | op     | target | size        | sha256   | CRC16  |
+--------+--------+--------+--------+--------+--------+-------------+----------+--------+

UPDATE op 1 · [target u8][seq u16][bytes 1..504]

504 is what the frame has left: 512 less the op, the target and a two-byte index, rounded down to a multiple of four so every flash write is aligned.

READY's arg says how many chunks the box will take before it must answer. Read it rather than assuming: the device chip asks for 16, the host chip for 6, because a relayed chunk waits in the inter-chip link's receive ring while the chip behind it writes the one before to flash. The window is a correctness requirement, not a throughput knob.

  PC   |-- credit chunks --|                       |-- credit chunks --|
  box                       |-- write, ACK next --|                     |-- ACK next --|
                            ^
                            cache is off here; nothing may be in flight

A sender that ignores the credit it was given overruns whichever hop is smaller, and the lost chunk leaves the window one short: nothing acknowledges it, and the session dies on the idle timer with the sender still waiting. Library binding: stage_firmware.

A chunk one behind the box's next expected seq is accepted and answered without being rewritten: that is what a lost acknowledgement looks like. Anything older is a SEQGAP and drops the session.

Chunk 3 of a device-chip image, a full 504 bytes of payload:

+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 17     | 2A     | FC 01  | 01     | 00     | 03 00  | ...    | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | op     | target | seq    | bytes  | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+

UPDATE op 2 · [target u8]

Checks the digest and the image header, and stops. It answers STAGED with the byte count, or BADSHA if the image is not what BEGIN promised. Library binding: stage_firmware.

Ten seconds with no traffic ends update mode by itself, so a client that disappears cannot leave the clone down. A staged image survives that: it is inert, and discarding it would throw away a transfer that already completed.

Close the device-chip session:

+--------+--------+--------+--------+--------+--------+--------+
| A5     | 17     | 3C     | 02 00  | 02     | 00     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | op     | target | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+

UPDATE op 3 · [target u8]

Drops whatever is staged or in flight for that target and answers OK. Leaving update mode does not reboot: the host chip re-sends its descriptor snapshot and the clone is rebuilt the same way a re-attach rebuilds it. Library binding: abort_update.

Once ACTIVATE is accepted the box answers new commands with BUSY, and this is the one exception: while the box is waiting on the host chip it abandons that wait and answers the ACTIVATE with TIMEOUT. Past that point the boot partition is already written, so there is nothing left to abort, and cancelling the reboot would leave the box running one image with the loader pointed at the other.

Discard whatever the host chip is holding:

+--------+--------+--------+--------+--------+--------+--------+
| A5     | 17     | 41     | 02 00  | 03     | 01     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | op     | target | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+

UPDATE op 4 · [target u8] (ignored)

Points each staged chip at its new slot and reboots into it, host chip first. The device chip is the only transport, so it is the last one down. Library binding: activate_firmware.

  ACTIVATE
     |
     +--> host commits, reboots
     |         |
     |         +--> back on the link at the new slot
     |                    |
     +--------------------+--> device commits, replies OK, reboots

If only one target is staged, only that one is committed. Anything that fails before ACTIVATE leaves both chips on their running slots untouched, so a failed transfer costs a retry and nothing else. The reply is OK once both chips are committed, NOSTAGE if nothing was staged, or TIMEOUT if the host chip never came back on the new slot; it always names target 0, so match it on the op alone.

Commit everything staged:

+--------+--------+--------+--------+--------+--------+--------+
| A5     | 17     | 55     | 02 00  | 04     | 00     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | op     | target | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+

One reply per UPDATE frame, and one per acknowledged window of DATA. Opcode 0x18.

UPDATE_RESP 0x18 · payload 7 bytes

Reply

Every refusal reaches the library as Error::Update.

READY for a device-chip BEGIN, credit 16:

+--------+--------+--------+--------+--------+--------+--------+-------------+--------+
| A5     | 18     | 00     | 07 00  | 00     | 00     | 01     | 10 00 00 00 | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+-------------+--------+
| SOF    | TYPE   | SEQ    | LEN    | op     | target | status | arg         | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+-------------+--------+

A freshly booted image is on probation until it proves itself, and the bootloader reverts one that never does. Which slot each chip booted, and the state of that image, is in QUERY(FIRMWARE).

  boot new slot --> pending-verify --> chip confirms itself --> valid
                          |
                          +-- panics, or never confirms --> bootloader picks the old slot

Measured on hardware: an image that panics in its entry point is back on the old slot in 0.8 s, and one that boots but never confirms is reverted by its own grace timer.