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
digest_func update_agent_config::df
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
receiver_ctx update_agent_ctx_t::rctx
conn_ctx update_agent_ctx_t::rconn
mem_id_t update_agent_ctx_t::id
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.

Coroutines

AGENTS_COROUTINE_H_
TIMEOUT
PULL_BEGIN(ev)
PULL_FINISH(ev)
IGNORE_EVENT(event)
PULL_CONTINUE(ev, ev_data)
PULL_RETURN(ev, ev_data)
PULL_SEND(ev, ev_data)