From 55a4dea904a3d51e3960bd2b036ba2dc3996cd90 Mon Sep 17 00:00:00 2001 From: Gregory Nutt Date: Sun, 13 Mar 2016 12:07:42 -0600 Subject: [PATCH] Update porting guide to include SMP interfaces --- Documentation/NuttxPortingGuide.html | 794 ++++++++++++--------------- 1 file changed, 352 insertions(+), 442 deletions(-) diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html index 674938f799..4dc78a6a0a 100644 --- a/Documentation/NuttxPortingGuide.html +++ b/Documentation/NuttxPortingGuide.html @@ -30,40 +30,41 @@ 1.0 Introduction
2.0 Directory Structure 3.0 Configuring and Building 4.6 boardctl() Application Interface
- 4.7 APIs Exported by NuttX to Architecture-Specific Logic + 4.7 Symmetric Multiprocssing (SMP) Application Interface - 4.8 Shared Memory + 4.8 APIs Exported by NuttX to Architecture-Specific Logic - 4.9 On-Demand Paging
- 4.10 LED Support + 4.9 Shared Memory + 4.10 On-Demand Paging
+ 4.11 LED Support + 5.0 NuttX File System
@@ -263,6 +273,10 @@ | | | |--<other-chips>/ | | | `-- (architecture-specific source files) | | `-- <other-architecture directories>/ +| |-- audio/ +| | |-- Makefile +| | |-- Kconfig +| | `-- (common audio source files) | |-- binfmt/ | | |-- Makefile | | |-- Kconfig @@ -303,7 +317,7 @@ | | | `-- (more standard header files) | | |-- (non-standard include sub-directories) | | `-- (non-standard header files) -| |-- libc/ +| |-- libc/ | | |-- Makefile | | |-- Kconfig | | `-- (libc source files) @@ -352,8 +366,12 @@ | | |-- Makefile | | |-- Kconfig | | `-- (syscall source files) -| `-- tools/ -| `-- (miscellaneous scripts and programs) +| |-- tools/ +| | `-- (miscellaneous scripts and programs) +| `-- tools/ +| |-- Makefile +| |-- Kconfig +| `-- (wireless management source files) `- apps |-- netutils/ | |-- Makefile @@ -614,35 +632,7 @@

  • arch/arm: - This directory holds common ARM architectures. At present, this includes - the following subdirectories: - + This directory holds common ARM architectures.
  • configs/mcu123-lpc214x: @@ -717,14 +707,20 @@ system into memory in a form that can be used to execute them.

    -

    2.4 nuttx/configs

    +

    2.4 nuttx/audio

    + +

    + The audio/ subdirectory contains the NuttX audio sub-system. +

    + +

    2.5 nuttx/configs

    The configs/ subdirectory contains configuration data for each board. These board-specific configurations plus the architecture-specific configurations in the arch/ subdirectory complete define a customized port of NuttX.

    -

    2.4.1 Subdirectory Structure

    +

    2.5.1 Subdirectory Structure

    The configs directory contains board specific configuration files. Each board must provide a subdirectory <board-name> under configs/ with the following characteristics: @@ -750,8 +746,8 @@ `-- (other board-specific configuration sub-directories)/ -

    2.4.2 Summary of Files

    -

    2.4.2.1 Board Specific Logic

    +

    2.5.2 Summary of Files

    +

    2.5.2.1 Board Specific Logic

    -

    2.4.2.2 Board Specific Configuration Sub-Directories

    +

    2.5.2.2 Board Specific Configuration Sub-Directories

    The configs/<board-name>/ sub-directory holds all of the files that are necessary to configure NuttX for the particular board. @@ -845,248 +841,11 @@

    • -

    2.4.3 Supported Boards

    +

    2.5.3 Supported Boards

    - All of the specific boards supported by NuttX are identified below. - These are the specific <board-name>'s that may be used to configure NuttX - as described below. + All of the specific boards supported by NuttX are identified in the README.txt file.

    - - -

    - * A customized version of the buildroot - is available to build these toolchains under Linux or Cygwin. -

    - -

    2.4.4 Adding a New Board Configuration

    +

    2.5.4 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? @@ -1164,7 +923,13 @@ endif This includes additional, board-specific configuration variable definitions in configs/myboard/Kconfig.

    -

    2.5 nuttx/drivers

    +

    2.6 nuttx/crypto

    + +

    + This sub-directory holds the NuttX cryptographic sub-system. +

    + +

    2.7 nuttx/drivers

    This directory holds architecture-independent device drivers. @@ -1228,7 +993,7 @@ drivers/ `-- (Various common driver source files) -

    2.6 nuttx/fs

    +

    2.8 nuttx/fs

    This directory contains the NuttX file system. @@ -1261,7 +1026,7 @@ fs/ `-- (common file system source files) -

    2.7 nuttx/graphics

    +

    2.9 nuttx/graphics

    This directory contains files for graphics/video support under NuttX. @@ -1288,7 +1053,7 @@ graphics/ `-- (common file system source files) -

    2.8 nuttx/include

    +

    2.10 nuttx/include

    This directory holds NuttX header files. Standard header files file retained in can be included in the normal fashion: @@ -1351,7 +1116,15 @@ include/ `-- (More standard header files) -

    2.9 nuttx/libc

    +

    2.11 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 phaase. + These libraries are then in a known place for the final link phase where they are accessed to generated the final binaries. +

    + +

    2.12 nuttx/libc

    This directory holds a collection of standard libc-like functions with custom interfaces into NuttX. @@ -1399,28 +1172,28 @@ libc/ `-- (Implementation of some functions from unistd.h) -

    2.10 nuttx/libxx

    +

    2.13 nuttx/libxx

    This directory holds a tiny, minimal standard std C++ that can be used to build some, simple C++ applications in NuttX.

    -

    2.11 nuttx/mm

    +

    2.14 nuttx/mm

    This is the NuttX memory manager.

    -

    2.12 nuttx/net

    +

    2.15 nuttx/net

    This directory contains the implementation of the NuttX networking layer including internal socket APIs.

    -

    2.13 nuttx/sched

    +

    2.16 nuttx/sched

    The files forming core of the NuttX RTOS reside here.

    -

    2.14 nuttx/syscall

    +

    2.17 nuttx/syscall

    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. @@ -1428,7 +1201,7 @@ libc/ between user-mode applications and the kernel-mode RTOS.

    -

    2.15 nuttx/tools

    +

    2.18 nuttx/tools

    This directory holds a collection of tools and scripts to simplify configuring, building and maintaining NuttX. @@ -1466,88 +1239,19 @@ tools/ Some of these tools are discussed below as well in the discussion of configuring and building NuttX.

    -

    2.16 nuttx/Makefile

    +

    2.19 nuttx/wireless

    + +

    + This directory holds support for hardware-independent wireless support. +

    + +

    2.20 nuttx/Makefile

    The top-level Makefile in the ${TOPDIR} directory contains all of the top-level control logic to build NuttX. Use of this Makefile to build NuttX is described below.

    -

    2.17 apps/netutils

    -

    - This directory contains most of the network applications. - Some of these are original with NuttX (like tftpc and dhcpd) and others were leveraged from the uIP-1.0 apps directory. - As the uIP apps/README says, these applications "are not all heavily tested." -

    - - -

    2.18 apps/nshlib

    -

    - This directory contains for the core of the NuttShell (NSH) application. -

    - -

    2.19 apps/examples

    -

    - Example and test programs to build against. -

    -
    @@ -3907,24 +3611,230 @@ void lpwork_restorepriority(uint8_t reqprio); -1 (ERROR) is returned on failure with the errno variable to to indicate the nature of the failure. -

    4.7 APIs Exported by NuttX to Architecture-Specific Logic

    +

    4.7 Symmetric Multiprocssing (SMP) Application Interface

    +

    +According to Wikipedia: "Symmetric multiprocessing (SMP) involves a symmetric multiprocessor system hardware and software architecture where two or more identical processors connect to a single, shared main memory, have full access to all I/O devices, and are controlled by a single operating system instance that treats all processors equally, reserving none for special purposes. Most multiprocessor systems today use an SMP architecture. In the case of multi-core processors, the SMP architecture applies to the cores, treating them as separate processors. +

    +

    +"SMP systems are tightly coupled multiprocessor systems with a pool of homogeneous processors running independently, each processor executing different programs and working on different data and with capability of sharing common resources (memory, I/O device, interrupt system and so on) and connected using a system bus or a crossbar." +

    +

    +For a technical description of the NuttX implementation of SMP, see the NuttX SMP Wiki Page. +

    + + None + + +

    4.7.1 up_testset()

    +

    Function Prototype:

    +

      +#include <nuttx/spinlock.h>
+#ifdef CONFIG_SPINLOCK
+spinlock_t up_testset(volatile FAR spinlock_t *lock);
+#endif
+
    + +

    Description:

    +
      +

      + Perform and atomic test and set operation on the provided spinlock. +

      +
    +

    Input Parameters:

    +
      +
    • + lock: The address of spinlock object. +
      • +
    +

    Returned Value:

    +
      +

      + The spinlock is always locked upon return. + The value of previous value of the spinlock variable is returned, either SP_LOCKED if the spinlock was previously locked (meaning that the test-and-set operation failed to obtain the lock) or SP_UNLOCKED if the spinlock was previously unlocked (meaning that we successfully obtained the lock) +

      +
    + +

    4.7.2 up_cpu_index()

    +

    Function Prototype:

    +

      +#include <nuttx/arch.h>
+#ifdef CONFIG_SMP
+int up_cpu_index(void);
+#else
+#  define up_cpu_index() (0)
+#endif
+
    + +

    Description:

    +
      +

      + Return an index in the range of 0 through (CONFIG_SMP_NCPUS-1) that corresponds to the currently executing CPU. +

      +
    +

    Input Parameters:

    +
      + None +
    +

    Returned Value:

    +
      +

      + An integer index in the range of 0 through (CONFIG_SMP_NCPUS-1) that corresponds to the currently executing CPU. +

      +
    + +

    4.7.3 up_cpu_start()

    +

    Function Prototype:

    +

      +#include <nuttx/arch.h>
+#ifdef CONFIG_SMP
+int up_cpu_start(int cpu);
+#endif
+
    + +

    Description:

    +
      +

      + In an SMP configution, only one CPU is initially active (CPU 0). + System initialization occurs on that single thread. + At the completion of the initialization of the OS, just before beginning normal multitasking, the additional CPUs would be started by calling this function. +

      +

      + Each CPU is provided the entry point to is IDLE task when started. + A TCB for each CPU's IDLE task has been initialized and placed in the CPU's g_assignedtasks[cpu] list. + A stack has also been allocated and initialized. +

      +

      + The OS initialization logic calls this function repeatedly until each CPU has been started, 1 through (CONFIG_SMP_NCPUS-1). +

      +
    +

    Input Parameters:

    +
      +
    • + cpu: The index of the CPU being started. + This will be a numeric value in the range of from one to (CONFIG_SMP_NCPUS-1)). + (CPU 0 is already active). +
      • +
    +

    Returned Value:

    +
      +

      + Zero (OK) is returned on success; a negated errno value on failure. +

      +
    + +

    4.7.4 up_cpu_initialize()

    +

    Function Prototype:

    +

      +#include <nuttx/arch.h>
+#ifdef CONFIG_SMP
+int up_cpu_initialize(void);
+#endif
+
    + +

    Description:

    +
      +

      + After the CPU has been started (via up_cpu_start()) the system will call back into the architecture-specific code with this function on the thread of execution of the newly started CPU. + This gives the architecture-specific a chance to perform ny initial, CPU-specific initialize on that thread. +

      +
    +

    Input Parameters:

    +
      + None +
    +

    Returned Value:

    +
      +

      + Zero (OK) is returned on success; a negated errno value on failure. +

      +
    + +

    4.7.5 up_cpu_pause()

    +

    Function Prototype:

    +

      +#include <nuttx/arch.h>
+#ifdef CONFIG_SMP
+int up_cpu_pause(int cpu);
+#endif
+
    + +

    Description:

    +
      +

      + Save the state of the current task at the head of the g_assignedtasks[cpu] task list and then pause task execution on the CPU. +

      +

      + This function is called by the OS when the logic executing on one CPU needs to modify the state of the g_assignedtasks[cpu] list for another CPU. +

      +
    +

    Input Parameters:

    +
      +
    • + cpu: The index of the CPU to be paused. + This will not be the index of the currently executing CPU. +
      • +
    +

    Returned Value:

    +
      +

      + Zero (OK) is returned on success; a negated errno value on failure. +

      +
    + +

    4.7.6 up_cpu_resume()

    +

    Function Prototype:

    +

      +#include <nuttx/arch.h>
+#ifdef CONFIG_SMP
+int up_cpu_resume(int cpu);
+#endif
+
    + +

    Description:

    +
      +

      + Restart the cpu after it was paused via up_cpu_pause(), restoring the state of the task at the head of the g_assignedtasks[cpu] list, and resume normal tasking. +

      +

      + This function is called after up_cpu_pause() in order resume operation of the CPU after modifying its g_assignedtasks[cpu] list. +

      +
    +

    Input Parameters:

    +
      +
    • + cpu: The index of the CPU being resumed. + This will not be the index of the currently executing CPU. +
      • +
    +

    Returned Value:

    +
      +

      + Zero (OK) is returned on success; a negated errno value on failure. +

      +
    + +

    4.8 APIs Exported by NuttX to Architecture-Specific Logic

    These are standard interfaces that are exported by the OS for use by the architecture specific logic.

    -

    4.7.1 os_start()

    +

    4.8.1 os_start()

    To be provided

    -

    4.7.2 OS List Management APIs

    +

    4.8.2 OS List Management APIs

    To be provided

    -

    4.7.3 sched_process_timer()

    -

    Function Prototype: void sched_process_timer(void);

    +

    4.8.3 sched_process_timer()

    +

    Function Prototype:

    +
      +#include <nuttx/arch.h>
+void sched_process_timer(void);
+

    Description. This function handles system timer events. @@ -3934,7 +3844,30 @@ void lpwork_restorepriority(uint8_t reqprio); MSEC_PER_TICK.

    -

    4.7.4 sched_timer_expiration()

    +

    4.8.4 sched_timer_expiration()

    +

    Function Prototype:

    +

      +#include <nuttx/arch.h>
+void sched_timer_expiration(void);
+
    +

    Description:

    + Description: if CONFIG_SCHED_TICKLESS is defined, then this function is provided by the RTOS base code and called from platform-specific code when the interval timer used to implemented the tick-less OS expires. +
      +
    +

    Input Parameters:

    +
      + None +
    +

    Returned Value:

    +
      + None +
    +

    Assumptions:

    +
      + Base code implementation assumes that this function is called from interrupt handling logic with interrupts disabled. +
    + +

    4.8.5 sched_alaram_expiration()

    Function Prototype:

       #include <nuttx/arch.h>
@@ -3957,30 +3890,7 @@ void sched_timer_expiration(void);
   Base code implementation assumes that this function is called from interrupt handling logic with interrupts disabled.
    -

    4.7.5 sched_alaram_expiration()

    -

    Function Prototype:

    -

      -#include <nuttx/arch.h>
-void sched_timer_expiration(void);
-
    -

    Description:

    - Description: if CONFIG_SCHED_TICKLESS is defined, then this function is provided by the RTOS base code and called from platform-specific code when the interval timer used to implemented the tick-less OS expires. -
      -
    -

    Input Parameters:

    -
      - None -
    -

    Returned Value:

    -
      - None -
    -

    Assumptions:

    -
      - Base code implementation assumes that this function is called from interrupt handling logic with interrupts disabled. -
    - -

    4.7.6 irq_dispatch()

    +

    4.8.6 irq_dispatch()

    Function Prototype: void irq_dispatch(int irq, FAR void *context);

    Description. @@ -3989,7 +3899,7 @@ void sched_timer_expiration(void); the appropriate, registered handling logic.

    -

    4.8 Shared Memory

    +

    4.9 Shared Memory

    Shared memory interfaces are only available with the NuttX kernel build (CONFIG_BUILD_KERNEL=y). These interfaces support user memory regions that can be shared between multiple user processes. @@ -3998,7 +3908,7 @@ void sched_timer_expiration(void); Those interfaces are described below:

    -

    4.8.1 up_shmat()

    +

    4.9.1 up_shmat()

    Function Prototype:

       #include <nuttx/arch.h>
@@ -4027,7 +3937,7 @@ int up_shmat(FAR uintptr_t *pages, unsigned int npages, uintptr_t vaddr);
   Zero (OK) is returned on success; a negated errno value is returned on failure.
    -

    4.8.2 up_shmdt()

    +

    4.9.2 up_shmdt()

    Function Prototype:

       #include <nuttx/arch.h>
@@ -4053,7 +3963,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages);
   Zero (OK) is returned on success; a negated errno value is returned on failure.
    -

    4.9 On-Demand Paging

    +

    4.10 On-Demand Paging

    The NuttX On-Demand Paging feature permits embedded MCUs with some limited RAM space to execute large programs from some non-random access media. If the platform meets certain requirements, then NuttX can provide on-demand paging: @@ -4062,7 +3972,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages); Please see the NuttX Demand Paging design document for further information.

    -

    4.10 LED Support

    +

    4.11 LED Support

    A board architecture may or may not have LEDs. @@ -4072,7 +3982,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages); However, the support provided by each architecture is sufficiently similar that it can be documented here.

    -

    4.10.1 Header Files

    +

    4.11.1 Header Files

    LED-related definitions are provided in two header files: @@ -4096,7 +4006,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages);

    -

    4.10.2 LED Definitions

    +

    4.11.2 LED Definitions

    The implementation of LED support is very specific to a board architecture. @@ -4160,7 +4070,7 @@ int up_shmdt(uintptr_t vaddr, unsigned int npages); -

    4.10.3 Common LED interfaces

    +

    4.11.3 Common LED interfaces

    The include/nuttx/board.h has declarations like: