Bindesc Read

Reading Binary Descriptors of other images. More...

Typedefs
typedef int(*	bindesc_callback_t) (const struct bindesc_entry *entry, void *user_data)
	Callback type to be called on descriptors found during a walk.

Functions
int	bindesc_open_memory_mapped_flash (struct bindesc_handle *handle, size_t offset)
	Open an image's binary descriptors for reading, from a memory mapped flash.
int	bindesc_open_ram (struct bindesc_handle *handle, const uint8_t *address, size_t max_size)
	Open an image's binary descriptors for reading, from RAM.
int	bindesc_open_flash (struct bindesc_handle *handle, size_t offset, const struct device *flash_device)
	Open an image's binary descriptors for reading, from flash.
int	bindesc_foreach (struct bindesc_handle *handle, bindesc_callback_t callback, void *user_data)
	Walk the binary descriptors and run a user defined callback on each of them.
int	bindesc_find_str (struct bindesc_handle *handle, uint16_t id, const char **result)
	Find a specific descriptor of type string.
int	bindesc_find_uint (struct bindesc_handle *handle, uint16_t id, const uint32_t **result)
	Find a specific descriptor of type uint.
int	bindesc_find_bytes (struct bindesc_handle *handle, uint16_t id, const uint8_t **result, size_t *result_size)
	Find a specific descriptor of type bytes.
int	bindesc_get_size (struct bindesc_handle *handle, size_t *result)
	Get the size of an image's binary descriptors.

Detailed Description

Reading Binary Descriptors of other images.

Typedef Documentation

bindesc_callback_t

typedef int(* bindesc_callback_t) (const struct bindesc_entry *entry, void *user_data)

#include <zephyr/bindesc.h>

Callback type to be called on descriptors found during a walk.

Parameters

entry	Current descriptor
user_data	The user_data given to bindesc_foreach

Returns

Any non zero value will halt the walk

Function Documentation

bindesc_find_bytes()

int bindesc_find_bytes	(	struct bindesc_handle *	handle,
		uint16_t	id,
		const uint8_t **	result,
		size_t *	result_size )

#include <zephyr/bindesc.h>

Find a specific descriptor of type bytes.

Warning

When using the flash backend, result will be invalidated by the next call to any bindesc API. Use the value immediately or copy it elsewhere.

Parameters

handle	An initialized bindesc handle
id	ID to search for
result	Pointer to the found bytes
result_size	Size of the found bytes

Return values

0	If the descriptor was found
-ENOENT	If the descriptor was not found

bindesc_find_str()

int bindesc_find_str	(	struct bindesc_handle *	handle,
		uint16_t	id,
		const char **	result )

#include <zephyr/bindesc.h>

Find a specific descriptor of type string.

Warning

When using the flash backend, result will be invalidated by the next call to any bindesc API. Use the value immediately or copy it elsewhere.

Parameters

handle	An initialized bindesc handle
id	ID to search for
result	Pointer to the found string

Return values

0	If the descriptor was found
-ENOENT	If the descriptor was not found

bindesc_find_uint()

int bindesc_find_uint	(	struct bindesc_handle *	handle,
		uint16_t	id,
		const uint32_t **	result )

#include <zephyr/bindesc.h>

Find a specific descriptor of type uint.

Warning

When using the flash backend, result will be invalidated by the next call to any bindesc API. Use the value immediately or copy it elsewhere.

Parameters

handle	An initialized bindesc handle
id	ID to search for
result	Pointer to the found uint

Return values

0	If the descriptor was found
-ENOENT	If the descriptor was not found

bindesc_foreach()

int bindesc_foreach	(	struct bindesc_handle *	handle,
		bindesc_callback_t	callback,
		void *	user_data )

#include <zephyr/bindesc.h>

Walk the binary descriptors and run a user defined callback on each of them.

Note

If the callback returns a non zero value, the walk stops.

Parameters

handle	An initialized bindesc handle
callback	A user defined callback to be called on each descriptor
user_data	User defined data to be given to the callback

Returns

If the walk was finished prematurely by the callback, return the callback's retval, zero otherwise

bindesc_get_size()

int bindesc_get_size	(	struct bindesc_handle *	handle,
		size_t *	result )

#include <zephyr/bindesc.h>

Get the size of an image's binary descriptors.

Walks the binary descriptor structure to caluculate the total size of the structure in bytes. This is useful, for instance, if the whole structure is to be copied to RAM.

Parameters

handle	An initialized bindesc handle
result	Pointer to write result to

Returns

0 On success, negative errno otherwise

bindesc_open_flash()

int bindesc_open_flash	(	struct bindesc_handle *	handle,
		size_t	offset,
		const struct device *	flash_device )

#include <zephyr/bindesc.h>

Open an image's binary descriptors for reading, from flash.

Initializes a bindesc handle for subsequent calls to bindesc API. As opposed to reading bindesc from RAM or memory mapped flash, this backend requires reading the data from flash to an internal buffer using the flash API

Parameters

handle	Bindesc handle to be given to subsequent calls
offset	The offset from the beginning of the flash that the bindesc magic can be found at
flash_device	Flash device to read descriptors from

Return values

0	On success
-ENOENT	If no bindesc magic was found at the given offset

bindesc_open_memory_mapped_flash()

int bindesc_open_memory_mapped_flash	(	struct bindesc_handle *	handle,
		size_t	offset )

#include <zephyr/bindesc.h>

Open an image's binary descriptors for reading, from a memory mapped flash.

Initializes a bindesc handle for subsequent calls to bindesc API. Memory mapped flash is any flash that can be directly accessed by the CPU, without needing to use the flash API for copying the data to RAM.

Parameters

handle	Bindesc handle to be given to subsequent calls
offset	The offset from the beginning of the flash that the bindesc magic can be found at

Return values

0	On success
-ENOENT	If no bindesc magic was found at the given offset

bindesc_open_ram()

int bindesc_open_ram	(	struct bindesc_handle *	handle,
		const uint8_t *	address,
		size_t	max_size )

#include <zephyr/bindesc.h>

Open an image's binary descriptors for reading, from RAM.

Initializes a bindesc handle for subsequent calls to bindesc API. It's assumed that the whole bindesc context was copied to RAM prior to calling this function, either by the user or by a bootloader.

Note

The given address must be aligned to BINDESC_ALIGNMENT

Parameters

handle	Bindesc handle to be given to subsequent calls
address	The address that the bindesc magic can be found at
max_size	Maximum size of the given buffer

Return values

0	On success
-ENOENT	If no bindesc magic was found at the given address
-EINVAL	If the given address is not aligned