fw_image.c File Reference

The panel's application image. See fw_image.h. More...

#include "fw_image.h"
#include <string.h>

Macros
#define	OFF_SEGMENTS   1u
#define	OFF_CHIP   12u
#define	OFF_HASHED   23u
#define	HEADER_BYTES   24u
#define	SEGHEAD_BYTES   8u
#define	OFF_DESC   (HEADER_BYTES + SEGHEAD_BYTES)
#define	DESC_BYTES   256u
#define	OFF_VERSION   (OFF_DESC + 16u)
#define	OFF_PROJECT   (OFF_DESC + 48u)
#define	OFF_ELF_SHA   (OFF_DESC + 144u)

Functions
static uint32_t	le32 (const uint8_t *p)
	Reads 4 bytes at p as a little-endian number.
static uint16_t	le16 (const uint8_t *p)
	Reads 2 bytes at p as a little-endian number.
const char *	fw_err_str (fw_err_t e)
	The English name of e, for the console.
bool	fw_version_parse (const char *text, size_t n, fw_version_t *out)
	Parses "MAJOR.MINOR.PATCH" from at most n bytes of text: digits only, each number 0 to 65535, terminated by '\0' or by the end of the field.
int	fw_version_cmp (fw_version_t a, fw_version_t b)
	Compares two versions.
fw_err_t	fw_image_head (const uint8_t *head, uint32_t have, uint32_t bytes, uint32_t slot, fw_image_info_t *out)
	Checks the first have bytes of an image of bytes in all, for a slot of slot bytes: size, magic, chip, descriptor, project and version.
static uint32_t	image_length (const uint8_t *img, uint32_t bytes)
	The length the segment table gives: the header, each segment's header and data, the checksum byte padded to 16, and the hash. 0 when a segment runs past bytes, which is a file cut short.
fw_err_t	fw_image_check (const uint8_t *img, uint32_t bytes, uint32_t slot, fw_image_info_t *out)
	Checks a whole image of bytes at img for a slot of slot bytes: everything fw_image_head() checks, then that the segments add up to the image's length and that the last 32 bytes are the SHA-256 of all bytes before them.
fw_offer_t	fw_offer (const fw_image_info_t *running, const fw_image_info_t *image)
	Classifies a checked image against the panel running now.
bool	fw_offer_installable (fw_offer_t o)
	Whether an offer is one INSTALL may act on.

Detailed Description

The panel's application image. See fw_image.h.

SPDX-License-Identifier: MIT

Macro Definition Documentation

DESC_BYTES

#define DESC_BYTES   256u

application descriptor, bytes

HEADER_BYTES

#define HEADER_BYTES   24u

image header, bytes

OFF_CHIP

#define OFF_CHIP   12u

chip ID, 2 bytes

OFF_DESC

#define OFF_DESC   (HEADER_BYTES + SEGHEAD_BYTES)

application descriptor, 32

OFF_ELF_SHA

#define OFF_ELF_SHA   (OFF_DESC + 144u)

the ELF file's SHA-256, at 176

OFF_HASHED

#define OFF_HASHED   23u

hash-appended flag

OFF_PROJECT

#define OFF_PROJECT   (OFF_DESC + 48u)

project name, at 80

OFF_SEGMENTS

#define OFF_SEGMENTS   1u

segment count

OFF_VERSION

#define OFF_VERSION   (OFF_DESC + 16u)

version text, at 48

SEGHEAD_BYTES

#define SEGHEAD_BYTES   8u

one segment header, bytes

Function Documentation

fw_err_str()

const char * fw_err_str

(

fw_err_t

e

)

The English name of e, for the console.

Parameters

e	the result

Returns

the name, static

fw_image_check()

fw_err_t fw_image_check	(	const uint8_t *	img,
		uint32_t	bytes,
		uint32_t	slot,
		fw_image_info_t *	out )

Checks a whole image of bytes at img for a slot of slot bytes: everything fw_image_head() checks, then that the segments add up to the image's length and that the last 32 bytes are the SHA-256 of all bytes before them.

out is filled on FW_OK.

Parameters

img	the image
bytes	the length of the image
slot	the size of the slot, bytes
out	what the image says about itself

Returns

FW_OK or the first check that failed

fw_image_head()

fw_err_t fw_image_head	(	const uint8_t *	head,
		uint32_t	have,
		uint32_t	bytes,
		uint32_t	slot,
		fw_image_info_t *	out )

Checks the first have bytes of an image of bytes in all, for a slot of slot bytes: size, magic, chip, descriptor, project and version.

The length and the hash need the whole image and are not checked. have below FW_HEAD_BYTES with bytes at or above it reads as the source failing (FW_ERR_READ). out is filled on FW_OK.

Parameters

head	the first bytes of the image
have	the number of bytes at head
bytes	the length of the image
slot	the size of the slot, bytes
out	what the image says about itself

Returns

FW_OK or the first check that failed

fw_offer()

fw_offer_t fw_offer	(	const fw_image_info_t *	running,
		const fw_image_info_t *	image )

Classifies a checked image against the panel running now.

Parameters

running	the running image
image	the image offered

Returns

what the image is to the panel

fw_offer_installable()

bool fw_offer_installable

(

fw_offer_t

o

)

Whether an offer is one INSTALL may act on.

Parameters

o

the offer

Returns

true when INSTALL may act on it

fw_version_cmp()

int fw_version_cmp	(	fw_version_t	a,
		fw_version_t	b )

Compares two versions.

Parameters

a	the first version
b	the second version

Returns

negative, zero or positive as a is older, the same or newer

fw_version_parse()

bool fw_version_parse	(	const char *	text,
		size_t	n,
		fw_version_t *	out )

Parses "MAJOR.MINOR.PATCH" from at most n bytes of text: digits only, each number 0 to 65535, terminated by '\0' or by the end of the field.

Anything else ("4184795", "0.19.0-dirty", "1..2") is false.

Parameters

text	the version text
n	the bytes of text that may be read
out	the version, written on success

Returns

true when the text parses