Make uVisor API Documentation Great Again

Author: niklarm

api/inc/benchmark.h

@@ -20,8 +20,16 @@
 #include "api/inc/uvisor_exports.h"
 #include <stdint.h>
 
+/** @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__ */

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,14 +60,15 @@ 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); \
     uint8_t __attribute__((section(".keep.uvisor.page_heap"))) \
         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__ */

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__ */

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__ */

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__ */

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__ */

api/inc/debug_exports.h

@@ -19,15 +19,21 @@
 
 #include <stdint.h>
 
-/* 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 {
     uint32_t (*get_version)(void);
     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__ */

api/inc/disabled.h

@@ -20,6 +20,8 @@
 #include "api/inc/uvisor_exports.h"
 #include <stdint.h>
 
+/** @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__ */

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__ */

api/inc/export_table_exports.h

@@ -20,6 +20,11 @@
 #include "rt_OsEventObserver.h"
 #include <stdint.h>
 
+/** @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

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__ */

api/inc/interrupts.h

@@ -20,6 +20,12 @@
 #include "api/inc/uvisor_exports.h"
 #include <stdint.h>
 
+/** @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,26 +44,30 @@ 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
  *  active box.
  *
  * 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__ */

api/inc/page_allocator.h

@@ -21,20 +21,33 @@
 #include "api/inc/page_allocator_exports.h"
 #include <stdint.h>
 
-/* 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.
  * @returns Non-zero on failure with failure class `UVISOR_ERROR_CLASS_PAGE`. See `UVISOR_ERROR_PAGE_*`.
  */
 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__ */