202 lines
7.7 KiB
ReStructuredText
202 lines
7.7 KiB
ReStructuredText
==============
|
|
Boards Support
|
|
==============
|
|
|
|
This page discusses the board support logic for NuttX.
|
|
|
|
The ``nuttx/boards`` directory is a part of the internal OS. It should contain
|
|
only OS bring-up logic and driver initialization logic.
|
|
|
|
**THERE SHOULD BE NO APPLICATION CALLABLE LOGIC IN THIS DIRECTORY.**
|
|
|
|
If you have board-specific, application callable logic, that logic should not
|
|
go here. Please consider using a sub-directory under ``apps/platform`` instead.
|
|
|
|
Board-Specific Configurations
|
|
=============================
|
|
|
|
The NuttX configuration consists of:
|
|
|
|
* Processor architecture specific files. These are the files contained
|
|
in the ``arch/<arch>/`` directory.
|
|
|
|
* Chip/SoC specific files. Each processor architecture is embedded
|
|
in a chip or System-on-a-Chip (SoC) architecture. The full chip
|
|
architecture includes the processor architecture plus chip-specific
|
|
interrupt logic, general purpose I/O (GIO) logic, and specialized,
|
|
internal peripherals (such as UARTs, USB, etc.).
|
|
|
|
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
|
|
|
|
* Board specific files. In order to be usable, the chip must be
|
|
contained in a board environment. The board configuration defines
|
|
additional properties of the board including such things as
|
|
peripheral LEDs, external peripherals (such as network, USB, etc.).
|
|
|
|
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>``.
|
|
|
|
The ``boards/`` subdirectory contains configuration data for each board. These
|
|
board-specific configurations plus the architecture-specific configurations in
|
|
the ``arch/`` subdirectory completely define a customized port of NuttX.
|
|
|
|
``boards/`` Directory Structure
|
|
===============================
|
|
|
|
The ``boards/`` directory contains board specific configuration logic. Each
|
|
board must provide a subdirectory ``<board>`` under ``boards/`` with the
|
|
following characteristics::
|
|
|
|
<board>
|
|
|-- include/
|
|
| `-- (board-specific header files)
|
|
|-- 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``
|
|
|
|
* ``src/`` -- This directory contains board specific drivers. This
|
|
directory will be linked as ``arch/<arch>/src/board`` at configuration
|
|
time and will be integrated into the build system.
|
|
|
|
* ``src/Makefile`` -- This makefile will be invoked to build the board specific
|
|
drivers. It must support the following targets: ``libext$(LIBEXT)``, ``clean``,
|
|
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).
|
|
|
|
* ``Make.defs`` -- This makefile fragment provides architecture and
|
|
tool-specific build options. It will be included by all other
|
|
makefiles in the build (once it is installed). This make fragment
|
|
should define::
|
|
|
|
Tools: CC, LD, AR, NM, OBJCOPY, OBJDUMP
|
|
Tool options: CFLAGS, LDFLAGS
|
|
|
|
When this makefile fragment runs, it will be passed TOPDIR which
|
|
is the path to the root directory of the build. This makefile
|
|
fragment should include::
|
|
|
|
$(TOPDIR)/.config : NuttX configuration
|
|
$(TOPDIR)/tools/Config.mk : Common definitions
|
|
|
|
Definitions in the ``Make.defs`` file probably depend on some of the
|
|
settings in the ``.config`` file. For example, the ``CFLAGS`` will most likely be
|
|
different if ``CONFIG_DEBUG_FEATURES=y``.
|
|
|
|
The included ``tools/Config.mk`` file contains additional definitions that may
|
|
be overridden in the architecture-specific ``Make.defs`` file as necessary::
|
|
|
|
COMPILE, ASSEMBLE, ARCHIVE, CLEAN, and MKDEP macros
|
|
|
|
* ``defconfig`` -- This is a configuration file similar to the Linux
|
|
configuration file. In contains variable/value pairs like::
|
|
|
|
CONFIG_VARIABLE=value
|
|
|
|
This configuration file will be used at build time:
|
|
|
|
(1) as a makefile fragment included in other makefiles, and
|
|
(2) to generate include/nuttx/config.h which is included by
|
|
most C files in the system.
|
|
|
|
Configuration Variables
|
|
=======================
|
|
|
|
At one time, this section provided a list of all NuttX configuration
|
|
variables. However, NuttX has since converted to use the kconfig-frontends
|
|
tools (See https://bitbucket.org/nuttx/tools/src/master/kconfig-frontends/.)
|
|
Now, the NuttX configuration is determined by a self-documenting set of
|
|
Kconfig files.
|
|
|
|
The current NuttX configuration variables are also documented in separate,
|
|
auto-generated configuration variable document. That configuration variable
|
|
document is generated using the kconfig2html tool that can be found in the
|
|
nuttx/tools directory. That tool analyzes the NuttX Kconfig files and
|
|
generates an excruciatingly boring HTML document.
|
|
|
|
The latest boring configuration variable documentation can be regenerated at
|
|
any time using that tool or, more appropriately, the wrapper script at
|
|
nuttx/tools/mkconfigvars.sh. That script will generate the file
|
|
nuttx/Documentation/NuttXConfigVariables.html.
|
|
|
|
Supported Boards
|
|
================
|
|
|
|
The list of supported boards can be found in :ref:`Supported Platforms <platforms>`.
|
|
|
|
Configuring NuttX
|
|
=================
|
|
|
|
Configuring NuttX requires only copying::
|
|
|
|
boards/<arch>/<chip>/<board>/<config-dir>/Make.def to ${TOPDIR}/Make.defs
|
|
boards/<arch>/<chip>/<board>/<config-dir>/defconfig to ${TOPDIR}/.config
|
|
|
|
- ``tools/configure.sh``
|
|
|
|
There is a script that automates these steps. The following steps will
|
|
accomplish the same configuration::
|
|
|
|
tools/configure.sh <board>:<config-dir>
|
|
|
|
There is an alternative Windows batch file that can be used in the
|
|
windows native environment like::
|
|
|
|
tools\configure.bat <board>:<config-dir>
|
|
|
|
See :doc:`tools/index` for more information about these scripts.
|
|
|
|
And if your application directory is not in the standard location (``../apps``
|
|
or ``../apps-<version>``), then you should also specify the location of the
|
|
application directory on the command line like::
|
|
|
|
cd tools
|
|
./configure.sh -a <app-dir> <board>:<config-dir>
|
|
|
|
Building Symbol Tables
|
|
======================
|
|
|
|
Symbol tables are needed at several of the binfmt interfaces in order to bind
|
|
a module to the base code. These symbol tables can be tricky to create and
|
|
will probably have to be tailored for any specific application, balancing
|
|
the number of symbols and the size of the symbol table against the symbols
|
|
required by the applications.
|
|
|
|
The top-level System.map file is one good source of symbol information
|
|
(which, or course, was just generated from the top-level nuttx file
|
|
using the GNU 'nm' tool).
|
|
|
|
There are also common-separated value (CSV) values in the source try that
|
|
provide information about symbols. In particular::
|
|
|
|
nuttx/syscall/syscall.csv - Describes the NuttX RTOS interface, and
|
|
nuttx/lib/libc.csv - Describes the NuttX C library interface.
|
|
|
|
There is a tool at nuttx/tools/mksymtab that will use these CSV files as
|
|
input to generate a generic symbol table. See ``nuttx/tools/README.txt`` for
|
|
more information about using the mksymtab tool.
|