diff --git a/dist/tools/genconfigheader/genconfigheader.sh b/dist/tools/genconfigheader/genconfigheader.sh index 581ceb55e0..1cdcc7e9e8 100755 --- a/dist/tools/genconfigheader/genconfigheader.sh +++ b/dist/tools/genconfigheader/genconfigheader.sh @@ -17,6 +17,7 @@ set -e echo "/* DO NOT edit this file, your changes will be overwritten and won't take any effect! */" echo "/* Generated from CFLAGS: $@ */" +cat "$(dirname "$0")/riotbuild-prefix.h.in" [ -n "${LTOFLAGS}" ] && echo "/* LTOFLAGS=${LTOFLAGS} */" diff --git a/dist/tools/genconfigheader/riotbuild-prefix.h.in b/dist/tools/genconfigheader/riotbuild-prefix.h.in new file mode 100644 index 0000000000..d3562b06c5 --- /dev/null +++ b/dist/tools/genconfigheader/riotbuild-prefix.h.in @@ -0,0 +1,96 @@ +/* + * Copyright (C) 2024 Otto-von-Guericke-Universität Magdeburg + * + * This file is subject to the terms and conditions of the GNU Lesser General + * Public License v2.1. See the file LICENSE in the top level directory for more + * details. + */ + +/** + * @defgroup config_riotbuild riotbuild.h: Preprocessor Constants to Query the Build System Configuration + * @ingroup config + * + * The RIOT build system generates a header file `riotbuild.h` that is included + * in every C compilation unit by passing the `-include` flag to the C compiler. + * Hence, it provides a set of macros that are unconditionally available and + * can be used by C code to query the build system configuration. + * @{ + */ + +#ifdef DOXYGEN +/** + * @brief The used RIOT version as human readable string literal, e.g., for + * printing to stdio or writing to a log. + */ +#define RIOT_VERSION ".-" + +/** + * @brief The used RIOT version as machine readable number, e.g., for testing + * whether new APIs are available. + * + * @see RIOT_VERSION_NUM + */ +#define RIOT_VERSION_CODE RIOT_VERSION_NUM(,,,) + +/** + * @brief Name of the RIOT application as string literal + * + * The string is defined in the applications `Makefile` using the `APPLICATION` + * variable. + */ +#define RIOT_APPLICATION "" + +/** + * @brief Name of the board the app is compiled for as string literal + */ +#define RIOT_BOARD "" + +/** + * @brief Name of the MCU the app is compiled for as string literal + * + * This is the name of the MCU family in terms of RIOT's peripheral drivers, + * or in other words, the folder name in the `cpu` folder in RIOT's repo root + * used. + */ +#define RIOT_CPU "" + +/** + * @brief Size of the RAM in Bytes + * + * @warning Not every CPU family provides this, it will be undefined if + * not provided + */ +#define CPU_RAM_SIZE /* RAM Size in Bytes */ +#endif /* DOXYGEN */ + +/** + * @brief Mark a preprocessor macro as deprecated by including this + * macro in the definition + * + * Usage: + * ``` C + * /// @deprecated, use @ref BAR instead of FOO + * #define FOO MACRO_DEPRECATED BAR + * ``` + */ +#if defined(DOXYGEN) +# define MACRO_DEPRECATED /* implementation */ +#elif defined(__GNUC__) || defined(__clang__) +# define MACRO_DEPRECATED _Pragma("GCC warning \"Code is using a deprecated macro\"") +#else +# define MACRO_DEPRECATED +#endif + +/** + * @brief Name of the MCU the app is compiled for as string literal + * + * @deprecated Use @ref RIOT_CPU instead. This will be removed soonest in + * release 2025.04 + * + * This has been renamed to `RIOT_CPU` for consistency. Even though MCU would + * technically be the better name, CPU is used every else in the source code + * and folder structure. + */ +#define RIOT_MCU MACRO_DEPRECATED RIOT_CPU + +/** @} */ diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile index aa2e1eba00..71f6b8428f 100644 --- a/doc/doxygen/riot.doxyfile +++ b/doc/doxygen/riot.doxyfile @@ -277,7 +277,7 @@ OPTIMIZE_OUTPUT_VHDL = NO # 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 +EXTENSION_MAPPING = mk=Python in=C # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable @@ -785,7 +785,8 @@ INPUT = ../../doc.txt \ ../../LOSTANDFOUND.md \ ../../makefiles/pseudomodules.inc.mk \ ../../makefiles/blob.inc.mk \ - ../../sys/net/gnrc/routing/ipv6_auto_subnets/gnrc_ipv6_auto_subnets.c + ../../sys/net/gnrc/routing/ipv6_auto_subnets/gnrc_ipv6_auto_subnets.c \ + ../../dist/tools/genconfigheader/riotbuild-prefix.h.in # 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 @@ -807,6 +808,7 @@ INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.txt \ *.h \ + *.h.in \ *.hpp # The RECURSIVE tag can be used to specify whether or not subdirectories should