update_hw.c File Reference

The firmware update on this board. More...

#include "update_hw.h"
#include <stddef.h>
#include <string.h>
#include "pico/stdlib.h"
#include "boot/bootrom_constants.h"
#include "boot/picobin.h"
#include "boot/picoboot_constants.h"
#include "hardware/flash.h"
#include "pico/bootrom.h"
#include "link_update_dev.h"
#include "out_store.h"

Macros
#define	FLASH_READ_BASE   XIP_NOCACHE_NOALLOC_NOTRANSLATE_BASE
	Reads of both slots by their storage address: not translated to the running slot, and not cached, so a sector just written reads back as the flash holds it.

Functions
static bool	io_erase (void *ctx, uint32_t off)
	Erases a sector of the slot being written.
static bool	io_program (void *ctx, uint32_t off, const uint8_t *data)
	Programs one sector of the slot being written.
static bool	io_gate (void *ctx)
	Tells whether a flash write may run now.
static void	buy_in_window (void *arg)
	Inside a flash window: the boot ROM clears the TBYB (try before you buy) flag in flash, and for a version downgrade erases the other slot's first sector. link_update_dev erases that sector after every BUY, and owes the erase until it holds.
static bool	io_buy (void *ctx)
	Runs the boot ROM's BUY inside a flash window.
static void	io_restart (void *ctx)
	Restarts into the slot just written, as a flash update boot. This function does not return.
static bool	partition_at (unsigned n, uint32_t *start, uint32_t *bytes)
	Where partition n of the table the boot ROM holds starts and how many bytes it spans; false without one.
void	update_hw_init (bool(*busy)(void))
	Read the boot ROM's word on this boot – which slot runs, whether it is on trial – and check the partition table against the layout this build has.
void	update_hw_ctl_read (void *ctx, uint8_t off, uint8_t n, uint16_t *out)
	The two pages' handlers, for the link_page_t table.
uint8_t	update_hw_ctl_write (void *ctx, uint8_t off, uint8_t n, const uint16_t *in)
	Writes the UPDATE_CTL page, for the link_page_t table.
void	update_hw_data_read (void *ctx, uint8_t off, uint8_t n, uint16_t *out)
	Reads the UPDATE_DATA page, for the link_page_t table.
uint8_t	update_hw_data_write (void *ctx, uint8_t off, uint8_t n, const uint16_t *in)
	Writes the UPDATE_DATA page, for the link_page_t table.
void	update_hw_poll (uint32_t now_ms)
	Once per pass: a slice of a hash, the restart after ACTIVATE, an owed erase of the other slot's first sector, the end of a session that has had no update request for 5s.
bool	update_hw_holds_arm (void)
	True while ARM is refused: an update session or an image on trial.
bool	update_hw_refuses_arm (uint8_t off, uint8_t n, const uint16_t *in)
	Whether a CONTROL write is refused for the update (link_update_dev.h).
int	update_hw_slot (void)
	For the console: the slot running, 0 or 1, or -1 without a table.
bool	update_hw_on_trial (void)
	For the console: whether the running image waits for its BUY.

Variables
static link_update_dev_t	s_upd
static link_update_io_t	s_io
static bool(*)	s_busy (void)
static uint32_t	s_target_off
static uint32_t	s_running_off
	Offset of the running image's slot from the start of flash.
static int	s_slot = -1
static uint32_t	s_buy_work [FLASH_SECTOR_SIZE/sizeof(uint32_t)]
	The boot ROM's BUY needs 4KiB to rewrite the sector holding the flag.
static int	s_buy_rc

Detailed Description

The firmware update on this board.

See update_hw.h and the update section of link_pages.h.

SPDX-License-Identifier: MIT

Function Documentation

buy_in_window()

void buy_in_window ( void * arg )

static

Inside a flash window: the boot ROM clears the TBYB (try before you buy) flag in flash, and for a version downgrade erases the other slot's first sector. link_update_dev erases that sector after every BUY, and owes the erase until it holds.

Parameters

arg

Unused.

io_buy()

bool io_buy ( void * ctx )

static

Runs the boot ROM's BUY inside a flash window.

Parameters

ctx

Unused.

Returns

True when the window opened and BUY returned 0.

io_erase()

