Zephyr API Documentation 4.0.0-rc2
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

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
entryCurrent descriptor
user_dataThe 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
handleAn initialized bindesc handle
idID to search for
resultPointer to the found bytes
result_sizeSize of the found bytes
Return values
0If the descriptor was found
-ENOENTIf 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
handleAn initialized bindesc handle
idID to search for
resultPointer to the found string
Return values
0If the descriptor was found
-ENOENTIf 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
handleAn initialized bindesc handle
idID to search for
resultPointer to the found uint
Return values
0If the descriptor was found
-ENOENTIf 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
handleAn initialized bindesc handle
callbackA user defined callback to be called on each descriptor
user_dataUser 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
handleAn initialized bindesc handle
resultPointer 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
handleBindesc handle to be given to subsequent calls
offsetThe offset from the beginning of the flash that the bindesc magic can be found at
flash_deviceFlash device to read descriptors from
Return values
0On success
-ENOENTIf 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
handleBindesc handle to be given to subsequent calls
offsetThe offset from the beginning of the flash that the bindesc magic can be found at
Return values
0On success
-ENOENTIf 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
handleBindesc handle to be given to subsequent calls
addressThe address that the bindesc magic can be found at
max_sizeMaximum size of the given buffer
Return values
0On success
-ENOENTIf no bindesc magic was found at the given address
-EINVALIf the given address is not aligned