From 68d0c291a9d16ab50b5b77738a0e7ec9b2b39437 Mon Sep 17 00:00:00 2001 From: chrysn Date: Thu, 4 Nov 2021 09:54:32 +0100 Subject: [PATCH 1/5] doc: Initial documentation of pseudomodules Co-authored-by: Francisco --- doc/doxygen/riot.doxyfile | 7 +++++-- makefiles/pseudomodules.inc.mk | 20 ++++++++++++++++++++ 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile index 6bf18e0536..35a78a3c42 100644 --- a/doc/doxygen/riot.doxyfile +++ b/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 diff --git a/makefiles/pseudomodules.inc.mk b/makefiles/pseudomodules.inc.mk index c2a03b2d4a..0b3013c764 100644 --- a/makefiles/pseudomodules.inc.mk +++ b/makefiles/pseudomodules.inc.mk @@ -1,3 +1,21 @@ +## @defgroup pseudomodules Pseudomodules +## @brief Modules without dedicated files +## +## These are implemented in other modules or core components, +## and serve to enable certain functionality. +## +## 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. +## +## @{ + PSEUDOMODULES += atomic_utils PSEUDOMODULES += base64url PSEUDOMODULES += board_software_reset @@ -214,3 +232,5 @@ NO_PSEUDOMODULES += auto_init_usbus NO_PSEUDOMODULES += auto_init_screen # Packages and drivers may also add modules to PSEUDOMODULES in their `Makefile.include`. + +## @} From bb8402fc0b2c21cbd2539dca6cff2a36b63258d0 Mon Sep 17 00:00:00 2001 From: chrysn Date: Thu, 4 Nov 2021 09:55:18 +0100 Subject: [PATCH 2/5] doc: Document the MPU pseudomodules --- cpu/cortexm_common/vectors_cortexm.c | 5 +---- makefiles/pseudomodules.inc.mk | 13 +++++++++++++ 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/cpu/cortexm_common/vectors_cortexm.c b/cpu/cortexm_common/vectors_cortexm.c index 6652ee702f..9159f319c0 100644 --- a/cpu/cortexm_common/vectors_cortexm.c +++ b/cpu/cortexm_common/vectors_cortexm.c @@ -158,10 +158,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 - * makes exploitation of buffer overflows significantly harder. - * - * This marks the memory region from 0x20000000 to 0x3FFFFFFF as non + /* 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( diff --git a/makefiles/pseudomodules.inc.mk b/makefiles/pseudomodules.inc.mk index 0b3013c764..bb6e6db491 100644 --- a/makefiles/pseudomodules.inc.mk +++ b/makefiles/pseudomodules.inc.mk @@ -105,8 +105,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 From dcd08c257b87add5150562924d5a8086e411f609 Mon Sep 17 00:00:00 2001 From: chrysn Date: Thu, 4 Nov 2021 09:57:29 +0100 Subject: [PATCH 3/5] doc: Link concrete measures from DEVELHELP documentation --- doc.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc.txt b/doc.txt index c88e9cdd19..78dca2c188 100644 --- a/doc.txt +++ b/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 From 15398a53cbff9c376f69a04ee07a4abe2d9c43ec Mon Sep 17 00:00:00 2001 From: chrysn Date: Thu, 27 Jan 2022 11:03:28 +0100 Subject: [PATCH 4/5] doc: Sharpen list of pseudomodules in documentation Not all pseudomodules should go here; this is mainly for those that don't belon anywhere else. --- makefiles/pseudomodules.inc.mk | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/makefiles/pseudomodules.inc.mk b/makefiles/pseudomodules.inc.mk index bb6e6db491..cf0ac04342 100644 --- a/makefiles/pseudomodules.inc.mk +++ b/makefiles/pseudomodules.inc.mk @@ -1,10 +1,10 @@ -## @defgroup pseudomodules Pseudomodules -## @brief Modules without dedicated files +## @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. ## -## Pseudomodules are used instead of plain defines (that would be set using `CFLAGS += -DMODULE_NAME`) +## 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. ## @@ -13,6 +13,10 @@ ## ## 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 the documentation on pseudomodules in general. ## ## @{ From 1e8209f80ebe8812471cdc8db5c48ca77052232e Mon Sep 17 00:00:00 2001 From: chrysn Date: Thu, 27 Jan 2022 11:14:21 +0100 Subject: [PATCH 5/5] pseudomodules: Documentation for board_software_reset --- makefiles/pseudomodules.inc.mk | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/makefiles/pseudomodules.inc.mk b/makefiles/pseudomodules.inc.mk index cf0ac04342..a6cb65a2b8 100644 --- a/makefiles/pseudomodules.inc.mk +++ b/makefiles/pseudomodules.inc.mk @@ -22,7 +22,17 @@ 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