From 1ad2cda49668be9220f4e96e05e2bec943c041fe Mon Sep 17 00:00:00 2001
From: Karl Palsson <karlp@tweak.net.au>
Date: Sun, 9 Sep 2018 15:21:02 +0000
Subject: [PATCH] doc: add all cm3 headers to doxygen.

Just get them all included as they are.  Gets them grouped up and
visible so we can start clarifying the rest of their docs.
---
 include/libopencm3/cm3/assert.h | 1 +
 include/libopencm3/cm3/dwt.h    | 8 ++++++++
 include/libopencm3/cm3/fpb.h    | 8 +++++++-
 include/libopencm3/cm3/itm.h    | 8 +++++++-
 include/libopencm3/cm3/scb.h    | 7 +++++++
 include/libopencm3/cm3/scs.h    | 5 ++++-
 include/libopencm3/cm3/tpiu.h   | 8 +++++++-
 7 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/include/libopencm3/cm3/assert.h b/include/libopencm3/cm3/assert.h
index f1aabc3c..528eb0ff 100644
--- a/include/libopencm3/cm3/assert.h
+++ b/include/libopencm3/cm3/assert.h
@@ -1,4 +1,5 @@
 /** @defgroup debugging Debugging
+@ingroup CM3_defines
 
 @brief Macros and functions to aid in debugging
 
diff --git a/include/libopencm3/cm3/dwt.h b/include/libopencm3/cm3/dwt.h
index 184b509e..73b5291e 100644
--- a/include/libopencm3/cm3/dwt.h
+++ b/include/libopencm3/cm3/dwt.h
@@ -20,6 +20,12 @@
 #ifndef LIBOPENCM3_CM3_DWT_H
 #define LIBOPENCM3_CM3_DWT_H
 
+/**
+ * @defgroup cm_fpb Cortex-M Flash Patch and Breakpoint (FPB) unit
+ * @ingroup CM3_defines
+ * @{
+ */
+
 #include <libopencm3/cm3/common.h>
 #include <libopencm3/cm3/memorymap.h>
 
@@ -149,4 +155,6 @@ uint32_t dwt_read_cycle_counter(void);
 
 END_DECLS
 
+/**@}*/
+
 #endif /* LIBOPENCM3_CM3_DWT_H */
diff --git a/include/libopencm3/cm3/fpb.h b/include/libopencm3/cm3/fpb.h
index 805ddbb9..e7527fcc 100644
--- a/include/libopencm3/cm3/fpb.h
+++ b/include/libopencm3/cm3/fpb.h
@@ -20,7 +20,11 @@
 #ifndef LIBOPENCM3_CM3_FPB_H
 #define LIBOPENCM3_CM3_FPB_H
 
-/* Cortex-M3 Flash Patch and Breakpoint (FPB) unit */
+/**
+ * @defgroup cm_fpb Cortex-M Flash Patch and Breakpoint (FPB) unit
+ * @ingroup CM3_defines
+ * @{
+ */
 
 /* Those defined only on ARMv7 and above */
 #if !defined(__ARM_ARCH_7M__) && !defined(__ARM_ARCH_7EM__)
@@ -84,4 +88,6 @@
 
 #define FPB_COMP_ENABLE			(1 << 0)
 
+/**@}*/
+
 #endif
diff --git a/include/libopencm3/cm3/itm.h b/include/libopencm3/cm3/itm.h
index d549fc2f..ac5dbbd9 100644
--- a/include/libopencm3/cm3/itm.h
+++ b/include/libopencm3/cm3/itm.h
@@ -20,7 +20,11 @@
 #ifndef LIBOPENCM3_CM3_ITM_H
 #define LIBOPENCM3_CM3_ITM_H
 
-/* Cortex-M3 Instrumentation Trace Macrocell (ITM) */
+/**
+ * @defgroup cm_itm Cortex-M Instrumentation Trace Macrocell (ITM)
+ * @ingroup CM3_defines
+ * @{
+ */
 
 /* Those defined only on ARMv7 and above */
 #if !defined(__ARM_ARCH_7M__) && !defined(__ARM_ARCH_7EM__)
@@ -85,4 +89,6 @@
 #define ITM_TCR_TSENA			(1 << 1)
 #define ITM_TCR_ITMENA			(1 << 0)
 
+/**@}*/
+
 #endif
diff --git a/include/libopencm3/cm3/scb.h b/include/libopencm3/cm3/scb.h
index 8c2465da..aa9dc74a 100644
--- a/include/libopencm3/cm3/scb.h
+++ b/include/libopencm3/cm3/scb.h
@@ -21,6 +21,11 @@
 #ifndef LIBOPENCM3_SCB_H
 #define LIBOPENCM3_SCB_H
 
+/**
+ * @defgroup cm_scb Cortex-M System Control Block
+ * @ingroup CM3_defines
+ * @{
+ */
 #include <libopencm3/cm3/memorymap.h>
 #include <libopencm3/cm3/common.h>
 
@@ -447,4 +452,6 @@ void scb_set_priority_grouping(uint32_t prigroup);
 
 END_DECLS
 
+/**@}*/
+
 #endif
diff --git a/include/libopencm3/cm3/scs.h b/include/libopencm3/cm3/scs.h
index 391270ee..898a8fb9 100644
--- a/include/libopencm3/cm3/scs.h
+++ b/include/libopencm3/cm3/scs.h
@@ -28,7 +28,9 @@
  * Processors" for details on System Timer/SysTick.
  */
 
-/*
+/**
+ * @defgroup cm_scs Cortex-M System Control Space
+ * @ingroup CM3_defines
  * The System Control Space (SCS) is a memory-mapped 4KB address space that
  * provides 32-bit registers for configuration, status reporting and control.
  * The SCS registers divide into the following groups:
@@ -328,4 +330,5 @@
 /* CoreSight Lock Access key, common for all */
 #define SCS_LAR_KEY		0xC5ACCE55
 
+/**@}*/
 #endif
diff --git a/include/libopencm3/cm3/tpiu.h b/include/libopencm3/cm3/tpiu.h
index ff215116..74428ba3 100644
--- a/include/libopencm3/cm3/tpiu.h
+++ b/include/libopencm3/cm3/tpiu.h
@@ -20,7 +20,11 @@
 #ifndef LIBOPENCM3_CM3_TPIU_H
 #define LIBOPENCM3_CM3_TPIU_H
 
-/* Cortex-M3 Trace Port Interface Unit (TPIU) */
+/**
+ * @defgroup cm_tpiu Cortex-M Trace Port Interface Unit (TPIU)
+ * @ingroup CM3_defines
+ * @{
+ */
 
 /* Those defined only on ARMv7 and above */
 #if !defined(__ARM_ARCH_7M__) && !defined(__ARM_ARCH_7EM__)
@@ -94,4 +98,6 @@
 #define TPUI_DEVID_FIFO_SIZE_MASK	(7 << 6)
 /* Bits 5:0 - Implementation defined */
 
+/**@}*/
+
 #endif