K-FSW lightweight firmware upload

Data Structures
struct	kfsw_fwu_lite_message

Macros
#define	KFSW_FWU_LITE_HEADER_SIZE   12U
#define	KFSW_FWU_LITE_MAX_BLOCK_SIZE   CONFIG_KFSW_FWU_LITE_BLOCK_SIZE

Enumerations
enum	kfsw_fwu_lite_opcode {   KFSW_FWU_LITE_OP_BEGIN = 1 , KFSW_FWU_LITE_OP_BLOCK = 2 , KFSW_FWU_LITE_OP_STATUS = 3 , KFSW_FWU_LITE_OP_VERIFY = 4 ,   KFSW_FWU_LITE_OP_START_FLASHING = 5 , KFSW_FWU_LITE_OP_ABORT = 6 }
enum	kfsw_fwu_lite_status {   KFSW_FWU_LITE_STATUS_OK = 0 , KFSW_FWU_LITE_STATUS_INVALID = 1 , KFSW_FWU_LITE_STATUS_OUT_OF_ORDER = 2 , KFSW_FWU_LITE_STATUS_BAD_BLOCK = 3 ,   KFSW_FWU_LITE_STATUS_BAD_IMAGE = 4 , KFSW_FWU_LITE_STATUS_TOO_LARGE = 5 , KFSW_FWU_LITE_STATUS_BUSY = 6 , KFSW_FWU_LITE_STATUS_FAILED = 7 }

Functions
int	kfsw_fwu_lite_encode (const struct kfsw_fwu_lite_message *message, uint8_t *buffer, size_t buffer_size, size_t *encoded_size)
int	kfsw_fwu_lite_decode (const uint8_t *buffer, size_t size, struct kfsw_fwu_lite_message *message)
int	kfsw_fwu_lite_handle (const struct kfsw_fwu_lite_message *request, struct kfsw_fwu_lite_message *reply)
const char *	kfsw_fwu_lite_status_name (uint8_t status)

Description

Uploads firmware in checksummed blocks over CSP, with retries.

It shares the update service with FTP; concurrent uploads return busy. RDP is optional and off by default.

Macro Documentation

KFSW_FWU_LITE_HEADER_SIZE

#define KFSW_FWU_LITE_HEADER_SIZE   12U

#include <fwu_lite.h>

Fixed header on every request and reply, big-endian on the wire.

KFSW_FWU_LITE_MAX_BLOCK_SIZE

#define KFSW_FWU_LITE_MAX_BLOCK_SIZE   CONFIG_KFSW_FWU_LITE_BLOCK_SIZE

#include <fwu_lite.h>

Largest block payload this build accepts.

Enumeration Documentation

kfsw_fwu_lite_opcode

enum kfsw_fwu_lite_opcode

#include <fwu_lite.h>

Wire opcodes.

Requests carry the low value; replies echo it.

Enumerator
KFSW_FWU_LITE_OP_BEGIN	Declare size and whole-image checksum; erases the slot.
KFSW_FWU_LITE_OP_BLOCK	Carry one block of image bytes with its own checksum.
KFSW_FWU_LITE_OP_STATUS	Report transfer state and the block expected next.
KFSW_FWU_LITE_OP_VERIFY	Check the received image against the declared checksum.
KFSW_FWU_LITE_OP_START_FLASHING	Offer the verified image to the bootloader for the next boot.
KFSW_FWU_LITE_OP_ABORT	Abandon the transfer and erase the slot.

kfsw_fwu_lite_status

enum kfsw_fwu_lite_status

#include <fwu_lite.h>

Reply status values.

Distinct from errno so the wire meaning is stable.

Enumerator
KFSW_FWU_LITE_STATUS_INVALID	The request was malformed or arrived in the wrong state.
KFSW_FWU_LITE_STATUS_OUT_OF_ORDER	The block index was not the one expected next.
KFSW_FWU_LITE_STATUS_BAD_BLOCK	The block failed its own checksum; send that block again.
KFSW_FWU_LITE_STATUS_BAD_IMAGE	The image failed its whole-image checksum.
KFSW_FWU_LITE_STATUS_TOO_LARGE	The image does not fit the slot.
KFSW_FWU_LITE_STATUS_BUSY	A transfer is already running.
KFSW_FWU_LITE_STATUS_FAILED	The node could not write flash or reach its bootloader.

Function Documentation

kfsw_fwu_lite_decode()

int kfsw_fwu_lite_decode	(	const uint8_t *	buffer,
		size_t	size,
		struct kfsw_fwu_lite_message *	message
	)

#include <fwu_lite.h>

Decode a message from a buffer.

The decoded data points into buffer and is valid only while it is.

Parameters

	buffer	Source bytes.
	size	Bytes available.
[out]	message	Decoded message.

Return values

0	Decoded.
-EINVAL	A pointer is NULL.
-EBADMSG	The buffer is shorter than a header, or the opcode is not one this build knows.
-EMSGSIZE	The payload is larger than the block size.

kfsw_fwu_lite_encode()

int kfsw_fwu_lite_encode	(	const struct kfsw_fwu_lite_message *	message,
		uint8_t *	buffer,
		size_t	buffer_size,
		size_t *	encoded_size
	)

#include <fwu_lite.h>

Encode a message into a buffer.

Parameters

	message	Message to encode.
	buffer	Destination.
	buffer_size	Bytes available.
[out]	encoded_size	Bytes written.

Return values

0	Encoded.
-EINVAL	A pointer is NULL.
-EMSGSIZE	The payload does not fit, or exceeds the block size.

kfsw_fwu_lite_handle()

int kfsw_fwu_lite_handle	(	const struct kfsw_fwu_lite_message *	request,
		struct kfsw_fwu_lite_message *	reply
	)

#include <fwu_lite.h>

Apply a decoded request and produce the reply.

A rejected request returns a reply with the error status.

Parameters

	request	Decoded request.
[out]	reply	Reply to send back.

Return values

0	A reply was produced, whatever its status.
-EINVAL	A pointer is NULL.

kfsw_fwu_lite_status_name()

const char * kfsw_fwu_lite_status_name

(

uint8_t

status

)

#include <fwu_lite.h>

Human-readable name for a reply status.

Parameters

status

One of kfsw_fwu_lite_status.

Returns

A stable lowercase name; "unknown" for an unrecognised value.