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