K-FSW firmware update

Data Structures
struct	kfsw_fwu_status

Enumerations
enum	kfsw_fwu_state {   KFSW_FWU_IDLE = 0 , KFSW_FWU_RECEIVING = 1 , KFSW_FWU_READY = 2 , KFSW_FWU_FAILED = 3 ,   KFSW_FWU_VERIFIED = 4 }

Functions
uint32_t	kfsw_fwu_max_image_size (void)
uint32_t	kfsw_fwu_slot_write_offset (void)
int	kfsw_fwu_begin (uint32_t total_size, uint32_t expected_crc32)
int	kfsw_fwu_write (uint32_t offset, const void *data, size_t size)
int	kfsw_fwu_verify (void)
int	kfsw_fwu_files_mount (void)
int	kfsw_fwu_finish (void)
int	kfsw_fwu_abort (void)
int	kfsw_fwu_get_status (struct kfsw_fwu_status *status)
const char *	kfsw_fwu_state_name (enum kfsw_fwu_state state)

Description

Receives a firmware image into the secondary image slot and asks the bootloader to try it on the next boot.

Images are written directly to flash. With KFSW_FWU_FILES, both slots are also available as read-only files, without using data filesystem space. The service handles the MCUboot write offset and checks upgrade scheduling.

The CRC32 catches corruption in transit, not tampering. Authenticity is the bootloader's signature check.

Enumeration Documentation

kfsw_fwu_state

enum kfsw_fwu_state

#include <fwu.h>

Transfer state.

Enumerator
KFSW_FWU_IDLE	No transfer in progress.
KFSW_FWU_RECEIVING	A transfer has begun and is accepting data.
KFSW_FWU_READY	Fully received, verified, and offered to the bootloader.
KFSW_FWU_FAILED	The transfer failed; call kfsw_fwu_abort before retrying.
KFSW_FWU_VERIFIED	Checked and flushed to flash; no upgrade requested yet.

Function Documentation

kfsw_fwu_abort()

int kfsw_fwu_abort

(

void

)

#include <fwu.h>

Abandon a transfer and return to idle.

On success the secondary slot is erased. If cleanup fails, the service retains its transfer details in the failed state; call again to retry. Erasing the rollback image during a trial boot is refused.

Return values

0	Cleanup completed, or no target partition is bound.
-EBUSY	A secondary-slot reader is open.

Returns

A negative errno from flash on cleanup failure.

kfsw_fwu_begin()

int kfsw_fwu_begin	(	uint32_t	total_size,
		uint32_t	expected_crc32
	)

#include <fwu.h>

Begin receiving an image, erasing whatever the slot held.

Parameters

total_size	Image size in bytes.
expected_crc32	CRC32 (IEEE, as produced by Zephyr's crc32_ieee) over the whole image.

Return values

0	The slot is ready to receive.
-ENODEV	No target partition is bound.
-EINVAL	total_size is zero.
-EFBIG	total_size exceeds kfsw_fwu_max_image_size.
-EBUSY	A transfer is receiving, a secondary reader is open, or MCUboot still needs the previous image for trial rollback.

Returns

A negative errno value from the flash layer on failure.

kfsw_fwu_files_mount()

int kfsw_fwu_files_mount

(

void

)

#include <fwu.h>

Mount read-only MCUboot images at /kfsw/boot.

firmware_1.bin reads slot0; firmware_2.bin reads slot1. Files contain the image header, payload, and TLVs, excluding slot padding and swap metadata. A secondary reader blocks erase and upgrade requests until it closes. Image visibility checks structure, not the bootloader's signature policy. Call once during service startup, before exposing file transfers.

Returns

0 on success, or a negative errno on failure.

kfsw_fwu_finish()

int kfsw_fwu_finish

(

void

)

#include <fwu.h>

Verify the received image and offer it to the bootloader.

On success the image is marked to be tried once. It becomes permanent only if it confirms itself after booting; otherwise the bootloader restores the previous image.

Return values

0	The image was accepted and a swap is scheduled.
-EINVAL	No transfer is receiving or verified.
-EBUSY	A secondary-slot reader is open.
-EAGAIN	Fewer bytes were received than declared.
-EILSEQ	The CRC32 does not match what the sender declared.
-EIO	The bootloader did not schedule a swap despite being asked.

Returns

A negative errno value from the flash layer on failure.

kfsw_fwu_get_status()

int kfsw_fwu_get_status

(

struct kfsw_fwu_status *

status

)

#include <fwu.h>

Read a consistent snapshot of the update state.

Parameters

[out]

status

Destination snapshot.

Return values

0	The snapshot was written.
-EINVAL	status is NULL.

kfsw_fwu_max_image_size()

uint32_t kfsw_fwu_max_image_size

(

void

)

#include <fwu.h>

Largest image the target slot can hold, in bytes.

Smaller than the partition: the swap offset costs one sector at the start, and the bootloader needs its trailer at the end.

Returns

The maximum image size, or zero when no target is bound.

kfsw_fwu_slot_write_offset()

uint32_t kfsw_fwu_slot_write_offset

(

void

)

#include <fwu.h>

Byte offset within the target partition where an image is written.

Non-zero because of the bootloader's swap mode.

Returns

The offset in bytes.

kfsw_fwu_state_name()

const char * kfsw_fwu_state_name

(

enum kfsw_fwu_state

state

)

#include <fwu.h>

Human-readable name for a state, for shells and logs.

Parameters

state

One of kfsw_fwu_state.

Returns

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

kfsw_fwu_verify()

int kfsw_fwu_verify

(

void

)

#include <fwu.h>

Check the transfer CRC and flush all received bytes to flash.

Does not schedule a boot. Repeated verification of a verified transfer succeeds. Further writes are rejected until a new transfer begins.

Return values

0	The complete image is available in flash.
-EINVAL	No transfer is receiving or verified.
-EAGAIN	The transfer is incomplete.
-EILSEQ	The transfer CRC does not match.

Returns

A negative errno from flash on failure.

kfsw_fwu_write()

int kfsw_fwu_write	(	uint32_t	offset,
		const void *	data,
		size_t	size
	)

#include <fwu.h>

Accept the next span of image bytes.

Spans must arrive in order and without gaps.

Parameters

offset	Offset of this span within the image, from zero.
data	Bytes to write.
size	Number of bytes.

Return values

0	The span was accepted.
-EINVAL	data is NULL, size is zero, or no transfer is running.
-ESPIPE	offset is not where the transfer had reached.
-EFBIG	The span would run past the declared image size.

Returns

A negative errno value from the flash layer on failure.