Put bytes storage

Backends storing received objects. More...

Modules
	File storage
	Backend writing objects to PFS files.
	Put bytes storage backend interface
	Operations implemented by each storage backend.
	Raw flash storage
	Backend writing firmware, recovery and system resources to flash.

Data Structures
struct	PutBytesStorage
	Storage of an object being received. More...
struct	PutBytesStorageInfo
	Object information passed to pb_storage_init(). More...

Enumerations
enum	PutBytesCrcType { PutBytesCrcType_Legacy = 0 , PutBytesCrcType_CRC32 }
	CRC algorithms. More...

Functions
void	pb_storage_write (PutBytesStorage *storage, uint32_t offset, const uint8_t *buffer, uint32_t length)
	Write data at an offset, without moving PutBytesStorage::current_offset.
void	pb_storage_append (PutBytesStorage *storage, const uint8_t *buffer, uint32_t length)
	Append data at PutBytesStorage::current_offset and advance it.
uint32_t	pb_storage_calculate_crc (PutBytesStorage *storage, PutBytesCrcType crc_type)
	Compute the CRC of the data written so far.
bool	pb_storage_init (PutBytesStorage *storage, PutBytesObjectType object_type, uint32_t total_size, PutBytesStorageInfo *info, uint32_t append_offset)
	Initialize storage for a new transfer.
void	pb_storage_deinit (PutBytesStorage *storage, bool is_success)
	Release storage after a transfer.
bool	pb_storage_get_status (PutBytesObjectType obj_type, PbInstallStatus *status)
	Recover the progress of a partially written object.

Detailed Description

Backends storing received objects.

Firmware, recovery and system resources use the raw flash backend, other objects the PFS file backend (not built in recovery firmware).

---

Data Structure Documentation

PutBytesStorage

struct PutBytesStorage

Storage of an object being received.

Data Fields
uint32_t	current_offset	Offset of the next append, advanced by pb_storage_append(). Set by pb_storage_init(), e.g. past a metadata header or to the append offset.
const PutBytesStorageImplementation *	impl	Backend operations, NULL when not initialized.
void *	impl_data	Backend private data.

PutBytesStorageInfo

struct PutBytesStorageInfo

Object information passed to pb_storage_init().

Data Fields
char	filename[]	NUL-terminated file name of file objects.
int	index	Bank index of raw objects.

Enumeration Type Documentation

PutBytesCrcType

enum PutBytesCrcType

CRC algorithms.

Enumerator
PutBytesCrcType_Legacy	Legacy checksum, see pbl_crc32_legacy().
PutBytesCrcType_CRC32	CRC-32, see pbl_crc32(). Raw backend only.

Function Documentation

pb_storage_append()

void pb_storage_append	(	PutBytesStorage *	storage,
		const uint8_t *	buffer,
		uint32_t	length
	)

Append data at PutBytesStorage::current_offset and advance it.

Parameters

storage	Storage.
buffer	Data.
length	Length of buffer in bytes.

pb_storage_calculate_crc()

uint32_t pb_storage_calculate_crc	(	PutBytesStorage *	storage,
		PutBytesCrcType	crc_type
	)

Compute the CRC of the data written so far.

Covers the data up to PutBytesStorage::current_offset, excluding any metadata header.

Parameters

storage	Storage.
crc_type	CRC algorithm.

Returns

CRC.

pb_storage_deinit()

void pb_storage_deinit	(	PutBytesStorage *	storage,
		bool	is_success
	)

Release storage after a transfer.

Does nothing if the storage is not initialized. A failed file transfer deletes the file.

Parameters

storage	Storage.
is_success	Whether the transfer succeeded.

pb_storage_get_status()

bool pb_storage_get_status	(	PutBytesObjectType	obj_type,
		PbInstallStatus *	status
	)

Recover the progress of a partially written object.

Only supported for firmware, recovery and system resources.

Parameters

	obj_type	Object type.
[out]	status	Bytes written and their CRC.

Returns

true if status was filled in.

pb_storage_init()

bool pb_storage_init	(	PutBytesStorage *	storage,
		PutBytesObjectType	object_type,
		uint32_t	total_size,
		PutBytesStorageInfo *	info,
		uint32_t	append_offset
	)

Initialize storage for a new transfer.

Selects the backend for object_type and rejects objects larger than it can hold.

Parameters

[out]	storage	Storage, zeroed beforehand.
	object_type	Object type.
	total_size	Object size in bytes.
	info	Object information.
	append_offset	If non-zero, resume a previously interrupted transfer at this offset instead of starting over.

Returns

true on success.

pb_storage_write()

void pb_storage_write	(	PutBytesStorage *	storage,
		uint32_t	offset,
		const uint8_t *	buffer,
		uint32_t	length
	)

Write data at an offset, without moving PutBytesStorage::current_offset.

The file backend only supports writing at the current offset.

Parameters

storage	Storage.
offset	Offset within the storage.
buffer	Data.
length	Length of buffer in bytes.