This is an automated email from the ASF dual-hosted git repository. xiaoxiang pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 2d6df43ca2394e9c822f25dbb4cbd97d22458e55 Author: Ludovic Vanasse <[email protected]> AuthorDate: Mon Oct 14 12:36:48 2024 -0400 Doc: Migrate including files in board.h Migrate including files in board.h (https://cwiki.apache.org/confluence/display/NUTTX/Including+Files+in+board.h) to official wiki Signed-off-by: Ludovic Vanasse <[email protected]> --- Documentation/guides/include_files_board_h.rst | 73 ++++++++++++++++++++++++++ Documentation/guides/index.rst | 1 + 2 files changed, 74 insertions(+) diff --git a/Documentation/guides/include_files_board_h.rst b/Documentation/guides/include_files_board_h.rst new file mode 100644 index 0000000000..103ab5b075 --- /dev/null +++ b/Documentation/guides/include_files_board_h.rst @@ -0,0 +1,73 @@ +========================== +Including Files in board.h +========================== + +.. warning:: + Migrated from: https://cwiki.apache.org/confluence/display/NUTTX/Including+Files+in+board.h + +Global Scope of board.h +======================= + +Each board under the ``boards/`` directory must provide a header file call +``board.h`` in the board's ``include/`` sub-directory. + +When the board is configured symbolic links will be created to the board's +``board.h`` header file at ``include/arch/board/board.h``. Header files at that +location have `Global Scope` meaning they can be included by C/C++ logic +anywhere in the system. For example, the ``board.h`` file can be included by +any file with: + +.. code-block:: C + + #include <arch/board/board.h> + +Restricted Scope of Architecture-Specific Header Files +====================================================== + +Each architecture also provides internal architecture-specific header files +that can be included only by (1) the architecture logic itself and (2) by +board logic based on that architecture. This is made possible by special +include path options in the CFLAGS provided by the NuttX build system to +the architecture and board logic `only`. + +For this reason, the scope of the architecture-specific header files is +`restricted`. Any attempt to include the architecture-specific header files +by logic other than architecture- or board-specific logic will result in a +compilation error. This is the intended behavior; it is implemented this way +to prevent the use of such `restricted`, non-portable files throughout the OS. +Doing so would degrade the modularity of the OS and would take many giant +steps down the path toward `spaghetti code`. + + +Errors due to Mixed Scope of Header Files +========================================= + +The ``board.h`` header file is included in many contexts including both by the +architecture- and board-specific logic but also by other common OS logic. +As examples: + +* Architecture-specific code may include the ``board.h`` header file to get GPIO + pin definitions or to get configuration information to configure processor + clocking. +* Common LED and button drivers include board's ``board.h`` header file to get + LED and button definitions, respectively. +* Applications may include the ``board.h`` header file to get, for example, + ``boardctl()`` board-specific IOCTL commands. + +In the first example, the ``board.h`` header file often uses pre-processor symbols +that require definition from an architecture-specific header file. For example, +GPIO pin definitions or clock configuration register settings. However, `you +must avoid the temptation to include any of those architecture-specific header +files in the board.h header file. This is prohibited!` That would be a +"time bomb" waiting to cause a compilation failure in the future. + +So How Do I Avoid This? +======================= + +The only way to avoid this header file inclusion trap is: + +* Never include architecture-specific header files in the ``board.h`` header file. + Instead, +* Include the header files needed by the the ``board.h`` header file in the C file + that includes ``board.h`` +* Make sure that ``board.h`` is the last header file included. \ No newline at end of file diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst index a10ecdabe4..ccf17b7acc 100644 --- a/Documentation/guides/index.rst +++ b/Documentation/guides/index.rst @@ -40,3 +40,4 @@ Guides usingkernelthreads.rst armv7m_runtimestackcheck.rst disabling_stackdumpdebug.rst + include_files_board_h.rst
