This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 64be5c695808a730ac6e8e47165dc5b4bd1dcb30
Author: raiden00pl <raide...@railab.me>
AuthorDate: Sun Oct 29 16:37:00 2023 +0100
Documentation: update organization.rst
---
Documentation/components/arch/index.rst | 13 ++
Documentation/components/boards.rst | 46 ++++
Documentation/quickstart/organization.rst | 365 +++++-------------------------
3 files changed, 111 insertions(+), 313 deletions(-)
diff --git a/Documentation/components/arch/index.rst
b/Documentation/components/arch/index.rst
index 399206a024..c2e5a49948 100644
--- a/Documentation/components/arch/index.rst
+++ b/Documentation/components/arch/index.rst
@@ -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.
diff --git a/Documentation/components/boards.rst
b/Documentation/components/boards.rst
index 229c156575..c05bbe3c09 100644
--- a/Documentation/components/boards.rst
+++ b/Documentation/components/boards.rst
@@ -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
======================
diff --git a/Documentation/quickstart/organization.rst
b/Documentation/quickstart/organization.rst
index 20bc1c0583..401dcd207b 100644
--- a/Documentation/quickstart/organization.rst
+++ b/Documentation/quickstart/organization.rst
@@ -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 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.
+This sub-directory holds the NuttX supported architectures.
+
+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 Summary of Files
------------------------
-
-**Board Specific Logic**
-
-- ``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``.
-
-**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:
+``boards/<arch-name>/<chip-name>/``.
+
+See :doc:`/components/boards` for details.
-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!
+``nuttx/cmake``
+===============
-And finally, add something like this near the bottom of
-``boards/myarch/mychip/myboard``:
+This sub-directory holds the NuttX CMake functions.
-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.
-
