mirror of
https://github.com/apache/nuttx.git
synced 2026-10-03 04:07:55 +00:00
e17d776357
This change mentions the special Kconfig settings for custom boards to tell the build system about properties that are defined using the `HAVE` options for in-tree boards. It also specifically mentions to avoid using Kconfig `if` guards around the custom board Kconfig, which would be a gotcha for people copying from in-tree boards. Signed-off-by: Matteo Golin <matteo.golin@gmail.com> fix
139 lines
4.8 KiB
ReStructuredText
139 lines
4.8 KiB
ReStructuredText
====================
|
|
Custom Boards How-To
|
|
====================
|
|
|
|
As explained in :doc:`../quickstart/configuring`, supported boards (also known
|
|
as "in-tree" boards) are configured using a standard syntax:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd nuttx
|
|
$ ./tools/configure.sh -l board-name:config-name
|
|
Copy files
|
|
Select CONFIG_HOST_LINUX=y
|
|
Refreshing...
|
|
|
|
Sometimes it is not appropriate, or not wanted, to add a new or custom board to
|
|
the NuttX boards tree itself. If so, the board can be defined out-of-tree in a
|
|
custom directory and still be built easily.
|
|
|
|
Add a Custom Board
|
|
==================
|
|
|
|
The same set of files as provided for in-tree boards is required (i.e. configs,
|
|
Kconfig, scripts, etc.) but these can be placed in a directory of your choice.
|
|
|
|
In this example, the files are assumed to exist in:
|
|
``../nuttx/CustomBoards/MyCustomBoardName``
|
|
|
|
.. code-block:: console
|
|
|
|
$pwd
|
|
/home/nuttx/nuttx
|
|
$ ls -1 ../CustomBoards/MyCustomBoardName
|
|
configs
|
|
helpers
|
|
include
|
|
Kconfig
|
|
scripts
|
|
$ ls ../CustomBoards/MyCustomBoardName/configs
|
|
nsh
|
|
MyCustomConfig
|
|
$
|
|
|
|
At this stage, the contents of the files is not important. The notable exception to this
|
|
is file named ``defconfig``, which is stored in the directory ``MyCustomConfig`` (see
|
|
the listing above.)
|
|
|
|
This file is autogenerated and should not be edited manually. However, it should also
|
|
not be copied blindly from an existing board as the values within are incorrect
|
|
for the custom board. This causes an issue because the configure script called below
|
|
is supposed to create some symbolic links in the NuttX source tree and it is using
|
|
the contents of the ``defconfig`` file for that. Since the file does not exist,
|
|
configure script will fail which prevents the user from creating the ``defconfig``
|
|
file automatically.
|
|
|
|
As a workaround, a minimal ``defconfig`` file needs to be provided. See an example
|
|
for AVR architecture:
|
|
|
|
.. code-block:: kconfig
|
|
|
|
CONFIG_ARCH="avr"
|
|
CONFIG_ARCH_AVR=y
|
|
CONFIG_ARCH_BOARD_CUSTOM=y
|
|
CONFIG_ARCH_BOARD_CUSTOM_DIR_RELPATH=y
|
|
CONFIG_ARCH_BOARD_CUSTOM_DIR="../CustomBoards/MyCustomBoardName/"
|
|
CONFIG_ARCH_BOARD_CUSTOM_NAME="MyCustomBoardName"
|
|
CONFIG_ARCH_CHIP="avrdx"
|
|
|
|
This minimal file should be sufficient for the configure script to succeed. Additional
|
|
changes can be made using ``make menuconfig`` and proper ``defconfig`` file can then
|
|
be generated using ``make savedefconfig``.
|
|
|
|
To build the custom board, alter the contents of the example above to fit your
|
|
architecture and chip, then use this syntax, which is slightly different
|
|
from in-tree boards and configs:
|
|
|
|
.. code-block:: console
|
|
|
|
$ ./tools/configure.sh -l ../CustomBoards/MyCustomBoardName/configs/MyCustomConfig
|
|
Copy files
|
|
Select CONFIG_HOST_LINUX=y
|
|
Refreshing...
|
|
|
|
Kconfig Settings
|
|
================
|
|
|
|
Once the board is configured, to ensure subsequent builds run correctly, there
|
|
are two Kconfig settings that need to be set. These are:
|
|
|
|
:menuselection:`Board Selection --> Custom Board Configuration --> Custom Board Name`
|
|
|
|
:menuselection:`Board Selection --> Custom Board Configuration --> Relative custom board directory`
|
|
|
|
They should be set to suit your board name and directory location.
|
|
|
|
.. Note::
|
|
If you subsequently run a ``make distclean`` operation, then these settings will be lost.
|
|
They should be added back before building, and/or before running ``make menuconfig``.
|
|
|
|
Kconfig flags
|
|
-------------
|
|
|
|
Some boards make using of Kconfig ``ARCH_HAVE_*`` flags in order to be able to
|
|
select certain features. For example, ``ARCH_HAVE_LEDS`` is a necessary flag for
|
|
enabling ``CONFIG_ARCH_LEDS=y`` because it tells the build system that the board
|
|
has LEDs. Selecting ``ARCH_HAVE_*`` flags happens inside the NuttX build
|
|
system, so it is not accessible to custom boards. If you need to enable these
|
|
flags, then you should select them manually with the ``BOARD_CUSTOM_*`` options:
|
|
|
|
* ``BOARD_CUSTOM_LEDS`` selects ``ARCH_HAVE_LEDS``
|
|
* ``BOARD_CUSTOM_BUTTONS`` selects ``ARCH_HAVE_BUTTONS``
|
|
* ``BOARD_CUSTOM_IRQBUTTONS`` selects ``ARCH_HAVE_IRQBUTTONS``
|
|
* ``BOARD_CUSTOM_INTERRUPT`` selects ``ARCH_PHY_INTERRUPT``
|
|
|
|
If there are any other ``ARCH_HAVE_*`` selectors you cannot access but need for
|
|
your custom board, please open an issue!
|
|
|
|
Kconfig file
|
|
------------
|
|
|
|
You may have noticed that in-tree boards typically surround their board-level
|
|
Kconfig logic with something like:
|
|
|
|
.. code:: kconfig
|
|
|
|
if ARCH_BOARD_BOARDNAME
|
|
endif # ARCH_BOARD_BOARDAME
|
|
|
|
You should **not** do this for custom boards; just write your Kconfig logic
|
|
without the guard. However, it is still good practice to prefix your custom
|
|
Kconfig options with the board name:
|
|
|
|
.. code:: kconfig
|
|
|
|
config BOARDNAME_MYOPTION
|
|
bool "My custom option"
|
|
default n
|
|
---help---
|
|
This is my custom option for my custom board.
|