diff --git a/.gitignore b/.gitignore index 672fab86..692a7f46 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,4 @@ JLink.log *~ .DS_Store .custom.vim +docs/dox diff --git a/api/inc/benchmark.h b/api/inc/benchmark.h index b3e0c6c7..1d15c284 100644 --- a/api/inc/benchmark.h +++ b/api/inc/benchmark.h @@ -20,8 +20,16 @@ #include "api/inc/uvisor_exports.h" #include +/** @cond UVISOR_INTERNAL */ +/** @defgroup benchmark Benchmark + * @{ + */ + UVISOR_EXTERN void uvisor_benchmark_configure(void); UVISOR_EXTERN void uvisor_benchmark_start(void); UVISOR_EXTERN uint32_t uvisor_benchmark_stop(void); +/** @} */ +/** @endcond */ + #endif /* __UVISOR_API_BENCHMARK_H__ */ diff --git a/api/inc/box_config.h b/api/inc/box_config.h index b6594282..913eef28 100644 --- a/api/inc/box_config.h +++ b/api/inc/box_config.h @@ -25,6 +25,12 @@ UVISOR_EXTERN const uint32_t __uvisor_mode; +/** @defgroup box_config Box configuration + * + * @brief Creating and configuring secure boxes + * @{ + */ + #define UVISOR_DISABLED 0 #define UVISOR_PERMISSIVE 1 #define UVISOR_ENABLED 2 @@ -60,7 +66,7 @@ UVISOR_EXTERN const uint32_t __uvisor_mode; \ extern const __attribute__((section(".keep.uvisor.cfgtbl_ptr_first"), aligned(4))) void * const main_cfg_ptr = &main_cfg; -/* Creates a global page heap with at least `minimum_number_of_pages` each of size `page_size` in bytes. +/** Creates a global page heap with at least `minimum_number_of_pages` each of size `page_size` in bytes. * The total page heap size is at least `minimum_number_of_pages * page_size`. */ #define UVISOR_SET_PAGE_HEAP(page_size, minimum_number_of_pages) \ const uint32_t __uvisor_page_size = (page_size); \ @@ -68,6 +74,7 @@ UVISOR_EXTERN const uint32_t __uvisor_mode; main_page_heap_reserved[ (page_size) * (minimum_number_of_pages) ] +/** @cond UVISOR_INTERNAL */ /* this macro selects an overloaded macro (variable number of arguments) */ #define __UVISOR_BOX_MACRO(_1, _2, _3, _4, NAME, ...) NAME @@ -135,13 +142,15 @@ UVISOR_EXTERN const uint32_t __uvisor_mode; #define UVISOR_BOX_CONFIG(...) \ UVISOR_BOX_CONFIG_ACL(__VA_ARGS__) -/* Use this macro before box defintion (for example, UVISOR_BOX_CONFIG) to +/** @endcond */ + +/** Use this macro before box defintion (for example, `UVISOR_BOX_CONFIG`) to * define the name of your box. If you don't want a name, use this macro with - * box_namespace as NULL. */ + * box_namespace as `NULL`. */ #define UVISOR_BOX_NAMESPACE(box_namespace) \ static const char *const __uvisor_box_namespace = box_namespace -/* Use this macro before UVISOR_BOX_CONFIG to define the function the main +/** Use this macro before `UVISOR_BOX_CONFIG` to define the function the main * thread of your box will use for its body. If you don't want a main thread, * too bad: you have to have one. */ #define UVISOR_BOX_MAIN(function, priority, stack_size) \ @@ -153,13 +162,21 @@ UVISOR_EXTERN const uint32_t __uvisor_mode; #define uvisor_ctx (*__uvisor_ps) -/* Copy the box namespace of the specified box ID to the memory provided by +/** @} */ + +/** @addtogroup box_info + * @{ + */ + +/** Copy the box namespace of the specified box ID to the memory provided by * box_namespace. The box_namespace's length must be at least - * MAX_BOX_NAMESPACE_LENGTH bytes. Return how many bytes were copied into - * box_namespace. Return UVISOR_ERROR_INVALID_BOX_ID if the provided box ID is - * invalid. Return UVISOR_ERROR_BUFFER_TOO_SMALL if the provided box_namespace - * is too small to hold MAX_BOX_NAMESPACE_LENGTH bytes. Return - * UVISOR_ERROR_BOX_NAMESPACE_ANONYMOUS if the box is anonymous. */ + * `UVISOR_MAX_BOX_NAMESPACE_LENGTH` bytes. Return how many bytes were copied into + * box_namespace. Return `UVISOR_ERROR_INVALID_BOX_ID` if the provided box ID is + * invalid. Return `UVISOR_ERROR_BUFFER_TOO_SMALL` if the provided box_namespace + * is too small to hold `MAX_BOX_NAMESPACE_LENGTH` bytes. Return + * `UVISOR_ERROR_BOX_NAMESPACE_ANONYMOUS` if the box is anonymous. */ UVISOR_EXTERN int uvisor_box_namespace(int box_id, char *box_namespace, size_t length); +/** @} */ + #endif /* __UVISOR_API_BOX_CONFIG_H__ */ diff --git a/api/inc/box_id.h b/api/inc/box_id.h index 5ef573db..80f338e1 100644 --- a/api/inc/box_id.h +++ b/api/inc/box_id.h @@ -19,6 +19,12 @@ #include "api/inc/uvisor_exports.h" +/** @defgroup box_info Box Information + * + * @brief Accessing information about own box and other boxes + * @{ + */ + /* Return the numeric box ID of the current box. */ UVISOR_EXTERN int uvisor_box_id_self(void); @@ -26,4 +32,6 @@ UVISOR_EXTERN int uvisor_box_id_self(void); * secure gateway. Return -1 if there is no secure gateway calling box. */ UVISOR_EXTERN int uvisor_box_id_caller(void) UVISOR_DEPRECATED; +/** @} */ + #endif /* __UVISOR_API_BOX_ID_H__ */ diff --git a/api/inc/cmsis_nvic_virtual.h b/api/inc/cmsis_nvic_virtual.h index c490a9b8..b5b4f60f 100644 --- a/api/inc/cmsis_nvic_virtual.h +++ b/api/inc/cmsis_nvic_virtual.h @@ -20,16 +20,22 @@ #include "api/inc/interrupts.h" #include "api/inc/unvic_exports.h" -#define NVIC_SetPriorityGrouping __NVIC_SetPriorityGrouping -#define NVIC_GetPriorityGrouping __NVIC_GetPriorityGrouping -#define NVIC_EnableIRQ vIRQ_EnableIRQ -#define NVIC_DisableIRQ vIRQ_DisableIRQ -#define NVIC_GetPendingIRQ vIRQ_GetPendingIRQ -#define NVIC_SetPendingIRQ vIRQ_SetPendingIRQ -#define NVIC_ClearPendingIRQ vIRQ_ClearPendingIRQ -#define NVIC_GetActive __NVIC_GetActive -#define NVIC_SetPriority vIRQ_SetPriority -#define NVIC_GetPriority vIRQ_GetPriority -#define NVIC_SystemReset() vIRQ_SystemReset(RESET_REASON_NO_REASON) +/** @addtogroup interrupt + * @{ + */ + +#define NVIC_SetPriorityGrouping __NVIC_SetPriorityGrouping /**< @showinitializer */ +#define NVIC_GetPriorityGrouping __NVIC_GetPriorityGrouping /**< @showinitializer */ +#define NVIC_EnableIRQ vIRQ_EnableIRQ /**< @showinitializer */ +#define NVIC_DisableIRQ vIRQ_DisableIRQ /**< @showinitializer */ +#define NVIC_GetPendingIRQ vIRQ_GetPendingIRQ /**< @showinitializer */ +#define NVIC_SetPendingIRQ vIRQ_SetPendingIRQ /**< @showinitializer */ +#define NVIC_ClearPendingIRQ vIRQ_ClearPendingIRQ /**< @showinitializer */ +#define NVIC_GetActive __NVIC_GetActive /**< @showinitializer */ +#define NVIC_SetPriority vIRQ_SetPriority /**< @showinitializer */ +#define NVIC_GetPriority vIRQ_GetPriority /**< @showinitializer */ +#define NVIC_SystemReset() vIRQ_SystemReset(RESET_REASON_NO_REASON) /**< @showinitializer */ + +/** @} */ #endif /* __UVISOR_API_NVIC_VIRTUAL_H__ */ diff --git a/api/inc/cmsis_vectab_virtual.h b/api/inc/cmsis_vectab_virtual.h index 5dfbfccc..2eb7ae17 100644 --- a/api/inc/cmsis_vectab_virtual.h +++ b/api/inc/cmsis_vectab_virtual.h @@ -19,7 +19,13 @@ #include "api/inc/interrupts.h" -#define NVIC_SetVector vIRQ_SetVector -#define NVIC_GetVector vIRQ_GetVector +/** @addtogroup interrupt + * @{ + */ + +#define NVIC_SetVector vIRQ_SetVector /**< @showinitializer */ +#define NVIC_GetVector vIRQ_GetVector /**< @showinitializer */ + +/** @} */ #endif /* __UVISOR_API_VECTAB_VIRTUAL_H__ */ diff --git a/api/inc/context_exports.h b/api/inc/context_exports.h index dc4c8464..bc25112d 100644 --- a/api/inc/context_exports.h +++ b/api/inc/context_exports.h @@ -17,10 +17,14 @@ #ifndef __UVISOR_CONTEX_EXPORTS_H__ #define __UVISOR_CONTEX_EXPORTS_H__ +/** @cond UVISOR_INTERNAL */ + /** Maximum number of nested context switches. * * The same state stack is kept for all kinds of context switches that are bound * to a function, for which uVisor keeps an internal state. */ #define UVISOR_CONTEXT_MAX_DEPTH 16 +/** @endcond */ + #endif /* __UVISOR_CONTEX_EXPORTS_H__ */ diff --git a/api/inc/debug.h b/api/inc/debug.h index a170d46c..bb595f74 100644 --- a/api/inc/debug.h +++ b/api/inc/debug.h @@ -20,6 +20,12 @@ #include "api/inc/debug_exports.h" #include "api/inc/uvisor_exports.h" +/** @defgroup debug Debug Box + * @{ + */ + UVISOR_EXTERN void uvisor_debug_init(const TUvisorDebugDriver * const driver); +/** @} */ + #endif /* __UVISOR_API_DEBUG_H__ */ diff --git a/api/inc/debug_exports.h b/api/inc/debug_exports.h index acbecee1..70c1ce43 100644 --- a/api/inc/debug_exports.h +++ b/api/inc/debug_exports.h @@ -19,7 +19,11 @@ #include -/* Debug box driver -- Version 0 +/** @addtogroup debug + * @{ + */ + +/** @brief Debug box driver -- Version 0 * A constant instance of this struct must be instantiated by the unprivileged * code to setup a debug box.*/ typedef struct TUvisorDebugDriver { @@ -27,7 +31,9 @@ typedef struct TUvisorDebugDriver { void (*halt_error)(int); } TUvisorDebugDriver; -/* Number of handlers in the debug box driver */ +/** @brief Number of handlers in the debug box driver */ #define DEBUG_BOX_HANDLERS_NUMBER (sizeof(TUvisorDebugDriver) / sizeof(void *)) +/** @} */ + #endif /* __UVISOR_API_DEBUG_EXPORTS_H__ */ diff --git a/api/inc/disabled.h b/api/inc/disabled.h index 21b9a489..baefce07 100644 --- a/api/inc/disabled.h +++ b/api/inc/disabled.h @@ -20,6 +20,8 @@ #include "api/inc/uvisor_exports.h" #include +/** @cond UVISOR_INTERNAL */ + UVISOR_EXTERN void uvisor_disabled_switch_in(const uint32_t *dst_box_cfgtbl_ptr); UVISOR_EXTERN void uvisor_disabled_switch_out(void); @@ -28,4 +30,6 @@ UVISOR_EXTERN void uvisor_disabled_switch_out(void); UVISOR_EXTERN void uvisor_disabled_set_vector(uint32_t irqn, uint32_t vector); UVISOR_EXTERN uint32_t uvisor_disabled_get_vector(uint32_t irqn); +/** @endcond */ + #endif /* __UVISOR_API_DISABLED_H__ */ diff --git a/api/inc/error.h b/api/inc/error.h index b7da1cc1..7085bc5a 100644 --- a/api/inc/error.h +++ b/api/inc/error.h @@ -20,6 +20,12 @@ #include "api/inc/halt_exports.h" #include "api/inc/uvisor_exports.h" +/** @defgroup error Error + * @{ + */ + UVISOR_EXTERN void uvisor_error(THaltUserError reason); +/** @} */ + #endif /* __UVISOR_API_ERROR_H__ */ diff --git a/api/inc/export_table_exports.h b/api/inc/export_table_exports.h index 64aa11ef..f6241fa7 100644 --- a/api/inc/export_table_exports.h +++ b/api/inc/export_table_exports.h @@ -21,6 +21,11 @@ #include "api/inc/pool_queue_exports.h" #include +/** @cond UVISOR_INTERNAL */ +/** @addtogroup box_config + * @{ + */ + /* If this magic doesn't match what you get in a TUvisorExportTable, then you * didn't find a TUvisorExportTable and all bets are off as to what will be * contained in what you found. */ @@ -57,4 +62,7 @@ static inline TUvisorExportTable const * uvisor_export_table(void) return (TUvisorExportTable *) (uvisor_config_addr - uvisor_export_table_size); } +/** @} */ +/** @endcond */ + #endif diff --git a/api/inc/halt_exports.h b/api/inc/halt_exports.h index 77ecc588..855da67a 100644 --- a/api/inc/halt_exports.h +++ b/api/inc/halt_exports.h @@ -17,6 +17,12 @@ #ifndef __UVISOR_API_HALT_EXPORTS_H__ #define __UVISOR_API_HALT_EXPORTS_H__ +/** @addtogroup error + * @{ + */ + +/** @name Global errors + * @{ */ #define UVISOR_ERROR_INVALID_BOX_ID (-2) #define UVISOR_ERROR_BUFFER_TOO_SMALL (-3) #define UVISOR_ERROR_BOX_NAMESPACE_ANONYMOUS (-4) @@ -25,13 +31,19 @@ #define UVISOR_ERROR_OUT_OF_STRUCTURES (-7) #define UVISOR_ERROR_INVALID_PARAMETERS (-8) #define UVISOR_ERROR_NOT_IMPLEMENTED (-9) +/** @} */ - +/** @name Global error classes + * @{ */ #define UVISOR_ERROR_CLASS_MASK (0xFFFF0000UL) #define UVISOR_ERROR_MASK (0x0000FFFFUL) #define UVISOR_ERROR_CLASS_PAGE (1UL << 16) +/** @} */ + +/** @name Global halt errors + * @{ */ typedef enum { USER_NOT_ALLOWED = 1, DEBUG_BOX_HALT, @@ -50,5 +62,8 @@ typedef enum { FAULT_DEBUG, __THALTERROR_MAX /* always keep as the last element of the enum */ } THaltError; +/** @} */ + +/** @} */ #endif /* __UVISOR_API_HALT_EXPORTS_H__ */ diff --git a/api/inc/interrupts.h b/api/inc/interrupts.h index 579f015a..5857f359 100644 --- a/api/inc/interrupts.h +++ b/api/inc/interrupts.h @@ -21,6 +21,12 @@ #include "api/inc/uvisor_exports.h" #include +/** @defgroup interrupt Interrupts + * + * @brief Secure interrupt management. + * @{ + */ + UVISOR_EXTERN void vIRQ_SetVector(uint32_t irqn, uint32_t vector); UVISOR_EXTERN uint32_t vIRQ_GetVector(uint32_t irqn); UVISOR_EXTERN void vIRQ_EnableIRQ(uint32_t irqn); @@ -39,18 +45,20 @@ UVISOR_EXTERN int vIRQ_GetLevel(void); * * Successive calls to this function increase an internal counter that is used * by uVisor to decide when to re-enable IRQs. The related call - * ::vIRQ_EnableIRQ() decreases this counter. Only when the counter is 0 the + * `::vIRQ_EnableIRQ()` decreases this counter. Only when the counter is 0 the * interrupts are re-enabled for that box. * * This guarantees that code that disables IRQs will not accidentally have them * re-enabled by a nested function that it calls before the expected call to - * ::vIRQ_EnableAll(). Example: + * `::vIRQ_EnableAll()`. Example: * + * @code * vIRQ_DisableAll(); counter = 1; IRQs are now disabled. * some_function(); counter = 2, then counter = 1; IRQs are still disabled. * vIRQ_EnableAll(); counter = 0; IRQs are now re-enabled. + * @endcode * - * where some_function() also has a disable/enable pair. */ + * where `some_function()` also has a disable/enable pair. */ UVISOR_EXTERN void vIRQ_DisableAll(void); /** Re-enable all interrupts that were previously disabled for the currently @@ -58,7 +66,7 @@ UVISOR_EXTERN void vIRQ_DisableAll(void); * * This function only re-enables interrupt if the uVisor internal counter is set * to 0, to make sure that nested disabling of IRQs is still effective. See - * ::vIRQ_DisableAll for more information. */ + * `::vIRQ_DisableAll()` for more information. */ UVISOR_EXTERN void vIRQ_EnableAll(void); /** Reset the device. @@ -67,4 +75,6 @@ UVISOR_EXTERN void vIRQ_EnableAll(void); */ UVISOR_EXTERN void vIRQ_SystemReset(TResetReason reason); +/** @} */ + #endif /* __UVISOR_API_INTERRUPTS_H__ */ diff --git a/api/inc/page_allocator.h b/api/inc/page_allocator.h index 7dae4b69..2d7fc2f2 100644 --- a/api/inc/page_allocator.h +++ b/api/inc/page_allocator.h @@ -21,7 +21,14 @@ #include "api/inc/page_allocator_exports.h" #include -/* Allocate a number of requested pages with the requested page size. +/** @defgroup page_allocator Page allocator + * + * @brief Allocate and free memory on the page heap. + * @{ + */ + +/** @brief Allocate a number of requested pages with the requested page size. + * * @param table.page_size[in] Must be equal to the current page size * @param table.page_count[in] The number of pages to be allocated * @param table.page_origins[out] Pointers to the page origins. The table must be large enough to hold page_count entries. @@ -29,12 +36,18 @@ */ UVISOR_EXTERN int uvisor_page_malloc(UvisorPageTable * const table); -/* Free the pages associated with the table, only if it passes validation. +/** @brief Free the pages associated with the table, only if it passes validation. + * * @returns Non-zero on failure with failure class `UVISOR_ERROR_CLASS_PAGE`. See `UVISOR_ERROR_PAGE_*`. */ UVISOR_EXTERN int uvisor_page_free(const UvisorPageTable * const table); -/* @returns the active page size for one page. */ +/** @brief Retrieve the active page size for one page. + * + * @returns active page size for one page. + */ UVISOR_EXTERN uint32_t uvisor_get_page_size(void); +/** @} */ + #endif /* __UVISOR_API_PAGE_ALLOCATOR_H__ */ diff --git a/api/inc/page_allocator_exports.h b/api/inc/page_allocator_exports.h index 52c24ec9..b2c7fce1 100644 --- a/api/inc/page_allocator_exports.h +++ b/api/inc/page_allocator_exports.h @@ -21,23 +21,45 @@ #include #include +/** @addtogroup page_allocator + * @{ + */ +/** @name Error return codes + * @{ + */ +/** @brief No error occurred. */ #define UVISOR_ERROR_PAGE_OK (0) +/** @brief The page heap does not have enough free memory to serve your request. */ #define UVISOR_ERROR_PAGE_OUT_OF_MEMORY (UVISOR_ERROR_CLASS_PAGE + 1) +/** @brief The page table is not correct. */ #define UVISOR_ERROR_PAGE_INVALID_PAGE_TABLE (UVISOR_ERROR_CLASS_PAGE + 2) +/** @brief The page table contains an invalid page size. */ #define UVISOR_ERROR_PAGE_INVALID_PAGE_SIZE (UVISOR_ERROR_CLASS_PAGE + 3) +/** @brief The page table contains at least one invalid page origin. */ #define UVISOR_ERROR_PAGE_INVALID_PAGE_ORIGIN (UVISOR_ERROR_CLASS_PAGE + 4) +/** @brief The page table contains pages of which you are not the owner. */ #define UVISOR_ERROR_PAGE_INVALID_PAGE_OWNER (UVISOR_ERROR_CLASS_PAGE + 5) +/** @brief The page table contains more pages than you own in total. */ #define UVISOR_ERROR_PAGE_INVALID_PAGE_COUNT (UVISOR_ERROR_CLASS_PAGE + 6) +/** @} */ -/* Contains the uVisor page size. - * @warning Do not read directly, instead use `uvisor_get_page_size()` accessor! */ +/** @cond UVISOR_INTERNAL */ UVISOR_EXTERN const uint32_t __uvisor_page_size; +/** @endcond */ +/** This user-allocated structure is used to communicate allocation and free + * requests to and from the page allocator. + */ typedef struct { - uint32_t page_size; /* The page size in bytes. Must be multiple of `UVISOR_PAGE_SIZE`! */ - uint32_t page_count; /* The number of pages in the page table. */ - void * page_origins[1]; /* Table of pointers to the origin of each page. */ + /** The page size in bytes. Must be multiple of `uvisor_get_page_size()`! */ + uint32_t page_size; + /** The number of pages in the table. */ + uint32_t page_count; + /** Table of pointers to the origin of each page. */ + void * page_origins[1]; } UvisorPageTable; +/** @} */ + #endif /* __UVISOR_API_PAGE_ALLOCATOR_EXPORTS_H__ */ diff --git a/api/inc/priv_sys_hook_exports.h b/api/inc/priv_sys_hook_exports.h index 25188d48..2dc34d5e 100644 --- a/api/inc/priv_sys_hook_exports.h +++ b/api/inc/priv_sys_hook_exports.h @@ -17,11 +17,15 @@ #ifndef __UVISOR_API_PRIV_SYS_HOOK_EXPORTS_H__ #define __UVISOR_API_PRIV_SYS_HOOK_EXPORTS_H__ +/** @addtogroup box_config + * @{ + */ + /* Predeclaration */ typedef struct uvisor_semaphore UvisorSemaphore; -/* - * Privileged system hooks +/** @cond UVISOR_INTERNAL */ +/** @brief Privileged system hooks * * In this version of uVisor, uVisor lives alongside an RTOS that requires * running privileged code. In order for the RTOS to run any privileged code, @@ -36,10 +40,12 @@ typedef struct { uint32_t (*priv_os_suspend)(void); int (*priv_uvisor_semaphore_post)(UvisorSemaphore * semaphore); } UvisorPrivSystemHooks; +/** @endcond */ -/* Use this macro to register privileged system IRQ hooks. If you don't want to - * register a particular privileged system IRQ hook, you can supply NULL for - * that hook parameter. */ +/** @brief Use this macro to register privileged system IRQ hooks. + * + * If you don't want to register a particular privileged system IRQ hook, you + * can supply NULL for that hook parameter. */ #define UVISOR_SET_PRIV_SYS_HOOKS(priv_svc_0_, priv_pendsv_, priv_systick_, priv_os_suspend_, priv_uvisor_semaphore_post_) \ UVISOR_EXTERN_C_BEGIN \ const UvisorPrivSystemHooks __uvisor_priv_sys_hooks = { \ @@ -51,4 +57,6 @@ typedef struct { }; \ UVISOR_EXTERN_C_END +/** @} */ + #endif diff --git a/api/inc/register_gateway.h b/api/inc/register_gateway.h index 532554f8..174f1945 100644 --- a/api/inc/register_gateway.h +++ b/api/inc/register_gateway.h @@ -21,8 +21,12 @@ #include "api/inc/uvisor_exports.h" #include +/** @defgroup register_gateway Register Gateway + * @{ + */ + +/** @cond UVISOR_INTERNAL */ /** Get the offset of a struct member. - * @internal */ #define __UVISOR_OFFSETOF(type, member) ((uint32_t) (&(((type *)(0))->member))) @@ -44,10 +48,11 @@ #define BRANCH_OPCODE(instr, label) \ (uint16_t) (0xE000 | (uint8_t) ((((uint32_t) (label) - ((uint32_t) (instr) + 4)) / 2) & 0xFF)) + /** `BX LR` encoding - * @internal */ #define BXLR ((uint16_t) 0x4770) +/** @endcond */ /** Register Gateway - Read operation * @@ -68,7 +73,7 @@ * is chosen among the `UVISOR_RGW_OP_*` macros. * @param mask[in] The mask to apply for the read operation. * @returns The value read from address using the operation and mask provided - * (or their respective defaults if they have not been provided). + * (or their respective defaults if they have not been provided). */ #define uvisor_read(box_name, shared, addr, op, msk) \ ({ \ @@ -236,4 +241,6 @@ * *address ^= (0xFFFFFFFF & mask) */ \ uvisor_write(box_name, shared, address, 0xFFFFFFFF, UVISOR_RGW_OP_WRITE_XOR, mask) +/** @} */ + #endif /* __UVISOR_API_REGISTER_GATEWAY_H__ */ diff --git a/api/inc/register_gateway_exports.h b/api/inc/register_gateway_exports.h index 5fb055f2..256604cc 100644 --- a/api/inc/register_gateway_exports.h +++ b/api/inc/register_gateway_exports.h @@ -17,7 +17,12 @@ #ifndef __UVISOR_API_REGISTER_GATEWAY_EXPORTS_H__ #define __UVISOR_API_REGISTER_GATEWAY_EXPORTS_H__ -/** Register gateway magic +/** @addtogroup register_gateway + * @{ + */ + +/** @cond UVISOR_INTERNAL */ +/** @brief Register gateway magic * * The following magic is used to verify a register gateway structure. It has * been generated starting from the ARM Thumb/Thumb-2 invalid opcode. @@ -32,7 +37,7 @@ #error "Unsupported instruction set. The ARM Thumb-2 instruction set must be supported." #endif /* __thumb__ && __thumb2__ */ -/** Register gateway structure +/** @brief Register gateway structure * * This struct is packed because we must ensure that the `svc_opcode` field has * no padding before itself, and that the `bxlr` field is at a pre-determined @@ -49,8 +54,8 @@ typedef struct { uint16_t bxlr; } UVISOR_PACKED UVISOR_ALIGN(4) TRegisterGateway; -/** Register gateway operation - Masks - * @internal +/** @brief Register gateway operation - Masks + * * These are used to extract the operation fields. */ #define __UVISOR_RGW_OP_TYPE_MASK ((uint16_t) 0x00FF) @@ -59,18 +64,20 @@ typedef struct { #define __UVISOR_RGW_OP_WIDTH_POS 8 #define __UVISOR_RGW_OP_SHARED_MASK ((uint16_t) 0x8000) #define __UVISOR_RGW_OP_SHARED_POS 15 +/** @endcond */ -/** Register gateway operations +/** @brief Register gateway operations * The user can specify the following properties: * - Access type: read/write, and-, or-, xor-, replac-ed. * - Access width: 8, 16, 32 bits. * - Access shared: Whether the gateway can be shared with other boxes. * These parameters are stored in a 16-bit value as follows: - * - * 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 - * | |__________________| |____________________| - * | | | - * shared width type + @verbatim + 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + | |__________________| |____________________| + | | | + shared width type + @endverbatim * * @note The operation value must be hardcoded. */ @@ -79,17 +86,30 @@ typedef struct { (((uint16_t) (width) << __UVISOR_RGW_OP_WIDTH_POS) & __UVISOR_RGW_OP_WIDTH_MASK) | \ (((uint16_t) (shared) << __UVISOR_RGW_OP_SHARED_POS) & __UVISOR_RGW_OP_SHARED_MASK))) -/** Register gateway operation - Shared */ +/** @name Register gateway operation - Shared + * @{ */ #define UVISOR_RGW_SHARED 1 #define UVISOR_RGW_EXCLUSIVE 0 +/** @} */ + +/** @name Register gateway operation - Type + * @{ */ +/** @brief `value = *address` */ +#define UVISOR_RGW_OP_READ 0 +/** @brief `value = *address & mask` */ +#define UVISOR_RGW_OP_READ_AND 1 +/** @brief `*address = value` */ +#define UVISOR_RGW_OP_WRITE 2 +/** @brief `*address &= value | mask` */ +#define UVISOR_RGW_OP_WRITE_AND 3 +/** @brief `*address |= value & ~mask` */ +#define UVISOR_RGW_OP_WRITE_OR 4 +/** @brief `*address ^= value & mask` */ +#define UVISOR_RGW_OP_WRITE_XOR 5 +/** @brief `*address = (*address & ~mask) | (value & mask)` */ +#define UVISOR_RGW_OP_WRITE_REPLACE 6 +/** @} */ -/** Register gateway operation - Type */ -#define UVISOR_RGW_OP_READ 0 /**< value = *address */ -#define UVISOR_RGW_OP_READ_AND 1 /**< value = *address & mask */ -#define UVISOR_RGW_OP_WRITE 2 /**< *address = value */ -#define UVISOR_RGW_OP_WRITE_AND 3 /**< *address &= value | mask */ -#define UVISOR_RGW_OP_WRITE_OR 4 /**< *address |= value & ~mask */ -#define UVISOR_RGW_OP_WRITE_XOR 5 /**< *address ^= value & mask */ -#define UVISOR_RGW_OP_WRITE_REPLACE 6 /**< *address = (*address & ~mask) | (value & mask) */ +/** @} */ #endif /* __UVISOR_API_REGISTER_GATEWAY_EXPORTS_H__ */ diff --git a/api/inc/rpc.h b/api/inc/rpc.h index ca36474b..4114c6f5 100644 --- a/api/inc/rpc.h +++ b/api/inc/rpc.h @@ -22,6 +22,11 @@ #include #include +/** @defgroup rpc Remote Procedure Call + * + * @brief Secure communications between boxes + * @{ + */ /** Wait for incoming RPC. * @@ -53,4 +58,6 @@ UVISOR_EXTERN int rpc_fncall_waitfor(const TFN_Ptr fn_ptr_array[], size_t fn_cou */ UVISOR_EXTERN int rpc_fncall_wait(uvisor_rpc_result_t result, uint32_t timeout_ms, uint32_t * ret); +/** @} */ + #endif /* __UVISOR_API_RPC_H__ */ diff --git a/api/inc/rpc_gateway.h b/api/inc/rpc_gateway.h index 84d8016c..b0b66895 100644 --- a/api/inc/rpc_gateway.h +++ b/api/inc/rpc_gateway.h @@ -22,6 +22,10 @@ #include "api/inc/uvisor_exports.h" #include +/** @addtogroup rpc + * @{ + */ + /** Synchronous RPC Gateway * * This macro declares a new function pointer (with no name mangling) named @@ -38,7 +42,7 @@ * @param fn_name[in] The function that will run in the callee's box as an RPC target * @param fn_ret[in] The return type of the function being designated as an * RPC target - * @param __VA_ARGS__ The type of each parameter passed to the target + * @param ... The type of each parameter passed to the target * function. There can be up to 4 parameters in a target * function. Each parameter must be no more than uint32_t * in size. If the RPC target function accepts no @@ -85,7 +89,7 @@ * @param fn_name[in] The function that will run in the callee's box as an RPC target * @param fn_ret[in] The return type of the function being designated as an * RPC target - * @param __VA_ARGS__ The type of each parameter passed to the target + * @param ... The type of each parameter passed to the target * function. There can be up to 4 parameters in a target * function. Each parameter must be no more than uint32_t * in size. If the RPC target function accepts no @@ -116,6 +120,7 @@ uvisor_rpc_result_t (*gw_name)(__VA_ARGS__) __attribute__((section(".rodata"))) = (uvisor_rpc_result_t (*)(__VA_ARGS__)) ((uint32_t) &gw_name ## _rpc_gateway + 1); \ UVISOR_EXTERN_C_END +/** @cond UVISOR_INTERNAL */ #define _UVISOR_BOX_RPC_GATEWAY_ARG_CHECK(gw_name, ...) \ __UVISOR_BOX_MACRO(__VA_ARGS__, _UVISOR_BOX_RPC_GATEWAY_ARG_CHECK_4, \ _UVISOR_BOX_RPC_GATEWAY_ARG_CHECK_3, \ @@ -268,5 +273,8 @@ UVISOR_EXTERN uint32_t rpc_fncall_sync(uint32_t p0, uint32_t p1, uint32_t p2, ui /* This function is private to uvisor-lib, but needs to be publicly visible for * the RPC gateway creation macros to work. */ UVISOR_EXTERN uvisor_rpc_result_t rpc_fncall_async(uint32_t p0, uint32_t p1, uint32_t p2, uint32_t p3, const TRPCGateway * gateway); +/** @endcond */ + +/** @} */ #endif /* __UVISOR_API_RPC_GATEWAY_H__ */ diff --git a/api/inc/rpc_gateway_exports.h b/api/inc/rpc_gateway_exports.h index 87b148cd..d700f76f 100644 --- a/api/inc/rpc_gateway_exports.h +++ b/api/inc/rpc_gateway_exports.h @@ -21,12 +21,39 @@ #include "api/inc/magic_exports.h" #include +/** @addtogroup rpc + * @{ + */ + +/** @cond UVISOR_INTERNAL */ /* ldr pc, [pc, #