The panel's half of the IOmcu update: finding out whether the IOmcu runs the image the panel carries, sending it, and buying it once it has started. More...

#include <stdbool.h>
#include <stdint.h>
#include "link_host.h"
#include "link_pages.h"
#include "link_port.h"
#include "link_sha256.h"
#include "link_update_image.h"

Data Structures
struct	link_uph_t
	The panel's state for one update run. More...
struct	link_uph_mismatch_t
	An IOmcu of another protocol major answers its identity while the link stays down. More...

Macros
#define	LINK_UPH_HASH_STEP 8192u
	Image bytes hashed in one step.
#define	LINK_UPH_LOST_MS 4000u
	How long exchanges may go unanswered in a row before the link counts as gone: an IOmcu that restarts answers again well inside it.
#define	LINK_UPH_RESTARTS 3u
	Starts from block 0 after the IOmcu lost the session (a restart, link silence) before the update gives up.
#define	LINK_UPH_BLOCK_TRIES 3u
	Refusals of the same block before the update gives up.
#define	LINK_UPH_BUSY_MS 10000u
	How long the store's gate may stay shut while a command waits for it.
#define	LINK_UPH_HASH_MS 10000u
	How long a hash at the IOmcu may take: 2036KiB at 1KiB a pass.
#define	LINK_UPH_SETTLE_MS 500u
	After ACTIVATE: nothing asked for this long, so the old image has restarted before identity is read.
#define	LINK_UPH_CONFIRM_MS 12000u
	After ACTIVATE: the new image has to answer and be bought inside this, well inside the boot ROM's 16.7s TBYB (try before you buy) watchdog.

Enumerations
enum	link_uph_phase_t { LINK_UPH_IDLE = 0 , LINK_UPH_CHECK_HASH , LINK_UPH_CHECK_ASK , LINK_UPH_CHECK_WAIT , LINK_UPH_PREPARE , LINK_UPH_BEGIN , LINK_UPH_SEND , LINK_UPH_RESYNC , LINK_UPH_FINISH , LINK_UPH_VERIFY , LINK_UPH_ACTIVATE , LINK_UPH_RESTARTING , LINK_UPH_BUY , LINK_UPH_DONE }
	The phase the update is in; one per link_uph_step(). More...
enum	link_uph_result_t { LINK_UPH_NONE = 0 , LINK_UPH_SAME , LINK_UPH_DIFFERENT , LINK_UPH_TRIAL , LINK_UPH_NEEDS_USB , LINK_UPH_NO_ANSWER , LINK_UPH_REFUSED , LINK_UPH_BAD_DIGEST , LINK_UPH_BUSY , LINK_UPH_RESTARTED_OUT , LINK_UPH_NOT_STARTED , LINK_UPH_UPDATED }
	How the update ended; held in link_uph_t.result. More...

Functions
void	link_uph_check (link_uph_t u, const uint8_t img, uint32_t len, uint32_t now_ms)
	Find out whether the IOmcu runs the build in `img:` this end's build hash, then the IOmcu's over its running slot.
void	link_uph_update (link_uph_t u, const uint8_t img, uint32_t len, uint32_t now_ms)
	Send `img` to the slot that is not running, check it, start it and buy it.
void	link_uph_confirm (link_uph_t *u, uint32_t now_ms)
	Buy an image found on trial.
link_uph_phase_t	link_uph_step (link_uph_t u, link_host_t h, const link_port_t *port)
	One step; returns the phase it leaves the update in.
uint16_t	link_uph_permille (const link_uph_t *u)
	Blocks committed, in thousandths of the image: 0 to 1000.
bool	link_uph_mismatch_probe (link_uph_mismatch_t *m, bool mismatch)
	One identity probe: `mismatch` whether an IOmcu of another protocol major answered it.
bool	link_uph_mismatch_answers (const link_uph_mismatch_t *m)
	Whether the last probe was answered by a mismatched IOmcu.
void	link_uph_mismatch_rearm (link_uph_mismatch_t *m)
	An update ended: the next mismatched answer owes the check again.

Detailed Description

The panel's half of the IOmcu update: finding out whether the IOmcu runs the image the panel carries, sending it, and buying it once it has started.

Stepwise. Each link_uph_step() does one thing – one block of 64 bytes (8 data frames and a COMMIT), one read, one command, or 8KiB of a hash – and returns, so the caller runs its own loop between steps. The wire is a link_port_t, so the host suite runs every step against a simulated IOmcu over the real link layer.

Only the frozen registers are used: IDENTITY 0 to 6 and the two update pages. An IOmcu of another protocol major is checked and updated the same way.

SPDX-License-Identifier: MIT

Macro Definition Documentation

◆ LINK_UPH_LOST_MS

#define LINK_UPH_LOST_MS 4000u

How long exchanges may go unanswered in a row before the link counts as gone: an IOmcu that restarts answers again well inside it.

An unanswered exchange takes LINK_HOST_TIMEOUT_MS (1000ms) at the panel.

Enumeration Type Documentation

◆ link_uph_phase_t

enum link_uph_phase_t

