ESP Priv Access

Overview

This component provides APIs to configure memory/peripheral permissions and boot user app. It also handles the build system for both, protected and user apps and provides configuration options for the following:

  • Reserve memory space for code and data

  • Policy for handling user space exceptions

API reference

Functions

esp_err_t esp_priv_access_init(esp_priv_access_intr_handler_t fn)

Initialize Privilege Separation (PA) component.

Configures various memory regions, sets split lines and permissions. Enables interrupt for permission violation and registers user specified interrupt handler

Return

  • ESP_OK on success

  • ESP_FAIL otherwise

Parameters

  • fn: Interrupt handler which will be invoked whenever any permission violation occurs

esp_err_t esp_priv_access_user_boot()

Unpack, load and boot user app.

Return

  • ESP_OK on success

  • ESP_INVALID_ARG if incorrect user entry

  • ESP_ERR_NO_MEM if memory exhausted

  • ESP_FAIL otherwise

esp_err_t esp_priv_access_verify_user_app(const esp_partition_t *user_partition)

Verify the digital signature appended at the end of the user application.

Return

  • ESP_OK on success

  • ESP_ERR_NO_MEM if there is no available free heap space

  • ESP_ERR_IMAGE_INVALID if the image cannot be verified successfully

Parameters

  • user_partition: Pointer to user app partition handle

void esp_priv_access_user_reboot()

Reboots user app. Deletes all the user tasks and then calls esp_priv_access_user_boot.

esp_err_t esp_priv_access_user_set_entry(void *user_entry)

Set entry to user space. When the entry address is fetched, CPU switches to user space.

Return

  • ESP_OK on success

  • ESP_FAIL if user_entry is invalid

Parameters

  • user_entry: Pointer to user space code

esp_err_t esp_priv_access_user_spawn_task(void *user_entry, uint32_t stack_sz)

Spawn a task that executes under user space.

Return

  • ESP_OK on success

  • ESP_FAIL if user_entry is invalid

Parameters

  • user_entry: Pointer to task entry function

  • stack_sz: Size of the task stack

char *esp_priv_access_int_type_to_str(esp_priv_access_int_t int_type)

Converts interrupt type to corresponding memory region string.

Return

Pointer to a string

Parameters

  • int_type: Interrupt type, see esp_priv_access_int_t

void esp_priv_access_enable_int(esp_priv_access_int_t int_type)

Enable interrupt for a given violation type.

Parameters

  • int_type: Interrupt type, see esp_priv_access_int_t

void esp_priv_access_clear_and_reenable_int(esp_priv_access_int_t int_type)

Clear and re-enable interrupt for the given interrupt type.

Parameters

  • int_type: Interrupt type, see esp_priv_access_int_t

esp_priv_access_int_t esp_priv_access_get_int_status()

Get the triggered violation interrupt, if any.

Return

Interrupt type of triggered violation

uint32_t esp_priv_access_get_fault_addr(esp_priv_access_int_t int_type)

Get the fault address that triggered violation interrupt.

Return

Address which triggered the interrupt

Parameters

  • int_type: Interrupt type, see esp_priv_access_int_t

esp_err_t esp_priv_access_set_periph_perm(esp_priv_access_periph_t periph, esp_priv_access_world_t world, esp_priv_access_perm_t perm)

Set the permissions for a specified peripheral under a WORLD.

Return

  • ESP_OK on success

Parameters

  • periph: One of the supported peripheral, see esp_priv_access_periph_t

  • world: WORLD under which the following permissions will be enforced

  • perm: Permissions for the peripheral

Type Definitions

typedef void (*esp_priv_access_intr_handler_t)(void *arg)

Enumerations

enum esp_priv_access_int_t

Values:

PA_IRAM_INT = 1
PA_DRAM_INT
PA_RTC_INT
PA_FLASH_ICACHE_INT
PA_FLASH_DCACHE_INT
PA_PERIPH_INT
enum esp_priv_access_world_t

Values:

PA_WORLD_0 = 0
PA_WORLD_1
enum esp_priv_access_perm_t

Values:

PA_PERM_NONE = 0
PA_PERM_R = 1
PA_PERM_W = 2
PA_PERM_X = 4
PA_PERM_ALL = 7