[doc] Add Doxygen Headers to Device Code
Doxygen needs specific `@file` annotations to pick up C headers and
implementation files. This commit adds these annotations, as well as
brief descriptions of each header or implementation file.
Signed-off-by: Sam Elliott <selliott@lowrisc.org>
diff --git a/sw/device/lib/arch/device.h b/sw/device/lib/arch/device.h
index b56a774..61f9586 100644
--- a/sw/device/lib/arch/device.h
+++ b/sw/device/lib/arch/device.h
@@ -8,6 +8,9 @@
#include <stdint.h>
/**
+ * @file
+ * @brief This header contains declarations of device-specific information.
+ *
* This header contains "device-specific" declarations, i.e., information that
* all devices are known to provide, but which is specific to the particular
* choice of platform, which can range from a software simulation, like
diff --git a/sw/device/lib/arch/device_fpga_nexysvideo.c b/sw/device/lib/arch/device_fpga_nexysvideo.c
index f7ee37a..7ea7463 100644
--- a/sw/device/lib/arch/device_fpga_nexysvideo.c
+++ b/sw/device/lib/arch/device_fpga_nexysvideo.c
@@ -5,7 +5,8 @@
#include "sw/device/lib/arch/device.h"
/**
- * Device-specific symbol definitions for the Nexysvideo device.
+ * @file
+ * @brief Device-specific symbol definitions for the Nexysvideo device.
*/
const device_type_t kDeviceType = kDeviceFpgaNexysVideo;
diff --git a/sw/device/lib/arch/device_sim_verilator.c b/sw/device/lib/arch/device_sim_verilator.c
index fa84314..47de216 100644
--- a/sw/device/lib/arch/device_sim_verilator.c
+++ b/sw/device/lib/arch/device_sim_verilator.c
@@ -5,7 +5,8 @@
#include "sw/device/lib/arch/device.h"
/**
- * Device-specific symbol definitions for the Verilator device.
+ * @file
+ * @brief Device-specific symbol definitions for the Verilator device.
*/
const device_type_t kDeviceType = kDeviceSimVerilator;
diff --git a/sw/device/lib/base/freestanding/float.h b/sw/device/lib/base/freestanding/float.h
index 0cf3b9c..6a7e010 100644
--- a/sw/device/lib/base/freestanding/float.h
+++ b/sw/device/lib/base/freestanding/float.h
@@ -6,6 +6,9 @@
#define OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_FLOAT_H_
/**
+ * @file
+ * @brief C library Floating-point environment (Freestanding)
+ *
* This header implements the float.h standard header, as required by C11 S4p6.
* This header is specified in detail in S7.7 and S5.2.4.2.2 of the same.
*
@@ -13,58 +16,58 @@
* https://clang.llvm.org/doxygen/float_8h_source.html
*/
-#define FLT_EVAL_METHOD __FLT_EVAL_METHOD__
-#define FLT_ROUNDS (-1)
-#define FLT_RADIX __FLT_RADIX__
+#define FLT_EVAL_METHOD __FLT_EVAL_METHOD__ /**< @hideinitializer */
+#define FLT_ROUNDS (-1) /**< @hideinitializer */
+#define FLT_RADIX __FLT_RADIX__ /**< @hideinitializer */
-#define FLT_MANT_DIG __FLT_MANT_DIG__
-#define DBL_MANT_DIG __DBL_MANT_DIG__
-#define LDBL_MANT_DIG __LDBL_MANT_DIG__
+#define FLT_MANT_DIG __FLT_MANT_DIG__ /**< @hideinitializer */
+#define DBL_MANT_DIG __DBL_MANT_DIG__ /**< @hideinitializer */
+#define LDBL_MANT_DIG __LDBL_MANT_DIG__ /**< @hideinitializer */
-#define DECIMAL_DIG __DECIMAL_DIG__
+#define DECIMAL_DIG __DECIMAL_DIG__ /**< @hideinitializer */
-#define FLT_DIG __FLT_DIG__
-#define DBL_DIG __DBL_DIG__
-#define LDBL_DIG __LDBL_DIG__
+#define FLT_DIG __FLT_DIG__ /**< @hideinitializer */
+#define DBL_DIG __DBL_DIG__ /**< @hideinitializer */
+#define LDBL_DIG __LDBL_DIG__ /**< @hideinitializer */
-#define FLT_MIN_EXP __FLT_MIN_EXP__
-#define DBL_MIN_EXP __DBL_MIN_EXP__
-#define LDBL_MIN_EXP __LDBL_MIN_EXP__
+#define FLT_MIN_EXP __FLT_MIN_EXP__ /**< @hideinitializer */
+#define DBL_MIN_EXP __DBL_MIN_EXP__ /**< @hideinitializer */
+#define LDBL_MIN_EXP __LDBL_MIN_EXP__ /**< @hideinitializer */
-#define FLT_MIN_10_EXP __FLT_MIN_10_EXP__
-#define DBL_MIN_10_EXP __DBL_MIN_10_EXP__
-#define LDBL_MIN_10_EXP __LDBL_MIN_10_EXP__
+#define FLT_MIN_10_EXP __FLT_MIN_10_EXP__ /**< @hideinitializer */
+#define DBL_MIN_10_EXP __DBL_MIN_10_EXP__ /**< @hideinitializer */
+#define LDBL_MIN_10_EXP __LDBL_MIN_10_EXP__ /**< @hideinitializer */
-#define FLT_MAX_EXP __FLT_MAX_EXP__
-#define DBL_MAX_EXP __DBL_MAX_EXP__
-#define LDBL_MAX_EXP __LDBL_MAX_EXP__
+#define FLT_MAX_EXP __FLT_MAX_EXP__ /**< @hideinitializer */
+#define DBL_MAX_EXP __DBL_MAX_EXP__ /**< @hideinitializer */
+#define LDBL_MAX_EXP __LDBL_MAX_EXP__ /**< @hideinitializer */
-#define FLT_MAX_10_EXP __FLT_MAX_10_EXP__
-#define DBL_MAX_10_EXP __DBL_MAX_10_EXP__
-#define LDBL_MAX_10_EXP __LDBL_MAX_10_EXP__
+#define FLT_MAX_10_EXP __FLT_MAX_10_EXP__ /**< @hideinitializer */
+#define DBL_MAX_10_EXP __DBL_MAX_10_EXP__ /**< @hideinitializer */
+#define LDBL_MAX_10_EXP __LDBL_MAX_10_EXP__ /**< @hideinitializer */
-#define FLT_MAX __FLT_MAX__
-#define DBL_MAX __DBL_MAX__
-#define LDBL_MAX __LDBL_MAX__
+#define FLT_MAX __FLT_MAX__ /**< @hideinitializer */
+#define DBL_MAX __DBL_MAX__ /**< @hideinitializer */
+#define LDBL_MAX __LDBL_MAX__ /**< @hideinitializer */
-#define FLT_EPSILON __FLT_EPSILON__
-#define DBL_EPSILON __DBL_EPSILON__
-#define LDBL_EPSILON __LDBL_EPSILON__
+#define FLT_EPSILON __FLT_EPSILON__ /**< @hideinitializer */
+#define DBL_EPSILON __DBL_EPSILON__ /**< @hideinitializer */
+#define LDBL_EPSILON __LDBL_EPSILON__ /**< @hideinitializer */
-#define FLT_MIN __FLT_MIN__
-#define DBL_MIN __DBL_MIN__
-#define LDBL_MIN __LDBL_MIN__
+#define FLT_MIN __FLT_MIN__ /**< @hideinitializer */
+#define DBL_MIN __DBL_MIN__ /**< @hideinitializer */
+#define LDBL_MIN __LDBL_MIN__ /**< @hideinitializer */
-#define FLT_TRUE_MIN __FLT_DENORM_MIN__
-#define DBL_TRUE_MIN __DBL_DENORM_MIN__
-#define LDBL_TRUE_MIN __LDBL_DENORM_MIN__
+#define FLT_TRUE_MIN __FLT_DENORM_MIN__ /**< @hideinitializer */
+#define DBL_TRUE_MIN __DBL_DENORM_MIN__ /**< @hideinitializer */
+#define LDBL_TRUE_MIN __LDBL_DENORM_MIN__ /**< @hideinitializer */
-#define FLT_DECIMAL_DIG __FLT_DECIMAL_DIG__
-#define DBL_DECIMAL_DIG __DBL_DECIMAL_DIG__
-#define LDBL_DECIMAL_DIG __LDBL_DECIMAL_DIG__
+#define FLT_DECIMAL_DIG __FLT_DECIMAL_DIG__ /**< @hideinitializer */
+#define DBL_DECIMAL_DIG __DBL_DECIMAL_DIG__ /**< @hideinitializer */
+#define LDBL_DECIMAL_DIG __LDBL_DECIMAL_DIG__ /**< @hideinitializer */
-#define FLT_HAS_SUBNORM __FLT_HAS_DENORM__
-#define DBL_HAS_SUBNORM __DBL_HAS_DENORM__
-#define LDBL_HAS_SUBNORM __LDBL_HAS_DENORM__
+#define FLT_HAS_SUBNORM __FLT_HAS_DENORM__ /**< @hideinitializer */
+#define DBL_HAS_SUBNORM __DBL_HAS_DENORM__ /**< @hideinitializer */
+#define LDBL_HAS_SUBNORM __LDBL_HAS_DENORM__ /**< @hideinitializer */
#endif // OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_FLOAT_H_
diff --git a/sw/device/lib/base/freestanding/iso646.h b/sw/device/lib/base/freestanding/iso646.h
index 762f480..d941fd3 100644
--- a/sw/device/lib/base/freestanding/iso646.h
+++ b/sw/device/lib/base/freestanding/iso646.h
@@ -6,6 +6,9 @@
#define OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_ISO646_H_
/**
+ * @file
+ * @brief C library Alternative Spellings (Freestanding)
+ *
* This header implements the iso646.h standard header, as required by C11 S4p6.
* See S7.9 of the same for a description.
*
diff --git a/sw/device/lib/base/freestanding/limits.h b/sw/device/lib/base/freestanding/limits.h
index 4b16fba..6859d0c 100644
--- a/sw/device/lib/base/freestanding/limits.h
+++ b/sw/device/lib/base/freestanding/limits.h
@@ -8,37 +8,40 @@
#include <stdint.h>
/**
+ * @file
+ * @brief C library Sizes of integer types (Freestanding)
+ *
* This header implements the limits.h standard header, as required by C11 S4p6.
* This header is specified in detail in S7.10 and S5.2.4.2.1 of the same.
*/
-#define SCHAR_MAX __SCHAR_MAX__
-#define SHRT_MAX __SHRT_MAX__
-#define INT_MAX __INT_MAX__
-#define LONG_MAX __LONG_MAX__
-#define LLONG_MAX __LONG_LONG_MAX__
+#define SCHAR_MAX __SCHAR_MAX__ /**< @hideinitializer */
+#define SHRT_MAX __SHRT_MAX__ /**< @hideinitializer */
+#define INT_MAX __INT_MAX__ /**< @hideinitializer */
+#define LONG_MAX __LONG_MAX__ /**< @hideinitializer */
+#define LLONG_MAX __LONG_LONG_MAX__ /**< @hideinitializer */
-#define SCHAR_MIN (-__SCHAR_MAX__ - 1)
-#define SHRT_MIN (-__SHRT_MAX__ - 1)
-#define INT_MIN (-__INT_MAX__ - 1)
-#define LONG_MIN (-__LONG_MAX__ - 1L)
-#define LLONG_MIN (-__LONG_LONG_MAX__ - 1LL)
+#define SCHAR_MIN (-__SCHAR_MAX__ - 1) /**< @hideinitializer */
+#define SHRT_MIN (-__SHRT_MAX__ - 1) /**< @hideinitializer */
+#define INT_MIN (-__INT_MAX__ - 1) /**< @hideinitializer */
+#define LONG_MIN (-__LONG_MAX__ - 1L) /**< @hideinitializer */
+#define LLONG_MIN (-__LONG_LONG_MAX__ - 1LL) /**< @hideinitializer */
-#define UCHAR_MAX (__SCHAR_MAX__ * 2 + 1)
-#define USHRT_MAX (__SHRT_MAX__ * 2 + 1)
-#define UINT_MAX (__INT_MAX__ * 2U + 1U)
-#define ULONG_MAX (__LONG_MAX__ * 2UL + 1UL)
-#define ULLONG_MAX (__LONG_LONG_MAX__ * 2ULL + 1ULL)
+#define UCHAR_MAX (__SCHAR_MAX__ * 2 + 1) /**< @hideinitializer */
+#define USHRT_MAX (__SHRT_MAX__ * 2 + 1) /**< @hideinitializer */
+#define UINT_MAX (__INT_MAX__ * 2U + 1U) /**< @hideinitializer */
+#define ULONG_MAX (__LONG_MAX__ * 2UL + 1UL) /**< @hideinitializer */
+#define ULLONG_MAX (__LONG_LONG_MAX__ * 2ULL + 1ULL) /**< @hideinitializer */
-#define CHAR_BIT __CHAR_BIT__
-#define MB_LEN_MAX (1)
+#define CHAR_BIT __CHAR_BIT__ /**< @hideinitializer */
+#define MB_LEN_MAX (1) /**< @hideinitializer */
#ifdef __CHAR_UNSIGNED__
-#define CHAR_MIN (0)
-#define CHAR_MAX UCHAR_MAX
+#define CHAR_MIN (0) /**< @hideinitializer */
+#define CHAR_MAX UCHAR_MAX /**< @hideinitializer */
#else
-#define CHAR_MIN SCHAR_MIN
-#define CHAR_MAX SCHAR_MAX
+#define CHAR_MIN SCHAR_MIN /**< @hideinitializer */
+#define CHAR_MAX SCHAR_MAX /**< @hideinitializer */
#endif
#endif // OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_LIMITS_H_
diff --git a/sw/device/lib/base/freestanding/stdalign.h b/sw/device/lib/base/freestanding/stdalign.h
index 3feab85..10126c9 100644
--- a/sw/device/lib/base/freestanding/stdalign.h
+++ b/sw/device/lib/base/freestanding/stdalign.h
@@ -6,6 +6,9 @@
#define OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_STDALIGN_H_
/**
+ * @file
+ * @brief C library Alignment (Freestanding)
+ *
* This header implements the stdalign.h standard header, as required by C11
* S4p6. This header is specified in detail in S7.15 of the same.
*/
diff --git a/sw/device/lib/base/freestanding/stdarg.h b/sw/device/lib/base/freestanding/stdarg.h
index dca2e72..ec121fa 100644
--- a/sw/device/lib/base/freestanding/stdarg.h
+++ b/sw/device/lib/base/freestanding/stdarg.h
@@ -6,6 +6,9 @@
#define OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_STDARG_H_
/**
+ * @file
+ * @brief C library Variable arguments (Freestanding)
+ *
* This header implements the stdarg.h standard header, as required by C11 S4p6.
* This header is specified in detail in S7.16.
*
@@ -14,9 +17,10 @@
*/
typedef __builtin_va_list va_list;
-#define va_start(ap, param) __builtin_va_start(ap, param)
-#define va_end(ap) __builtin_va_end(ap)
-#define va_arg(ap, type) __builtin_va_arg(ap, type)
-#define va_copy(dest, src) __builtin_va_copy(dest, src)
+#define va_start(ap, param) \
+ __builtin_va_start(ap, param) /**< @hideinitializer */
+#define va_end(ap) __builtin_va_end(ap) /**< @hideinitializer */
+#define va_arg(ap, type) __builtin_va_arg(ap, type) /**< @hideinitializer */
+#define va_copy(dst, src) __builtin_va_copy(dst, src) /**< @hideinitializer */
#endif // OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_STDARG_H_
diff --git a/sw/device/lib/base/freestanding/stdbool.h b/sw/device/lib/base/freestanding/stdbool.h
index 95b4077..f9a9fa0 100644
--- a/sw/device/lib/base/freestanding/stdbool.h
+++ b/sw/device/lib/base/freestanding/stdbool.h
@@ -6,6 +6,9 @@
#define OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_STDBOOL_H_
/**
+ * @file
+ * @brief C Library Boolean type and values (Freestanding)
+ *
* This header implements the stdbool.h standard header, as required by C11
* S4p6. This header is specified in detail in S7.18 of the same.
*/
diff --git a/sw/device/lib/base/freestanding/stddef.h b/sw/device/lib/base/freestanding/stddef.h
index 8878696..d229871 100644
--- a/sw/device/lib/base/freestanding/stddef.h
+++ b/sw/device/lib/base/freestanding/stddef.h
@@ -9,6 +9,9 @@
#include <stdint.h>
/**
+ * @file
+ * @brief C library Common definitions (Freestanding)
+ *
* This header implements the stdint.h standard header, as required by C11 S4p6.
* This header is specified in detail in S7.19 of the same.
*
@@ -16,18 +19,24 @@
* for the RISC-V specifics this file conforms to.
*/
-// GCC's built-in defines do not include a type with the maximum alignment, but
-// does include a define with the maximum alignment value. Since the only
-// requirement of `max_align_t` is that it be some type such that its alignment
-// is maximal, we simply use a one-byte struct whose alignment is forced to be
-// the maximum.
-typedef struct { alignas(__BIGGEST_ALIGNMENT__) uint8_t __nonce; } max_align_t;
+/**
+ * @internal
+ * GCC's built-in defines do not include a type with the maximum alignment, but
+ * does include a define with the maximum alignment value. Since the only
+ * requirement of `max_align_t` is that it be some type such that its alignment
+ * is maximal, we simply use a one-byte struct whose alignment is forced to be
+ * the maximum.
+ */
+typedef struct {
+ alignas(__BIGGEST_ALIGNMENT__) uint8_t __nonce; /**< @private **/
+} max_align_t;
typedef __PTRDIFF_TYPE__ ptrdiff_t;
typedef __SIZE_TYPE__ size_t;
typedef __WCHAR_TYPE__ wchar_t;
-#define NULL ((void *)0)
-#define offsetof(type, member) __builtin_offsetof(type, member)
+#define NULL ((void *)0) /**< @hideinitializer */
+#define offsetof(type, member) \
+ __builtin_offsetof(type, member) /**< @hideinitializer */
#endif // OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_STDDEF_H_
diff --git a/sw/device/lib/base/freestanding/stdint.h b/sw/device/lib/base/freestanding/stdint.h
index 14b102b..026a103 100644
--- a/sw/device/lib/base/freestanding/stdint.h
+++ b/sw/device/lib/base/freestanding/stdint.h
@@ -6,6 +6,9 @@
#define OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_STDINT_H_
/**
+ * @file
+ * @brief C library Integer types (Freestanding)
+ *
* This header implements the stdint.h standard header, as required by C11 S4p6.
* This header is specified in detail in S7.20 the same.
*
@@ -63,75 +66,75 @@
// (-MIN - 1). (MAX + 1) will trigger signed overflow and, as such, Undefined
// Behavior.
-#define INT8_MIN (-__INT8_MAX__ - 1)
-#define INT8_MAX __INT8_MAX__
-#define UINT8_MAX __UINT8_MAX__
-#define INT16_MIN (-__INT16_MAX__ - 1)
-#define INT16_MAX __INT16_MAX__
-#define UINT16_MAX __UINT16_MAX__
-#define INT32_MIN (-__INT32_MAX__ - 1)
-#define INT32_MAX __INT32_MAX__
-#define UINT32_MAX __UINT32_MAX__
-#define INT64_MIN (-__INT64_MAX__ - 1)
-#define INT64_MAX __INT64_MAX__
-#define UINT64_MAX __UINT64_MAX__
+#define INT8_MIN (-__INT8_MAX__ - 1) /**< @hideinitializer */
+#define INT8_MAX __INT8_MAX__ /**< @hideinitializer */
+#define UINT8_MAX __UINT8_MAX__ /**< @hideinitializer */
+#define INT16_MIN (-__INT16_MAX__ - 1) /**< @hideinitializer */
+#define INT16_MAX __INT16_MAX__ /**< @hideinitializer */
+#define UINT16_MAX __UINT16_MAX__ /**< @hideinitializer */
+#define INT32_MIN (-__INT32_MAX__ - 1) /**< @hideinitializer */
+#define INT32_MAX __INT32_MAX__ /**< @hideinitializer */
+#define UINT32_MAX __UINT32_MAX__ /**< @hideinitializer */
+#define INT64_MIN (-__INT64_MAX__ - 1) /**< @hideinitializer */
+#define INT64_MAX __INT64_MAX__ /**< @hideinitializer */
+#define UINT64_MAX __UINT64_MAX__ /**< @hideinitializer */
-#define INT_LEAST8_MIN (-__INT_LEAST8_MAX__ - 1)
-#define INT_LEAST8_MAX __INT_LEAST8_MAX__
-#define UINT_LEAST8_MAX __UINT_LEAST8_MAX__
-#define INT_LEAST16_MIN (-__INT_LEAST16_MAX__ - 1)
-#define INT_LEAST16_MAX __INT_LEAST16_MAX__
-#define UINT_LEAST16_MAX __UINT_LEAST16_MAX__
-#define INT_LEAST32_MIN (-__INT_LEAST32_MAX__ - 1)
-#define INT_LEAST32_MAX __INT_LEAST32_MAX__
-#define UINT_LEAST32_MAX __UINT_LEAST32_MAX__
-#define INT_LEAST64_MIN (-__INT_LEAST64_MAX__ - 1)
-#define INT_LEAST64_MAX __INT_LEAST64_MAX__
-#define UINT_LEAST64_MAX __UINT_LEAST64_MAX__
+#define INT_LEAST8_MIN (-__INT_LEAST8_MAX__ - 1) /**< @hideinitializer */
+#define INT_LEAST8_MAX __INT_LEAST8_MAX__ /**< @hideinitializer */
+#define UINT_LEAST8_MAX __UINT_LEAST8_MAX__ /**< @hideinitializer */
+#define INT_LEAST16_MIN (-__INT_LEAST16_MAX__ - 1) /**< @hideinitializer */
+#define INT_LEAST16_MAX __INT_LEAST16_MAX__ /**< @hideinitializer */
+#define UINT_LEAST16_MAX __UINT_LEAST16_MAX__ /**< @hideinitializer */
+#define INT_LEAST32_MIN (-__INT_LEAST32_MAX__ - 1) /**< @hideinitializer */
+#define INT_LEAST32_MAX __INT_LEAST32_MAX__ /**< @hideinitializer */
+#define UINT_LEAST32_MAX __UINT_LEAST32_MAX__ /**< @hideinitializer */
+#define INT_LEAST64_MIN (-__INT_LEAST64_MAX__ - 1) /**< @hideinitializer */
+#define INT_LEAST64_MAX __INT_LEAST64_MAX__ /**< @hideinitializer */
+#define UINT_LEAST64_MAX __UINT_LEAST64_MAX__ /**< @hideinitializer */
-#define INT_FAST8_MIN (-__INT_FAST8_MAX__ - 1)
-#define INT_FAST8_MAX __INT_FAST8_MAX__
-#define UINT_FAST8_MAX __UINT_FAST8_MAX__
-#define INT_FAST16_MIN (-__INT_FAST16_MAX__ - 1)
-#define INT_FAST16_MAX __INT_FAST16_MAX__
-#define UINT_FAST16_MAX __UINT_FAST16_MAX__
-#define INT_FAST32_MIN (-__INT_FAST32_MAX__ - 1)
-#define INT_FAST32_MAX __INT_FAST32_MAX__
-#define UINT_FAST32_MAX __UINT_FAST32_MAX__
-#define INT_FAST64_MIN (-__INT_FAST64_MAX__ - 1)
-#define INT_FAST64_MAX __INT_FAST64_MAX__
-#define UINT_FAST64_MAX __UINT_FAST64_MAX__
+#define INT_FAST8_MIN (-__INT_FAST8_MAX__ - 1) /**< @hideinitializer */
+#define INT_FAST8_MAX __INT_FAST8_MAX__ /**< @hideinitializer */
+#define UINT_FAST8_MAX __UINT_FAST8_MAX__ /**< @hideinitializer */
+#define INT_FAST16_MIN (-__INT_FAST16_MAX__ - 1) /**< @hideinitializer */
+#define INT_FAST16_MAX __INT_FAST16_MAX__ /**< @hideinitializer */
+#define UINT_FAST16_MAX __UINT_FAST16_MAX__ /**< @hideinitializer */
+#define INT_FAST32_MIN (-__INT_FAST32_MAX__ - 1) /**< @hideinitializer */
+#define INT_FAST32_MAX __INT_FAST32_MAX__ /**< @hideinitializer */
+#define UINT_FAST32_MAX __UINT_FAST32_MAX__ /**< @hideinitializer */
+#define INT_FAST64_MIN (-__INT_FAST64_MAX__ - 1) /**< @hideinitializer */
+#define INT_FAST64_MAX __INT_FAST64_MAX__ /**< @hideinitializer */
+#define UINT_FAST64_MAX __UINT_FAST64_MAX__ /**< @hideinitializer */
-#define INTPTR_MIN (-__INTPTR_MAX__ - 1)
-#define INTPTR_MAX __INTPTR_MAX__
-#define UINTPTR_MAX __UINTPTR_MAX__
+#define INTPTR_MIN (-__INTPTR_MAX__ - 1) /**< @hideinitializer */
+#define INTPTR_MAX __INTPTR_MAX__ /**< @hideinitializer */
+#define UINTPTR_MAX __UINTPTR_MAX__ /**< @hideinitializer */
-#define INTMAX_MIN (-__INTMAX_MAX__ - 1)
-#define INTMAX_MAX __INTMAX_MAX__
-#define UINTMAX_MAX __UINTMAX_MAX__
+#define INTMAX_MIN (-__INTMAX_MAX__ - 1) /**< @hideinitializer */
+#define INTMAX_MAX __INTMAX_MAX__ /**< @hideinitializer */
+#define UINTMAX_MAX __UINTMAX_MAX__ /**< @hideinitializer */
-#define PTRDIFF_MIN (-__PTRDIFF_MAX__ - 1)
-#define PTRDIFF_MAX __PTRDIFF_MAX__
+#define PTRDIFF_MIN (-__PTRDIFF_MAX__ - 1) /**< @hideinitializer */
+#define PTRDIFF_MAX __PTRDIFF_MAX__ /**< @hideinitializer */
-#define SIZE_MAX __SIZE_MAX__
+#define SIZE_MAX __SIZE_MAX__ /**< @hideinitializer */
-#define WCHAR_MIN (-__WCHAR_MAX__ - 1)
-#define WCHAR_MAX __WCHAR_MAX__
+#define WCHAR_MIN (-__WCHAR_MAX__ - 1) /**< @hideinitializer */
+#define WCHAR_MAX __WCHAR_MAX__ /**< @hideinitializer */
// NOTE: While GCC and Clang both provide macros for implememting the _C macros,
// they are inconsistent on which is correct, so we implement them ourselves
// below.
-#define INT8_C(value) (value)
-#define INT16_C(value) (value)
-#define INT32_C(value) (value)
-#define INT64_C(value) (value##LL)
-#define INTMAX_C(value) (value##LL)
+#define INT8_C(value) (value) /**< @hideinitializer */
+#define INT16_C(value) (value) /**< @hideinitializer */
+#define INT32_C(value) (value) /**< @hideinitializer */
+#define INT64_C(value) (value##LL) /**< @hideinitializer */
+#define INTMAX_C(value) (value##LL) /**< @hideinitializer */
-#define UINT8_C(value) (value##U)
-#define UINT16_C(value) (value##U)
-#define UINT32_C(value) (value##U)
-#define UINT64_C(value) (value##ULL)
-#define UINTMAX_C(value) (value##ULL)
+#define UINT8_C(value) (value##U) /**< @hideinitializer */
+#define UINT16_C(value) (value##U) /**< @hideinitializer */
+#define UINT32_C(value) (value##U) /**< @hideinitializer */
+#define UINT64_C(value) (value##ULL) /**< @hideinitializer */
+#define UINTMAX_C(value) (value##ULL) /**< @hideinitializer */
#endif // OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_STDINT_H_
diff --git a/sw/device/lib/base/freestanding/stdnoreturn.h b/sw/device/lib/base/freestanding/stdnoreturn.h
index 925ac88..bf17afd 100644
--- a/sw/device/lib/base/freestanding/stdnoreturn.h
+++ b/sw/device/lib/base/freestanding/stdnoreturn.h
@@ -6,6 +6,9 @@
#define OPENTITAN_SW_DEVICE_LIB_BASE_FREESTANDING_STDNORETURN_H_
/**
+ * @file
+ * @brief C library _Noreturn (Freestanding)
+ *
* This header implements the stdnoreturn.h standard header, as required by C11
* S4p6. This header is specified in detail in S7.23 of the same.
*/
diff --git a/sw/device/lib/base/memory.h b/sw/device/lib/base/memory.h
index 1e0f277..f4df0cf 100644
--- a/sw/device/lib/base/memory.h
+++ b/sw/device/lib/base/memory.h
@@ -5,6 +5,14 @@
#ifndef OPENTITAN_SW_DEVICE_LIB_BASE_MEMORY_H_
#define OPENTITAN_SW_DEVICE_LIB_BASE_MEMORY_H_
+/**
+ * @file
+ * @brief OpenTitan Device Memory Library
+ *
+ * This library provides memory functions for aligned word accesses, and some
+ * useful functions from the C library's <string.h>.
+ */
+
#include <stdalign.h>
#include <stddef.h>
#include <stdint.h>
diff --git a/sw/device/lib/base/mmio.h b/sw/device/lib/base/mmio.h
index 91b06bc..885b9bf 100644
--- a/sw/device/lib/base/mmio.h
+++ b/sw/device/lib/base/mmio.h
@@ -17,6 +17,9 @@
#endif // __cplusplus
/**
+ * @file
+ * @brief Memory-mapped IO functions, for volatile access.
+ *
* Memory-mapped IO functions, which either map to volatile accesses, or can be
* replaced with instrumentation calls at compile time, for use with tests.
*
diff --git a/sw/device/lib/base/stdasm.h b/sw/device/lib/base/stdasm.h
index 9dacb09..14cfd94 100644
--- a/sw/device/lib/base/stdasm.h
+++ b/sw/device/lib/base/stdasm.h
@@ -6,8 +6,9 @@
#define OPENTITAN_SW_DEVICE_LIB_BASE_STDASM_H_
/**
- * This header simply provides the `asm` keyword, in analogy with the ISO C
- * headers `stdbool.h`, `stdnoreturn.h`, and so on.
+ * @file
+ * @brief This header simply provides the `asm` keyword, in analogy with the ISO
+ * C headers `stdbool.h`, `stdnoreturn.h`, and so on.
*/
#define asm __asm__
diff --git a/sw/device/lib/dif/dif_gpio.h b/sw/device/lib/dif/dif_gpio.h
index 58aa956..428eb34 100644
--- a/sw/device/lib/dif/dif_gpio.h
+++ b/sw/device/lib/dif/dif_gpio.h
@@ -2,6 +2,11 @@
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
+/**
+ * @file
+ * @brief <a href="/hw/ip/gpio/doc/">GPIO</a> Device Interface Functions
+ */
+
#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_GPIO_H_
#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_GPIO_H_
diff --git a/sw/device/lib/dif/dif_plic.h b/sw/device/lib/dif/dif_plic.h
index 0f998cb..a400977 100644
--- a/sw/device/lib/dif/dif_plic.h
+++ b/sw/device/lib/dif/dif_plic.h
@@ -23,13 +23,18 @@
extern const uint32_t kDifPlicMaxPriority;
/**
+ * @file
+ * @brief <a href="/hw/ip/rv_plic/doc/">PLIC</a> Device Interface Functions
+ */
+
+/**
* PLIC interrupt source identifier.
*
* This corresponds to a specific interrupt, and not the device it originates
* from.
*
* This is an unsigned 32-bit value that is at least zero and is less than the
- * `NumSrc` instantiation parameter of the `rv_plic` device.
+ * `NumSrc` instantiation parameterof the `rv_plic` device.
*
* The value 0 corresponds to "No Interrupt".
*/
diff --git a/sw/device/lib/dif/dif_spi_device.h b/sw/device/lib/dif/dif_spi_device.h
index 5257c3e..c81d99c 100644
--- a/sw/device/lib/dif/dif_spi_device.h
+++ b/sw/device/lib/dif/dif_spi_device.h
@@ -17,6 +17,12 @@
#endif // __cplusplus
/**
+ * @file
+ * @brief <a href="/hw/ip/spi_device/doc/">SPI Device</a> Device Interface
+ * Functions
+ */
+
+/**
* Represents a signal edge type.
*/
typedef enum dif_spi_device_edge {
diff --git a/sw/device/lib/dif/dif_uart.h b/sw/device/lib/dif/dif_uart.h
index aa5f35a..8e74660 100644
--- a/sw/device/lib/dif/dif_uart.h
+++ b/sw/device/lib/dif/dif_uart.h
@@ -2,6 +2,11 @@
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
+/**
+ * @file
+ * @brief <a href="/hw/ip/uart/doc/">UART</a> Device Interface Functions
+ */
+
#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_UART_H_
#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_UART_H_
diff --git a/sw/device/lib/runtime/hart.h b/sw/device/lib/runtime/hart.h
index 7ac1e66..066726e 100644
--- a/sw/device/lib/runtime/hart.h
+++ b/sw/device/lib/runtime/hart.h
@@ -11,8 +11,9 @@
#include "sw/device/lib/base/stdasm.h"
/**
- * This header provides functions for controlling the excution of a hart, such
- * as halt-like functionality.
+ * @file
+ * @brief This header provides functions for controlling the excution of a hart,
+ * such as halt-like functionality.
*/
/**
diff --git a/sw/device/lib/runtime/ibex.h b/sw/device/lib/runtime/ibex.h
index a6081f5..ce8a087 100644
--- a/sw/device/lib/runtime/ibex.h
+++ b/sw/device/lib/runtime/ibex.h
@@ -10,8 +10,9 @@
#include "sw/device/lib/base/stdasm.h"
/**
- * This header provides Ibex-specific functions, such as cycle-accurate busy
- * loops.
+ * @file
+ * @brief This header provides Ibex-specific functions, such as cycle-accurate
+ * busy loops.
*/
/**
