From 302b41d5397e9f821d360a74335e8821d4513970 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 1 Apr 2025 16:55:23 -0600 Subject: Kbuild: Always use $(PHASE_) It is confusing to have both "$(PHASE_)" and "$(XPL_)" be used in our Makefiles as part of the macros to determine when to do something in our Makefiles based on what phase of the build we are in. For consistency, bring this down to a single macro and use "$(PHASE_)" only. Signed-off-by: Tom Rini --- doc/develop/tests_writing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/tests_writing.rst b/doc/develop/tests_writing.rst index 7ea17081def..f6f852c297d 100644 --- a/doc/develop/tests_writing.rst +++ b/doc/develop/tests_writing.rst @@ -309,15 +309,15 @@ an #ifdef since the suite will automatically be compiled out in that case. Finally, add the test to the build by adding to the Makefile in the same directory:: - obj-$(CONFIG_$(XPL_)CMDLINE) += wibble.o + obj-$(CONFIG_$(PHASE_)CMDLINE) += wibble.o Note that CMDLINE is never enabled in SPL, so this test will only be present in U-Boot proper. See below for how to do SPL tests. You can add an extra Kconfig check if needed:: - ifneq ($(CONFIG_$(XPL_)WIBBLE),) - obj-$(CONFIG_$(XPL_)CMDLINE) += wibble.o + ifneq ($(CONFIG_$(PHASE_)WIBBLE),) + obj-$(CONFIG_$(PHASE_)CMDLINE) += wibble.o endif Each suite can have an optional init and uninit function. These are run before -- cgit v1.2.3 From 0471f8d0012ff9794014d222151acb65ce387550 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 1 Apr 2025 16:55:24 -0600 Subject: doc/develop/codingstyle.rst: Add a section on conditional compilation In order to make a start on explaining how and when to use certain macros, we need to document their usage somewhere. As a first step, take section 21 of the v6.13 Linux Kernel coding-style document on conditional compilation, verbatim, and add it to our documentation. Further rewording to be clearer about U-Boot will be done next. Signed-off-by: Tom Rini --- doc/develop/codingstyle.rst | 48 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) (limited to 'doc/develop') diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst index fa3cd6aec82..7211e4e4eed 100644 --- a/doc/develop/codingstyle.rst +++ b/doc/develop/codingstyle.rst @@ -154,6 +154,54 @@ See `here `_ for style. +Conditional Compilation +----------------------- + +Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c +files; doing so makes code harder to read and logic harder to follow. Instead, +use such conditionals in a header file defining functions for use in those .c +files, providing no-op stub versions in the #else case, and then call those +functions unconditionally from .c files. The compiler will avoid generating +any code for the stub calls, producing identical results, but the logic will +remain easy to follow. + +Prefer to compile out entire functions, rather than portions of functions or +portions of expressions. Rather than putting an ifdef in an expression, factor +out part or all of the expression into a separate helper function and apply the +conditional to that function. + +If you have a function or variable which may potentially go unused in a +particular configuration, and the compiler would warn about its definition +going unused, mark the definition as __maybe_unused rather than wrapping it in +a preprocessor conditional. (However, if a function or variable *always* goes +unused, delete it.) + +Within code, where possible, use the IS_ENABLED macro to convert a Kconfig +symbol into a C boolean expression, and use it in a normal C conditional: + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +The compiler will constant-fold the conditional away, and include or exclude +the block of code just as with an #ifdef, so this will not add any runtime +overhead. However, this approach still allows the C compiler to see the code +inside the block, and check it for correctness (syntax, types, symbol +references, etc). Thus, you still have to use an #ifdef if the code inside the +block references symbols that will not exist if the condition is not met. + +At the end of any non-trivial #if or #ifdef block (more than a few lines), +place a comment after the #endif on the same line, noting the conditional +expression used. For instance: + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + Driver model ------------ -- cgit v1.2.3 From fa72470a4ec5522fe92986bb53b22167d35d0913 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 1 Apr 2025 16:55:25 -0600 Subject: doc/develop/codingstyle.rst: Expand to include CONFIG_IS_ENABLED and PHASE_ Expand the conditional compilation section to explain when to use CONFIG_IS_ENABLED rather than IS_ENABLED and provide an example. Next, note what the PHASE_ macro is supposed to be used for as well. Signed-off-by: Tom Rini --- doc/develop/codingstyle.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'doc/develop') diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst index 7211e4e4eed..bc18b2ebb7b 100644 --- a/doc/develop/codingstyle.rst +++ b/doc/develop/codingstyle.rst @@ -192,6 +192,25 @@ inside the block, and check it for correctness (syntax, types, symbol references, etc). Thus, you still have to use an #ifdef if the code inside the block references symbols that will not exist if the condition is not met. +When working with xPL (see :doc:`spl` for more information) we need to take +further care to use the right macro. In the case where a symbol may be +referenced with an xPL-specific Kconfig symbol, use the CONFIG_IS_ENABLED macro +instead, in a similar manner: + +.. code-block:: c + + if (CONIG_IS_ENABLED(SOMETHING)) { + ... + } + +When dealing with a Kconfig symbol that has both a normal name and one or more +xPL-prefixed names, the Makefile needs special consideration as well. The +PHASE\_ macro helps us in this situation thusly: + +.. code-block:: make + + obj-$(CONFIG_$(PHASE_)SOMETHING) += something.o + At the end of any non-trivial #if or #ifdef block (more than a few lines), place a comment after the #endif on the same line, noting the conditional expression used. For instance: -- cgit v1.2.3