Agents API¶
Bootloader Agent¶
-
enum
ag_bl
::
agent_event_t
¶ Events returned by the bootloader agent.
Values:
-
EVENT_INIT
= 0¶
-
EVENT_CONTINUE_START_
¶
-
EVENT_BOOT
¶
-
EVENT_VALIDATE_BOOTABLE_START
¶
-
EVENT_VALIDATE_BOOTABLE_STOP
¶
-
EVENT_BOOTSTRAP
¶
-
EVENT_FIRST_BOOT
¶
-
EVENT_GET_NEWEST_FIRMWARE
¶
-
EVENT_GET_NEWEST_NON_BOOTABLE
¶
-
EVENT_STORE_BOOTLAODER_CTX
¶
-
EVENT_UPGRADE
¶
-
EVENT_UPGRADE_COPY_START
¶
-
EVENT_UPGRADE_COPY_STOP
¶
-
EVENT_UPGRADE_SUCCESS
¶
-
EVENT_VALIDATE_NON_BOOTABLE
¶
-
EVENT_VALIDATE_NON_BOOTABLE_START
¶
-
EVENT_VALIDATE_NON_BOOTABLE_STOP
¶
-
EVENT_CONTINUE_STOP_
¶
-
EVENT_FAILURE_START_
¶
-
EVENT_VALIDATE_BOOTABLE_FAILURE
¶
-
EVENT_BOOTSTRAP_FAILURE
¶
-
EVENT_BOOTSTRAP_FAILURE_2
¶
-
EVENT_FATAL_FAILURE
¶
-
EVENT_FIRST_BOOT_FAILURE
¶
-
EVENT_GET_NEWEST_FIRMWARE_FAILURE
¶
-
EVENT_GET_NEWEST_FIRMWARE_FAILURE_2
¶
-
EVENT_GET_NEWEST_NON_BOOTABLE_FAILURE
¶
-
EVENT_STORE_BOOTLAODER_CTX_FAILURE
¶
-
EVENT_UPGRADE_COPY_FAILURE
¶
-
EVENT_UPGRADE_FAILURE
¶
-
EVENT_UPGRADE_FAILURE_2
¶
-
EVENT_UPGRADE_FAILURE_3
¶
-
EVENT_UPGRADE_FAILURE_4
¶
-
EVENT_VALIDATE_NON_BOOTABLE_INVALID
¶
-
EVENT_VALIDATE_NON_BOOTABLE_FAILURE
¶
-
EVENT_FAILURE_STOP_
¶
-
EVENT_FINISH
¶
-
EVENT_INIT
= 0
-
EVENT_CONTINUE_START_
-
EVENT_SUBSCRIBE
¶
-
EVENT_CHECKING_UPDATES
¶
-
EVENT_CHECKING_UPDATES_TIMEOUT
¶
-
EVENT_SEARCHING_SLOT
¶
-
EVENT_CONN_RECEIVER
¶
-
EVENT_RECEIVE
¶
-
EVENT_VERIFY
¶
-
EVENT_FINAL
¶
-
EVENT_APPLY
¶
-
EVENT_VERIFY_BEFORE
¶
-
EVENT_VERIFY_AFTER
¶
-
EVENT_CONTINUE_END_
¶
-
EVENT_SEND_START_
¶
-
EVENT_CHECKING_UPDATES_SEND
¶
-
EVENT_RECEIVE_SEND
¶
-
EVENT_SEND_END_
¶
-
EVENT_RECOVER_START_
¶
-
EVENT_CHECKING_UPDATES_RECOVER
¶
-
EVENT_RECEIVE_RECOVER
¶
-
EVENT_RECOVER_END_
¶
-
EVENT_FAILURE_START_
-
EVENT_INIT_FAILURE
¶
-
EVENT_SUBSCRIBE_FAILURE
¶
-
EVENT_SEARCHING_SLOT_FAILURE
¶
-
EVENT_SEARCHING_SLOT_FAILURE_2
¶
-
EVENT_CONN_RECEIVER_FAILURE
¶
-
EVENT_CONN_RECEIVER_FAILURE_2
¶
-
EVENT_VERIFY_FAILURE
¶
-
EVENT_INVALIDATE_OBJECT_FAILURE
¶
-
EVENT_FAILURE_END_
¶
-
-
typedef enum agent_event_t
agent_event_t
¶ Events returned by the bootloader agent.
-
typedef struct bootloader_agent_config
bootloader_agent_config
¶ Configuration structure of the bootloader agent.
-
static void
bootloader_agent_vendor_keys
(bootloader_agent_config *cfg, uint8_t *x, uint8_t *y)¶ Function to configure the vendor keys.
- Parameters
cfg
: Pointer to configuration structure.x
: X component of the vendor key.y
: Y component of the vendor key.
-
static void
bootloader_agent_digest_func
(bootloader_agent_config *cfg, digest_func df)¶ Function to configure the bootloader digest function.
- Parameters
cfg
: Pointer to the configuration structure.df
: Digest function to be used. (For a list of them check the security/digest documentation).
-
static void
bootloader_agent_ecc_func
(bootloader_agent_config *cfg, ecc_func_t ef)¶ Function to configure the bootloader ECC function.
- Parameters
cfg
: Pointer to the configuration structure.ef
: ECC function to be used. (For a list of them check the security/ecc documentation).
-
static void
bootloader_agent_set_buffer
(bootloader_agent_config *cfg, uint8_t *buffer, size_t buffer_size)¶ Function to set the buffer used by the bootloader.
- Note
- When using flash memory, to optimize the IO performance the buffer size should be equal to the page size of your flash memory.
- Parameters
cfg
: Pointer to the configuration structure.buffer
: Pointer to the buffer.buffer_size
: Size of the buffer.
-
agent_event_t
bootloader_agent
(bootloader_agent_config *cfg, void **event_data)¶ Function executing the bootloader agent. This function is internally build with a set of coroutines that stops the function at different execution points. This allows you to perform several actions during according to the returned phase, to check for errors and try to recover, etc.
- Return
- Structure indicating the current state and the data related to it.
- Parameters
cfg
: Pointer to the configuration structure.
-
IS_CONTINUE
(event)¶
-
IS_FAILURE
(event)¶
-
GET_BOOT_ID
(event_data)¶
-
GET_ERROR
(event_data)¶
-
FOREACH_IGNORED_EVENT
(ACTION)¶
-
struct
bootloader_agent_config
- #include <bootloader_agent.h>
Configuration structure of the bootloader agent.
Update Agent¶
-
enum
ag_update
::
agent_event_t
¶ This states will be used by the update agent coroutines.
Values:
-
EVENT_INIT
= 0¶
-
EVENT_CONTINUE_START_
¶
-
EVENT_BOOT
¶
-
EVENT_VALIDATE_BOOTABLE_START
¶
-
EVENT_VALIDATE_BOOTABLE_STOP
¶
-
EVENT_BOOTSTRAP
¶
-
EVENT_FIRST_BOOT
¶
-
EVENT_GET_NEWEST_FIRMWARE
¶
-
EVENT_GET_NEWEST_NON_BOOTABLE
¶
-
EVENT_STORE_BOOTLAODER_CTX
¶
-
EVENT_UPGRADE
¶
-
EVENT_UPGRADE_COPY_START
¶
-
EVENT_UPGRADE_COPY_STOP
¶
-
EVENT_UPGRADE_SUCCESS
¶
-
EVENT_VALIDATE_NON_BOOTABLE
¶
-
EVENT_VALIDATE_NON_BOOTABLE_START
¶
-
EVENT_VALIDATE_NON_BOOTABLE_STOP
¶
-
EVENT_CONTINUE_STOP_
¶
-
EVENT_FAILURE_START_
¶
-
EVENT_VALIDATE_BOOTABLE_FAILURE
¶
-
EVENT_BOOTSTRAP_FAILURE
¶
-
EVENT_BOOTSTRAP_FAILURE_2
¶
-
EVENT_FATAL_FAILURE
¶
-
EVENT_FIRST_BOOT_FAILURE
¶
-
EVENT_GET_NEWEST_FIRMWARE_FAILURE
¶
-
EVENT_GET_NEWEST_FIRMWARE_FAILURE_2
¶
-
EVENT_GET_NEWEST_NON_BOOTABLE_FAILURE
¶
-
EVENT_STORE_BOOTLAODER_CTX_FAILURE
¶
-
EVENT_UPGRADE_COPY_FAILURE
¶
-
EVENT_UPGRADE_FAILURE
¶
-
EVENT_UPGRADE_FAILURE_2
¶
-
EVENT_UPGRADE_FAILURE_3
¶
-
EVENT_UPGRADE_FAILURE_4
¶
-
EVENT_VALIDATE_NON_BOOTABLE_INVALID
¶
-
EVENT_VALIDATE_NON_BOOTABLE_FAILURE
¶
-
EVENT_FAILURE_STOP_
¶
-
EVENT_FINISH
¶
-
EVENT_INIT
= 0
-
EVENT_CONTINUE_START_
-
EVENT_SUBSCRIBE
¶
-
EVENT_CHECKING_UPDATES
¶
-
EVENT_CHECKING_UPDATES_TIMEOUT
¶
-
EVENT_SEARCHING_SLOT
¶
-
EVENT_CONN_RECEIVER
¶
-
EVENT_RECEIVE
¶
-
EVENT_VERIFY
¶
-
EVENT_FINAL
¶
-
EVENT_APPLY
¶
-
EVENT_VERIFY_BEFORE
¶
-
EVENT_VERIFY_AFTER
¶
-
EVENT_CONTINUE_END_
¶
-
EVENT_SEND_START_
¶
-
EVENT_CHECKING_UPDATES_SEND
¶
-
EVENT_RECEIVE_SEND
¶
-
EVENT_SEND_END_
¶
-
EVENT_RECOVER_START_
¶
-
EVENT_CHECKING_UPDATES_RECOVER
¶
-
EVENT_RECEIVE_RECOVER
¶
-
EVENT_RECOVER_END_
¶
-
EVENT_FAILURE_START_
-
EVENT_INIT_FAILURE
¶
-
EVENT_SUBSCRIBE_FAILURE
¶
-
EVENT_SEARCHING_SLOT_FAILURE
¶
-
EVENT_SEARCHING_SLOT_FAILURE_2
¶
-
EVENT_CONN_RECEIVER_FAILURE
¶
-
EVENT_CONN_RECEIVER_FAILURE_2
¶
-
EVENT_VERIFY_FAILURE
¶
-
EVENT_INVALIDATE_OBJECT_FAILURE
¶
-
EVENT_FAILURE_END_
¶
-
-
typedef enum agent_event_t
agent_event_t
This states will be used by the update agent coroutines.
-
typedef struct update_agent_ctx_t
update_agent_ctx_t
¶ Context of the update agent.
-
conn_config_t
update_agent_config
::
subscriber
¶
-
conn_config_t
update_agent_config
::
receiver
¶
-
uint8_t
update_agent_config
::
reuse_connection
¶
-
identity_t
update_agent_config
::
identity
¶
-
uint8_t *
update_agent_config
::
vendor_x
¶
-
uint8_t *
update_agent_config
::
vendor_y
¶
-
ecc_func_t
update_agent_config
::
ef
¶
-
uint8_t *
update_agent_config
::
buffer
¶
-
size_t
update_agent_config
::
buffer_size
¶
-
conn_ctx
update_agent_ctx_t
::
sconn
¶
-
subscriber_ctx
update_agent_ctx_t
::
sctx
¶
-
conn_ctx
update_agent_ctx_t
::
rconn
¶
-
mem_object_t
update_agent_ctx_t
::
new_obj
¶
-
mem_object_t
update_agent_ctx_t
::
obj_t
¶
-
pull_error
update_agent_ctx_t
::
err
¶
-
static void
update_agent_reuse_connection
(update_agent_config *cfg, uint8_t reuse)¶ The update agents connects to the subscription server and the provisioning server. If the connection to both server should be done with the same connection than the connection must be reused.
- Parameters
cfg
: Pointer to the configuration structure.reuse
: Boolean indicating if the connection should be reused (1 to reuse).
-
static void
update_agent_set_identity
(update_agent_config *cfg, identity_t identity)¶ Function to set the device identity used to identify the device with the server.
- Parameters
cfg
: Pointer to the configuration structure.identity
: Identity structure.
-
static void
update_agent_vendor_keys
(update_agent_config *cfg, uint8_t *x, uint8_t *y)¶ Function to set the vendor keys.
- Parameters
cfg
: Pointer to the configuration structure.x
: The X component of the vendor key.y
: The Y component of the vendor key.
-
static void
update_agent_digest_func
(update_agent_config *cfg, digest_func df)¶ Function to set the digest function.
- Parameters
cfg
: Pointer to the configuration structure.df
: Digest function to be used. (To see all the available digest functions check the documentation at security/digest).
-
static void
update_agent_ecc_func
(update_agent_config *cfg, ecc_func_t ef)¶ Function to set the ECC function.
- Parameters
cfg
: Pointer to the configuration structure.ef
: ECC function to be used. (To see all the available ECC functions check the documentation at security/ECC).
-
static void
update_agent_set_buffer
(update_agent_config *cfg, uint8_t *buffer, size_t buffer_size)¶ Function to set the buffer for the update agent.
- Parameters
cfg
: Pointer to the configuration structure.buffer
: Pointer to the buffer.buffer_size
: Size of the buffer.
-
agent_event_t
update_agent
(update_agent_config *cfg, update_agent_ctx_t *ctx, void **agent_data)¶ Function to execute the update agent. This function will return several times, each time with a different message indicating the state of the update agent. In this way you can interact with the update agent modifying the states.
- Return
- Messages containing the current event.
- Parameters
cfg
: Pointer to the configuration structure.ctx
: Pointer to the update agent context.
-
AGENTS_UPDATE_H_
¶
-
IS_CONTINUE
(agent_event)
-
IS_SEND
(agent_event)¶
-
IS_RECOVER
(agent_event)¶
-
IS_FAILURE
(agent_event)
-
GET_CONNECTION
(event_data)¶
-
GET_ERROR
(event_data)
-
FOREACH_IGNORED_EVENT
(ACTION)
-
struct
update_agent_config
¶ - #include <update.h>
Configuration structure for the update agent.
-
struct
update_agent_ctx_t
- #include <update.h>
Context of the update agent.
Utils¶
Bootloader Context¶
-
uint8_t
bootloader_ctx
::
vendor_key
[64]¶
-
uint8_t
bootloader_ctx
::
buffer
[63]¶
-
uint8_t
bootloader_ctx
::
startup_flags
¶
-
LIBPULL_AGENTS_BOOTLOADER_CTX_H_
¶
-
FIRST_BOOT
¶
-
struct
bootloader_ctx
¶ - #include <bootloader_ctx.h>
Structure of the bootloader context. It is used to store data used by the bootloader.