link_update_image.h File Reference

What both ends of the IOmcu update need to know about an RP2350 image: where its TBYB (try before you buy) flag is, and the hash that names a build whatever that flag says. More...

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

Go to the source code of this file.

Data Structures
struct	link_image_hash_t
	A SHA-256 over len bytes fed in pieces, the byte at flag_at read with LINK_IMAGE_TBYB_BIT set or clear as flag_set says (-1: every byte as it is). More...

Macros
#define	LINK_IMAGE_SCAN_BYTES   4096u
	The first block of the loop starts in the image's first 4KiB.
#define	LINK_IMAGE_MAX_BLOCKS   8u
	Blocks followed before a loop that has not closed is given up on.
#define	LINK_IMAGE_TBYB_BIT   0x80u
	The TBYB flag's bit in the byte link_update_tbyb_byte() names.

Functions
int32_t	link_update_tbyb_byte (const uint8_t *img, uint32_t len)
	The byte offset of the TBYB flag in img: byte 3 of the IMAGE_TYPE item of the last IMAGE_DEF block of the block loop. -1 when the first 4KiB hold no block loop that closes inside len bytes, or no block of it is an IMAGE_DEF.
void	link_image_hash_begin (link_image_hash_t *h, uint32_t len, int32_t flag_at, bool flag_set)
	Start a hash of an image.
uint8_t	link_image_byte (const uint8_t *img, uint32_t at, int32_t flag_at, bool flag_set)
	The byte at at of img as the hash and the transfer read it: the TBYB bit set or cleared at flag_at, as flag_set says.
bool	link_image_hash_step (link_image_hash_t *h, const uint8_t *src, uint32_t n)
	Fold in up to n bytes from src, which holds the image's bytes from h->pos on.
void	link_image_hash_end (link_image_hash_t *h, uint8_t out[LINK_SHA256_BYTES])
	Write the digest; only meaningful once link_image_hash_step() said so.
void	link_update_build_hash (const uint8_t *img, uint32_t len, uint8_t out[LINK_SHA256_BYTES])
	The SHA-256 that names the build in img: every byte, the TBYB flag read as clear.

Detailed Description

What both ends of the IOmcu update need to know about an RP2350 image: where its TBYB (try before you buy) flag is, and the hash that names a build whatever that flag says.

An RP2350 image carries its metadata in a loop of picobin blocks, the first inside its first 4KiB. The boot ROM uses the last IMAGE_DEF block of the loop, and that block's IMAGE_TYPE item holds the TBYB flag in bit 15 of its flags: byte 3 of the item, bit 7. The build seals the image with a SHA-256 hash in that last block, computed with the flag read as clear, so the flag can be set after the build without breaking the hash.

No image this build makes carries the flag. The panel sets it in the copy it sends, and the boot ROM clears it in flash when the IOmcu buys the image. A build is therefore named by the SHA-256 of its bytes with that one bit read as clear: the image in the release, the copy on trial and the copy bought all hash the same.

Pure C, fed a pointer and a length.

SPDX-License-Identifier: MIT

Function Documentation

link_image_byte()

uint8_t link_image_byte	(	const uint8_t *	img,
		uint32_t	at,
		int32_t	flag_at,
		bool	flag_set )

The byte at at of img as the hash and the transfer read it: the TBYB bit set or cleared at flag_at, as flag_set says.

Parameters

img	The image bytes; NULL gives 0xFF.
at	Offset of the byte.
flag_at	Offset of the flag byte, or -1 for none.
flag_set	true to set the TBYB bit at flag_at, false to clear it.

Returns

The byte, with the TBYB bit forced when at is flag_at.

link_image_hash_begin()

void link_image_hash_begin	(	link_image_hash_t *	h,
		uint32_t	len,
		int32_t	flag_at,
		bool	flag_set )

Start a hash of an image.

Parameters

h	The hash state to set up; NULL is ignored.
len	Length of the image in bytes.
flag_at	Offset of the flag byte, or -1 for none.
flag_set	true to set the TBYB bit at flag_at, false to clear it.

link_image_hash_end()

void link_image_hash_end	(	link_image_hash_t *	h,
		uint8_t	out[LINK_SHA256_BYTES] )

Write the digest; only meaningful once link_image_hash_step() said so.

Parameters

h	The hash state.
out	Receives the 32-byte digest.

link_image_hash_step()

bool link_image_hash_step	(	link_image_hash_t *	h,
		const uint8_t *	src,
		uint32_t	n )

Fold in up to n bytes from src, which holds the image's bytes from h->pos on.

No more than the bytes left are taken. True once all len bytes are in.

Parameters

h	The hash state, from link_image_hash_begin().
src	The next bytes of the image; NULL takes nothing.
n	Number of bytes offered in src.

Returns

true once all len bytes are in.

link_update_build_hash()

void link_update_build_hash	(	const uint8_t *	img,
		uint32_t	len,
		uint8_t	out[LINK_SHA256_BYTES] )

The SHA-256 that names the build in img: every byte, the TBYB flag read as clear.

In one call, for an image in memory.

Parameters

img	Image bytes.
len	Length of img in bytes.
out	Receives the 32-byte digest.

link_update_tbyb_byte()

int32_t link_update_tbyb_byte	(	const uint8_t *	img,
		uint32_t	len )

The byte offset of the TBYB flag in img: byte 3 of the IMAGE_TYPE item of the last IMAGE_DEF block of the block loop. -1 when the first 4KiB hold no block loop that closes inside len bytes, or no block of it is an IMAGE_DEF.

Parameters

img	The image bytes; NULL gives -1.
len	Length of img in bytes.

Returns

The offset of the flag byte, or -1.