From: Jiri Vlasak <[email protected]> --- Dear NuttX developers,
the following is a small improvement to the "Boards Support" documentation page. I found out some inconsistencies and format issues that has been fixed in this patch. I also slightly rewrote the "Adding a New Board Configuration" section. Have a nice day, jiri .editorconfig | 5 ++ Documentation/components/boards.rst | 131 +++++++++++++++++----------- 2 files changed, 85 insertions(+), 51 deletions(-) diff --git a/.editorconfig b/.editorconfig index 833ed63d82..35b9cf2171 100644 --- a/.editorconfig +++ b/.editorconfig @@ -14,6 +14,11 @@ max_line_length = 78 curly_bracket_next_line = true indent_brace_style = GNU +[*.rst] +indent_style = space +indent_size = 2 +max_line_length = 80 + [Makefile] indent_style = tab [Make.defs] diff --git a/Documentation/components/boards.rst b/Documentation/components/boards.rst index c05bbe3c09..6c8669b7e8 100644 --- a/Documentation/components/boards.rst +++ b/Documentation/components/boards.rst @@ -28,7 +28,7 @@ The NuttX configuration consists of: These chip-specific files are contained within chip-specific sub-directories in the ``arch/<arch>/`` directory and are selected - via the ``CONFIG_ARCH_name`` selection + via the ``CONFIG_ARCH_name`` selection. * Board specific files. In order to be usable, the chip must be contained in a board environment. The board configuration defines @@ -37,8 +37,8 @@ The NuttX configuration consists of: These board-specific configuration files can be found in the ``boards/<arch>/<chip>/<board>/`` sub-directories. - Additional configuration information may be available in board-specific documentation pages - at ``Documentation/platforms/<arch>/<chip>/<board>``. + Additional board-specific documentation may be available in the documentation + pages at ``Documentation/platforms/<arch>/<chip>/<board>``. The ``boards/`` subdirectory contains configuration data for each board. These board-specific configurations plus the architecture-specific configurations in @@ -52,27 +52,32 @@ board must provide a subdirectory ``<board>`` under ``boards/`` with the following characteristics:: <board> + |-- configs/ + | |-- <config1-dir> + | `-- defconfig + | |-- <config2-dir> + | |-- Make.defs + | `-- defconfig |-- include/ + | |-- board.h | `-- (board-specific header files) + |-- Kconfig + |-- scripts/ + | |-- Make.defs + | `-- <board>.ld |-- src/ | |-- Makefile | `-- (board-specific source files) - |-- <config1-dir> - | |-- Make.defs - | `-- defconfig - |-- <config2-dir> - | |-- Make.defs - | `-- defconfig ... Summary of Files ================ -* ``include/`` -- This directory contains board specific header files. This - directory will be linked as include/arch/board at configuration time and - can be included via #include <arch/board/header.h>``. These header file - can only be included by files in ``arch/<arch>include/`` and - ``arch/<arch>/src`` +* ``include/`` -- This directory contains board specific header files; it will + be linked as ``include/arch/board`` at configuration time and ``header.h`` + files of the directory can be included via ``#include <arch/board/header.h>``. + These header files can only be included by files in ``arch/<arch>/include/`` + and ``arch/<arch>/src/``. * ``src/`` -- This directory contains board specific drivers. This directory will be linked as ``arch/<arch>/src/board`` at configuration @@ -83,10 +88,10 @@ Summary of Files and ``distclean``. A board may have various different configurations using these common source -files. Each board configuration is described by two files: Make.defs and -defconfig. Typically, each set of configuration files is retained in a -separate configuration sub-directory (``<config1-dir>``, ``<config2-dir>``, .. -in the above diagram). +files. Each board configuration is described by two files: (optional) +``Make.defs`` and ``defconfig``. Typically, each set of configuration files is +retained in a separate configuration sub-directory (``<config1-dir>`` and +``<config2-dir>`` in the above diagram). * ``Make.defs`` -- This makefile fragment provides architecture and tool-specific build options. It will be included by all other @@ -181,47 +186,71 @@ Configuring NuttX requires only copying:: Adding a New Board Configuration ================================ -Okay, so you have created a new board configuration directory. -Now, how do you hook this board into the configuration system so -that you can select with ``make menuconfig``? +Okay, so we have a new ``<board>`` configuration directory ``myboard``. How to +hook this board into the configuration system so we can select ``myboard`` with +the ``make menuconfig``? -You will need modify the file ``boards/Kconfig``. Let's look at -the STM32F4-Discovery configuration in the ``Kconfig`` file and -see how we would add a new board directory to the configuration. -For this configuration let's say that you new board resides in the -directory ``boards/myarch/mychip/myboard``; It uses an MCU -selected with ``CONFIG_ARCH_CHIP_MYMCU``; and you want the board -to be selected with ``CONFIG_ARCH_BOARD_MYBOARD``. Then here is -how you can clone the STM32F4-Discovery configuration in -``boards/Kconfig`` to support your new board configuration. +First, we need to modify the ``boards/Kconfig`` file; we can get inspired by the +*STM32F4-Discovery*, for example. In ``boards/Kconfig``, find:: -In ``boards/Kconfig`` for the stm32f4-discovery, you will see a -configuration definition like this: + config ARCH_BOARD_STM32F4_DISCOVERY + bool "STMicro STM32F4-Discovery board" + depends on ARCH_CHIP_STM32F407VG + select ARCH_HAVE_LEDS + select ARCH_HAVE_BUTTONS + select ARCH_HAVE_IRQBUTTONS + ---help--- + STMicro STM32F4-Discovery board based on the STMicro STM32F407VGT6 MCU. -The above selects the STM32F4-Discovery board. The ``select`` -lines say that the board has both LEDs and buttons and that the -board can generate interrupts from the button presses. You can -just copy the above configuration definition to a new location -(notice that they the configurations are in alphabetical order). -Then you should edit the configuration to support your board. The -final configuration definition might look something like: +The above is an option for *STM32F4-Discovery* board. It ``depends on`` the chip +from ``arch/`` directory and the ``select`` lines say that the board has both +LEDs and buttons and that the board can generate interrupts from the button +presses. -Later in the ``boards/Kconfig`` file, you will see a long, long -string configuration with lots of defaults like this: +To add the configuration definition for the new board: -This logic will assign string value to a configuration variable -called ``CONFIG_ARCH_BOARD`` that will name the directory where -the board-specific files reside. In our case, these files reside -in ``boards/myarch/mychip/myboard`` and we add the following to -the long list of defaults (again in alphabetical order): +1. Copy the configuration definition to a new location (notice that the + configurations are/used to be in alphabetical order). -Now the build system knows where to find your board configuration! +2. Update the ``config`` name to reflect the new board, e.g., + ``ARCH_BOARD_MYBOARD``. -And finally, add something like this near the bottom of -``boards/myarch/mychip/myboard``: +3. Edit the configuration with the appropriate ``depends on`` (e.g., + ``ARCH_CHIP_MYCHIP``) and ``select`` lines for the new board. -This includes additional, board-specific configuration variable -definitions in ``boards/myarch/mychip/myboard/Kconfig``. +Later in the ``boards/Kconfig`` file we can see a very long string configuration +``ARCH_BOARD`` with a lot of board-dependent defaults:: + + default "stm32f4discovery" if ARCH_BOARD_STM32F4_DISCOVERY + +This logic will assign a string value to the ``CONFIG_ARCH_BOARD`` that will +name the directory where the board-specific files reside: ``stm32f4discovery`` +value for the *STM32F4-Discovery* board says that the board-specific files are +available in the ``boards/<arch>/<chip>/stm32f4discovery`` directory. ``<arch>`` +and ``<chip>`` depend on ``depends on`` of the board's configuration option and +are ``arm`` and ``stm32`` respectivelly for the *STM32F4-Discovery* board. + +To propagate board-specific directory: + +1. Add another default for ``"myboard"`` (again in alphabetical order):: + + default "myboard" if ARCH_BOARD_MYBOARD + +2. Make sure that the ``myboard`` directory is in the appropriate place for the + ``<arch>`` and ``<chip>``, i.e., ``boards/<arch>/<chip>/myboard``. + +The last update to the ``boards/Kconfig`` file is the inclusion of the +board-specific ``Kconfig`` file. We can find lines similar to:: + + if ARCH_BOARD_STM32F4_DISCOVERY + source "boards/arm/stm32/stm32f4discovery/Kconfig" + endif + +and, inspired by these lines, add to the appropriate place:: + + if ARCH_BOARD_MYBOARD + source "boards/<arch>/<chip>/myboard/Kconfig" + endif Building Symbol Tables ====================== -- 2.47.3
