Documentation: update organization.rst

This commit is contained in:
raiden00pl 2023-10-29 16:37:00 +01:00 committed by Xiang Xiao
parent 93f1d62f34
commit 64be5c6958
3 changed files with 109 additions and 311 deletions

View File

@ -47,6 +47,7 @@ under ``arch/`` with the following characteristics::
| |--<other-chips>/
| |-- arch.h
| |-- irq.h
| |-- syscall.h
| `-- types.h
`-- src/
|--<chip-name>/
@ -120,6 +121,18 @@ Summary of Files
This file must also define NR_IRQS, the total number of IRQs supported
by the board.
- ``include/syscall.h``: This file needs to define some
architecture specific functions (usually inline if the compiler
supports inlining) to support software interrupts or
*syscall*\ s that can be used all from user-mode applications
into kernel-mode NuttX functions. This file must always be
provided to prevent compilation errors. However, it need only
contain valid function declarations if the architecture
supports the ``CONFIG_BUILD_PROTECTED`` or
``CONFIG_BUILD_KERNEL``\ configurations.
See :doc:`/components/syscall` for details.
``src/<chip-name>/``
This sub-directory contains chip-specific source files.

View File

@ -177,6 +177,52 @@ Configuring NuttX requires only copying::
cd tools
./configure.sh -a <app-dir> <board>:<config-dir>
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``?
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.
In ``boards/Kconfig`` for the stm32f4-discovery, you will see a
configuration definition like this:
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:
Later in the ``boards/Kconfig`` file, you will see a long, long
string configuration with lots of defaults like this:
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):
Now the build system knows where to find your board configuration!
And finally, add something like this near the bottom of
``boards/myarch/mychip/myboard``:
This includes additional, board-specific configuration variable
definitions in ``boards/myarch/mychip/myboard/Kconfig``.
Building Symbol Tables
======================

View File

