Merge pull request #17133 from chrysn-pull-requests/doc-develhelp-stackoverflow-precision

doc: Start documenting pseudomodules

cpu/cortexm_common/vectors_cortexm.c

@@ -161,10 +161,7 @@ void reset_handler_default(void)
 #endif /* CPU_HAS_BACKUP_RAM */
 
 #ifdef MODULE_MPU_NOEXEC_RAM
-    /* Mark the RAM non executable. This is a protection mechanism which
+    /* This marks the memory region from 0x20000000 to 0x3FFFFFFF as non
-     * makes exploitation of buffer overflows significantly harder.
-     *
-     * This marks the memory region from 0x20000000 to 0x3FFFFFFF as non
      * executable. This is the Cortex-M SRAM region used for on-chip RAM.
      */
     mpu_configure(

doc.txt

@@ -41,7 +41,8 @@
  * The following list of what `DEVELHELP=1` enables is not comprehensive, but
  * should give a rough impression of what to expect:
  *
- * * Many runtime checks are enabled (stack overflow protection, warnings when
+ * * Many runtime checks are enabled (stack overflow protection by means of
+ *   @ref pseudomodule_mpu_stack_guard or @ref SCHED_TEST_STACK, warnings when
  *   sending messages to invalid PIDs, …), some of which just log errors to
  *   stdout, some even halt the system.
  * * Some structures contain additional information, e.g. threads store their

doc/doxygen/riot.doxyfile

@@ -275,7 +275,9 @@ OPTIMIZE_OUTPUT_VHDL   = NO
 # Note that for custom extensions you also need to set FILE_PATTERNS otherwise
 # the files are not read by doxygen.
 
-EXTENSION_MAPPING      =
+# Python is close enough that we can have Makefile comments starting with `##`
+# that are both recognized by Doxygen and comments to Make
+EXTENSION_MAPPING      = mk=Python
 
 # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
 # according to the Markdown format, which allows for more readable
@@ -771,7 +773,8 @@ INPUT                  = ../../doc.txt \
                          src/emulators.md \
                          src/release-cycle.md \
                          src/changelog.md \
-                         ../../LOSTANDFOUND.md
+                         ../../LOSTANDFOUND.md \
+                         ../../makefiles/pseudomodules.inc.mk
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

makefiles/pseudomodules.inc.mk

@@ -1,6 +1,38 @@
+## @defgroup pseudomodules Generic pseudomodules
+## @brief Modules influencing general RIOT behavior
+##
+## These are implemented in other modules or core components,
+## and serve to enable certain functionality.
+##
+## Here, pseudomodules are used instead of plain defines (that would be set using `CFLAGS += -DMODULE_NAME`)
+## because they can participate in dependency resolution:
+## they can pull in other modules.
+##
+## Pseudomodules are often enabled automatically through module dependencies,
+## but can also be enabled manually by stating `USEMODULE += module_name` in the Makefile.
+##
+## The list of documented pseudomodules is not comprehensive by far;
+## @ref makefiles/pseudomodules.inc.mk lists all that are not defined inside their main modules.
+## Not all modules listed there are "generic" pseudomodules;
+## some are merely optional components of a particular subsystem and should be documented there.
+##
+## See also <a href="creating-modules.html#pseudomodules">the documentation on pseudomodules in general</a>.
+##
+## @{
+
 PSEUDOMODULES += atomic_utils
 PSEUDOMODULES += base64url
+
+## @defgroup pseudomodule_board_software_reset board_software_reset
+## @brief Use any software-only reset button on the board to reboot
+##
+## Some boards have reset buttons that are not wired to the MCU's reset line,
+## but merely are configured to cause a reset by convention.
+##
+## If this module is active, the button will be configured thusly (and then not
+## be advertised in any other capacity, e.g. through @ref sys_auto_init_saul).
 PSEUDOMODULES += board_software_reset
+
 PSEUDOMODULES += can_mbox
 PSEUDOMODULES += can_pm
 PSEUDOMODULES += can_raw
@@ -87,8 +119,21 @@ PSEUDOMODULES += log
 PSEUDOMODULES += log_printfnoformat
 PSEUDOMODULES += log_color
 PSEUDOMODULES += lora
+
+## @defgroup pseudomodule_mpu_stack_guard mpu_stack_guard
+## @brief MPU based stack guard
+##
+## When this module is active (which it is by default on supported MCUs),
+## the Memory Protection Unit will be configured to detect stack overflows.
 PSEUDOMODULES += mpu_stack_guard
+
+## @defgroup pseudomodule_mpu_noexec_ram mpu_noexec_ram
+## @brief Mark RAM as non-executable using the MPU
+##
+## Mark the RAM non executable.
+## This is a protection mechanism which makes exploitation of buffer overflows significantly harder.
 PSEUDOMODULES += mpu_noexec_ram
+
 PSEUDOMODULES += mtd_write_page
 PSEUDOMODULES += nanocoap_%
 PSEUDOMODULES += netdev_default
@@ -214,3 +259,5 @@ NO_PSEUDOMODULES += auto_init_usbus
 NO_PSEUDOMODULES += auto_init_screen
 
 # Packages and drivers may also add modules to PSEUDOMODULES in their `Makefile.include`.
+
+## @}