link_update_image.c File Reference

The picobin block loop, as the RP2350 datasheet sections 5.1.5 and 5.9.1 describe it: a block opens with PICOBIN_BLOCK_MARKER_START (0xffffded3), holds items, closes its item list with a LAST item that counts their words, then a word with the signed byte offset of the next block and the marker 0xab123579. More...

#include "link_update_image.h"
#include <stddef.h>
#include <string.h>

Macros
#define	MARKER_START   0xffffded3u
#define	MARKER_END   0xab123579u
#define	ITEM_IMAGE_TYPE   0x42u
#define	ITEM_LAST   0xffu
#define	ITEM_SIZE_2BYTES   0x80u
#define	MAX_BLOCK_BYTES   0x280u
	The largest block the boot ROM reads (PICOBIN_MAX_BLOCK_SIZE).

Functions
static uint32_t	word_at (const uint8_t *p, uint32_t at)
	Read a 32-bit little-endian word.
static bool	parse_block (const uint8_t *img, uint32_t len, uint32_t at, int64_t *next, int32_t *image_type)
	The block at at: true when it is whole inside len, with the offset of the next block in next and of its IMAGE_TYPE item in image_type (-1 for none).
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.
static uint8_t	flagged (uint8_t v, bool set)
	Set or clear the TBYB bit of a 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.
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

The picobin block loop, as the RP2350 datasheet sections 5.1.5 and 5.9.1 describe it: a block opens with PICOBIN_BLOCK_MARKER_START (0xffffded3), holds items, closes its item list with a LAST item that counts their words, then a word with the signed byte offset of the next block and the marker 0xab123579.

An item's first byte is its type; bit 7 of the type says its size in words is the 16-bit field in bytes 1 and 2 rather than byte 1.

SPDX-License-Identifier: MIT

Function Documentation

flagged()

uint8_t flagged ( uint8_t v, bool set )

static

Set or clear the TBYB bit of a byte.

Parameters

v	The byte.
set	true to set LINK_IMAGE_TBYB_BIT, false to clear it.

Returns

The byte with the bit forced.

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.

parse_block()

bool parse_block ( const uint8_t * img, uint32_t len, uint32_t at, int64_t * next, int32_t * image_type )

static

The block at at: true when it is whole inside len, with the offset of the next block in next and of its IMAGE_TYPE item in image_type (-1 for none).

Parameters

img	The image bytes.
len	Length of img in bytes.
at	Offset of the block's start marker; a multiple of 4.
next	Receives the offset of the next block.
image_type	Receives the offset of the IMAGE_TYPE item, or -1.

Returns

true when the block is whole inside len, else false.

word_at()

uint32_t word_at ( const uint8_t * p, uint32_t at )

static

Read a 32-bit little-endian word.

Parameters

p	The image bytes.
at	Offset of the word.

Returns

The word.