bool io_erase ( void * ctx, uint32_t off )

static

Erases a sector of the slot being written.

Parameters

ctx	Unused.
off	Offset within the slot, in bytes. An offset of IOMCU_SLOT_BYTES or more is refused.

Returns

True when the erase ran.

io_gate()

bool io_gate ( void * ctx )

static

Tells whether a flash write may run now.

Parameters

ctx

Unused.

Returns

True when a flash window is open and the busy check allows it.

io_program()

bool io_program ( void * ctx, uint32_t off, const uint8_t * data )

static

Programs one sector of the slot being written.

Parameters

ctx	Unused.
off	Offset within the slot, in bytes. An offset of IOMCU_SLOT_BYTES or more is refused.
data	The sector contents.

Returns

True when the program ran.

io_restart()

void io_restart ( void * ctx )

static

Restarts into the slot just written, as a flash update boot. This function does not return.

Parameters

ctx

Unused.

partition_at()

bool partition_at ( unsigned n, uint32_t * start, uint32_t * bytes )

static

Where partition n of the table the boot ROM holds starts and how many bytes it spans; false without one.

Parameters

n	Partition number, 0 or 1.
start	Receives the start offset in bytes from flash 0.
bytes	Receives the length of the partition, in bytes.

Returns

True when the boot ROM holds the partition.

update_hw_ctl_read()

void update_hw_ctl_read	(	void *	ctx,
		uint8_t	off,
		uint8_t	n,
		uint16_t *	out )

The two pages' handlers, for the link_page_t table.

Parameters

ctx	Unused.
off	First register to read.
n	Number of registers to read.
out	Receives the register values.

update_hw_ctl_write()

uint8_t update_hw_ctl_write	(	void *	ctx,
		uint8_t	off,
		uint8_t	n,
		const uint16_t *	in )

Writes the UPDATE_CTL page, for the link_page_t table.

Parameters

ctx	Unused.
off	First register to write.
n	Number of registers to write.
in	The register values to write.

Returns

0 to accept, or a link_nack_t to refuse.

update_hw_data_read()

void update_hw_data_read	(	void *	ctx,
		uint8_t	off,
		uint8_t	n,
		uint16_t *	out )

Reads the UPDATE_DATA page, for the link_page_t table.

Parameters

ctx	Unused.
off	First register to read.
n	Number of registers to read.
out	Receives the register values.

update_hw_data_write()

uint8_t update_hw_data_write	(	void *	ctx,
		uint8_t	off,
		uint8_t	n,
		const uint16_t *	in )

Writes the UPDATE_DATA page, for the link_page_t table.

Parameters

ctx	Unused.
off	First register to write.
n	Number of registers to write.
in	The register values to write.

Returns

0 to accept, or a link_nack_t to refuse.

update_hw_holds_arm()

bool update_hw_holds_arm

(

void

)

True while ARM is refused: an update session or an image on trial.

Returns

True when ARM is refused.

update_hw_init()

void update_hw_init

(

bool(*

busy )(void)

)

Read the boot ROM's word on this boot – which slot runs, whether it is on trial – and check the partition table against the layout this build has.

busy says whether flash may not be written now: the bank driving, the supply on, a servo programming session.

Parameters

busy	Returns true while flash may not be written now.

update_hw_on_trial()

bool update_hw_on_trial

(

void

)

For the console: whether the running image waits for its BUY.

Returns

True when the running image is on trial.

update_hw_poll()

void update_hw_poll

(

uint32_t

now_ms

)

Once per pass: a slice of a hash, the restart after ACTIVATE, an owed erase of the other slot's first sector, the end of a session that has had no update request for 5s.

Parameters

now_ms

The pass's clock in ms.

update_hw_refuses_arm()

bool update_hw_refuses_arm	(	uint8_t	off,
		uint8_t	n,
		const uint16_t *	in )

Whether a CONTROL write is refused for the update (link_update_dev.h).

Parameters

off	First register of the write.
n	Number of registers in the write.
in	The register values of the write.

Returns

True when the write is refused.

update_hw_slot()

int update_hw_slot

(

void

)

For the console: the slot running, 0 or 1, or -1 without a table.

Returns

The slot running, 0 or 1, or -1 without a partition table.