SUIT firmware worker thread

Detailed Description

SUIT secure firmware updates worker thread

SUIT CoAP helper API

Author

Kaspar Schleiser kaspa.nosp@m.r@sc.nosp@m.hleis.nosp@m.er.d.nosp@m.e

Francisco Molina franc.nosp@m.ois-.nosp@m.xavie.nosp@m.r.mo.nosp@m.lina@.nosp@m.inri.nosp@m.a.fr

Alexandre Abadie alexa.nosp@m.ndre.nosp@m..abad.nosp@m.ie@i.nosp@m.nria..nosp@m.fr

Functions
bool	suit_worker_trigger (const char *url, size_t len)
	Trigger a SUIT update via a worker thread.
void	suit_worker_trigger_prepared (const uint8_t *manifest, size_t size)
	Trigger a SUIT update via a worker thread.
int	suit_worker_try_prepare (uint8_t **buffer, size_t *size)
	Prepare for a worker run with a preloaded manifest.
void	suit_worker_done_cb (int res)
	Callback that is executed after the SUIT process has finished.
int	suit_handle_url (const char *url)
	Trigger a SUIT update.
int	suit_handle_manifest_buf (const uint8_t *buffer, size_t size)
	Trigger a SUIT update on an in-memory manifest.

Function Documentation

suit_handle_manifest_buf()

int suit_handle_manifest_buf	(	const uint8_t *	buffer,
		size_t	size )

Trigger a SUIT update on an in-memory manifest.

Note

Make sure the thread calling this function has enough stack space to fit a whole flash page.

This function accesses global state shared with suit_handle_url; only one of those may be called at the same time. You may use suit_worker_try_prepare / suit_worker_trigger_prepared instead, which manage locking and also do away with the stack space requirement by being executed on an own stack.

Parameters

[in]	buffer	Memory area containing a SUIT manifest.
[in]	size	Size of the manifest in buffer.

Returns

0 on success <0 on error

suit_handle_url()

int suit_handle_url

(

const char *

url

)

Trigger a SUIT update.

Note

Make sure the thread calling this function has enough stack space to fit a whole flash page.

This function accesses global state shared with suit_handle_manifest_buf; only one of those may be called at the same time. You may use suit_worker_trigger instead, which manages locking and also does away with the stack space requirement by being executed on an own stack.

Parameters

[in]

url

url pointer containing the full coap url to the manifest

Returns

0 on success <0 on error

suit_worker_done_cb()

void suit_worker_done_cb

(

int

res

)

Callback that is executed after the SUIT process has finished.

Parameters

[in]

res

Result of the SUIT update, 0 on success

By default this will reboot the board, can be overwritten by the application.

suit_worker_trigger()

bool suit_worker_trigger	(	const char *	url,
		size_t	len )

Trigger a SUIT update via a worker thread.

Parameters

[in]	url	url pointer containing the full coap url to the manifest
[in]	len	length of the url

Return values

true	if the worker was triggered
false	if the worker is already busy

suit_worker_trigger_prepared()

void suit_worker_trigger_prepared	(	const uint8_t *	manifest,
		size_t	size )

Trigger a SUIT update via a worker thread.

Precondition

The caller called suit_worker_try_prepare to obtain the buf, and populated size bytes into it.

This can be called with a size of 0 when writing a manifest was started, but could not be completed.

Parameters

[in]	manifest	Pointer to the manifest. This must be the return value of a previous call to suit_worker_try_prepare, and is invalidated at some point during or after the call.
[in]	size	Number of bytes that have been prepared in the buffer before the call.

suit_worker_try_prepare()

int suit_worker_try_prepare	(	uint8_t **	buffer,
		size_t *	size )

Prepare for a worker run with a preloaded manifest.

This obtains a lock on the SUIT worker, and provides a pointer to a memory area into which the manifest is to be written. The lock must be released by calling suit_worker_trigger_prepared later.

Parameters

[out]	buffer	On success, buffer into which the image may be written.
[in,out]	size	Requested buffer size. On some errors, this will be decreased to a size that would be acceptable.

Returns

0 on success

-EAGAIN if the worker is currently busy.

-ENOMEM if the worker is available but the requested size is too large. (In this case, an acceptable size is indicated in size).

Note

There is no blocking version of this (it behaves like mutex_trylock, not like mutex_lock). This allows a simpler implementation on the thread handling side , and is also what typical use cases need.