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 a15295da..279ede73 100644 --- a/api/inc/box_config.h +++ b/api/inc/box_config.h @@ -24,6 +24,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 @@ -54,7 +60,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); \ @@ -62,6 +68,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 @@ -121,13 +128,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) \ @@ -139,20 +148,30 @@ UVISOR_EXTERN const uint32_t __uvisor_mode; #define uvisor_ctx (*__uvisor_ps) -/* Return the numeric box ID of the current box. */ +/** @} */ + +/** @defgroup box_info Box Information + * + * @brief Accessing information about own box and other boxes + * @{ + */ + +/** @brief Return the numeric box ID of the current box. */ UVISOR_EXTERN int uvisor_box_id_self(void); -/* Return the numeric box ID of the box that is calling through the most recent - * secure gateway. Return -1 if there is no secure gateway calling box. */ +/** @brief Return the numeric box ID of the box that is calling through the most recent + * secure gateway. @return -1 if there is no secure gateway calling box. */ UVISOR_EXTERN int uvisor_box_id_caller(void); -/* Copy the box namespace of the specified box ID to the memory provided by +/** 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/cmsis_nvic_virtual.h b/api/inc/cmsis_nvic_virtual.h index e469b662..bfa66b63 100644 --- a/api/inc/cmsis_nvic_virtual.h +++ b/api/inc/cmsis_nvic_virtual.h @@ -19,15 +19,21 @@ #include "api/inc/interrupts.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 +/** @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 */ + +/** @} */ #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 b37514d6..9a89b2ef 100644 --- a/api/inc/export_table_exports.h +++ b/api/inc/export_table_exports.h @@ -20,6 +20,11 @@ #include "rt_OsEventObserver.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. */ @@ -44,4 +49,7 @@ typedef struct { uint32_t size; } TUvisorExportTable; +/** @} */ +/** @endcond */ + #endif diff --git a/api/inc/halt_exports.h b/api/inc/halt_exports.h index 9abbecdb..76888c21 100644 --- a/api/inc/halt_exports.h +++ b/api/inc/halt_exports.h @@ -17,16 +17,28 @@ #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) +/** @} */ - +/** @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, } THaltUserError; @@ -44,5 +56,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 7459ad93..00ce3a64 100644 --- a/api/inc/interrupts.h +++ b/api/inc/interrupts.h @@ -20,6 +20,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); @@ -38,18 +44,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 @@ -57,7 +65,9 @@ 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); +/** @} */ + #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 b8324377..19d059a8 100644 --- a/api/inc/priv_sys_hook_exports.h +++ b/api/inc/priv_sys_hook_exports.h @@ -17,8 +17,12 @@ #ifndef __UVISOR_API_PRIV_SYS_HOOK_EXPORTS_H__ #define __UVISOR_API_PRIV_SYS_HOOK_EXPORTS_H__ -/* - * Privileged system hooks +/** @addtogroup box_config + * @{ + */ + +/** @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, @@ -32,10 +36,12 @@ typedef struct { void (*priv_systick)(void); uint32_t (*priv_os_suspend)(void); } 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_) \ UVISOR_EXTERN const UvisorPrivSystemHooks __uvisor_priv_sys_hooks = { \ .priv_svc_0 = priv_svc_0_, \ @@ -44,4 +50,6 @@ typedef struct { .priv_os_suspend = priv_os_suspend_, \ }; +/** @} */ + #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..50a2946a 100644 --- a/api/inc/register_gateway_exports.h +++ b/api/inc/register_gateway_exports.h @@ -17,6 +17,11 @@ #ifndef __UVISOR_API_REGISTER_GATEWAY_EXPORTS_H__ #define __UVISOR_API_REGISTER_GATEWAY_EXPORTS_H__ +/** @addtogroup register_gateway + * @{ + */ + +/** @cond UVISOR_INTERNAL */ /** Register gateway magic * * The following magic is used to verify a register gateway structure. It has @@ -50,7 +55,7 @@ typedef struct { } UVISOR_PACKED UVISOR_ALIGN(4) TRegisterGateway; /** Register gateway operation - Masks - * @internal + * * These are used to extract the operation fields. */ #define __UVISOR_RGW_OP_TYPE_MASK ((uint16_t) 0x00FF) @@ -59,6 +64,7 @@ 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 * The user can specify the following properties: @@ -66,11 +72,12 @@ typedef struct { * - 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 b1a89cef..ab1786b5 100644 --- a/api/inc/rpc.h +++ b/api/inc/rpc.h @@ -21,6 +21,12 @@ #include #include +/** @defgroup rpc Remote Procedure Call + * + * @brief Secure communications between boxes + * @{ + */ + /** Specify the maximum number of incoming RPC messages for a box * * @param max_num_incoming_rpc The maximum number of incoming RPC messages for @@ -59,4 +65,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 81d840d4..18da5984 100644 --- a/api/inc/rpc_gateway.h +++ b/api/inc/rpc_gateway.h @@ -22,11 +22,17 @@ #include "api/inc/uvisor_exports.h" #include +/** @addtogroup rpc + * @{ + */ + +/** @cond UVISOR_INTERNAL */ /* ldr pc, [pc, #