fw_upload.h File Reference

Receiving a panel image into memory, as a source hands it over. More...

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

Go to the source code of this file.

Data Structures
struct	fw_upload_t
	An upload into a buffer the caller owns. More...

Enumerations
enum	fw_up_state_t { FW_UP_IDLE = 0 , FW_UP_RECEIVING , FW_UP_STAGED , FW_UP_FAILED }
	Where an upload is. More...

Functions
void	fw_upload_init (fw_upload_t *u, uint8_t *buf, uint32_t cap, uint32_t slot)
	An upload into buf of cap bytes, for a slot of slot bytes: IDLE.
fw_err_t	fw_upload_begin (fw_upload_t *u, uint32_t bytes)
	A source announces bytes.
fw_err_t	fw_upload_add (fw_upload_t *u, const uint8_t *data, uint32_t len)
	len more bytes.
fw_err_t	fw_upload_end (fw_upload_t *u, bool whole)
	The source is done; the image is checked at once.
fw_err_t	fw_upload_seal (fw_upload_t *u, bool whole)
	The first half of fw_upload_end(), for a check run without the caller's lock: the bytes are whole and wait for fw_image_check() over buf and bytes.
fw_err_t	fw_upload_checked (fw_upload_t *u, fw_err_t e, const fw_image_info_t *info)
	The second half: the answer of the check over a sealed upload.
bool	fw_upload_busy (const fw_upload_t *u)
	Whether the buffer is in use: bytes arriving, or a check under way. A caller frees the buffer of an upload that is neither this nor STAGED.
void	fw_upload_discard (fw_upload_t *u)
	Drop what is received or staged: IDLE. During a check, IDLE once fw_upload_checked() has its answer.
unsigned	fw_upload_percent (const fw_upload_t *u)
	Received of announced.

Detailed Description

Receiving a panel image into memory, as a source hands it over.

The installer (fw_install.h) takes an image already in memory and knows nothing about where it came from. This is the step before it: a source announces how many bytes it will send, then hands them over in pieces of any size, into a buffer the caller owns (PSRAM, pseudo-static random-access memory, on the panel). The Wi-Fi page's upload is one source; nothing here assumes a network or a file system.

Refused before a byte is stored: an announced size of 0 or larger than the slot, a buffer too small, and a second image while one is being received or waits for the operator. A source that breaks off, or sends more than it announced, leaves nothing staged. A whole image is checked at once (fw_image_check()), so what waits for the operator is an image that can be installed or one that says why not.

Not thread-safe: the platform serialises the calls. No flash is touched.

Pure C, no ESP-IDF (Espressif Internet-of-Things Development Framework).

SPDX-License-Identifier: MIT

Enumeration Type Documentation

fw_up_state_t

enum fw_up_state_t

Where an upload is.

Enumerator
FW_UP_IDLE	nothing received or waiting
FW_UP_RECEIVING	bytes are arriving
FW_UP_STAGED	a whole image passed fw_image_check()
FW_UP_FAILED	the last one was refused: see err

Function Documentation

fw_upload_add()

fw_err_t fw_upload_add	(	fw_upload_t *	u,
		const uint8_t *	data,
		uint32_t	len )

len more bytes.

Parameters

u	the upload
data	the bytes
len	how many

Returns

FW_OK; FW_ERR_LENGTH, and FAILED, when they run past the announced size; FW_ERR_BUSY when not RECEIVING or sealed

fw_upload_begin()

fw_err_t fw_upload_begin	(	fw_upload_t *	u,
		uint32_t	bytes )

A source announces bytes.

Parameters

u	the upload
bytes	the image's bytes

Returns

FW_OK and RECEIVING, or why not, with the state unchanged: FW_ERR_BUSY while RECEIVING, sealed or STAGED, FW_ERR_EMPTY for 0, FW_ERR_TOO_BIG over the slot, FW_ERR_MEMORY for a buffer too small

fw_upload_busy()

bool fw_upload_busy

(

const fw_upload_t *

u

)

Whether the buffer is in use: bytes arriving, or a check under way. A caller frees the buffer of an upload that is neither this nor STAGED.

Parameters

u	the upload

Returns

true while RECEIVING or sealed

fw_upload_checked()

fw_err_t fw_upload_checked	(	fw_upload_t *	u,
		fw_err_t	e,
		const fw_image_info_t *	info )

The second half: the answer of the check over a sealed upload.

Parameters

u	the upload
e	what fw_image_check() returned
info	what it filled in

Returns

FW_OK and STAGED, or FAILED with e; FW_ERR_BUSY and IDLE when the upload was discarded during the check, or was not sealed

fw_upload_discard()

void fw_upload_discard

(

fw_upload_t *

u

)

Drop what is received or staged: IDLE. During a check, IDLE once fw_upload_checked() has its answer.

Parameters

u	the upload

fw_upload_end()

fw_err_t fw_upload_end	(	fw_upload_t *	u,
		bool	whole )

The source is done; the image is checked at once.

Parameters

u	the upload
whole	false when the source broke off

Returns

FW_OK and STAGED, or FAILED with the reason: FW_ERR_READ for a source that broke off or sent less than announced, anything fw_image_check() refuses

fw_upload_init()

void fw_upload_init	(	fw_upload_t *	u,
		uint8_t *	buf,
		uint32_t	cap,
		uint32_t	slot )

An upload into buf of cap bytes, for a slot of slot bytes: IDLE.

Parameters

u	the upload
buf	the buffer, or NULL
cap	its bytes
slot	the slot's bytes

fw_upload_percent()

unsigned fw_upload_percent

(

const fw_upload_t *

u

)

Received of announced.

Parameters

u	the upload

Returns

percent, 0 to 100

fw_upload_seal()

fw_err_t fw_upload_seal	(	fw_upload_t *	u,
		bool	whole )

The first half of fw_upload_end(), for a check run without the caller's lock: the bytes are whole and wait for fw_image_check() over buf and bytes.

Between this and fw_upload_checked() the state stays RECEIVING and fw_upload_busy() is true, a fw_upload_discard() included: the buffer is the check's, and no caller frees it.

Parameters

u	the upload
whole	false when the source broke off

Returns

FW_OK and checking set; otherwise what fw_upload_end() returns for the same call, with the same state