Documentation: migrate the rest boards

- migrated /README are removed from /boards

- there are a lot of READMEs that should be further converted to rst.
  At the moment they are moved to Documentation/platforms and included in rst files

Documentation/components/boards.rst

@@ -0,0 +1,201 @@
+==============
+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.

Documentation/components/index.rst

@@ -25,3 +25,4 @@ case, you can head to the :doc:`reference <../reference/index>`.
    syscall.rst
    tools/index.rst
    arch/index.rst
+   boards.rst

Documentation/platforms/arm/a1x/boards/pcduino-a10/index.rst

@@ -0,0 +1,6 @@
+===========
+pcduino-a10
+===========
+
+.. include:: README.txt
+   :literal:

Documentation/platforms/arm/a1x/index.rst

@@ -21,3 +21,12 @@ have are supported by NuttX:
    ready for "prime time", the pcDuino port is functional and could the
    basis for a more extensive development. There is, at present, no work
    in progress to extend this port, however.
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/arm/am335x/boards/beaglebone-black/index.rst

@@ -0,0 +1,7 @@
+================
+beaglebone-black
+================
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/am335x/index.rst

@@ -22,3 +22,12 @@ AM335x are supported by NuttX:
    Refer to the Beaglebone Black board
    `README <https://github.com/apache/nuttx/blob/master/boards/arm/am335x/beaglebone-black/README.txt>`__
    file for further, up-to-date information.
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/arm/at32/boards/at32f437-mini/index.rst

@@ -0,0 +1,7 @@
+=============
+at32f437-mini
+=============
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/at32/index.rst

@@ -1,3 +1,12 @@
 ===========
 Artery AT32
 ===========
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/arm/c5471/boards/c5471evm/index.rst

@@ -0,0 +1,7 @@
+========
+c5471evm
+========
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/c5471/index.rst

@@ -7,3 +7,12 @@ TI TMS320-C5471
 NuttX operates on the ARM7 of this dual core processor. This port uses
 the `Spectrum Digital <http://www.spectrumdigital.com/>`__ evaluation
 board with a GNU arm-nuttx-elf toolchain\* under Linux or Cygwin.
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/arm/cxd56xx/boards/spresense/index.rst

@@ -0,0 +1,7 @@
+==============
+Sony Spresense
+==============
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/cxd56xx/index.rst

@@ -46,3 +46,12 @@ camera support, added audio and board audio control implementation,
 added an audio_tone_generator, added optional initialization of GNSS and
 GEOFENCE at boot if the drivers are enabled, added an lcd examples
 configuration.
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/arm/dm320/boards/ntosd-dm320/index.rst

@@ -0,0 +1,7 @@
+===========
+ntosd-dm320
+===========
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/dm320/index.rst

@@ -8,3 +8,12 @@ NuttX operates on the ARM9 of
 this dual core processor. This port uses the Neuros OSD
 with a GNU arm-nuttx-elf toolchain\* under Linux or Cygwin. The port was
 performed using the OSD v1.0, development board.
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/arm/efm32/boards/efm32-g8xx-stk/index.rst

@@ -0,0 +1,7 @@
+==============
+efm32-g8xx-stk
+==============
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/efm32/boards/efm32gg-stk3700/index.rst

@@ -0,0 +1,7 @@
+===============
+efm32gg-stk3700
+===============
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/efm32/boards/olimex-efm32g880f128-stk/index.rst

@@ -0,0 +1,7 @@
+========================
+olimex-efm32g880f128-stk
+========================
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/efm32/index.rst

@@ -91,3 +91,12 @@ Board support is available for the following:
    -  Development of USB support is in started, but never completed.
    -  Reset Management Unit (RMU) was added Pierre-noel Bouteville in
       NuttX-7.7.
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/arm/eoss3/boards/quickfeather/index.rst

@@ -0,0 +1,7 @@
+============
+quickfeather
+============
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/eoss3/index.rst

@@ -0,0 +1,12 @@
+=====
+EOSS3
+=====
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/arm/fvp-v8r-aarch32/boards/fvp-armv8r-aarch32/index.rst

@@ -0,0 +1,7 @@
+==================
+fvp-armv8r-aarch32
+==================
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/fvp-v8r-aarch32/index.rst

@@ -1,2 +1,12 @@
+=====================
 FVP ARMv8-R Virt Chip
 =====================
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/arm/gd32f4/boards/gd32f450zk-eval/index.rst

@@ -0,0 +1,4 @@
+===============
+gd32f450zk-eval
+===============
+

Documentation/platforms/arm/gd32f4/boards/gd32f470ik-eval/index.rst

@@ -0,0 +1,4 @@
+===============
+gd32f470ik-eval
+===============
+

Documentation/platforms/arm/gd32f4/boards/gd32f470zk-eval/index.rst

@@ -0,0 +1,4 @@
+===============
+gd32f470zk-eval
+===============
+

Documentation/platforms/arm/gd32f4/index.rst

@@ -0,0 +1,12 @@
+======
+GD32F4
+======
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/arm/goldfish/index.rst

@@ -0,0 +1,6 @@
+========
+GOLDFISH
+========
+
+Supported Boards
+================

Documentation/platforms/arm/imx6/boards/sabre-6quad/index.rst

@@ -0,0 +1,6 @@
+===========
+sabre-6quad
+===========
+
+This directory holds a port of NuttX to the NXP/Freescale Sabre board
+featuring the iMX 6Quad CPU.

Documentation/platforms/arm/imx6/index.rst

@@ -20,3 +20,12 @@ The basic port has been completed for the following i.MX6 board:
    with SMP support on this platform as described in the
    `README <https://github.com/apache/nuttx/blob/master/boards/arm/imx6/sabre-6quad/README.txt>`__
    file for the board.
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/arm/imxrt/index.rst

@@ -1,6 +1,6 @@
-=======
-i.MX RT
-=======
+===========
+NXP i.MX RT
+===========
 
 The i.MX RT series of chips from NXP Semiconductors is based around an ARM Cortex-M7 core running
 at 500 MHz, 600 MHz or 1 GHz based on particular MCUs

Documentation/platforms/arm/kinetis/boards/freedom-k28f/index.rst

@@ -0,0 +1,7 @@
+============
+freedom-k28f
+============
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/kinetis/boards/freedom-k64f/index.rst

@@ -0,0 +1,7 @@
+============
+freedom-k64f
+============
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/kinetis/boards/freedom-k66f/index.rst

@@ -0,0 +1,7 @@
+============
+freedom-k66f
+============
+
+.. include:: README.txt
+   :literal:
+

Documentation/platforms/arm/kinetis/boards/kwikstik-k40/index.rst

@@ -0,0 +1,7 @@
+============
+kwikstik-k40
+============
+
+.. include:: README.txt
+   :literal:
+