@ -25,7 +25,7 @@ board configuration directories. The complete configuration is
specified by several settings in the NuttX configuration file.
- *Processor architecture specific files*. These are the files
contained in the ``arch/``\ *<arch-name>*\ ``/`` directory and
contained in the ``arch/<arch-name>/`` directory and
are discussed in a paragraph
`below <#arch-subdirectory-structure>`__. As an example, all ARM
processor architectures are provided under the ``arch/arm/``
@ -47,7 +47,7 @@ specified by several settings in the NuttX configuration file.
as UARTs, USB, etc.).
These chip-specific files are contained within chip-specific
sub-directories also under the ``arch/``\ *<arch-name>*\ ``/``
sub-directories also under the ``arch/<arch-name>/``
directory and are selected via the ``CONFIG_ARCH_CHIP``
selection.
@ -64,7 +64,7 @@ specified by several settings in the NuttX configuration file.
(such as networks, USB, etc.).
These board-specific configuration files can be found in the
``boards/``\ *<arch-name>*\ ``/``\ *<chip-name>*\ ``/``\ *<board-name>*\ ``/``
``boards/<arch-name>/<chip-name>/<board-name>/``
sub-directories and are discussed in a paragraph
`below <#boards-subdirectory-structure>`__.
@ -83,154 +83,9 @@ README.md file for information on how to build it.
``nuttx/arch``
==============
Arch Subdirectory Structure
---------------------------
This sub-directory holds the NuttX supported architectures.
This directory contains several sub-directories, each containing
architecture-specific logic. The task of porting NuttX to a new
processor consists of add a new subdirectory under ``arch/``
containing logic specific to the new architecture. The complete
board port in is defined by the architecture-specific code in this
directory (plus the board-specific configurations in the
``config/`` subdirectory). Each architecture must provide a
subdirectory, *<arch-name>* under ``arch/`` with the following
characteristics:
Arch Summary of Files
---------------------
- ``include/``\ *<chip-name>*\ ``/`` This sub-directory contains
chip-specific header files.
- ``include/arch.h``: This is a hook for any architecture
specific definitions that may be needed by the system. It is
included by ``include/nuttx/arch.h``.
- ``include/types.h``: This provides
architecture/toolchain-specific definitions for standard types.
This file should ``typedef``:
and if the architecture supports 24- or 64-bit integers
NOTE that these type names have a leading underscore character.
This file will be included(indirectly) by include/stdint.h and
typedef'ed to the final name without the underscore character.
This roundabout way of doings things allows the stdint.h to be
removed from the include/ directory in the event that the user
prefers to use the definitions provided by their toolchain
header files
And finally
Must be defined to the be the size required to hold the
interrupt enable/disable state.
This file will be included by include/sys/types.h and be made
available to all files.
- ``include/irq.h``: This file needs to define some architecture
specific functions (usually inline if the compiler supports
inlining) and some structures. These include:
- ``struct xcptcontext``: This structures represents the saved
context of a thread.
- ``irqstate_t up_irq_save(void)``: Used to disable all
interrupts. In the case of multi-CPU platforms, this
function disables interrupts on CPUs.
- ``void up_irq_restore(irqstate_t flags)``: Used to restore
interrupt enables to the same state as before
``up_irq_save()`` was called.
This file must also define ``NR_IRQS``, the total number of
IRQs supported by the board.
- ``include/syscall.h``: This file needs to define some
architecture specific functions (usually inline if the compiler
supports inlining) to support software interrupts or
*syscall*\ s that can be used all from user-mode applications
into kernel-mode NuttX functions. This directory must always be
provided to prevent compilation errors. However, it need only
contain valid function declarations if the architecture
supports the ``CONFIG_BUILD_PROTECTED`` or
``CONFIG_BUILD_KERNEL``\ configurations.
- ``uintptr_t sys_call0(unsigned int nbr)``: ``nbr`` is one of
the system call numbers that can be found in
``include/sys/syscall.h``. This function will perform a
system call with no (additional) parameters.
- ``uintptr_t sys_call1(unsigned int nbr, uintptr_t parm1)``:
``nbr`` is one of the system call numbers that can be found
in ``include/sys/syscall.h``. This function will perform a
system call with one (additional) parameter.
- ``uintptr_t sys_call2(unsigned int nbr, uintptr_t parm1, uintptr_t parm2)``:
``nbr`` is one of the system call numbers that can be found
in ``include/sys/syscall.h``. This function will perform a
system call with two (additional) parameters.
- ``uintptr_t sys_call3(unsigned int nbr, uintptr_t parm1, uintptr_t parm2, uintptr_t parm3)``:
``nbr`` is one of the system call numbers that can be found
in ``include/sys/syscall.h``. This function will perform a
system call with three (additional) parameters.
- ``uintptr_t sys_call4(unsigned int nbr, uintptr_t parm1, uintptr_t parm2, uintptr_t parm3, uintptr_t parm4)``:
``nbr`` is one of the system call numbers that can be found
in ``include/sys/syscall.h``. This function will perform a
system call with four (additional) parameters.
- ``uintptr_t sys_call5(unsigned int nbr, uintptr_t parm1, uintptr_t parm2, uintptr_t parm3, uintptr_t parm4, uintptr_t parm5)``:
``nbr`` is one of the system call numbers that can be found
in ``include/sys/syscall.h``. This function will perform a
system call with five (additional) parameters.
- ``uintptr_t sys_call6(unsigned int nbr, uintptr_t parm1, uintptr_t parm2, uintptr_t parm3, uintptr_t parm4, uintptr_t parm5, uintptr_t parm6)``:
``nbr`` is one of the system call numbers that can be found
in ``include/sys/syscall.h``. This function will perform a
system call with six (additional) parameters.
This file must also define ``NR_IRQS``, the total number of
IRQs supported by the board.
- ``src/``\ *<chip-name>*\ ``/`` This sub-directory contains
chip-specific source files.
- ``src/Makefile``: This makefile will be executed to build the
targets ``src/libup.a`` and ``src/up_head.o``. The
``up_head.o`` file holds the entry point into the system
(power-on reset entry point, for example). It will be used in
the final link with ``libup.a`` and other system archives to
generate the final executable.
- *(architecture-specific source files)*. The file
``include/nuttx/arch.h`` identifies all of the APIs that must
be provided by the architecture specific logic. (It also
includes ``arch/``\ *<arch-name>*\ ``/arch.h`` as described
above).
Supported Architectures
-----------------------
**Architecture- and Chip-Specific Directories**. All processor
architecture-specific directories are maintained in
sub-directories of the ``arch/`` directory. Different chips or
SoC's may implement the same processor core. Chip-specific logic
can be found in sub-directories under the architecture directory.
Current architecture/chip directories are summarized below:
- ``arch/sim``: A user-mode port of NuttX to the x86 Linux or
Cygwin platform is available. The purpose of this port is
primarily to support OS feature development. This port does not
support interrupts or a real timer (and hence no round robin
scheduler) Otherwise, it is complete.
- ``arch/arm``: This directory holds common ARM architectures.
- ``arch/avr``: This directory holds common AVR and AVR32
architectures.
- ``arch/mips``: This directory holds common MIPS architectures.
This include PIC32MX and PIC32MZ.
- ``arch/misoc``: This directory supports the Misoc LM3
architecture.
- ``arch/or1K``: This directory supports the OpenRISC mor1kx
architecture.
- ``arch/renesas``: This directory is the home for various
Renesas architectures, currently only the M16C and vererable
SuperH-1 architectures.
- ``arch/xtensa``: This directory supports the Xtensa LX6
architecture as used by the ESP32.
- ``arch/z16f``: Zilog z16f Microcontroller.
- ``arch/z80``: This directory holds 8-bit ZiLOG architectures.
At present, this includes the Zilog z80, ez80Acclaim! and
z8Encore! Microcontrollers.
For details see :doc:`/components/arch/index`.
``nuttx/binfmt``
================
@ -260,152 +115,31 @@ Boards Subdirectory Structure
The ``boards/`` directory contains board specific configuration
files. Each board must provide a sub-directory <board-name> under
``boards/``\ *<arch-name>*\ ``/``>\ *<chip-name>*\ ``/`` with the
following characteristics:
``boards/<arch-name>/<chip-name>/``.
Boards Summary of Files
-----------------------
See :doc:`/components/boards` for details.
**Board Specific Logic**
``nuttx/cmake``
===============
- ``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-name>*\ ``/include/``
and ``arch/``\ *<arch-name>*\ ``/src/``.
- ``src/``: This directory contains board specific drivers. This
directory will be linked as
*<config>*\ ``/arch/``\ *<arch-name>*\ ``/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``.
This sub-directory holds the NuttX CMake functions.
**Board Specific Configuration Sub-Directories**
The
``boards/``\ *<arch-name>*\ ``/``\ *<chip-name>*\ ``/``\ *<board-name>*\ ``/configs``
sub-directory holds all of the files that are necessary to
configure NuttX for the particular board. A board may have various
different configurations using the 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).
NOTE: That the ``Make.defs`` file may reside in one of two
locations: There may be a unique Make.defs file for each
configuration in the configuration directory *OR* if that file is
absent, there may be a common board ``Make.defs`` file in the
``/scripts`` directory. The ``Make.defs`` file in the
configuration takes precedence if it is present.
The procedure for configuring NuttX is described
`below <#configuringnuttx>`__, This paragraph will describe the
contents of these configuration files.
- ``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:
#. As a makefile fragment included in other makefiles, and
#. to generate ``include/nuttx/config.h`` which is included by
most C files in the system.
Supported Boards
----------------
The list of supported boards can be found in :ref:`Supported Platforms <platforms>`.
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``?
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.
In ``boards/Kconfig`` for the stm32f4-discovery, you will see a
configuration definition like this:
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:
Later in the ``boards/Kconfig`` file, you will see a long, long
string configuration with lots of defaults like this:
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):
Now the build system knows where to find your board configuration!
And finally, add something like this near the bottom of
``boards/myarch/mychip/myboard``:
This includes additional, board-specific configuration variable
definitions in ``boards/myarch/mychip/myboard/Kconfig``.
For details see :doc:`/components/cmake`.
``nuttx/crypto``
================
This sub-directory holds the NuttX cryptographic sub-system.
For details see :doc:`/components/crypto`.
``nuttx/drivers``
=================
This directory holds architecture-independent device drivers.
For details see :doc:`/components/drivers/index`.
``nuttx/fs``
============
@ -418,59 +152,49 @@ described `below <#NxFileSystem>`__.
This directory contains files for graphics/video support under
NuttX.
For details see :doc:`/components/nxgraphics/index`.
``nuttx/include``
=================
This directory holds NuttX header files. Standard header files
file retained in can be included in the *normal* fashion:
``nuttx``
=========
This is a (almost) empty directory that has a holding place for
generated static libraries. The NuttX build system generates a
collection of such static libraries in this directory during the
compile phase. These libraries are then in a known place for the
final link phase where they are accessed to generated the final
binaries.
``nuttx/libs/libc``
===================
This directory holds a collection of standard libc-like functions
with custom interfaces into NuttX.
Normally the logic in this file builds to a single library
(``libc.a``). However, if NuttX is built as a separately compiled
kernel (with ``CONFIG_BUILD_PROTECTED=y`` or
``CONFIG_BUILD_KERNEL=y``), then the contents of this directory
are built as two libraries: One for use by user programs
(``libc.a``) and one for use only within the <kernel> space
(``libkc.a``).
These user/kernel space libraries (along with the sycalls of
```nuttx/syscall`` <#DirStructSyscall>`__) are needed to support
the two differing protection domains.
Directory structure:
``nuttx/libs/libxx``
====================
This directory holds a tiny, minimal standard std C++ that can be
used to build some, simple C++ applications in NuttX.
For details see :doc:`/components/libs/index`.
``nuttx/mm``
============
This is the NuttX memory manager.
For details see :doc:`/components/mm/index`.
``nuttx/net``
=============
This directory contains the implementation of the NuttX networking
layer including internal socket APIs.
For details see :doc:`/components/net/index`.
``nuttx/openamp``
=================
This directory contains OpenAMP support for NuttX.
For details see :doc:`/components/openamp`.
``nuttx/pass1``
===============
TODO
``nuttx/sched``
===============
@ -485,6 +209,8 @@ the contents of this directory are built. This directory holds a
syscall interface that can be used for communication between
user-mode applications and the kernel-mode RTOS.
For details see :doc:`/components/syscall`.
``nuttx/tools``
===============
@ -496,15 +222,28 @@ information about the individual files. Some of these tools are
discussed below as well in the discussion of `configuring and
building <#configandbuild>`__ NuttX.
``nuttx/video``
===============
This directory holds support for video sub-system.
For details see :doc:`/components/video`.
``nuttx/wireless``
==================
This directory holds support for hardware-independent wireless
support.
For details see :doc:`/components/wireless`.
``nuttx/CMakeList.txt``
=======================
The top-level ``CMakeList.txt`` file.
``nuttx/Makefile``
==================
The top-level ``Makefile`` in the ``$(TOPDIR)`` directory contains
all of the top-level control logic to build NuttX.