The phase the update is in; one per link_uph_step().

Enumerator
LINK_UPH_CHECK_HASH	this end's build hash
LINK_UPH_CHECK_ASK	the IOmcu asked to hash its slot
LINK_UPH_CHECK_WAIT	and its answer awaited
LINK_UPH_PREPARE	the SHA-256 of the image as it is sent
LINK_UPH_SEND	a block, then its COMMIT
LINK_UPH_RESYNC	where the IOmcu stands, after a miss
LINK_UPH_RESTARTING	the IOmcu restarts into the new slot
LINK_UPH_DONE	result says how it ended

◆ link_uph_result_t

enum link_uph_result_t

How the update ended; held in link_uph_t.result.

Enumerator
LINK_UPH_NONE	not ended yet
LINK_UPH_SAME	check: it runs this end's build
LINK_UPH_DIFFERENT	check: it runs another build
LINK_UPH_TRIAL	check: an image on trial waits for BUY
LINK_UPH_NEEDS_USB	no update pages, or no slots
LINK_UPH_NO_ANSWER	unanswered for LINK_UPH_LOST_MS
LINK_UPH_REFUSED	refused; error holds the link_upd_err_t
LINK_UPH_BAD_DIGEST	the slot's SHA-256 is not the image's
LINK_UPH_BUSY	the store's gate stayed shut
LINK_UPH_RESTARTED_OUT	LINK_UPH_RESTARTS starts from block 0
LINK_UPH_NOT_STARTED	no new image on trial after the restart
LINK_UPH_UPDATED	the new image runs and is bought

Function Documentation

◆ link_uph_check()

void link_uph_check	(	link_uph_t *	u,
		const uint8_t *	img,
		uint32_t	len,
		uint32_t	now_ms )

Find out whether the IOmcu runs the build in img: this end's build hash, then the IOmcu's over its running slot.

Ends SAME, DIFFERENT, TRIAL, NEEDS_USB, NO_ANSWER or REFUSED.

A session found in the IOmcu – this panel's own, from before it restarted or lost the link – is ended with ABORT first: nobody sends its blocks any more, and it would hold ARM. An ACTIVATE found is waited out for LINK_UPH_HASH_MS: the restart it leads to ends it.

Parameters

u	The update state.
img	The image to compare with the IOmcu's running slot.
len	Length of img in bytes.
now_ms	The current time, in ms.

◆ link_uph_confirm()

void link_uph_confirm	(	link_uph_t *	u,
		uint32_t	now_ms )

Buy an image found on trial.

Ends UPDATED, NO_ANSWER or REFUSED.

Parameters

u	The update state.
now_ms	The current time, in ms.

◆ link_uph_mismatch_answers()

bool link_uph_mismatch_answers ( const link_uph_mismatch_t * m )

Whether the last probe was answered by a mismatched IOmcu.

Parameters

m	The mismatch state; NULL gives false.

Returns: true when the last probe was answered by a mismatched IOmcu.

◆ link_uph_mismatch_probe()

bool link_uph_mismatch_probe	(	link_uph_mismatch_t *	m,
		bool	mismatch )

One identity probe: mismatch whether an IOmcu of another protocol major answered it.

True when the build check is owed now: the first such answer since a probe nobody or a matching IOmcu answered, or the first after link_uph_mismatch_rearm().

Parameters

m	The mismatch state.
mismatch	true when the answer came from an IOmcu of another major.

Returns: true when the build check is owed now.

◆ link_uph_mismatch_rearm()

void link_uph_mismatch_rearm ( link_uph_mismatch_t * m )

An update ended: the next mismatched answer owes the check again.

Parameters

m	The mismatch state; NULL is ignored.

◆ link_uph_permille()

uint16_t link_uph_permille ( const link_uph_t * u )

Blocks committed, in thousandths of the image: 0 to 1000.

Parameters

u	The update state; NULL or no blocks gives 0.

Returns: Committed blocks times 1000 over all blocks.

◆ link_uph_step()

link_uph_phase_t link_uph_step	(	link_uph_t *	u,
		link_host_t *	h,
		const link_port_t *	port )

One step; returns the phase it leaves the update in.

Parameters

u	The update state.
h	The panel's link state.
port	The transport and clock.

Returns: The phase after the step.

◆ link_uph_update()

void link_uph_update	(	link_uph_t *	u,
		const uint8_t *	img,
		uint32_t	len,
		uint32_t	now_ms )

Send img to the slot that is not running, check it, start it and buy it.

Ends UPDATED or with the reason it stopped.

Parameters

u	The update state.
img	The image to send.
len	Length of img in bytes.
now_ms	The current time, in ms.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ LINK_UPH_LOST_MS

Enumeration Type Documentation

◆ link_uph_phase_t

◆ link_uph_result_t

Function Documentation

◆ link_uph_check()

◆ link_uph_confirm()

◆ link_uph_mismatch_answers()

◆ link_uph_mismatch_probe()

◆ link_uph_mismatch_rearm()

◆ link_uph_permille()

◆ link_uph_step()

◆ link_uph_update()