fw_trial.h File Reference

When a new build's first start is kept: the steps the start waits for, and the bound on the wait. More...

#include <stdbool.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	fw_trial_t
	One trial: the steps seen and whether it is settled. More...

Macros
#define	FW_TRIAL_CARD   0x01u
	The card was tried and the start's card reads ran.
#define	FW_TRIAL_SETTINGS   0x02u
	The settings are loaded.
#define	FW_TRIAL_CONTROL   0x04u
	The control task finished one pass.
#define	FW_TRIAL_LOGGER   0x08u
	The logger task finished one pass.
#define	FW_TRIAL_FRAME   0x10u
	A whole frame reached the display.
#define	FW_TRIAL_TICK   0x20u
	The screen loop ticked after FW_TRIAL_FRAME.
#define	FW_TRIAL_ALL   0x3Fu
	Every step: the start as a whole works.
#define	FW_TRIAL_BOUND_MS   30000u
	How long after the start a trial waits for every step: 30000ms. Past it, FW_TRIAL_TICK alone keeps the build.

Enumerations
enum	fw_trial_verdict_t { FW_TRIAL_OPEN = 0 , FW_TRIAL_KEEP , FW_TRIAL_KEEP_BOUND , FW_TRIAL_SETTLED }
	What fw_trial_poll() decides. More...

Functions
void	fw_trial_init (fw_trial_t *t, uint32_t start_ms)
	Start a trial with no step seen.
void	fw_trial_mark (fw_trial_t *t, uint32_t steps)
	Record steps as seen. FW_TRIAL_TICK counts only once FW_TRIAL_FRAME is seen, before this call or in it; bits outside FW_TRIAL_ALL are ignored.
void	fw_trial_settle (fw_trial_t *t)
	Settle the trial outside this model, as the start without touch does; every later poll says FW_TRIAL_SETTLED.
fw_trial_verdict_t	fw_trial_poll (fw_trial_t *t, uint32_t now_ms, bool quiet)
	Decide at now_ms. FW_TRIAL_KEEP and FW_TRIAL_KEEP_BOUND settle the trial: each is returned once.
uint32_t	fw_trial_missing (const fw_trial_t *t)
	The steps not seen yet.

Detailed Description

When a new build's first start is kept: the steps the start waits for, and the bound on the wait.

The bootloader starts a new build once on trial (pending verify). A reset while it still is, by a panic, a watchdog, a restart or a power cut, starts the build before it. This model says when the trial is settled in the build's favour: once every step in FW_TRIAL_ALL is seen, or, FW_TRIAL_BOUND_MS after the start, once the screen loop is ticking. Either way only on a quiet bench, because keeping the build writes otadata and a flash write stalls both cores.

The steps:

• FW_TRIAL_CARD: the card was tried (mounted, or found missing or unreadable) and the start's card reads ran;
• FW_TRIAL_SETTINGS: the settings are loaded and handed on;
• FW_TRIAL_CONTROL: the control task finished one pass of its loop;
• FW_TRIAL_LOGGER: the logger task finished one pass of its loop;
• FW_TRIAL_FRAME: a whole frame reached the display;
• FW_TRIAL_TICK: the screen loop ticked after that frame. A tick seen before FW_TRIAL_FRAME counts for nothing.

No step waits for the IOmcu: a panel without one is kept the same way.

Pure C, no ESP-IDF (Espressif Internet-of-Things Development Framework). The panel's calls are firmware/panel/main/panel_trial.c.

SPDX-License-Identifier: MIT

Enumeration Type Documentation

fw_trial_verdict_t

enum fw_trial_verdict_t

What fw_trial_poll() decides.

Enumerator
FW_TRIAL_OPEN	still on trial: wait
FW_TRIAL_KEEP	every step seen: keep the build now
FW_TRIAL_KEEP_BOUND	the bound passed and the screen loop ticks
FW_TRIAL_SETTLED	settled before: nothing more to do

Function Documentation

fw_trial_init()

void fw_trial_init	(	fw_trial_t *	t,
		uint32_t	start_ms )

Start a trial with no step seen.

Parameters

t	The trial.
start_ms	The millisecond count the bound counts from.

fw_trial_mark()

void fw_trial_mark	(	fw_trial_t *	t,
		uint32_t	steps )

Record steps as seen. FW_TRIAL_TICK counts only once FW_TRIAL_FRAME is seen, before this call or in it; bits outside FW_TRIAL_ALL are ignored.

Parameters

t	The trial.
steps	One or more FW_TRIAL_* steps.

fw_trial_missing()

uint32_t fw_trial_missing

(

const fw_trial_t *

t

)

The steps not seen yet.

Parameters

t	The trial.

Returns

The FW_TRIAL_* bits of FW_TRIAL_ALL not marked.

fw_trial_poll()

fw_trial_verdict_t fw_trial_poll	(	fw_trial_t *	t,
		uint32_t	now_ms,
		bool	quiet )

Decide at now_ms. FW_TRIAL_KEEP and FW_TRIAL_KEEP_BOUND settle the trial: each is returned once.

Parameters

t	The trial.
now_ms	The millisecond count; it may wrap past 2^32.
quiet	Whether the bench can take a flash write now.

Returns

FW_TRIAL_KEEP once every step is seen on a quiet bench; FW_TRIAL_KEEP_BOUND once FW_TRIAL_BOUND_MS has passed since start_ms with FW_TRIAL_TICK seen on a quiet bench; otherwise FW_TRIAL_OPEN, or FW_TRIAL_SETTLED after a settle.

fw_trial_settle()

void fw_trial_settle

(

fw_trial_t *

t

)

Settle the trial outside this model, as the start without touch does; every later poll says FW_TRIAL_SETTLED.

Parameters

t	The trial.