nuttx/Documentation/components/boards.rst

==============
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 ``tools/README.txt`` 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.