From 6d89ae8fc7668d49b90a130481eab4432d4e8120 Mon Sep 17 00:00:00 2001 From: Matias N Date: Fri, 14 Aug 2020 16:50:02 -0300 Subject: [PATCH] move last content from old docs to new docs; remove old docs --- Documentation/.gitignore | 3 - Documentation/NXGraphicsSubsystem.html | 4819 -------- Documentation/NfsHowto.html | 385 - Documentation/NuttShell.html | 6008 ---------- Documentation/NuttX.html | 7576 ------------- Documentation/NuttXBinfmt.html | 585 - Documentation/NuttXDemandPaging.html | 672 -- Documentation/NuttXNxFlat.html | 765 -- Documentation/NuttxPortingGuide.html | 7273 ------------ Documentation/NuttxUserGuide.html | 10600 ------------------ Documentation/NxWidgets.html | 76 - Documentation/UsbTrace.html | 453 - Documentation/favicon.ico | Bin 3126 -> 0 bytes Documentation/style.css | 84 - {Documentation => doc/_static}/NuttX.png | Bin {Documentation => doc/_static}/NuttX320.png | Bin doc/_static/favicon.ico | Bin 4286 -> 3126 bytes 17 files changed, 39299 deletions(-) delete mode 100644 Documentation/.gitignore delete mode 100644 Documentation/NXGraphicsSubsystem.html delete mode 100644 Documentation/NfsHowto.html delete mode 100644 Documentation/NuttShell.html delete mode 100644 Documentation/NuttX.html delete mode 100644 Documentation/NuttXBinfmt.html delete mode 100644 Documentation/NuttXDemandPaging.html delete mode 100644 Documentation/NuttXNxFlat.html delete mode 100644 Documentation/NuttxPortingGuide.html delete mode 100644 Documentation/NuttxUserGuide.html delete mode 100644 Documentation/NxWidgets.html delete mode 100644 Documentation/UsbTrace.html delete mode 100644 Documentation/favicon.ico delete mode 100644 Documentation/style.css rename {Documentation => doc/_static}/NuttX.png (100%) rename {Documentation => doc/_static}/NuttX320.png (100%) diff --git a/Documentation/.gitignore b/Documentation/.gitignore deleted file mode 100644 index a2966262c5..0000000000 --- a/Documentation/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -/TODO.txt -/ChangeLog.txt -/NuttXConfigVariables.* diff --git a/Documentation/NXGraphicsSubsystem.html b/Documentation/NXGraphicsSubsystem.html deleted file mode 100644 index b43f13820d..0000000000 --- a/Documentation/NXGraphicsSubsystem.html +++ /dev/null @@ -1,4819 +0,0 @@ - - -NX Graphics Subsystem - - - - - -
- - - - -
-

- NX Graphics Subsystem -

-

Last Updated: August 8, 2019

-
-
- - - - - -
-

Table of Contents

-
- - - - - - -
-

- 1.0 Introduction -

- -

- 2.0 NX User APIs -

- 		-

- 2.4 NX Tool Kit (NXTK) -

-

-

-

-

- 2.5 NX Fonts Support (NXFONTS) -

-

-

-

-

- 2.6 NX Cursor Support (NXCURSOR) -

-

-

-

-

- 2.7 Sample Code -

- -

- Appendix A graphics/ Directory Structure
- Appendix B NX Configuration Options -

-

-

-

-

- Appendix C Installing New Fonts -

-

- Appendix D NX Test Coverage -

- -
- - - - - -
-

1.0 Introduction

-
- -

1.1 Overview

-

- This document describes the tiny graphics support included in NuttX. - It includes an overview description of that graphics support, detailed - descriptions of the NuttX graphics APIs, and discussion of code organization, - and OS configuration options. -

- -
- - - - - -
Figure 1. - This scren shot shows the final frame for the NuttX example at apps/examples/nx - running on the simulated, Linux x86 platform with simulated framebuffer output to - an X window. - This picture shows to framed windows with (blank) toolbars. - Each window has displayed text as received from the NX keyboard interface - The second window has just been raised to the top of the display. - -
- - -

1.2 Objectives

- -

- The objective of this development was to provide a tiny windowing system in the - spirit of X, but greatly scaled down and appropriate for most resource-limited - embedded environments. - The current NX implementation supports the general following, high-level features: -

- - -

1.3 Organization

- -

- NX is organized into 6 (and perhaps someday 7 or 8) logical modules. - These logical modules also correspond to the directory organization. - That NuttX directory organization is discussed in - Appendix B of this document. - The logic modules are discussed in the following sub-paragraphs. -

- -

-

-

- -

1.3.1 NX Graphics Library (NXGL)

- -

- NXGLIB is a standalone library that contains low-level graphics utilities and - direct framebuffer or LCD rendering logic. NX is built on top NXGLIB. -

- -

1.3.2 NX (NXSU and NXMU)

- -

- NX is the tiny NuttX windowing system for raw windows (i.e., simple regions of - graphics memory). - NX includes a small-footprint, multi-user implementation (NXMU as described below). - NX can be used without NxWidgets and without NXTOOLKIT for raw window displays. -

- -

- 1NXMU and NXSU are interchangeable other than (1) certain start-up - and initialization APIs (as described below), and (2) timing. With NXSU, NX APIs - execute immediately; with NXMU, NX APIs defer and serialize the operations and, hence, - introduce different timing and potential race conditions that you would not experience - with NXSU. -

- -

NXNULL? - At one time, I also envisioned a NULL front-end that did not support windowing - at all but, rather, simply provided the entire framebuffer or LCD memory as one dumb window. - This has the advantage that the same NX APIs can be used on the one dumb window as - for the other NX windows. - This would be in the NuttX spirit of scalability. -

-

- However, the same end result can be obtained by using the - nx_requestbkgd() API. - It still may be possible to reduce the footprint in this usage case by developing - and even thinner NXNULL front-end. - That is a possible future development. -

- -

1.3.3 NX Tool Kit (NXTK)

- -

- NXTK is a s set of C graphics tools that provide higher-level window drawing - operations. - This is the module where the framed windows and toolbar logic is implemented. - NXTK is built on top of NX and does not depend on NxWidgets. -

- -

1.3.4 NX Fonts Support (NXFONTS)

- -

- A set of C graphics tools for present (bitmap) font images. - The font implementation is at a very low level or graphics operation, - comparable to the logic in NXGLIB. - NXFONTS does not depend on any NX module other than some utilities and types from NXGLIB. -

- -

1.3.5 NX Widgets (NxWidgets)

- -

- NxWidgets is a higher level, C++, object-oriented library for object-oriented access to graphical "widgets." - NxWidgets is provided as a separate library in the apps/ repository - NxWidgets is built on top of the core NuttX graphics subsystem, but is part of the application space rather than part of the core OS graphics subsystems. -

- -

1.3.6 NX Terminal Driver (NxTerm)

- -

- NxTerm is a write-only character device (not shown) that is built on top of an NX window. - This character device can be used to provide stdout and stderr and, hence, can provide the output side of NuttX console. -). -

- - - - - -
-

2.0 NX User APIs

-
- -

2.1 NX Header Files

- - - -

2.2 NX Graphics Library (NXGL)

- -

- NXGL provides many APIs, some available for use internally by NX and - others for use by applications as well. - Only those APIs intended for application usage are documented here - See include/nuttx/nx/nxglib.h for the full set of APIs; - those APIs might be of interest if you are rendering directly into - framebuffer or LCD memory. -

- -

2.2.1 NXGL Types

- -

- nxgl_mxpixel_t. - Holds one device pixel. - NXGLIB will select the smallest size for the nxgl_mxpixel_t - that just contains the pixel: byte if 16, 24, and 32 resolution - support is disabled, uint16_t if 24, and 32 resolution - support is disabled, or uint32_t. -

- -

- nxgl_coord_t. - A given coordinate is limited to the screen height an width. If either - of those values exceed 32,767 pixels, then the following will have to need - to change: -

- - -

- struct nxgl_point_s. Describes a point on the display: -

- - -

- struct nxgl_size_s. Describes the size of a rectangular region. -

- - -

- struct nxgl_rect_s. Describes a positioned rectangle on the display. -

- - -

- struct nxgl_run_s. - Describes a run, i.e., a horizontal line. Note that the start/end positions - have fractional precision. This is necessary for good joining of trapezoids - when a more complex shape is decomposed into trapezoids -

- - -

- struct nxgl_trapezoid_s. - Describes a horizontal trapezoid on the display in terms the run at the - top of the trapezoid and the run at the bottom -

- - -

2.2.1 nxgl_rgb2yuv()

-

Function Prototype:

- -

- Description: - Convert 8-bit RGB triplet to 8-bit YUV triplet. -

- -

2.2.2 nxgl_yuv2rgb()

-

Function Prototype:

- -

- Description: - Convert 8-bit YUV triplet to 8-bit RGB triplet. -

- -

2.2.3 nxgl_rectcopy()

-

Function Prototype:

- -

- Description: - This is essentially memcpy()for rectangles. We don't do structure - assignments because some compilers are not good at that. -

- -

2.2.4 nxgl_rectoffset()

-

Function Prototype:

- -

- Description: - Offset the rectangle position by the specified dx, dy values. -

- -

2.2.5 nxgl_vectoradd()

-

Function Prototype:

- -

- Description: - Add two 2x1 vectors and save the result to a third. -

- -

2.2.6 nxgl_vectorsubtract()

-

Function Prototype:

- -

- Description: - Add subtract vector v2 from vector v1 and return the result in vector dest. -

- -

2.2.7 nxgl_rectintersect()

-

Function Prototype:

- -

- Description: - Return the rectangle representing the intersection of the two rectangles. -

- -

2.2.8 nxgl_rectunion()

-

Function Prototype:

- -

- Description: - Given two rectangles, src1 and src2, return the larger rectangle that - contains both, dest. -

- -

2.2.9 nxgl_nonintersecting()

-

Function Prototype:

- -

- Description: - Return the regions of rectangle rect1 that do not intersect with - rect2. This will four rectangles, some of which may be - degenerate (and can be picked off with nxgl_nullrect()). -

- -

2.2.10 nxgl_rectoverlap()

-

Function Prototype:

- -

- Description: - Return true if the two rectangles overlap. -

- -

2.2.11 nxgl_rectinside()

-

Function Prototype:

- -

- Description: - Return true if the point pt lies within rect. -

- -

2.2.12 nxgl_rectsize()

-

Function Prototype:

- -

- Description: - Return the size of the specified rectangle. -

- -

2.2.13 nxgl_nullrect()

-

Function Prototype:

- -

- Description: - Return true if the area of the retangle is <= 0. -

- -

2.2.14 nxgl_runoffset()

-

Function Prototype:

- -

- Description: - Offset the run position by the specified dx, dy values. -

- -

2.2.15 nxgl_runcopy()

-

Function Prototype:

- -

- Description: - This is essentially memcpy()for runs. We don't do structure assignments - because some compilers are not good at that. -

- -

2.2.16 nxgl_trapoffset()

-

Function Prototype:

- -

- Description: - Offset the trapezoid position by the specified dx, dy values. -

- -

2.2.17 nxgl_trapcopy()

-

Function Prototype:

- -

- Description: - This is essentially memcpy()for trapezoids. We don't do structure - assignments because some compilers are not good at that. -

- -

2.2.18 nxgl_colorcopy

-

Function Prototype:

- -

- Description: - This is essentially memcpy()for colors. This does very little for us - other than hide all of the conditional compilation for planar colors - in one place. -

- -

2.2.19 nxgl_splitline

- -

Function Prototype:

- -

- Description: - In the general case, a line with width can be represented as a parallelogram with a triangle at the top and bottom. - Triangles and parallelograms are both degenerate versions of a trapezoid. - This function breaks a wide line into triangles and trapezoids. - This function also detects other degenerate cases: -

-
    -
  1. - If y1 == y2 then the line is horizontal and is better represented as a rectangle. -
    2. -
  2. - If x1 == x2 then the line is vertical and also better represented as a rectangle. -
    3. -
  3. - If the width of the line is 1, then there are no triangles at the top and bottom - (this may also be the case if the width is narrow and the line is near vertical). -
    4. -
  4. - If the line is oriented is certain angles, it may consist only of the upper and lower triangles with no trapezoid in between. - In this case, 3 trapezoids will be returned, but traps[1] will be degenerate. -
    5. -
-

- Input parameters: -

-

-

- Returned value: -

- - -

2.2.20 nxgl_circlepts

- -

- Description: - Given a description of a circle, return a set of 16 points on the circumference of the circle. - These points may then be used by nx_drawcircle() or related APIs to draw a circle outline. -

-

- Input parameters: -

-

-

- Returned value: None -

- -

2.2.21 nxgl_circletraps

- -

- Description: - Given a description of a a circle, return 8 trapezoids that can be used to fill the circle by nx_fillcircle() and other interfaces. -

-

- Input parameters: -

-

-

- Returned value: None -

- -

2.3 NX

- -

2.3.1 Pre-Processor Definitions

- -

- The default server message queue name used by the - nx_run() macro: -

- - -

- Mouse button bits: -

- - -

2.3.2 NX Types

- -

- The interface to the NX server is managed using a opaque handle: -

- - -

- The interface to a specific window is managed using an opaque handle: -

- - -

- These define callbacks that must be provided to nx_openwindow(). - These callbacks will be invoked as part of the processing performed by nx_eventhandler(). -

- - -

2.3.3 Starting the NX Server

-

- The NX Server is a kernel daemon that receives and serializes graphic commands. - Before you can use the NX graphics system, you must first start this daemon. - There are two ways that this can be done: -

-
    -
  1. -

    - The NX server may be started in your board startup logic by simply calling the function nxmu_start(). - The board startup logic usually resides the the boards/arch/chip/board/src directory. - The board startup logic can run automatically during the early system if CONFIG_BOARD_LATE_INITIALIZE is defined in the configuration. - Or, the board startup logic can execute under control of the application by calling the boardctl(BOARDIOC_INIT, arg) OS interface. -

    -

    - The board initialization logic will run in either case and the simple call to nxmu_start() will start the NX server. -

    -
    2. -
  2. - The NX server may also be started later by the application via the boardctl(BOARDIOC_NX_START, arg) -
    3. -
- -

2.3.3.1 nxmu_start()

-

Function Prototype:

- -

- Description: - nxmu_start() provides a wrapper function to simplify and standardize the starting of the NX server. -

-

- Input Parameters: -

-

-

- Returned Value: - Zero (OK) is returned on success. - This indicates that the NX server has been successfully started, is running, and waiting to accept connections from NX clients. -

-

- A negated errno value is returned on failure. - The errno value indicates the nature of the failure. -

- -

2.3.3.1 boardctl()

-

Function Prototype:

- -

- Description: - boardctl() is a generic NuttX interface that among many of it functions, may also be used to start the NX server. -

- In a small embedded system, there will typically be a much greater interaction between application and low-level board features. - The canonically correct to implement such interactions is by implementing a character driver and performing the interactions via low level ioctl() calls. - This, however, may not be practical in many cases and will lead to "correct" but awkward implementations. -

-

- boardctl() is non-standard OS interface to alleviate the problem. - It basically circumvents the normal device driver ioctl interlace and allows the application to perform direction IOCTL-like calls to the board-specific logic. - In it is especially useful for setting up board operational and test configurations. -

-

- When called with the cmd of BOARDIOC_NX_START, then the boardctl() will call nxmu_start indirectly on behalf of the application. - In this case the arg parameter is ignored. -

-

- Input Parameters: -

-

-

- Returned Value: - On success zero (OKERROR) is returned on failure with the errno variable set to indicate the nature of the failure. -

- -

2.3.4 NX Server Callbacks

- -

2.3.4.1 redraw()

-

Callback Function Prototype:

- -

- Description: - NX requests that the client re-draw the portion of the window within - with rectangle. -

-

- Input Parameters: -

-

-

- Returned Value: None -

- -

2.3.4.2 position()

-

Callback Function Prototype:

- -

- Description: - The size or position of the window has changed (or the window was - just created with zero size. -

-

- Input Parameters: -

-

-

- Returned Value: None -

- -

2.3.4.3 mousein()

-

Callback Function Prototype:

- -

- Description: - New mouse data is available for the window -

-

- Input Parameters: -

-

-

- Returned Value: None -

- -

2.3.4.4 kbdin()

-

Callback Function Prototype:

- -

- Description: - New keyboard/keypad data is available for the window. -

-

- Input Parameters: -

-

-

- Returned Value: None -

- - 2.3.4.5 event() -

2.3.4.5 event()

-

Callback Function Prototype:

- -

- Description: - This callback is used to communicate server events to the window listener. -

-
-
NXEVENT_BLOCKED - Window messages are blocked. -
This callback is the response from nx_block(), nxtk_block(). Those blocking interfaces are used to assure that no further messages are directed to the window. Receipt of the blocked callback signifies that (1) there are no further pending callbacks and (2) that the window is now defunct and will receive no further callbacks. - - This callback supports coordinated destruction of a window. In the multi-user mode, the client window logic must stay intact until all of the queued callbacks are processed. Then the window may be safely closed. Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed. -
NXEVENT_SYNCHED - Synchronization handshake -
This completes the handshake started by nx_synch(), or nxtk_synch(). Those interfaces send a synchronization messages to the NX server which responds with this event. The sleeping client is awakened and continues graphics processing, completing the handshake. - - Due to the highly asynchronous nature of client-server communications, synchronization is sometimes necessary to assure that the client and server are working together properly. -
-

- Input Parameters: -

-

-

- Returned Value: None -

- - -

2.3.5 nx_runinstance() (and nx_run() macro)

-

Function Prototype:

- -

- Description: - This is the server entry point. It does not return; the calling thread - is dedicated to supporting NX server. -

-

- NOTE that multiple instances of the NX server may run at the same time, - with different callback and message queue names. - nx_run() is simply a macro that can be used when only one - server instance is required. - In that case, a default server name is used. -

-

- Input Parameters: -

-

-

- Returned Value: - This function usually does not return. If it does return, it will - return ERROR and errno will be set appropriately. -

- -

2.3.6 nx_connectinstance() (and nx_connect() macro)

-

Function Prototype:

- -

- Description: - Open a connection from a client to the NX server. One one client - connection is normally needed per thread as each connection can host - multiple windows. -

-

- NOTES: -

- -

- Input Parameters: -

-

-

- Returned Value: -

- - -

2.3.7 nx_disconnect()

-

Function Prototype:

- -

- Description: - Disconnect a client from the NX server and/or free resources reserved - by nx_connect()/nx_connectinstance(). -

-

- Input Parameters: -

-

-

- Returned Value: None. -

- -

2.3.8 nx_eventhandler()

-

Function Prototype:

- -

- Description: - The client code must call this function periodically to process - incoming messages from the server. If CONFIG_NX_BLOCKING is defined, - then this function not return until a server message is received. -

-

- When CONFIG_NX_BLOCKING is not defined, the client must exercise - caution in the looping to assure that it does not eat up all of - the CPU bandwidth calling nx_eventhandler repeatedly. - nx_eventnotify() - may be called to get a signal event whenever a new incoming server - event is available. -

-

- Input Parameters: -

-

-

- Returned Value: -

- - -

2.3.9 nx_eventnotify()

-

Function Prototype:

- -

- Description: - Rather than calling nx_eventhandler() periodically, - the client may register to receive a signal when a server event is available. - The client can then call nv_eventhandler() only when - incoming events are available. -

-

- The underlying implementation used mq_notifiy() and, as a result, - the client must observe the rules for using mq_notifiy(): -

-

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.10 nx_block()

-

Function Prototype:

- -

- Description: - The response to this function call is two things: (1) any queued callback messages to the window are 'blocked' and then (2) also subsequent window messaging is blocked. -

-

- The event callback with the NXEVENT_BLOCKED event is the response from nx_block(). This blocking interface is used to assure that no further messages are are directed to the window. Receipt of the NXEVENT_BLOCKED event signifies that (1) there are no further pending callbacks and (2) that the window is now defunct and will receive no further callbacks. -

-

- This callback supports coordinated destruction of a window. The client window logic must stay intact until all of the queued callbacks are processed. Then the window may be safely closed. Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; ERROR on failure with errno set appropriately. -

- -

2.3.11 nx_synch()

-

Function Prototype:

- -

- Description: - This interface can be used to synchronize the window client with the NX server. It really just implements an echo: A synch message is sent from the window client to the server which then responds immediately by sending the NXEVENT_SYNCHED back to the windows client. -

-

- Due to the highly asynchronous nature of client-server communications, nx_synch() is sometimes necessary to assure that the client and server are fully synchronized in time. -

-

- Usage by the window client might be something like this: -

- -

- When the window listener thread receives the NXEVENT_SYNCHED event, it would set g_synched to true and post g_synch_sem, waking up the above loop. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; ERROR on failure with errno set appropriately -

- -

2.3.12 nx_openwindow()

-

Function Prototype:

- -

- Description: Create a new window. -

-

- Input Parameters: -

-

-

- Returned Value: -

- - -

2.3.13 nx_closewindow()

-

Function Prototype:

- -

- Description: - Destroy a window created by nx_openwindow() window. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.14 nx_requestbkgd()

-

Function Prototype:

- -

- Description: - NX normally controls a separate window called the background window. - It repaints the window as necessary using only a solid color fill. The - background window always represents the entire screen and is always - below other windows. It is useful for an application to control the - background window in the following conditions: -

- -

- This API only requests the handle of the background window. That - handle will be returned asynchronously in a subsequent position and - redraw callbacks. -

-

- Cautions: -

- -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.15 nx_releasebkgd()

-

Function Prototype:

- -

- Description: - Release the background window previously acquired using - nx_requestbkgd() - and return control of the background to NX. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.16 nx_getposition()

-

Function Prototype:

- -

- Description: - Request the position and size information for the selected window. The - values will be return asynchronously through the client callback function - pointer. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.17 nx_setposition()

-

Function Prototype:

- -

- Description: - Set the position and size for the selected window. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.18 nx_setsize()

-

Function Prototype:

- -

- Description: Set the size of the selected window. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.19 nx_raise()

-

Function Prototype:

- -

- Description: Bring the specified window to the top of the display. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.20 nx_lower()

-

Function Prototype:

- -

- Description: Lower the specified window to the bottom of the display. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.21 nx_modal()

-

Function Prototype:

- -

- Description: May be used to either (1) raise a window to the top of the display and select modal behavior, or (2) disable modal behavior. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.22 nx_setvisibility()

-

Function Prototype:

- -

- Description: Select if the window is visible or hidden. - A hidden window is still present and will update normally, but will not be visible on the display until it is unhidden. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.23 nx_ishidden()

-

Function Prototype:

- -

- Description: Return true if the window is hidden. -

-

- NOTE: There will be a delay between the time that the visibility of the window is changed via nx_setvisibily() before that new setting is reported by nx_ishidden(). - nx_synch() may be used if temporal synchronization is required. -

-

- Input Parameters: -

-

-

- Returned Value: - True: the window is hidden, false: the window is visible -

- -

2.3.24 nx_fill()

-

Function Prototype:

- -

- Description: - Fill the specified rectangle in the window with the specified color. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.25 nx_getrectangle()

-

Function Prototype:

- -

- Description: - Get the raw contents of graphic memory within a rectangular region. NOTE: - Since raw graphic memory is returned, the returned memory content may be - the memory of windows above this one and may not necessarily belong to - this window unless you assure that this is the top window. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.26 nx_filltrapezoid()

-

Function Prototype:

- -

- Description: - Fill the specified trapezoidal region in the window with the specified color. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.27 nx_drawline()

-

Function Prototype:

- -

- Description: - Fill the specified trapezoidal region in the window with the specified color. - Fill the specified line in the window with the specified color. - This is simply a wrapper that uses nxgl_splitline() to break the line into - trapezoids and then calls nx_filltrapezoid() to render the line. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.28 nx_drawcircle()

-

Function Prototype:

- -

- Description: - Draw a circular outline using the specified line thickness and color. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.29 nx_fillcircle()

-

Function Prototype:

- -

- Description: - Fill a circular region using the specified color. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.30 nx_setbgcolor()

-

Function Prototype:

- -

- Description: Set the color of the background. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.31 nx_move()

-

Function Prototype:

- -

- Description: Move a rectangular region within the window. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.32 nx_bitmap()

-

Function Prototype:

- -

- Description: - Copy a rectangular region of a larger image into the rectangle in the - specified window. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.33 nx_kbdin()

-

Function Prototype:

- -

- Description: - Used by a thread or interrupt handler that manages some kind of keypad - hardware to report text information to the NX server. That text - data will be routed by the NX server to the appropriate window client. -

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.3.34 nx_mousein()

-

Function Prototype:

- -

- Description: - Used by a thread or interrupt handler that manages some kind of pointing - hardware to report new positional data to the NX server. That positional - data will be routed by the NX server to the appropriate window client. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4 NX Tool Kit (NXTK)

- -

- NXTK implements where the framed window. - NX framed windows consist of three components within one NX window: -

-
    -
  1. The window border,
    2. -
  2. The main client window area, and
    3. -
  3. A toolbar area
    4. -
- -

- Each sub-window represents a region within one window. - Figure 1 shows some simple NX framed windows. - NXTK allows these sub-windows to be managed more-or-less independently: -

- - -

2.4.1 NXTK Types()

- -

- This is the handle that can be used to access the window data region. -

- - -

2.4.2 nxtk_block()

-

Function Prototype:

- -

- Description: - The response to this function call is two things: (1) any queued callback messages to the window are 'blocked' and then (2) also subsequent window messaging is blocked. -

-

- The event callback with the NXEVENT_BLOCKED event is the response from nxtk_block(). This blocking interface is used to assure that no further messages are are directed to the window. Receipt of the NXEVENT_BLOCKED event signifies that (1) there are no further pending callbacks and (2) that the window is now defunct and will receive no further callbacks. -

-

- This callback supports coordinated destruction of a window. The client window logic must stay intact until all of the queued callbacks are processed. Then the window may be safely closed. Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; ERROR on failure with errno set appropriately. -

- -

2.4.3 nxtk_synch()

-

Function Prototype:

- -

- Description: - This interface can be used to synchronize the window client with the NX server. It really just implements an echo: A synch message is sent from the window client to the server which then responds immediately by sending the NXEVENT_SYNCHED back to the windows client. -

-

- Due to the highly asynchronous nature of client-server communications, nx_synch() is sometimes necessary to assure that the client and server are fully synchronized in time. -

-

- Usage by the window client might be something like this: -

- -

- When the window listener thread receives the NXEVENT_SYNCHED event, it would set g_synched to true and post g_synch_sem, waking up the above loop. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; ERROR on failure with errno set appropriately -

- -

2.4.4 nxtk_openwindow()

-

Function Prototype:

- -

- Description: Create a new, framed window. -

-

- Input Parameters: -

-
handle -
The handle returned by nx_connect(). -
flags -
Optional flags. - These include: -
    -
  • NXBE_WINDOW_RAMBACKED: Creates a RAM backed window. - This option is only valid if CONFIG_NX_RAMBACKED is enabled. -
    • -
  • NXBE_WINDOW_HIDDEN: The window is create in the HIDDEN state and can be made visible later with nxtk_setvisibility(). -
    • -
-
cb -
Callbacks used to process window events -
arg -
User provided argument (see nx_openwindow()) -
-

-

- Returned Value: -

- - -

2.4.5 nxtk_closewindow()

-

Function Prototype:

- -

- Description: - Close the window opened by nxtk_openwindow(). -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.6 nxtk_getposition()

-

Function Prototype:

- -

- Description: - Request the position and size information for the selected framed window. - The size/position for the client window and toolbar will be return - asynchronously through the client callback function pointer. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.7 nxtk_setposition()

-

Function Prototype:

- -

- Description: - Set the position for the selected client window. This position does not - include the offsets for the borders nor for any toolbar. Those offsets - will be added in to set the full window position. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
pos -
The new position of the client sub-window -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.8 nxtk_setsize()

-

Function Prototype:

- -

- Description: - Set the size for the selected client window. This size does not - include the sizes of the borders nor for any toolbar. Those sizes - will be added in to set the full window size. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
size -
The new size of the client sub-window. -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.9 nxtk_raise()

-

Function Prototype:

- -

- Description: - Bring the window containing the specified client sub-window to the top - of the display. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow() - specifying the window to be raised. -
-
-
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.10 nxtk_lower()

-

Function Prototype:

- -

- Description: - Lower the window containing the specified client sub-window to the - bottom of the display. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow() - specifying the window to be lowered. -
-
-
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.11 nxtk_modal()

-

Function Prototype:

- -

- Description: May be used to either (1) raise a window to the top of the display and select modal behavior, or (2) disable modal behavior. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.12 nxtk_setvisibility()

-

Function Prototype:

- -

- Description: Select if the window is visible or hidden. - A hidden window is still present and will update normally, but will not be visible on the display until it is unhidden. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.13 nxtk_ishidden()

-

Function Prototype:

- -

- Description: Return true if the window is hidden. -

-

- NOTE: There will be a delay between the time that the visibility of the window is changed via nxtk_setvisibily() before that new setting is reported by nxtk_ishidden(). - nxtk_synch() may be used if temporal synchronization is required. -

-

- Input Parameters: -

-

-

- Returned Value: - True: the window is hidden, false: the window is visible -

- -

2.4.14 nxtk_fillwindow()

-

Function Prototype:

- -

- Description: - Fill the specified rectangle in the client window with the specified color. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
rect -
The location within the client window to be filled -
color -
The color to use in the fill -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.15 nxtk_getwindow()

-

Function Prototype:

- -

- Description: - Get the raw contents of graphic memory within a rectangular region. NOTE: - Since raw graphic memory is returned, the returned memory content may be - the memory of windows above this one and may not necessarily belong to - this window unless you assure that this is the top window.

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
rect -
The location within the client window to be retrieved. - -
plane -
Specifies the color plane to get from. -
dest -
The location to copy the memory region -
deststride -
The width, in bytes, of the dest memory -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.16 nxtk_filltrapwindow()

-

Function Prototype:

- -

- Description: - Fill the specified trapezoid in the client window with the specified color -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
trap -
The trapezoidal region to be filled. -
color -
The color to use in the fill. -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.17 nxtk_drawlinewindow()

-

Function Prototype:

- -

- Description: - Fill the specified trapezoidal region in the window with the specified color. - Fill the specified line in the window with the specified color. - This is simply a wrapper that uses nxgl_splitline() to break the line into - trapezoids and then calls nxtk_filltrapwindow() to render the line. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.18 nxtk_drawcirclewindow()

-

Function Prototype:

- -

- Description: - Draw a circular outline using the specified line thickness and color. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.19 nxtk_fillcirclewindow()

-

Function Prototype:

- -

- Description: - Fill a circular region using the specified color. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.20 nxtk_movewindow()

-

Function Prototype:

- -

- Description: - Move a rectangular region within the client sub-window of a framed window. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow() - specifying the client sub-window within which the move is to be done. -
rect -
Describes the rectangular region relative to the client sub-window to move. -
offset -
The offset to move the region -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.21 nxtk_bitmapwindow()

-

Function Prototype:

- -

- Description: - Copy a rectangular region of a larger image into the rectangle in the - specified client sub-window. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow() - specifying the client sub-window that will receive the bitmap. -
dest -
Describes the rectangular region on in the client sub-window - will receive the bit map. -
src -
The start of the source image(s). This is an array source - images of size CONFIG_NX_NPLANES (probably 1). -
origin -
The origin of the upper, left-most corner of the full bitmap. - Both dest and origin are in sub-window coordinates, however, the - origin may lie outside of the sub-window display. -
stride -
The width of the full source image in pixels. -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.22 nxtk_opentoolbar()

-

Function Prototype:

- -

- Description: - Create a tool bar at the top of the specified framed window. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
height -
The requested height of the toolbar in pixels. -
cb -
Callbacks used to process toolbar events. -
arg -
User provided value that will be returned with toolbar callbacks. -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.23 nxtk_closetoolbar()

-

Function Prototype:

- -

- Description: - Remove the tool bar at the top of the specified framed window. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
-
-
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.24 nxtk_filltoolbar()

-

Function Prototype:

- -

- Description: - Fill the specified rectangle in the toolbar sub-window with the specified color. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
rect -
The location within the toolbar window to be filled. -
color -
The color to use in the fill. -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.25 nxtk_gettoolbar()

-

Function Prototype:

- -

- Description: - Get the raw contents of graphic memory within a rectangular region. NOTE: - Since raw graphic memory is returned, the returned memory content may be - the memory of windows above this one and may not necessarily belong to - this window unless you assure that this is the top window. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
rect -
The location within the toolbar window to be retrieved. - -
plane -
TSpecifies the color plane to get from. -
dest -
TThe location to copy the memory region. -
deststride -
The width, in bytes, of the dest memory. -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.26 nxtk_filltraptoolbar()

-

Function Prototype:

- -

- Description: - Fill the specified trapezoid in the toolbar sub-window with the specified color. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
trap -
The trapezoidal region to be filled -
color -
The color to use in the fill -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.27 nxtk_drawlinetoolbar()

-

Function Prototype:

- -

- Description: - Fill the specified line in the toolbar sub-window with the specified color. - This is simply a wrapper that uses nxgl_splitline() to break the line into - trapezoids and then calls nxtk_filltraptoolbar() to render the line. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.28 nxtk_drawcircletoolbar()

-

Function Prototype:

- -

- Description: - Draw a circular outline using the specified line thickness and color. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.29 nxtk_fillcircletoolbar()

-

Function Prototype:

- -

- Description: - Fill a circular region using the specified color. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.30 nxtk_movetoolbar()

-

Function Prototype:

- -

- Description: - Move a rectangular region within the toolbar sub-window of a framed window. -

-

- Input Parameters: -

-
hfwnd -
A handle identifying sub-window containing the toolbar within which the move is - to be done. - This handle must have previously been returned by - nxtk_openwindow(). -
rect -
Describes the rectangular region relative to the toolbar sub-window to move. -
offset -
The offset to move the region -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.4.31 nxtk_bitmaptoolbar()

-

Function Prototype:

- -

- Description: - Copy a rectangular region of a larger image into the rectangle in the - specified toolbar sub-window. -

-

- Input Parameters: -

-
hfwnd -
A handle previously returned by - nxtk_openwindow(). -
dest -
Describes the rectangular region on in the toolbar sub-window - will receive the bit map. -
src -
The start of the source image. -
origin -
The origin of the upper, left-most corner of the full bitmap. - Both dest and origin are in sub-window coordinates, however, the - origin may lie outside of the sub-window display. -
stride -
The width of the full source image in bytes. -
-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately -

- -

2.5 NX Fonts Support (NXFONTS)

- -

2.5.1 NXFONTS Types()

-

- This structures provides the metrics for one glyph: -

- - -

- This structure binds the glyph metrics to the glyph bitmap: -

- - -

- This structure describes one contiguous grouping of glyphs that - can be described by an array starting with encoding first and - extending through (first + nchars - 1). -

- - -

- This structure describes the overall fontset: -

- - -

2.5.2 nxf_getfonthandle()

-

Function Prototype:

- -

- Description: - Given a numeric font ID, return a handle that may be subsequently be used to access the font data sets. -

-

- Input Parameters: -

-

-

- Returned Value: - A handle that may be subsequently be used to access the font data sets. -

- -

2.5.3 nxf_getfontset()

-

Function Prototype:

- -

- Description: - Return information about the current font set. -

-

- Input Parameters: -

-

-

- Returned Value: - An instance of struct nx_font_s describing the font set. -

- -

2.5.4 nxf_getbitmap()

-

Function Prototype:

- -

- Description: - Return font bitmap information for the selected character encoding. -

-

- Input Parameters: -

-

-

- Returned Value: - An instance of struct nx_fontbitmap_s describing the glyph. -

- -

2.5.5 nxf_convert_*bpp()

-

Function Prototype:

- -

- Description: Convert the 1BPP font to a new pixel depth. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; - ERROR on failure with errno set appropriately. -

- - - -

- 2.6 -

-

-

-

- -

2.6 NX Cursor Support (NXCURSOR)

- -

2.6.1 nxcursor_enable()

-

Function Prototype:

- -

- Description: - Enable/disable presentation of the cursor. The disabled cursor still exits and still may be controlled, but is not visible on the display. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; ERROR on failure with errno set appropriately. -

- -

2.6.2 nxcursor_setimage()

-

Function Prototype:

- -

- Description: - Set the cursor image. -

-

- The image is provided a a 2-bits-per-pixel image. The two bit incoding is as following: -

- -

- NOTE: The NX logic will reference the user image buffer repeatedly. That image buffer must persist for as long as the NX server connection persists. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; ERROR on failure with errno set appropriately. -

- -

2.6.3 nxcursor_setposition()

-

Function Prototype:

- -

- Description: - Move the cursor to the specified position. -

-

- Input Parameters: -

-

-

- Returned Value: - OK on success; ERROR on failure with errno set appropriately. -

- -

2.7 Sample Code

- -

apps/examples/nx*. - No sample code is provided in this document. - However, examples can be found in the NuttX source tree at the follow locations: - That example code is intended to test NX. - Since it is test code, it is designed to exercise functionality and does not necessarily represent best NX coding practices. -

- - -

- In its current form, the NX graphics system provides a low level of graphics and window - support. - Most of the complexity of manage redrawing and handling mouse and keyboard events must - be implemented by the NX client code. -

- -

Building apps/examples/nx. - Testing was performed using the Linux/Cygwin-based NuttX simulator. - Instructions are provided for building that simulation are provided in - Appendix C of this document. -

- - - - - -
-

Appendix A graphics/ Directory Structure

-
- -

- The graphics capability consist both of components internal to the RTOS and of user-callable interfaces. - In the NuttX kernel mode build there are some components of the graphics subsystem are callable in user mode and other components that are internal to the RTOS. - The directory nuttx/graphics contains only those components that are internal to the RTOS. - - User callable functions must be part of a library that can be linked against user applications. - This user callable interfaces are provided in sub-directories under nuttx/libnx. -

-

- - - - - -
-

Appendix B NX Configuration Options

-
- -

B.1 General Configuration Settings

- - - -

B.2 NXGL Configuration Settings

- - - -

B.3 NX Configuration Settings

- - - -

B.4 NX Server Configuration Settings

- - - -

B.5 NXTK Configuration Settings

- - - -

B.6 NXFONTS Configuration Settings

- - - -

B.7 NxTerm Configuration Settings

- -

General NxTerm settings.

- - -

NxTerm output text/graphics options:

- - -

NxTerm input options:

- - - - - - -
-

Appendix C Installing New Fonts

-
- -

The BDF Font Converter. - There is a tool called bdf-converter in the directory tools/.. - The bdf-converter program be used to convert fonts in Bitmap Distribution Format (BDF) into fonts that can be used in the NX graphics system. - The BDF format most well known as a font format traditionally used for X-11 bitmap fonts. -

-
- A Note about Font Copyrights: - My understanding is that the underlying bitmap font data for traditional fonts cannot be copyrighted (the same is not true for scalable fonts). - This is because a copyright covers only the form of delivery of the font and not the underlying font content and, at least for the traditional typefaces, the underlying font designs are ancient. - There could be issues, however, if you convert from modern, trademarked images. - However, remember that I am a programmer not an attorney and that my knowledge of font copyright issues is limited to what I glean by Googling. -
-

- Font Installation Steps, - Below are general instructions for creating and installing a new font in the NX graphic system. - The first two steps only apply if you are using the BDF font converter program. -

-
    -
  1. -

    - Locate a font in BDF format. - There are many good BDF bitmap fonts bundled with X-11. - See this link, as an example, -

    -
    2. -
  2. -

    - Use the bdf-converter program to convert the BDF font to the NuttX font format. - This will result in a C header file containing definitions. - That header file should be installed at, for example, graphics/nxfonts/nxfonts_myfont.h. -

    -
    3. -
-

- The remaining steps apply however you managed to create the NuttX C font header file. - After you have your C font header file, the next thing to do is to create a new NuttX configuration variable to select the font. - For example, suppose you define the following variable: CONFIG_NXFONT_MYFONT. - Then you would need to: -

-
    -
  1. -

    - Define CONFIG_NXFONT_MYFONT=y in your NuttX configuration file. -

    -
    2. -
-

- A font ID number has to be assigned for each new font. - The font IDs are defined in the file include/nuttx/nx/nxfonts.h. - Those definitions have to be extended to support your new font. - Look at how the font ID enabled by CONFIG_NXFONT_SANS23X27 is defined and add an ID for yournew font in a similar fashion: -

-
    -
  1. -

    - include/nuttx/nx/nxfonts.h. Add you new font as a possible system default font: -

    - 
      -#if defined(CONFIG_NXFONT_SANS23X27)
-# define NXFONT_DEFAULT FONTID_SANS23X27
-#elif defined(CONFIG_NXFONT_MYFONT)
-# define NXFONT_DEFAULT FONTID_MYFONT
-#endif
-
    -

    - Then define the actual font ID. - Make sure that the font ID value is unique: -

    - 
      -enum nx_fontid_e
-{
-  FONTID_DEFAULT     = 0      /* The default font */
-#ifdef CONFIG_NXFONT_SANS23X27
-  , FONTID_SANS23X27 = 1      /* The 23x27 sans serif font */
-#endif
-#ifdef CONFIG_NXFONT_MYFONT
-  , FONTID_MYFONT    = 2      /* My shiny, new font */
-#endif
-...
-
    -
    2. -
-

- New Add the font to the NX build system. - There are several files that you have to modify to do this. - Look how the build system uses the font CONFIG_NXFONT_SANS23X27 for examaples: -

-
    -
  1. -

    - nuttx/graphics/Makefile. - This file needs logic to auto-generate a C source file from the header file that you generated with the bdf-converter program. - Notice NXFONTS_FONTID=2; this must be set to the same font ID value that you defined in the include/nuttx/nx/nxfonts.h file. -

    - 
      -genfontsources:
-  ifeq ($(CONFIG_NXFONT_SANS23X27),y)
-      @$(MAKE) -C nxfonts -f Makefile.sources TOPDIR=$(TOPDIR) NXFONTS_FONTID=1 EXTRAFLAGS=$(EXTRAFLAGS)
-  endif
-  ifeq ($(CONFIG_NXFONT_MYFONT),y)
-      @$(MAKE) -C nxfonts -f Makefile.sources TOPDIR=$(TOPDIR) NXFONTS_FONTID=2 EXTRAFLAGS=$(EXTRAFLAGS)
-  endif
-
    -
    2. -
  2. -

    - nuttx/graphics/nxfonts/Make.defs. - Set the make variable NXFSET_CSRCS. - NXFSET_CSRCS determines the name of the font C file to build when NXFONTS_FONTID=2: -

    - 
      -ifeq ($(CONFIG_NXFONT_SANS23X27),y)
-NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c
-endif
-ifeq ($(CONFIG_NXFONT_MYFONT),y)
-NXFSET_CSRCS += nxfonts_bitmaps_myfont.c
-endif
-
    -
    3. -
  3. -

    - nuttx/graphics/nxfonts/Makefile.sources. - This is the Makefile used in step 5 that will actually generate the font C file. - So, given your NXFONTS_FONTID=2, it needs to determine a prefix to use for auto-generated variable and function names and (again) the name of the autogenerated file to create (this must be the same name that was used in nuttx/graphics/nxfonts/Make.defs): -

    - 
      -ifeq ($(NXFONTS_FONTID),1)
-NXFONTS_PREFIX	:= g_sans23x27_
-GEN_CSRC	= nxfonts_bitmaps_sans23x27.c
-endif
-ifeq ($(NXFONTS_FONTID),2)
-NXFONTS_PREFIX	:= g_myfont_
-GEN_CSRC	= nxfonts_bitmaps_myfont.c
-endif
-
    -
    4. -
  4. -

    - graphics/nxfonts/nxfonts_bitmaps.c. - This is the file that contains the generic font structures. - It is used as a "template&qout; file by nuttx/graphics/nxfonts/Makefile.sources to create your customized font data set at build time. -

    - 
      -#if NXFONTS_FONTID == 1
-#  include "nxfonts_sans23x27.h"
-#elif NXFONTS_FONTID == 2
-#  include "nxfonts_myfont.h"
-#else
-#  error "No font ID specified"
-#endif
-
    -

    - Where nxfonts_myfont.h is the NuttX font file that we generated in - step 2 using the bdf-converter tool. -

    -
  5. -

    - graphics/nxfonts/nxfonts_getfont.c. - Finally, we need to extend the logic that does the run-time font lookups so that can find our new font. - The lookup function is NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid). - Note that the lookup is based on the font ID that was defined in step 4. - The new font information needs to be added to data structures used by that function: -

    - 
      -#ifdef CONFIG_NXFONT_SANS23X27
-extern const struct nx_fontpackage_s g_sans23x27_package;
-#endif
-#ifdef CONFIG_NXFONT_MYFONT
-extern const struct nx_fontpackage_s g_myfont_package;
-#endif
-
-static FAR const struct nx_fontpackage_s *g_fontpackages[] =
-{
-#ifdef CONFIG_NXFONT_SANS23X27
-  &g_sans23x27_package,
-#endif
-#ifdef CONFIG_NXFONT_MYFONT
-  &g_myfont_package,
-#endif
-  NULL
-};
-
    -
    6. -
- - - - - -
-

Appendix D NX Test Coverage

-
- -

apps/examples/nx. - The primary test tool for debugging NX resides at apps/examples/nx. -

-

Building apps/examples/nx. - NX testing was performed using apps/examples/nx with the - Linux/Cygwin-based NuttX simulator. - Configuration files for building this test can be found in boards/sim/sim/sim/configs/nx - and boards/sim/sim/sim/configs/nx11. - There are two alternative configurations for building the simulation: -

-
    -
  1. - The configuration using the configuration file at boards/sim/sim/sim/configs/nx/defconfig. - This default configuration exercises the NX logic a 8 BPP but provides no visual feedback. - In this configuration, a very simple, simulated framebuffer driver is used that is - based upon a simple region of memory posing as video memory. - That default configuration can be built as follows: -
      -tools/configure.sh sim:nx
-make
-./nuttx
-
    -
    2. -
  2. -

    - The preferred configuration is at boards/sim/sim/sim/configs/nx11/defconfig. - This configuration extends the test with a simulated framebuffer driver - that uses an X window as a framebuffer. - This is a superior test configuration because the X window appears at your desktop - and you can see the NX output. - This preferred configuration can be built as follows: -

    -
      -tools/configure sim:nx11
-make
-./nuttx
-
    -

    - Update: - The sim target has suffered some bit-rot over the years and so the following caveats need to be added: -

      -

    • - The X target builds under recent Cygwin configurations, but does not execute. - (It fails inside of XOpenDisplay(). -

      • -

    • - The X target does not build under current (9.09) Ubuntu distributions. - I needed to make the following changes: -

      -
        -cd /usr/lib/ -sudo ln -s libXext.so.6.4.0 libXext.so -
      -

      - The build will also fail to locate the X header files unless you install an X11 development package. -

      • -

    • - The sim target itself is broken under 64-bit Linux. - This is because the sim target is based upon some assembly language setjmp/longjmp logic that only works on 32-bit systems. -

      -

      - NOTE: There is a workaround in this case: - You can build for 32-bit execution on a 64-bit machine by adding -m3 to the CFLAGS and -m32 -m elf_i386 to the LDFLAGS. - The configuration/build system will do this for you; - you simply need to select CONFIG_SIM_M32=y in your configuration file. -

      -
      • -

    • - Refer to the readme file in sim configuration - README.txt file for additional information. -

      • -
    -

    -
    3. -
- -

Test Coverage. - At present, apps/examples/nxt only exercises a subset of NX; - the remainder is essentially untested. - The following table describes the testing performed on each NX API: -

- -

Table D.1: NXGLIB API Test Coverage

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FunctionSpecial Setup/NotesVerified
nxgl_rgb2yuv()
NO
nxgl_yuv2rgb()
NO
nxgl_rectcopy()
YES
nxgl_rectoffset()
YES
nxgl_vectoradd()
YES
nxgl_vectorsubtract()
YES
nxgl_rectintersect()
YES
nxgl_rectunion()
YES
nxgl_nonintersecting()
YES
nxgl_rectoverlap()
YES
nxgl_rectinside()
YES
nxgl_rectsize()
YES
nxgl_nullrect()
YES
nxgl_runoffset() - Verified by apps/examples/nxlines. - YES
nxgl_runcopy()
NO
nxgl_trapoffset() - Verified by apps/examples/nxlines. - YES
nxgl_trapcopy() - Verified by apps/examples/nxlines. - YES
nxgl_colorcopy
YES
nxgl_splitline - Verified using apps/examples/nxlines. - Generally works well, but has some accuracy/overflow problems wide lines - that are nearly horizontal. - There is a "fudge factor" that seems to eliminate the problem, - but there could still be issues in some configurations. - YES
nxgl_circlepts - Verified by apps/examples/nxlines. - YES
nxgl_circletraps - Verified by apps/examples/nxlines. - YES
- -

Table D.2: NX Server Callbacks Test Coverage

-
- - - - - - - - - - - - - - - - - - - - - - - - - -
FunctionSpecial Setup/NotesVerified
redraw()
YES
position()
YES
mousein()
YES
kbdin()
YES
- -

Table D.3: NX API Test Coverage

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FunctionSpecial Setup/NotesVerified
nx_runinstance()
YES
nx_connectinstance()
YES
nx_disconnect()
YES
nx_eventhandler()
YES
nx_eventnotify()This is not used in the current version of apps/examples/nx, - was tested in a previous version)NO
nx_openwindow()Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the - <NuttX-Directory>/.config fileYES
nx_closewindow()Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the - <NuttX-Directory>/.config fileYES
nx_requestbkgd() - Verified by apps/examples/nxtext and apps/examples/nxhello. - YES
nx_releasebkgd() - Verified by apps/examples/nxtext and apps/examples/nxhello. - YES
nx_getposition()
NO
nx_setposition()Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the - <NuttX-Directory>/.config fileYES
nx_setsize()Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the - <NuttX-Directory>/.config fileYES
nx_raise()Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the - <NuttX-Directory>/.config fileYES
nx_lower()Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the - <NuttX-Directory>/.config fileYES
nx_modal() NO
nx_setvisibility()Exercized using Twm4NxYES, Informally
nx_ishidden()Exercized using Twm4NxYES, Informally
nx_fill()Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the - <NuttX-Directory>/.config fileYES
nx_getrectangle()
YES
nx_filltrapezoid() - Verified by apps/examples/nxlines. - YES
nx_drawline() - Verified by apps/examples/nxlines. - YES
nx_drawcircle() - Verified by apps/examples/nxlines. - YES
nx_fillcircle() - Verified by apps/examples/nxlines. - YES
nx_setbgcolor()
YES
nx_move()Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the - <NuttX-Directory>/.config fileYES
nx_bitmap()Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the - <NuttX-Directory>/.config file.YES
nx_kbdin()
YES
nx_mousein()
YES
- - -

Table D.4: NXTK API Test Coverage

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FunctionSpecial Setup/NotesVerified
nxtk_openwindow()
YES
nxtk_closewindow()
YES
nxtk_getposition()
NO
nxtk_setposition()
YES
nxtk_setsize()
YES
nxtk_raise()
YES
nxtk_lower()
YES
nxtk_modal()
NO
nxtk_setvisibility()Exercized using Twm4NxYES, informally
nxtk_ishidden()Exercized using Twm4NxYES, informally
nxtk_fillwindow()
YES
nxtk_getwindow()
NO
nxtk_filltrapwindow()
NO
nxtk_drawlinewindow()
YES
nxtk_drawcirclewindow()
YES
nxtk_fillcirclewindow()
YES
nxtk_movewindow()
NO
nxtk_bitmapwindow()
YES
nxtk_opentoolbar()
YES
nxtk_closetoolbar()
YES
nxtk_filltoolbar()
YES
nxtk_gettoolbar()
NO
nxtk_filltraptoolbar()
NO
nxtk_drawlinetoolbar()
NO
nxtk_drawcircletoolbar()
NO
nxtk_fillcircletoolbar()
NO
nxtk_movetoolbar()
NO
nxtk_bitmaptoolbar()
NO
- -

Table D.5: NXFONTS API Test Coverage

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FunctionSpecial Setup/NotesVerified
nxf_getfonthandle()
YES
nxf_getfontset()
YES
nxf_getbitmap()
YES
nxf_convert_2bpp()
NO
nxf_convert_4bpp()
NO
nxf_convert_8bpp()Use defconfig when building.YES
nxf_convert_16bpp()
YES
nxf_convert_24bpp()
NO
nxf_convert_32bpp()
YES
- - - diff --git a/Documentation/NfsHowto.html b/Documentation/NfsHowto.html deleted file mode 100644 index 9de0ee679f..0000000000 --- a/Documentation/NfsHowto.html +++ /dev/null @@ -1,385 +0,0 @@ - - -NFS Client How-To - - -
- - - - - -
-

NFS Client How-To

-

Last Updated: June 18, 2012

-
-
- - - - - -
-

Table of Contents

-
- -
- - - -
- - - - - -
- Adding NFS to the NuttX Configuration -
- - - - - -
- Mount Interface -
- - - - - -
- NFS Mount Command -
- - - - - -
- Configuring the NFS server (Ubuntu) -
-
- - - - - -
-

Adding NFS to the NuttX Configuration

 -
- -

- The NFS client is easily added to your configuration: - You simply need to add CONFIG_NFS to your nuttx/.config file. - There are, however, a few dependencies on other system settings: -

-
    -
  1. - First, there are things that you must configure in order to be able to use any file system: -
    2. - -
  2. - And there are several dependencies on the networking configuration. - At a minimum, you need to have the following selections: -
    3. - -
- - - - - -
-

Mount Interface

 -
- -

- A low-level, C-callable interface is provided to mount a file system. - That interface is called mount() and is mentioned in the porting guide and is prototyped in the header file include/sys/mount.h: -

- -

- Synopsis: - mount() attaches the filesystem specified by the source block device name into the root file system at the path specified by target. -

-

- Input Parameters: -

-

-

- Returned Values - Zero is returned on success; -1 is returned on an error and errno is set appropriately: -

-

-

- This same interface can be used to mount a remote, NFS file system using some special parameters. - The NFS mount differs from the normal file system mount in that: (1) there is no block driver for the NFS file system, and (2) special parameters must be passed as data to describe the remote NFS server. - Thus the following code snippet might represent how an NFS file system is mounted: -

- -

- NOTE that: (1) the block driver parameter is NULL. - The mount() is smart enough to know that no block driver is needed with the NFS file system. - (2) The NFS file system is identified with the simple string "nfs" - (3) A reference to struct nfs_args is passed as an NFS-specific argument. -

-

- The NFS-specific interface is described in the file include/nuttx/fs/nfs.h. - There you can see that struct nfs_args is defined as: -

- - - - - - -
-

NFS Mount Command

 -
- -

- The NuttShell (NSH) also supports a command called nfsmount - that can be used to mount a remote file system via the NSH command line. -

-

- Command Syntax: -

- -

- Synopsis. - The nfsmount command mounts a network file system in the NuttX pseudo filesystem. - The nfsmount will use NFSv3 UDP protocol to mount the remote file system. -

-

- Command Line Arguments. - The nfsmount takes three arguments: -

-
    -
  1. - The <server-address> is the IP address of the server exporting the file system you wish to mount. - This implementation of NFS for the NuttX RTOS is only for a local area network, so the server and client must be in the same network. -
    2. -
  2. - The <mount-point > is the location in the NuttX pseudo filesystem where the mounted volume will appear. - This mount point can only reside in the NuttX pseudo filesystem. - By convention, this mount point is a subdirectory under /mnt. - The mount command will create whatever pseudo directories that may be needed to complete the full path (but the full path must not already exist). -
    3. -
  3. - The <remote-path> is the file system / directory being exported from server. - This / directory must have been configured for exportation on the server before when the NFS server was set up. -
    4. -
- -

- After the volume has been mounted in the NuttX pseudo filesystem, it may be access in the same way as other objects in the file system. -

-

- Example. - Suppose that the NFS server has been configured to export the directory /export/shared. - The the following command would mount that file system (assuming that the target also has privileges to mount the file system). -

- - - - - - -
-

Configuring the NFS server (Ubuntu)

 -
- -

- Setting up the server will be done in two steps: - First, setting up the configuration file for NFS, and then starting the NFS services. - But first, you need to install the nfs server on Ubuntu with these two commands: -

- - -

- After that, we need to make or choose the directory we want to export from the NFS server. - In our case, we are going to make a new directory called /export. -

- -

- It is important that /export directory allow access to everyone (777 permissions) as we will be accessing the NFS share from the client with no authentication. -

- -

- When all this is done, we will need to edit the configuration file to set up an NFS server: /etc/exports. - This file contains a list of entries; - each entry indicates a volume that is shared and how it is shared. - For more information for a complete description of all the setup options for this file you can check in the man pages (man export).

- An entry in /etc/exports will typically look like this: -

- -

- So for our example we export /export to the client 10.0.0.2 add the entry: -

- -

- In our case we are using all the default options except for the ro that we replaced with rw so that our client will have read and write access to the directory that we are exporting. -

-

- After we do all the require configurations, we are ready to start the server with the next command: -

- -

- Note: If you later decide to add more NFS exports to the /etc/exports file, you will need to either restart NFS daemon -or run command exportfs. -

- -

Or

- -

- Now we can check if the export directory and our mount point is properly set up. -

- -

- And also we can verify if NFS is running in the system with: -

-

-

-

- Now your NFS sever is sharing /export directory to be accessed. -

- - - diff --git a/Documentation/NuttShell.html b/Documentation/NuttShell.html deleted file mode 100644 index 11d53e2a47..0000000000 --- a/Documentation/NuttShell.html +++ /dev/null @@ -1,6008 +0,0 @@ - - -NuttShell - - - -
-
- - - - -
-

Table of Contents

-
- - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- 1.0 Overview -

- 1.1 Console/NSH Front End -

- 1.2 Command Overview -

- 1.3 Conditional Command Execution -

- 1.4 Looping -

- 1.5 Built-In Variables -

- 1.6 Current Working Directory -

- 1.7 Environment Variables -

- 1.8 NSH Start-Up Script -
- 2.0 Commands. -

- 2.1 Evaluate Expression (test) -

- 2.2 Add a Routing Table Entry (addroute) -

- 2.3 Access the ARP table (arp) -

- 2.4 Base64 Decode (base64dec) -

- 2.5 Base64 Encode (base64enc) -

- 2.6 Extract Base File/Directory Name (basename) -

- 2.7 Terminate a Loop (break) -

- 2.8 Concatenate Files (cat) -

- 2.9 Change Current Working Directory (cd) -

- 2.10 Compare Files (cmp) -

- 2.11 Copy Files (cp) -

- 2.12 Show or set the date and time (date) -

- 2.13 Copy and Convert Files (dd) -

- 2.14 Delete a Routing Table Entry (delroute) -

- 2.15 Show volume status (df) -

- 2.16 Extract Path to a File/Directory (dirname) -

- 2.17 Dump Buffered SYSLOG Output (dmesg) -

- 2.18 Echo Strings and Variables (echo) -

- 2.19 Show Environment Variables (env) -

- 2.20 Execute User Code (exec) -

- 2.21 Exit NSH (exit) -

- 2.22 Set an Environment Variable (export) -

- 2.23 Show Memory Manager Status (free) -

- 2.24 Get File Via TFTP (get) -

- 2.25 Show Usage Command Usage (help) -

- 2.26 Hexadecimal Dump of File or Device (hexdump) -

- 2.27 Manage Network Configuration (ifconfig) -

- 2.28 Take a network down (ifdown) -

- 2.29 Bring a network up (ifup) -

- 2.30 Install an OS module (insmod) -

- 2.31 Show Interrupt Status (irqinfo) -

- 2.32 Send a signal to a task (kill) -

- 2.33 Setup/teardown the Loop Device (losetup) -

- 2.34 List to a File or Directory (ln) -

- 2.35 List Directory Contents (ls) -

- 2.36 Show information about installed OS modules (lsmod) -

- 2.37 Calculate MD5 (md5) -

- 2.38 Access Memory (mb, mh, and mw) -

- 2.39 Show Current Tasks and Threads (ps) -

- 2.40 Create a Directory (mkdir) -

- 2.41 Create a FAT File System (mkfatfs) -

- 2.42 Create a FIFO (mkfifo) -

- 2.43 Create a RAMDISK (mkrd) -

- 2.44 Mount a File System (mount) -

- 2.45 Rename a File (mv) -

- 2.46 Mount an NFS File System (nfsmount) -

- 2.47 Lookup a network address (nslookup) -

- 2.48 Change a User's Password (passwd) -

- 2.49 Manage Power Management Subsystem (pmconfig) -

- 2.50 Shut the system down (poweroff) -

- 2.51 Send File Via TFTP (put) -

- 2.52 Show Current Working Directory (pwd) -

- 2.53 Show target of a link (readlink) -

- 2.54 Reset and reboot the system (reboot) -

- 2.55 Remove a File (rm) -

- 2.56 Remove a Directory (rmdir) -

- 2.57 Remove on OS Module (rmmod) -

- 2.58 Show routing table (route) -

- 2.59 Start/Stop the OpenAMP RPC Tunnel (rptun) -

- 2.60 Set a Variable (set) -

- 2.61 Execute an NSH Script (sh) -

- 2.62 Shut the system down (shutdown) -

- 2.63 Wait for Seconds (sleep) -

- 2.64 Start the Telnet Daemon (telnetd) -

- 2.65 Time execution of another command (time) -

- 2.66 Set the Size of a File (truncate) -

- 2.67 Unmount a File System (umount) -

- 2.68 Print system information (uname) -

- 2.69 Unset an Environment Variable (unset) -

- 2.70 URL Decode (urldecode) -

- 2.71 URL Encode (urlencode) -

- 2.72 Add a New User (useradd) -

- 2.73 Delete a user (userdel) -

- 2.74 Wait for Microseconds (usleep) -

- 2.75 Get File Via HTTP (wget) -

- 2.76 Hexadecimal Dump of Memory (xd) -
- 3.0 Built-In Commands -

 - 3.1 Check Network Peer (ping/pin6) -
- 4.0 Configuration Settings -

 - 4.1 Command Dependencies on Configuration Settings -

- 4.2 Built-In Command Dependencies on Configuration Settings -

- 4.3 NSH-Specific Configuration Settings -
- 5.0 Customizing the NuttShell -

- 5.1 The NSH Library and NSH Initialization -

- 5.2 NSH Commands -

- 5.3 NSH "Built-In" Applications -

- 5.4 Customizing NSH Initialization -
- 6.0 Shell Login -

 - 6.1 Enabling Shell Logins -

- 6.2 Verification of Credentials -

- 6.3 Password Files -

- 6.4 Creating a Password File for a ROMFS File System -
- Index -
-
- -
-
- - - - -
-

NuttShell (NSH)

-

Last Updated: March 21, 2020

-
-
- - - - - - -
-

1.0 Overview

 -
- -

- The NSH Library. - The apps/nshlib sub-directory contains the NuttShell (NSH) - library. - This library can easily to linked to produce a NSH application (See as an example apps/examples/nsh). - The NSH Library provides a simple shell application for NuttX. -

- - - - - -
-

1.1 Console/NSH Front End

 -
- -

- NSH Consoles. - Using settings in the configuration file, NSH may be configured to use - (1) the serial stdin/out, - (2) a USB serial device (such as CDC/ACM), or - (3) a telnet connection as the console. - Or, perhaps even all at once since or BOTH. - An indefinite number of telnet sessions are supported. -

-

- Start-Up prompt. - When NSH is started, you will see the a welcome message such the following on the selected console: - 

    -NuttShell (NSH)
-nsh>
-
- The greeting may also include NuttX versioning information if you are using a versioned copy of NuttX. - nsh> is the NSH prompt and indicates that you may enter a command from the console. -

-

- USB console startup. - When using a USB console, the start-up sequence differs a little: In this case, you are required to press ENTER three times. Then NSH prompt will appear as described above. - This is required for the following reasons: -

-
    -
  1. - This assures that the USB connection is stable. - The USB connection may be made, broken, and re-established a few times if the USB cable is not yet fully seated. - Waiting for ENTER to be pressed three times assures that the connection is stable. -
    2. -
  2. - The establishment of the connection is two step process: First, the USB serial connection is made with the host PC. Then the application that uses the serial interface is started on the host. - When the serial connection is established on the host, the host operating system may send several AT modem commands to the host depending upon how the host serial port is configured. - By waiting for ENTER to be pressed three consecutive times, all of these modem commands will go to the bit-bucket and will not be interpreted as NSH command input. -
    3. -
  3. - Similarly, in the second step when the applications is started, there may be additional AT modem commands sent out the serial port. - Most serial terminal programs will do this unless they are specifically configured to suppress the modem command output. - Waiting for the ENTER input eliminates the invalid command errors from both (2) and (3). -
    4. -
  4. - Finally, if NSH did not wait for some positive indication that the serial terminal program is up and running, then the output of the NSH greeting and initial NSH prompt would be lost. -
    5. -
- -

- Extended Command Line Editing. - By default, NuttX uses a simple command line editor that allows command entry after the nsh> and supports only the backspace key for editing. - However, a more complete command line editor can be selected by setting CONFIG_NSH_CLE=y in the NuttX configuration file. - When that option is selected, the following EMACS-like line editing commands are supported: -

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Key Binding - - Editor Action -
- ^A - - Move cursor to start of the line -
- ^B - - Move left one character -
- ^D or Del - - Delete a single character at the cursor position -
- ^E - - Move cursor to end of current line -
- ^F - - Move right one character -
- ^H or Backspace - - Delete character, left (backspace) -
- ^K - - Delete to the end of the line -
- ^U - - Delete the entire line -
- - - - - -
-

1.2 Command Overview

 -
- -

- Simple, Re-directed, and Background Commands. - The NuttShell (NSH) is a simple shell application. - NSH supports the following commands forms: -

-
    - - - - - - - - - - - - - - - - -
    Simple command:<cmd>
    Command with re-directed output: - <cmd> > <file>
    - <cmd> >> <file> -
    Background command:<cmd> &
    Re-directed background command: - <cmd> > <file> &
    - <cmd> >> <file> & -
-

Where:

-
    - - - - - - - - -
    <cmd> - is any one of the simple commands listed later. -
    <file> - is the full or relative path to any writable object - in the file system name space (file or character driver). - Such objects will be referred to simply as files throughout - this document. -
-

- nice'd Background Commands - NSH executes at the mid-priority (128). Backgrounded commands can - be made to execute at higher or lower priorities using nice: -

-
    - [nice [-d <niceness>>]] <cmd> [> <file>|>> <file>] [&] -
-

- Where <niceness> is any value between -20 and 19 where lower - (more negative values) correspond to higher priorities. - The default niceness is 10. -

- -

- Multiple commands per line. - NSH will accept multiple commands per command line with each command separated with the semi-colon character (;). -

- -

- Optional Syntax Extensions - Because these features commit significant resources, they are disabled by default. -

-
    -
  • -

    - CONFIG_NSH_CMDPARMS. - If selected, then the output from commands, from file applications, and from NSH built-in commands can be used as arguments to other commands. - The entity to be executed is identified by enclosing the command line in back quotes. - For example, -

    - 
      -set FOO `myprogram $BAR`
-
    -

    - Will execute the program named myprogram passing it the value of the environment variable BAR. - The value of the environment variable FOO is then set output of myprogram on stdout. -

    -
    • -
  • -

    - CONFIG_NSH_ARGCAT. - Support concatenation of strings with environment variables or command output. For example: -

    - 
      -set FOO XYZ
-set BAR 123
-set FOOBAR ABC_${FOO}_${BAR}
-
    -

    - would set the environment variable FOO to XYZ, BAR to 123 and FOOBAR to ABC_XYZ_123. - If CONFIG_NSH_ARGCAT is not selected, then a slightly smaller FLASH footprint results but then also only simple environment variables like $FOO can be used on the command line. -

    -
    • -
  • -

    - CONFIG_NSH_QUOTE. - Enables back-slash quoting of certain characters within the command. - This option is useful for the case where an NSH script is used to dynamically generate a new NSH script. - In that case, commands must be treated as simple text strings without interpretation of any special characters. - Special characters such as $, `, ", and others must be retained intact as part of the test string. - This option is currently only available is CONFIG_NSH_ARGCAT is also selected. -

    -
    • -
- - - - - -
-

1.3 Conditional Command Execution

 -
- -

- An if-then[-else]-fi construct is also supported in order to - support conditional execution of commands. This works from the - command line but is primarily intended for use within NSH scripts - (see the sh command). The syntax is as follows: -

-
    -if [!] <cmd>
-then
-  [sequence of <cmd>]
-else
-  [sequence of <cmd>]
-fi
-
- -

- Where <cmd> is a simple command. - The command success value of zero is treated true; a non-zero command failure value is treated false. - The test command is frequently used for comparisons. -

- - - - - -
-

1.4 Looping

 -
- -

Looping Constructs. - while-do-done and until-do-done looping constructs are also supported. - These work from the command line but are primarily intended for use within NSH scripts - (see the sh command). -

-
    -
  • -

    while-do-done. - Execute [sequence of <cmd>] as long as <cmd> has an exit status of zero. - The syntax is as follows: - 

      -while <cmd>
-do
-  [sequence of <cmd>]
-done
-
    -

    -
    • -
  • -

    until-do-done - Execute [sequence of <cmd>] as long as <cmd> has a non-zero exit status. - The syntax is as follows: - 

      -until <cmd>
-do
-  [sequence of <cmd>]
-done
-
    -

    -
    • -
- -

- Where <cmd> is a simple command. - The command success value of zero is treated true; a non-zero command failure value is treated false. - The test command is frequently used for comparisons. -

- -

The break Command. - A break command is also supported. - The break command is only meaningful within the body of the a while or until loop, between the do and done tokens. - If the break command is executed within the body of a loop, the loop will immediately terminate and execution will continue with the next command immediately following the done token. -

- - - - - -
-

1.5 Built-In Variables

 -
- -

    - - - - -
    $? - The result of the last simple command execution. - On backgrounded commands, this variable holds only the result of spawning the background command. -
- - - - - -
-

1.6 Current Working Directory

 -
- -

- cd and pwd. - All path arguments to commands may be either an absolute path or a - path relative to the current working directory. The current working - directory is set using the cd command and can be queried either - by using the pwd command or by - using the echo $PWD - command. -

- - - - - -
-

1.7 Environment Variables

 -
- -

- Environment Variables: -

-
    - - - - - - - - - -
    PATHThe default path in the file systems to look for executable, binary programs working directory
    PWDThe current working directory
    OLDPWDThe previous working directory
- - - - - -
-

1.8 NSH Start-Up Script

 -
- -

- NSH Start-Up Script. - NSH supports options to provide a start up script for NSH. In general - this capability is enabled with CONFIG_NSH_ROMFSETC, but has - several other related configuration options as described with the - NSH-specific configuration settings. - This capability also depends on: -

    -
  • CONFIG_DISABLE_MOUNTPOINT not set -
  • CONFIG_NFILE_DESCRIPTORS > 4 -
  • CONFIG_FS_ROMFS enabled -
-

- -

- Default Start-Up Behavior. - The implementation that is provided is intended to provide great flexibility - for the use of Start-Up files. This paragraph will discuss the general - behavior when all of the configuration options are set to the default - values. -

-

- In this default case, enabling CONFIG_NSH_ROMFSETC will cause - NSH to behave as follows at NSH startup time: -

    -
  • - NSH will create a read-only RAM disk (a ROM disk), containing a tiny - ROMFS file system containing the following: -
      -`--init.d/
-     `-- rcS
-
    - Where rcS is the NSH start-up script. -
    • -
  • - NSH will then mount the ROMFS file system at /etc, resulting in: -
      -|--dev/
-|   `-- ram0
-`--etc/
-    `--init.d/
-        `-- rcS
-
    -
    • -
  • - By default, the contents of rcS script are: -
      -# Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX
-
-mkrd -m 1 -s 512 1024
-mkfatfs /dev/ram1
-mount -t vfat /dev/ram1 /tmp
-
    -
    • -
  • - NSH will execute the script at /etc/init.d/rcS at start-up (before the - first NSH prompt). After execution of the script, the root FS will look - like: -
      -|--dev/
-|   |-- ram0
-|   `-- ram1
-|--etc/
-|   `--init.d/
-|       `-- rcS
-`--tmp/
-
    -
    • -
-

-

- Modifying the ROMFS Image. - The contents of the /etc directory are retained in the file apps/nshlib/nsh_romfsimg.h OR, if CONFIG_NSH_ARCHROMFS is defined, include/arch/board/rcs.template). - In order to modify the start-up behavior, there are three things to study: -

    -
  1. - Configuration Options. - The additional CONFIG_NSH_ROMFSETC configuration options - discussed with the other NSH-specific configuration settings. -
    2. -
  2. -

    - tools/mkromfsimg.sh Script. - The script tools/mkromfsimg.sh creates nsh_romfsimg.h. - It is not automatically executed. If you want to change the - configuration settings associated with creating and mounting - the /tmp directory, then it will be necessary to re-generate - this header file using the tools/mkromfsimg.sh script. -

    -

    - The behavior of this script depends upon three things: -

      -
    • The configuration settings then installed configuration. -
    • The genromfs tool (available from http://romfs.sourceforge.net). -
    • The file apps/nshlib/rcS.template - (OR, if CONFIG_NSH_ARCHROMFS is defined include/arch/board/rcs.template. -
    -

    -
    3. -
  3. - rcS.template. - The file apps/nshlib/rcS.template contains the general form - of the rcS file; configured values are plugged into this - template file to produce the final rcS file. -
    4. -
-

-

- NOTE: - apps/nshlib/rcS.template generates the standard, default nsh_romfsimg.h file. - If CONFIG_NSH_ARCHROMFS is defined in the NuttX configuration file, then a custom, board-specific nsh_romfsimg.h file residing in the boards/<arch>/<chip>/<board>/include directory will be used. - NOTE when the OS is configured, include/arch/board will be linked to boards/<arch>/<chip>/<board>/include. -

-

- All of the startup-behavior is contained in rcS.template. The - role of mkromfsimg.sh is to (1) apply the specific configuration - settings to rcS.template to create the final rcS, and (2) to - generate the header file nsh_romfsimg.h containing the ROMFS - file system image. -

- -

- Further Information. - See the section on Customizing the NuttShell for additional, more detailed information about the NSH start-up script and how to modify it. -

- - - - - -
-

2.0 Commands

 -
- - - - - -
-

2.1 Evaluate Expression (test)

 -
- -

Command Syntax:

-
    -[ <expression> ]
-test <expression>
-
-

- Synopsis. - These are two alternative forms of the same command. They support - evaluation of a boolean expression which sets $?. - This command is used most frequently as the conditional command following the - if in the if-then[-else]-fi construct. -

-

Expression Syntax:

-
    -

    - expression = simple-expression | !expression | expression -o expression | expression -a expression -

    -

    - simple-expression = unary-expression | binary-expression -

    -

    - unary-expression = string-unary | file-unary -

    -

    - string-unary = -n string | -z string -

    -

    - file-unary = -b file | -c file | -d file | -e file | -f file | -r file | -s file | -w file -

    -

    - binary-expression = string-binary | numeric-binary -

    -

    - string-binary = string = string | string == string | string != string -

    -

    - numeric-binary = integer -eq integer | integer -ge integer | integer -gt integer | integer -le integer | - integer -lt integer | integer -ne integer -

    -
- - - - - -
-

2.2 Add a Routing Table Entry (addroute)

 -
- -

Command Syntax:

-
    -addroute <target> [<netmask>] <router>
-addroute default <ipaddr> <interface>
-
-

- Synopsis. - This command adds an entry in the routing table. - The new entry will map the IP address of a router on a local network (<router>) to an external network characterized by the <target> IP address and a network mask <netmask> -

-

- The netmask may also be expressed using IPv4 CIDR or IPv6 slash notation. - In that case, the netmask need not be provided. -

-

- Example: -

-
    -nsh> addroute addroute 11.0.0.0 255.255.255.0 10.0.0.2
-
-

- which is equivalent to -

-
    -nsh> addroute 11.0.0.0/24 10.0.0.2
-
-

- The second form of the addroute command can be used to set the default gateway. -

- - - - - -
-

2.3 Access the ARP table (arp)

 -
- -

Command Syntax:

-
    -arp [-t|-a <ipaddr> |-d <ipaddr> |-s <ipaddr> <hwaddr>]
-
-

- Synopsis. - Access the OS ARP table. -

-
    -
    -a <ipaddr> -
    Will show the hardware address that the IP address <ipaddr> is mapped to. - -
    -d <ipaddr> -
    Will delete the mapping for the IP address <ipaddr> from the ARP table. - -
    -s <ipaddr> <hwaddr> -
    Will set (or replace) the mapping of the IP address <ipaddr> to the hardware address <hwaddr>. - -
    -t -
    Will dump the entire content of the ARP table. This option is only available if CONFIG_NETLINK_ROUTE is enabled. -
-

- Example: -

-
    -nsh> arp -a 10.0.0.1
-nsh: arp: no such ARP entry: 10.0.0.1
-
-nsh> arp -s 10.0.0.1 00:13:3b:12:73:e6
-nsh> arp -a 10.0.0.1
-HWAddr: 00:13:3b:12:73:e6
-
-nsh> arp -d 10.0.0.1
-nsh> arp -a 10.0.0.1
-nsh: arp: no such ARP entry: 10.0.0.1
-
- - - - - -
-

2.4 Base64 Decode (base64dec)

 -
- -

Command Syntax:

-
    -base64dec [-w] [-f] <string or filepath>
-
-

- Synopsis. - To be provided. -

- - - - - -
-

2.5 Base64 Encode (base64enc)

 -
- -

Command Syntax:

-
    -base64enc [-w] [-f] <string or filepath>
-
-

- Synopsis. - To be provided. -

- - - - - -
-

2.6 Extract Base File/Directory Name (basename)

 -
-

Command Syntax:

-
    -basename <path> [<suffix>]
-
-

- Synopsis. - Extract the final string from a <path> by removing the preceding path - segments and (optionally) removing any trailing <suffix>. -

- - - - - -
-

2.7 Terminate a Loop (break)

 -
- -

Command Syntax:

-
    -break
-
-

- Synopsis. - The break command is only meaningful within the body of the a while or until loop, between the do and done tokens. - Outside of a loop, break command does nothing. - If the break command is executed within the body of a loop, the loop will immediately terminate and execution will continue with the next command immediately following the done token. -

- - - - - -
-

2.8 Concatenate Files (cat)

 -
- -

Command Syntax:

-
    -cat <path> [<path> [<path> ...]]
-
-

- Synopsis. - This command copies and concatenates all of the files at <path> - to the console (or to another file if the output is redirected). -

- - - - - -
-

2.9 Change Current Working Directory (cd)

 -
- -

Command Syntax:

-
    -cd [<dir-path>|-|~|..]
-
-

- Synopsis. - Changes the current working directory (PWD). Also sets the - previous working directory environment variable (OLDPWD). -

-

Forms:

-
    - - - - - - - - - - - - - - - - -
    cd <dir-path>sets the current working directory to <dir-path>.
    cd -sets the current working directory to the previous - working directory ($OLDPWD). - Equivalent to cd $OLDPWD.
    cd or cd ~set the current working directory to the 'home' - directory. The home directory can be configured by setting - CONFIG_LIB_HOMEDIR in the configuration file. The default - home directory is /.
    cd ..sets the current working directory to the parent directory.
- - - - - -
-

2.10 Compare Files (cmp)

 -
- -

Command Syntax:

-
    -cmp <path1> <path2>
-
-

- Synopsis. - Compare of the contents of the file at <path1> with the contents of the file at <path2>. Returns an indication only if the files differ. -

- - - - - -
-

2.11 Copy Files (cp)

 -
- -

Command Syntax:

-
    -cp <source-path> <dest-path>
-
-

- Synopsis. - Copy of the contents of the file at <source-path> to the location - in the file system indicated by <dest-path>. -

- - - - - -
-

2.12 Show or set the date and time (date)

 -
-

Command Syntax:

-
    -date [-s "MMM DD HH:MM:SS YYYY"]
-
-

- Synopsis. - Show or set the current date and time. -

-

- Only one format is used both on display and when setting the date/time: - MMM DD HH:MM:SS YYYY. For example, -

    -date -s "Sep 1 11:30:00 2011"
-
-

-

- 24-hour time is used. -

- - - - - -
-

2.13 Copy and Convert Files (dd)

 -
-

Command Syntax:

-
    -dd if=<infile> of=<outfile> [bs=<sectsize>] [count=<sectors>] [skip=<sectors>]
-
-

- Synopsis. - Copy blocks from <infile> to <outfile>. - <infile> or <outfile> may be the path to a standard file, a character device, or a block device. - Examples follow: -

-
    -
  1. - Read from character device, write to regular file. - This will create a new file of the specified size filled with zero. -
      -nsh> ls -l /dev
-/dev:
- crw-rw-rw-       0 zero
-nsh> dd if=/dev/zero of=/tmp/zeros bs=64 count=16
-nsh> ls -l /tmp
-/tmp:
- -rw-rw-rw-    1024 ZEROS
-
    -
    2. -
  2. - Read from character device, write to block device. - This will fill the entire block device with zeros. -
    3. -
      -nsh> ls -l /dev
-/dev:
- brw-rw-rw-       0 ram0
- crw-rw-rw-       0 zero
-nsh> dd if=/dev/zero of=/dev/ram0
-
    - -
  3. - Read from a block device, write to a character device. This - will read the entire block device and dump the contents in - the bit bucket. -
    4. -
      -nsh> ls -l /dev
-/dev:
- crw-rw-rw-       0 null
- brw-rw-rw-       0 ram0
-nsh> dd if=/dev/ram0 of=/dev/null
-
    - -
- - - - - -
-

2.14 Delete a Routing Table Entry (delroute)

 -
- -

Command Syntax:

-
    -delroute <target> [<netmask>]
-
-

- Synopsis. - The entry removed will be the first entry in the routing table that matches - the external network characterized by the <target> IP address and the network mask <netmask> -

-

- The netmask may also be expressed using IPv4 CIDR or IPv6 slash - notation. In that case, the netmask need not be provided. -

-

- Example: -

-
    -nsh> delroute 11.0.0.0 255.255.255.0
-
-

- which is equivalent to -

-
    -nsh> delroute 11.0.0.0/24
-
- - - - - -
-

2.15 Show Volume Status (df)

 -
- -

Command Syntax:

-
    -df [-h]
-
-

- Synopsis. - Show the state of each mounted volume. - As an example: -

-
    -nsh> mount
-  /etc type romfs
-  /tmp type vfat
-nsh> df
-  Block  Number
-  Size   Blocks     Used Available Mounted on
-    64        6        6         0 /etc
-   512      985        2       983 /tmp
-nsh>
-
-

- If CONFIG_NSH_CMDOPT_DF_H is defined in the NuttX configuration, then the df will also support an option -h which may be used to show the volume information in human readable format. -

- - - - - -
-

2.16 Extract Path to a File/Directory (dirname)

 -
-

Command Syntax:

-
    -dirname <path>
-
-

- Synopsis. - Extract the path string leading up to the full <path> by removing - the final directory or file name. -

- - - - - - -
-

2.17 Dump Buffered SYSLOG Output (dmesg)

 -
- -

Command Syntax:

-
    -dmesg
-
-

- Synopsis. - This command can be used to dump (and clear) the content of any buffered syslog output messages. - This command is only available if CONFIG_RAMLOG_SYSLOG is enabled. - In that case, syslog output will be collected in an in-memory, circular buffer. - Entering the dmesg command will dump the content of that in-memory, circular buffer to the NSH console output. - dmesg has the side effect of clearing the buffered data so that entering dmesg again will show only newly buffered data. -

- - - - - -
-

2.18 Echo Strings and Variables (echo)

 -
- -

Command Syntax:

-
    -echo [-n] [<string|$name> [<string|$name>...]]
-
-

- Synopsis. - Copy the sequence of strings and expanded environment variables to - console output (or to a file if the output is re-directed). -

-

- The -n option suppresses the trailing newline character. -

- - - - - -
-

2.19 Show Environment Variables (env)

 -
- -

Command Syntax:

-
    -env
-
-

- Synopsis. - Show the current name-value pairs in the environment. Example:. -

-
    -nsh> env
-PATH=/bin
-
-nsh> set foo bar
-nsh> env
-PATH=/bin
-foo=bar
-
-nsh> unset PATH
-nsh> env
-foo=bar
-
-nsh>
-
-

- NOTE: NSH local variables are not shown by the env command. -

- - - - - -
-

2.20 Execute User Code (exec)

 -
- -

Command Syntax:

-
    -exec <hex-address>
-
-

- Synopsis. - Execute the user logic at address <hex-address>. NSH will pause - until the execution unless the user logic is executed in background - via exec <hex-address> &. -

- - - - - -
-

2.21 Exit NSH (exit)

 -
- -

Command Syntax:

-
    -exit
-
-

- Synopsis. - Exit NSH. Only useful for the serial front end if you have started some other tasks (perhaps - using the exec command) and you would like to have NSH out of the - way. For the telnet front-end, exit terminates the telnet session. -

- - - - - -
-

2.22 Set an Environment Variable (export)

 -
- -

Command Syntax:

-
    -export <name> [<value>]
-
-

- Synopsis. - The export command sets an environment variable, or promotes an NSH variable to an environment variable. As examples: -

-
    -
  1. -

    - Using export to promote an NSH variable to an environment variable. -

    - 
      -nsh> env
-PATH=/bin
-
-nsh> set foo bar
-nsh> env
-PATH=/bin
-
-nsh> export foo
-nsh> env
-PATH=/bin
-foo=bar
-
    -

    - A group-wide environment variable is created with the same value as the local NSH variable; the local NSH variable is removed. -

    -
    - NOTE: This behavior differs from the Bash shell. - Bash would retain the local Bash variable which will shadow the environment variable of the same name and same value. -
    -
    2. -
  2. -

    - Using export to set an environment variable -

    - 
      -nsh> export dog poop
-nsh> env
-PATH=/bin
-foo=bar
-dog=poop
-
    -
    3. -
-

- The export command is not supported by NSH unless both CONFIG_NSH_VARS=y and CONFIG_DISABLE_ENVIRONis not set. -

- - - - - -
-

2.23 Show Memory Manager Status (free)

 -
- -

Command Syntax:

-
    -free
-
-

- Synopsis. - Show the current state of the memory allocator. For example, -

-
    -nsh> free
-             total       used       free    largest
-Mem:       4194288    1591552    2602736    2601584
-nsh>
-
-

Where:

-
    - - - - - - - - - - - - - - - - -
    totalThis is the total size of memory allocated for use by malloc in bytes.
    usedThis is the total size of memory occupied by chunks handed out by malloc.
    freeThis is the total size of memory occupied by free (not in use) chunks.
    largestSize of the largest free (not in use) chunk.
- - - - - -
-

2.24 Get File Via TFTP (get)

 -
- -

Command Syntax:

-
    -get [-b|-n] [-f <local-path>] -h <ip-address> <remote-path>
-
-

- Synopsis. - Copy the file at <remote-address> from the host whose IP address is - identified by <ip-address>. -

-

Other options:

-
    - - - - - - - - -
    -f <local-path> - The file will be saved relative to the current working directory - unless <local-path> is provided. -
    -b|-n - Selects either binary ("octet") or text ("netascii") transfer - mode. Default: text. -
- - - - - -
-

2.25 Show Usage Command Usage (help)

 -
- -

Command Syntax:

-
    -help [-v] [<cmd>]
-
-

- Synopsis. - Presents summary information about NSH commands to console. -

-

Options:

-
    - - - - - - - - -
    -v - how verbose output will full command usage. -
    <cmd> - Show full command usage only for this command. -
- - - - - -
-

2.26 Hexadecimal Dump of File or Device (hexdump)

 -
- -

Command Syntax:

-
    -hexdump <file or device> [skip=<bytes>] [count=<bytes>]
-
-

- Synopsis. - Dump data in hexadecimal format from a file or character device. -

-
    - - - - - - -
    skip=<bytes>Will skip <bytes> number of bytes from the beginning. -
    count=<bytes>Will stop after dumping <bytes> number of bytes. -
-

-The skip and count options are only available if CONFIG_NSH_CMDOPT_HEXDUMP is defined in the NuttX configuration. -

- - - - - -
-

2.27 Manage Network Configuration (ifconfig)

 -
- -

Command Syntax:

-
    -ifconfig [nic_name [<ip-address>|dhcp]] [dr|gw|gateway <dr-address>] [netmask <net-mask>] [dns <dns-address>] [hw <hw-mac>]]
-
-

- Synopsis. - Multiple forms of the ifconfig command are supported: -

-
    -
  1. -

    - With one or no arguments, ifconfig will shows the - current configuration of the network and, perhaps, the status of Ethernet - device: -

    - 
      -ifconfig
-ifconfig [nic_name]
-
    -

    - As an example: -

    - 
      -nsh> ifconfig
-eth0    HWaddr 00:18:11:80:10:06
-        IPaddr:10.0.0.2 DRaddr:10.0.0.1 Mask:255.255.255.0
-
    -

    - If network statistics are enabled (CONFIG_NET_STATISTICS), then - this command will also show the detailed state of network. -

    -
    2. -
  2. -

    - If both the network interface name and an IP address are supplied as arguments, - then ifconfig will set the address of the Ethernet device: -

    - 
      -ifconfig nic_name ip_address
-
    -
    3. -
  3. - Other forms to be provided -
    4. -
-

-NOTE: This commands depends upon having the procfs file system configured into the system. -The procfs file system must also have been mounted with a command like: -

-
    -nsh> mount -t procfs /proc
-
-

- - - - - -
-

2.28 Take a network down (ifdown)

 -
- -

Command Syntax:

-
    -ifdown <interface>
-
-

- Synopsis. - Take down the interface identified by the name <interface>. -

-

- Example: -

-
    -ifdown eth0
-
- - - - - -
-

2.29 Bring a network up (ifup)

 -
- -

Command Syntax:

-
    -ifup <interface>
-
-

- Synopsis. - Bring up down the interface identified by the name <interface>. -

-

- Example: -

-
    -ifup eth0
-
- - - - - -
-

2.30 Install an OS module (insmod)

 -
- -

Command Syntax:

-
    -insmod <file-path> <module-name>
-
-

- Synopsis. - Install the loadable OS module at <file-path> as module <module-name>. -

-

Example:

-
    -nsh> ls -l /mnt/romfs
-/mnt/romfs:
- dr-xr-xr-x       0 .
- -r-xr-xr-x    9153 chardev
-nsh> ls -l /dev
-/dev:
- crw-rw-rw-       0 console
- crw-rw-rw-       0 null
- brw-rw-rw-       0 ram0
- crw-rw-rw-       0 ttyS0
-nsh> lsmod
-NAME                 INIT   UNINIT      ARG     TEXT     SIZE     DATA     SIZE
-nsh> insmod /mnt/romfs/chardev mydriver
-nsh> ls -l /dev
-/dev:
- crw-rw-rw-       0 chardev
- crw-rw-rw-       0 console
- crw-rw-rw-       0 null
- brw-rw-rw-       0 ram0
- crw-rw-rw-       0 ttyS0
-nsh> lsmod
-NAME                 INIT   UNINIT      ARG     TEXT     SIZE     DATA     SIZE
-mydriver         20404659 20404625        0 20404580      552 204047a8        0
-
- - - - - -
-

2.31 Show Interrupt Status (irqinfo)

 -
- -

Command Syntax:

-
    -irqinfo
-
-

- Synopsis. - Show the current count of interrupts taken on all attached interrupts. -

-

- Example:. -

-
    -nsh> irqinfo
-IRQ HANDLER  ARGUMENT    COUNT    RATE
-  3 00001b3d 00000000        156   19.122
- 15 0000800d 00000000        817  100.000
- 30 00000fd5 20000018         20    2.490
-
- - - - - -
-

2.32 Send a signal to a task (kill)

 -
- -

Command Syntax:

-
    -kill -<signal> <pid>
-
-

- Synopsis. - Send the <signal> to the task identified by <pid>. -

-

Example:

-
    -nsh> mkfifo /dev/fifo
-nsh> cat /dev/fifo &
-cat [2:128]
-nsh> ps
-PID PRI POLICY   TYPE    NPX STATE    EVENT     SIGMASK  COMMAND
-  0   0 FIFO     Kthread --- Ready              00000000 Idle Task
-  1 128 RR       Task    --- Running            00000000 init
-  2 128 FIFO     pthread --- Waiting  Semaphore 00000000 <pthread>(51ea50)
-nsh> kill -9 2
-nsh> ps
-PID PRI POLICY   TYPE    NPX STATE    EVENT     SIGMASK  COMMAND
-  0   0 FIFO     Kthread --- Ready              00000000 Idle Task
-  1 128 RR       Task    --- Running            00000000 init
-nsh>
-
-

- NOTE: - NuttX does not support a FULL POSIX signaling system. - A few standard signal names like SIGCHLD, SIGUSR1, SIGUSR2, SIGALRM, and SIGPOLL exist in the system. - However, they do not have the default actions that you might expect. - Rather, NuttX supports only what are referred to as POSIX real-time signals. - These signals may be used to communicate with running tasks, may be use to waiting waiting tasks, etc. -

-

- If the configuration option CONFIG_SIG_DEFAULT is enabled, then default actions for the SIGINT and SIGKILL signals (only) will be supported. - In that case, as an example, kill -9 (SIGKILL) will, indeed, terminate a task. - Caution should be exercised, however, because this is likely to cause memory leaks and to strand resource since there is insufficient clean-up in certain build configurations. -

 - - - - - -
-

2.33 Setup/teardown the Loop Device (losetup)

 -
- -

Command Syntax 1:

-
    -losetup [-o <offset>] [-r] <dev-path> <file-path>
-
-

- Synopsis. - Setup the loop device at <dev-path> to access the file at <file-path> as a block device. - In the following example a 256K file is created (dd) and losetup is - used to make the file accessible as a block device. - A FAT file system is created (mkfatfs) and mounted (mount). - Files can then be managed on the loop-mounted file. -

    -nsh> dd if=/dev/zero of=/tmp/image bs=512 count=512
-nsh> ls -l /tmp
-/tmp:
- -rw-rw-rw-   262144 IMAGE
-nsh> losetup /dev/loop0 /tmp/image
-nsh> ls -l /dev
-/dev:
- brw-rw-rw-       0 loop0
-nsh> mkfatfs /dev/loop0
-nsh> mount -t vfat /dev/loop0 /mnt/example
-nsh> ls -l /mnt
-ls -l /mnt
-/mnt:
- drw-rw-rw-       0 example/
-nsh> echo "This is a test" >/mnt/example/atest.txt
-nsh> ls -l /mnt/example
-/mnt/example:
- -rw-rw-rw-      16 ATEST.TXT
-nsh> cat /mnt/example/atest.txt
-This is a test
-nsh>
-
-

- -

Command Syntax 2:

-
    -losetup d <dev-path>
-
-

- Synopsis. - Teardown the setup for the loop device at <dev-path>. -

- - - - - -
-

2.34 Link to a File or Directory (ln)

 -
- -

Command Syntax:

-
    -ln [-s] <target> <link>
-
-

- Synopsis. - The ln command will create a new symbolic link at <link> for the existing file or directory, <target>. - This implementation is simplified for use with NuttX in these ways: -

-
    -
  • Links may be created only within the NuttX top-level, pseudo file system. - No file system currently supported by NuttX provides symbolic links.
    • -
  • For the same reason, only soft links are implemented.
    • -
  • File privileges are ignored.
    • -
  • c_time is not updated.
    • -
- - - - - -
-

2.35 List Directory Contents (ls)

 -
- -

Command Syntax:

-
    -ls [-lRs] <dir-path>
-
-

- Synopsis. - Show the contents of the directory at <dir-path>. NOTE: - <dir-path> must refer to a directory and no other file system - object. -

-

Options:

-
    - - - - - - - - - - - - -
    -RShow the contents of specified directory and all of its - sub-directories.
    -sShow the size of the files along with the filenames in the - listing
    -lShow size and mode information along with the filenames - in the listing.
- - - - - - -
-

2.36 Show information about installed OS modules (lsmod)

 -
- -

Command Syntax:

-
    -lsmod
-
-

- Synopsis. - Show information about the currently installed OS modules. This information includes: -

-
    -
  • The module name assigned to the module when it was installed (NAME, string).
    • -
  • The address of the module initialization function (INIT, hexadecimal).
    • -
  • The address of the module un-initialization function (UNINIT, hexadecimal).
    • -
  • An argument that will be passed to the module un-initialization function (ARG, hexadecimal).
    • -
  • The start of the .text memory region (TEXT, hexadecimal).
    • -
  • The size of the .text memory region size (SIZE, decimal).
    • -
  • The start of the .bss/.data memory region (DATA, hexadecimal).
    • -
  • The size of the .bss/.data memory region size (SIZE, decimal).
    • -
-

Example:

-
    -nsh> lsmod
-NAME                 INIT   UNINIT      ARG     TEXT     SIZE     DATA     SIZE
-mydriver         20404659 20404625        0 20404580      552 204047a8        0
-
- - - - - -
-

2.37 Calculate MD5 (md5)

 -
- -

Command Syntax:

-
    -md5 [-f] <string or filepath>
-
-

- Synopsis. - To be provided. -

- - - - - -
-

2.38 Access Memory (mb, mh, and mw)

 -
- -

Command Syntax:

-
    -mb <hex-address>[=<hex-value>][ <hex-byte-count>]
-mh <hex-address>[=<hex-value>][ <hex-byte-count>]
-mw <hex-address>[=<hex-value>][ <hex-byte-count>]
-
-

- Synopsis. - Access memory using byte size access (mb), 16-bit accesses (mh), - or 32-bit access (mw). In each case, -

-
    - - - - - - - - - -
    <hex-address>Specifies the address to be accessed. The current - value at that address will always be read and displayed. -
    <hex-address>=<hex-value>Read the value, then write <hex-value> - to the location. -
    <hex-byte-count>Perform the mb, mh, or mw operation on a total - of <hex-byte-count> bytes, increment the <hex-address> appropriately after each access. -
-

Example:

-

    -nsh> mh 0 16
-  0 = 0x0c1e
-  2 = 0x0100
-  4 = 0x0c1e
-  6 = 0x0110
-  8 = 0x0c1e
-  a = 0x0120
-  c = 0x0c1e
-  e = 0x0130
-  10 = 0x0c1e
-  12 = 0x0140
-  14 = 0x0c1e
-nsh>
-
- - - - - -
-

2.39 Show Current Tasks and Threads (ps)

 -
- -

Command Syntax:

-
    -ps
-
-

- Synopsis. - Show the currently active threads and tasks. For example, -

-
    -nsh> ps
-PID PRI POLICY   TYPE    NPX STATE    EVENT     SIGMASK  COMMAND
-  0   0 FIFO     Kthread --- Ready              00000000 Idle Task
-  1 128 RR       Task    --- Running            00000000 init
-  2 128 FIFO     Task    --- Waiting  Semaphore 00000000 nsh_telnetmain()
-  3 100 RR       pthread --- Waiting  Semaphore 00000000 <pthread>(21)
-nsh>
-
-

-NOTE: This commands depends upon having the procfs file system configured into the system. -The procfs file system must also have been mounted with a command like: -

-
    -nsh> mount -t procfs /proc
-
-

- - - - - -
-

2.40 Create a Directory (mkdir)

 -
- -

Command Syntax:

-
    -mkdir <path>
-
-

- Synopsis. - Create the directory at <path>. - All components of <path> except the final directory name must exist on a mounted file - system; the final directory must not. -

-

- Limited to Mounted File Systems. - Recall that NuttX uses a pseudo file system for its root file - system. - The mkdir command can only be used to create directories in volumes set up with the - mount command; it cannot be used to create directories in the pseudo file system. -

-

Example:

-
    -nsh> mkdir /mnt/fs/tmp
-nsh> ls -l /mnt/fs
-/mnt/fs:
- drw-rw-rw-       0 TESTDIR/
- drw-rw-rw-       0 TMP/
-nsh>
-
- - - - - -
-

2.41 Create a FAT File System (mkfatfs)

 -
- -

Command Syntax:

-
    -mkfatfs [-F <fatsize>] [-r <rootdirentries>] <block-driver>
-
-

- Synopsis. - Format a fat file system on the block device specified by <block-driver> path. - The FAT size may be provided as an option. - Without the <fatsize> option, mkfatfs will select either the FAT12 or FAT16 format. - For historical reasons, if you want the FAT32 format, it must be explicitly specified on the command line. -

-

- The -r option may be specified to select the the number of entries in the root directory for FAT12 and FAT16 file systems. - Typical values for small volumes would be 112 or 224; 512 should be used for large volumes, such as hard disks or very large SD cards. The default is 512 entries in all cases. -

-

- The reported number of root directory entries used with FAT32 is zero because the FAT32 root directory is a cluster chain. -

-

- NSH provides this command to access the mkfatfs() NuttX API. - This block device must reside in the NuttX pseudo file system and - must have been created by some call to register_blockdriver() (see include/nuttx/fs/fs.h). -

- - - - - -
-

2.42 Create a FIFO (mkfifo)

 -
- -

Command Syntax:

-
    -mkfifo <path>
-
-

- Synopsis. - Creates a FIFO character device anywhere in the pseudo file system, creating - whatever pseudo directories that may be needed to complete the <path>. - By convention, however, device drivers are place in the standard /dev directory. - After it is created, the FIFO device may be used as any other device driver. - NSH provides this command to access the mkfifo() NuttX API. -

-

Example

-
    -nsh> ls -l /dev
-/dev:
- crw-rw-rw-       0 console
- crw-rw-rw-       0 null
- brw-rw-rw-       0 ram0
-nsh> mkfifo /dev/fifo
-nsh> ls -l /dev
-ls -l /dev
-/dev:
- crw-rw-rw-       0 console
- crw-rw-rw-       0 fifo
- crw-rw-rw-       0 null
- brw-rw-rw-       0 ram0
-nsh>
-
- - - - - -
-

2.43 Create a RAMDISK (mkrd)

 -
- -

Command Syntax:

-
    -mkrd [-m <minor>] [-s <sector-size>] <nsectors>
-
-

- Synopsis. - Create a ramdisk consisting of <nsectors>, each of size - <sector-size> (or 512 bytes if <sector-size> is not specified. - The ramdisk will be registered as /dev/ram<minor>. If <minor> is not - specified, mkrd will attempt to register the ramdisk as /dev/ram0. -

-

Example

-
    -nsh> ls /dev
-/dev:
- console
- null
- ttyS0
- ttyS1
-nsh> mkrd 1024
-nsh> ls /dev
-/dev:
- console
- null
- ram0
- ttyS0
- ttyS1
-nsh>
-
-

- Once the ramdisk has been created, it may be formatted using - the mkfatfs command and mounted using the mount command. -

-

Example

-
    -nsh> mkrd 1024
-nsh> mkfatfs /dev/ram0
-nsh> mount -t vfat /dev/ram0 /tmp
-nsh> ls /tmp
-/tmp:
-nsh>
-
- - - - - -
-

2.44 Mount a File System (mount)

 -
- -

Command Syntax:

-
    -mount -t <fstype> [-o <options>] <block-device> <dir-path>
-
-

- Synopsis. - The mount command performs one of two different operations. - If no parameters are provided on the command line after the mount command, then the mount command will enumerate all of the current mountpoints on the console. -

-

- If the mount parameters are provided on the command after the mount command, then the mount command will mount a file system in the NuttX pseudo-file system. - mount performs a three way association, binding: -

-
    -
  1. File System. - The '-t <fstype>' option identifies the type of - file system that has been formatted on the <block-device>. - As of this writing, vfat is the only supported value for <fstype> -
    2. -
  2. Block Device. - The <block-device> argument is the full or relative - path to a block driver inode in the pseudo file system. - By convention, this is a name under the /dev sub-directory. - This <block-device> must have been previously formatted with the same file system - type as specified by <fstype> -
    3. -
  3. Mount Point. - The mount point, <dir-path>, is the location in the - pseudo file system where the mounted volume will appear. - This mount point can only reside in the NuttX pseudo file system. - By convention, this mount point is a subdirectory under /mnt. - The mount command will create whatever pseudo directories that may be needed to complete the - full path but the full path must not already exist. -
    4. -
-

- After the volume has been mounted in the NuttX - pseudo file system, - it may be access in the same way as other objects in the file system. -

-

Examples:

-

Using mount to mount a file system:

-
    -nsh> ls -l /dev
-/dev:
- crw-rw-rw-       0 console
- crw-rw-rw-       0 null
- brw-rw-rw-       0 ram0
-nsh> ls /mnt
-nsh: ls: no such directory: /mnt
-nsh> mount -t vfat /dev/ram0 /mnt/fs
-nsh> ls -l /mnt/fs/testdir
-/mnt/fs/testdir:
- -rw-rw-rw-      15 TESTFILE.TXT
-nsh> echo "This is a test" >/mnt/fs/testdir/example.txt
-nsh> ls -l /mnt/fs/testdir
-/mnt/fs/testdir:
--rw-rw-rw-      15 TESTFILE.TXT
- -rw-rw-rw-      16 EXAMPLE.TXT
-nsh> cat /mnt/fs/testdir/example.txt
-This is a test
-nsh>
-
-

Using mount to enumerate mounts:

-
    -nsh> mount
-  /etc type romfs
-  /mnt/fs type vfat
-  /tmp type vfat
-
- - - - - -
-

2.45 Rename a File (mv)

 -
- -

Command Syntax:

-
    -mv <old-path> <new-path>
-
-

- Synopsis. - Rename the file object at <old-path> to <new-path>. - Both paths must reside in the same mounted file system. -

- - - - - -
-

2.46 Mount an NFS file system (nfsmount)

 -
- - -

Command Syntax:

-
    -nfsmount <server-address> <mount-point> <remote-path>
-
-

- Synopsis. - Mount the remote NFS server directory<remote-path> at <mount-point> on the target machine. - <server-address> is the IP address of the remote server. -

- - - - - -
-

2.47 Lookup a network address (nslookup)

 -
- -

Command Syntax:

-
    -nslookup <host-name>
-
-

- Synopsis. - Lookup and print the IP address associated with <host-name>. -

- - - - - -
-

2.48 Change a User's Password (passwd)

 -
- -

Command Syntax:

-
    -passwd <username> <password>
-
-

- Synopsis. - Set the password for the existing user <username> to <password>. -

- - - - - -
-

2.49 Manage Power Management Subsystem (pmconfig)

 -
- -

Command Syntax:

-
    -pmconfig [stay|relax] [normal|idle|standby|sleep]
-
-

- Synopsis. - Control power management subsystem. -

- - - - - -
-

2.50 Shut the system down (poweroff)

 -
- -

Command Syntax:

-
    -poweroff [<n>]
-
-

- Synopsis. - Shutdown and power off the system immediately. - This command depends on board-specific hardware support to power down the system. - The optional,decimal numeric argument may be included to provide power off - mode to board-specific power off logic. -

-

- NOTE: Supporting both the poweroff and shutdown commands is redundant. -

- - - - - - -
-

2.51 Send File Via TFTP (put)

 -
- -

Command Syntax:

-
    -put [-b|-n] [-f <remote-path>] -h <ip-address> <local-path>
-
-

- Synopsis. - Copy the file at <local-address> to the host whose IP address is - identified by <ip-address>. -

-

Other options:

-
    - - - - - - - - -
    -f <remote-path> - The file will be saved relative with the same name on the host - unless <remote-path> is provided. -
    -b|-n - Selects either binary ("octet") or text ("netascii") transfer - mode. Default: text. -
- - - - - -
-

2.52 Show Current Working Directory (pwd)

 -
- -

Command Syntax:

-
    -pwd
-
-

- Synopsis. - Show the current working directory. -

-
    -nsh> cd /dev
-nsh> pwd
-/dev
-nsh>
-
- -

Same as echo $PWD.

-
    -nsh> echo $PWD
-/dev
-nsh>
-
- - - - - -
-

2.53 Show target of a link (readlink)

 -
- -

Command Syntax:

-
    -readlink <link>
-
-

- Synopsis. - Show the target of the soft link at the path <link>. -

- - - - - -
-

2.54 Reboot the system (reboot)

 -
- -

Command Syntax:

-
    -reboot [<n>]
-
-

- Synopsis. - Reset and reboot the system immediately. - This command depends on hardware support to reset the system. - The optional, decimal numeric argument <n> may be included to provide a reboot mode to board-specific reboot logic. -

-

- NOTE: Supporting both the reboot and shutdown commands is redundant. -

- - - - - -
-

2.55 Remove a File (rm)

 -
- -

Command Syntax:

-
    -rm <file-path>
-
-

- Synopsis. - Remove the specified <file-path> name from the mounted file system. - Recall that NuttX uses a pseudo file system for its root file - system. - The rm command can only be used to remove (unlink) files in volumes set up with the - mount command; - it cannot be used to remove names in the pseudo file system. -

-

Example:

-
    -nsh> ls /mnt/fs/testdir
-/mnt/fs/testdir:
- TESTFILE.TXT
- EXAMPLE.TXT
-nsh> rm /mnt/fs/testdir/example.txt
-nsh> ls /mnt/fs/testdir
-/mnt/fs/testdir:
- TESTFILE.TXT
-nsh>
-
- - - - - -
-

2.56 Remove a Directory (rmdir)

 -
- -

Command Syntax:

-
    -rmdir <dir-path>
-
-

- Synopsis. - Remove the specified <dir-path> directory from the mounted file system. - Recall that NuttX uses a pseudo file system for its root file - system. - The rmdir command can only be used to remove directories from volumes set up with the - mount command; - it cannot be used to remove directories from the pseudo file system. -

-

Example:

-
    -nsh> mkdir /mnt/fs/tmp
-nsh> ls -l /mnt/fs
-/mnt/fs:
- drw-rw-rw-       0 TESTDIR/
- drw-rw-rw-       0 TMP/
-nsh> rmdir /mnt/fs/tmp
-nsh> ls -l /mnt/fs
-/mnt/fs:
- drw-rw-rw-       0 TESTDIR/
-nsh>
-
- - - - - -
-

2.57 Remove on OS Module (rmmod)

 -
- -

Command Syntax:

-
    -rmmod <module-name>
-
-

- Synopsis. - Remove the loadable OS module with the <module-name>. - NOTE: An OS module can only be removed if it is not busy. -

-

Example:

-
    -nsh> lsmod
-NAME                 INIT   UNINIT      ARG     TEXT     SIZE     DATA     SIZE
-mydriver         20404659 20404625        0 20404580      552 204047a8        0
-nsh> rmmod mydriver
-nsh> lsmod
-NAME                 INIT   UNINIT      ARG     TEXT     SIZE     DATA     SIZE
-nsh>
-
- - - - - -
-

2.58 Show routing table (route)

 -
- -

Command Syntax:

-
    -route ipv4|ipv6
-
-

- Synopsis. - Show the contents of routing table for IPv4 or IPv6. -

-

- If only IPv4 or IPv6 is enabled, then the argument is optional but, if provided, must match the enabled internet protocol version. -

- - - - - - -
-

2.59 Start/Stop the OpenAMP RPC Tunnel (rptun)

 -
- -

Command Syntax:

-
    -rptun start|stop <dev-path>
-
-

- Synopsis. - Start or stop the OpenAMP RPC tunnel device at <dev-path>. -

- - - - - -
-

2.60 Set a Variable (set)

 -
- -

Command Syntax:

-
    -set [{+|-}{e|x|xe|ex}] [<name> <value>]
-
-

- Synopsis. - Set the variable <name> to the string <value> and or set NSH parser control options. -

-

- For example, a variable may be set like this: -

-
    -nsh> echo $foobar
-
-nsh> set foobar foovalue
-nsh> echo $foobar
-foovalue
-nsh>
-
-

- If CONFIG_NSH_VARS is selected, the effect of this set command is to set the local NSH variable. Otherwise, the group-wide environment variable will be set. -

- If the local NSH variable has already been promoted to an environment variable via the export, then the set command will set the value of the environment variable rather than the local NSH variable. -

-

-

- NOTE: The Bash shell does not work this way. - Bash would set the value of both the local Bash variable and the environment variable of the same name to the same value. -
-

-

- If CONFIG_NSH_VARS=y is selected and no arguments are provided, then the set command will list all of the local NSH variables. -

-
    -nsh> set
-foolbar=foovalue
-
-

- Set the exit on error control and/or print a trace of commands when parsing scripts in NSH. - The settings are in effect from the point of execution, until they are changed again, or in the case of the initialization script, the settings are returned to the default settings when it exits. - Included child scripts will run with the parents settings and changes made in the child script will effect the parent on return. -

-
    -

  • - Use set -e to enable and set +e to disable (ignore) the exit condition on commands. - The default is -e. Errors cause script to exit. -

    • -

  • - Use set -x to enable and set +x to disable (silence) printing a trace of the script commands as they are executed. - The default is +x: no printing of a trace of script commands as they are executed. -

    • -
-

- Example 1 - no exit on command not found -

-
    -set +e
-notacommand
-
-

- Example 2 - will exit on command not found -

-
    -set -e
-notacommand
-
-

- Example 3 - will exit on command not found, and print a trace of the script commands -

-
    -set -ex
-
-

- Example 4 - will exit on command not found, and print a trace of the script commands and set foobar to foovalue. -

-
    -set -ex foobar foovalue
-nsh> echo $foobar
-foovalue
-
- - - - - -
-

2.61 Execute an NSH Script (sh)

 -
- -

Command Syntax:

-
    -sh <script-path>
-
-

- Synopsis. - Execute the sequence of NSH commands in the file referred - to by <script-path>. -

- - - - - -
-

2.62 Shut the system down (shutdown)

 -
- -

Command Syntax:

-
    -shutdown [--reboot]
-
-

- Synopsis. - Shutdown and power off the system or, optionally, reset and reboot the system immediately. - This command depends on hardware support to power down or reset the system; one, both, or neither behavior may be supported. -

-

- NOTE: The shutdown command duplicates the behavior of the poweroff and eboot commands. -

- - - - - -
-

2.63 Wait for Seconds (sleep)

 -
- -

Command Syntax:

-
    -sleep <sec>
-
-

- Synopsis. - Pause execution (sleep) for <sec> seconds. -

- - - - - -
-

2.64 Time Start the Telnet Daemon (telnetd)

 -
- -

Command Syntax:

-
    -telnetd
-
-

- Synopsis. - Start the Telnet daemon if it is not already running. -

-

- The Telnet daemon may be started either programmatically by calling nsh_telnetstart() or it may be started from the NSH command line using this telnetd command. -

-

- Normally this command would be suppressed with CONFIG_NSH_DISABLE_TELNETD because the Telnet daemon is automatically started in nsh_main.c. The exception is when CONFIG_NSH_NETLOCAL is selected. In that case, the network is not enabled at initialization but rather must be enabled from the NSH command line or via other applications. -

-

- In that case, when nsh_telnetstart() is called before the the network is initialized, it will fail. -

- - - - - -
-

2.65 Time execution of another command (time)

 -
- -

Command Syntax:

-
    -time "<command>"
-
-

- Synopsis. - Perform command timing. - This command will execute the following <command> string and then show how much time was required to execute the command. - Time is shown with a resolution of 100 microseconds which may be beyond the resolution of many configurations. - Note that the <command> must be enclosed in quotation marks if it contains spaces or other delimiters. -

-

Example:

-
    -nsh> time "sleep 2"
-
-2.0100 sec
-nsh>
-
-

- The additional 10 milliseconds in this example is due to the way that the sleep command works: It always waits one system clock tick longer than requested and this test setup used a 10 millisecond periodic system timer. - Sources of error could include various quantization errors, competing CPU usage, and the additional overhead of the time command execution itself which is included in the total. -

-

- The reported time is the elapsed time from starting of the command to completion of the command. - This elapsed time may not necessarily be just the processing time for the command. - It may included interrupt level processing, for example. - In a busy system, command processing could be delayed if pre-empted by other, higher priority threads competing for CPU time. - So the reported time includes all CPU processing from the start of the command to its finish possibly including unrelated processing time during that interval. -

-

- Notice that: -

-
    -nsh> time "sleep 2 &"
-sleep [3:100]
-
-0.0000 sec
-nsh>
-
-

- Since the sleep command is executed in background, the sleep command completes almost immediately. - As opposed to the following where the time command is run in background with the sleep command: -

-
    -nsh> time "sleep 2" &
-time [3:100]
-nsh>
-2.0100 sec
-
- - - - - -
-

2.66 Set the Size of a File (truncate)

 -
- -

Command Syntax:

-
    -truncate -s <length> <file-path>
-
-

- Synopsis. - Shrink or extend the size of the regular file at <file-path> to the - specified<length>. -

-

- A <file-path> argument that does not exist is created. The <length> - option is NOT optional. -

-

- If a <file-path> is larger than the specified size, the extra data is - lost. If a <file-path> is shorter, it is extended and the extended part - reads as zero bytes. -

- - - - - - -
-

2.67 Unmount a File System (umount)

 -
- -

Command Syntax:

-
    -umount <dir-path>
-
-

- Synopsis. - Un-mount the file system at mount point <dir-path>. - The umount command can only be used to un-mount volumes previously mounted using - mount command. -

-

Example:

-
    -nsh> ls /mnt/fs
-/mnt/fs:
- TESTDIR/
-nsh> umount /mnt/fs
-nsh> ls /mnt/fs
-/mnt/fs:
-nsh: ls: no such directory: /mnt/fs
-nsh>
-
- - - - - -
-

2.68 Print system information (uname)

 -
- -

Command Syntax:

-
    -uname [-a | -imnoprsv]
-
-

- Synopsis. - Print certain system information. With no options, the output is the same as -s. -

-

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    -a - Print all information, in the following order, except omit -p and -i if unknown: -
    -s, -o - Print the operating system name (NuttX) -
    -n - Print the network node hostname (only available if CONFIG_NET=y) -
    -r - Print the kernel release -
    -v - Print the kernel version -
    -m - Print the machine hardware name -
    -i - Print the machine platform name -
    -p - Print "unknown" -
- - - - - -
-

2.69 Unset an Environment Variable (unset)

 -
- -

Command Syntax:

-
    -unset <name>
-
-

- Synopsis. - Remove the value associated with the variable <name>. - This will remove the name-value pair from both the NSH local variables and the group-wide environment variables. For example: -

-
    -nsh> echo $foobar
-foovalue
-nsh> unset foobar
-nsh> echo $foobar
-
-nsh>
-
- - - - - -
-

2.70 URL Decode (urldecode)

 -
- -

Command Syntax:

-
    -urldecode [-f] <string or filepath>
-
-

- Synopsis. - To be provided. -

- - - - - -
-

2.71 URL Encode (urlencode)

 -
- -

Command Syntax:

-
    -urlencode [-f] <string or filepath>
-
-

- Synopsis. - To be provided. -

- - - - - -
-

2.72 Add a New User (useradd)

 -
- -

Command Syntax:

-
    -useradd <username> <password>
-
-

- Synopsis. - Add a new user with <username> and <password>. -

- - - - - -
-

2.73 Delete a user (userdel)

 -
- -

Command Syntax:

-
    -userdel <username>
-
-

- Synopsis. - Delete the user with the name <username>. -

- - - - - -
-

2.74 Wait for Microseconds (usleep)

 -
- -

Command Syntax:

-
    -usleep <usec>
-
-

- Synopsis. - Pause execution (sleep) of <usec> microseconds. -

- - - - - -
-

2.75 Get File Via HTTP (wget)

 -
- -

Command Syntax:

-
    -wget [-o <local-path>] <url>
-
-

- Synopsis. - Use HTTP to copy the file at <url> to the current directory. -

-

Options:

-
    - - - - -
    -o <local-path> - The file will be saved relative to the current working directory - and with the same name as on the HTTP server unless <local-path> is provided. -
- - - - - -
-

2.76 Hexadecimal Dump of Memory (xd)

 -
- -

Command Syntax:

-
    -xd <hex-address> <byte-count>
-
-

- Synopsis. - Dump <byte-count> bytes of data from address <hex-address>. -

-

Example:

-
    -nsh> xd 410e0 512
-Hex dump:
-0000: 00 00 00 00 9c 9d 03 00 00 00 00 01 11 01 10 06 ................
-0010: 12 01 11 01 25 08 13 0b 03 08 1b 08 00 00 02 24 ....%..........$
-...
-01f0: 08 3a 0b 3b 0b 49 13 00 00 04 13 01 01 13 03 08 .:.;.I..........
-nsh>
-
- - - - - -
-

3.0 Built-In Commands

 -
- -

- In addition to the commands that are part of NSH listed in the previous section above, there can be additional, external built-in applications that can be added to NSH. - These are separately excecuble programs but will appear much like the commands that are a part of NSH. - The primary difference from the user's perspective is that help information about the built-in applications is not available directly from NSH. - Rather, you will need to execute the application with the -h option to get help about using the built-in applications. -

- -

- There are several built-in applications in the apps/ repository. - No attempt is made here to enumerate all of them. - But a few of the more common, useful built-in applications are listed below. -

- - - - - -
-

3.1 Check Network Peer (ping/ping6)

 -
- -

Command Syntax:

-
    -ping  [-c <count>] [-i <interval>] <ip-address>
-ping6 [-c <count>] [-i <interval>] <ip-address>
-
-

- Synopsis. - Test the network communication with a remote peer. Example, -

-
    -nsh> ping 10.0.0.1
-PING 10.0.0.1 56 bytes of data
-56 bytes from 10.0.0.1: icmp_seq=1 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=2 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=3 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=4 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=5 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=6 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=7 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=8 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=9 time=0 ms
-56 bytes from 10.0.0.1: icmp_seq=10 time=0 ms
-10 packets transmitted, 10 received, 0% packet loss, time 10190 ms
-nsh>
-
-

- ping6 differs from ping in that it uses IPv6 addressing. -

- - - - - -
-

4.0 Configuration Settings

 -
- -

- The availability of the above commands depends upon features that - may or may not be enabled in the NuttX configuration file. The - following table indicates the dependency of each command on NuttX - configuration settings. General configuration settings are discussed - in the NuttX Porting Guide. - Configuration settings specific to NSH as discussed at the bottom of this document. -

- -

- Note that in addition to general NuttX configuration settings, each NSH command can be - individually disabled via the settings in the rightmost column. - All of these settings make the configuration of NSH potentially complex but also allow it to - squeeze into very small memory footprints. -

- - - - - -
-

4.1 Command Dependencies on Configuration Settings

 -
- -

Table. Command Dependencies on Configuration Settings

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandDepends on ConfigurationCan Be Disabled with
[!CONFIG_NSH_DISABLESCRIPTCONFIG_NSH_DISABLE_TEST
addrouteCONFIG_NET && CONFIG_NET_ROUTECONFIG_NSH_DISABLE_ADDROUTE
arpCONFIG_NET && CONFIG_NET_ARPCONFIG_NSH_DISABLE_ARP
base64decCONFIG_NETUTILS_CODECS && CONFIG_CODECS_BASE64CONFIG_NSH_DISABLE_BASE64DEC
base64encCONFIG_NETUTILS_CODECS && CONFIG_CODECS_BASE64CONFIG_NSH_DISABLE_BASE64ENC
basename CONFIG_NSH_DISABLE_BASENAME
break!CONFIG_NSH_DISABLESCRIPT && !CONFIG_NSH_DISABLE_LOOPS 
cat CONFIG_NSH_DISABLE_CAT
cd!CONFIG_DISABLE_ENVIRONCONFIG_NSH_DISABLE_CD
cmp CONFIG_NSH_DISABLE_CMP
cp CONFIG_NSH_DISABLE_CP
date
CONFIG_NSH_DISABLE_DATE
dd CONFIG_NSH_DISABLE_DD
delrouteCONFIG_NET && CONFIG_NET_ROUTECONFIG_NSH_DISABLE_DELROUTE
df!CONFIG_DISABLE_MOUNTPOINTCONFIG_NSH_DISABLE_DF
dirname CONFIG_NSH_DISABLE_DIRNAME
dmesgCONFIG_RAMLOG_SYSLOGCONFIG_NSH_DISABLE_DMESG
echo
CONFIG_NSH_DISABLE_ECHO
envCONFIG_FS_PROCFS && !CONFIG_DISABLE_ENVIRON && !CONFIG_PROCFS_EXCLUDE_ENVIRON - CONFIG_NSH_DISABLE_ENV
exec
CONFIG_NSH_DISABLE_EXEC
exit
CONFIG_NSH_DISABLE_EXIT
exportCONFIG_NSH_VARS && !CONFIG_DISABLE_ENVIRONCONFIG_NSH_DISABLE_EXPORT
free
CONFIG_NSH_DISABLE_FREE
getCONFIG_NET && CONFIG_NET_UDP && MTU >= 5581CONFIG_NSH_DISABLE_GET
help3
CONFIG_NSH_DISABLE_HELP
hexdump CONFIG_NSH_DISABLE_HEXDUMP
ifconfigCONFIG_NET && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_NETCONFIG_NSH_DISABLE_IFCONFIG
ifdownCONFIG_NET && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_NETCONFIG_NSH_DISABLE_IFUPDOWN
ifupCONFIG_NET && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_NETCONFIG_NSH_DISABLE_IFUPDOWN
insmodCONFIG_MODULECONFIG_NSH_DISABLE_MODCMDS
irqinfo!CONFIG_DISABLE_MOUNTPOINT && CONFIG_FS_PROCFS && CONFIG_SCHED_IRQMONITOR
kill CONFIG_NSH_DISABLE_KILL
losetup!CONFIG_DISABLE_MOUNTPOINT && CONFIG_DEV_LOOPCONFIG_NSH_DISABLE_LOSETUP
lnCONFIG_PSEUDOFS_SOFTLINKSCONFIG_NSH_DISABLE_LN
ls CONFIG_NSH_DISABLE_LS
lsmodCONFIG_MODULE && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_MODULECONFIG_NSH_DISABLE_MODCMDS
md5CONFIG_NETUTILS_CODECS && CONFIG_CODECS_HASH_MD5CONFIG_NSH_DISABLE_MD5
mb,mh,mw
 - CONFIG_NSH_DISABLE_MB,
- CONFIG_NSH_DISABLE_MH,
- CONFIG_NSH_DISABLE_MW -
mkdir(!CONFIG_DISABLE_MOUNTPOINT || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS)CONFIG_NSH_DISABLE_MKDIR
mkfatfs!CONFIG_DISABLE_MOUNTPOINT && CONFIG_FSUTILS_MKFATFSCONFIG_NSH_DISABLE_MKFATFS
mkfifoCONFIG_PIPES && CONFIG_DEV_FIFO_SIZE > 0CONFIG_NSH_DISABLE_MKFIFO
mkrd!CONFIG_DISABLE_MOUNTPOINTCONFIG_NSH_DISABLE_MKRD
mount!CONFIG_DISABLE_MOUNTPOINTCONFIG_NSH_DISABLE_MOUNT
mv!CONFIG_DISABLE_MOUNTPOINT || !CONFIG_DISABLE_PSEUDOFS_OPERATIONSCONFIG_NSH_DISABLE_MV
nfsmount!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NET && CONFIG_NFSCONFIG_NSH_DISABLE_NFSMOUNT
nslookupCONFIG_LIBC_NETDB && CONFIG_NETDB_DNSCLIENTCONFIG_NSH_DISABLE_NSLOOKUP
passwd!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NSH_LOGIN_PASSWDCONFIG_NSH_DISABLE_PASSWD
pmconfigCONFIG_PMCONFIG_NSH_DISABLE_PMCONFIG
poweroffCONFIG_BOARDCTL_POWEROFFCONFIG_NSH_DISABLE_POWEROFF
psCONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_PROCCONFIG_NSH_DISABLE_PS
putCONFIG_NET && CONFIG_NET_UDP && - MTU >= 5581,2CONFIG_NSH_DISABLE_PUT
pwd!CONFIG_DISABLE_ENVIRONCONFIG_NSH_DISABLE_PWD
readlinkCONFIG_PSEUDOFS_SOFTLINKSCONFIG_NSH_DISABLE_READLINK
rebootCONFIG_BOARD_RESETCONFIG_NSH_DISABLE_REBOOT
rm!CONFIG_DISABLE_MOUNTPOINT || !CONFIG_DISABLE_PSEUDOFS_OPERATIONSCONFIG_NSH_DISABLE_RM
rmdir!CONFIG_DISABLE_MOUNTPOINT || !CONFIG_DISABLE_PSEUDOFS_OPERATIONSCONFIG_NSH_DISABLE_RMDIR
rmmodCONFIG_MODULECONFIG_NSH_DISABLE_MODCMDS
routeCONFIG_FS_PROCFS && CONFIG_FS_PROCFS_EXCLUDE_NET && !CONFIG_FS_PROCFS_EXCLUDE_ROUTE && CONFIG_NET_ROUTE && !CONFIG_NSH_DISABLE_ROUTE && (CONFIG_NET_IPv4 || CONFIG_NET_IPv6)CONFIG_NSH_DISABLE_ROUTE
rptunCONFIG_RPTUN - CONFIG_NSH_DISABLE_RPTUN
setCONFIG_NSH_VARS || !CONFIG_DISABLE_ENVIRONCONFIG_NSH_DISABLE_SET
shutdownCONFIG_BOARDCTL_POWEROFF || CONFIG_BOARD_RESETCONFIG_NSH_DISABLE_SHUTDOWN
sleep CONFIG_NSH_DISABLE_SLEEP
sourceCONFIG_NFILE_STREAMS > 0 && !CONFIG_NSH_DISABLESCRIPTCONFIG_NSH_DISABLE_SOURCE
telnetdCONFIG_NSH_TELNETCONFIG_NSH_DISABLE_TELNETD
test!CONFIG_NSH_DISABLESCRIPTCONFIG_NSH_DISABLE_TEST
time CONFIG_NSH_DISABLE_TIME
truncate!CONFIG_DISABLE_MOUNTPOINTCONFIG_NSH_DISABLE_TRUNCATE
umount!CONFIG_DISABLE_MOUNTPOINTCONFIG_NSH_DISABLE_UMOUNT
uname CONFIG_NSH_DISABLE_UNAME
unsetCONFIG_NSH_VARS || !CONFIG_DISABLE_ENVIRONCONFIG_NSH_DISABLE_UNSET
urldecode!CONFIG_NETUTILS_CODECS && CONFIG_CODECS_URLCODE - CONFIG_NSH_DISABLE_URLDECODE
urlencode!CONFIG_NETUTILS_CODECS && CONFIG_CODECS_URLCODE - CONFIG_NSH_DISABLE_URLENCODE
useradd!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NSH_LOGIN_PASSWDCONFIG_NSH_DISABLE_USERADD
userdel!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NSH_LOGIN_PASSWDCONFIG_NSH_DISABLE_USERDEL
usleep CONFIG_NSH_DISABLE_USLEEP
wgetCONFIG_NET && CONFIG_NET_TCPCONFIG_NSH_DISABLE_WGET
xd
CONFIG_NSH_DISABLE_XD
- -

1 - Because of hardware padding, the actual required packet size may be larger
- 2 - Special TFTP server start-up options will probably be required to permit - creation of files for the correct operation of the put command.
- 3 - Verbose help output can be suppressed by defining CONFIG_NSH_HELP_TERSE. - In that case, the help command is still available but will be slightly smaller. - -

- - - - - -
-

4.2 Built-In Command Dependencies on Configuration Settings

 -
- -

- All built-in applications require that support for NSH built-in applications has been enabled. - This support is enabled with CONFIG_BUILTIN=y and CONFIG_NSH_BUILTIN_APPS=y. -

- -

Table. Built-In Command Dependencies on Configuration Settings

- - - - - - - - - - - - - -
CommandDepends on Configuration
pingCONFIG_NET && CONFIG_NET_ICMP && - CONFIG_NET_ICMP_SOCKET && CONFIG_SYSTEM_PING
ping6CONFIG_NET && CONFIG_NET_ICMPv6 && - CONFIG_NET_ICMPv6_SOCKET && CONFIG_SYSTEM_PING6
- - - - - -
-

4.3 NSH-Specific Configuration Settings

 -
- -

- The behavior of NSH can be modified with the following settings in - the boards/<arch>/<chip>/<board>/defconfig file: -

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ConfigurationDescription
CONFIG_NSH_READLINE - Selects the minimal implementation of readline(). - This minimal implementation provides on backspace for command line editing. - It expects some minimal VT100 command support from the terminal. -
CONFIG_NSH_CLE - Selects the more extensive, EMACS-like command line editor. - Select this option only if - (1) you don't mind a modest increase in the FLASH footprint, and - (2) you work with a terminal that supports extensive VT100 editing commands. - Selecting this option will add probably 1.5-2KB to the FLASH footprint. -
CONFIG_NSH_BUILTIN_APPS - Support external registered, "builtin" applications that can be - executed from the NSH command line (see apps/README.txt for - more information). - This required CONFIG_BUILTIN to enable NuttX support for - "builtin" applications. -
CONFIG_NSH_FILEIOSIZE - Size of a static I/O buffer used for file access (ignored if - there is no file system). Default is 1024. -
CONFIG_NSH_STRERROR - strerror(errno) makes more readable output but strerror() is - very large and will not be used unless this setting is y. - This setting depends upon the strerror() having been enabled with CONFIG_LIBC_STRERROR. -
CONFIG_NSH_LINELEN - The maximum length of one command line and of one output line. - Default: 80 -
CONFIG_NSH_DISABLE_SEMICOLON - By default, you can enter multiple NSH commands on a line with each command separated by a semicolon. - You can disable this feature to save a little memory on FLASH challenged platforms. - Default: n -
CONFIG_NSH_CMDPARMS - If selected, then the output from commands, from file applications, and from NSH built-in commands can be used as arguments to other commands. - The entity to be executed is identified by enclosing the command line in back quotes. - For example, - 
    -set FOO `myprogram $BAR`
-
- will execute the program named myprogram passing it the value of the environment variable BAR. - The value of the environment variable FOO is then set output of myprogram on stdout. Because this feature commits significant resources, it is disabled by default. - - The CONFIG_NSH_CMDPARMS interim output will be retained in a temporary file. - Full path to a directory where temporary files can be created is taken from CONFIG_LIBC_TMPDIR and it defaults to /tmp if CONFIG_LIBC_TMPDIR is not set. -
CONFIG_NSH_MAXARGUMENTS - The maximum number of NSH command arguments. Default: 6 -
CONFIG_NSH_ARGCAT - Support concatenation of strings with environment variables or command output. - For example: - 
    -set FOO XYZ
-set BAR 123
-set FOOBAR ABC_${FOO}_${BAR}
-
- would set the environment variable FOO to XYZ, BAR to 123 and FOOBAR to ABC_XYZ_123. - If CONFIG_NSH_ARGCAT is not selected, then a slightly small FLASH footprint results but then also only simple environment variables like $FOO can be used on the command line. -
CONFIG_NSH_VARS - By default, there are no internal NSH variables. NSH will use OS - environment variables for all variable storage. If this option, NSH - will also support local NSH variables. These variables are, for the - most part, transparent and work just like the OS environment - variables. The difference is that when you create new tasks, all of - environment variables are inherited by the created tasks. NSH local - variables are not. -

-

- If this option is enabled (and CONFIG_DISABLE_ENVIRON is not), then a - new command called 'export' is enabled. The export command works very - must like the set command except that is operates on environment - variables. When CONFIG_NSH_VARS is enabled, there are changes in the - behavior of certain commands -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CMDw/o CONFIG_NSH_VARSw/ CONFIG_NSH_VARS
set <a> <b>Set environment variable <a> to <b>Set NSH variable <a> to <b> - (Unless the NSH variable has been promoted via export, in which case the environment variable of the same name is set to <b>). -
setCauses an error.Lists all NSH variables.
unset <a>Unsets environment variable <a>Unsets both environment variable and NSH variable with and name <a>
export <a> <b>Causes an error,Unsets NSH variable <a>. Sets environment variable <a> to <b>.
export <a>Causes an error.Sets environment variable <a> to the value of NSH variable <a> (or "" if the NSH variable has not been set). Unsets NSH local variable <a>.
envLists all environment variablesLists all environment variables (only)
-
CONFIG_NSH_QUOTE - Enables back-slash quoting of certain characters within the command. - This option is useful for the case where an NSH script is used to dynamically generate a new NSH script. - In that case, commands must be treated as simple text strings without interpretation of any special characters. - Special characters such as $, `, ", and others must be retained intact as part of the test string. - This option is currently only available is CONFIG_NSH_ARGCAT is also selected. -
CONFIG_NSH_NESTDEPTH - The maximum number of nested if-then[-else]-fi sequences that - are permissible. Default: 3 -
CONFIG_NSH_DISABLESCRIPT - This can be set to y to suppress support for scripting. This - setting disables the sh, test, and [ commands and the - if-then[-else]-fi construct. This would only be set on systems - where a minimal footprint is a necessity and scripting is not. -
CONFIG_NSH_DISABLE_ITEF - If scripting is enabled, then then this option can be selected to suppress support for if-then-else-fi sequences in scripts. - This would only be set on systems where some minimal scripting is required but if-then-else-fi is not. -
CONFIG_NSH_DISABLE_LOOPS - If scripting is enabled, then then this option can be selected suppress support for while-do-done and until-do-done sequences in scripts. - This would only be set on systems where some minimal scripting is required but looping is not. -
CONFIG_NSH_DISABLEBG - This can be set to y to suppress support for background - commands. This setting disables the nice command prefix and - the & command suffix. This would only be set on systems - where a minimal footprint is a necessity and background command execution is not. -
CONFIG_NSH_MMCSDMINOR - If the architecture supports an MMC/SD slot and if the NSH - architecture specific logic is present, this option will provide - the MMC/SD minor number, i.e., the MMC/SD block driver will - be registered as /dev/mmcsdN where N is the minor number. - Default is zero. -
CONFIG_NSH_ROMFSETC - Mount a ROMFS file system at /etc and provide a startup script - at /etc/init.d/rcS. The default startup script will mount - a FAT FS RAMDISK at /tmp but the logic is - easily extensible. -
CONFIG_NSH_CONSOLE -

- If CONFIG_NSH_CONSOLE is set to y, then a serial - console front-end is selected. -

-

- Normally, the serial console device is a UART and RS-232 interface. - However, if CONFIG_USBDEV is defined, then a USB serial device may, instead, be used if the one of the following are defined: -

-
    -
  • - CONFIG_PL2303 and CONFIG_PL2303_CONSOLE. - Sets up the Prolifics PL2303 emulation as a console device at /dev/console. -
    • -
  • - CONFIG_CDCACM and CONFIG_CDCACM_CONSOLE. - Sets up the CDC/ACM serial device as a console device at /dev/console. -
    • -
  • - CONFIG_NSH_USBCONSOLE. - If defined, then an arbitrary USB device may be used to as the NSH console. - In this case, CONFIG_NSH_USBCONDEV must be defined to indicate which USB device to use as the console. - The advantage of using a device other that /dev/console is that normal debug output can then use /dev/console while NSH uses CONFIG_NSH_USBCONDEV. -

    - CONFIG_NSH_USBCONDEV. - If CONFIG_NSH_USBCONSOLE is set to 'y', then CONFIG_NSH_USBCONDEV must also be set to select the USB device used to support the NSH console. - This should be set to the quoted name of a readable/write-able USB driver such as: CONFIG_NSH_USBCONDEV="/dev/ttyACM0". -

    -
    • -
-

- If there are more than one USB slots, then a USB device minor number may also need to be provided: -

-
    -
  • - CONFIG_NSH_UBSDEV_MINOR. - The minor device number of the USB device. Default: 0 -
    • -
-

- If USB tracing is enabled (CONFIG_USBDEV_TRACE), then NSH will initialize USB tracing as requested by the following. - Default: Only USB errors are traced. -

-
    -
  • - CONFIG_NSH_USBDEV_TRACEINIT. - Show initialization events -
    • -
  • - CONFIG_NSH_USBDEV_TRACECLASS. - Show class driver events -
    • -
  • - CONFIG_NSH_USBDEV_TRACETRANSFERS. - Show data transfer events -
    • -
  • - CONFIG_NSH_USBDEV_TRACECONTROLLER. - Show controller events -
  • - CONFIG_NSH_USBDEV_TRACEINTERRUPTS. - Show interrupt-related events. -
    • -
-
CONFIG_NSH_ALTCONDEV and CONFIG_NSH_CONDEV - If CONFIG_NSH_CONSOLE is set to y, then CONFIG_NSH_ALTCONDEV - may also be selected to enable use of an alternate character device to support the NSH console. - If CONFIG_NSH_ALTCONDEV is selected, then CONFIG_NSH_CONDEV holds the quoted name of a readable/write-able character driver such as: - CONFIG_NSH_CONDEV="/dev/ttyS1". - This is useful, for example, to separate the NSH command line from the system console - when the system console is used to provide debug output. - Default: stdin and stdout (probably "/dev/console") -
    -
  • - NOTE 1: - When any other device other than /dev/console is used for a user interface, - (1) linefeeds (\n) will not be expanded to carriage return / linefeeds (\r\n). - You will need to configure your terminal program to account for this. - And (2) input is not automatically echoed so you will have to turn local echo on. -
    • -
  • - NOTE 2: - This option forces the console of all sessions to use NSH_CONDEV. - Hence, this option only makes sense for a system that supports only a single session. - This option is, in particular, incompatible with Telnet sessions because each Telnet session must use a different console device. -
    • -
-
CONFIG_NSH_TELNET - If CONFIG_NSH_TELNET is set to y, then a TELNET - server front-end is selected. When this option is provided, - you may log into NuttX remotely using telnet in order to - access NSH. -
CONFIG_NSH_ARCHINIT - Set CONFIG_NSH_ARCHINIT if your board provides architecture - specific initialization via the board-specific function board_app_initialize(). - This function will be called early in NSH initialization to allow board logic to - do such things as configure MMC/SD slots. -
- -

- If Telnet is selected for the NSH console, then we must configure - the resources used by the Telnet daemon and by the Telnet clients. -

- -
- - - - - - - - - - - - - - - - - - - - - - - - - -
ConfigurationDescription
CONFIG_NSH_TELNETD_PORT - The telnet daemon will listen on this TCP port number for connections. Default: 23 -
CONFIG_NSH_TELNETD_DAEMONPRIO - Priority of the Telnet daemon. - Default: SCHED_PRIORITY_DEFAULT -
CONFIG_NSH_TELNETD_DAEMONSTACKSIZE - Stack size allocated for the - Telnet daemon. Default: 2048 -
CONFIG_NSH_TELNETD_CLIENTPRIO - Priority of the Telnet client. - Default: SCHED_PRIORITY_DEFAULT -
CONFIG_NSH_TELNETD_CLIENTSTACKSIZE - Stack size allocated for the Telnet client. Default: 2048 -
- -

- One or both of CONFIG_NSH_CONSOLE and CONFIG_NSH_TELNET - must be defined. If CONFIG_NSH_TELNET is selected, then there some - other configuration settings that apply: -

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ConfigurationDescription
CONFIG_NET=y - Of course, networking must be enabled. -
CONFIG_NSOCKET_DESCRIPTORS - And, of course, you must allocate some socket descriptors. -
CONFIG_NET_TCP=y - TCP/IP support is required for telnet (as well as various other TCP-related configuration settings). -
CONFIG_NSH_IOBUFFER_SIZE - Determines the size of the I/O buffer to use for sending/ - receiving TELNET commands/responses -
CONFIG_NSH_DHCPC - Obtain the IP address via DHCP. -
CONFIG_NSH_IPADDR - If CONFIG_NSH_DHCPC is NOT set, then the static IP - address must be provided. -
CONFIG_NSH_DRIPADDR - Default router IP address -
CONFIG_NSH_NETMASK - Network mask -
CONFIG_NSH_NOMAC - Set if your Ethernet hardware has no built-in MAC address. - If set, a bogus MAC will be assigned. -
CONFIG_NSH_MAX_ROUNDTRIP - This is the maximum round trip for a response to a ICMP ECHO request. - It is in units of deciseconds. The default is 20 (2 seconds). -
- -

- If you use DHCPC, then some special configuration network options are - required. These include: -

- -
- - - - - - - - - - - - - - - - - - - - - - - - -
ConfigurationDescription
CONFIG_NET=y - Of course, networking must be enabled. -
CONFIG_NSOCKET_DESCRIPTORS - And, of course, you must allocate some socket descriptors. -
CONFIG_NET_UDP=y - UDP support is required for DHCP (as well as various other UDP-related configuration settings). -
CONFIG_NET_BROADCAST=y - UDP broadcast support is needed. -
CONFIG_NET_ETH_PKTSIZE=650 (or larger) - Per RFC2131 (p. 9), the DHCP client must be prepared to receive DHCP messages of up to - 576 bytes (excluding Ethernet, IP, or UDP headers and FCS). - NOTE: Note that the actual MTU setting will depend upon the specific link protocol. - Here Ethernet is indicated. -
- -

- If CONFIG_NSH_ROMFSETC is selected, then the following additional - configuration setting apply: -

- -
- - - - - - - - - - - - - - - - - - - - - - - - -
ConfigurationDescription
CONFIG_NSH_ARCHROMFS - May be defined to specify an alternative ROMFS image that can be found at boards/<arch>/<chip>/<board>/include/nsh_romfsimg.h. -
CONFIG_NSH_ROMFSMOUNTPT - The default mountpoint for the ROMFS volume is "/etc", but that - can be changed with this setting. This must be a absolute path - beginning with '/' and enclosed in quotes. -
CONFIG_NSH_INITSCRIPT - This is the relative path to the startup script within the mountpoint. - The default is "init.d/rcS". This is a relative path and must not - start with '/' but must be enclosed in quotes. -
CONFIG_NSH_ROMFSDEVNO - This is the minor number of the ROMFS block device. The default is - '0' corresponding to /dev/ram0. -
CONFIG_NSH_ROMFSSECTSIZE - This is the sector size to use with the ROMFS volume. Since the - default volume is very small, this defaults to 64 but should be - increased if the ROMFS volume were to be become large. Any value - selected must be a power of 2. -
- -

- When the default rcS file used when CONFIG_NSH_ROMFSETC is - selected, it will mount a FAT FS under /tmp. The following selections - describe that FAT FS. -

- -
- - - - - - - - - - - - -
ConfigurationDescription
CONFIG_NSH_FATDEVNO - This is the minor number of the FAT FS block device. The default is - '1' corresponding to /dev/ram1. -
CONFIG_NSH_FATSECTSIZE - This is the sector size use with the FAT FS. Default is 512. -
- - - - - -
-

5.0 Customizing the NuttShell

 -
- -

- Overview. - The NuttShell (NSH) is a simple shell application that may be used with NuttX. - It supports a variety of commands and is (very) loosely based on the Bash shell and the common utilities used with Bash shell programming. - The paragraphs in this appendix will focus on customizing NSH: Adding new commands, changing the initialization sequence, etc. -

- - - - - -
-

5.1 The NSH Library and NSH Initialization

 -
- -

- Overview. - NSH is implemented as a library that can be found at apps/nshlib. - As a library, it can be custom built into any application that follows the NSH initialization sequence described below. - As an example, the code at apps/examples/nsh/nsh_main.c illustrates how to start NSH and the logic there was intended to be incorporated into your own custom code. - Although code was generated simply as an example, in the end most people just use this example code as their application main() function. - That initialization performed by that example is discussed in the following paragraphs. -

- -

5.1.1 NSH Initialization sequence

- -

- The NSH start-up sequence is very simple. - As an example, the code at apps/system/nsh/nsh_main.c illustrates how to start NSH. - It simple does the following: -

- -
    -
  1. -

    - This function calls nsh_initialize() which initializes the NSH library. - nsh_initialize() is described in more detail below. -

    -
  2. -

    - If the Telnetconsole is enabled, it calls nsh_telnetstart() which resides in the NSH library. - nsh_telnetstart() will start the Telnet daemon that will listen for Telnet connections and start remote NSH sessions. -

    -
  3. -

    - If a local console is enabled (probably on a serial port), then nsh_consolemain() is called. - nsh_consolemain() also resides in the NSH library. - nsh_consolemain() does not return so that finished the entire NSH initialization sequence. -

    -
- -

5.1.2 nsh_initialize()

- -

- The NSH initialization function, nsh_initialize(), be found in apps/nshlib/nsh_init.c. - It does only three things: -

- -
    -
  1. -

    - nsh_romfsetc(): - If so configured, it executes an NSH start-up script that can be found at /etc/init.d/rcS in the target file system. - The nsh_romfsetc() function can be found in apps/nshlib/nsh_romfsetc.c. - This function will (1) register a ROMFS file system, then (2) mount the ROMFS file system. - /etc is the default location where a read-only, ROMFS file system is mounted by nsh_romfsetc(). -

    -

    - The ROMFS image is, itself, just built into the firmware. - By default, this rcS start-up script contains the following logic: -

    -
      -# Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX
-
-mkrd -m XXXMKRDMINORXXX -s XXMKRDSECTORSIZEXXX XXMKRDBLOCKSXXX
-mkfatfs /dev/ramXXXMKRDMINORXXX
-mount -t vfat /dev/ramXXXMKRDMINORXXX XXXRDMOUNTPOINTXXX
-
    - -

    - Where the XXXX*XXXX strings get replaced in the template when the ROMFS image is created: -

    -
      -
    • -

      - XXXMKRDMINORXXX will become the RAM device minor number. - Default: 0 -

      -
    • -

      - XXMKRDSECTORSIZEXXX will become the RAM device sector size -

      -
    • -

      - XXMKRDBLOCKSXXX will become the number of sectors in the device. -

      -
    • -

      - XXXRDMOUNTPOINTXXX will become the configured mount point. - Default: /etc -

      -
    -

    - By default, the substituted values would yield an rcS file like: -

    -
      -# Create a RAMDISK and mount it at /tmp
-
-mkrd -m 1 -s 512 1024
-mkfatfs /dev/ram1
-mount -t vfat /dev/ram1 /tmp
-
    -

    - This script will, then: -

    -
      -
    • -

      - Create a RAMDISK of size 512*1024 bytes at /dev/ram1, -

      -
    • -

      - Format a FAT file system on the RAM disk at /dev/ram1, and then -

      -
    • -

      - Mount the FAT file system at a configured mountpoint, /tmp. -

      -
    -

    - This rcS template file can be found at apps/nshlib/rcS.template. - The resulting ROMFS file system can be found in apps/nshlib/nsh_romfsimg.h. -

    -
  2. -

    - board_app_initialize(): - Next any architecture-specific NSH initialization will be performed (if any). - For the STM3240G-EVAL, this architecture specific initialization can be found at boards/arm/stm32/stm3240g-eval/src/stm32_appinit.c. - This it does things like: (1) Initialize SPI devices, (2) Initialize SDIO, and (3) mount any SD cards that may be inserted. -

    -
  3. -

    - nsh_netinit(): - The nsh_netinit() function can be found in apps/nshlib/nsh_netinit.c. -

    -
- - - - - -
-

5.2 NSH Commands

 -
- -

- Overview. - NSH supports a variety of commands as part of the NSH program. - All of the NSH commands are listed in the NSH documentation above. - Not all of these commands may be available at any time, however. - Many commands depend upon certain NuttX configuration options. - You can enter the help command at the NSH prompt to see the commands actual available: -

-
    -nsh> help
-
-

- For example, if network support is disabled, then all network-related commands will be missing from the list of commands presented by 'nsh> help'. - You can see the specific command dependencies in the table above. -

- -

5.2.1 Adding New NSH Commands

- -

- New commands can be added to the NSH very easily. - You simply need to add two things: -

-
    -
  1. -

    - The implementation of your command, and -

    -
  2. -

    - A new entry in the NSH command table -

    -
- -

- Implementation of Your Command. - For example, if you want to add a new a new command called mycmd to NSH, you would first implement the mycmd code in a function with this prototype: -

-
    -int cmd_mycmd(FAR struct nsh_vtbl_s *vtbl, int argc, char **argv);
-
-

- The argc and argv are used to pass command line arguments to the NSH command. - Command line parameters are passed in a very standard way: argv[0] will be the name of the command, and argv[1] through argv[argc-1] are the additional arguments provided on the NSH command line. -

-

- The first parameter, vtbl, is special. - This is a pointer to session-specific state information. - You don't need to know the contents of the state information, but you do need to pass this vtbl argument when you interact with the NSH logic. - The only use you will need to make of the vtbl argument will be for outputting data to the console. - You don't use printf() within NSH commands. - Instead you would use: -

-
    -void nsh_output(FAR struct nsh_vtbl_s *vtbl, const char *fmt, …);
-
-

- So if you only wanted to output "Hello, World!" on the console, then your whole command implementation might be: -

-
    -int cmd_mycmd(FAR struct nsh_vtbl_s *vtbl, int argc, char **argv)
-{
-  nsh_output(vtbl, "Hello, World!");
-  return 0;
-}
-
-

- The prototype for the new command should be placed in apps/examples/nshlib/nsh.h. -

- -

- Adding You Command to the NSH Command Table. - All of the commands support by NSH appear in a single table called: -

-
    -const struct cmdmap_s g_cmdmap[]
-
-

- That table can be found in the file apps/examples/nshlib/nsh_parse.c. - The structure cmdmap_s is also defined in apps/nshlib/nsh_parse.c: -

-
    -struct cmdmap_s
-{
-  const char *cmd;        /* Name of the command */
-  cmd_t       handler;    /* Function that handles the command */
-  uint8_t     minargs;    /* Minimum number of arguments (including command) */
-  uint8_t     maxargs;    /* Maximum number of arguments (including command) */
-  const char *usage;      /* Usage instructions for 'help' command */
-};
-
-

- This structure provides everything that you need to describe your command: - Its name (cmd), the function that handles the command (cmd_mycmd()), the minimum and maximum number of arguments needed by the command, - and a string describing the command line arguments. - That last string is what is printed when enter "nsh> help". -

-

- So, for you sample command, you would add the following the to the g_cmdmap[] table: -

-
    -{ "mycmd", cmd_mycmd, 1, 1, NULL },
-
- -

- This entry is particularly simply because mycmd is so simple. - Look at the other commands in g_cmdmap[] for more complex examples. -

- - - - - -
-

5.3 NSH "Built-In" Applications

 -
- -

- Overview. - In addition to these commands that are a part of NSH, external programs can also be executed as NSH commands. - These external programs are called "Built-In" Applications for historic reasons. - That terminology is somewhat confusing because the actual NSH commands as described above are truly "built-into" NSH whereas these applications are really external to NuttX. -

-

- These applications are built-into NSH in the sense that they can be executed by simply typing the name of the application at the NSH prompt. - Built-in application support is enabled with these configuration option: -

-
    -
  • - CONFIG_BUILTIN: - Enable NuttX support for builtin applications. -
    • -
  • - CONFIG_NSH_BUILTIN_APPS: - Enable NSH support for builtin applications. -
    • -
-

- When these configuration options are set, you will also be able to see the built-in applications if you enter "nsh> help". - They will appear at the bottom of the list of NSH commands under: -

- -
    -Builtin Apps:
-
-

- Note that no detailed help information beyond the name of the built-in application is provided. -

- -

5.3.1 Built-In Applications

- -

- Overview. - The underlying logic that supports the NSH built-in applications is called "Built-In Applications". - The builtin application logic can be found at apps/builtin. - This logic simply does the following: -

- -
    -
  1. -

    - It supports registration mechanism so that builtin applications can dynamically register themselves at build time, and -

    -
  2. -

    - Utility functions to look up, list, and execute the builtin applications. -

    -
- -

- Built-In Application Utility Functions. - The utility functions exported by the builtin application logic are prototyped in nuttx/include/nuttx/lib/builtin.h and apps/include/builtin.h. - These utility functions include: -

- -
    -
  • -

    - int builtin_isavail(FAR const char *appname); - Checks for availability of application registered as appname during build time. -

    -
  • -

    - const char *builtin_getname(int index); - Returns a pointer to a name of built-in application pointed by the index. - This is the utility function that is used by NSH in order to list the available built-in applications when "nsh> help" is entered. -

    -
  • -

    - int exec_builtin(FAR const char *appname, FAR const char **argv); - Executes built-in builtin application registered during compile time. - This is the utility function used by NSH to execute the built-in application. -

    -
- -

- Autogenerated Header Files. - Application entry points with their requirements are gathered together in two files when NuttX is first built: -

-
    -
  1. -

    - apps/builtin/builtin_proto.h: - Prototypes of application task entry points. -

    -
  2. -

    - apps/builtin/builtin_list.h: - Application specific information and start-up requirements -

    -
- -

- Registration of Built-In Applications. - The NuttX build occurs in several phases as different build targets are executed: - (1) context when the configuration is established, - (2) depend when target dependencies are generated, and - (3) default (all) when the normal compilation and link operations are performed. - Built-in application information is collected during the make context build phase. -

- -

- An example application that can be "built-in" is be found in the apps/examples/hello directory. - Let's walk through this specific cause to illustrate the general way that built-in applications are created and how they register themselves so that they can be used from NSH. -

- -

- apps/examples/hello. - The main routine for apps/examples/hello can be found in apps/examples/hello/main.c. - The main routine is: -

-
    -int hello_main(int argc, char *argv[])
-{
-  printf("Hello, World!!\n");
-  return 0;
-}
-
- -

- This is the built in function that will be registered during the context build phase of the NuttX build. - That registration is performed by logic in apps/examples/hello/Makefile. - But the build system gets to that logic through a rather tortuous path: -

- -
    -
  1. -

    - The top-level context make target is in nuttx/Makefile. - All build targets depend upon the context build target. - For the apps/ directory, this build target will execute the context target in the apps/Makefile. -

    -
  2. -

    - The apps/Makefile will, in turn, execute the context targets in all of the configured sub-directories. - In our case will include the Makefile in apps/examples. -

    -
  3. -

    - And finally, the apps/examples/Makefile will execute the context target in all configured examplesub-directories, getting us finally to apps/examples/Makefile which is covered below.

    -
- -

- NOTE: - Since this context build phase can only be executed one time, any subsequent configuration changes that you make will, then, not be reflected in the build sequence. - That is a common area of confusion. - Before you can instantiate the new configuration, you have to first get rid of the old configuration. - The most drastic way to this is: -

-
    -make distclean
-
-

- But then you will have to re-configuration NuttX from scratch. - But if you only want to re-build the configuration in the apps/ sub-directory, then there is a less labor-intensive way to do that. - The following NuttX make command will remove the configuration only from the apps/ directory and will let you continue without re-configuring everything: -

-
    -make apps_distclean
-
- -

- Logic for the context target in apps/examples/hello/Makefile registers the hello_main() application in the builtin's builtin_proto.hand builtin_list.h files. - That logic that does that in apps/examples/hello/Makefile is abstracted below: -

-
    -
  1. -

    - First, the Makefile includes apps/Make.defs: -

    -
      -include $(APPDIR)/Make.defs
-
    -

    - This defines a macro called REGISTER that adds data to the builtin header files: -

    -
      -define REGISTER
-    @echo "Register: $1"
-    @echo "{ \"$1\", $2, $3, $4 }," >> "$(APPDIR)/builtin/builtin_list.h"
-    @echo "EXTERN int $4(int argc, char *argv[]);" >> "$(APPDIR)/builtin/builtin_proto.h"
-endef
-
    -

    - When this macro runs, you will see the output in the build "Register: hello", that is a sure sign that the registration was successful. -

    -
  2. -

    - The make file then defines the application name (hello), the task priority (default), and the stack size that will be allocated in the task runs (2K). -

    -
      -APPNAME         = hello
-PRIORITY        = SCHED_PRIORITY_DEFAULT
-STACKSIZE       = 2048
-
    - -
  3. -

    - And finally, the Makefile invokes the REGISTER macro to added the hello_main() builtin application. - Then, when the system build completes, the hello command can be executed from the NSH command line. - When the hello command is executed, it will start the task with entry point hello_main() with the default priority and with a stack size of 2K. -

    -
      -context:
-  $(call REGISTER,$(APPNAME),$(PRIORITY),$(STACKSIZE),$(APPNAME)_main)
-
    -
- -

- Other Uses of Built-In Application. - The primary purpose of builtin applications is to support command line execution of applications from NSH. - However, there is one other use of builtin applications that should be mentioned. -

- -
    -
  1. -

    binfs. - binfs is a tiny file system located at apps/builtin/binfs.c. - This provides an alternative what of visualizing installed builtin applications. - Without binfs, you can see the installed builtin applications using the NSH help command. - binfs will create a tiny pseudo-file system mounted at /bin. - Using binfs, you can see the available builtin applications by listing the contents of /bin directory. - This gives some superficial Unix-like compatibility, but does not really add any new functionality. -

    -
    2. -
- -

5.3.2 Synchronous Built-In Applications

- -

- By default, built-in commands started from the NSH command line will run asynchronously with NSH. - If you want to force NSH to execute commands then wait for the command to execute, you can enable that feature by adding the following to the NuttX configuration file: -

-
    -CONFIG_SCHED_WAITPID=y
-
-

- This configuration option enables support for the standard waitpid() RTOS interface. - When that interface is enabled, NSH will use it to wait, sleeping until the built-in application executes to completion. -

-

- Of course, even with CONFIG_SCHED_WAITPID=y defined, specific applications can still be forced to run asynchronously by adding the ampersand (&) after the NSH command. -

- - - - - -
-

5.4 Customizing NSH Initialization

 -
- -

- Ways to Customize NSH Initialization. - There are three ways to customize the NSH start-up behavior. - Here they are presented in order of increasing difficulty: -

- -
    -
  1. -

    - You can extend the initialization logic in boards/arm/stm32/stm3240g-eval/src/stm32_appinit.c. - The logic there is called each time that NSH is started and is good place in particular for any device-related initialization. -

    -
  2. -

    - You replace the sample code at apps/examples/nsh/nsh_main.c with whatever start-up logic that you want. - NSH is a library at apps/nshlib. - apps.examples/nsh is just a tiny, example start-up function (CONFIG_USER_ENTRYPOINT()) that that runs immediately and illustrates how to start NSH - If you want something else to run immediately then you can write your write your own custom CONFIG_USER_ENTRYPOINT() function and then start other tasks from your custom CONFIG_USER_ENTRYPOINT(). -

    -
  3. -

    - NSH also supports a start-up script that executed when NSH first runs. - This mechanism has the advantage that the start-up script can contain any NSH commands and so can do a lot of work with very little coding. - The disadvantage is that is is considerably more complex to create the start-up script. - It is sufficiently complex that is deserves its own paragraph -

    -
- -

5.4.1 NuttShell Start up Scripts

- -

- First of all you should look at NSH Start-Up Script paragraph. - Most everything you need to know can be found there. - That information will be repeated and extended here for completeness. -

- -

- NSH Start-Up Script. - NSH supports options to provide a start up script for NSH. - The start-up script contains any command support by NSH (i.e., that you see when you enter 'nsh> help'). - In general this capability is enabled with CONFIG_NSH_ROMFSETC=y, but has several other related configuration options as described with the NSH-specific configuration settings paragraph. - This capability also depends on: -

- -
    -
  • -

    - CONFIG_DISABLE_MOUNTPOINT=n. - If mount point support is disabled, then you cannot mount any file systems. -

    -
  • -

    - CONFIG_NFILE_DESCRIPTORS > 4. - Of course you have to have file descriptions to use any thing in the file system. -

    -
  • -

    - CONFIG_FS_ROMFS enabled. - This option enables ROMFS file system support. -

    -
- -

- Default Start-Up Behavior. - The implementation that is provided is intended to provide great flexibility for the use of Start-Up files. - This paragraph will discuss the general behavior when all of the configuration options are set to the default values. -

-

- In this default case, enabling CONFIG_NSH_ROMFSETC will cause NSH to behave as follows at NSH start-up time: -

-
    -
  • -

    - NSH will create a read-only RAM disk (a ROM disk), containing a tiny ROMFS file system containing the following: -

    -
      -`--init.d/
-    `-- rcS
-
    -

    - Where rcS is the NSH start-up script. -

    -
  • -

    - NSH will then mount the ROMFS file system at /etc, resulting in: -

    -
      -|--dev/
-|   `-- ram0
-`--etc/
-    `--init.d/
-        `-- rcS
      -
    -
  • -

    - By default, the contents of rcS script are: -

    -
      -# Create a RAMDISK and mount it at /tmp
-
-mkrd -m 1 -s 512 1024
-mkfatfs /dev/ram1
-mount -t vfat /dev/ram1 /tmp
-
    -
  • -

    - NSH will execute the script at /etc/init.d/rcS at start-up (before the first NSH prompt). - After execution of the script, the root FS will look like: -

    -
      -|--dev/
-|   |-- ram0
-|   `-- ram1
-|--etc/
-|   `--init.d/
-|       `-- rcS
-`--tmp/
-
    -
- -

- Example Configurations. - Here are some configurations that have CONFIG_NSH_ROMFSETC=y in the NuttX configuration file. - They might provide useful examples: -

-
    -
  • boards/arm/stm32/hymini-stm32v/nsh2
    • -
  • boards/arm/dm320/ntosd-dm320/nsh
    • -
  • boards/sim/sim/sim/nsh
    • -
  • boards/sim/sim/sim/nsh2
    • -
  • boards/sim/sim/sim/nx
    • -
  • boards/sim/sim/sim/nx11
    • -
  • boards/sim/sim/sim/touchscreen
    • -
-

- In most of these cases, the configuration sets up the default /etc/init.d/rcS script. - The default script is here: apps/nshlib/rcS.template. - (The funny values in the template like XXXMKRDMINORXXX get replaced via sed at build time). - This default configuration creates a ramdisk and mounts it at /tmp as discussed above. -

-

- If that default behavior is not what you want, then you can provide your own custom rcS script by defining CONFIG_NSH_ARCHROMFS=y in the configuration file. -

-

- Modifying the ROMFS Image. - The contents of the /etc directory are retained in the file apps/nshlib/nsh_romfsimg.h OR, if CONFIG_NSH_ARCHROMFS is defined, include/arch/board/nsh_romfsimg.h. - In order to modify the start-up behavior, there are three things to study: -

- -
    -
  1. -

    - Configuration Options. - The additional CONFIG_NSH_ROMFSETC configuration options discussed with the other NSH-specific configuration settings. -

    -
  2. -

    - tools/mkromfsimg.sh Script. - The script tools/mkromfsimg.sh creates nsh_romfsimg.h. - It is not automatically executed. - If you want to change the configuration settings associated with creating and mounting the /tmp directory, then it will be necessary to re-generate this header file using the tools/mkromfsimg.sh script. -

    -

    - The behavior of this script depends upon several things: -

    -
      -
    1. -

      - The configuration settings then installed configuration. -

      -
    2. -

      - The genromfs tool(available from http://romfs.sourceforge.net) or included within the NuttX buildroot toolchain. - There is also a snapshot available in the NuttX tools repository here. -

      -
    3. -

      - The xxd tool that is used to generate the C header files (xxd is a normal part of a complete Linux or Cygwin installation, usually as part of the vi package). -

      -
    4. -

      - The file apps/nshlib/rcS.template (OR, if CONFIG_NSH_ARCHROMFS is defined include/arch/board/rcs.template. -

      -
    -
  3. -

    - rcS.template. - The file apps/nshlib/rcS.template contains the general form of the rcS file; configured values are plugged into this template file to produce the final rcS file. -

    -

    - To generate a custom rcS file a copy of rcS.template needs to be placed at tools/ and changed according to the desired start-up behaviour. - Running tools/mkromfsimg.h creates nsh_romfsimg.h which needs to be copied to apps/nshlib OR if CONFIG_NSH_ARCHROMFS is defined to boards/<arch>/<chip>/<board>/include. -

    -
- -

- rcS.template. - The default rcS.template, apps/nshlib/rcS.template, generates the standard, default apps/nshlib/nsh_romfsimg.h file. -

- -

- If CONFIG_NSH_ARCHROMFS is defined in the NuttX configuration file, then a custom, board-specific nsh_romfsimg.h file residing in boards/<arch>/<chip>/<board>/includewill be used. - NOTE when the OS is configured, include/arch/board will be linked to boards/<arch>/<chip>/<board>/include. -

- -

- All of the startup-behavior is contained in rcS.template. - The role of mkromfsimg.sh script is to (1) apply the specific configuration settings to rcS.template to create the final rcS, and (2) to generate the header file nsh_romfsimg.h containing the ROMFS file system image. - To do this, mkromfsimg.sh uses two tools that must be installed in your system: -

-
    -
  1. -

    - The genromfs tool that is used to generate the ROMFS file system image. -

    -
  2. -

    - The xxd tool that is used to create the C header file. -

    -
- - - - - -
-

6.0 Shell Login

 -
- - - - - -
-

6.1 Enabling Shell Logins

 -
-

- NuttShell sessions can be protected by requiring that the user supply username and password credentials at the beginning of the session. - Logins can be enabled for standard USB or serial consoles with: -

-
    -CONFIG_NSH_CONSOLE_LOGIN=y
-
-

- Logins for Telnet sessions can be enabled separately with: -

-
    -CONFIG_NSH_TELNET_LOGIN=y
-
-

- Logins can be enabled for either or both session types. - On a successful login, the user will have access to the NSH session: -

-
    -login: admin
-password:
-User Logged-in!
-
-NuttShell (NSH)
-nsh>
-
-

- After each failed login attempt, a delay can be set up. - The purpose of this delay is to discourage attempts to crack the password by brute force. - That delay is configured with -

-
    -CONFIG_NSH_LOGIN_FAILDELAY=0
-
-

- This setting provides the login failure delay in units of milliseconds. - The system will pause this amount of time after each failed login attempt. - After a certain number of failed login attempts, the session will be closed. - That number is controlled by: -

-
    -CONFIG_NSH_LOGIN_FAILCOUNT=3
-
- - - - - -
-

6.2 Verification of Credentials

 -
-

- There are three ways that NSH can be configured to verify user credentials at login time: -

-
    -
  1. -

    - The simplest implementation simply uses fixed login credentials and is selected with: -

    -
      -CONFIG_NSH_LOGIN_FIXED=y
-
    -

    - The fixed login credentials are selected via: -

    -
      -CONFIG_NSH_LOGIN_USERNAME=admin
-CONFIG_NSH_LOGIN_PASSWORD="Administrator"
-
    -

    - This is not very flexible since there can be only one user and the password is fixed in the FLASH image. This option is also not very secure because a malicious user could get the password by just looking at the .text stings in the flash image. -

    -
    2. -
  2. -

    - NSH can also be configured to defer the entire user credential verification to platform-specific logic with this setting: -

    -
      -CONFIG_NSH_LOGIN_PLATFORM=y
-
    -

    - In this case, NSH will call a platform-specific function to perform the verification of user credentials. - The platform-specific logic must provide a function with the following prototype: -

    -
      -int platform_user_verify(FAR const char *username, FAR const char *password);
-
    -

    - which is prototyped an described in apps/include/nsh.h and which may be included like: -

    -
      -#include <apps/nsh.h>
-
    -

    - An appropriate place to implement this function might be in the directory apps/platform/<board>. -

    -
  3. -

    - A final option is to use a password file contained encrypted password information. - This final option is selected with the following and described in more detail in the - following paragraph. -

    -
      -CONFIG_NSH_LOGIN_PASSWD=y
-
    -
    4. -
- - - - - -
-

6.3 Password Files

 -
-

- NuttX can also be configured to support a password file, by default at /etc/passwd. - This option enables support for a password file: -

-
    -CONFIG_NSH_LOGIN_PASSWD=y
-
-

-This options requires that you have selected CONFIG_FSUTILS_PASSWD=y to enable the access methods of apps/fsutils/passwd: -

-
    -CONFIG_FSUTILS_PASSWD=y
-
-

- And this determines the location of the password file in a mounted volume: -

-
    -CONFIG_FSUTILS_PASSWD_PATH="/etc/passwd"
-
-

- /etc/passwd is a standard location, but you will need to locate the password where ever you have a mounted volume. -

-

- The password file can be a fixed list of users in a ROMFS file system or a modifiable list maintained in a file in some writable file system. If the password file lies in a read-only file system like ROMFS, then you should also indicate that the password file is read-only. -

-
    -CONFIG_FSUTILS_PASSWD_READONLY=y
-
-

- If the password file is writable, then additional NSH commands will be enabled to modify the password file: useradd, userdel, and passwd. If you do not wish you have these commands available, then they should be specifically disabled. -

-

- The password file logic requires a few additional settings: -

    -
  1. -

    - The size of dynamically allocated and freed buffer that is used for file access: -

    -
      -CONFIG_FSUTILS_PASSWD_IOBUFFER_SIZE=512
-
    -
    2. -
  2. -

    - And the 128-bit encryption key. The password file currently uses the Tiny Encryption Algorithm (TEA), but could be extended to use something more powerful. -

    -
      -CONFIG_FSUTILS_PASSWD_KEY1=0x12345678
-CONFIG_FSUTILS_PASSWD_KEY2=0x9abcdef0
-CONFIG_FSUTILS_PASSWD_KEY3=0x12345678
-CONFIG_FSUTILS_PASSWD_KEY4=0x9abcdef0
-
    -
    3. -
-

- Password can only be decrypted with access to this key. Note that this key could potentially be fished out of your FLASH image, but without any symbolic information, that would be a difficult job since the TEA KEY is binary data and not distinguishable from other binary data in the FLASH image. -

-

- If the password file is enabled (CONFIG_NSH_LOGIN_PASSWD=y), then the fixed user credentials will not be used for the NSH session login. Instead, the password file will be consulted to verify the user credentials. -

- - - - - -
-

6.4 Creating a Password File for a ROMFS File System

 -
-

- What we want to accomplish is a ROMFS file system, mounted at /etc and containing the password file, passwd like: -

-
    -NuttShell (NSH)
-nsh> ls -Rl /etc
-/etc:
- dr-xr-xr-x       0 .
- dr-xr-xr-x       0 init.d/
- -r--r--r--      39 passwd
-/etc/init.d:
- dr-xr-xr-x       0 ..
- -r--r--r--     110 rcS
-nsh>
-
-

- Where /etc/init.d/rcS is the start-up script; /etc/passwd is a the password file. Note that here we assume that you are already using a start-up script. We can then piggyback the passwd file into the /etc file system already mounted for the NSH start up file as described above above. -

-

- I use the sim/nsh configuration to create a new password file, but other configurations could also be used. That configuration already supports a ROMFS file system, passwords, and login prompts. First, I make these changes to that configuration. -

-
    -
  1. -

    - Disable logins -

    -
      -- CONFIG_NSH_CONSOLE_LOGIN=y
-+ # CONFIG_NSH_CONSOLE_LOGIN is not set
-  # CONFIG_NSH_TELNET_LOGIN is not set
-
    -
    2. -
  2. -

    - Move the password file to a write-able file system: -

    -
      -- CONFIG_FSUTILS_PASSWD_PATH="/etc/passwd"
-+ CONFIG_FSUTILS_PASSWD_PATH="/tmp/passwd"
-
    -
    3. -
  3. -

    - Make the password file modifiable -

    -
      -- CONFIG_FSUTILS_PASSWD_READONLY=y
-# CONFIG_FSUTILS_PASSWD_READONLY is not set
-
    -
    4. -
-

- Now rebuild the simulation. No login should be required to enter the - shell and you should find the useradd, userdel, and passwd commands available in the help summary, provided that they are enabled. - Make certain that the useradd command is not disabled: -

-
    -# CONFIG_NSH_DISABLE_USERADD is not set
-
-

- Use the NSH useradd command to add new uses with new user passwords like: -

-
    -nsh> useradd <username> <password>
-
-

- Do this as many times as you would like. Each time that you do this a new - entry with an encrypted password will be added to the passwd file at - /tmp/passwd. You can see the content of the password file like: -

-
    -nsh> cat /tmp/passwd
-
-

- When you are finished, you can simply copy the /tmp/passwd content from the - cat command and paste it into an editor. Make sure to remove any - carriage returns that may have ended up on the file if you are using - Windows. -

-

- Then create/re-create the nsh_romfsimg.h file as described below. -

-
    -
  1. -

    - The content on the nsh_romfsimg.h header file is generated from a template directory structure. Create the directory structure: -

    -
      -mkdir etc
-mkdir etc/init.d
-
    -

    - And copy your existing startup script into etc/init.c as rcS. -

    -
    2. -
  2. -

    - Save your new password file in the etc/ directory as passwd. -

    -
    3. -
  3. -

    - Create the new ROMFS image. -

    -
      -genromfs -f romfs_img -d etc -V MyVolName
-
    -
    4. -
  4. -

    - Convert the ROMFS image to a C header file -

    -
      -xxd -i romfs_img >nsh_romfsimg.h
-
    -
    5. -
  5. -

    - Edit nsh_romfsimg.h: Mark both data definitions as const so that the data will be stored in FLASH. -

    -
    6. -
  6. -

    - Edit nsh_romfsimg.h, mark both data definitions as const so that that will be stored in FLASH. -

    -
    7. -
-

- There is a good example of how to do this in the NSH simulation configuration at boards/sim/sim/sim/configs/nsh. The ROMFS support files are provided at boards/sim/include and the README.txt file at the location provides detailed information about creating and modifying the ROMFS file system. -

- - - - - -
-

Index

 -
- - - - - -
- - -
- -
-
- - diff --git a/Documentation/NuttX.html b/Documentation/NuttX.html deleted file mode 100644 index 2e2b6e880d..0000000000 --- a/Documentation/NuttX.html +++ /dev/null @@ -1,7576 +0,0 @@ - - -NuttX - - - -
-
- - - - -
-

Table of Contents

-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Overview.
- What is NuttX? Look at all those files and features... How can it be a tiny OS? -
- NuttX Discussion Group.
- Do you want to talk about NuttX features? Do you need some help? Problems? Bugs? -
- Downloads.
- Where can I get NuttX? What is the current development status? -
- Supported Platforms.
- What target platforms has NuttX been ported to? -
- Development Environments.
- What kinds of host cross-development platforms can be used with NuttX? -
- Licensing.
- Are there any licensing restrictions for the use of NuttX? (Almost none) - Will there be problems if I link my proprietary code with NuttX? (No) -
- Release Notes - What has changed in the last release of NuttX? - What has changed in previous releases of NuttX? - Are there any unreleased changes. -
- Bugs, Issues, Things-To-Do.
- Software is never finished nor ever tested well enough. - (Do you want to help develop NuttX? If so, send me an email). -
- Other Documentation.
- What other NuttX documentation is available? -
- Trademarks.
- Some of the words used in this document belong to other people. -
-
-
- -
-
- - - - -
-

NuttX RTOS

-

Last Updated: April 16, 2020

-
-
- - - - - -
-

Overview

 -
- -

- Goals. - NuttX is a real time embedded operating system (RTOS). - Its goals are: -

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Small Footprint -

-

- Usable in all but the tightest micro-controller environments, - The focus is on the tiny-to-small, deeply embedded environment. -

-
- Rich Feature OS Set -

-

- The goal is to provide implementations of most standard POSIX OS interfaces - to support a rich, multi-threaded development environment for deeply embedded - processors. -

- NON-GOALS: It is not a goal to provide the level of OS features like those provided by Linux. - In order to work with smaller MCUs, small footprint must be more important than an extensive feature set. - But standard compliance is more important than small footprint. - Surely a smaller RTOS could be produced by ignoring standards. - Think of NuttX is a tiny Linux work-alike with a much reduced feature set. -

-
- Highly Scalable -

-

- Fully scalable from tiny (8-bit) to moderate embedded (32-bit). - Scalability with rich feature set is accomplished with: - Many tiny source files, link from static libraries, highly configurable, use of - weak symbols when available. -

-
- Standards Compliance -

-

- NuttX strives to achieve a high degree of standards compliance. - The primary governing standards are POSIX and ANSI standards. - Additional standard APIs from Unix and other common RTOS's are - adopted for functionality not available under these standards - or for functionality that is not appropriate for the deeply-embedded - RTOS (such as fork()). -

-

- Because of this standards conformance, software developed under other - standard OSs (such as Linux) should port easily to NuttX. -

-
- Real-Time -

-

- Fully pre-emptible; fixed priority, round-robin, and "sporadic" scheduling. -

-
- Totally Open -

-

- Non-restrictive BSD license. -

-
- GNU Toolchains -

-

- Compatible GNU toolchains based on buildroot - available for - download - to provide a complete development environment for many architectures. -

-
- -

- Feature Set. - Key features of NuttX include: -

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Standards Compliant Core Task Management -

-

-

  • Fully pre-emptible.
    • -

    -

    		-

    -

  • Naturally scalable.
    • -

    -

    		-

    -

  • Highly configurable.
    • -

    -

    		-

    -

  • - Easily extensible to new processor architectures, SoC architecture, or board architectures. - A Porting Guide is available. -
    • -

    -

    		-

    -

  • FIFO and round-robin scheduling.
    • -

    -

    		-

    -

  • Realtime, deterministic, with support for priority inheritance
    • -

    -

    		-

    -

  • Tickless Operation
    • -

    -

    		 -

    -

  • POSIX/ANSI-like task controls, named message queues, counting semaphores, clocks/timers, signals, pthreads, robust mutexes, cancellation points, environment variables, filesystem.
    • -

    -

    		 -

    -

  • Standard default signal actions (optional).
    • -

    -

    		 -

    -

  • VxWorks-like task management and watchdog timers.
    • -

    -

    		-

    -

  • BSD socket interface.
    • -

    -

    		-

    -

  • Extensions to manage pre-emption.
    • -

    -

    		 -

    -

  • Optional tasks with address environments (Processes).
    • -

    -

    		-

    -

  • Loadable kernel modules; lightweight, embedded shared libraries.
    • -

    -

    		-

    -

  • Memory Configurations: (1) Flat embedded build, (2) Protected build with MPU, and (3) Kernel build with MMU.
    • -

    -

    		-

    -

  • Memory Allocators: (1) standard heap memory allocation, (2) granule allocator, (3) shared memory, and (4) dynamically sized, per-process heaps.
    • -

    -

    		-

    -

  • Inheritable "controlling terminals" and I/O re-direction. Pseudo-terminals
    • -

    -

    		 -

    -

  • On-demand paging.
    • -

    -

    		-
  • System logging.
    • -

    -

    		-

    -

  • May be built either as an open, flat embedded RTOS or as a separately built, secure, monolithic kernel with a system call interface.
    • -

    -

    		-

    -

  • Built-in, per-thread CPU load measurements.
    • -

    -

    		-

    -

  • Well documented in the NuttX User Guide.
    • -

    -
    - File system -

    		-

    -

  • Tiny, in-memory, root pseudo-file-system.
    • -

    -

    		-

    -

  • Virtual file system (VFS) supports drivers and mountpoints.
    • -

    -

    		-

    -

  • - Mount-able volumes. Bind mountpoint, filesystem, and block device driver. -
    • -

    -

    		-

    -

  • Generic system logging (SYSLOG) support.
    • -

    -

    		-

    -

  • - FAT12/16/32 filesystem support with optional FAT long file name support1. -
    • -

    -

    		-

    -

  • - NFS Client. Client side support for a Network File System (NFS, version 3, UDP). -
    • -

    -

    		-

    -

  • - NXFFS. The tiny NuttX wear-leveling FLASH file system. -
    • -

    -

    		-

    -

  • - SMART. FLASH file system from Ken Pettit. -
    • -

    -

    		-

    -

  • - SPIFFS. FLASH file system, originally by Peter Anderson. -
    • -

    -

    		-

    -

  • - LittleFS. FLASH file system from ARM mbed.. -
    • -

    -

    		-

    -

  • ROMFS filesystem support (XIP capable).
    • -

    -

    		-

    -

  • CROMFS (Compressed ROMFS) filesystem support.
    • -

    -

    		-

    -

  • TMPFS RAM filesystem support.
    • -

    -

    		-

    -

  • BINFS pseudo-filesystem support.
    • -

    -

    		-

    -

  • HOSTFS filesystem support (simulation only).
    • -

    -

    		-

    -

  • Union filesystem - Supports combining and overlaying file systems.
    • -

    -

    		-

    -

  • UserFS - User application file system.
    • -

    -

    		-

    -

  • procfs/ pseudo-filesystem support.
    • -

    -

    		-

    -

  • - A binary loader with support for the following formats: -
      -
    • Separately linked ELF modules.
      • -
    • - Separately linked NXFLAT modules. - NXFLAT is a binary format that can be XIP from a file system. -
      • -
    • - "Built-In" applications.
      • - -
    -
    • -

    -

    		-

    -

  • PATH variable support.
    • -

    -

    		-

    -

  • - File transfers via TFTP and FTP (get and put), HTML (wget), and Zmodem (sz and rz). -
    • -
  • - Intel HEX file conversions. -
    • -

    -

    		-

    - 1 - FAT long file name support may be subject to certain Microsoft patent restrictions if enabled. - See the top-level COPYING file for details. -

    -
    - Device Drivers -

    		-

    -

  • Supports character and block drivers as well as specialized driver interfaces.
    • -

    -

    		-

    -

  • Full VFS integration.
    • -

    -

    		-

    -

  • Asynchronous I/O (AIO)
    • -

    -

    		-

    -

  • - Network, USB (host), USB (device), serial, I2C, I2S, NAND, CAN, ADC, DAC, PWM, Quadrature Encoder, I/O Expander, Wireless, generic timer, and watchdog timer driver architectures. -
    • -

    -

    		-

    -

  • - RAMDISK, pipes, FIFO, /dev/null, /dev/zero, /dev/random, and loop drivers. -
    • -

    -

    		-

    -

  • Generic driver for SPI-based or SDIO-based MMC/SD/SDH cards.
    • -

    -

    		-

    -

  • - Graphics: framebuffer drivers, graphic- and segment-LCD drivers. - VNC server. -
    • -

    -

    		-

    -

  • Audio subsystem: CODECs, audio input and output drivers. Command line and graphic media player applications.
    • -

    -

    		-

    -

  • Cryptographic subsystem.
    • -

    -

    		-

    -

  • Power Management sub-system.
    • -

    -

    		-

    -

  • ModBus support provided by built-in FreeModBus version 1.5.0.
    • -

    -
    - C/C++ Libraries -

    		-

    -

  • Standard C Library Fully integrated into the OS.
    • -

    -

    		-

    -

  • Includes floating point support via a Standard Math Library.
    • -

    -

    		-

    -

  • Add-on uClibc++ module provides Standard C++ Library (LGPL).
    • -

    -
    - Networking -

    		-

    -

  • Multiple network interface support; multiple network link layer support.
    • -

    -

    		-

    -

  • IPv4, IPv6, TCP/IP, UDP, ICMP, ICMPv6, IGMPv2 and MLDv1/v2 (client) stacks.
    • -

    -

    		-

    -

  • IP Forwarding (routing) support.
    • -

    -

    		-

    -

  • User space stacks.
    • -

    -

    		-

    -

  • Stream and datagram sockets.
    • -

    -

    		-

    -

  • Address Families: IPv4/IPv6 (AF_INET/AF_INET6), Raw socket (AF_PACKET), raw IEEE 802.15.4 (AF_IEEE802154), raw Bluetooth (AF_BLUETOOTH), and local, Unix domain socket support (AF_LOCAL).
    • -

    -

    		-

    -

  • Special INET protocol sockets: Raw ICMP and ICMPv6 protocol ping sockets (IPPROTO_ICMP/IPPROTO_ICMP6).
    • -

    -

    		-

    -

  • Custom user sockets.
    • -

    -

    		-

    -

  • IP Forwarding.
    • -

    -

    		-

    -

  • DNS name resolution / NetDB
    • -

    -

    		-

    -

  • IEEE 802.11 FullMac
    • -

    -

    		-

    -

  • Radio Network Drivers: IEEE 802.15.4 MAC, Generic Packet Radio, Bluetooth LE
    • -

    -

    		-

    -

  • 6LoWPAN for radio network drivers (IEEE 802.15.4 MAC and generic packet radios)
    • -

    -

    		-

    -

  • SLIP, TUN/PPP, Local loopback devices
    • -

    -

    		-

    -

  • A port cJSON
    • -

    -

    		-

    -

  • Small footprint.
    • -

    -

    		-

    -

  • BSD compatible socket layer.
    • -

    -

    		-

    -

  • Networking utilities (DHCP server and client, SMTP client, Telnet server and client, FTP server and client, TFTP client, HTTP server and client, PPPD, NTP client). - Inheritable TELNET server sessions (as "controlling terminal"). - VNC server.
    • -

    -

    		-

    -

  • ICMPv6 autonomous auto-configuration
    • -

    -

    		-

    -

  • - NFS Client. Client side support for a Network File System (NFS, version 3, UDP). -
    • -

    -

    		-

    -

  • - A NuttX port of Jeff Poskanzer's THTTPD HTTP server - integrated with the NuttX binary loader to provide true, embedded CGI. -
    • -

    -

    		-

    -

  • - PHY Link Status Management. -
    • -

    -

    		-

    -

  • - UDP Network Discovery (Contributed by Richard Cochran). -
    • -

    -

    		-

    -

  • - XML RPC Server (Contributed by Richard Cochran). -
    • -

    -

    		-

    -

  • - Support for networking modules (e.g., ESP8266). -
    • -

    -
    - FLASH Support -

    		-

    -

  • MTD-inspired interface for Memory Technology Devices.
    • -

    -

    		 -

    -

  • NAND support.
    • -

    -

    		 -

    -

  • FTL. Simple Flash Translation Layer support file systems on FLASH.
    • -

    -

    		 -

    -

  • Wear-Leveling FLASH File Systems: NXFFS, SmartFS, SPIFFS.
    • -

    -

    		 -

    -

  • Support for SPI-based FLASH and FRAM devices.
    • -

    -
    - USB Host Support -

    		-

    -

  • USB host architecture for USB host controller drivers and device-dependent USB class drivers.
    • -

    -

    		 -

    -

  • USB host controller drivers available for the Atmel SAMA5Dx, NXP LPC17xx, LPC31xx, and STmicro STM32
    • -

    -

    		 -

    -

  • Device-dependent USB class drivers available for USB mass storage, CDC/ACM serial, HID keyboard, and HID mouse.
    • -

    -

    		 -

    -

  • Seam-less support for USB hubs.
    • -

    -
    - USB Device Support -

    		-

    -

  • Gadget-like architecture for USB device controller drivers and device-dependent USB class drivers.
    • -

    -

    		 -

    -

  • USB device controller drivers available for the most MCU architectures includeing PIC32, Atmel AVR, SAM3, SAM4, SAMv7, and SAMA5Dx, NXP/Freescale LPC17xx, LPC214x, LPC313x, LPC43xx, and Kinetis, Silicon Laboraties EFM32, STMicro STM32 F1, F2, F3, F4, and F7, TI DM320, and others.
    • -

    -

    		 -

    -

  • Device-dependent USB class drivers available for USB serial (CDC/ACM and a PL2303 emulation), for USB mass storage, for USB networking (RNDIS and CDC/ECM), DFU, and for a dynamically configurable, composite USB devices.
    • -

    -

    		 -

    -

  • Built-in USB device and USB host trace functionality for non-invasive USB debug.
    • -

    -
    - Graphics Support -

    		-

    -

  • Framebuffer drivers.
    • -

    -

    		 -

    -

  • Graphic LCD drivers for both parallel and SPI LCDs and OLEDs.
    • -

    -

    		 -

    -

  • Segment LCD drivers.
    • -

    -

    		 -

    -

  • VNC Server.
    • -

    -

    		 -

    -

  • mmap-able, framebuffer character driver.
    • -

    -

    		 -

    -

  • - NX: A graphics library, tiny windowing system and tiny font support that works with either framebuffer or LCD drivers. - Documented in the NX Graphics Subsystem - manual. -
    • -

    -

    		 -

    -

  • Font management sub-system.
    • -

    -

    		 -

    -

  • - NxWidgets: NXWidgets is library of graphic objects, or "widgets," (labels, buttons, text boxes, images, sliders, progress bars, etc.). NXWidgets is written in C++ and integrates seamlessly with the NuttX NX graphics and font management subsystems. -
    • -

    -

    		 -

    -

  • - NxWM: NxWM is the tiny NuttX window manager based on NX and NxWidgets. -
    • -

    -
    - Input Devices -

    		-

    -

  • Touchscreen, USB keyboard, GPIO-based buttons and keypads.
    • -

    -
    - Analog Devices -

    		-

    -

  • Support for Analog-to-Digital conversion (ADC), Digital-to-Analog conversion (DAC), multiplexers, and amplifiers.
    • -

    -
    - Motor Control -

    		-

    -

  • Pulse width modulation (PWM) / Pulse count modulation.
    • -

    -
    - -

    - NuttX Add-Ons. - The following packages are available to extend the basic NuttX feature set: -

    -
    - - - - - - - - - - - - - - - - - - - -
    - NuttShell (NSH) -

    		-

    -

  • A small, scalable, bash-like shell for NuttX with rich feature set and small footprint. - See the NuttShell User Guide.
    • -

    -
    - BAS 2.4 -

    		-

    -

  • Seamless integration of Michael Haardt's BAS 2.4: - "Bas is an interpreter for the classic dialect of the programming language - BASIC. It is pretty compatible to typical BASIC interpreters of the 1980s, - unlike some other UNIX BASIC interpreters, that implement a different - syntax, breaking compatibility to existing programs. Bas offers many ANSI - BASIC statements for structured programming, such as procedures, local - variables and various loop types. Further there are matrix operations, - automatic LIST indentation and many statements and functions found in - specific classic dialects. Line numbers are not required."
    • -

    -
    - -

    - Look at all those files and features... How can it be a tiny OS?. - The NuttX feature list (above) is fairly long and if you look at the NuttX - source tree, you will see that there are hundreds of source files comprising - NuttX. How can NuttX be a tiny OS with all of that? -

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Lots of Features -- More can be smaller! -

    		-

    - The philosophy behind that NuttX is that lots of features are great... BUT - also that if you don't use those features, then you should not have to pay a penalty - for the unused features. - And, with NuttX, you don't! If you don't use a feature, it will not - be included in the final executable binary. - You only have to pay the penalty of increased footprint for the features - that you actually use. -

    -

    - Using a variety of technologies, NuttX can scale from the very tiny to - the moderate-size system. I have executed NuttX with some simple applications - in as little as 32K total memory (code and data). - On the other hand, typical, richly featured NuttX builds require more like 64K - (and if all of the features are used, this can push 100K). -

    -
    - Many, many files -- More really is smaller! -

    		-

    - One may be intimidated by the size NuttX source tree. There are hundreds of source files! - How can that be a tiny OS? - Actually, the large number of files is one of the tricks to keep NuttX small and - as scalable as possible. - Most files contain only a single function. - Sometimes just one tiny function with only a few lines of code. - Why? -

    -
      -
    • - Static Libraries. - Because in the NuttX build processed, objects are compiled and saved into - static libraries (archives). - Then, when the file executable is linked, only the object files that are needed - are extracted from the archive and added to the final executable. - By having many, many tiny source files, you can assure that no code that you do - not execute is ever included in the link. - And by having many, tiny source files you have better granularity -- - if you don't use that tiny function of even just a few lines of code, it will - not be included in the binary. -
      • -
    -
    - Other Tricks -

    		-

    - As mentioned above, the use of many, tiny source files and linking from static - libraries keeps the size of NuttX down. - Other tricks used in NuttX include: -

    -
      -
    • - Configuration Files. - Before you build NuttX, you must provide a configuration file that specifies - what features you plan to use and which features you do not. - This configuration file contains a long list of settings that control - what is built into NuttX and what is not. - There are hundreds of such settings - (see the Configuration Variable Documentation - for a partial list that excludes platform specific settings). - These many, many configuration options allow NuttX to be highly tuned to - meet size requirements. - The downside to all of these configuration options is that it greatly - complicates the maintenance of NuttX -- but that is my problem, not yours. -
      • -
    • - Weak Symbols - The GNU toolchain supports weak symbols and these also help to keep - the size of NuttX down. - Weak symbols prevent object files from being drawn into the link even if they - are accessed from source code. - Careful use of weak symbols is another trick for keep unused code out of the - final binary. -
      • -
    -
    - - - - - - -
    -

    NuttX Discussion Group

     -
    - -

    - Most NuttX-related discussion occurs on the Google NuttX group. - You are cordially invited to join. - In most cases, I make a special effort to answer any questions and provide any help that I can. -

    - - - - - -
    -

    Downloads

     -
    - -

    Git Repository

    -

    - The working version of NuttX is available from the Bitbucket GIT repository here. - That same page provides the URLs and instructions for cloning the GIT repository. -

    - -

    Released Versions

    -

    - In addition to the ever-changing GIT repository, there are frozen released versions of NuttX available. - The current release is NuttX 9.0. - NuttX 9.0 is the 134rd release of NuttX. - It was released on April 30, 2020, and is available for download from the - nuttx.apache.org website. - Note that the release consists of two tarballs: - apache-nuttx-9.0.x-incubating.tar.gz and - apache-nuttx-apps-9.0.x-incubating.tar.gz. - Both may be needed (see the top-level nuttx/README.txt file for build information). -

    - -

    Release Notes and Change Logs:

    - -
      -
    • nuttx. -

        - Release notes for all released versions on NuttX are available in GitHub. - The ReleaseNotes for the current release is at the bottom of that file. - The ChangeLog for all releases of NuttX is available in the ChangeLog file - that can viewed in GitHub. - The ChangeLog for the current release is at the bottom of that file. -

        -
      -
    • apps. -

        - Release notes for all released versions on NuttX are available in GitHub - The ReleaseNotes for the current release is at the bottom of that file. - The ChangeLog for all releases of apps/ is available in the - ChangeLog file that can viewed in the GitHub. - The ChangeLog for the current release is at the bottom of that file. -

        -
      -
    • NxWidgets. -

        -

        - As of NuttX-7.27, the content of the NxWidgets repository has been included within the apps/ package and no longer has separate releases. -

        -
      -
    • buildroot. -

        - Release notes for buildroot 1.14 are available here. - Release notes for all released versions on buildroot are available in the Bitbucket GIT - The ChangeLog for all releases of buildroot is available at the bottom of the ChangeLog file that can viewed in the Bitbucket GIT. -

        -
      -
    - - - - - -
    -

    Supported Platforms

     -
    - -

    Supported Platforms by CPU core. - The number of ports to this CPU follow in parentheses. - The state of the various ports vary from board-to-board. - Follow the links for the details: -

    -
    -
      -
    - - - - -
    -
  • Linux/Cygwin user mode simulation (1)
    • -
  • ARM - -
  • Atmel AVR - -
    • -
  • Freescale - -
    • -     		-
  • Intel - -
    • -
  • Microchip - -
    • -
  • Misoc - -
    • -
  • OpenRISC - -
    • -
  • Renesas/Hitachi: - -
    • -     		-
  • RISC-V (2) - -
    • -
  • Xtensa LX6: - -
    • -
  • ZiLOG - -
    • -
    - -

    Supported Platforms by Manufacturer/MCU Family. - CPU core type follows in parentheses. - The state of the various ports vary from MCU to MCU. - Follow the links for the details: -

    -
    -
      -
    - - - - - - -
    -
  • Allwinner -
      -
    • A10 (Cortex-A8)
      • -
    -
    • -
  • Broadcom - -
    • -
  • Espressif -
      -
    • ESP32 (Dual Xtensa LX6)
      • -
    -
  • GreenWaves -
      -
    • GAP8 (RISC-V RV32IM)
      • -
    -
    • -
  • Host PC based simulations - -
    • -
  • Infineon - -
    • -
  • Intel - -
    • -
  • Maxim Integrated - -
    • -
  • Microchip - -
    • -
  • Microchip (Formerly Atmel) - -
    • -
  • Moxa - -
    • -
  • nuvoTon - -
    • -
  • Nordic Semiconductor - -
    • -
  • NXP/Freescale - -
    • -     		-
  • NXP/Freescale (Continued) - - - - -
    • -
  • ON Semiconductor: -
      -
    • LC823450 (Dual core ARM Cortex-M3)
      • -
    -
    • -
  • Renesas/Hitachi: - -
    • -
  • Silicon Laboratories, Inc. - -
    • -
  • Sony. - -
    • -
  • STMicroelectronics - -
    • -     		-
  • STMicroelectronics (Continued) - -
  • Texas Instruments (some formerly Luminary) - -
    • -
  • ZiLOG - -
    • -     		- -
    - -

    - Details. - The details, caveats and fine print follow. - For even more information see the README files that can be found here. -

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  • (ARM Cortex-M3)
    • - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Linux User Mode. -

    		-

    - A user-mode port of NuttX to the x86 Linux/Cygwin platform is available. - The purpose of this port is primarily to support OS feature development. -

    -
      -

      - STATUS: - Does not support interrupts but is otherwise fully functional. - Refer to the NuttX README file for further information. -

      -
    -
    - ARM7TDMI. -

    		-

    - TI TMS320C5471 - (also called C5471 or TMS320DA180 or DA180). - NuttX operates on the ARM7 of this dual core processor. - This port uses the Spectrum Digital - evaluation board with a GNU arm-nuttx-elf toolchain* under Linux or Cygwin. -

    -
      -

      - STATUS: - This port is complete, verified, and included in the initial NuttX release. - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - NXP LPC214x. - Support is provided for the NXP LPC214x family of processors. In particular, - support is provided for (1) the mcu123.com lpc214x evaluation board (LPC2148) - and (1) the The0.net ZPA213X/4XPA development board (with the The0.net UG-2864AMBAG01 OLED) - This port also used the GNU arm-nuttx-elf toolchain* under Linux or Cygwin. -

    -
      -

      - STATUS: - This port boots and passes the OS test (apps/examples/ostest). - The port is complete and verified. As of NuttX 0.3.17, the port includes: - timer interrupts, serial console, USB driver, and SPI-based MMC/SD card - support. A verified NuttShell (NSH) - configuration is also available. - Refer to the NuttX board README files for the mcu123.com and for the ZPA213X/4XPA boards for further information. -

      -

      - Development Environments: - 1) Linux with native Linux GNU toolchain, 2) Cygwin/MSYS with Cygwin GNU toolchain, 3) Cygwin/MSYS - with Windows native toolchain (CodeSourcery or devkitARM), or 4) Native Windows. A DIY toolchain for Linux - or Cygwin is provided by the NuttX - buildroot - package. -

      -
    -


    		-

    - NXP LPC2378. - Support is provided for the NXP LPC2378 MCU. In particular, - support is provided for the Olimex-LPC2378 development board. - This port was contributed by Rommel Marcelo is was first released in NuttX-5.3. - This port also used the GNU arm-nuttx-elf toolchain* under Linux or Cygwin. -

    -
      -

      - STATUS: - This port boots and passes the OS test (apps/examples/ostest) and includes a - working implementation of the NuttShell (NSH). - The port is complete and verified. - As of NuttX 5.3, the port included only basic timer interrupts and serial console support. - In NuttX 7.1, Lizhuoyi contributed additional I2C and SPI drivers. - Refer to the NuttX board README file for further information. -

      -

      - Development Environments: (Same as for the NXP LPC214x). -

      -
    -


    		-

    - STMicro STR71x. - Support is provided for the STMicro STR71x family of processors. In particular, - support is provided for the Olimex STR-P711 evaluation board. - This port also used the GNU arm-nuttx-elf toolchain* under Linux or Cygwin. -

    -
      -

      - STATUS: - Integration is complete on the basic port (boot logic, system time, serial console). - Two configurations have been verified: (1) The board boots and passes the OS test - with console output visible on UART0, and the NuttShell (NSH) - is fully functional with interrupt driven serial console. An SPI driver is available - but only partially tested. Additional features are needed: USB driver, MMC integration, - to name two (the slot on the board appears to accept on MMC card dimensions; I have only - SD cards). - An SPI-based ENC28J60 Ethernet driver for add-on hardware is available and - but has not been fully verified on the Olimex board (due to issues powering the ENC28J60 add-on board). - Refer to the NuttX board README file for further information. -

      -

      - Development Environments: - 1) Linux with native Linux GNU toolchain, 2) Cygwin/MSYS with Cygwin GNU toolchain, 3) Cygwin/MSYS - with Windows native toolchain (CodeSourcery or devkitARM), or 4) Native Windows. A DIY toolchain for Linux - or Cygwin is provided by the NuttX - buildroot - package. -

      -
    -
    - ARM920T. -

    		-

    - Freescale MC9328MX1 or i.MX1. - This port uses the Freescale MX1ADS development board with a GNU arm-nuttx-elf toolchain* - under either Linux or Cygwin. -

    -
      -

      - STATUS: - This port has stalled due to development tool issues. - Coding is complete on the basic port (timer, serial console, SPI). - Refer to the NuttX board README file for further information. -

      -

      - NOTE: This port has been obsoleted. - I know longer have the hardware and the likelihood that the port would ever be completed is infitesmal. - The unfinished board support is still available in the Obsoleted repository if anyone would ever like to resurrect it. -

    -
    - ARM926EJS. -

    		-

    - TI TMS320DM320 - (also called DM320). - 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. -

    -
      -

      - STATUS: - The basic port (timer interrupts, serial ports, network, framebuffer, etc.) is complete. - All implemented features have been verified with the exception of the USB device-side - driver; that implementation is complete but untested. - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - NXP LPC3131. - Two boards based on the NXP LPC3131 are supported: -

    -
      -
    • -

      - First, a port for the NXP LPC3131 on the Embedded Artists EA3131 development board was first released in NuttX-5.1 (but was not functional until NuttX-5.2). -

      -
        -

        - STATUS: - The basic EA3131 port is complete and verified in NuttX-5.2. - This basic port includes basic boot-up, serial console, and timer interrupts. - This port was extended in NuttX 5.3 with a USB high speed driver contributed by David Hewson. - David also contributed I2C and SPI drivers plus several important LPC313x USB bug fixes that appear in the NuttX 5.6 release. - This port has been verified using the NuttX OS test, USB serial and mass storage tests and includes a working implementation of the NuttShell (NSH). -

        -

        - Support for on-demand paging has been developed for the EA3131. - That support would all execute of a program in SPI FLASH by paging code sections out of SPI flash as needed. - However, as of this writing, I have not had the opportunity to verify this new feature. -

        -

        - Refer to the Embedded Artists EA3131 board README file for further information. -

        -
      -
      • -
    • -

      - A second port to the NXP LPC3131 on the Olimex LPC-H3131 development board was added in NuttX-6.32. -

      -
        -

        - STATUS: - The basic H3131 port is complete and verified in NuttX-6.3. - It is similar to the EA3131 port except: (1) I have not yet gotten the SDRAM to work, and (2) this board was used to develop and verify the USB 2.0, low-/full-/high-speed EHCI host controller driver. - NOTE: That driver should work on the EA3131 as well. However, the EA3131 uses a PCA9532 PWM part to controller the port power so the it would not quite be a simple drop-in. -

        -

        - Refer to the Olimex LPC-H3131 board README file for further information. -

        -
      -
      • -
    -


    		- NXP LPC315x. - Support for the NXP LPC315x family has been incorporated into the code base as of NuttX-6.4. - Support was added for the Embedded Artists EA3152 board in NuttX-6.11. -

    -
      -

      - STATUS: - Basic support is in place for both the LPC3152 MCU and the EA3152 board. - Verification of the port was deferred due to tool issues - However, because of the high degree of compatibility between the LPC313x and LPC315x family, it - is very likely that the support is in place (or at least very close). - At this point, verification of the EA3152 port has been overcome by events and - may never happen. - However, the port is available for anyone who may want to use it. - Refer to the NuttX board README file for further information. -

      -
    -
    - Other ARMv4. -

    		-

    - MoxaRT - A port to the Moxa NP51x0 series of 2-port advanced RS-232/422/485 serial device servers was contributed by Anton D. Kachalov in NuttX-7.11. - This port includes a NuttShell (NSH) configuration with support for the Faraday FTMAC100 Ethernet MAC Driver. -

    -
    - ARM1176JZ. -

    		-

    - Broadcom BCM2708. - Very basic support for the Broadcom BCM2708 was released with NuttX-7.23. -

    - Raspberry Pi Zero. - This support was provided for the Raspberry Pi Zero which is based on the BCM2835. - Basic logic is in place but the port is incomplete and completely untested as of the NuttX-7.23 released. - Refer to the NuttX board README file for further information. -

    -

    - Obsoleted:: Support for the Raspberry Pi Zero was never completed. - The incomplete port along with all support for the BCM2708 was removed from the repository with the NuttX-7.28 release but can still be be found in the Obsoleted repository. -

    -
    - ARM Cortex-A5. -

    		-

    - Atmel SAMA5D2. -

    -

      -

    • Atmel SAMA5D2 Xplained Ultra development board. - This is the port of NuttX to the Atmel SAMA5D2 Xplained Ultra development board. - This board features the Atmel SAMA5D27 microprocessor. -

      -
        -

        - STATUS. - Initial support for the SAMA5D2 was released in NuttX-7.12. - This port is code complete but, however, still a work in progress and has not been verified in this this initial release. -

        -
      -
    -


    		-

    - Atmel SAMA5D3. - There are ports to two Atmel SAMA5D3 boards: -

    -

      -

    • Atmel SAMA5D3x-EK development boards. - This is the port of NuttX to the Atmel SAMA5D3x-EK development boards (where x=1,3,4, or 5). - These boards feature the Atmel SAMA5D3x microprocessors. - Four different SAMA5D3x-EK kits are available -

      - -

      - The each kit consist of an identical base board with different plug-in modules for each CPU. - All four boards are supported by NuttX with a simple reconfiguration of the processor type. -

      -
        -

        - STATUS. - Initial support for the SAMA5D3x-EK was released in NuttX-6.29. - That initial support was minimal: - There are simple test configurations that run out of internal SRAM and extended configurations that run out of the on-board NOR FLASH: -

        -
          -
        • - A barebones NuttShell (NSH) configuration that can be used as the basis for further application development. -
          • -
        • - A full-loaded NuttShell (NSH) configuration that demonstrates all of the SAMA5D3x features. -
          • -
        -

        - The following support was added in Nuttx 6.30: -

        -
          -
        • - DMA support, and -
          • -
        • - PIO interrupts, -
          • -
        -

        - And drivers for -

        -
          -
        • - SPI (with DMA support), -
          • -
        • - AT25 Serial Flash, -
          • -
        • - Two Wire Interface (TWI), and -
          • -
        • - HSMCI memory cards. -
          • -
        -

        - NuttX-6.30 also introduces full USB support: -

        -
          -
        • - High speed device controller driver, -
          • -
        • - OHCI (low- and full-speed) and -
          • -
        • - EHCI (high-speed) host controller driver support. -
          • -
        -

        - With NuttX-6.31, these additional drivers were added: -

        -
          -
        • - A 10/100Base-T Ethernet (EMAC) driver, -
          • -
        • - A 1000Base-T Ethernet (GMAC) driver, -
          • -
        • - A Real Time Clock (RTC) driver and integrated with the NuttX system time logic -
          • -
        • - /dev/random using the SAMA5D3x True Random Number Generator (TRNG), -
          • -
        • - A Watchdog Timer (WDT) driver, -
          • -
        • - A Timer/Counter (TC) library with interface that make be used by other drivers that need timer support, -
          • -
        • - An ADC driver that can collect multiple samples using the sequencer, can be trigger by a timer/counter, and supports DMA data transfers, -
          • -
        • - A touchscreen driver based on the special features of the SAMA5D3 ADC peripheral, - An LCD controller (LCDC) frame buffer driver, and -
          • -
        • - A CAN driver (Testing of the CAN has been delayed because of cabling issues). -
          • -
        -

        - Additional board configurations were added to test and demonstrate these new drivers including new graphics and NxWM configurations. -

        -

        - These drivers were added in NuttX-6.32: -

        -
          -
        • - A PWM driver with DMA support -
          • -
        • - An SSC-based I2S driver -
          • -
        • - Support for Programmable clock outputs -
          • -
        • - NAND support including support for the PMECC hardware ECC and for DMA transfers. -
          • -
        -

        - DBGU support was added in NuttX-7.2 (primarily for the SAMA5D3 Xplained board). -

        -

        - NuttX-7.4 added support for the on-board WM8904 CODEC chip and for Tickless operation. -

        -

        - Refer to the NuttX board README file for further information. -

        -
      -
    • -

      - Atmel SAMA5D3 Xplained development board - This is the port of NuttX to the Atmel SAMA5D3 Xplained development board. - The board features the Atmel SAMA5D36 microprocessor. - See the Atmel Website for additional information about this board. -

      -

      - STATUS. - This port is complete as of this writing and ready for general use. - The basic port is expected to be simple because of the similarity to the SAMAD3x-EK boards and is available in the NuttX 7.2 release. -

      -

      - Most of the drivers and capabilities of the SAMA5D3x-EK boards can be used with the SAMA5D3 Xplained board. - The primary difference between the ports is that the SAMA5D3x-EK supports NOR FLASH and NuttX can be configured to boot directly from NOR FLASH. - The SAMA5D3 Xplained board does not have NOR FLASH and, as a consequence NuttX must boot into SDRAM with the help of U-Boot. -

      -

      - Refer to the NuttX board README file for further information. -

      -
      • -
    -


    		-

    - Atmel SAMA5D4. - There is a port in progress on one Atmel SAMA5D4 board: -

    -

      -

    • Atmel SAMA5D4-EK/MB development boards - This is the port of NuttX to the Atmel SAMA5D4-MB Rev C. development board (which should be compatible with the SAMA5D4-EK). - These boards feature the Atmel SAMA5D44 microprocessors with compatibility with most of the SAMA5D3 peripherals. -

      -

      STATUS. - At the time of the release of NuttX-7.3, the basic port for the SAMA5D4-MB was complete. - The board had basic functionality. - But full functionality was not available until NuttX-7.4. - In NuttX-7.4 support was added for the L2 cache, many security features, XDMAC, HSMCI and Ethernet integrated with XDMAC, the LCDC, TWI, SSC, and most of the existing SAMA5 drivers. - Timers were added to support Tickless operation. - The TM7000 LCDC with the maXTouch multi-touch controller are also fully support in a special NxWM configuration for that larger display. - Support for a graphics media player is included (although there were issues with the WM8904 audio CODEC on my board). - An SRAM bootloader was also included. - Refer to the NuttX board README file for current status. -

      • -
    -


    		-

    - Development Environments: - 1) Linux with native Linux GNU toolchain, 2) Cygwin/MSYS with Cygwin GNU toolchain, 3) Cygwin/MSYS with Windows native toolchain, or 4) Native Windows. - All testing has been performed with the CodeSourcery toolchain (GCC version 4.7.3) in the Cygwin environment under Windows. -

    -
    - ARM Cortex-A8. -

    		-

    - Allwinner A10. - These following boards are based on the Allwinner A10 have are supported by NuttX: -

    -
      -
    • -

      - pcDuino v1. - A port of NuttX to the pcDuino v1 board was first released in NuttX-6.33. - See http://www.pcduino.com/ for information about pcDuino Lite, v1, and v2 boards. - These boards are based around the Allwinner A10 Cortex-A8 CPU. - This port was developed on the v1 board, but the others may be compatible: -

      -

      - Refer to the NuttX board README file for further information. -

      -

      - STATUS. - This port was an experiment was was not completely developed. - This configuration builds and runs an NuttShell (NSH), but only if a patch to work around some issues is applied. - While not 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. -

      -
      • -
    -


    		-

    - TI/Sitara AM335x. - These following boards are based on the TI/Sitara AM335x are supported by NuttX: -

    -
      -
    • -

      - Beaglebone Black. - A port of NuttX to the Beaglebone Black board was first released in NuttX-7.28. - This port was contributed by Petro Karashchenko. - This board is based on the TI/Sitara AM3358 Cortex-A8 CPU running 1GHz. -

      -
        -
      • - NuttX-7.28. - This initial port in NuttX-7.28 is very sparse. - While not ready for prodcution use, the Beaglebone Black port is functional and will be the basis for a more extensive development. - Additional work in progress to extend this port and more capable is anticipated in NuttX-7.29. -
        • -
      • - NuttX-9.0 - CAN support was added. - Clock Configuration was added. -
        • -
      • - NuttX-7.31. - An LCD driver was added in NuttX-7.31. -
        • -
      -

      - Refer to the Beaglebone Black board README file for further, up-to-date information. -

      -
      • -
    -
    - ARM Cortex-A9. -

    		-

    - NXP/Freescale i.MX6. - The basic port has been completed for the following i.MX6 board -

    -

      -
    • -

      - Sabre-6Quad. - This is a port to the NXP/Freescale Sabre-6Quad board. - Refer to the NuttX board README file for further information. -

      -

      - STATUS: - The basic, minimal port is code complete and introduced in NuttX-7.15, but had not yet been tested at that time due to the inavailability of hardware. - This basic port was verified in the NuttX-7.16 release, however. - The port is still minimal and more device drivers are needed to make the port usable. -

      -

      - Basic support of NuttX running in SMP mode on the i.MX6Q was also accomplished in NuttX-7.16. - However, there are still known issues with SMP support on this platform as described in the README file for the board. -

      -
      • -
    -
    - ARM Cortex-R4. -

    		-

    - TI/Hercules TMS570LS04xx. - A port is available for the Texas Instruments Hercules TMS570LS04x/03x LaunchPad Evaluation Kit (LAUNCHXL-TMS57004) featuring the Hercules TMS570LS0432PZ chip. -

    -
      -

      - STATUS. - My porting efforts were stalled due to tool-related issues. - Refer to the NuttX board README file for further information. - However, my understanding is that other people have successfully completed the port and submitted changes to the NuttX repository. -

      -

      - Toolchain: - The TMS570 is a big-endian ARM platform and requires a big-endian ARM toolchain. - All testing has been performed using a big-endian NuttX buildroot toolchain. - Instructions for building this toolchain are included in the board README file. -

      -
    -

    		-

    - TI/Hercules TMS570LS31xx. - Architecture support for the TMS570LS3137ZWT part was added in NuttX 7.25 by Ivan Ucherdzhiev. - Ivan also added support for the TI Hercules TMS570LS31x USB Kit. -

    -
      -

      - STATUS. - Refer to the NuttX board README file for further information. -

      -

      - Toolchain: - See discussion related to the TI/Hercules TMS570LS04xx above. -

      -
    -
    - ARM Cortex-M0/M0+. -

    		-

    - nuvoTon NUC120. - This is a port of NuttX to the nuvoTon NuTiny-SDK-NUC120 that features the NUC120LE3AN MCU. -

    -
      -

      - STATUS. - Initial support for the NUC120 was released in NuttX-6.26. - This initial support is very minimal: - There is a NuttShell (NSH) configuration that might be the basis for an application development. - As of this writing, more device drivers are needed to make this a more complete port. - Refer to the NuttX board README file for further information. -

      -

      - Memory Usage. - For a full-featured RTOS such as NuttX, providing support in a usable and meaningful way within the tiny memories of the NUC120 demonstrates the scalability of NuttX. The NUC120LE2AN comes in a 48-pin package and has 128KB FLASH and 16KB of SRAM. - When running the NSH configuration (itself a full up application), there is still more than 90KB of FLASH and 10KB or SRAM available for further application development). -

      -

      - Static memory usage can be shown with size command: -

      - 
        -$ size nuttx
-   text    data     bss     dec     hex filename
-  35037     106    1092   36235    8d8b nuttx
-
      -

      - NuttX, the NSH application, and GCC libraries use 34.2KB of FLASH leaving 93.8KB of FLASH (72%) free from additional application development. - Static SRAM usage is about 1.2KB (<4%) and leaves 14.8KB (86%) available for heap at runtime. - SRAM usage at run-time can be shown with the NSH free command: -

      - 
        -NuttShell (NSH) NuttX-6.26
-nsh> free
-             total       used       free    largest
-Mem:         14160       3944      10216       10216
-nsh>
-
      -

      - You can see that 10.0KB (62%) is available for further application development. -

      -

      - Development Environments: - 1) Linux with native Linux GNU toolchain, 2) Cygwin/MSYS with Cygwin GNU toolchain, 3) Cygwin/MSYS - with Windows native toolchain, or 4) Native Windows. - A DIY toolchain for Linux or Cygwin is provided by the NuttX - buildroot package. -

      -


    		-

    - FreeScale KL25Z. - There are two board ports for the KL25Z parts: -

    -
      -

      Freedom KL25Z. - This is a port of NuttX to the Freedom KL25Z board that features the MKL25Z128 Cortex-M0+ MCU, 128KB of FLASH and 16KB of SRAM. - See the Freescale website for further information about this board. -

      -
        -

        - STATUS. - This is the work of Alan Carvalho de Assis. - Verified, initial, minimal support for the Freedom KL25Z is in place in NuttX 6.27 and 6.28: - There is a working NuttShell (NSH) configuration that might be the basis for an application development. - As of NuttX-6.28 more device driver development would be needed to make this a complete port, particularly to support USB OTG. - A TSI and a SPI driver were added in NuttX-6.29. - Alan contributed a PWM driver in NuttX-6.32. - Refer to the Freedom KL25Z board README file for further information. -

        -
      -

      - PJRC Teensy-LC. - This is a port of NuttX to the PJRC Teensy-LC board that features the MKL25Z64 Cortex-M0+ MCU, 64KB of FLASH and 8KB of SRAM. - The Teensy LC is a DIP style breakout board for the MKL25Z64 and comes with a USB based bootloader. - See the Freescale website for further information about this board. -

      -
        -

        - STATUS. - This is the work of Michael Hope. - Verified, initial support for the Teensy-LC first appeared in NuttX-7.10. - Refer to the Teensy-LC board README file for further information. -

        -
      -
    -


    		-

    - FreeScale Freedom KL26Z. - This is a port of NuttX to the Freedom KL25Z board that features the MK26Z128VLH4 Cortex-M0+ MCU, 128KB of FLASH and 16KB of SRAM. - See the Freescale website for further information about this board. -

    -
      -

      - STATUS. - This work was contributed in NuttX 7.8 by Derek B. Noonburg. - The board support is very similar to the Freedom-KL25Z. - It was decided to support this a a separate board, however, due to some small board-level differences. - Refer to the Freedom KL26Z board README file for further information. -

      -
    -


    		-

    - Atmel SAMD20. - The port of NuttX to the Atmel SAMD20-Xplained Pro development board. - This board features the ATSAMD20J18A MCU (Cortex-M0+ with 256KB of FLASH and 32KB of SRAM). -

    -
      -

      - STATUS. - The initial SAMD20 Xplained Pro release (NuttX 7.1) included a functional NuttShell (NSH) configuration. - An SPI driver was also included to support the OLED1 and I/O1 modules. - That SPI driver, however, was not completely verified due to higher priority tasks that came up (I hope to get back to this later). - Refer to the SAMD20 Explained Pro board README file for further information. -

      -

      - The fully verified SPI driver appeared in the NuttX-7.22 release. -

      -
    -


    		-

    - Atmel SAMD21. - There two boards supported for the SAMD21: -

    -
      -
    1. - The port of NuttX to the Atmel SAMD21-Xplained Pro development board added in NuttX-7.11, and -
      2. -
    2. - The port of NuttX to the Arduino-M0 contributed by Alan Carvalho de Assis in NuttX-8.2. The initial release included nsh and usbnsh configurations. -
      3. -
    - -


    		-

    - Atmel SAML21. - The port of NuttX to the Atmel SAML21-Xplained Pro development board. - This board features the ATSAML21J18A MCU (Cortex-M0+ with 256KB of FLASH and 32KB of SRAM). -

    -
      -

      - STATUS. - Initial support for the SAML21 Xplained Pro was release in the NuttX 7.10. - This initial support included a basic configuration for the NuttShell (NSH) - (see the NSH User Guide). - Refer to the SAML21 Explained Pro board README file for further information. -

      -

      - The fully verified SPI driver appeared in the NuttX-7.22 release along with an I2C and USB device driver. -

      -
    -


    		-

    - NXP LPC11xx. - Support is provided for the NXP LPC11xx family of processors. - In particular, support is provided for LPCXpresso LPC1115 board. - This port was contributed by Alan Carvalho de Assis. -

    -
      -

      - STATUS: - The first released version was provided in NuttX 7.10. - Refer to the board README.txt file for further information. -

      -

      - Obsoleted: - Support for the LPCXpresso-LPC1115 and for the LPC1115 architecture in general was removed after NuttX-7.30. - The LPC11 port was never really used (to my knowledge) and was no longer supported. - A snapshot of the port is still available in the Obsoleted repository. - It can be brought back into the main repository at any time if anyone is willing to provide support for the architecture. -

      -
    -


    		-

    - NXP S32K11x. - Support is provided for the NXP S32K11x family of processors and, in particular, the S32K118EVB development board. -

    -
      -

      - STATUS: - The first released version was provided in NuttX 8.1. - The S32K118EVB port port provides a minimal NSH configuration. - Refer to the S32K118EVB board README.txt file for further information. -

      -
    -
    - ARM Cortex-M3. -

    		-

    - TI/Stellaris LM3S6432. - This is a port of NuttX to the Stellaris RDK-S2E Reference Design Kit and the MDL-S2E Ethernet to Serial module - (contributed by Mike Smith). -

    -


    		-

    - TI/Stellaris LM3S6432S2E. - This port uses Serial-to-Ethernet Reference Design Kit (RDK-S2E) and has similar support as for the other Stellaris family members. - A configuration is available for the NuttShell (NSH) - (see the NSH User Guide). - The NSH configuration including networking support with a Telnet NSH console. - This port was contributed by Mike Smith. -

    -
      -

      - STATUS: - This port was was released in NuttX 6.14. - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - TI/Stellaris LM3S6918. - This port uses the Micromint Eagle-100 development - board with a GNU arm-nuttx-elf toolchain* under either Linux or Cygwin. -

    -
      -

      - STATUS: - The initial, release of this port was included in NuttX version 0.4.6. - The current port includes timer, serial console, Ethernet, SSI, and microSD support. - There are working configurations to run the NuttShell - (NSH), the NuttX networking test, and the uIP web server. - Refer to the NuttX board README file for further information. -

      -
    -

    - Development Environments: - 1) Linux with native Linux GNU toolchain, 2) Cygwin/MSYS with Cygwin GNU toolchain, 3) Cygwin/MSYS - with Windows native toolchain (CodeSourcery or devkitARM), or 4) Native Windows. A DIY toolchain for Linux - or Cygwin is provided by the NuttX - buildroot - package. -

    -


    		-

    - TI/Stellaris LM3S6965. - This port uses the Stellaris LM3S6965 Ethernet Evaluation Kit with a GNU arm-nuttx-elf toolchain* - under either Linux or Cygwin. -

    -
      -

      - STATUS: - This port was released in NuttX 5.5. - Features are the same as with the Eagle-100 LM3S6918 described above. - The apps/examples/ostest configuration has been successfully verified and an - NSH configuration with Telnet support is available. - MMC/SD and Networking support was not been thoroughly verified: - Current development efforts are focused on porting the NuttX window system (NX) - to work with the Evaluation Kits OLED display. -

      -

      - NuttX-9.0 added protected build support to the LM3S6965-ek. -

      -

      - NOTE: As it is configured now, you MUST have a network connected. - Otherwise, the NSH prompt will not come up because the Ethernet - driver is waiting for the network to come up. - Refer to the NuttX board README file for further information. -

      -
    -

    - Development Environments: See the Eagle-100 LM3S6918 above. -

    -


    		-

    - TI/Stellaris LM3S8962. - This port uses the Stellaris EKC-LM3S8962 Ethernet+CAN Evaluation Kit with a GNU arm-nuttx-elf toolchain* - under either Linux or Cygwin. - Contributed by Larry Arnold. -

    -
      -

      - STATUS: - This port was released in NuttX 5.10. - Features are the same as with the Eagle-100 LM3S6918 described above. - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - TI/Stellaris LM3S9B92. - Architectural support for the LM3S9B92 was contributed by Lwazi Dube in NuttX 7.28. No board support for boards using the LM3S9B92 are currently available. -

    -


    		-

    - TI/Stellaris LM3S9B96. - Header file support was contributed by Tiago Maluta for this part. - Jose Pablo Rojas V. is used those header file changes to port NuttX to the TI/Stellaris EKK-LM3S9B96. - That port was available in the NuttX-6.20 release. - Refer to the NuttX board README file for further information. -

    -


    		-

    - TI/SimpleLink CC13x0. - Basic, unverified architectural support for the CC13x0 was added in NuttX-7.28. - This is a work in progress and, with any luck, a fully verified port will be available in NuttX-7.29. -

    -


    		-

    - SiLabs EFM32 Gecko. - This is a port for the Silicon Laboratories' EFM32 Gecko family. - Board support is available for the following: -

    -
      -
    1. -

      - SiLabs EFM32 Gecko Starter Kit (EFM32-G8XX-STK). - The Gecko Starter Kit features: -

      -

        -
      • EFM32G890F128 MCU with 128 kB flash and 16 kB RAM -
      • 32.768 kHz crystal (LXFO) and 32 MHz crystal (HXFO) -
      • Advanced Energy Monitoring -
      • Touch slider -
      • 4x40 LCD -
      • 4 User LEDs -
      • 2 pushbutton switches -
      • Reset button and a switch to disconnect the battery. -
      • On-board SEGGER J-Link USB emulator -
      • ARM 20 pin JTAG/SWD standard Debug in/out connector -
      -

      - STATUS. - The basic port is verified and available now. This includes - on-board LED and button support and a serial console available - on LEUART0. A single configuration is available using the - NuttShell NSH and the LEUART0 serial console. - DMA and USART-based SPI supported are included, but not fully tested. -

      -

      - Refer to the EFM32 Gecko Starter Kit README.txt file for further information. -

      -
      2. -
    2. -

      - Olimex EFM32G880F120-STK. - This board features: -

      -
        -
      • EFM32G880F128 with 128 kB flash and 16 kB RAM -
      • 32.768 kHz crystal (LXFO) and 32 MHz crystal (HXFO) -
      • LCD custom display -
      • DEBUG connector with ARM 2x10 pin layout for programming/debugging with ARM-JTAG-EW -
      • UEXT connector -
      • EXT extension connector -
      • RS232 connector and driver -
      • Four user buttons -
      • Buzzer -
      -

      - STATUS. - The board support is complete but untested because of tool-related issues. An OpenOCD compatible, SWD debugger would be required to make further progress in testing. -

      -

      - Refer to the Olimex EFM32G880F120-STK README.txt for further information. -

      -
      3. -
    -


    		-

    - SiLabs EFM32 Giant Gecko. - This is a port for the Silicon Laboratories' EFM32 Giant Gecko family. - This board features the EFM32GG990F1024 MCU with 1 MB flash and 128 kB RAM. -

    - Board support is available for the following: -

    -
      -
    • -

      - SiLabs EFM32 Giant Gecko Starter Kit t (EFM32GG-STK3700). - The Gecko Starter Kit features: -

      -

        -
      • EFM32GG990F1024 MCU with 1 MB flash and 128 kB RAM -
      • 32.768 kHz crystal (LXFO) and 48 MHz crystal (HXFO) -
      • 32 MB NAND flash -
      • Advanced Energy Monitoring -
      • Touch slider -
      • 8x20 LCD -
      • 2 user LEDs -
      • 2 user buttons -
      • USB interface for Host/Device/OTG -
      • Ambient light sensor and inductive-capacitive metal sensor -
      • EFM32 OPAMP footprint -
      • 20 pin expansion header -
      • Breakout pads for easy access to I/O pins -
      • Power sources (USB and CR2032 battery) -
      • Backup Capacitor for RTC mode -
      • Integrated Segger J-Link USB debugger/emulator -
      -

      - STATUS. -

      -
        -
      • - The basic board support for the Giant Gecko was introduced int the NuttX source tree in NuttX-7.6. - A verified configuration was available for the basic NuttShell (NSH) using LEUART0 for the serial console. -
        • -
      • - Development of USB support is in started, but never completed. -
        • -
      • - Reset Management Unit (RMU) was added Pierre-noel Bouteville in NuttX-7.7. -
        • -
      -
      • -
    -


    		-

    - STMicro STM32L152 (STM32L "EnergyLite" Line). - Two boards are supported: -

    -

      -
    • -

      STM32L-Discovery. - This is a port of NuttX to the STMicro STM32L-Discovery development board. - The STM32L-Discovery board is based on the STM32L152RBT6 MCU (128KB FLASH and 16KB of SRAM). -

      -

      - The STM32L-Discovery and STM32L152C DISCOVERY kits are functionally equivalent. - The difference is the internal Flash memory size (STM32L152RBT6 with 128 Kbytes or STM32L152RCT6 with 256 Kbytes). - Both boards feature: -

      -
        -
      • An ST-LINK/V2 embedded debug tool interface,
        • -
      • LCD (24 segments, 4 commons),
        • -
      • LEDs,
        • -
      • Pushbuttons,
        • -
      • A linear touch sensor, and
        • -
      • Four touchkeys.
        • -
      -
      • -
    • -

      Nucleo-L152RE. - Board support for the Nucleo-L152RE was contributed by Mateusz Szafoni in NuttX-7.28. - Available configurations include NSH, ADC, and PWM. -

      -
      • -
    -

    - STATUS. - Initial support for the STM32L-Discovery was released in NuttX-6.28. - Addition (architecture-only) support for the STM32L152xC family was added in NuttX-7.21. - Support for the Nucleo-L152RE was added in NuttX-7.28. -

    -

    - That initial STM32L-Discovery support included a configuration using the NuttShell (NSH) that might be the basis for an application development. - A driver for the on-board segment LCD is included as well as an option to drive the segment LCD from an NSH "built-in" command. - Refer to the STM32L-Discovery board README file for further information. -

    -

    - Memory Usage. -

    - REVISIT: These numbers are out of date. Current NuttX sizing might be somewhat larger. -
    - For a full-featured RTOS such as NuttX, providing support in a usable and meaningful way within the tiny memories of the STM32L152RBT6 demonstrates the scalability of NuttX. The STM32L152RBT6 comes in a 64-pin package and has 128KB FLASH and 16KB of SRAM. -

    -

    - Static memory usage can be shown with size command: -

    - 
      -$ size nuttx
-   text    data     bss     dec     hex filename
-  39664     132    1124   40920    9fd8 nuttx
-
    -

    - NuttX, the NSH application, and GCC libraries use 38.7KB of FLASH leaving 89.3B of FLASH (70%) free from additional application development. - Static SRAM usage is about 1.2KB (<4%) and leaves 14.8KB (86%) available for heap at runtime. -

    - SRAM usage at run-time can be shown with the NSH free command: - 
      -NuttShell (NSH) NuttX-6.27
-nsh> free
-             total       used       free    largest
-Mem:         14096       3928      10168      10168
-nsh>
-
    -

    - You can see that 9.9KB (62%) of SRAM heap is still available for further application development while NSH is running. -

    -


    		-

    - STMicro STM32L152x/162x (STM32 L1 "EnergyLite" Medium+ Density Family). - Support for the STM32L152 and STM32L162 Medium+ density parts from Jussi Kivilinna and Sami Pelkonen was included in NuttX-7.3, extending the basic STM32L152x support. - This is architecture-only support, meaning that support for the boards with these chips is available, but no support for any publicly available boards is included. -

    -


    		-

    - STMicro STM32F0xx (STM32 F0, ARM Cortex-M0). - Support for the STM32 F0 family was contributed by Alan Carvalho de Assis in NuttX-7.21. - There are ports to three different boards in this repository: -

    -
      -
    • - STM32F0-Discovery - This board features the STM32 2F051R8 and was used by Alan to produce the initial STM32 F0 port. - However, its very limited 8KB SRAM makes this port unsuitable for for usages. - Contributed by Alan Carvalho de Assis in NuttX-7.21. -
      • -
    • - Nucleo-F072RB - With 16KB of SRAM the STM32 F072RB makes a much more usable platform. -
      • -
    • - Nucleo-F091RC - With 32KB of SRAM the STM32 F091RC this board is a great match for NuttX. - Contributed by Juha Niskanen in NuttX-7.21. -
      • -
    -

    		-

    - STMicro STM32L0xx (STM32 L0, ARM Cortex-M0). - Support for the STM32 FL family was contributed by Mateusz Sfafoni in NuttX-7.28. - There are ports to two different STM32 L0 boards in the repository: -

    -
      -
    • - B-L072Z-LRWAN1 - Contributed byMateusz Sfafoni in NuttX-7.28. -
      • -
    • - Nucleo-L073RZ - Contributed byMateusz Sfafoni in NuttX-7.28. -
      • -
    -

    		 -

    - STMicro STM32G0xx (STM32 G0, ARM Cortex-M0+). - Support for the STM32 FL family was contributed by Mateusz Sfafoni in NuttX-7.28. - There are ports to two different STM32 L0 boards in the repository: -

    -
      -
    • - Nucleo-G071RB - Initial support for Nucleo-G071RB was contributed by Mateusz Szafoni in NuttX-7.31. - Refer to the board README file for further information. -
      • -
    • - Nucleo-G070RB - Contributed by Daniel Pereira Volpato. in NuttX-8.2. - Refer to the board README file for further information. -
      • -
    -

    		 -

    - STATUS: - Status for the STM32F0xx, STM32L0xx, and STM32G0xx is shown together since these parts share many drivers in common. -

    -
      -
    • - NuttX-7.21. - In this initial release, the level of support for the STM32 F0 family is minimal. - Certainly enough is in place to support a robust NSH configuration. - There are also unverified I2C and USB device drivers available in - NuttX-7.21. -
      • -
    • - NuttX-7.28 - Added support for GPIO EXTI. From Mateusz Sfafoni. -
      • -
    • - NuttX-7.29 - Added an SPI driver. From Mateusz Sfafoni. -
      • -
    • - NuttX-7.30 - Added ADC and I2C drivers. From Mateusz Szafoni. - Add AES and RND drivers for the L0. From Mateusz Szafoni. - Add support for HS148 for L0. From Mateusz Szafoni. -
      • -
    • - NuttX-8.2 - Added PWM and TIM drivers for the G0. From Daniel Pereira Volpato. -
      • -
    • - NuttX-9.0 - Added I2C support for F0, L0 and G0. -
      • -

      -


    		-

    - STMicro STM32F100x (STM32 F1 "Value Line"Family). -

    -
      -
    • -

      - Proprietary Boards - Chip support for these STM32 "Value Line" family was contributed by Mike Smith and users have reported that they have successful brought up NuttX on their proprietary boards using this logic. -

      -
      • -
    • -

      - STM32VL-Discovery. - In NuttX-6.33, support for the STMicro STM32VL-Discovery board was contributed by Alan Carvalho de Assis. - The STM32VL-Discovery board features an STM32F100RB MCU. - Refer to the NuttX board README file for further information. -

      -
      • -
    -


    		 -

    - STMicro STM32F102. - Architecture support (only) for the STM32 F102 family was contributed by the PX4 team in NuttX-7.7. -

    -
      -

      - STATUS: - Architecture support only is provided. - No specific STM32 F102 boards are supported. -

      -
    -


    		-

    - STMicro STM32F103C4/8 (STM32 F1 Low- and Medium-Density Family). - There are two ports available for this family: -

    -
      -
    • -

      - One port is for "STM32 Tiny" development board. - This board is available from several vendors on the net, and may be sold under different names. - It is based on a STM32 F103C8T6 MCU, and is bundled with a nRF24L01 wireless communication module. -

      -
      • -
    • -

      - The other port is for a generic minimal STM32F103CBT6 "blue" board contributed by Alan Carvalho de Assis. - Alan added support for numerous sensors, tone generators, user LEDs, and LCD support in NuttX 7.18. -

      -
      • -
    -

    - STATUS: - -

      - The basic STM32F103C8 port was released in NuttX version 6.28. - This work was contributed by Laurent Latil. - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - STMicro STM32F103x (STM32 F1 Family). - Support for five board configurations are available. - MCU support includes all of the high density and connectivity line families. - Board supported is available specifically for: STM32F103ZET6, STM32F103RET6, STM32F103VCT, STM32F103VET6, STM32F103RBT6, and STM32103CBT6. - Boards supported include: -

    -
      -
    1. -

      - STM3210E-EVAL. - A port for the STMicro STM3210E-EVAL development board that - features the STM32F103ZET6 MCU. - Refer to the NuttX board README file for further information. -

      -
      2. -
    2. -

      - HY-Mini STM32v board. - This board is based on the STM32F103VCT chip. Port contributed by Laurent Latil. - Refer to the NuttX board README file. -

      -
      3. -
    3. -

      - The M3 Wildfire development board (STM32F103VET6), version 2. - See http://firestm32.taobao.com (the current board is version 3). - Refer to the NuttX board README file for further information. -

      -
      4. -
    4. -

      - LeafLab's Maple and Maple Mini boards. - These boards are based on the STM32F103RBT6 chip for the standard version and on the STM32F103CBT6 for the mini version. - See the LeafLabs web site for hardware information; - see the NuttX board README file for further information about the NuttX port. -

      -
      5. -
    5. -

      - Olimexino-STM32. - This port uses the Olimexino STM32 board (STM32F103RBT6). - See the http://www.olimex.com for further information. - Contributed by David Sidrane. -

      -
      6. -
    6. -

      - Nucleo-STM32F103RB. - This port uses the STM32F103RBT6. - It was contributed by Mateusz Szafoni in NuttX-7.28, -

      -
      7. -
    -

    - These ports uses a GNU arm-nuttx-elf toolchain* under either Linux or Cygwin (with native Windows GNU tools or Cygwin-based GNU tools). -

    -
      -

      - STATUS: -

      -
        -
      • -

        - Basic Support/Drivers. - The basic STM32 port was released in NuttX version 0.4.12. The basic port includes boot-up - logic, interrupt driven serial console, and system timer interrupts. - The 0.4.13 release added support for SPI, serial FLASH, and USB device.; - The 4.14 release added support for buttons and SDIO-based MMC/SD and verified DMA support. - Verified configurations are available for the NuttShell (NSH) example, - the USB serial device class, and the USB mass storage device class example. -

        -
        • -
      • -

        - Additional Drivers. - Additional drivers and configurations were added in NuttX 6.13 and later releases for the STM32 F1 and F4. - F1 compatible drivers include an Ethernet driver, ADC driver, DAC driver, PWM driver, IWDG, WWDG, and CAN drivers. -

        -
        • -
      • -

        - M3 Wildfire. - Support for the Wildfire board was included in version 6.22 of NuttX. - The board port is basically functional. - Not all features have been verified. - Support for FAT file system on an an SD card had been verified. - The ENC28J60 network is functional (but required lifting the chip select pin on the W25x16 part). - Customizations for the v3 version of the Wildfire board are selectable (but untested). -

        -
        • -
      • -

        - Maple. - Support for the Maple boards was contributed by Yiran Liao and first appear in NuttX 6-30. -

        -
        • -
      • -

        - Olimexino-STM32. - Contributed by David Sidrane and introduced with NuttX 7.9. - Configurations are included for the NuttShell (NSH), a tiny version of the NuttShell, USB composite CDC/ACM + MSC, CAN support, and two tiny, small-footprint NSH configurations. -

        -
        • -
      • -

        - Nucleo-STM32F103RB. - Contributed by Mateusz Szafoni and introduced with NuttX 7.28. - Configurations are included for the NuttShell (NSH), ADC, and PWM. -

        -
        • -
      -
    -

    - Development Environments: - 1) Linux with native Linux GNU toolchain, 2) Cygwin/MSYS with Cygwin GNU toolchain, 3) Cygwin/MSYS - with Windows native toolchain (RIDE7, CodeSourcery or devkitARM), or 4) Native Windows. A DIY toolchain or Linux - or Cygwin is provided by the NuttX - buildroot - package. -

    -


    		-

    - STMicro STM32F105x. - Architecture support (only) for the STM32 F105R was contribed in NuttX-7.17 by Konstantin Berezenko. - There is currently no support for boards using any STM32F105x parts in the source tree. -

    -


    		-

    - STMicro STM32F107x (STM32 F1 "Connectivity Line" family). - Chip support for the STM32 F1 "Connectivity Line" family has been present in NuttX for some time and users have reported that they have successful brought up NuttX on their proprietary boards using this logic. -

    -
      -
    • -

      - Olimex STM32-P107 - Support for the Olimex STM32-P107 was contributed by Max Holtzberg and first appeared in NuttX-6.21. That port features the STMicro STM32F107VC MCU. -

      -

      - STATUS: - A configuration for the NuttShell (NSH) is available and verified. - Networking is functional. - Support for an external ENCX24J600 network was added in NuttX 6.30. -

      -
      • -
    • -

      - Shenzhou IV - A port of NuttX to the Shenzhou IV development board (See www.armjishu.com) featuring the STMicro STM32F107VCT MCU was added in NuttX-6.22. -

      -

      - STATUS: - In progress. - The following have been verified: - (1) Basic Cortex-M3 port, - (2) Ethernet, - (3) On-board LEDs. - Refer to the NuttX board README file for further information. -

      -
      • -
    • -

      - ViewTool STM32F103/F107 - Support for the Viewtool STM32F103/F107 board was added in NuttX-6.32. That board features the STMicro STM32F107VCT6 MCU. - Networking, LCD, and touchscreen support were added in NuttX-6.33. -

      -

      - Three configurations are available: -

      -
        -
      1. - A standard NuttShell (NSH) configuration that will work with either the STM32F103 or STM32F107 part. -
        2. -
      2. - A network-enabled NuttShell (NSH) configuration that will work only with the STM32F107 part. -
        3. -
      3. - The configuration that was used to verify the Nuttx high-priority, nested interrupt feature. -
        4. -
      -

      - STATUS: - Networking and touchscreen support are well test. - But, at present, neither USB nor LCD functionality have been verified. - Refer to the Viewtool STM32F103/F107 README file for further information. -

      -
      • -
    • -

      - Kamami STM32 Butterfly 2 - Support for the Kamami STM32 Butterfly 2 was contributed by MichaÅ‚ Åyszczek in NuttX-7.18. That port features the STMicro STM32F107VC MCU. -

      -

      - STATUS: - A configuration for the NuttShell (NSH), NSH with networking, and NSH with USB host are available and verified. -

      -
      • -


    		-

    - STMicro STM32F205 (STM32 F2 family). - Architecture only support for the STM32F205RG was contributed as an anonymous contribution in NuttX-7.10. -

    -

    - Particle.io Phone. - Support for the Particle.io Photon board was contributed by Simon Pirious in NuttX-7.21. - The Photon board features the STM32F205RG MCU. - The STM32F205RG is a 120 MHz Cortex-M3 operation with 1Mbit Flash memory and 128kbytes. - The board port includes support for the on-board Broadcom BCM43362 WiFi and fully usable FullMac network support. -

    -
      - STATUS: - In addition to the above-mention WiFI support, the Photon board support includes buttons, LEDS, IWDG, USB OTG HS, and procfs support. Configurations available for nsh, usbnsh, and wlan configurations. See the Photon README file for additional information. -


    		-

    - STMicro STM32F207 (STM32 F2 family). -

      -
    • - Support for the STMicro STM3220G-EVAL development board was contributed by Gary Teravskis and first released in NuttX-6.16. This board uses the STM32F207IG. -
      • -
    • - Martin Lederhilger contributed support for the Olimex STM32 P207 board using the STM32F207ZE MCU. -
      • -
    • - Board support for the Nucleo-L152RE was contributed by Mateusz Szafoni in NuttX-7.28. - Available configurations include NSH, ADC, and PWM. -
      • -
    -

    -
      -

      - STATUS: - The peripherals of the STM32 F2 family are compatible with the STM32 F4 family. - See discussion of the STM3240G-EVAL board below for further information. - Refer also to the NuttX board README file for further information. -

      -

      - Support for both the IAR and uVision GCC IDEs added for the STM3220G-EVAL board in NuttX 7.16. - From Kha Vo. -

      -
    -


    		-

    - Atmel SAM3U. - This port uses the Atmel SAM3U-EK - development board that features the SAM3U4E MCU. - This port uses a GNU arm-nuttx-elf or arm-nuttx-eabi toolchain* under either Linux or Cygwin (with native Windows GNU tools or Cygwin-based GNU tools). -

    -
      -

      - STATUS: - The basic SAM3U-EK port was released in NuttX version 5.1. The basic port includes boot-up - logic, interrupt driven serial console, and system timer interrupts. - That release passes the NuttX OS test and is proven to have a valid OS implementation. - A configuration to support the NuttShell is also included. - NuttX version 5.4 adds support for the HX8347 LCD on the SAM3U-EK board. - This LCD support includes an example using the - NX graphics system. - NuttX version 6.10 adds SPI support. - Touchscreen support was added in NuttX-6.29. -

      -

      - Subsequent NuttX releases will extend this port and add support for the SDIO-based SD cards and - USB device. - Refer to the NuttX board README file for further information about this port. -

      -
    -

    - Development Environments: - 1) Linux with native Linux GNU toolchain, 2) Cygwin/MSYS with Cygwin GNU toolchain, 3) Cygwin/MSYS - with Windows native toolchain (CodeSourcery or devkitARM), or 4) Native Windows. A DIY toolchain for inux - or Cygwin is provided by the NuttX - buildroot - package. -

    -


    		-

    - Atmel SAM3X. - There are two SAM3X boards supported: -

    -
      -
    1. - The Arduino Due development board that features the ATSAM3X8E MCU running at 84MHz. - See the Arduino Due page for more information. -
      2. -
    2. - The Mikroelektronika Flip&Click SAM3X development board. This board is an Arduino Due work-alike with additional support for 4 mikroBUS Click boards. -
      3. -
    -

    -
      -

      - STATUS: - As of this writing, the basic Arduino Due port is code complete and a fully verified configuration exists for the NuttShell NSH). - The first fully functional Arduino Due port was released in NuttX-6.29. - Refer to the NuttX board README file for further information. -

      -

      - Support for the Flip&Click SAM3X was added in NuttX-7.24. -

      -
    -

    - Development Environments: - See the Atmel SAM3U discussion above. -

    -


    		-

    - NXP LPC1766, LPC1768, and LPC1769. - Drivers are available for CAN, DAC, Ethernet, GPIO, GPIO interrupts, I2C, UARTs, SPI, SSP, USB host, and USB device. - Additional drivers for the RTC, ADC, DAC, Timers, PWM and MCPWM were contributed by Max (himax) in NuttX-7.3. - Verified LPC17xx configurations are available for these boards: -

      -
    • - The Nucleus 2G board from 2G Engineering (LPC1768), -
      • -
    • - The mbed board from mbed.org (LPC1768, Contributed by Dave Marples), and -
      • -
    • - The LPC1766-STK board from Olimex (LPC1766). -
      • -
    • - The Embedded Artists base board with NXP LPCXpresso LPC1768. -
      • -
    • - Zilogic's ZKIT-ARM-1769 board. -
      • -
    • - The Micromint Lincoln60 board with an NXP LPC1769. -
      • -
    • - A version of the LPCXPresso LPC1768 board with special support for the U-Blox model evaluation board. -
      • -
    • - Support for the Keil MCB1700 was contributed by Alan Carvalho de Assis in NuttX-7.23. -
      • -
    • - Support for the NXP Semiconductors' PN5180 NFC Frontend Development Kit was contributed by Michael Jung in NuttX-7.1. This board is based on the NXP LPC1769 MCU. -
      • -
    -

    -

    - The Nucleus 2G board, the mbed board, the LPCXpresso, and the MCB1700 all feature the NXP LPC1768 MCU; - the Olimex LPC1766-STK board features an LPC1766. - All use a GNU arm-nuttx-elf or arm-eabi toolchain* under either Linux or Cygwin (with native Windows GNU tools or Cygwin-based GNU tools). -

    -
      -

      - STATUS: - The following summarizes the features that has been developed and verified on individual LPC17xx-based boards. - These features should, however, be common and available for all LPC17xx-based boards. -

      -
        -
      1. -

        Nucleus2G LPC1768

        -
          -
        • - Some initial files for the LPC17xx family were released in NuttX 5.6, but -
          • -
        • - The first functional release for the NXP LPC1768/Nucleus2G occurred with NuttX 5.7 with - Some additional enhancements through NuttX-5.9. - Refer to the NuttX board README file for further information. -
          • -
        -

        -

        - That initial, 5.6, basic release included timer interrupts and a serial console and was - verified using the NuttX OS test (apps/examples/ostest). - Configurations available include include a verified NuttShell (NSH) configuration - (see the NSH User Guide). - The NSH configuration supports the Nucleus2G's microSD slot and additional configurations - are available to exercise the USB serial and USB mass storage devices. - However, due to some technical reasons, neither the SPI nor the USB device drivers are fully verified. - (Although they have since been verified on other platforms; this needs to be revisited on the Nucleus2G). -

        -

        Obsoleted. - Support for the Nucleus2G board was terminated on 2016-04-12. - There has not been any activity with the commercial board in a few years and it no longer appears to be available from the 2g-eng.com website. - Since the board is commercial and no longer publicly available, it no longer qualifies for inclusion in the open source repositories. - A snapshot of the code is still available in the Obsoleted repository and can easily be reconstitued if needed. -

        -
        2. -
      2. -

        mbed LPC1768

        -
          -
        • - Support for the mbed board was contributed by Dave Marples and released in NuttX-5.11. - Refer to the NuttX board README file for further information. -
          • -
        -

        -
        3. -
      3. -

        Olimex LPC1766-STK

        -
          -
        • - Support for that Olimex-LPC1766-STK board was added to NuttX 5.13. -
          • -
        • - The NuttX-5.14 release extended that support with an Ethernet driver. -
          • -
        • - The NuttX-5.15 release further extended the support with a functional USB device driver and SPI-based micro-SD. -
          • -
        • - The NuttX-5.16 release added a functional USB host controller driver and USB host mass storage class driver. -
          • -
        • - The NuttX-5.17 released added support for low-speed USB devices, interrupt endpoints, and a USB host HID keyboard class driver. -
          • -
        • - Refer to the NuttX board README file for further information. -
          • -
        -

        -

        - Verified configurations are now available for the NuttShell with networking and microSD support(NSH, see the NSH User Guide), - for the NuttX network test, for the THTTPD webserver, - for USB serial deive and USB storage devices examples, and for the USB host HID keyboard driver. - Support for the USB host mass storage device can optionally be configured for the NSH example. - A driver for the Nokia 6100 LCD and an NX graphics configuration for the Olimex LPC1766-STK have been added. - However, neither the LCD driver nor the NX configuration have been verified as of the NuttX-5.17 release. -

        -
        4. -
      4. -

        Embedded Artists base board with NXP LPCXpresso LPC1768

        -

        - An fully verified board configuration is included in NuttX-6.2. - The Code Red toolchain is supported under either Linux or Windows. - Verified configurations include DHCPD, the NuttShell (NSH), NuttX graphis (NX), THTTPD, and USB mass storage device. - Refer to the NuttX board README file for further information. -

        -
        5. -
      5. -

        Zilogic's ZKIT-ARM-1769 board

        -

        - Zilogic System's ARM development Kit, ZKIT-ARM-1769. - This board is based on the NXP LPC1769. - The initial release was included NuttX-6.26. - The Nuttx Buildroot toolchain is used by default. - Verifed configurations include the "Hello, World!" example application and a THTTPD demonstration. - Refer to the NuttX board README file for further information. -

        -
        6. -
      6. -

        Micromint Lincoln60 board with an NXP LPC1769

        -

        - This board configuration was contributed and made available in NuttX-6.20. - As contributed board support, I am unsure of what all has been verfied and what has not. - See the Microment website Lincoln60 board and the NuttX board README file for further information about the Lincoln board. -

        -
        7. -
      7. -

        U-Blox Modem Evaluation (LPCXpresso LPC1768)

        -

        - This board configuration was contributed by Vladimir Komendantskiy and made available in NuttX-7.15. - This is a variant of the LPCXpresso LPC1768 board support with special provisions for the U-Blox Model Evaluation board. - See the NuttX board README file for further information about this port. -

        -
        8. -
      8. -

        Keil MCB1700 (LPC1768)

        -

        - This board configuration was contributed by Alan Carvalho de Assis in NuttX-7.23. -

        -
        9. -
      9. -

        PN5180 NFC Frontend Development Kit

        -

        - This board configuration was contributed by Michael Jung in NuttX-7.31. -

        -
        10. -
      -
    -

    - Development Environments: - 1) Linux with native Linux GNU toolchain, 2) Cygwin/MSYS with Cygwin GNU toolchain, 3) Cygwin/MSYS - with Windows native toolchain (CodeSourcery devkitARM or Code Red), or 4) Native Windows. A DIY toolchain for Linux - or Cygwin is provided by the NuttX - buildroot package. -

    -


    		-

    - NXP LPC1788. - The port of NuttX to the WaveShare Open1788 is a collaborative effort between Rommel Marcelo and myself - (with Rommel being the leading contributor and I claiming only a support role). - You can get more information at the Open1788 board from the WaveShare website. -

    -
      -

      - STATUS: - Initial Open1788 support appeared in NuttX-6.26 with the first verified configurations in NuttX-6.27. - In NuttX-6.27 there is a working basic port with OS verification, Nuttshell (NSH) configurations, and a graphics test configuration. - SDRAM and GPDMA are working. - The NSH configuration includes verified support for a DMA-based SD card interface. - The frame-buffer LCD driver is functional and uses the SDRAM for frame-buffer memory. - A touchscreen interface has been developed but there appears to be a hardware issue with the WaveShare implementation of the XPT2046 touchscreen controller. - Refer to the NuttX board README file for further information. -

      -

      - NuttX-7.29 - Configurations were added to verify the use of NxTerms in the PROTECTED build most as was as graphic examples using the "Per-Window Framebuffer" support which was also introduced in NuttX-7.29. -

      -
    -


    		-

    - ON Semiconductor LC823450 (Dual core ARM Cortex-M3). - In NuttX-7.22, Masayuki Ishikawa contributed support for both the LC823450 architecture and for ON Semiconductor's LC823450XGEVK board: -

    -
    - The LC823450XGEVK is an audio processing system Evaluation Board Kit used to demonstrate the LC823450. This part can record and playback, and offers High-Resolution 32-bit & 192 kHz audio processing capability. It is possible to cover most of the functions necessary for a portable audio with only this LSI as follows. It has Dual CPU and DSP with High processing capability, and internal 1656K-Byte SRAM, which make it possible to implement large scale program. And it has integrated analog functions (low-power Class D HP amplifier, PLL, ADC etc.) so that PCB space and cost is reduced, and it has various interface (USB, SD, SPI, UART, etc.) to make extensibility high. Also it is provided with various function including SBC/AAC codec by DSP and UART and ASRC (Asynchronous Sample Rate Converter) for Bluetooth® audio. It is very small chip size in spite of the multi-funciton as described above and it realizes the low power consumption. Therefore, it is applicable to portable audio markets such as Wireless headsets and will show high performance. -
    -

    - Further information about the LC823450XGEVK is available on from the the ON Semiconductor website as are LC823450 related technical documents. - Refer to the NuttX board README file for details of the NuttX port. -

    -

    - This port is intended to test LC823450 features including SMP. Supported peripherals include UART, TIMER, RTC, GPIO, DMA, I2C, SPI, LCD, eMMC, and USB device. - ADC, Watchdog, IPC2, and I2S support was added by Masayuki Ishikawa in NuttX-7.23. - Bluetooth, SPI, and PROTECTED build support were added by Masayuki Ishikawa in NuttX-7.26. - Support for for SPI flash boot was added in NuttX-7.28. -

    -


    		-

    - Maxim Integrated MAX36600. - Architectural upport for the MAX32660 was added (along with partial support for other members of the MAX326xx family) in NuttX 7.28. -

    -

    - MAX32660-EVSYS. - Basic support for the Maxim Integrated MAC3X660 - EVSYS was included in the NuttX-7.28 release. - A basic NSH configuration is available and is fully functional. - Includes unverified support for an SPI0-based SD card. -

    -

    - STATUS: -

    -
      -

      - NuttX-7.29. - The initial release included: Clock configuration, timer, GPIO pin configuration, ICC, and UART. - Additional untested drivers are complete and ready for testing: DMA, GPIO interrupts, SPI0 Master, TC, WDT. - The following drivers are not yet implemented: I2C and I2S. -

      -

      - README File. - Refer to the MAX32660-EVSYS README file for further information. -

      -
    -
    - ARM Cortex-M4. -

    		-

    - Infineon XMC45xx. - An initial but still incomplete port to the XMC4500 Relax board was released with NuttX-7.21 (although it was not really ready for prime time). Basic NSH functionality was a serial console was added by Alan Carvahlo de Assis in NuttX-7.23. Alan also added an SPI driver in NuttX-7.25. -

    -

    - This initial porting effort uses the Infineon XMC4500 Relax v1 board as described on the manufacturer's website. - The current status of the board is available in the board README file -

    -


    		-

    - Nordic Semiconductor/NRF52xxx. - Initial architecture support of the NRF52 including UART, Timer, and GPIOs was contributed by Janne Rosberg in NuttX-7.25. - Janne also contributed board support for the NRF52-PCA10040 development board at that time. -

    -

    - The NRF52 was generalized by Hanya Zou in NuttX-7.28 for any similar board based on the NRF52832 MCU. Support was specifically included for the Adafruit NRF52 Feather board. -

    -

    - Available drivers include: -

    -
      -
    • - NuttX-7.25. UART, Timer, and GPIOs from Janne Rosberg and a watchdog timer driver was added by Levin Li. -
      • -
    • - NuttX-7.25. Flash PROGMEM support was added by Alan Carvalho de Assis. -
      • -
    • - NuttX-7.29. Support for the 52804 family and an RNG drivers was added by Levin Li. -
      • -
    -
      -

      - STATUS: - Refer to the generic NRF52 board README file for further information. -

      -
    -


    		-

    - NXP/FreeScale Kinetis K20/Teensy-3.x. - Architecture support (only) was added in NuttX-7.10. - This support was taken from PX4 and is the work of Jakob Odersky. - Support was added for the PJRC Teensy-3.1 board in NuttX-7.11. - Backward compatible support for the Teensy-3.0 is included. -

    -
      -

      - STATUS: - Refer to the Teensy-3.1 board README file for further information. -

      -
    -


    		-

    - NXP/FreeScale Kinetis K28F/Freedom-K28F. - Architecture support for the Kinetis K28F along with board support for the Freedom-K28F was added in NuttX-7.15. - The Freedom-K28F board is based on the Kinetis MK28FN2M0VMI15 MCU (ARM Cortex-M4 at150 MHz, 1 MB SRAM, 2 MB flash, HS and FS USB, 169 MAPBGA package). - More information is available from the NXP website. -

    -
      -

      - STATUS: - Refer to the Freedom-K28F board README file for further information. -

      -
    -


    		-

    - NXP/FreeScale Kinetis K40. - This port uses the Freescale Kinetis KwikStik K40. - Refer to the Freescale web site for further information about this board. - The Kwikstik is used with the FreeScale Tower System (mostly just to provide a simple UART connection) -

    -
      -

      - STATUS: - The unverified KwikStik K40 first appeared in NuttX-6.8 - As of this writing, the basic port is complete but I accidentally locked my board during the initial bringup. - Further development is stalled unless I learn how to unlock the device (or until I get another K40). - Additional work remaining includes, among other things: (1) complete the basic bring-up, - (2) bring up the NuttShell NSH, (3) develop support for the SDHC-based SD card, - (4) develop support for USB host and device, and (2) develop an LCD driver. - NOTE: Some of these remaining tasks are shared with the K60 work described below. - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - NXP/FreeScale Kinetis K60. - This port uses the Freescale Kinetis TWR-K60N512 tower system. - Refer to the Freescale web site for further information about this board. - The TWR-K60N51 includes with the FreeScale Tower System which provides (among other things) a DBP UART connection. -

    -
      -

      - STATUS: - As of this writing, the basic port is complete and passes the NuttX OS test. - An additional, validated configuration exists for the NuttShell (NSH, see the - NSH User Guide). - This basic TWR-K60N512 first appeared in NuttX-6.8. - Refer to the NuttX board README file for further information. -

      -
    -

    - MK60N512VLL100. - Architecture support for the MK60N512VLL100 was contributed by Andrew Webster in NuttX-7.14. -

    -


    		-

    - NXP/FreeScale Kinetis K64. - Support for the Kinetis K64 family and specifically for the NXP/Freescale Freedom K64F board was added in NuttX 7.17. - Initial release includes two NSH configurations with support for on-board LEDs, buttons, and Ethernet with the on-board KSZ8081 PHY. - SDHC supported has been integrated, but not verified. - Refer to the NuttX board README file for further information. -

    -

    - MK64FN1M0VMD12. - Architecture support for the _MK64FN1M0VMD12 was contributed by Maciej Skrzypek in NuttX-7.20. -

    -

    - NXP/Freescale Kinetis TWR-K64F120M. - Support for the Freescale Kinetis TWR-K64F120M was contributed in NuttX-7.20 by Maciej Skrzypek. Refer to the Freescale web site for further information about this board. - The board may be complemented by TWR-SER which includes (among other things), an RS232 and Ethernet connections. - Refer to the NuttX board README file for further information. -

    -

    		-

    - Driver Status. -

    -
      -
    • - NuttX-6.8. - Ethernet and SD card (SDHC) drivers also exist: - The SDHC driver is partially integrated in to the NSH configuration but has some outstanding issues. - Additional work remaining includes: (1) integrate th SDHC drivers, and (2) develop support for USB host and device. - NOTE: Most of these remaining tasks are the same as the pending K40 tasks described above. -
      • -
    • - NuttX-7.14. - The Ethernet driver became stable in NuttX-7.14 thanks to the efforts of Andrew Webster. -
    • - NuttX-7.17. - Ethernet support was extended and verified on the Freedom K64F. - A Kinetis USB device controller driver and PWM support was contributed by kfazz. -
      • -
    -


    		-

    - NXP/FreeScale Kinetis K66. - Support for the Kinetis K64 family and specifically for the NXP/Freescale Freedom K66F board was contributed by David Sidrane in NuttX 7.20. - Refer to the NuttX board README file for further information. -

    -

    		-

    - Driver Status. -

    -
      -
    • - Most K6x drivers are compatible with the K66. -
      • -
    • - NuttX-7.20. David Sidrane also contributed support for a serial driver on the K66's LPUART. -
      • -
    • - NuttX-7.22. David Sidrane contributed improvements to the USB and I2C device drivers, RTC alarm functionality, and new SPI driver. -
      • -
    • - NuttX-7.26. David Sidrane contributed DMA support to the Kinetis K6x family. -
      • -
    -


    		-

    - Sony CXD56xx (6 x ARM Cortex-M4). - Support for the CXD56xx was introduced by Nobuto Kobayashi in NuttX-7.30. -

    -

    - Sony Spresence. - Spresense is a compact development board based on Sony’s power-efficient multicore microcontroller CXD5602. - Basic support for the Sony Spresense board was included in the contribution of Nobuto Kobayashi in NuttX-7.30. NOTE: That was an initial, bare bones basic Spresense port sufficient for running a NuttShell (NSH) and should not be confused with the full Spresence SDK offered from Sony. - Since then there has been much development of the NuttX CXD56xx port. -

    - Features: -

    -
      -
    • Integrated GPS: Embedded GNSS with support for GPS, QZSS.
      • -
    • Hi-res audio output and multi mic inputs" Advanced 192kHz/24 bit audio codec and amplifier for audio output, and support for up to 8 mic input channels.
      • -
    • Multicore microcontroller: Spresense is powered by Sony's CXD5602 microcontroller (ARM® Cortex®-M4F × 6 cores), with a clock speed of 156 MHz.
      • -
    -

    - Driver Status: -

    -
      -
    • -

      - NuttX-3.31. - In this release, many new architectural features, peripheral drivers, and board configurations were contributed primarily through the work of Alin Jerpelea. - These new architectural features include: Inter-core communications, power management, and clock management. - New drivers include: GPIO, PMIC, USB, SDHC, SPI, I2C, DMA, RTC, PWM, Timers, Watchdog Timer, UID, SCU, ADC, eMMC, Camera CISIF, GNSS, and others. -

      -

      - NuttX-8.1. - Alin Jerpelea brought in ten (external) sensor drivers that integrate through the CXD56xx's SCU. -

      -

      - NuttX-8.2. - Masayuki Ishikawa implemented SMP operation of the CX56Dxx parts. - Alin Jerpelea: Added support for the Altair LTE modem support, enabled support for accelerated format converter, rotation and so on using the CXD5602 image processing accelerator, added ISX012 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. -

      -
      • -
        -
      -


    		-

    - STMicro STM32 F302 (STM32 F3 family). - Architecture (only) support for the STM32 F302 was contributed in NuttX-7.10 by Ben Dyer (via the PX4 team and David Sidrane). -

    -

    - Support for the Nucleo-F302R8 board was added by raiden00pl in NuttX-7.27. - Refer to the NuttX board README file for further information. -

    -


    		-

    - STMicro STM32 F303 (STM32 F3 family). -

    -

      -

    • - STM32F3-Discovery. - This port uses the STMicro STM32F3-Discovery board featuring the STM32F303VCT6 MCU (STM32 F3 family). - Refer to the STMicro web site for further information about this board. -

      -
        -

        - STATUS: - The basic port for the STM32F3-Discover was first released in NuttX-6.26. - Many of the drivers previously released for the STM32 F1, Value Line, and F2 and F4 may be usable on this platform as well. - New drivers will be required for ADC and I2C which are very different on this platform. - Refer to the NuttX board README file for further information. -

        -
      -
      • - -

    • - STMicro ST Nucleo F303RE board. - The basic port for the Nucleo F303RE was contributed by Paul Alexander Patience and first released in NuttX-7.12. - Refer to the NuttX board README file for further information. -

      • -

    • - STMicro ST Nucleo F303ZE board. - Support for the Nucleo-F303ZE board was added by Mateusz Szafoni in NuttX-7.27. - Refer to the NuttX board README file for further information. -

      • -
    -


    		-

    - STMicro STM32 F334 (STM32 F3 family, ARM Cortex-M4). -

    -

    - Support for the STMicro STM32F334-Disco board was contributed by Mateusz Szafoni in NuttX-7.22 and for the Nucleo-STM32F334R8 was contributed in an earlier release. -

    -


    		-

    - STMicro STM32 F372/F373 (ARM Cortex-M4). -

    -

    - Basic architecture support for the STM32F372/F373 was contributed by Marten Svanfeldt in NuttX 7.9. - There are no STM32F*72 boards currently supported, however. -

    -


    		-

    - STMicro STM324x1 (STM32 F4 family). -

    -

      -

      - Nucleo F401RE. - This port uses the STMicro Nucleo F401RE board featuring the STM32F401RE MCU. - Refer to the STMicro web site for further information about this board. -

      -

      - Nucleo F411RE. - This port uses the STMicro Nucleo F411RE board featuring the STM32F411RE MCU. - Refer to the STMicro web site for further information about this board. -

      -

      - STATUS: -

        -
      • NuttX-7.2 - The basic port for STMicro Nucleo F401RE board was contributed by Frank Bennett. -
        • -
      • NuttX-7.6 - The basic port for STMicro Nucleo F401RE board was added by Serg Podtynnyi. -
        • -
      • NuttX-7.25 - Architecture support (only) for STMicro STM32F401xB and STM32F401xC pars was added. -
        • -
      • - Refer to the NuttX board README file for further information. -
        • -
      -

      -


    		-

    - STMicro STM32410 (STM32 F4 family). -

    -

      -

      - Architecture-only support was contributed to NuttX-7.21 by Gwenhael Goavec-Merou. -

      -


    		-

    - STMicro STM32405x/407x (STM32 F4 family). -

    -

      -

      - STMicro STM3240G-EVAL. - This port uses the STMicro STM3240G-EVAL board featuring the STM32F407IGH6 MCU. - Refer to the STMicro web site for further information about this board. -

      -

      - STATUS: -

        -
      • NuttX-6.12 - The basic port is complete and first appeared in NuttX-6.12. - The initial port passes the NuttX OS test and includes a validated configuration for the NuttShell (NSH, see the - NSH User Guide) as well as several other configurations. -
        • -
      • NuttX-6.13-6.16 - Additional drivers and configurations were added in NuttX 6.13-6.16. - Drivers include an Ethernet driver, ADC driver, DAC driver, PWM driver, CAN driver, F4 RTC driver, Quadrature Encoder, DMA, SDIO with DMA - (these should all be compatible with the STM32 F2 family and many should also be compatible with the STM32 F1 family as well). -
        • -
      • NuttX-6.16 - The NuttX 6.16 release also includes and logic for saving/restoring F4 FPU registers in context switches. - Networking intensions include support for Telnet NSH sessions and new configurations for DHPCD and the networking test (nettest). -
        • -
      • NuttX-6.17 - The USB OTG device controller driver, and LCD driver and a function I2C driver were added in NuttX 6.17. -
        • -
      • NuttX-6.18 - STM32 IWDG and WWDG watchdog timer drivers were added in NuttX 6.18 (should be compatible with F1 and F2). - An LCD driver and a touchscreen driver for the STM3240G-EVAL based on the STMPE811 I/O expander were also added in NuttX 6.18. -
        • -
      • NuttX-6.21 - A USB OTG host controller driver was added in NuttX 6.21. -
        • -
      • NuttX-7.3 - Support for the Olimex STM32 H405 board was added in NuttX-7.3. -
        • -
      • NuttX-7.14 - Support for the Olimex STM32 H407 board was added in NuttX-7.14. -
        • -
      • NuttX-7.17 - Support for the Olimex STM32 E407 board was added in NuttX-7.17. -
        • -
      • NuttX-7.19 - Support for the Olimex STM32 P407 board was added in NuttX-7.19. -
        • -
      • NuttX-7.21 - Support for the MikroElektronika Clicker2 for STM32 (STM32 P405) board was added in NuttX-7.21. -
        • -
      • NuttX-7.29 - Support for the OmnibusF4 architecture (STM32 P405) board was added in NuttX-7.29. -
        • -
      -

      -

      - Refer to the STM3240G-EVAL board README file for further information. -

      -

      - STMicro STM32F4-Discovery. - This port uses the STMicro STM32F4-Discovery board featuring the STM32F407VGT6 MCU. - The STM32F407VGT6 is a 168MHz Cortex-M4 operation with 1Mbit Flash memory and 128kbytes. - The board features: -

      -
        -
      • On-board ST-LINK/V2 for programming and debugging,
        • -
      • LIS302DL, ST MEMS motion sensor, 3-axis digital output accelerometer,
        • -
      • MP45DT02, ST MEMS audio sensor, omni-directional digital microphone,
        • -
      • CS43L22, audio DAC with integrated class D speaker driver,
        • -
      • Eight LEDs and two push-buttons,
        • -
      • USB OTG FS with micro-AB connector, and
        • -
      • Easy access to most MCU pins.
        • -
      -

      - Support for the STM3F4DIS-BB base board was added in NuttX-7.5. - This includes support for the serial communications via the on-board DB-9 connector, Networking, and the microSD card slot. -

      -

      - Refer to the STMicro web site for further information about this board and to -

      -
        -

        - STATUS: - The basic port for the STM32F4-Discovery was contributed by Mike Smith and was first released in NuttX-6.14. - All drivers listed for the STM3240G-EVAL are usable on this platform as well. - Refer to the NuttX board README file for further information. -

        -
      -

      - MikroElektronika Mikromedia for STM32F4. - This is another board supported by NuttX that uses the same STM32F407VGT6 MCU as does the STM32F4-Discovery board. - This board, however, has very different on-board peripherals than does the STM32F4-Discovery: -

      -
        -
      • TFT display with touch panel,
        • -
      • VS1053 stereo audio codec with headphone jack,
        • -
      • SD card slot,
        • -
      • Serial FLASH memory,
        • -
      • USB OTG FS with micro-AB connector, and
        • -
      • Battery connect and batter charger circuit.
        • -
      -

      - See the Mikroelektronika website for more information about this board and the NuttX board README file for further information about the NuttX port. -

      -
        -

        - STATUS: - The basic port for the Mikromedia STM32 M4 was contributed by Ken Petit and was first released in NuttX-6.128. - All drivers for the STM32 F4 family may be used with this board as well. -

        -
      -

      - Olimex STM32 H405. - Support for the Olimex STM32 H405 development board was contributed by Martin Lederhilger and appeared in NuttX-7.3. - See the NuttX board README file for further information about the NuttX port. -

      -

      - Olimex STM32 H407. - Support for the Olimex STM32 H407 development board was contributed by Neil Hancock and appeared in NuttX-7.14. - See the NuttX board README file for further information about the NuttX port. -

      -

      - Olimex STM32 E407. - Support for the Olimex STM32 E407 development board was contributed by Mateusz Szafoni and appeared in NuttX-7.17. - Networking configurations were added in NuttX-7.18. - See the NuttX board README file for further information about the NuttX port. -

      -

      - Olimex STM32 P407. - Support for the Olimex STM32 P407 development board appeared in NuttX-7.19. - See the NuttX board README file for further information about the NuttX port. -

      -

      - MikroElektronika Clicker2 for STM32. - This is yet another board supported by NuttX that uses the same STM32F407VGT6 MCU as does the STM32F4-Discovery board. - This board has been used primarily with the MRF24J40 Click board for the development of IEEE 802.15.4 MAC and 6LoWPAN support. -

      - See the Mikroelektronika website for more information about this board and the NuttX board README file for further information about the NuttX port. -

      -
        -

        - STATUS: - The basic port for the Clicker2 STM32 was contributed by Anthony Merlino and was first released in NuttX-7.21. - All compatible drivers for the STM32 F4 family may be used with this board as well. -

        -
      -

      - OmnibusF4. - Initial support for the OmnibusF4 family of flight management units was contributed by Bill Gatliff in NuttX-7.29. - "OmnibusF4" is not a product name per se, but rather a design specification that many product vendors adhere to. - The specification defines the major components, and how those components are wired into the microcontroller. - Airbot is one such vendor. They publish a schematic. - Other software that supports the OmnibusF4 family include Betaflight, iNAV, and many others. - PX4 recently added support as well, also based on NuttX. - No code from those resources is included in this port. - The OmnibusF4 specification mandates the InvenSense MPU6000 which is included in NuttX-7.29 along with a driver for the MAX7546 OSD. -

      -


    		-

    - STMicro STM32 F427/437. - General architectural support was provided for the F427/437 family in NuttX 6.27. - Specific support includes the STM32F427I, STM32F427Z, and STM32F427V chips. - This is architecture-only support, meaning that support for the boards with these chips is available, but not support for any publicly available boards is included. - This support was contributed by Mike Smith. -

    -

    - The F427/437 port adds (1) additional SPI ports, (2) additional UART ports, (3) analog and digital noise filters on the I2C ports, (4) up to 2MB of flash, (5) an additional lower-power mode for the internal voltage regulator, (6) a new prescaling option for timer clock, (7) a larger FSMSC write FIFO, and (8) additional crypto modes (F437 only). -

    -

    - Axlotoi. - In NuttX-7.31, Jason Harris contributed support for the Axloti board. - That is the board for the Axoloti open source synthesizer board featuring the STM32F427IGH6 MCU - The STM32F427IGH6 has a 180MHz Cortex-M4 core with 1MiB Flash memory and 256KiB of SRAM - The Axloti board features: -

    -
      -
    • - ADAU1961 24-bit 96 kHz stereo CODEC -
      • -
    • - 1/4" in/out jacks for analog audio signals -
      • -
    • - 3.5 mm jack for analog audio signals -
      • -
    • - 8 MiB of SDRAM (Alliance Memory AS4C4M16SA) -
      • -
    • - Serial MIDI in/out ports -
      • -
    • - SD Card slot -
      • -
    • - Two user LEDs and one (GPIO) push-button -
      • -
    • - USB OTG FS with Micro-AB connector (USB device mode operation) -
      • -
    • - USB OTG HS with Type-A connector (USB host mode operation) -
      • -
    • - Easy access to most IO pins -
      • -
    -

    - Refer to Axloti website for further information about this board. -

    -


    		-

    - STMicro STM32 F429. - Support for STMicro STM32F429I-Discovery development board featuring the STM32F429ZIT6 MCU was contributed in NuttX-6.32 by Ken Pettit. - The STM32F429ZIT6 is a 180MHz Cortex-M4 operation with 2Mbit Flash memory and 256kbytes. -

    -

    - STATUS: -

    -
      -
    • - The initial release included support from either OTG FS or OTG HS in FS mode. -
      • -
    • - The F429 port adds support for the STM32F439 LCD and OTG HS (in FS mode). -
      • -
    • - In Nutt-7.6, Brennan Ashton added support for concurrent OTG FS and OTG HS (still in FS mode) and Marco Krahl added support for an SPI-based LCD . -
      • -
    • - In Nutt-7.7, Marco Krahl included support for a framebuffer based driver using the LTDC and DMA2D. - Marcos's implementation included extensions to support more advance LTDC functions through an auxiliary interface. -
      • -
    • - Support for the uVision GCC IDE added for theSTM32F429I-Discovery board in NuttX 7.16. - From Kha Vo. -
      • -
    -

    - Refer to the STM32F429I-Discovery board README file for further information. -

    -


    		-

    - STMicro STM32 F433. - Architecture-only support for the STM32 F433 family was contributed by Alan Carvalho de Assis in NuttX-7.22 (meaning that the parts are supported, but there is no example board supported in the system). - This support was contributed by David Sidrane and made available in NuttX-7.11. -

    -


    		-

    - STMicro STM32 F446. - Architecture-only support is available for the STM32 F446 family (meaning that the parts are supported, but there is no example board supported in the system). - This support was contributed by David Sidrane and made available in NuttX-7.11. -

    -


    		-

    - STMicro STM32 F46xx. - Architecture-only support is available for the STM32 F46xx family (meaning that the parts are supported, but there is no example board supported in the system). - This support was contributed by Paul Alexander Patienc and made available in NuttX-7.15. -

    -


    		-

    - STMicro STM32 G474. - One board is supported in this family: -

    -
      -
    • -

      - B-G474E-DPOW1 Discovery Kit. - Initial board support for the STMicro B-G474E-DPOW1 board from ST Micro was added in NuttX-9.1. See the STMicro website and the board README file for further information. -

      -
      • -
    - -

    Status:

    -
      -

      - NuttX-9.1. - Initial support for booting NuttX to a functional NSH prompt on this board. -

      -


    		-

    - STMicro STM32 L475. - One board in supported in this family: -

    -
      -
    • -

      - B-L475E-IOT01A Discovery Kit. - Board support for the STMicro B-L475E-IOT01A board from ST Micro was contributed by Simon Piriou in NuttX-7.22. See the STMicro website and the board README file for further information. -

      -

      - This board STMicro is powered by STM32L475VG Cortex-M4 and targets IoT nodes with a choice of connectivity options including WiFi, Bluetooth LE, NFC, and sub-GHZ RF at 868 or 915 MHz, as well as a long list of various environmental sensors. -

      -

      • -
    - -

    Status:

    -
      -

      - NuttX-7.22. - The initial board support was released. Since this board is highly compatible with the related, more mature STM32 L4 parts, it is expected that there is a high degree of compatibility and with those part. -

      -

      - This board has been used extensive to develop NuttX PktRadio support for the onboard Spirit1 radio (SPSGRF-915) radio. - 6LoWPAN radio communications are fully supported in point-to-point and in star topologies. -

      -

      - Simon Pirou also contributed support for the on-board Macronix QuadSPI FLASH in NuttX 7.22. -

      -


    		-

    - STMicro STM32 L476. - Three boards are supported in this family: -

    -
      -
    • -

      - Nucleo-L476RG. - Board support for the STMicro NucleoL476RG board from ST Micro was contributed by Sebastien Lorquet in NuttX-7.15. See the STMicro website and the board README file for further information. -

      -
      • -
    • -

      - STM32L476VG Discovery. - Board support for the STMicro STM32L476VG Discovery board from ST Micro was contributed by Dave in NuttX-7.15. See the STMicro website and the board README file for further information. -

      -
      • -
    • -

      - STM32L476 MDK. - Very basic support for NuttX on the Motorola Moto Z MDK was contributed by Jim Wylder in NuttX 7.18. - A simple NSH configuration is available for the STM32L476 chip. - See the Moto Mods Development Kit and the board README file for further information. -

      -
      • -
    -

    Status:

    -
      -

      - NuttX-7.15. - Only the first initial release of support for this family is present. - It includes these basics: -

      -
        -
      • RCC, clocking, Interrupts, System timer
        • -
      • UART, USART, Serial Console
        • -
      • GPIO, DMA, I2C, RNG, SPI
        • -
      -

      - NuttX-7.16. - Additional drivers were contributed: -

      -
        -
      • QSPI with DMA and memory mapped support. From Dave (ziggurat29).
        • -
      • CAN contributed by Sebastien Lorquet.
        • -
      • I2C made functional by Dave (ziggurat29).
        • -
      -

      - NuttX-7.17. - Additional drivers/features were contributed: -

      -
        -
      • Support for tickless mode.
        • -
      • CAN driver enhancements.
        • -
      -

      - NuttX-7.18. - Additional drivers were contributed: -

      -
        -
      • Oneshot timer driver.
        • -
      • Quadrature encode contributed by Sebastien Lorquet.
        • -
      -

      - NuttX-7.20. - Additional drivers were added: -

      -
        -
      • Serial Audio Interface (SAI).
        • -
      • Power Management.
        • -
      • LPTIM.
        • -
      • Comparator (COMP).
        • -
      -

      - NuttX-7.21. - Additional drivers were added: -

      -
        -
      • Internal Watchdog (IWDG).
        • -
      -

      - NuttX-7.22. -

      -
        -
      • DAC and ADC drivers were contributed by Juha Niskanen.
        • -
      -

      - NuttX-7.30. -

      -
        -
      • Added USB FS device driver, CRS and HSI38 support from Juha Niskanen.
        • -
      -

      - NuttX-8.2. -

      -
        -
      • Add DMA support for STM32L4+ series. From Jussi Kivilinna.
        • -
      • Add support for LPTIM timers on the STM32L4 as PWM outputs. From Matias N.
        • Enable OTGFS for STM32L4+ series. The OTGFS peripheral on stm32l4x6 and stm32l4rxxx reference manual is exactly the same. From Jussi Kivilinna. -


    		-

    - STMicro STM32 L4x2. - Architecture support for STM32 L4x2 family was contributed by Juha Niskanen in NuttX-7.21. - Support was extended for the STM32L412 and STM32L422 chips in NuttX-7.27. - Two boards are currently supported. -

    -
      -
    • -

      - Nucleo-L432KC. - Board support for the STMicro Nucleo-L432KC board from ST Micro was contributed by JSebastien Lorquet in NuttX-7.21. See the STMicro website and the board README file for further information. -

      -
      • -
    • -

      - Nucleo-L452RE. - Board support for the STMicro Nucleo-L452RE board from ST Micro was contributed by Juha Niskanen in NuttX-7.21. See the STMicro website and the board README file for further information. -

      -
      • -
    -

    - See also the status above for the STM32 L476 most of which also applies to these parts. -

    -


    		-

    - STMicro STM32 L496. - Architecture support for STM32 L496 was contributed by Juha Niskanen along with board support for the Nucleo-L496ZG in NuttX-7.21: -

    -
      -
    • -

      - Nucleo-L496ZG. - Board support for the STMicro Nucleo-L496ZG board from ST Micro was contributed by Juha Niskanen in NuttX-7.21. See the STMicro website and the board README file for further information. - See also the status above for the STM32 L476 most of which also applies to this part. -

      -
      • -
    -


    		-

    - STMicro STM32 L4Rx. - Architecture support for STM32 L4+ family was contributed by Juha Niskanen along with board support for the STM32L4R9I-Discovery in NuttX-7.26. Additional support for the STM32L4R5ZI part was added by Jussi in NuttX-8.2. -

    -
      -
    • -

      - STM32L4R9I-Discovery. - Board support for the STMicro STM32L4R9I-Discovery board from ST Micro was contributed by Juha Niskanen in NuttX-7.26. - That development board uses the STM32L4R9AI part. - See the STMicro website and the board README file for further information. - See also the status above for the opther STM32 L4 parts, most of which also applies to this part. -

      -
      • -
    -


    		-

    - NCP LPC40xx. - The LPC40xx family is very similar to the LPC17xx family except that it features a Cortex-M4F versus the LPC17xx's Cortex-M3. - Architectural support for the LPC40xx family was built on top of the existing LPC17xx by jjlange in NuttX-7.31. - With that architectural support came support for two boards also contributed by jjlange: -

    -
      -

      - Embedded Artists LPC4088 Developer's kit. - See the Embedded Artists website for further information about this board. -

      -

      - Embedded Artists LPC4088 Developer's kit. - See the Embedded Artists website for further information about this board. -

      -
    -

    - LX CPU. - Pavel Pisa add support for the PiKRON LX CPU board. - This board may be configured to use either the LPC4088 or the LPC1788. -

    -

    - Driver Status. -

    -
      - NuttX-7.31. - No new unique drivers for the LPC40xx family are needed. - Most (if not all) LPC17xx drivers should be simply used with the LPC40xx. - That is an unverified assertion, however, not a proven fact. -
    -


    		-

    - NCP LPC43xx. - Several board ports are available for this higher end, NXP Cortex-M4F part: -

    -
      -

      - NXG Technologies LPC4330-Xplorer. - This NuttX port is for the LPC4330-Xplorer board from NGX Technologies featuring the NXP LPC4330FET100 MCU. - See the NXG website for further information about this board. -

      -
        -
      • -

        STATUS: - Refer to the NuttX board README file for more detailed information about this port. -

        -
        • -
      • -

        NuttX-6.20 - The basic LPC4330-Xplorer port is complete. - The basic NuttShell (NSH) configuration is present and fully verified. - This includes verified support for: SYSTICK system time, pin and GPIO configuration, and a serial console. -

        -
        • -
      -

      - NXP/Embest LPC4357-EVB. - This NuttX port is for the LPC4357-EVB from NXP/Embest featuring the NXP LPC4357FET256 MCU. - The LPC4357 differs from the LPC4330 primarily in that it includes 1024KiB of on-chip NOR FLASH. - See the NXP website for more detailed information about the LPC4357 and the LPC4357-EVB. -

      -
        -
      • -

        STATUS: - Refer to the NuttX board README file for more detailed information about this port. -

        -
        • -
      • -

        NuttX-7.6. - The basic port is was contributed by Toby Duckworth. - This port leverages from the LPC4330-Xplorer port (and, as of this writing, still requires some clean up of the technical discussion in some files). - The basic NuttShell (NSH) configuration is present and has been verified. - Support is generally the same as for the LPC4330-Xplorer as discussed above. -

        -
        • -
      - -

      - NXP LPC4370-Link2. - This is the NuttX port to the NXP LPC4370-Link2 development board featuring the NXP LPC4370FET100 MCU. -

      -
        -
      • -

        STATUS: - Refer to the NuttX board README file for more detailed information about this port. -

        -
        • -
      • -

        NuttX-7.12 - The NXP LPC4370-Link2 port is was contributed by Lok Tep and first released in NuttX-7.12. -

        -
        • -
      - -

      - WaveShare LPC4337-WS. - This is the NuttX port to the WaveShare LPC4337-WS development board featuring the NXP LPC4337JBD144 MCU. -

      -
        -
      • -

        STATUS: - Refer to the NuttX board README file for more detailed information about this port. -

        -
        • -
      • -

        NuttX-7.14 - The NXP WaveShare LPC4337-WS port is was contributed by Lok Tep and first released in NuttX-7.14. -

        -
        • -
      • -

        NuttX-7.16 - Support for the LPC4337JET100 chip was contribed by Alexander Vasiljev. - Alexander also contributed an LPC43xx AES driver available in NuttX-7.16. -

        -
        • -
      -

    		-

    - Driver Status. -

    -
      -
    • -

      NuttX-6.20 - Several drivers have been copied from the related LPC17xx port but require integration into the LPC43xx: ADC, DAC, GPDMA, I2C, SPI, and SSP. - The registers for these blocks are the same in both the LPC43xx and the LPC17xx and they should integrate into the LPC43xx very easily by simply adapting the clocking and pin configuration logic. -

      -

      - Other LPC17xx drivers were not brought into the LPC43xx port because these peripherals have been completely redesigned: CAN, Ethernet, USB device, and USB host. -

      -

      - So then there is no support for the following LPC43xx peripherals: SD/MMC, EMC, USB0,USB1, Ethernet, LCD, SCT, Timers 0-3, MCPWM, QEI, Alarm timer, WWDT, RTC, Event monitor, and CAN. -

      -

      - Some of these can be leveraged from other MCUs that appear to support the same peripheral IP: -

      -
        -
      • - The LPC43xx USB0 peripheral appears to be the same as the USB OTG peripheral for the LPC31xx. - The LPC31xx USB0 device-side driver has been copied from the LPC31xx port but also integration into the LPC43xx (clocking and pin configuration). - It should be possible to complete porting of this LPC31xx driver with a small porting effort. -
        • -
      • - The Ethernet block looks to be based on the same IP as the STM32 Ethernet and, as a result, it should be possible to leverage the NuttX STM32 Ethernet driver with a little more effort. -
        • -
      -
      • -
    • -

      NuttX-6.21 - Added support for a SPIFI block driver and for RS-485 option to the serial driver. -

      • -
    • -

      NuttX-7.17 - EMC support was extended to include support SDRAM by Vytautas Lukenska. -

      • -
    • -

      NuttX-7.23 - A CAN driver was contributed by Alexander Vasiljev in NuttX-7.23. -

      • -
    • -

      NuttX-7.24 - RTC and Windowed Watchdog Timer (WWDT) drivers were leveraged from the LPC17 and contributed by Gintaras Drukteinis. - Leveraged the LPC54xx SD/MMC to the LPC43xx. - There are still remaining issues with the SD/MMC driver and it is not yet functional. -

      • -
    -


    		-

    - NCP LPC54xx. - A port to the LPCXpresso-LPC54628 was added in NuttX-7.24. Initial configurations include: A basic NSH configuration (nsh), a networking configuration (netnsh), and three graphics configurations (nxwm, fb, and lvgl). -

    -

    - LPC4508. - The port was verified on an LPC5408 by a NuttX user with relevant changes incorporated in NuttX-7.26. -

    -

    		-

    - Driver Status. -

    -
      -
    • -

      NuttX-7.24 - The initial release for the LPC54xx in NuttX included the following drivers: UARTs, SysTick, SD/MMC, DMA, GPIO, GPIO interrupts, LEDs and buttons, LCD, WWDT, RTC, RNG, Ethernet, and SPI. The SPI driver is untested and there are known issues with the SD/MMC driver, however. -

      • -
    • -

      NuttX-7.29 - Configurations were added to verify the "Per-Window Framebuffer" feature also added in NuttX-7.29. -

      • -
    -

    - Refer to the LPCXpresso-LPC54628 board README file for more detailed information about this port. -

    -


    		-

    - NXP S32K14x. - Support for the S32K14x family was added in NuttX-8.1. - Two boards are supported -

    -
      -
    • S32K146EVB. - A port to the S32K146EVB was included in NuttX-8.1. The initial release supports two full-featured NSH configurations. - Refer to the S32K146EVB board README file for more detailed information about this port. -
      • -
    • S32K148EVB. - A port to the S32K148EVB was also provided in NuttX-8.1. The initial release supports two full-featured NSH configurations. - Refer to the S32K148EVB board README file for more detailed information about this port. -
      • -
    -

    - Both boards featured two NSH configurations: One for execution out of FLASH and a safe version that executes out of SRAM and, hence, cannot lock up the system because of a bad FLASH image. -

    -

    		-

    - Driver Status. -

    -
      -
    • -

      NuttX-8.1 - The initial release for the S32K14x boards in NuttX included the following verfied drivers: Basic boot up logic, clock configuration, LPUART - console, Systick timer, and GPIO controls. - Additional complete-but-unverified drivers were also included: GPIO interrupts, eDMA, LPSPI, LPI2C, and Ethernet (S32K148 only). -

      • -
    -


    		-

    - TI Stellaris LM4F120. - This port uses the TI Stellaris LM4F120 LaunchPad. - Jose Pablo Carballo and I are doing this port. -

    -
      -

      - STATUS: - As of this writing, the basic port is code complete and a fully verified configuration exists for the NuttShell NSH). - The first fully functional LM4F120 LaunchPad port was released in NuttX-6.27. -

      -
    -


    		-

    - TI Tiva TM4C123G. - This port uses the Tiva C Series TM4C123G LaunchPad Evaluation Kit (EK-TM4C123GXL). -

    -
      -

      - Refer to the EK-TM4C123GXL board README file for more detailed information about this port. -

      -
    -

    - TI Tiva TM4C123H. - Architectural support for the Tiva TM4C123AH6PM was contributed in NuttX-8.1 by Nathan Hartman. -

    - STATUS: -
      -
    • NuttX-7.1. - Initial architectural support for the EK-TM4C123GXL was implemented and was released in NuttX 7.1. - Basic board support the EK-TM4C123GXL was also included in that release but was not fully tested. - This basic board support included a configuration for the NuttShell NSH). -
      • -
    • NuttX-7.2. - The fully verified port to the EK-TM4C123GXL was provided in NuttX-7.2. -
      • -
    • NuttX-7.7. - An I2C driver was added in NuttX-7.7. -
      • -
    • NuttX-8.1. - Along with TM4C123AH6PM support, Nathan Hartman also reinstated and extended the Tiva Quadrature Encoder driver. -
      • -
    -


    		-

    - TI Tiva TM4C1294. - This port uses the TI Tiva C Series TM4C1294 Connected LaunchPad (EK-TM4C1294XL). -

    -
      -

      - STATUS: -

        -
      • - Support for the EK-TM4C1294XL was contributed by Frank Sautter and was released in NuttX 7.9. - This basic board support included a configuration for the NuttShell NSH) and a configuration for testing IPv6. - See drivers for the TI Tiva TM4C129X. -
        • -
      • - FLASH and EEPROM drivers from Shirshak Sengupta were included in NuttX-7.25. -
        • -
      -

      - Refer to the EK-TM4C1294XL board README file for more detailed information about this port. -

      -
    -


    		-

    - TI Tiva TM4C129X. - This port uses the TI Tiva C Series TM4C129X Connected Development Kit (DK-TM4C129X). -

    -
      -

      - STATUS: -

        -
      • - A mature port to the DK-TM4C129X was implemented and was released in NuttX 7.7. -
        • -
      • - At the initial release, verified drivers were available for Ethernet interface, I2C, and timers as well as board LEDs and push buttons. - Other Tiva/Stellaris drivers should port to the TM4C129X without major difficulty. -
        • -
      • - This board supports included two configurations for the NuttShell (NSH). - Both are networked enabled: One configured to support IPv4 and one configured to supported IPv6. - Instructions are included in the board README file for configuring both IPv4 and IPv6 simultaneously. -
        • -
      • - Tiva PWM and Quadrature Encoder drivers were contributed to NuttX in 7.18 by Young. -
        • -
      -

      - Refer to the DK-TM4C129X board README file for more detailed information about this port. -

      -
    -


    		-

    - TI/SimpleLink CC13x2. - Basic, unverified architectural support for the CC13x2 was added in NuttX-7.28. - Fragmentary support for very similar CC26x2 family is included. - This is a work in progress and, with any luck, a fully verified port will be available in NuttX-7.29. - It is currently code complete (minus some ROM DriverLib hooks) but untested. -

    -

    - TI LaunchXL-CC1312R1. - Basic board support for the TI LaunchXL-CC1312R1 board is in place. - Board bring-up, however, cannot be done until the the basic CC13x2 architecture support is complete, hopefully in NuttX-7.29. -

    -
      -

      - STATUS: - The basic port is nearly code complete but unverified in NuttX-7.28; The NSH configuration was fully functional in NuttX-7.29. - This effort is stalled on further radio development. - The plan was to integrate the IEEE 802.15.4 radio provided by the co-resident Cortex-M0. The Cortex-M0 interface, however, is not available with an open license that would permit redistribution. - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - Atmel SAM4L. - This port uses the Atmel SAM4L Xplained Pro development board. - This board features the ATSAM4LC4C MCU running at 48MHz with 256KB of FLASH and 32KB of internal SRAM. -

    -
      -

      - STATUS: - As of this writing, the basic port is code complete and a fully verified configuration exists for the NuttShell NSH). - The first fully functional SAM4L Xplained Pro port was released in NuttX-6.28. - Support for the SAM4L Xplained modules was added in NuttX-6.29: -

      -
        -
      • - Support for the SPI-based SD card on the I/O1 module. -
        • -
      • - Driver for the LED1 segment LCD module. -
        • -
      • - Support for the UG-2832HSWEG04 OLED on the SAM4L Xplained Pro's OLED1 module -
        • -
      -

      - Refer to the NuttX board README file for further information. -

      -

      - Memory Usage. - The ATSAM4LC4C comes in a 100-pin package and has 256KB FLASH and 32KB of SRAM. - Below is the current memory usage for the NSH configuration (June 9, 2013). - This is not a minimal implementation, but a full-featured NSH configuration. -

      -

      - Static memory usage can be shown with size command: -

      - 
        -$ size nuttx
-   text    data     bss     dec     hex filename
-  43572     122    2380   46074    b3fa nuttx
-
      -

      - NuttX, the NSH application, and GCC libraries use 42.6KB of FLASH leaving 213.4B of FLASH (83.4%) free from additional application development. - Static SRAM usage is about 2.3KB (<7%) and leaves 29.7KB (92.7%) available for heap at runtime. -

      - SRAM usage at run-time can be shown with the NSH free command. - This runtime memory usage includes the static memory usage plus all dynamic memory allocation for things like stacks and I/O buffers: - 
        -NuttShell (NSH) NuttX-6.28
-nsh> free
-             total       used       free    largest
-Mem:         29232       5920      23312      23312
-
      -

      - You can see that 22.8KB (71.1%) of the SRAM heap is still available for further application development while NSH is running. -

      -
    -


    		-

    - Atmel SAM4CM. - General architectural support was provided for SAM4CM family in NuttX 7.3 - This was architecture-only support, meaning that support for the boards with these chips is available, but no support for any publicly available boards was included. - The SAM4CM port should be compatible with most of the SAM3/4 drivers (like HSMCI, DMAC, etc.) but those have not be verified on hardware as of this writing. - This support was contributed in part by Max Neklyudov. -

    -

    		-

    - Atmel SAM4CMP-DB. - Support for the SAM4CMP-DB board was contributed to NuttX by Masayuki Ishikawa in NuttX-7.19. - The SAM4CM is a dual-CPU part and SMP was included for the ARMv7-M and SAM3/4 families. - The SAM4CMP-DB board support includes an NSH configuration that operates in an SMP configuration. - Refer to the NuttX board README file for further information. -

    -


    		-

    - Atmel SAM4E. - General architectural support was provided for the SAM4E family in NuttX 6.32. - This was architecture-only support, meaning that support for the boards with these chips is available, but no support for any publicly available boards was included. - This support was contributed in part by Mitko. -

    -

    - Atmel SAM4E-EK. - Board support was added for the SAM4E-EK development board in NuttX 7.1. - A fully functional NuttShell (NSH) configuration is available - (see the NSH User Guide). - That NSH configuration includes networking support and support for an AT25 Serial FLASH file system. -

    -
      - STATUS. - A new Ethernet MAC driver has been developed and is functional in the NSH configuration. - A DMA-base SPI driver is supported and has been verified with the AT25 Serial FLASH. - Touchscreen and LCD support was added in NuttX-7.3, but has not been fully integrated as of this writing. - The SAM4E-EK should be compatible with most of the other SAM3/4 drivers (like HSMCI, DMAC, etc.) but those have not be verified on the SAM4E-EK as of this writing. - Refer to the NuttX board README file for further information. -
    -


    		-

    - Atmel SAM4S. - There are ports to two Atmel SAM4S board: -

    -
      -
    • -

      - There is a port the Atmel SAM4S Xplained development board. - This board features the ATSAM4S16 MCU running at 120MHz with 1MB of FLASH and 128KB of internal SRAM. -

      -
        -

        - STATUS: - As of this writing, the basic port is code complete and a fully verified configuration exists for the NuttShell NSH). - The first fully functional SAM4S Xplained port was released in NuttX-6.28. - Support for the on-board 1MB SRAM was added in NuttX-6.29. - An RTT driver was Bob Doiron in NuttX-7.3. - Bob also added an high resolution RTC emulation using the RTT for the sub-second counter. - Refer to the NuttX board README file for further information. -

        -
      -
      • -
    • -

      - There is also a port to the Atmel SAM4S Xplained Pro development board. - This board features the ATSAM4S32C MCU running at 120MHz with 2MB of FLASH and 160KB of internal SRAM. -

      -
        -

        - STATUS: - As of this writing, the basic port is code complete and a fully verified configuration exists for the NuttShell NSH). - The first fully functional SAM4S Xplained Pro port was released in NuttX-7.2. - This supported also added HSMCI, RTC, and watchdog and verified support for USB device. - Refer to the NuttX board README file for further information. -

        -
      -
      • -
    -


    		-

    - Atmel SAM4E. - General architectural support was provided for the SAM4E family in NuttX 6.32. - This was architecture-only support, meaning that support for the boards with these chips is available, but no support for any publicly available boards was included. - This support was contributed in part by Mitko. -

    -

    - Atmel SAM4E-EK. - Board support was added for the SAM4E-EK development board in NuttX 7.1. - A fully functional NuttShell (NSH) configuration is available - (see the NSH User Guide). - That NSH configuration includes networking support and support for an AT25 Serial FLASH file system. -

    -
      - STATUS. - This is very much a work in progress. - A new Ethernet MAC driver has been developed and is functional in the NSH configuration. - A DMA-base SPI driver is supported and has been verified with the AT25 Serial FLASH. - The SAM4E-EK should be compatible with most of the other SAM3/4 drivers (like HSMCI, DMAC, etc.) but those have not be verified on the SAM4E-EK as of this writing. - Refer to the NuttX board README file for further information. -
    -


    		-

    - Development Environments: - 1) Linux with native Linux GNU toolchain, 2) Cygwin/MSYS with Cygwin GNU Cortex-M3 or 4 toolchain, 3) Cygwin/MSYS with Windows native GNU Cortex-M3 or M4 toolchain (CodeSourcery or devkitARM), or 4) Native Windows. A DIY toolchain for Linux or Cygwin is provided by the NuttX - buildroot package. -

    -
    - ARM Cortex-M7. -

    		-

    - Atmel SAMV71. - This port uses Atmel SAM V71 Xplained Ultra Evaluation Kit (SAMV71-XULT). - This board features the ATSAMV71Q21 Cortex-M7 microcontroller. - Refer to the Atmel web site for further information about this board. -

    -
      -

      - STATUS: - The basic port is complete and there are several different, verified configurations available. - All configurations use the NuttShell (NSH) and a serial console. - The first release of the SAMV71-XULT port was available in NuttX-7.9. - Support for the connect maXTouch Xplained Pro LCD as added in NuttX-7.10. -

      -

      - Additional drivers, with status as of 2015-04-03, include: -

      -
        -
      • PIO configuration, including PIO interrupts,
        • -
      • On-board LEDs and buttons,
        • -
      • DMA,
        • -
      • SDRAM (not yet functional),
        • -
      • UART/USART-based serial drivers, including the NuttShell serial console,
        • -
      • High Speed Memory Card Interface (HSMCI) with support for the on board SD card slot,
        • -
      • SPI (not fully tested),
        • -
      • TWIHS/I2C, with the support for the on-board serial EEPROM,
        • -
      • SSC/I2S (not fully tested),
        • -
      • Ethernet MAC,
        • -
      • USB device controller driver (complete, partially functional, but not well tested).
        • -
      • On-board AT24 I2C EEPROM.
        • -
      • On-board WM8904 Audio CODEC with CS2100-CP Fractional-N Multiplier (not yet tested).
        • -
      • Support for the (optional) maXTouch Xplained Pro LCD module.
        • -
      -

      - Additional Drivers added in NuttX-7.11 include: -

      -
        -
      • MCAN CAN device driver (fully verified in loopback mode only).
        • -
      • SPI slave driver.
        • -
      -

      - Additional Drivers added in NuttX-7.13 include: -

      -
        -
      • MPU and protected build mode support.
        • -
      • Timer/Counter driver, one-shot timer, free-running timer support.
        • -
      • Tickless mode of operation.
        • -
      • QuadSPI driver.
        • -
      • Support for programming on-chip FLASH.
        • -
      -

      - And in NuttX-7.14: -

      -
        -
      • TRNG driver,
        • -
      • WDT driver, and
        • -
      • RSWDT driver.
        • -
      -

      - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - Atmel SAME70. - This port uses Atmel SAM E70 Xplained Evaluation Kit (ATSAME70-XPLD). - This board is essentially a lower cost version of the SAMV71-XULT board featuring the ATSAME70Q21 Cortex-M7 microcontroller. - See the Atmel SAMV71 for supported features. - Also refer to the NuttX board README file for further information. -

    -


    		-

    - Atmel SAMD5x/E5x. - The port of NuttX to Adafruit Metro M4 development board was released with NuttX-7/26. - This board is essentially a advanced version of the Adafruit Metro board based on the SAMD21, but upgraded to the SAMD51, specifically the SAMD51J19. - See the Adafruit web page for additional information about the board. -

    -

    - A fully-function, basic NuttShell (NSH) configuration was was available in this initial NuttX-7.26 release. - That initial port verifies clock configuration boot-up logic, SysTick timer, and SERCOM USART for the serial console. - The NSH configuration also includes use of the Cortex-M Cache Controller (CMCC) which give the SAMD51's Cortex-M4 a performance boost. -

    -

    - Because of the similarity in peripherals, several drivers were brought in from the SAML21 port. - Most have not been verified as of the NuttX-7.26 release. - These unverfied drivers include: SPI, I2C, DMA, USB. - Also refer to the NuttX board README file for further information about the current state of the port. -

    -

    - Nuttx-9.0 added basic support for Microchip SAME54 Xplained Pro board. - An ethernet driver was also added to the SAME5x familly. -

    -


    		-

    - STMicro STM32 F72x/F73x. - Support for the F72x/F73x family was provided by Bob Feretich in NuttX-7.23. - A single board is supported in this family: -

    -
      -

      - Nucleo F722ZE. - This is a member of the common board support for the common Nucleo-144 boards, this one featuring the STM32F722ZE. - This port was also provided by Bob Feretich in NuttX-7.23. - See the board README.txt file for further information. -

      -
    -

    STATUS: - See below for STM32 F7 driver availability. -

    -


    		-

    - STMicro STM32 F745/F746. - Three boards are supported for this MCU: -

    -
      -
    1. -

      - STM32F746G Discovery. - One port uses the STMicro STM32F746G-DISCO development board featuring the STM32F746NGH6 MCU. The STM32F746NGH6 is a 216MHz Cortex-M7 operation with 1024Kb Flash. - The first release of the STM32F746G_DISCO port was available in NuttX-7.11. - Refer to the STMicro web site for further information about this board. -

      -
      2. -
    2. -

      - Nucleo-144 board with STM32F746ZG. - A basic port for the Nucleo-144 board with the STM32F746ZG MCU was contributed in NuttX-7.16 by Kconstantin Berezenko. -

      -
      3. -
    -
      -

      - STATUS: - Refer to the NuttX board README file for further information. -

      -
    -

    - STM32 F7 Driver Status: -

    -
      -
    • -

      NuttX-7.11. - Serial driver and Ethernet driver support, along with DMA support, were available in this initial release. - The STM32 F7 peripherals are very similar to some members of the STM32 F4 and additional drivers can easily be ported the F7 as discussed in this Wiki page: Porting Drivers to the STM32 F7 -

      -
      • -
    • -

      NuttX-7.17. - David Sidrane contributed PWR, RTC, BBSRAM, and DBGMCU support. - Lok Tep contribed SPI, I2c, ADC, SDMMC, and USB device driver support. -

      • -
    • -

      NuttX-7.22. - Titus von Boxberg also contributed LTDC support for the onboard LCD in NuttX-7.22. -

      -
      • -
    • -

      NuttX-7.29. - In NuttX-7.29, Valmantas Paliksa added a timer lowerhalf driver for STM32F7, ITM syslog support, a CAN driver with support for three bxCAN interfaces, and STM32F7 Quad SPI support. - Support for DMA and USB OTG was added by Mateusz Szafoni in NuttX-7.29. -

      -
      • -
    • -

      NuttX-7.30. - From Eduard Niesner contributed a PWM driver. - Added UID access from Valmantas Paliksa. - USB High speed driver was added for STM32F7 series by Ramtin Amin. -

      -
      • -
    • -

      NuttX-9.0. - Added serial DMA support. -

      -
      • -
    -


    		-

    - STMicro STM32 F756. - Architecture-only support is available for the STM32 F756 family (meaning that the parts are supported, but there is no example board supported in the system). - This support was made available in NuttX-7.11. - See above for STM32 F7 driver availability. -

    -


    		-

    - STMicro STM32 F76xx/F77xx. - Architecture support for the STM32 F76xx and F77xx families was contributed by David Sidrane in NuttX 7.17. Support is available for two boards from this family: -

    -
      -
    • -

      - Nucleo-F767ZI. - This is a member of the Nucleo-144 board family. - Support for this board was also contributed by David Sidrane in NuttX-7.17. - See the board README.txt file for further information. -

      -
      • -
    • -

      - STM32F76I-DISCO. - Support for the STM32F76I-DISCO was contributed by Titus von Boxberg in NuttX-7.22. - The STMicro STM32F769I-DISCO development board features the STM32F769NIH6 MCU. The STM32F769NIH6 is a 216MHz Cortex-M7 operating with 2048K Flash memory and 512Kb SRAM. The board features: -

      -
        -
      • On-board ST-LINK/V2 for programming and debugging,
        • -
      • Mbed-enabled (mbed.org)
        • -
      • 4-inch 800x472 color LCD-TFT with capacitive touch screen
        • -
      • SAI audio codec
        • -
      • Audio line in and line out jack
        • -
      • Two ST MEMS microphones
        • -
      • SPDIF RCA input connector
        • -
      • Two pushbuttons (user and reset)
        • -
      • 512-Mbit Quad-SPI Flash memory
        • -
      • 128-Mbit SDRAM
        • -
      • Connector for microSD card
        • -
      • RF-EEPROM daughterboard connector
        • -
      • USB OTG HS with Micro-AB connectors
        • -
      • Ethernet connector compliant with IEEE-802.3-2002 and PoE
        • -
      -

      - Refer to the http://www.st.com website for further information about this board (search keyword: stm32f769i-disco). - See also the board README.txt file for further information. -

      -
      • -
    -

    STATUS: - See above for STM32 F7 driver availability. -

    -


    		-

    - STMicro STM32 H7x3 - Architecture support for the STM32 H7x3 was added through efforts of several people in NuttX-7.26. Support is available for one board from this family: -

    -
      -
    • -

      - Nucleo-H743ZI. - This is a member of the Nucleo-144 board family. - Support for this board was added in NuttX-7.26. - See the board README.txt file for further information. -

      -

      - The basic NSH configuration is fully, thanks to the bring-up efforts of Mateusz Szafoni. - This port is still a work in progress and additional drivers are being ported from the F7 family. -

      -
      • -
    • -

      - STMicro STM32H747I-DISCO. - Support for this board was added in NuttX-9.0. - See the board README.txt file for further information. -

      -

      - This port is still a work in progress. -

      -
      • -
    -

    		 -

    Driver Availability:

    -
      -
    • -

      NuttX-7.27. - Add I2C and SPI support for the STM32H7. From Mateusz Szafoni. -

      -
      • -
    • -

      NuttX-7.30. - Added support for Ethernet, SDMMC, and Timer drivers. All from Jukka Laitinen. -

      -
      • -
    • -

      NuttX-8.1. - Added support for BBSRAM, DTCM, RTC, and UID. All from David Sidrane. -

      -
      • -
    • -

      NuttX-8.2. - Added support for SDMMC and FLASH progmem. From David Sidrane. -

      -
      • -
    • -

      NuttX-9.0. - Added QSPI support for the STM32H7. -

      -
      • -

      -


    		-

    - NXP/Freescale i.MX RT. - The initial port to the IMXRT1050-EVKB featuring the MIMXRT1052DVL6A Crossover MCU was included initially in NuttX-7.25. - The initial port was the joint effort of Janne Rosberg, Ivan Ucherdzhiev, and myself. - Ivan gets credit for the bulk of the bring-up work and for the Hyper FLASH boot logic. -

    - Another port, this one for the IMXRT1060-EVKB featuring the MIMXRT1062DVL6A Crossover MCU, was added by David Sidrane in NuttX-7.27. -

    -

    - STATUS: -

    -
      -

    • - The basic IMXRT1050-EVK port is complete and verified configurations are available. - Refer to the NuttX board README file for further information. -

      • -

    • - The basic IMXRT1060-EVK port was complete but un-verified as of NuttX-7.27 but has been fully verified since NuttX-7.27 - Refer to the NuttX board README file for more current status information. -

      • -

    • - Architecture-only support for the IMXRT1020 family was contributed in NuttX-7.30 by Dave Marples. -

      • -

    • - The basic IMXRT1020-EVK port was complete with verified configurations in NuttX-8.2. - This is again the work of Dave Marples. - The initial release includes nsh, netnsh, and usdhc configurations. - Refer to the NuttX board README file for further information. -

      • -
    -

    - i.MX RT Driver Status: -

    -
      -
    • -

      NuttX-7.25. - The initial release in NuttX-7.25 includes UART, Timer, GPIO, DMA, and Ethernet support (Ethernet support was contributed by Jake Choy). -

      -
    • -

      NuttX-7.26. - NuttX-7.26 added RTC, SNVS, and Serial TERMIOS support. -

      -
      • -
    • -

      NuttX-7.27. - NuttX-7.27 added LPI2C (from Ivan Ucherdzhiev) and SD card support via USDHC (from Dave Marples). -

      -
    • -

      NuttX-7.28. - GPIO support Input daisy selection was added in NuttX-7.28 by David Sidrane -

      -
      • -
    • -

      NuttX-7.29. - XBAR and OCOTP support was added in NuttX-7.28 by David Sidrane. - LCD Framebuffer support was added by Johannes. -

      -
      • -
    • -

      NuttX-7.31. - USB EHCI Host and USDHC drivers were added in NuttX-7.31 by Dave Marples. -

      -
      • -
    • -

      NuttX-8.2. - An LCD drivers was added in NuttX-8.2 by Fabio Balzano. -

      -

      NuttX-9.0. - Added USB Device support. -

      -
      • -
    -


    		-

    - Development Environments: - The same basic development environment is recommended for the Cortex-M7 as for the Cortex-M4. - It would be wise to use the latest GNU toolchains for this part because as of this writing (2015-02-09), support for the Cortex-M7 is a very new GCC feature. -

    -
    - Atmel AVR. -

    		-

    - AVR ATMega. -

    -
      -

      - SoC Robotics ATMega128. - This port of NuttX to the Amber Web Server from SoC Robotics - is partially completed. - The Amber Web Server is based on an Atmel ATMega128. -

      -
        -

        - STATUS: - Work on this port has stalled due to toolchain issues. Complete, but untested code for this port appears in the NuttX 6.5 release. - Refer to the NuttX board README file for further information. -

        -
      -

      - LowPowerLab MoteinoMEGA. - This port of NuttX to the MoteinoMEGA from LowPowerLab. - The MoteinoMEGA is based on an Atmel ATMega1284P. - See the LowPowerlab website and the board README file for further information. -

      -
        -

        - STATUS: - The basic function port support the NuttShell (NSH) was contribute by Jedi Tek'Enum and first appeared in the NuttX 7.8 release. -

        -
      -

      - Arduino MEGA2560. - Extension of the AVR architecture to support the ATMega2560 and specifi support for the Arduion MEGA2560 board were contributed by Dimitry Kloper and first released in NuttX-7.14. -

      -
        -

        - STATUS: - The basic port was released in NuttX-7.14 including a simple "Hello, World!" and OS test configurations. - Extensive effort was made to the use the special capabilities of the Atmel Studio AVR compiler to retain strings in FLASH memory and so keep the SRAM memory usage to a minimum. - Refer to the NuttX board README file for further information. -

        -
      -
    -


    		-

    - AVR AT90USB64x and AT90USB6128x. -

    -
      -

      - Micropendous 3 AT90USB64x and AT90USB6128x. - This port of NuttX to the Opendous Micropendous 3 board. The Micropendous3 is - may be populated with an AT90USB646, 647, 1286, or 1287. I have only the AT90USB647 - version for testing. This version have very limited memory resources: 64K of - FLASH and 4K of SRAM. -

      -
        -

        - STATUS: - The basic port was released in NuttX-6.5. This basic port consists only of - a "Hello, World!!" example that demonstrates initialization of the OS, - creation of a simple task, and serial console output. - Refer to the NuttX board README file for further information. -

        -
      -

      - PJRC Teensy++ 2.0 AT90USB1286. - This is a port of NuttX to the PJRC Teensy++ 2.0 board. - This board was developed by PJRC. - The Teensy++ 2.0 is based on an Atmel AT90USB1286 MCU. -

      -
        -

        - STATUS: - The basic port was released in NuttX-6.5. This basic port consists of - a "Hello, World!!" example that demonstrates initialization of the OS, - creation of a simple task, and serial console output as well as a somewhat - simplified NuttShell (NSH) configuration (see the - NSH User Guide). -

        -

        - An SPI driver and a USB device driver exist for the AT90USB as well - as a USB mass storage configuration. However, this configuration is not - fully debugged as of the NuttX-6.5 release. - Refer to the NuttX board README file for further information. -

        -
      -


    		 -

    AVR-Specific Issues. - The basic AVR port is solid. - The biggest issue for using AVR is its tiny SRAM memory and its Harvard architecture. - Because of the Harvard architecture, constant data that resides to flash is inaccessible using "normal" memory reads and writes (only SRAM data can be accessed "normally"). - Special AVR instructions are available for accessing data in FLASH, but these have not been integrated into the normal, general purpose OS. -

    -

    - Most NuttX test applications are console-oriented with lots of strings used for printf() and debug output. - These strings are all stored in SRAM now due to these data accessing issues and even the smallest console-oriented applications can quickly fill a 4-8K memory. - So, in order for the AVR port to be useful, one of two things would need to be done: -

    -
      -
    1. - Don't use console applications that required lots of strings. - The basic AVR port is solid and your typical deeply embedded application should work fine. - Or, -
      2. -
    2. - Create a special version of printf that knows how to access strings that reside in FLASH (or EEPROM). -
      3. -
    -


    		 -

    - Development Environments: - 1) Linux with native Linux GNU toolchain, 2) Cygwin/MSYS with Cygwin GNU toolchain, 3) Cygwin/MSYS with Windows native toolchain, or 4) Native Windows. - All testing, however, has been performed using the NuttX DIY toolchain for Linux or Cygwin is provided by the NuttX - buildroot package. - As a result, that toolchain is recommended. -

    -


    - Atmel AVR32. -

    		-

    - AV32DEV1. - This port uses the www.mcuzone.com AVRDEV1 board based on the Atmel AT32UC3B0256 MCU. - This port requires a special GNU avr32 toolchain available from atmel.com website. - This is a windows native toolchain and so can be used only under Cygwin on Windows. -

    -
      -

      - STATUS: - This port is has completed all basic development, but there is more that needs to be done. - All code is complete for the basic NuttX port including header files for all AT32UC3* peripherals. - The untested AVR32 code was present in the 5.12 release of NuttX. - Since then, the basic RTOS port has solidified: -

      -
        -
      • - The port successfully passes the NuttX OS test (apps/examples/ostest). -
        • -
      • - A NuttShell (NSH) configuration is in place (see the NSH User Guide). - Testing of that configuration has been postponed (because it got bumped by the Olimex LPC1766-STK port). - Current Status: I think I have a hardware problem with my serial port setup. - There is a good chance that the NSH port is complete and functional, but I am not yet able to demonstrate that. - At present, I get nothing coming in the serial RXD line (probably because the pins are configured wrong or I have the MAX232 connected wrong). -
        • -
      -

      - The basic, port was be released in NuttX-5.13. - A complete port will include drivers for additional AVR32 UC3 devices -- like SPI and USB --- and will be available in a later release, - time permitting. - Refer to the NuttX board README file for further information. -

      -
    -
    - Misoc. -

    		-

    - Misoc LM32 Architectural Support. - Architectural support for the Misoc LM32 was contributed by Ramtin Amin in NuttX 7.19 -

    - Minerva. - Architectural support for the Misoc Minoerva was contributed by Ramtin Amin in NuttX 7.29. -

    -

    - Drivers. - Driver support is basic in these initial releases: Serial, Timer, and Ethernet. "Board" support is a available for developing with Misoc LM32 under Qemu or on your custom FPGA. -

    - OpenRISC mor1kx. -

    		-

    - OpenRISC mor1kx Architectural Support. - Architectural support for the OpenRISC mor1kx was developed by Matt Thompson Amin and released in NuttX 7.25. Currently only an mor1kx Qemu simulation is available for testing. -

    -
    - Freescale M68HCS12. -

    		-

    - MC9S12NE64. - Support for the MC9S12NE64 MCU and two boards are included: -

    -
      -
    • - The Freescale DEMO9S12NE64 Evaluation Board, and -
      • -
    • - The Future Electronics Group NE64 /PoE Badge board. -
      • -
    -

    - Both use a GNU arm-nuttx-elf toolchain* under Linux or Cygwin. - The NuttX buildroot provides a properly patched GCC 3.4.4 toolchain that is highly optimized for the m9s12x family. -

    -
      -

      - STATUS: - Coding is complete for the MC9S12NE64 and for the NE64 Badge board. - However, testing has not yet begun due to issues with BDMs, Code Warrior, and - the paging in the build process. - Progress is slow, but I hope to see a fully verified MC9S12NE64 port in the near future. - Refer to the NuttX board README files for DEMO9S12NE64 and for the NE64 /PoE Badge for further information. -

      -
    -
    - Intel 80x86. -

    		-

    - QEMU/Bifferboard i486. - This port uses the QEMU i486 and the native - Linux, Cygwin, MinGW the GCC toolchain under Linux or Cygwin. -

    -
      -

      - STATUS: - The basic port was code-complete in NuttX-5.19 and verified in NuttX-6.0. - The port was verified using the OS and NuttShell (NSH) examples under QEMU. - The port is reported to be functional on the Bifferboard as well. - In NuttX 7.1, Lizhuoyi contributed additional keyboard and VGA drivers. - This is a great, stable starting point for anyone interested in fleshing out the x86 port! - Refer to the NuttX README file for further information. -

      -

      - QEMU/Intel64 - An x86_64 flat address port was ported in NuttX-9.0. - It consists of the following feautres: -

        -
      • - Runs in x86_64 long mode.
        • -
      • - Configurable SSE/AVX support.
        • -
      • - IRQs are managed by LAPIC(X2APIC) and IOAPIC.
        • -
      • - Used TSC_DEADLINE or APIC timer for systick.
        • -
      • - Pages are now maps the kernel at 4GB~, but changeable.
        • -
      -

      -

      - This kernel with ostest have been tested with -

        -
      • Qemu/KVM on a Xeon 2630v4 machine.
        • -
      • Bochs with broadwell_ult emulation.
        • -
      -

      -
    -
    - Microchip PIC32MX (MIPS M4K). -

    		-

    - PIC32MX250F128D. - A port is in progress from the DTX1-4000L "Mirtoo" module from Dimitech. - This module uses Microchip PIC32MX250F128D and the Dimitech DTX1-4000L EV-kit1 V2. - See the Dimitech website for further information. -

    -
      -

      - STATUS: - The basic port is code complete. - The OS test configuration is fully functional and proves that we have a basically healthy NuttX port to the Mirtoo. - A configuration is available for the NuttShell (NSH). - The NSH configuration includes support for a serial console and for the SST25 serial FLASH and the PGA117 amplifier/multiplexer on board the module. - The NSH configuration is set up to use the NuttX wear-leveling FLASH file system (NXFFS). - The PGA117, however, is not yet fully integrated to support ADC sampling. - See the NSH User Guide for further information about NSH. - The first verified port to the Mirtoo module was available with the NuttX 6.20 release. - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - PIC32MX4xx Family. -

    -
      -

      - PIC32MX440F512H. - This port uses the "Advanced USB Storage Demo Board," Model DB-DP11215, from Sure Electronics. - This board features the Microchip PIC32MX440F512H. - See the Sure website for further information about the DB-DP11215 board. - (I believe that that the DB-DP11215 may be obsoleted now but replaced with the very similar, DB-DP11212. - The DB-DP11212 board differs, I believe, only in its serial port configuration.) -

      -
        -

        - STATUS: - This NuttX port is code complete and has considerable test testing. - The port for this board was completed in NuttX 6.11, but still required a few bug fixes before it will be ready for prime time. - The fully verified port first appeared in NuttX 6.13. - Available configurations include the NuttShell (NSH - see the NSH User Guide). - An untested USB device-side driver is available in the source tree. - A more complete port would include support of the USB OTG port and of the LCD display on this board. - Those drivers are not yet available as of this writing. - Refer to the NuttX board README file for further information. -

        -
      -

      - PIC32MX460F512L. - There one two board ports using this chip: -

      -
        -
      • PIC32MX Board from PCB Logic Design Co. - This port is for the PIC32MX board from PCB Logic Design Co. and used the PIC32MX460F512L. - The board is a very simple -- little more than a carrier for the PIC32 MCU plus voltage regulation, debug interface, and an OTG connector. -
        • -

        - STATUS: - The basic port is code complete and fully verified in NuttX 6.13. - Available configurations include the NuttShell (NSH - see the NSH User Guide). - Refer to the NuttX board README file for further information. -

        -
      • UBW32 Board from Sparkfun - This is the port to the Sparkfun UBW32 board. - This port uses the original v2.5 board which is based on the Microchip PIC32MX460F512L. - This older version has been replaced with this newer board. - See also the UBW32 web site. -
        • -

        - STATUS: - The basic port is code complete and fully verified in NuttX 6.18. - Available configurations include the NuttShell (NSH - see the NSH User Guide). - USB has not yet been fully tested but on first pass appears to be functional. - Refer to the NuttX board README file for further information. -

        -
      -
    -


    		-

    - PIC32MX795F512L. - There one two board ports using this chip: -

    -
      -
    • Microchip PIC32 Ethernet Starter Kit. - This port uses the Microchip PIC32 Ethernet Starter Kit (DM320004) with the Expansion I/O board. - See the Microchip website for further information. -
      • -

      - STATUS: - This port was started and then shelved for some time until I received the Expansion I/O board. - The basic Starter Kit (even with the Multimedia Expansion Board, MEB, DM320005)) has no serial port and most NuttX test configurations depend heavily on console output. -

      -

      - A verified configuration is available for the NuttShel (NSH) appeared in NuttX-6.16. - Board support includes a verified USB (device-side) driver. - Also included are a a verified Ethernet driver, a partially verified USB device controller driver, and an unverifed SPI driver. - Refer to the NuttX board README file for further information. -

      -
    • Mikroelektronika PIC32MX7 Mulitmedia Board (MMB). - A port has been completed for the Mikroelektronika PIC32MX7 Multimedia Board (MMB). - See http://www.mikroe.com/ for further information about this board. -
      • -

      - STATUS: - A verified configuration is available for an extensive NuttShell (NSH) configuration. - The NSH configuration includes: - (1) Full network support, - (2) Verified SPI driver, - (3) SPI-based SD Card support, - (4) USB device support (including configuration options for the USB mass storage device and the CDC/ACM serial class), and - (5) Support for the MIO283QT2 LCD on the PIC32MX7 MMB. - (6) Support for the MIO283QT9A LCD used on later boards (NuttX 7.1). -

      -

      - The PIC32MX7 MMB's touchscreen is connected directly to the MCU via ADC pins. - A touchscreen driver has been developed using the PIC32's ADC capabilities and can be enabled in the NSH configuration. - However, additional verification and tuning of this driver is required. - Further display/touchscreen verification would require C++ support (for NxWidgets and NxWM). - Since I there is no PIC32 C++ is the free version of the MPLAB C32 toolchain, further graphics development is stalled. - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - Development Environment: - These ports uses either: -

    -
      -
    1. - The LITE version of the PIC32MX toolchain available - for download from the Microchip website, or -
      2. -
    2. - The Pinguino MIPS ELF toolchain available from the Pinguino website. -
      3. -
    3. - The MIPS SDE toolchain available from the Mentor Graphics website. -
      4. -
    -
    - Microchip PIC32MZ. -

    		-

    - PIC32MZEC Family (MIPS microAptiv). - A port is in available for the PIC32MZ Embedded Connectivity (EC) Starter Kit. - There are two configurations of the Microchip PIC32MZ EC Starter Kit: -

    -
      -
    1. The PIC32MZ Embedded Connectivity Starter Kit based on the PIC32MZ2048ECH144-I/PH chip (DM320006), and
      2. -
    2. The PIC32MZ Embedded Connectivity Starter Kit based on the PIC32MZ2048ECM144-I/PH w/Crypto Engine (DM320006-C).
      3. -
    -

    - See the Microchip website for further information. -

    -

    - This was a collaborative effort between Kristopher Tate, David Sidrane and myself. - The basic port is functional and a NuttShell (NSH) configuration is available. -

    -

    - PIC32MZEF Family (MIPS M5150). - A port is in available for the MikroElectronika Flip&Click PIC32MZ development board based on the PIC32MZ2048EFH100 MCU. - This board configuration was added in NuttX-7.24 and is, for the most part, compatible with the PIC32MZEC family. -

    -

    - STATUS: -

    -
      -

      - NuttX-7.9. - The first official release was in NuttX-7.9. - Many drivers port simply from the PIC32MX; others require more extensive efforts. - Driver status as of (2015-03-29) is provided below: -

      -

        -
      • I/O ports include I/O port interrupts
        • -
      • UART serial driver that provides the NSH console,
        • -
      • Timer,
        • -
      • I2C (untested),
        • -
      • SPI (untested),
        • -
      • On-board buttons and LEDs,
        • -
      • Ethernet (code complete, but not yet functional),
        • -
      -

      - NuttX-7.29. - Abdelatif Guettouche contributed additional timer support including: Timer lower half driver, free-running, and one-shot timers. -

      -

      - NuttX-7.31. - Abdelatif Guettouche contributed DMA support. -

      -

      - NuttX-9.0. - Cache operations were implemented. -

      -
    -

    - Refer to the NuttX board README file for further information. -

    -


    		-

    - Development Environment: - Same as for the PIC32MZ. -

    -

    - Renesas/Hitachi SuperH. -

    		-

    - SH-1 SH7032. - This port uses the Hitachi SH-1 Low-Cost Evaluation Board (SH1_LCEVB1), US7032EVB, - with a GNU ELF toolchain* under Linux or Cygwin. -

    -
      -

      - STATUS: - This port is available as of release 0.3.18 of NuttX. The port is basically complete - and many examples run correctly. However, there are remaining instabilities that - make the port un-usable. The nature of these is not understood; the behavior is - that certain SH-1 instructions stop working as advertised. This could be a silicon - problem, some pipeline issue that is not handled properly by the gcc 3.4.5 toolchain - (which has very limit SH-1 support to begin with), or perhaps with the CMON debugger. - At any rate, I have exhausted all of the energy that I am willing to put into this cool - old processor for the time being. - Refer to the NuttX board README file for further information. -

      -
    -
    - Renesas M16C/26. -

    		-

    - Renesas M16C/26 Microcontroller. - This port uses the Renesas SKP16C26 Starter kit and the GNU M32C toolchain. - The development environment is either Linux or Cygwin under WinXP. -

    -
      -

      - STATUS: - Initial source files released in nuttx-0.4.2. - At this point, the port has not been integrated; the target cannot be built - because the GNU m16c-nuttx-elf-ld link fails with the following message: -

      -
        - m32c-nuttx-elf-ld: BFD (GNU Binutils) 2.19 assertion fail /home/Owner/projects/nuttx/buildroot/toolchain_build_m32c/binutils-2.19/bfd/elf32-m32c.c:482 -
      -

      Where the reference line is:

      - 
        -/* If the symbol is out of range for a 16-bit address,
-   we must have allocated a plt entry.  */
-BFD_ASSERT (*plt_offset != (bfd_vma) -1);
-
      -

      - No workaround is known at this time. This is a show stopper for M16C. - Refer to the NuttX board README file for further information. -

      -
    -
    - Renesas RX65N. -

    		-

    - Support for the Renesas RX65N family was released in NuttX with a contribution from Anjana. - Two boards are supported in this initial release: -

    -
      -
    • RSK RX65N-2MB.
      • - This board features the R5F565NEHDFC (176pin). - Refer to the boar README file for further information. -
    • GR-Rose.
      • - The GR-ROSE board was produced by Gadget Renesas. - This board features the R5F565NEHDFP (100pin QFP). - Refer to the board README file for further information. -
    -

    STATUS

    -
      -
    • NuttX-8.2
      • - Basic support for the RX65N family was released by Anjana with support for two boards: The RSK RX65N-2MB and the GR-Rose. -
    • NuttX-9.0 - RTC driver for the RX65N was added. -
      • -
    -
    - RISC-V. -

    		-

    - RISC-V Architectural Support. - Basic support for the RISC-V architecture was contributed by Ken Pettit in NuttX-7.19. - This support is for a custom NEXT RISC-V NR5Mxx (RV32IM). - The initial release is thin but a great starting point for anyone interested in RISC-V development with NuttX. -

    -

    - GreenWaves GAP8 (RV32IM). - Basic support GreenWaves GAP8 gapuino board was added by hhuysqt in NuttX-7.27. - The GAP8 is a 1+8-core DSP-like RISC-V MCU. - The GAP8 features a RI5CY core called Fabric Controller(FC), and a cluster of 8 RI5CY cores that runs at a bit slower speed. - The GAP8 is an implementation of the opensource PULP platform, a Parallel-Ultra-Low-Power design. -

    -

    -

  • Sipeed Maix bit
    • - Initial support for the Sipeed Maix bit board was added in Nuttx-9.0. -

    -

    - Litex ARTY_A7. - Support for the Digilent ARTY_A7 board along with CPU VexRiscV SOC were added - in NuttX-9.0. -

    -
    - ESP32 (Dual Xtensa LX6). -

    		-

    - Xtensa LX6 ESP32 Architectural Support. - Basic architectural support for Xtensa LX6 processors and the port for the Espressif ESP32 were added in NuttX-7.19. - The basic ESP32 port is function in both single CPU and dual CPU SMP configurations. -

    -

    - Espressif ESP32 Core v2 Board - The NuttX release includes support for Espressif ESP32 Core v2 board. - There is an NSH configuration for each CPU configuration and an OS test configuration for verificatin of the port. -

    -

    - STATUS. - ESP32 support in NuttX-7.19 is functional, but very preliminary. - There is little yet in the way of device driver support. - Outstanding issues include missing clock configuration logic, missing partition tables to support correct configuration from FLASH, and some serial driver pin configuration issues. - The configuration is usable despite these limitations. - Refer to the NuttX board README file for further information. -

    - Zilog ZNEO Z16F. -

    		-
      -
    • -

      - Zilog z16f2800100zcog development kit. - This port use the Zilog z16f2800100zcog development kit and the Zilog - ZDS-II Windows command line tools. - The development environment is either Windows native or Cygwin under Windows. -

      -

      - STATUS: - The initial release of support for the z16f was made available in NuttX version 0.3.7. - A working NuttShell (NSH) configuration as added in NuttX-6.33 (although a patch is required to work around an issue with a ZDS-II 5.0.1 tool problem). - An ESPI driver was added in NuttX-7.2. - Refer to the NuttX board README file for further information. -

      -
      • -
    -
    - Zilog eZ80 Acclaim!. -

    		-

    - Zilog eZ80Acclaim! Microcontroller. - There are four eZ80Acclaim! ports: -

    -
      -
    • The ZiLOG ez80f0910200kitg development kit. -
    • The ZiLOG ez80f0910200zcog-d development kit. -
    • The MakerLisp CPU board. -
    • The Z20x DIY computing system. -
    -

    - All three boards are based on the eZ80F091 part and all use the Zilog ZDS-II - Windows command line tools. - The development environment is either Windows native or Cygwin or MSYS2 under Windows. -

    -
      -

      - NuttX-0.4.x: - Integration and testing of NuttX on the ZiLOG ez80f0910200zcog-d was completed. - The first integrated version was released in NuttX version 0.4.2 (with important early bugfixes - in 0.4.3 and 0.4.4). - As of this writing, that port provides basic board support with a serial console, SPI, and eZ80F91 EMAC driver. - Refer to the NuttX board README files for the ez80f0910200kitg and ez80f910200zcofile for further information. -

      -

      - NuttX-7.31: - Support for the MakerLisp board as well as an RTC driver and an improved SPI driver were included. - The MakerLisp machine is a portable, modular computer system, designed to recapture the feel of classic computing, with modern hardware. -

      -

      - The machine centers on a 2" x 3.5" business card-sized CPU, which can be used stand-alone, or plugged in to a 2" x 8" main board, for expansion into a full computer system. - A laser-cut wood enclosure holds a small keyboard, an LCD monitor, the circuit boards, and a prototyping area with a breadboard for electronics experimentation and development. -

      -

      - The eZ80 running at 50 MHz, with up to 16 Mb of zero-wait state RAM. - A VGA display adapter provides an IBM PC-like color text-mode display; - A USB keyboard adapter provides for standard keyboard input. - Data storage and interchange is accomplished by a SPI-based micro-SD card. -

      -

      - NuttX-9.0: - Support for the Z20X board was added. The port includes: - - Initial support to have a functional nsh. - - Support for SPI and W25 FLASH. - - A bootloader capable of writing code to the W25 FLASH and load it to the - SRAM to be executed. -

      -
    -
    - Zilog Z8Encore!. -

    		-

    - Zilog Z8Encore! Microcontroller. - This port uses the either: -

    -
      -
    • Zilog z8encore000zco development kit, Z8F6403 part, or
      • -
    • Zilog z8f64200100kit development kit, Z8F6423 part
      • -
    -

    - and the Zilog ZDS-II Windows command line tools. - The development environment is either Windows native or Cygwin under Windows. -

    -
      -

      - STATUS: - This release has been verified only on the ZiLOG ZDS-II Z8Encore! chip simulation - as of nuttx-0.3.9. - Refer to the NuttX board README files for the z8encore000zco and for thez8f64200100kit for further information. -

      -
        -
    - Zilog Z180. -

    		-

    - P112. - The P112 is a hobbyist single board computer based on a 16MHz Z80182 with up to 1MB of memory, serial, parallel and diskette IO, and realtime clock, in a 3.5-inch drive form factor. - The P112 computer originated as a commercial product of "D-X Designs Pty Ltd"[ of Australia. -

    -

    - Dave Brooks was successfully funded through Kickstarter for and another run of P112 boards in November of 2012. - In addition Terry Gulczynski makes additional P112 derivative hobbyist home brew computers. -

    -
      -

      - STATUS: - Most of the NuttX is in port for both the Z80182 and for the P112 board. - Boards from Kickstarter project will not be available, however, until the third quarter of 2013. - So it will be some time before this port is verified on hardware. - Refer to the NuttX board README file for further information. -

      -
        -
    - Zilog Z80. -

    		-

    - Z80 Instruction Set Simulator. - This port uses the SDCC toolchain - under Linux or Cygwin (verified using version 2.6.0). - This port has been verified using only a Z80 instruction simulator called z80sim. -

    -
      -

      - STATUS: - This port is complete and stable to the extent that it can be tested - using an instruction set simulator. - Refer to the NuttX board README file for further information. -

      -
        -


    		-

    - XTRS: TRS-80 Model I/III/4/4P Emulator for Unix. - A very similar Z80 port is available for XTRS, - the TRS-80 Model I/III/4/4P Emulator for Unix. - That port also uses the SDCC toolchain - under Linux or Cygwin (verified using version 2.6.0). -

    -
      -

      - STATUS: - Basically the same as for the Z80 instruction set simulator. - This port was contributed by Jacques Pelletier. - Refer to the NuttX board README file for further information. -

      -

      - NOTE: - This port was removed from the NuttX source tree on 2017-11-24. - It was removed because (1) it is unfinished, unverified, and unsupported, and (2) the TRS-80 simulation is a sub-optimal platform.i - That platform includes a 16-bit ROM image and only a 48Kb RAM space for NuttX. - The removed board support is still available in the Obsoleted repository if anyone would ever like to resurrect it. -

        -
    - -
    * A highly modified buildroot -is available that may be used to build a NuttX-compatible ELF toolchain under -Linux or Cygwin. Configurations are available in that buildroot to support ARM, Cortex-M3, -avr, m68k, m68hc11, m68hc12, m9s12, blackfin, m32c, h8, and SuperH ports.
    - - - - - -
    -

    Development Environments

     -
    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Linux + GNU make + GCC/binutils for Linux -

    		-

    - The is the most natural development environment for NuttX. - Any version of the GCC/binutils toolchain may be used. - There is a highly modified buildroot - available for download from the - NuttX Bitbucket.org - page. - This download may be used to build a NuttX-compatible ELF toolchain under Linux or Cygwin. - That toolchain will support ARM, m68k, m68hc11, m68hc12, and SuperH ports. - The buildroot GIT may be accessed in the NuttX - buildroot GIT. -

    -
    - Linux + GNU make + SDCC for Linux -

    		-

    - Also very usable is the Linux environment using the - SDCC compiler. - The SDCC compiler provides support for the 8051/2, z80, hc08, and other microcontrollers. - The SDCC-based logic is less well exercised and you will likely find some compilation - issues if you use parts of NuttX with SDCC that have not been well-tested. -

    -
    - Windows with Cygwin + GNU make + GCC/binutils (custom built under Cygwin) -

    		-

    - This combination works well too. - It works just as well as the native Linux environment except that compilation and build times are a little longer. - The custom NuttX buildroot referenced above may be build in the Cygwin environment as well. -

    -
    - Windows with Cygwin + GNU make + SDCC (custom built under Cygwin) -

    		-

    - I have never tried this combination, but it would probably work just fine. -

    -
    - Windows with Cygwin + GNU make + Windows Native Toolchain -

    		-

    - This is a tougher environment. - In this case, the Windows native toolchain is unaware of the - Cygwin sandbox and, instead, operates in the native Windows environment. - The primary difficulties with this are: -

    -
      -
    • - Paths. - Full paths for the native toolchain must follow Windows standards. - For example, the path /home/my\ name/nuttx/include my have to be - converted to something like 'C:\cygwin\home\my name\nuttx\include' - to be usable by the toolchain. -
      • -

      - Fortunately, this conversion is done simply using the cygpath utility. -

      -
    • - Symbolic Links - NuttX depends on symbolic links to install platform-specific directories in the build system. - On Linux, true symbolic links are used. - On Cygwin, emulated symbolic links are used. - Unfortunately, for native Windows applications that operate outside of the - Cygwin sandbox, these symbolic links cannot be used. -
      • -

      - The NuttX make system works around this limitation by copying the platform - specific directories in place. - These copied directories make work a little more complex, but otherwise work well. -

      -

      - NOTE: In this environment, it should be possible to use the NTFS mklink command to create links. - This should only require a minor modification to the build scripts (see tools/copydir.sh script). -

      -
    • - Dependencies - NuttX uses the GCC compiler's -M option to generate make dependencies. These - dependencies are retained in files called Make.deps throughout the system. - For compilers other than GCC, there is no support for making dependencies in this way. -
      • -

      - NOTE: dependencies may be suppressed by setting the make variable MKDEPS to point - to the do-nothing dependency script, tools/mknulldeps.sh. -

      -
    -

    - Supported Windows Native Toolchains. - At present, the following Windows native toolchains are in use: -

      -
    1. GCC built for Windows (such as CodeSourcery, Atollic, devkitARM, etc.),
      2. -
    2. SDCC built for Windows,
      3. -
    3. the ZiLOG XDS-II toolchain for Z16F, z8Encore, and eZ80Acclaim parts.
      4. -
    -

    -
    - Windows Native (CMD.exe) + GNUWin32 (including GNU make) + MinGW Host GCC compiler + Windows Native Toolchain -

    		-

    - Build support has been added to support building natively in a Windows console rather than in a POSIX-like environment. -

    -

    - This build: -

    -
      -
    1. Uses all Windows style paths
      2. -
    2. Uses primarily Windows batch commands from cmd.exe, with
      3. -
    3. A few extensions from GNUWin32
      4. -
    -

    - This capability first appeared in NuttX-6.24 and should still be considered a work in progress because: (1) it has not been verfied on all targets and tools, and (2) still lacks some of the creature-comforts of the more mature environments. - The windows native build logic initiated if CONFIG_WINDOWS_NATIVE=y is defined in the NuttX configuration file: -

    -

    - At present, this build environment also requires: -

    -
      -
    • - Windows Console. - The build must be performed in a Windows console window. - This may be using the standard CMD.exe terminal that comes with Windows. - I prefer the ConEmu terminal which can be downloaded from: - http://code.google.com/p/conemu-maximus5/ -
      • -
    • - GNUWin32. - The build still relies on some Unix-like commands. - I usethe GNUWin32 tools that can be downloaded from http://gnuwin32.sourceforge.net/. - See the top-level nuttx/README.txt file for some download, build, and installation notes. -
      • -
    • - MinGW-GCC. - MinGW-GCC is used to compiler the C tools in the nuttx/tools directory that are needed by the build. - MinGW-GCC can be downloaded from http://www.mingw.org/. - If you are using GNUWin32, then it is recommended that you not install the optional MSYS components as there may be conflicts. -
      • -
    - Wine + GNU make + Windows Native Toolchain -

    		-

    - I've never tried this one, but I off the following reported by an ez80 user using the ZiLOG ZDS-II Windows-native toolchain: -

    -
    -

    - "I've installed ZDS-II 5.1.1 (IDE for ez80-based boards) on wine (windows emulator for UNIX) and to my surprise, not many changes were needed to make GIT snapshot of NuttX buildable... - I've tried nsh profile and build process completed successfully. - One remark is necessary: NuttX makefiles for ez80 are referencing cygpath utility. - Wine provides similar thing called winepath which is compatible and offers compatible syntax. - To use that, winepath (which itself is a shell script) has to be copied as cygpath somewhere in $PATH, and edited as in following patch: -

    - 
      -# diff -u `which winepath` `which cygpath`
---- /usr/bin/winepath 2011-05-02 16:00:40.000000000 +0200
-+++ /usr/bin/cygpath 2011-06-22 20:57:27.199351255 +0200
-@@ -20,7 +20,7 @@
-#
-
-# determine the app Winelib library name
--appname=`basename "$0" .exe`.exe
-+appname=winepath.exe
-
-# first try explicit WINELOADER
-if [ -x "$WINELOADER" ]; then exec "$WINELOADER" "$appname" "$@"; fi
-
    -

    - "Better solution would be replacing all cygpath references in Makefiles with $(CONVPATH) (or ${CONVPATH} in shell scripts) and setting CONVPATH to cygpath or winepath regarding to currently used environment. -

    -
    -
    - Other Environments? -

    		-

    - Environment Dependencies. - The primary environmental dependency of NuttX are (1) GNU make, - (2) bash scripting, and (3) Linux utilities (such as cat, sed, etc.). - If you have other platforms that support GNU make or make - utilities that are compatible with GNU make, then it is very - likely that NuttX would work in that environment as well (with some - porting effort). If GNU make is not supported, then some significant - modification of the Make system would be required. -

    -

    - MSYS. - I have not used MSYS but what I gather from talking with NuttX users is that MSYS can be used as an alternative to Cygwin in any of the above Cygwin environments. - This is not surprising since MSYS is based on an older version of Cygwin (cygwin-1.3). - MSYS has been modified, however, to interoperate in the Windows environment better than Cygwin and that may be of value to some users. -

    -

    - MSYS, however, cannot be used with the native Windows NuttX build because it will invoke the MSYS bash shell instead of the CMD.exe shell. - Use GNUWin32 in the native Windows build environment. -

    -
    - - - - - -
    -

    Licensing

     -
    - -
      -

      - NuttX is available under the highly permissive - BSD license. - Other than some fine print that you agree to respect the copyright - you should feel absolutely free to use NuttX in any environment and - without any concern for jeopardizing any proprietary software that - you may link with it. -

      -
    - - - - - -
    -

    Bugs, Issues, Things-To-Do

     -
    - -
      -

      - The current list of NuttX Things-To-Do in GIT here. -

      -
    - - - - -
    -

    Other Documentation

     -
    - - - -
    - 1 - This configuration variable document is auto-generated using the kconfig2html tool - That tool analyzes the NuttX Kconfig files and generates the HTML document. - As a consequence, this file may not be present at any given time but can be regenerated following the instructions in tools directory README file. -
     - - - - - - -
    -

    Trademarks

     -
    - -
      -
    • NuttX is a registered trademark of Gregory Nutt.
      • -
    • ARM, ARM7 ARM7TDMI, ARM9, ARM920T, ARM926EJS, Cortex-M3 are trademarks of Advanced RISC Machines, Limited.
      • -
    • Beaglebone is a trademark of GHI.
      • -
    • BSD is a trademark of the University of California, Berkeley, USA.
      • -
    • Cygwin is a trademark of Red Hat, Incorporated.
      • -
    • Linux is a registered trademark of Linus Torvalds.
      • -
    • Eagle-100 is a trademark of Micromint USA, LLC. -
    • EnergyLite is a trademark of STMicroelectronics.
      • -
    • EFM32 is a trademark of Silicon Laboratories, Inc.
      • -
    • LPC2148 is a trademark of NXP Semiconductors.
      • -
    • POSIX is a trademark of the Institute of Electrical and Electronic Engineers, Inc.
      • -
    • RISC-V is a registration pending trade mark of the RISC-V Foundation.
      • -
    • Sitara is a trademark of Texas Instruments Incorporated.
      • -
    • TI is a tradename of Texas Instruments Incorporated.
      • -
    • Tiva is a trademark of Texas Instruments Incorporated.
      • -
    • UNIX is a registered trademark of The Open Group.
      • -
    • VxWorks is a registered trademark of Wind River Systems, Incorporated.
      • -
    • ZDS, ZNEO, Z16F, Z80, and Zilog are a registered trademark of Zilog, Inc.
      • -
    -

    - NOTE: NuttX is not licensed to use the POSIX trademark. - NuttX uses the POSIX standard as a development guideline only. -

    -     - -
    -
    - - diff --git a/Documentation/NuttXBinfmt.html b/Documentation/NuttXBinfmt.html deleted file mode 100644 index 766b96a6a6..0000000000 --- a/Documentation/NuttXBinfmt.html +++ /dev/null @@ -1,585 +0,0 @@ - - -NuttX Binary Loader - - - -
    - - - - -
    -

    NuttX Binary Loader

    -

    Last Updated: January 26, 2019

    -
    -
    - - - - - -
    -

    Table of Contents

    -
    - - - - - - - -
    -

    1.0 Introduction

    -
    - -

    - Binary Loaders. - The purpose of a binary loader is to load and execute modules in various binary formats that reside in a file system. - Loading refers instantiating the binary module in some fashion, usually copy all or some of the binary module into memory and then linking the module with other components. - In most architectures, it is the base FLASH code that is the primary component that the binary module must link with because that is where the RTOS and primary tasks reside. - Program modules can then be executed after they have been loaded. -

    - -

    - Binary Formats. - The binary loader provides generic support for different binary formats. - It supports a registration interface that allows the number of support binary formats to be loaded at run time. - Each binary format provides a common, interface for use by the binary loader. - When asked to load a binary, the binary loader will query each registered binary format, providing it with the path of the binary object to be loaded. - The binary loader will stop when first binary format the recognizes the binary object and successfully loads it or when all registered binary formats have attempt loading the binary object and failed. -

    - -

    - At present, the following binary formats are support by NuttX: -

    - - -

    - Executables and Libraries - The generic binary loader logic does not care what it is that it being loaded. It could load an executable program or a library. - There are no strict rules, but a library will tend to export symbols and a program will tend to import symbols: The program will use the symbols exported by the library. - However, at this point in time, none of the supported binary formats support exporting of symbols. -

    - -

    - binfmt. - In the NuttX source code, the short name binfmt is used to refer to the NuttX binary loader. - This is the name of the directory containing the binary loader and the name of the header files and variables used by the binary loader. -

    - -

    - The name binfmt is the same name used by the Linux binary loader. - However, the NuttX binary loader is an independent development and shares nothing with the Linux binary loader other the same name and the same basic functionality. -

    - - - - - -
    -

    2.0 Binary Loader Interface

    -
    - -

    2.1 Binary Loader Header Files

    -

    - The interface to the binary loader is described in the header file - - include/nuttx/binfmt/binfmt.h. - A brief summary of the data structurs and interfaces prototyped in that header file are listed below. -

    - -

    2.2 Binary Loader Data Structures

    - -

    - When a binary format registers with the binary loader, it provides a pointer to a write-able instance of the following data structure: -

    - - -

    - The load method is used to load the binary format into memory. - It returns either OK (0) meaning that the binary object was loaded successfully, or a negated errno indicating why the object was not loaded. -

    - -

    - The type struct binary_s is use both to (2) describe the binary object to be loaded, and if successfully loaded, (2) to provide information about where and how the binary object was loaded. - That structure is shown below: -

    - - - - -

    - Where the types binfmt_ctor_t and binfmt_dtor_t define the type of one C++ constructor or destructor: -

    - - - -

    2.3 Binary Loader Function Interfaces

    - -

    - Binary format management: -

    - -

    - Basic module management: -

    - -

    - PATH traversal logic: -

    - - -

    2.3.1 register_binfmt()

    - -

    Function Prototype:

    - -

    Description:

    - -

    Returned Value:

    - - -

    2.3.2 unregister_binfmt()

    -

    Function Prototype:

    - -

    Description:

    - -

    Returned Value:

    - - -

    2.3.3 load_module()

    -

    Function Prototype:

    - -

    Description:

    - -

    Returned Value:

    - - -

    2.3.4 unload_module()

    -

    Function Prototype:

    - -

    Description:

    - -

    Returned Value:

    - - -

    2.3.5 exec_module()

    -

    Function Prototype:

    - -

    Description:

    - -

    Returned Value:

    - - -

    2.3.7 exec()

    -

    Function Prototype:

    - -

    Description:

    - -

    Input Parameters:

    - -

    Returned Value:

    - - -

    2.3.8 envpath_init()

    -

    Function Prototype:

    - -

    Description:

    - -

    Input Parameters: None

    -

    Returned Value:

    - - -

    2.3.9 envpath_next()

    -

    Function Prototype:

    - -

    Description:

    - -

    Input Parameters:

    - -

    Returned Value:

    - - -

    2.3.10- envpath_release()

    -

    Function Prototype:

    - -

    Description:

    - -

    Input Parameters:

    - -

    Returned Value: None

    - - - - - -
    -

    3.0 Symbol Tables

    -
    - -

    - Symbol Tables. - Symbol tables are lists of name value mappings: - The name is a string that identifies a symbol, and the value is an address in memory where the symbol of that name has been positioned. - In most NuttX architectures symbol tables are required, as a minimum, in order to dynamically link the loaded binary object with the base code on FLASH. - Since the binary object was separately built and separately linked, these symbols will appear as undefined symbols in the binary object. - The binary loader will use the symbol table to look up the symbol by its name and to provide the address associated with the symbol as needed to perform the dynamic linking of the binary object to the base FLASH code. -

    - -

    3.1 Symbol Table Header Files

    -

    - The interface to the symbol table logic is described in the header file - - include/nuttx/binfmt/symtab.h. - A brief summary of the data structurs and interfaces prototyped in that header file are listed below. -

    - -

    3.2 Symbol Table Data Structures

    -

    - struct symbtab_s describes one entry in the symbol table. -

    - - - -

    - A symbol table is a fixed size array of struct symtab_s. - The information is intentionally minimal and supports only: -

    -
      -
    1. - Function pointers as sym_values. - Of other kinds of values need to be supported, then typing information would also need to be included in the structure. -
      2. -
    2. - Fixed size arrays. - There is no explicit provisional for dynamically adding or removing entries from the symbol table (realloc might be used for that purpose if needed). - The intention is to support only fixed size arrays completely defined at compilation or link time. -
      3. -
    - -

    3.3 Symbol Table Function Interfaces

    - - - -

    3.3.1 symtab_findbyname()

    -

    Function Prototype:

    - -

    Description:

    - -

    Returned Value:

    - - -

    3.3.2 symtab_findorderedbyname()

    -

    Function Prototype:

    - -

    Description:

    - -

    Returned Value:

    - - -

    3.3.3 symtab_findbyvalue()

    -

    Function Prototype:

    - -

    Description:

    - -

    Returned Value:

    - - - - - - -
    -

    4.0 Configuration Variables

    -
    - - - -

    - Additional configuration options may be required for the each enabled binary format. -

    - - diff --git a/Documentation/NuttXDemandPaging.html b/Documentation/NuttXDemandPaging.html deleted file mode 100644 index aeb210517e..0000000000 --- a/Documentation/NuttXDemandPaging.html +++ /dev/null @@ -1,672 +0,0 @@ - - -On-Demand Paging - - - -
    - - - - -
    -

    On-Demand Paging

    -

    Last Updated: February 4, 2019

    -
    -
    - - - - - -
    -

    Table of Contents

    -
    - -
    - - - - - - - - - - -
    - - - - - - - - - - - - - -
    - Introduction -
      - Overview -
      - Terminology -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - -
    - NuttX Common Logic Design Description -
      - Initialization -
      - Page Faults -
      - Fill Initiation -
      - Fill Complete -
      - Task Resumption -
    -
    - - - - - - - - - - - - - -
    - Architecture-Specific Support Requirements -
      - Memory Organization -
      - Architecture-Specific Functions -
    -
    - - - - - -
    -

    Introduction

     -
    -

    Overview

     - -

    - This document summarizes the design of NuttX on-demand paging. - This feature permits embedded MCUs with some limited RAM space to execute large programs from some non-random access media. -

    -

    - What kind of platforms can support NuttX on-demang paging? -

      -
    1. - The MCU should have some large, probably low-cost non-volatile storage such as serial FLASH or an SD card. - This storage probably does not support non-random access (otherwise, why not just execute the program directly on the storage media). - SD and serial FLASH are inexpensive and do not require very many pins and SPI support is prevalent in just about all MCUs. - This large serial FLASH would contain a big program. Perhaps a program of several megabytes in size. -
      2. -
    2. - The MCU must have a (relatively) small block of fast SRAM from which it can execute code. - A size of, say 256K (or 192K as in the NXP LPC3131) would be sufficient for many applications. -
      3. -
    3. - The MCU has an MMU (again like the NXP LPC3131). -
      4. -
    -

    -

    - If the platform meets these requirement, then NuttX can provide on-demand paging: - It can copy .text from the large program in non-volatile media into RAM as needed to execute a huge program from the small RAM. -

    - -

    Terminology

     - -
    -
    g_waitingforfill
    -
    An OS list that is used to hold the TCBs of tasks that are waiting for a page fill.
    -
    g_pftcb
    -
    A variable that holds a reference to the TCB of the thread that is currently be re-filled.
    -
    g_pgworker
    -
    The process ID of the thread that will perform the page fills.
    -
    pg_callback()
    -
    The callback function that is invoked from a driver when the fill is complete.
    -
    pg_miss()
    -
    The function that is called from architecture-specific code to handle a page fault.
    -
    TCB
    -
    Task Control Block
    -
    - - - - - -
    -

    NuttX Common Logic Design Description

     -
    - - -

    Initialization

     - -

    - The following declarations will be added. -

    -

    -

    - During OS initialization in sched/init/nx_start.c, the following steps - will be performed: -

    -

    -

    - Declarations for g_waitingforfill, g_pgworker, and other - internal, private definitions will be provided in sched/paging/paging.h. - All public definitions that should be used by the architecture-specific code will be available - in include/nuttx/page.h. - Most architecture-specific functions are declared in include/nuttx/arch.h, - but for the case of this paging logic, those architecture specific functions are instead declared in include/nuttx/page.h. -

    - -

    Page Faults

     - -

    - Page fault exception handling. - Page fault handling is performed by the function pg_miss(). - This function is called from architecture-specific memory segmentation - fault handling logic. This function will perform the following - operations: -

      -
    1. - Sanity checking. - This function will ASSERT if the currently executing task is the page fill worker thread. - The page fill worker thread is how the page fault is resolved and all logic associated with the page fill worker - must be "locked" and always present in memory. -
      2. -
    2. - Block the currently executing task. - This function will call up_block_task() to block the task at the head of the ready-to-run list. - This should cause an interrupt level context switch to the next highest priority task. - The blocked task will be marked with state TSTATE_WAIT_PAGEFILL and will be retained in the g_waitingforfill prioritized task list. -
      3. -
    3. - Boost the page fill worker thread priority. - Check the priority of the task at the head of the g_waitingforfill list. - If the priority of that task is higher than the current priority of the page fill worker thread, then boost the priority of the page fill worker thread to that priority. - Thus, the page fill worker thread will always run at the priority of the highest priority task that is waiting for a fill. -
      4. -
    4. - Signal the page fill worker thread. - Is there a page already being filled? - If not then signal the page fill worker thread to start working on the queued page fill requests. -
      5. -
    -

    -

    - When signaled from pg_miss(), the page fill worker thread will be awakenend and will initiate the fill operation. -

    -

    - Input Parameters. - None -- The head of the ready-to-run list is assumed to be that task that caused the exception. - The current task context should already be saved in the TCB of that task. - No additional inputs are required. -

    -

    - Assumptions. -

    -

    - -

    Fill Initiation

     - -

    - The page fill worker thread will be awakened on one of three conditions: -

    -

    - -

    - The page fill worker thread will maintain a static variable called struct tcb_s *g_pftcb. - If no fill is in progress, g_pftcb will be NULL. - Otherwise, it will point to the TCB of the task which is receiving the fill that is in progress. -

    - - -

    - When awakened from pg_miss(), no fill will be in progress and g_pftcb will be NULL. - In this case, the page fill worker thread will call pg_startfill(). - That function will perform the following operations: -

    -

    -

    - In any case, while the fill is in progress, other tasks may execute. - If another page fault occurs during this time, the faulting task will be blocked, its TCB will be added (in priority order) to g_waitingforfill, and the priority of the page worker task may be boosted. - But no action will be taken until the current page fill completes. - NOTE: The IDLE task must also be fully locked in memory. - The IDLE task cannot be blocked. - It the case where all tasks are blocked waiting for a page fill, the IDLE task must still be available to run. -

    - The architecture-specific functions, up_checkmapping(), up_allocpage(tcb, &vpage) and up_fillpage(page, pg_callback) - will be prototyped in include/nuttx/arch.h -

    - -

    Fill Complete

     - -

    - For the blocking up_fillpage(), the result of the fill will be returned directly from the call to up_fillpage. -

    -

    - For the non-blocking up_fillpage(), the architecture-specific driver call the pg_callback() that was provided to up_fillpage() when the fill completes. - In this case, the pg_callback() will probably be called from driver interrupt-level logic. - The driver will provide the result of the fill as an argument to the callback function. - NOTE: pg_callback() must also be locked in memory. -

    -

    - In this non-blocking case, the callback pg_callback() will perform the following operations when it is notified that the fill has completed: -

    -

    - -

    Task Resumption

     - -

    - For the non-blocking up_fillpage(), the page fill worker thread will detect that the page fill is complete when it is awakened with g_pftcb non-NULL and fill completion status from pg_callback. - In the non-blocking case, the page fill worker thread will know that the page fill is complete when up_fillpage() returns. -

    -

    - In this either, the page fill worker thread will: -

    -

    - - - - - -
    -

    Architecture-Specific Support Requirements

     -
    - -

    Memory Organization

     - -

    - Memory Regions. - Chip specific logic will map the virtual and physical address spaces into three general regions: -

      -
    1. - A .text region containing "locked-in-memory" code that is always available and will never cause a page fault. - This locked memory is loaded at boot time and remains resident for all time. - This memory regions must include: -
        -
      • - All logic for all interrupt paths. - All interrupt logic must be locked in memory because the design present here will not support page faults from interrupt handlers. - This includes the page fault handling logic and pg_miss() that is called from the page fault handler. - It also includes the pg_callback() function that wakes up the page fill worker thread - and whatever architecture-specific logic that calls pg_callback(). -
        • -
      • - All logic for the IDLE thread. - The IDLE thread must always be ready to run and cannot be blocked for any reason. -
        • -
      • - All of the page fill worker thread must be locked in memory. - This thread must execute in order to unblock any thread waiting for a fill. - It this thread were to block, there would be no way to complete the fills! -
      -
      2. -
    2. - A .text region containing pages that can be assigned allocated, mapped to various virtual addresses, and filled from some mass storage medium. -
      3. -
    3. - And a fixed RAM space for .bss, .text, and .heap. -
      4. -
    -

    -

    - This memory organization is illustrated in the following table. - Notice that: -

    -

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    SRAMVirtual Address SpaceNon-Volatile Storage
     DATA 
     Virtual Page n (n > m)Stored Page n
     Virtual Page n-1Stored Page n-1
    DATA......
    Physical Page m (m < n)......
    Physical Page m-1......
    .........
    Physical Page 1Virtual Page 1Stored Page 1
    Locked MemoryLocked MemoryMemory Resident
    - -

    - Example. - As an example, suppose that the size of the SRAM is 192K (as in the NXP LPC3131). And suppose further that: -

    -

    - Then, the size of the locked, memory resident code is 32K (m=32 pages). - The size of the physical page region is 96K (96 pages), and the - size of the data region is 64 pages. - And the size of the virtual paged region must then be greater than or equal to (1024-32) or 992 pages (n). -

    - -

    - Building the Locked, In-Memory Image. - One way to accomplish this would be a two phase link: -

    -

    - -

    Architecture-Specific Functions

     - -

    - Most standard, architecture-specific functions are declared in include/nuttx/arch.h. - However, for the case of this paging logic, the architecture specific functions are declared in include/nuttx/page.h. - Standard, architecture-specific functions that should already be provided in the architecture port. - The following are used by the common paging logic: -

    - - -

    - New, additional functions that must be implemented just for on-demand paging support: -

    - - - - diff --git a/Documentation/NuttXNxFlat.html b/Documentation/NuttXNxFlat.html deleted file mode 100644 index 3167f06a0c..0000000000 --- a/Documentation/NuttXNxFlat.html +++ /dev/null @@ -1,765 +0,0 @@ - - -NXFLAT - - - - -
    - - - - -
    -

    NXFLAT

    -

    Last Updated: October 1, 2017

    -
    -
    - - - - -
    -

    Table of Contents

    -
    - -
    - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - 1.0 Overview -

    		- 1.1 Functionality -

    		- 1.2 Background -

    		- 1.3 Limitations -

    		- 1.4 Supported Processors -

    		- 1.5 Development Status -
    - 2.0 NXFLAT Toolchain -

    		- 1.2 Building the NXFLAT Toolchain -

    		- 1.2 mknxflat -

    		- 1.3 ldnxflat -

    		- 1.4 mksymtab -

    		- 1.5 Making an NXFLAT module -
    - 3.0. Binary Loader APIs -
    - Appendix A. No GOT Operation -
    - Appendix B. PIC Text Workaround -
    -
    - - - - - -
    -

    1.0 Overview

     -
    - -

    1.1 Functionality

     - -

    - NXFLAT is a customized and simplified version of binary format implemented a few years ago called - XFLAT - With the NXFLAT binary format you will be able to do the following: -

    - -

    - This allows you to extend the NuttX base code after it has been written into FLASH. - One motivation for implementing NXFLAT is support clean CGI under an HTTPD server. -

    -

    - This feature is especially attractive when combined with the NuttX ROMFS support: - ROMFS allows you to execute programs in place (XIP) in flash without copying anything - other than the .data section to RAM. - In fact, the initial NXFLAT release only worked on ROMFS. - Later extensions also support execution NXFLAT binaries from an SRAM copy as well. -

    -

    - This NuttX feature includes: -

    - - -

    1.2 Background

     - -

    - NXFLAT is derived from XFLAT. - XFLAT is a toolchain add that provides full shared library and XIP executable - support for processors that have no Memory Management Unit (MMU1). - NXFLAT is greatly simplified for the deeply embedded environment targeted by Nuttx: -

    - -

    - Rather, the NXFLAT module only imports symbol values. - In the NXFLAT model, the (PIC2) NXFLAT module resides in a FLASH file system and - when it is loaded at run time, it is dynamically linked only to the (non-PIC) base NuttX - code: - The base NuttX exports a symbol table; the NXFLAT module imports those symbol value - to dynamically bind the module to the base code. -

    - - - -

    1.3 Limitations

     - - - - - -

    1.4 Supported Processors

     - -

    - As mentioned above, the NXFLAT toolchain is only available for ARM and - Cortex-M3 (thumb2) targets. - Furthermore, NXFLAT has only been tested on the Eagle-100 LMS6918 Cortex-M3 board. -

    - -

    1.5 Development Status

     - -

    - The initial release of NXFLAT was made in NuttX version 0.4.9. - Testing is limited to the tests found under apps/examples/nxflat in the source tree. - Some known problems exist - (see the TODO list). - As such, NXFLAT is currently in an early alpha phase. -

    - - - - - -
    -

    2.0 NXFLAT Toolchain

     -
    - -

    1.2 Building the NXFLAT Toolchain

     - -

    - In order to use NXFLAT, you must use special NXFLAT tools to create the binary module in FLASH. - To do this, you will need to download the buildroot package and build it on your Linux or Cygwin machine. - The buildroot can be downloaded from - Bitbucket.org. - You will need version 0.1.7 or later. -

    -

    - Here are some general build instructions: -

    - - -

    1.2 mknxflat

     - -

    - mknxflat is used to build a thunk file. - See below for usage. - -

    - -

    1.3 ldnxflat

     - -

    - ldnxflat is use to link your object files along with the thunk file - generated by mknxflat to produce the NXFLAT binary module. - See below for usage. -

    - - - -

    1.4 mksymtab

     - -

    - There is a small helper program available in nuttx/tools call mksymtab. - mksymtab can be sued to generate symbol tables for the NuttX base code that would be usable by the typical NXFLAT application. - mksymtab builds symbol tables from common-separated value (CSV) files. - In particular, the CSV files: -

    -
      -
    1. - nuttx/syscall/syscall.csv that describes the NuttX RTOS interface, and -
      2. -
    2. - nuttx/libc/libc.csv that describes the NuttX C library interface. -
      3. -
    3. - nuttx/libc/math.cvs that descirbes any math library. -
      4. -
    - -

    - For example, -

    - - -

    1.5 Making an NXFLAT module

     - -

    - Below is a snippet from an NXFLAT make file (simplified from NuttX - - Hello, World! example. -

    -

    - -

    Target 1. - This target links all of the module's object files together into one relocatable object. - Two relocatable objects will be generated; this is the first one (hence, the suffic .r1). - In this "Hello, World!" case, there is only a single object file, hello.o, - that is linked to produce the hello.r1 object. -

    - -

    - When the module's object files are compiled, some special compiler CFLAGS must be provided. - First, the option -fpic is required to tell the compiler to generate position independent code (other - GCC options, like -fno-jump-tables might also be desirable). - For ARM compilers, two additional compilation options are required: -msingle-pic-base - and -mpic-register=r10. -

    - -

    Target 2. - Given the hello.r1 relocatable object, this target will invoke - mknxflat - to make the thunk file, hello-thunk.S. - This thunk file contains all of the information needed to create the imported function list. -

    - -

    Target 3 - This target is similar to Target 1. - In this case, it will link together the module's object files (only hello.o here) - along with the assembled thunk file, hello-thunk.o to create the second relocatable object, - hello.r2. - The linker script, gnu-nxflat-gotoff.ld is required at this point to correctly position the sections. - This linker script produces two segments: - An I-Space (Instruction Space) segment containing mostly .text and a D-Space (Data Space) segment - containing .got, .data, and .bss sections. - The I-Space section must be origined at address 0 (so that the segment's addresses are really offsets into - the I-Space segment) - and the D-Space section must also be origined at address 0 (so that segment's addresses are really offsets into - the I-Space segment). - The option -no-check-sections is required to prevent the linker from failing because these segments overlap. -

    - -

    NOTE: - There are two linker scripts located at binfmt/libnxflat/. -

    -
      -
    1. - binfmt/libnxflat/gnu-nxflat-gotoff.ld. - Older versions of GCC (at least up to GCC 4.3.3), use GOT-relative addressing to access RO data. - In that case, read-only data (.rodata) must reside in D-Space and this linker script should be used. -
      2. -
    2. - binfmt/libnxflat/gnu-nxflat-pcrel.ld. - Newer versions of GCC (at least as of GCC 4.6.3), use PC-relative addressing to access RO data. - In that case, read-only data (.rodata) must reside in I-Space and this linker script should be used. -
      3. -
    - -

    Target 4. - Finally, this target will use the hello.r2 relocatable object to create the final, NXFLAT module - hello by executing ldnxflat. -

    - - - - - -
    -

    3.0 Binary Loader APIs

     -
    - -

    Relevant Header Files:

    - - -

    binfmt Registration - These first interfaces are used only by a binary loader module, such as NXFLAT itself. - NXFLAT (or any future binary loader) calls register_binfmt() to incorporate - itself into the system. - In this way, the binary loader logic is dynamically extensible to support any kind of loader. - Normal application code should not be concerned with these interfaces. -

    - - - -

    Binary Loader Interfaces. - The remaining APIs are called by user applications to maintain modules in the file system. -

    - - - - - - - -
    -

    Appendix A. No GOT Operation

     -
    - -

    - When GCC generate position independent code, new code sections will appear in your programs. - One of these is the GOT (Global Offset Table) and, in ELF environments, another is the PLT (Procedure - Lookup Table. - For example, if your C code generated (ARM) assembly language like this without PIC: -

    -

    - -

    - Then when PIC is enabled (say with the -fpic compiler option), it will generate code like - this: -

    - - - -

    See reference

    - -

    - Notice that the generates an extra level of indirection through the GOT. - This indirection is not needed by NXFLAT and only adds more RAM usage and - execution time. -

    -

    - NXFLAT (like XFLAT) can work even better without - the GOT. - Patches against older version of GCC exist to eliminate the GOT indirections. - Several are available here - if you are inspired to port them to a new GCC version. -

    - - - - - - -
    -

    Appendix B. PIC Text Workaround

     -
    - -

    - There is a problem with the memory model in GCC that prevents it from - being used as you need to use it in the NXFLAT context. - The problem is that GCC PIC model assumes that the executable lies in a flat, contiguous (virtual) address space like: -

    -

    -

    - It assumes that the PIC base register (usually r10 for ARM) points to the base of .text - so that any address in .text, .got, .data, .bss - can be found with an offset from the same base address. - But that is not the memory arrangement that we need in the XIP embedded environment. - We need two memory regions, one in FLASH containing shared code and on per task in RAM containing task-specific data: -

    - - - -

    - The PIC base register needs to point to the base of the .got and only - addresses in the .got, .data, and .bss - sections can be accessed as an offset from the PIC base register. - See also this - XFLAT discussion. -

    -

    - Patches against older version of GCC exist to correct this GCC behavior. - Several are available here - if you are inspired to port them to a new GCC version. -

    - - - diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html deleted file mode 100644 index 60f8dc825b..0000000000 --- a/Documentation/NuttxPortingGuide.html +++ /dev/null @@ -1,7273 +0,0 @@ - - -NuttX Porting Guide - - - - - - -
    -
    - - - - -
    -

    Table of Contents

    -
    - - -
    - -
    - -
    - - - - -
    -

    - NuttX RTOS Porting Guide -

    -

    Last Updated: April 7, 2020

    -
    -
    - - - - - -
    -

    1.0 Introduction

    -
    - -

    Overview - This document provides and overview of the NuttX build and configuration - logic and provides hints for the incorporation of new processor/board architectures - into the build. -

    -

    - See also arch/README.txt and boards/README.txt. -

    - - - - - -
    -

    2.0 Directory Structure

    -
    - -

    - Directory Structure. - The general directory layout for NuttX is very similar to the directory structure - of the Linux kernel -- at least at the most superficial layers. - At the top level is the main makefile and a series of sub-directories identified - below and discussed in the following paragraphs: -

    -
      -.
-|- nuttx
-|   |-- Makefile
-|   |-- Kconfig
-|   |-- Documentation
-|   |   `-- (documentation files)/
-|   |-- arch/
-|   |   |-- Kconfig
-|   |   |-- <arch-name>/
-|   |   |   |-- include/
-|   |   |   |   |--<chip-name>/
-|   |   |   |   |  `-- (chip-specific header files)
-|   |   |   |   |--<other-chips>/
-|   |   |   |   `-- (architecture-specific header files)
-|   |   |   `-- src/
-|   |   |       |--<chip-name>/
-|   |   |       |  `-- (chip-specific source files)
-|   |   |       |--<other-chips>/
-|   |   |       `-- (architecture-specific source files)
-|   |   `-- <other-architecture directories>/
-|   |-- audio/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   `-- (common audio source files)
-|   |-- binfmt/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   |-- (binfmt-specific sub-directories)/
-|   |   |   `-- (binfmt-specific source files)
-|   |   `-- (common binfmt source files)
-|   |-- boards/
-|   |   |-- <architecture-name>/
-|   |   |   |-- <chip-name>/
-|   |   |   |   |-- <board-name>/
-|   |   |   |   |   |-- include/
-|   |   |   |   |   |   `-- (other board-specific header files)
-|   |   |   |   |   |-- src/
-|   |   |   |   |   |   `-- (board-specific source files)
-|   |   |   |   |   `- configs/
-|   |   |   |   |         |---<config-name>/
-|   |   |   |   |         |   `-- (board configuration-specific source files)
-|   |   |   |   |         `---(other configuration sub-directories for this board)/
-|   |   |   |   `-- <(other board directories)>/
-|   |   |   `-- <(other chip directories)>/
-|   |   `-- <(other architecture directories)>/
-|   |-- crypto
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   `-- (common crypto source files)
-|   |-- drivers/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   |-- (driver-specific sub-directories)/
-|   |   |   `-- (driver-specific source files)
-|   |   `-- (common driver source files)
-|   |-- fs/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   |-- (file system-specific sub-directories)/
-|   |   |   `-- (file system-specific source files)
-|   |   `-- (common file system source files)
-|   |-- graphics/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   |-- (feature-specific sub-directories)/
-|   |   |   `-- (feature-specific source files library source files)
-|   |   `-- (common graphics-related source files)
-|   |-- include/
-|   |   |-- (standard header files)
-|   |   |-- (standard include sub-directories)
-|   |   |   `-- (more standard header files)
-|   |   |-- (non-standard include sub-directories)
-|   |       `-- (non-standard header files)
-|   |-- libs/
-|   |   |-- libc/
-|   |   |   |-- Makefile
-|   |   |   |-- Kconfig
-|   |   |   `-- (libc source files)
-|   |   |-- libdsp/
-|   |   |   |-- Makefile
-|   |   |   |-- Kconfig
-|   |   |   `-- (libdsp source files)
-|   |   |-- libnx/
-|   |   |   |-- Makefile
-|   |   |   |-- Kconfig
-|   |   |   `-- (libdsp source files)
-|   |   `-- libxx/
-|   |       |-- Makefile
-|   |       |-- Kconfig
-|   |       `-- (libxx source files)
-|   |-- mm/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   `-- (memory management source files)
-|   |-- net/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   |-- arp/
-|   |   |   `-- (ARP source files)
-|   |   |-- devif/
-|   |   |   `-- (Ethernet device interface source files)
-|   |   |-- icmp/
-|   |   |   `-- (ICMP source files)
-|   |   |-- igmp/
-|   |   |   `-- (IGMP source files)
-|   |   |-- iob/
-|   |   |   `-- (I/O buffering source files)
-|   |   |-- ipv6/
-|   |   |   `-- (IPv6 source files)
-|   |   |-- netdev/
-|   |   |   `-- (Socket device interface source files)
-|   |   |-- pkt/
-|   |   |   `-- (Packet socket source files)
-|   |   |-- route/
-|   |   |   `-- (Routing table source files)
-|   |   |-- socket/
-|   |   |   `-- (BSD socket source files)
-|   |   |-- tcp/
-|   |   |   `-- (TCP source files)
-|   |   |-- udp/
-|   |   |   `-- (UDP source files)
-|   |   `-- utils/
-|   |       `-- (Miscellaneous, utility source files)
-|   |-- pass1/
-|   |   `-- Makefile
-|   |-- sched/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   `-- (sched source files)
-|   |-- syscall/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   `-- (syscall source files)
-|   |-- tools/
-|   |   `-- (miscellaneous scripts and programs)
-|   `-- wireless/
-|       |-- Makefile
-|       |-- Kconfig
-|       `-- (wireless source files)
-`- apps
-    |-- builtin/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   `-- (builtin source files)
-    |-- canutils/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   `-- (can utililities sub-directories)
-    |-- fsutils/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   `-- (File system utilities sub-directories)
-    |-- gpsutils/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   `-- (GPS utilities sub-directories)
-    |-- include/
-    |   `-- (Include sub-directories)
-    |-- interpreters/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   `-- (Interpreter sub-directories)
-    |-- modbus/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   `-- (Modbus source files)
-    |-- netutils/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   |-- (network feature sub-directories)/
-    |   |   `-- (network utilities sub-directories)
-    |   `-- (netutils common files)
-    |-- nshlib/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   `-- NuttShell (NSH) files
-    |-- platform/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   `-- (Platform-specific sub-directories)
-    |-- system/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   `-- (System utilities sub-directories)
-    |-- testing/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   `-- (Test support sub-directories)
-    |-- wireless/
-    |   |-- Makefile
-    |   |-- Make.defs
-    |   |-- Kconfig
-    |   `-- (Wireless utilities sub-directories)
-    `-- examples/
-        `-- (example)/
-            |-- Makefile
-            |-- Make.defs
-            |-- Kconfig
-            `-- (example sub-directories)
-
    - -

    - Configuration Files. - The NuttX configuration consists of logic in processor architecture directories, chip/SoC directories, and 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 are discussed in a paragraph below. - As an example, all ARM processor architectures are provided under the arch/arm/ directory which is selected with the CONFIG_ARCH="arm" configuration option. -

      -

      - Variants of the processor architecture may be provided in sub-directories of the - Extending this example, the ARMv7-M ARM family is supported by logic in arch/arm/include/armv7-m and arch/arm/src/armv7-m directories which are selected by the CONFIG_ARCH_CORTEXM3=y, CONFIG_ARCH_CORTEXM4=y, or CONFIG_ARCH_CORTEXM7=y configuration options -

      -
      • -
    • -

      - Chip/SoC specific files. - Each processor architecture is embedded in a System-on-a-Chip (SoC) architecture. - The full SoC architecture includes the processor architecture plus chip-specific interrupt logic, clocking logic, general purpose I/O (GPIO) logic, and specialized, internal peripherals (such as UARTs, USB, etc.). -

      -

      - These chip-specific files are contained within chip-specific sub-directories also under the - arch/<arch-name>/ directory and are selected via - the CONFIG_ARCH_CHIP selection. -

      -

      - As an example, the STMicro STM32 SoC architecture is based on the ARMv7-M processor and is supported by logic in the arch/arm/include/stm32 and arch/arm/src/stm32 directories which are selected with the CONFIG_ARCH_CHIP="stm32" configuration setting. -

      -
      • -
    • -

      - Board specific configurations. - 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 networks, USB, etc.). -

      -

      - These board-specific configuration files can be found in the - boards/<arch-name>/<chip-name>/<board-name>/ sub-directories and are discussed - in a paragraph below. -

      -

      - The directory boards/arm/stm32/stm32f4disovery/, as an example, holds board-specific logic for the STM32F4 Discovery board and is selected via the CONFIG_ARCH_BOARD="stm32f4discovery" configuration setting. -

      -
      • -
    - -

    2.1 Documentation

    - -

    - General documentation for the NuttX OS resides in this directory. -

    - -

    2.2 nuttx/arch

    - -

    2.2.1 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-name>/
-|-- include/
-|   |--<chip-name>/
-|   |  `-- (chip-specific header files)
-|   |--<other-chips>/
-|   |-- arch.h
-|   |-- irq.h
-|   |-- types.h
-|   |-- limits.h
-|   `-- syscall.h
-`-- src/
-    |--<chip-name>/
-    |  `-- (chip-specific source files)
-    |--<other-chips>/
-    |-- Makefile
-    `-- (architecture-specific source files)
-
    - -

    2.2.2 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: -
        - _int8_t, _uint8_t, _int16_t, _uint16_t, _int32_t, _uint32_t_t -
      -

      and if the architecture supports 24- or 64-bit integers

      -
        - _int24_t, _uint24_t, int64_t, uint64_t -
      -

      - 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 -

      -
        - irqstate_t -
      -

      - 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 syscalls 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_KERNELconfigurations. -
        -
      • - 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). -
      • -
    - -

    2.2.3 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. -
      • -

      NOTE: In principle, this user mode port should run in any POSIX environment. - This target will probably not run "out-of-the-box" in unverified POSIX environments due to the many host environment dependencies. -

      - -
    • 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/risc-v: - This directory supports the RISC-V NR5 architecture. -
      • - -
    • 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. -
      • -
    - -

    2.3 nuttx/binfmt

    - -

    - The binfmt/ subdirectory contains logic for loading binaries in the file - system into memory in a form that can be used to execute them. -

    - -

    2.4 nuttx/audio

    - -

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

    - -

    2.5 nuttx/boards

    -

    - The boards/ subdirectory contains custom logic and board 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.5.1 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: -

    -
      -<board-name>
-|-- Kconfig
-|-- include/
-|   |-- board.h
-|   `-- (board-specific header files)
-|-- src/
-|   |-- Makefile
-|   `-- (board-specific source files)
-|-- configs/
-|   |-- <config1-dir>
-|   |   |-- Make.defs (optional)
-|   |   `-- defconfig
-|   |-- <config2-dir>
-|   |   |-- Make.defs
-|   |   `-- defconfig
-|   ...
-|-- scripts/
-|   |-- (linker script files)
-|   `-- Make.defs (optional)
-`-- (other board-specific configuration sub-directories)/
-
    - -

    2.5.2 Summary of Files

    -

    2.5.2.1 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. -
      • -
    -

    2.5.2.2 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, - 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: -

      -
        -
      1. As a makefile fragment included in other makefiles, and
        2. -
      2. to generate include/nuttx/config.h which is included by - most C files in the system.
        3. -
      -
      • -
    - -

    2.5.3 Supported Boards

    -

    - All of the specific boards supported by NuttX are identified in the README.txt file. -

    -

    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? -

    -

    - 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: -

    -

      -config ARCH_BOARD_STM32F4_DISCOVERY
-    bool "STMicro STM32F4-Discovery board"
-    depends on ARCH_CHIP_STM32F407VG
-    select ARCH_HAVE_LEDS
-    select ARCH_HAVE_BUTTONS
-    select ARCH_HAVE_IRQBUTTONS
-    ---help---
-        STMicro STM32F4-Discovery board based on the STMicro STM32F407VGT6 MCU.
-
    -

    - 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: -

    -
      -config ARCH_BOARD_MYBOARD
-    bool "My very own board configuration"
-    depends on ARCH_CHIP_MYMCU
-    select ARCH_HAVE_LEDS
-    select ARCH_HAVE_BUTTONS
-    select ARCH_HAVE_IRQBUTTONS
-    ---help---
-        This options selects the board configuration for my very own board
-        based on the MYMCU processor.
-
    -

    - Later in the boards/Kconfig file, you will see a long, long string configuration with lots of defaults like this: -

    -
      -config ARCH_BOARD
-    string
-    default "amber"               if ARCH_BOARD_AMBER
-    default "avr32dev1"           if ARCH_BOARD_AVR32DEV1
-    default "c5471evm"            if ARCH_BOARD_C5471EVM
-...
-    default "stm32f4discovery"    if ARCH_BOARD_STM32F4_DISCOVERY
-...
-
    -

    - 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): -

    -
      -    default "myboard"             if ARCH_BOARD_MYBOARD
-
    -

    - 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: -

    -
      -if ARCH_BOARD_MYBOARD
-source "boards/myarch/mychip/myboard/Kconfig"
-endif
-
    -

    - This includes additional, board-specific configuration variable definitions in boards/myarch/mychip/myboard/Kconfig. -

    - -

    2.6 nuttx/crypto

    - -

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

    - -

    2.7 nuttx/drivers

    - -

    - This directory holds architecture-independent device drivers. -

    -
      -drivers/
-|-- Kconfig
-|-- Makefile
-|-- 1wire/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (1-wire device source files)
-|-- analog/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (ADC and DAC driver source files)
-|-- audio/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Audio device source files)
-|-- bch/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (BCH driver source files)
-|-- can/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (CAN driver source files)
-|-- contactless/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Contactless device driver source files)
-|-- eeprom/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (EEPROM character driver source files)
-|-- i2c/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (I2C device driver source files)
-|-- input/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Touchscreen and keypad driver source files)
-|-- ioexpander/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (I/O expander and GPIO-related driver source files)
-|-- lcd/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (LCD driver source files)
-|-- leds/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (LED device driver source files)
-|-- loop/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Loop device driver source files)
-|-- mmcsd/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (MMC/SD card driver source files)
-|-- modem/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Modem driver source files)
-|-- mtd/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Memory technology device driver source files)
-|-- net/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Network driver source files)
-|-- pipes/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Pipe and FIFO driver source files)
-|-- power/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Power-related driver source files)
-|-- sensors/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Sensor driver source files)
-|-- serial/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Front-end character drivers for chip-specific UARTs, 16550 UART support, and Pseudo-Terminal support)
-|-- spi/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (SPI-related drivers and helper functions)
-|-- syslog/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (System logging device support)
-|-- timers/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Timer-based device driver support)
-|-- usbdev/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (USB device driver source files)
-|-- usbhost/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (USB host driver source files)
-|-- usbmisc/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Miscellaneous USB driver source files)
-|-- usbmonitor/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (USB monitor source files)
-|-- video/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Video driver source files)
-|-- wireless/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Wireless driver source files)
-`-- (Various uncategorized driver source files)
-
    - -

    2.8 nuttx/fs

    - -

    - This directory contains the NuttX file system. - This file system is described below. -

    -
      -fs/
-|-- Kconfig
-|-- Makefile
-|-- binfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (BINFS file system source files)
-|-- cromfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (CROMFS file system source files)
-|-- dirent/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (VFS directory access source files)
-|-- driver/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Driver registration OS internal interfaces)
-|-- fat/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (FAT file system source files)
-|-- inode/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Pseudo-file system OS internal interfaces)
-|-- hostfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (HOSTFS file system source files)
-|-- mmap/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (RAM-based file mapping source files)
-|-- mount/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Mount point-related OS internal interfaces)
-|-- mqueue/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (POSIX message queue OS internal interfaces)
-|-- nfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (NFS client file system source files)
-|-- nxffs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (NuttX Flash File System (NXFFS) source files)
-|-- procfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (PROCFS pseudo-file system source files)
-|-- romfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (ROMFS file system source files)
-|-- smartfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (SmartFS file system source files)
-|-- unionfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (UnionFS file system source files)
-|-- userfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (UserFS file system source files)
-|-- vfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (VFS OS internal interfaces)
- `-- (common file system source files)
-
    - -

    2.9 nuttx/graphics

    - -

    - This directory contains files for graphics/video support under NuttX. -

    -
      -graphics/
-|-- Kconfig
-|-- Makefile
-|-- nxbe/
-|   |-- Make.defs
-|   `-- (NuttX graphics back-end (NXBE) source files)
-|-- nxglib/
-|   |-- Make.defs
-|   `-- (NuttX graphics library (NXGL) source files)
-|-- nxmu/
-|   |-- Make.defs
-|   `-- (NuttX graphics multi-user (NXMU) server source files)
-|-- nxterm/
-|   |-- Make.defs
-|   `-- (NX terminal (NxTerm) source files)
-|-- vnc/
-|   |-- Make.defs
-|   `-- (VNC client/server source files)
-`-- (common file system source files)
-
    - -

    2.10 nuttx/include

    -

    - This directory holds NuttX header files. - Standard header files file retained in can be included in the normal fashion: -

    -
      - include <stdio.h>
      - include <sys/types.h>
      - etc. -
    -

    - Directory structure: -

    -
      -include/
-|-- (standard header files)
-|-- arpa/
-|   `-- (Standard header files)
-|-- cxx/
-|   `-- (C++ standard header files)
-|-- netinet/
-|   `-- (Standard header files)
-|-- netpacket/
-|   `-- (Protocol-specific header files.  Most non-standard)
-|-- nuttx/
-|   |-1wire/
-|   |  `-- (1-wire driver header files)
-|   |-analog/
-|   |  `-- (Analog driver header files)
-|   |-audio/
-|   |  `-- (Audio driver header files)
-|   |-binfmt/
-|   |  `-- (Binary format header files)
-|   |-contactless/
-|   |  `-- (Contactless driver header files)
-|   |-crypto/
-|   |  `-- (Cryptographic support header files)
-|   |-drivers/
-|   |  `-- (Miscellaneous driver header files)
-|   |-eeprom/
-|   |  `-- (EEPROM driver header files)
-|   |-fs/
-|   |  `-- (File System header files)
-|   |-i2c/
-|   |  `-- (I2C-related header files)
-|   |-input/
-|   |  `-- (Input device driver header files)
-|   |-ioexpander/
-|   |  `-- (I/O expander and GPIO driver header files)
-|   |-lcd/
-|   |  `-- (LCD driver header files)
-|   |-leds/
-|   |  `-- (LED driver header files)
-|   |-lib/
-|   |  `-- (Non-standard C library driver header files)
-|   |-mm/
-|   |  `-- (Memory management header files)
-|   |-modem/
-|   |  `-- (Modem driver header files)
-|   |-mtd/
-|   |  `-- (Memory technology device header files)
-|   |-net/
-|   |  `-- (Networking header files)
-|   |-nx/
-|   |  `-- (NX graphics header files)
-|   |-power/
-|   |  `-- (Power management header files)
-|   |-sensors/
-|   |  `-- (Sensor device driver header files)
-|   |-serial/
-|   |  `-- (Serial driver header files)
-|   |-spi/
-|   |  `-- (SPI-related header files)
-|   |-syslog/
-|   |  `-- (SYSLOG header files)
-|   |-timers/
-|   |  `-- (Timer-related driver header files)
-|   |-usb/
-|   |  `-- (USB driver header files)
-|   |-video/
-|   |  `-- (Video-related driver header files)
-|   `-wireless/
-|      `-- (Wireless device driver header files)
-`- sys/
-    `-- (More standard header files)
-
    - -

    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 phase. - 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/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) are needed to support the two differing protection domains. -

    -

    - Directory structure: -

    -
      -libc/
-|-- aio/
-|   `-- (Implementation of functions from aio.h)
-|-- audio/
-|   `-- (Implementation of audio-related functions)
-|-- dirent/
-|   `-- (Implementation of functions from dirent.h)
-|-- dllfch/
-|   `-- (Implementation of functions from dlfcn.h)
-|-- fixedmath/
-|   `-- (Implementation of functions from fixedmath.h)
-|-- hex2bin/
-|   `-- (Implementation of functions from hex2bin.h)
-|-- inttypes/
-|   `-- (Implementation of functions from inttypes.h)
-|-- libgen/
-|   `-- (Implementation of functions from libgen.h)
-|-- locale/
-|   `-- (Implementation of functions from locale.h)
-|-- lzf/
-|   `-- (Implementation of functions from lzf.h)
-|-- machine/
-|   `-- (Implementations of platform-specific logic)
-|-- math/
-|   `-- (Implementation of functions from fixedmath.h)
-|-- misc/
-|   `-- (Implementation of miscellaneous library functions)
-|-- modlib/
-|   `-- (Implementation of functions from nuttx/lib/modlib.h)
-|-- net/
-|   `-- (Implementation of network-related library functions)
-|-- netdb/
-|   `-- (Implementation of functions from netdb.h)
-|-- pthread/
-|   `-- (Implementation of functions from pthread.h)
-|-- queue/
-|   `-- (Implementation of functions from queue.h)
-|-- sched/
-|   `-- (Implementation of some functions from sched.h)
-|-- semaphore/
-|   `-- (Implementation of some functions from semaphore.h)
-|-- signal/
-|   `-- (Implementation of some functions from signal.h)
-|-- spawn/
-|   `-- (Implementation of some functions from spawn.h)
-|-- stdio/
-|   `-- (Implementation of functions from stdio.h)
-|-- stdlib/
-|   `-- (Implementation of functions from stdlib.h)
-|-- string/
-|   `-- (Implementation of functions from string.h)
-|-- symtab/
-|   `-- (Implementation of symbol-table library functions)
-|-- syslog/
-|   `-- (Implementation of functions from syslog.h)
-|-- termios/
-|   `-- (Implementation of functions from termios.h)
-|-- time/
-|   `-- (Implementation of some functions from time.h)
-|-- tls/
-|   `-- (Implementation of some functions from tls.h)
-|-- uio/
-|   `-- (Implementation of some functions from uio.h)
-|-- unistd/
-|   `-- (Implementation of some functions from unistd.h)
-|-- userfs/
-|   `-- (Implementation of application side internals of UserFS)
-|-- wchar/
-|   `-- (Implementation of some functions from wchar.h.  Not fully functional.)
-|-- wctype/
-|   `-- (Implementation of some functions from wctype.h.  Not fully functional.)
-|-- wqueue/
-|   `-- (Implementation of some functions from wqueue.h)
-`-- zoneinfo/
-    `-- (Implementation of timezone database)
-
-
    - -

    2.13 nuttx/libs/libxx

    -

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

    - -

    2.14 nuttx/mm

    -

    - This is the NuttX memory manager. -

    - -

    2.15 nuttx/net

    -

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

    - -

    2.16 nuttx/sched

    -

    - The files forming core of the NuttX RTOS reside here. -

    - -

    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. - This directory holds a syscall interface that can be used for communication - between user-mode applications and the kernel-mode RTOS. -

    - -

    2.18 nuttx/tools

    -

    - This directory holds a collection of tools and scripts to simplify - configuring, building and maintaining NuttX. -

    -
      -tools/
-|-- Makefile.host
-|-- Makefile.export
-|-- Makefile.unix, Makefile.win, FlatLibs.mk, KernelLibs.mk, LibTargets.mk, ProtectedLibs.mk
-|-- README.txt
-|-- b16.c
-|-- bdf-converter.c
-|-- cfgparser.c
-|-- cfgparser.h
-|-- cmpconfig.c
-|-- cnvwindeps.c
-|-- configure.sh / configure.bat / configure.c
-|-- copydir.sh / copydir.bat
-|-- define.sh / define.bat
-|-- discovery.py
-|-- incdir.sh / incdir.bat
-|-- indent.sh
-|-- initialconfig.c
-|-- kconfig2html.c / mkconfigvars.sh
-|-- link.sh / link.bat
-|-- mkconfig.c
-|-- mkctags.sh
-|-- mkdeps.c
-|-- mkexport.sh
-|-- mkfsdata.pl
-|-- mknulldeps.sh
-|-- mkromfsimg.sh
-|-- mksymtab.c
-|-- mksyscall.c
-|-- mkversion.c
-|-- mkwindeps.sh
-|-- noteinfo.c
-|-- nxstyle.c
-|-- pic32mx/mkpichex.c
-|-- refresh.sh
-|-- sethost.sh
-|-- showsize.sh
-|-- testbuild.sh
-|-- uncrustify.cfg
-|-- unlink.sh / unlink.bat
-|-- version.sh
-|-- xmlrpc_test.py
-`-- zipme.sh
-
    - -

    - Refer to the README file in the tools directory for more information about the individual files. - Some of these tools are discussed below as well in the discussion of configuring and building NuttX. -

    - -

    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. -

    - - - - - -
    -

    3.0 Configuring and Building

    -
    - -

    3.1 Configuring NuttX

    -

    - Manual Configuration. - Configuring NuttX requires only copying the - board-specific configuration files into the top level directory which appears in the make files as the make variable, $(TOPDIR). - This could be done manually as follows: -

    -
      -
    • Copy boards/<arch-name>/<chip-name>/<board-name>/configs/[<config-dir>/]Make.defs to $(TOPDIR)/Make.defs (see NOTE below),
      • -
    • Copy boards/<arch-name>/<chip-name>/<board-name>/configs/[<config-dir>/]defconfig to $(TOPDIR)/.config
      • -
    - -

    - Where <board-name> is the name of one of the sub-directories of the - NuttX boards/ directory. - This sub-directory name corresponds to one of the supported boards - identified above. - <config-dir> is the optional, specific configuration directory for the board. - And <app-dir> is the location of the optional application directory. -

    -

    - NOTE: Recall that the Make.defs file may reside in either the boards/<arch-name>/<chip-name>/<board-name>/configs/[<config-dir> directory or in the boards/<arch-name>/<chip-name>/<board-name>/scripts. -

    -

    - Automated Configuration. - There is a script that automates these steps. The following steps will - accomplish the same configuration: -

    -
      -  tools/configure.sh [OPTIONS] <board-name>[:<config-dir>]
-
    - -

    - There is an alternative Windows batch file, configure.bat, that can be used instead of configure.sh in the windows native environment like: -

    -
      -  tools\configure.bat <board-name>:<config-dir>
-
    -

    - And, to make sure that other platforms are supported, there is also a C program at tools/configure.c that can be compiled to establish the board configuration on all platforms. -

    -

    - NOTE (2019-08-6): As of this writing, changes to the boards/ directly have made configure.bat unusable. - For the native Windows environment, configure.c is recommended until that batch file can be repaired. -

    -

    - See tools/README.txt for more information about these scripts. - Or use the -h option with configure.sh> -

    -
      -$ tools/configure.sh -h
-
-USAGE: tools/configure.sh [-d] [-l|m|c|u|g|n] [-a <app-dir>] <board-name>[:<config-name>]
-
-Where:
-  -l selects the Linux (l) host environment.
-  -m selects the macOS (m) host environment.
-  -c selects the Windows host and Cygwin (c) environment.
-  -u selects the Windows host and Ubuntu under Windows 10 (u) environment.
-  -g selects the Windows host and MinGW/MSYS environment.
-  -n selects the Windows host and Windows native (n) environment.
-  Default: Use host setup in the defconfig file
-  Default Windows: Cygwin
-  <board-name> is the name of the board in the boards/ directory
-  <config-name> is the name of the board configuration sub-directory
-  <app-dir> is the path to the apps/ directory, relative to the nuttx
-     directory
-
    - -

    - 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: -

    -
      -  tools/configure.sh -a <app-dir> <board-name>[:<config-dir>]
-
    - -

    - Version Files. - The NuttX build expects to find a version file located in the top-level NuttX build directory. - That version file is called .version. - The correct version file is installed in each versioned NuttX released. - However, if you are working from an GIT snapshot, then there will be no version file. - If there is no version file, the top-level Makefile will create a dummy .version file on the first make. - This dummy version file will contain all zeroes for version information. - If that is not what you want, they you should run the version.sh script to create a better .version file. -

    - -

    - You can get help information from the version.sh script using the -h option. - For example: -

    -
      -$ tools/version.sh -h
-tools/version.sh is a tool for generation of proper version files for the NuttX build
-
-USAGE: tools/version.sh [-d|-h] [-b <build>] -v <major.minor> <outfile-path>
-
-Where:
-        -b 
-                Use this build identification string.  Default: use GIT build ID
-                NOTE: GIT build information may not be available in a snapshot
-        -d
-                Enable script debug
-        -h
-                show this help message and exit
-        -v 
-        -v <major.minor>
-                The NuttX version number expressed as a major and minor number separated
-                by a period
-        <outfile-path>
-                The full path to the version file to be created
-
    - -

    - As an example, the following command will generate a version file for version 6.1 using the current GIT revision number: -

    -
      -tools/version.h -v 6.1 .version
-
    - -

    - The .version file is also used during the build process to create a C header file at include/nuttx/version.h that contains the same version information. - That version file may be used by your C applications for, as an example, reporting version information. -

    - -

    - Additional Configuration Steps. - The remainder of configuration steps will be performed by $(TOPDIR)/Makefile - the first time the system is built as described below. -

    - -

    3.2 Building NuttX

    -

    - Building NuttX. - Once NuttX has been configured as described above, it may be built as follows: -

    -
      -cd $(TOPDIR)
-make
-
    -

    - The $(TOPDIR) directory holds: -

    -
      -
    • The top level Makefile that controls the NuttX build. -
    -

    - That directory also holds: -

    -
      -
    • The makefile fragment .config that describes the current configuration, and
      • -
    • The makefile fragment Make.defs that provides customized build targets.
      • -
    -

    -Environment Variables. -The specific environmental definitions are unique for each board but should include, as a minimum, updates to the PATH variable to include the full path to the architecture-specific toolchain identified in Make.defs. -

    -

    - First Time Make. - Additional configuration actions will be taken the first time that system is built. - These additional steps include: -

    -
      -
    • Auto-generating the file include/nuttx/config.h using the $(TOPDIR)/.config file.
      • -
    • Auto-generating the file $(TOPDIR)/.version with version 0.0 if one does not exist.
      • -
    • Auto-generating the file include/nuttx/version.h using the $(TOPDIR)/.version file.
      • -
    • Creating a link to $(TOPDIR)/arch/<arch-name>/include at $(TOPDIR)/include/arch.
      • -
    • Creating a link to $(TOPDIR)/boards/<arch-name>/<chip-name>/<board-name>/include at $(TOPDIR)/include/arch/board.
      • -
    • Creating a link to $(TOPDIR)/boards/<arch-name>/<chip-name>/<board-name>/src at $(TOPDIR)/arch/<arch-name>/src/board
      • -
    • Creating a link to ${APPDIR}/include at $(TOPDIR)/include/apps
      • -
    • Creating make dependencies. -
    - - - - - -
    -

    4.0 Architecture APIs

    -
    - -

    - The file include/nuttx/arch.h identifies by prototype all of the APIs that must - be provided by the architecture specific logic. - The internal OS APIs that architecture-specific logic must - interface with also also identified in include/nuttx/arch.h or in - other header files. -

    - -

    4.1 Naming and Header File Conventions

    - -
      -
    • -

      - Common Microprocessor Interfaces. - Any interface that is common to all microprocessors should be prefixed with up_ and prototyped in include/nuttx/arch.h. - The definitions in that header file provide the common interface between NuttX and the architecture-specific implementation in arch/. -

      -
      - up_ is supposed to stand for microprocessor; the u is like the Greek letter micron: ľ. So it would be ľP which is a common shortening of the word microprocessor. I don't like that name very much. I wish I would have used a more obvious prefix like arch_ instead -- then I would not have to answer this question so often. -
      -
      • -
    • -

      - Microprocessor-Specific Interfaces. - An interface which is unique to a certain microprocessor should be prefixed with the name of the microprocessor, for example stm32_, and be prototyped in some header file in the arch/ directories. -

      -

      - There is also a arch/<architecture>/include/<chip>/chip.h header file that can be used to communicate other microprocessor-specific information between the board logic and even application logic. - Application logic may, for example, need to know specific capabilities of the chip. - Prototypes in that chip.h header file should follow the microprocessor-specific naming convention. -

      -
      • -
    • -

      - Common Board Interfaces. - Any interface that is common to all boards should be prefixed with board_ and should also be prototyped in include/nuttx/board.h. - These board_ definitions provide the interface between the board-level logic and the commaon and architecture-specific logic. -

      -
    • -

      - Board-Specific Interfaces. - Any interface which is unique to a board should be prefixed with the board name, for example stm32f4discovery_. - Sometimes the board name is too long so stm32_ would be okay too. - These should be prototyped in boards/<arch>/<chip>/<board>/src/<board>.h and should not be used outside of that directory since board-specific definitions have no meaning outside of the board directory. -

      • -
    • -

      - Scope of Inclusions. - Header files are made accessible to internal OS logic and to applications through symbolic links and through include paths that are provided to the C/C++ compiler. - Through these include paths, the NuttX build system also enforces modularity in the design. - For example, one important design principle is architectural layering. - In this case I am referring to the OS as layered into application interface, common internal OS logic, and lower level platform-specific layers. - The platform-specific layers all reside in the either arch/ sub-directories on the config/ subdirectories: The former sub-directories are reserved for microcontroller-specific logic and the latter for board-specific logic. -

      -

      - In the strict, layered NuttX architecture, the upper level OS services are always available to platform-specific logic. However, the opposite is not true: Common OS logic must never have any dependency on the lower level platform-specific code. The OS logic must be totally agnostic about its hardware environment. Similarly, microcontroller-specific logic was be completely ignorant of board-specific logic. -

      -

      - This strict layering is enforced in the NuttX build system by controlling the compiler include paths: Higher level code can never include header files from either; of the platform-specific source directories; microcontroller-specific code can never include header files from the board-specific source directories. The board-specific directories are, then, at the bottom of the layered hierarchy. -

      -

      - An exception to these inclusion restrictions is the platform-specific include/. These are made available to higher level OS logic. The microcontroller-specific include directory will be linked at include/arch/chip and, hence, can be included like #include <arch/hardware/chip.h. - Similarly, the board-specific include directory will be linked at include/arch/board and, hence, can be included like #include <arch/board/board.h. -

      -

      - Keeping in the spirit of the layered architecture, these publicly visible header files must not export platform-specific definitions; Only platform-specific realizations of standardized declarations should be visible. - Those standardized declarations should appear in common header files such as those provided by include/nuttx/arch.h and include/nuttx/board.h. - Similarly, these publicly visible header file must not include files that reside in the inaccessible platform-specific source directories. - For example, the board-specific boards/<arch>/<chip>/<board>/include/board.h header file must never include microcontroller-specific header files that reside in arch/<arch>/src/<mcu>. - That practice will cause inclusion failures when the publicly visible file is included in common logic outside of the platform-specific source directories. -

      -
      • -
    - -

    4.2 APIs Exported by Architecture-Specific Logic to NuttX

    -

    4.2.1 up_initialize()

    - -

    Function Prototype: void up_initialize(void);

    - -

    Description. - up_initialize() will be called once during OS - initialization after the basic OS services have been - initialized. The architecture specific details of - initializing the OS will be handled here. Such things as - setting up interrupt service routines, starting the - clock, and registering device drivers are some of the - things that are different for each processor and hardware - platform. -

    -

    - up_initialize() is called after the OS initialized but - before the init process has been started and before the - libraries have been initialized. OS services and driver - services are available. -

    - -

    4.2.2 up_idle()

    -

    Function Prototype: void up_idle(void);

    - -

    Description. - up_idle() is the logic that will be executed - when their is no other ready-to-run task. This is processor - idle time and will continue until some interrupt occurs to - cause a context switch from the idle task. -

    -

    - Processing in this state may be processor-specific. e.g., - this is where power management operations might be performed. -

    - -

    4.2.3 up_initial_state()

    -

    Function Prototype: void up_initial_state(FAR struct tcb_s *tcb);

    - -

    Description. - A new thread is being started and a new TCB has been created. - This function is called to initialize the processor specific portions of the new TCB. -

    -

    - This function must setup the initial architecture registers and/or stack so that execution - will begin at tcb->start on the next context switch. -

    -

    - This function may also need to set up processor registers so that the new thread executes - with the correct privileges. - If CONFIG_BUILD_PROTECTED or CONFIG_BUILD_KERNEL have been selected in the NuttX configuration, then special initialization may need to be performed depending on the task type specified in the TCB's flags field: - Kernel threads will require kernel-mode privileges; - User tasks and pthreads should have only user-mode privileges. - If neither CONFIG_BUILD_PROTECTED nor CONFIG_BUILD_KERNEL have been selected, then all threads should have kernel-mode privileges. -

    - -

    4.2.4 up_create_stack()

    -

    Function Prototype: STATUS up_create_stack(FAR struct tcb_s *tcb, size_t stack_size, uint8_t ttype);

    - -

    Description. - Allocate a stack for a new thread and setup up stack-related information in the TCB. -

    -

    - The following TCB fields must be initialized: -

    -
      -
    • adj_stack_size: Stack size after adjustment for hardware, - processor, etc. This value is retained only for debug - purposes.
      • -
    • stack_alloc_ptr: Pointer to allocated stack
      • -
    • adj_stack_ptr: Adjusted stack_alloc_ptr for HW. The - initial value of the stack pointer. -
    - -

    Input Parameters:

    -
      -
    • -

      - tcb: The TCB of new task. -

      -
      • -
    • -

      - stack_size: The requested stack size. At least this much must be allocated. -

      -
      • -
    • -

      - ttype: The thread type. - This may be one of following (defined in include/nuttx/sched.h): -

      -
        -
      • TCB_FLAG_TTYPE_TASK: Normal user task
        • -
      • TCB_FLAG_TTYPE_PTHREAD: User pthread
        • -
      • TCB_FLAG_TTYPE_KERNEL: Kernel thread
        • -
      -

      - This thread type is normally available in the flags field of the TCB, however, there are certain contexts where the TCB may not be fully initialized when up_create_stack is called. -

      -

      - If CONFIG_BUILD_PROTECTED or CONFIG_BUILD_KERNEL are defined, then this thread type may affect how the stack is allocated. For example, kernel thread stacks should be allocated from protected kernel memory. Stacks for user tasks and threads must come from memory that is accessible to user code. -

      -
      • -
    - -

    4.2.5 up_use_stack()

    -

    Function Prototype: - STATUS up_use_stack(FAR struct tcb_s *tcb, FAR void *stack, size_t stack_size); -

    - -

    Description. - Setup up stack-related information in the TCB using pre-allocated stack memory. - This function is called only from nxtask_init() when a task or kernel thread is started (never for pthreads). -

    -

    - The following TCB fields must be initialized: -

    -
      -
    • adj_stack_size: Stack size after adjustment for hardware, - processor, etc. This value is retained only for debug - purposes.
      • -
    • stack_alloc_ptr: Pointer to allocated stack
      • -
    • adj_stack_ptr: Adjusted stack_alloc_ptr for HW. The - initial value of the stack pointer. -
    - -

    Input Parameters:

    -
      -
    • - tcb: The TCB of new task. -
      • -
    • - stack_size: The allocated stack size. -
      • -
    -

    - NOTE: Unlike up_stack_create() and up_stack_release, this function does not require the task type (ttype) parameter. - The TCB flags will always be set to provide the task type to up_use_stack() if the information needs that information. -

    - - -

    4.2.6 up_stack_frame()

    -

    Function Prototype: FAR void *up_stack_frame(FAR struct tcb_s *tcb, size_t frame_size);

    - -

    - Description. - Allocate a stack frame in the TCB's stack to hold thread-specific data. - This function may be called any time after up_create_stack() or up_use_stack() have been called but before the task has been started. -

    -

    - Thread data may be kept in the stack (instead of in the TCB) if it is accessed by the user code directly. - This includes such things as argv[]. - The stack memory is guaranteed to be in the same protection domain as the thread. -

    -

    - The following TCB fields will be re-initialized: -

    -
      -
    • - adj_stack_size: Stack size after removal of the stack frame from the stack. -
      • -
    • - adj_stack_ptr: Adjusted initial stack pointer after the frame has been removed from the stack. - This will still be the initial value of the stack pointer when the task is started. -
      • -
    -

    Input Parameters:

    -
      -
    • -

      - tcb: - The TCB of new task. -

      -
      • -
    • -

      - frame_size: - The size of the stack frame to allocate. -

      -
      • -
    -

    - Returned Value: - A pointer to bottom of the allocated stack frame. - NULL will be returned on any failures. - The alignment of the returned value is the same as the alignment of the stack itself -

    - -

    4.2.7 up_release_stack()

    -

    Function Prototype: void up_release_stack(FAR struct tcb_s *dtcb);

    - -

    Description. - A task has been stopped. - Free all stack related resources retained int the defunct TCB. -

    -

    Input Parameters:

    -
      -
    • -

      - dtcb: - The TCB containing information about the stack to be released. -

      -
      • -
    • -

      - ttype: The thread type. - This may be one of following (defined in include/nuttx/sched.h): -

      -
        -
      • TCB_FLAG_TTYPE_TASK: Normal user task
        • -
      • TCB_FLAG_TTYPE_PTHREAD: User pthread
        • -
      • TCB_FLAG_TTYPE_KERNEL: Kernel thread
        • -
      -

      - This thread type is normally available in the flags field of the TCB, however, there are certain error recovery contexts where the TCB may not be fully initialized when up_release_stack is called. -

      -

      - If CONFIG_BUILD_PROTECTED or CONFIG_BUILD_KERNEL are defined, then this thread type may affect how the stack is freed. - For example, kernel thread stacks may have been allocated from protected kernel memory. - Stacks for user tasks and threads must have come from memory that is accessible to user -

      -
      • -
    - -

    4.2.8 up_unblock_task()

    -

    Function Prototype: void up_unblock_task(FAR struct tcb_s *tcb);

    - -

    Description. - A task is currently in an inactive task list - but has been prepped to execute. Move the TCB to the - ready-to-run list, restore its context, and start execution. -

    -

    - This function is called only from the NuttX scheduling - logic. Interrupts will always be disabled when this - function is called. -

    - -

    Input Parameters: -

      -
    • tcb: Refers to the tcb to be unblocked. This tcb is - in one of the waiting tasks lists. It must be moved to - the ready-to-run list and, if it is the highest priority - ready to run tasks, executed. -
      • -
    - -

    4.2.9 up_block_task()

    -

    Function Prototype: void up_block_task(FAR struct tcb_s *tcb, tstate_t task_state);

    - -

    Description. - The currently executing task at the head of - the ready to run list must be stopped. Save its context - and move it to the inactive list specified by task_state. - - This function is called only from the NuttX scheduling - logic. Interrupts will always be disabled when this - function is called. - -

    Input Parameters:

    -
      -
    • tcb: Refers to a task in the ready-to-run list (normally - the task at the head of the list). It must be stopped, its context saved - and moved into one of the waiting task lists. If it was the task at the - head of the ready-to-run list, then a context switch to the new ready to - run task must be performed. -
      • -
    • task_state: Specifies which waiting task list should be - hold the blocked task TCB. -
      • -
    - -

    4.2.10 up_release_pending()

    -

    Function Prototype: void up_release_pending(void);

    - -

    Description. - When tasks become ready-to-run but cannot run because pre-emption - is disabled, they are placed into a pending task list. - This function releases and makes ready-to-run all of the tasks that have - collected in the pending task list. This can cause a - context switch if a new task is placed at the head of - the ready to run list. -

    -

    - This function is called only from the NuttX scheduling logic when - pre-emption is re-enabled. Interrupts will always be disabled when this - function is called. -

    - -

    4.2.11 up_reprioritize_rtr()

    -

    Function Prototype: void up_reprioritize_rtr(FAR struct tcb_s *tcb, uint8_t priority);

    - -

    Description. - Called when the priority of a running or - ready-to-run task changes and the reprioritization will - cause a context switch. Two cases: -

    -
      -
    1. - The priority of the currently running task drops and the next - task in the ready to run list has priority. -
      2. -
    2. - An idle, ready to run task's priority has been raised above the - the priority of the current, running task and it now has the - priority. -
      3. -
    -

    - This function is called only from the NuttX scheduling - logic. Interrupts will always be disabled when this - function is called. -

    - -

    Input Parameters:

    -
      -
    • - tcb: The TCB of the task that has been reprioritized -
      • -
    • - priority: The new task priority -
      • -
    - -

    4.2.12 up_exit()

    -

    Function Prototype: void up_exit(int status) noreturn_function;

    - -

    Description. - This function causes the currently executing task to cease - to exist. This is a special case of task_delete(). -

    -

    - Unlike other UP APIs, this function may be called - directly from user programs in various states. The - implementation of this function should disable interrupts - before performing scheduling operations. -

    - -

    4.2.13 up_assert()

    -

    Function Prototype:
    - void up_assert(FAR const char *filename, int linenum); -

    - -

    Description. - Assertions may be handled in an architecture-specific way. -

    - -

    4.2.14 up_schedule_sigaction()

    -

    Function Prototype: - void up_schedule_sigaction(FAR struct tcb_s *tcb, sig_deliver_t sigdeliver); -

    - -

    Description. - This function is called by the OS when one or more - signal handling actions have been queued for execution. - The architecture specific code must configure things so - that the 'sigdeliver' callback is executed on the thread - specified by 'tcb' as soon as possible. -

    -

    - This function may be called from interrupt handling logic. -

    -

    - This operation should not cause the task to be unblocked - nor should it cause any immediate execution of sigdeliver. - Typically, a few cases need to be considered: -

    -
      -
    1. - This function may be called from an interrupt handler - During interrupt processing, all xcptcontext structures - should be valid for all tasks. That structure should - be modified to invoke sigdeliver() either on return - from (this) interrupt or on some subsequent context - switch to the recipient task. -
      2. -
    2. - If not in an interrupt handler and the tcb is NOT - the currently executing task, then again just modify - the saved xcptcontext structure for the recipient - task so it will invoke sigdeliver when that task is - later resumed. -
      3. -
    3. - If not in an interrupt handler and the tcb IS the - currently executing task -- just call the signal - handler now. -
      4. -
    - -

    4.2.15 up_allocate_heap()

    -

    Function Prototype: void up_allocate_heap(FAR void **heap_start, size_t *heap_size);

    - -

    Description. - This function will be called to dynamically set aside the heap region. -

    -

    - For the kernel build (CONFIG_BUILD_PROTECTED=y or CONFIG_BUILD_KERNEL=y) with both kernel- and user-space heaps (CONFIG_MM_KERNEL_HEAP=y), this function provides the size of the unprotected, user-space heap. - If a protected kernel-space heap is provided, the kernel heap must be allocated (and protected) by an analogous up_allocate_kheap(). -

    - -

    4.2.16 up_interrupt_context()

    -

    Function Prototype: bool up_interrupt_context(void)

    - -

    Description. - Return true if we are currently executing in the interrupt handler context. -

    - -

    4.2.17 up_disable_irq()

    -

    Function Prototype:

    -
      -#ifndef CONFIG_ARCH_NOINTC
-  void up_disable_irq(int irq);
-#endif
-
    - -

    Description. - Disable the IRQ specified by 'irq' - On many architectures, there are three levels of interrupt enabling: (1) - at the global level, (2) at the level of the interrupt controller, - and (3) at the device level. In order to receive interrupts, they - must be enabled at all three levels. -

    -

    - This function implements enabling of the device specified by 'irq' - at the interrupt controller level if supported by the architecture - (up_irq_save() supports the global level, the device level is hardware - specific). -

    - If the architecture does not support up_disable_irq, - CONFIG_ARCH_NOINTC should be defined in the NuttX configuration file. - Since this API cannot be supported on all architectures, it should be - avoided in common implementations where possible. -

    - -

    4.2.18 up_enable_irq()

    -

    Function Prototype:

    -
      -#ifndef CONFIG_ARCH_NOINTC
-  void up_enable_irq(int irq);
-#endif
-
    - -

    Description. - This function implements disabling of the device specified by 'irq' - at the interrupt controller level if supported by the architecture - (up_irq_restore() supports the global level, the device level is hardware - specific). -

    -

    - If the architecture does not support up_disable_irq, - CONFIG_ARCH_NOINTC should be defined in the NuttX configuration file. - Since this API cannot be supported on all architectures, it should be - avoided in common implementations where possible. -

    - -

    4.2.19 up_prioritize_irq()

    -

    Function Prototype:

    -
      -#ifdef CONFIG_ARCH_IRQPRIO
-  void up_enable_irq(int irq);
-#endif
-
    -

    Description. - Set the priority of an IRQ. -

    -

    - If the architecture supports up_enable_irq, - CONFIG_ARCH_IRQPRIO should be defined in the NuttX configuration file. - Since this API cannot be supported on all architectures, it should be - avoided in common implementations where possible. -

    - -

    4.2.20 up_putc()

    - -

    Function Prototype: int up_putc(int ch);

    -

    Description. - This is a debug interface exported by the architecture-specific logic. - Output one character on the console -

    - -

    4.3 APIs Exported by Board-Specific Logic to NuttX

    - -

    - Exported board-specific interfaces are prototyped in the header file include/nuttx/board.h. - There are many interfaces exported from board- to architecture-specific logic. - But there are only a few exported from board-specific logic to common NuttX logic. - Those few of those related to initialization will be discussed in this paragraph. - There are others, like those used by boardctl() that will be discussed in other paragraphs. -

    -

    - All of the board-specific interfaces used by the NuttX OS logic are for controlled board initialization. - There are three points in time where you can insert custom, board-specific initialization logic: -

    -

    - First, <arch>_board_initialize(): This function is not called from the common OS logic, but rather from the architecture-specific power on reset logic. - This is used only for initialization of very low-level things like configuration of GPIO pins, power settings, DRAM initialization, etc. - The OS has not been initialized at this point, so you cannot allocate memory or initialize device drivers. -

    -

    - The other two board initialization hooks are called from the OS start-up logic and are described in the following paragraphs: -

    - -

    4.3.1 board_early_initialize()

    - -

    - The next level of initialization is performed by a call to up_initialize() (in arch/<arch>/src/common/up_initialize.c). The OS has been initialized at this point and it is okay to initialize drivers in this phase. - up_initialize() is not a board-specific interface, but rather an architecture-specific, board-independent interface. -

    -

    - But at this same point in time, the OS will also call a board-specific initialization function named board_early_initialize() if CONFIG_BOARD_EARLY_INITIALIZE=y is selected in the configuration. - The context in which board_early_initialize() executes is suitable for early initialization of most, simple device drivers and is a logical, board-specific extension of up_initialize(). -

    -

    - board_early_initialize() runs on the startup, initialization thread. - Some initialization operations cannot be performed on the start-up, initialization thread. - That is because the initialization thread cannot wait for event. - Waiting may be required, for example, to mount a file system or or initialize a device such as an SD card. - For this reason, such driver initialize must be deferred to board_late_initialize(). -

    - -

    4.3.2 board_late_initialize()

    - -

    - And, finally, just before the user application code starts. - If CONFIG_BOARD_LATE_INITIALIZE=y is selected in the configuration, then an final, additional initialization call will be performed in the boot-up sequence to a function called board_late_initialize(). - board_late_initialize() will be called well after up_initialize() and board_early_initialize() are called. - board_late_initialize() will be called just before the main application task is started. - This additional initialization phase may be used, for example, to initialize more complex, board-specific device drivers. -

    -

    - Waiting for events, use of I2C, SPI, etc are permissible in the context of board_late_initialize(). - That is because board_late_initialize() will run on a temporary, internal kernel thread. -

    - -

    4.4 System Time and Clock

    - -

    4.4.1 Basic System Timer

    - -

    System Timer - In most implementations, system time is provided by a timer interrupt. - That timer interrupt runs at rate determined by CONFIG_USEC_PER_TICK (default 10000 microseconds or 100Hz. If CONFIG_SCHED_TICKLESS is selected, the default is 100 microseconds). - The timer generates an interrupt each CONFIG_USEC_PER_TICK microseconds and increments a counter called g_system_timer. - g_system_timer then provides a time-base for calculating up-time and elapsed time intervals in units of CONFIG_USEC_PER_TICK. - The range of g_system_timer is, by default, 32-bits. - However, if the MCU supports type long long and CONFIG_SYSTEM_TIME16 is selected, - a 64-bit system timer will be supported instead. -

    -

    System Timer Accuracy - On many system, the exact timer interval specified by CONFIG_USEC_PER_TICK cannot be achieved due to limitations in frequencies or in dividers. - As a result, the time interval specified by CONFIG_USEC_PER_TICK may only be approximate and there may be small errors in the apparent up-time time. - These small errors, however, will accumulate over time and after a long period of time may have an unacceptably large error in the apparent up-time of the MCU. -

    - If the timer tick period generated by the hardware is not exactly CONFIG_USEC_PER_TICK and if there you require accurate up-time for the MCU, then there are measures that you can take: -

    -
      -
    • - Perhaps you can adjust CONFIG_USEC_PER_TICK to a different value so that an exactly CONFIG_USEC_PER_TICK can be realized. -
      • -
    • - Or you can use a technique known as Delta-Sigma Modulation. (Suggested by Uros Platise). Consider the example below. -
      • -
    - -

    Delta-Sigma Modulation Example. - Consider this case: The system timer is a count-up timer driven at 32.768KHz. - There are dividers that can be used, but a divider of one yields the highest accuracy. - This counter counts up until the count equals a match value, then a timer interrupt is generated. - The desire frequency is 100Hz (CONFIG_USEC_PER_TICK is 10000). -

    -

    - This exact frequency of 100Hz cannot be obtained in this case. - In order to obtain that exact frequency a match value of 327.68 would have to be provided. - The closest integer value is 328 but the ideal match value is between 327 and 328. - The closest value, 328, would yield an actual timer frequency of 99.9Hz! - That will may cause significant timing errors in certain usages. -

    -

    - Use of Delta-Sigma Modulation can eliminate this error in the long run. - Consider this example implementation: -

    -
      -
    1. - Initially an accumulator is zero an the match value is programmed to 328: -
        -accumulator = 0;
-match = 328;
-
      -
      2. -
    2. - On each timer interrupt, accumulator is updated with difference that, in this reflects, 100* the error in interval that just passed. - So on the first timer interrupt, the accumulator would be updated like: -
        -if (match == 328)
-  {
-    accumulator += 32; // 100*(328 - 327.68)
-  }
-else
-  {
-    accumulator -= 68; // (100*(327 - 327.68)
-  }
-
      -
      3. -
    3. - And on that same timer interrupt a new match value would be programmed: -
        -if (accumulator < 0)
-  {
-    match = 328;
-  }
-else
-  {
-    match = 327;
-  }
-
      -
    -

    - In this way, the timer interval is controlled from interrupt-to-interrupt to produce an average frequency of exactly 100Hz. -

    - -

    4.4.2 Hardware

    -

    - To enable hardware module use the following configuration options: -

    -

      -
      CONFIG_RTC -
      Enables general support for a hardware RTC. - Specific architectures may require other specific settings. -
      CONFIG_RTC_EXTERNAL -
      Most MCUs include RTC hardware built into the chip. - Other RTCs, external MCUs, may be provided as separate chips typically - interfacing with the MCU via a serial interface such as SPI or I2C. - These external RTCs differ from the built-in RTCs in that they cannot be initialized - until the operating system is fully booted and can support the required serial - communications. CONFIG_RTC_EXTERNAL will configure the operating - system so that it defers initialization of its time facilities. -
      CONFIG_RTC_DATETIME -
      There are two general types of RTC: (1) A simple battery backed counter that keeps the time when power - is down, and (2) A full date / time RTC the provides the date and time information, often in BCD format. - If CONFIG_RTC_DATETIME is selected, it specifies this second kind of RTC. - In this case, the RTC is used to "seed"" the normal NuttX timer and the NuttX system timer - provides for higher resolution time. -
      CONFIG_RTC_HIRES -
      If CONFIG_RTC_DATETIME not selected, then the simple, battery backed counter is used. - There are two different implementations of such simple counters based on the time resolution of the counter: - The typical RTC keeps time to resolution of 1 second, usually supporting a 32-bit time_t value. - In this case, the RTC is used to "seed" the normal NuttX timer and the NuttX timer provides for higher resolution time. - If CONFIG_RTC_HIRES is enabled in the NuttX configuration, then the RTC provides higher resolution time and completely replaces the system timer for purpose of date and time. -
      CONFIG_RTC_FREQUENCY -
      If CONFIG_RTC_HIRES is defined, then the frequency of the high resolution RTC must be provided. - If CONFIG_RTC_HIRES is not defined, CONFIG_RTC_FREQUENCY is assumed to be one. -
      CONFIG_RTC_ALARM -
      Enable if the RTC hardware supports setting of an alarm. - A callback function will be executed when the alarm goes off -
    -

    - which requires the following base functions to read and set time: -

    -
      -
    • up_rtc_initialize(). - Initialize the built-in, MCU hardware RTC per the selected configuration. - This function is called once very early in the OS initialization sequence. - NOTE that initialization of external RTC hardware that depends on the - availability of OS resources (such as SPI or I2C) must be deferred - until the system has fully booted. Other, RTC-specific initialization - functions are used in that case. -
      • -
    • up_rtc_time(). - Get the current time in seconds. This is similar to the standard time() function. - This interface is only required if the low-resolution RTC/counter hardware implementation selected. - It is only used by the RTOS during initialization to set up the system time when CONFIG_RTC is set - but neither CONFIG_RTC_HIRES nor CONFIG_RTC_DATETIME are set. -
      • -
    • up_rtc_gettime(). - Get the current time from the high resolution RTC clock/counter. - This interface is only supported by the high-resolution RTC/counter hardware implementation. - It is used to replace the system timer (g_system_tick). -
      • -
    • up_rtc_settime(). - Set the RTC to the provided time. - All RTC implementations must be able to set their time based on a standard timespec. -
      • -
    - -

    4.4.3 System Tick and Time

    -

    - The system tick is represented by:: -

    -
      -
    • g_system_timer
      • -
    -

    - Running at rate of system base timer, used for time-slicing, and so forth. -

    -

    - If hardware RTC is present (CONFIG_RTC) and and high-resolution timing - is enabled (CONFIG_RTC_HIRES), then after successful - initialization variables are overridden by calls to up_rtc_gettime() which is - running continuously even in power-down modes. -

    -

    - In the case of CONFIG_RTC_HIRES is set the g_system_timer - keeps counting at rate of a system timer, which however, is disabled in power-down mode. - By comparing this time and RTC (actual time) one may determine the actual system active time. - To retrieve that variable use: -

    - -

    4.4.4 Tickless OS

    -

    4.4.4.1 Tickless Overview

    - -

    - Default System Timer. - By default, a NuttX configuration uses a periodic timer interrupt that drives all system timing. The timer is provided by architecture-specific code that calls into NuttX at a rate controlled by CONFIG_USEC_PER_TICK. The default value of CONFIG_USEC_PER_TICK is 10000 microseconds which corresponds to a timer interrupt rate of 100 Hz. -

    -

    - On each timer interrupt, NuttX does these things: -

    -

      -
    • Increments a counter. This counter is the system time and has a resolution of CONFIG_USEC_PER_TICK microseconds. -
    • Checks if it is time to perform time-slice operations on tasks that have select round-robin scheduling. -
    • Checks for expiration of timed events. -
    -

    - What is wrong with this default system timer? Nothing really. It is reliable and uses only a small fraction of the CPU band width. But we can do better. Some limitations of default system timer are, in increasing order of importance: -

    -
      -
    • - Overhead: - Although the CPU usage of the system timer interrupt at 100Hz is really very low, it is still mostly wasted processing time. One most timer interrupts, there is really nothing that needs be done other than incrementing the counter. -
      • -
    • - Resolution: - Resolution of all system timing is also determined by CONFIG_USEC_PER_TICK. So nothing that be time with resolution finer than 10 milliseconds be default. To increase this resolution, CONFIG_USEC_PER_TICK an be reduced. However, then the system timer interrupts use more of the CPU bandwidth processing useless interrupts. -
      • -
    • - Power Usage: - But the biggest issue is power usage. When the system is IDLE, it enters a light, low-power mode (for ARMs, this mode is entered with the wfi or wfe instructions for example). But each interrupt awakens the system from this low power mode. Therefore, higher rates of interrupts cause greater power consumption. -
      • -
    -

    - Tickless OS. - The so-called Tickless OS provides one solution to issue. The basic concept here is that the periodic, timer interrupt is eliminated and replaced with a one-shot, interval timer. It becomes event driven instead of polled: The default system timer is a polled design. On each interrupt, the NuttX logic checks if it needs to do anything and, if so, it does it. -

    -

    - Using an interval timer, one can anticipate when the next interesting OS event will occur, program the interval time and wait for it to fire. When the interval time fires, then the scheduled activity is performed. -

    - -

    4.4.4.2 Tickless Platform Support

    - -In order to use the Tickless OS, one must provide special support from the platform-specific code. Just as with the default system timer, the platform-specific code must provide the timer resources to support the OS behavior. - -Currently these timer resources are only provided on a few platforms. An example implementation is for the simulation is at nuttx/arch/sim/src/up_tickless.c. There is another example for the Atmel SAMA5 at nuttx/arch/arm/src/sama5/sam_tickless.c. These paragraphs will explain how to provide the Tickless OS support to any platform. - -

    4.4.4.3 Tickless Configuration Options

    -
      -
    • -

      - CONFIG_ARCH_HAVE_TICKLESS: - If the platform provides support for the Tickless OS, then this setting should be selected in the Kconfig file for the board. Here is what the selection looks in the arch/Kconfig file for the simulated platform: -

      -
        -config ARCH_SIM
-   bool "Simulation"
-   select ARCH_HAVE_TICKLESS
-   ---help---
-       Linux/Cygwin user-mode simulation.
-
      -

      - When the simulation platform is selected, ARCH_HAVE_TICKLESS is automatically selected, informing the configuration system that Tickless OS options can be selected. -

      -
      • -
    • -

      - CONFIG_SCHED_TICKLESS: - If CONFIG_ARCH_HAVE_TICKLESS is selected, then it will enable the Tickless OS features in NuttX. -

      -
      • -
    • -

      - CONFIG_SCHED_TICKLESS_ALARM: - The tickless option can be supported either via a simple interval timer (plus elapsed time) or via an alarm. The interval timer allows programming events to occur after an interval. With the alarm, you can set a time in the future and get an event when that alarm goes off. This option selects the use of an alarm. -

      -

      - The advantage of an alarm is that it avoids some small timing errors; the advantage of the use of the interval timer is that the hardware requirement may be less. -

      -
      • -
    • -

      - CONFIG_USEC_PER_TICK: - This option is not unique to Tickless OS operation, but changes its relevance when the Tickless OS is selected. - In the default configuration where system time is provided by a periodic timer interrupt, the default system timer is configure the timer for 100Hz or CONFIG_USEC_PER_TICK=10000. If CONFIG_SCHED_TICKLESS is selected, then there are no system timer interrupt. In this case, CONFIG_USEC_PER_TICK does not control any timer rates. Rather, it only determines the resolution of time reported by clock_systime_ticks() and the resolution of times that can be set for certain delays including watchdog timers and delayed work. -

      -

      - In this case there is still a trade-off: It is better to have the CONFIG_USEC_PER_TICK as low as possible for higher timing resolution. However, the time is currently held in unsigned int. On some systems, this may be 16-bits in width but on most contemporary systems it will be 32-bits. In either case, smaller values of CONFIG_USEC_PER_TICK will reduce the range of values that delays that can be represented. So the trade-off is between range and resolution (you could also modify the code to use a 64-bit value if you really want both). -

      -

      - The default, 100 microseconds, will provide for a range of delays up to 120 hours. -

      -

      - This value should never be less than the underlying resolution of the timer. Errors may ensue. -

      -
      • -
    - -

    4.4.4.4 Tickless Imported Interfaces

    -

    - The interfaces that must be provided by the platform specified code are defined in include/nuttx/arch.h, listed below, and summarized in the following paragraphs: -

    -
      -
    • - <arch>_timer_initialize(): - Initializes the timer facilities. Called early in the initialization sequence (by up_initialize()). -
      • -
    • - up_timer_gettime(): - Returns the current time from the platform specific time source. -
      • -
    -

    - The tickless option can be supported either via a simple interval timer (plus elapsed time) or via an alarm. The interval timer allows programming events to occur after an interval. With the alarm, you can set a time in* the future and get an event when that alarm goes off. -

    -

    - If CONFIG_SCHED_TICKLESS_ALARM is defined, then the platform code must provide the following: -

    -

    -

    - If CONFIG_SCHED_TICKLESS_ALARM is notdefined, then the platform code must provide the following verify similar functions: -

    -

    -

    - Note that a platform-specific implementation would probably require two hardware timers: (1) A interval timer to satisfy the requirements of up_timer_start() and up_timer_cancel(), and a (2) a counter to handle the requirement of up_timer_gettime(). Ideally, both timers would run at the rate determined by CONFIG_USEC_PER_TICK (and certainly never slower than that rate). -

    -

    - Since timers are a limited resource, the use of two timers could be an issue on some systems. - The job could be done with a single timer if, for example, the single timer were kept in a free-running at all times. Some timer/counters have the capability to generate a compare interrupt when the timer matches a comparison value but also to continue counting without stopping. If your hardware supports such counters, one might used the CONFIG_SCHED_TICKLESS_ALARM option and be able to simply set the comparison count at the value of the free running timer PLUS the desired delay. Then you could have both with a single timer: An alarm and a free-running counter with the same timer! -

    -

    - In addition to these imported interfaces, the RTOS will export the following interfaces for use by the platform-specific interval timer implementation: -

    - - -
    4.4.4.4.1 <arch>_timer_initialize()
    -

    Function Prototype:

    -
      -#include "up_internal.h"
-void <arch>_timer_initialize()(void);
-
    -

    Description:

    -
      - Initializes all platform-specific timer facilities. This function is called early in the initialization sequence by up_initialize(). On return, the current up-time should be available from up_timer_gettime() and the interval timer is ready for use (but not actively timing). -
    -

    Input Parameters:

    -
      - None -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    -

    Assumptions:

    -
      - Called early in the initialization sequence before any special concurrency protections are required. -
    - -
    4.4.4.4.2 up_timer_gettime()
    -

    Function Prototype:

    -

      -#include <nuttx/arch.h>
-int up_timer_gettime(FAR struct timespec *ts);
-
    -

    Description:

    - Return the elapsed time since power-up (or, more correctly, since <arch>_timer_initialize() was called). This function is functionally equivalent to clock_gettime() for the clock ID CLOCK_MONOTONIC. This function provides the basis for reporting the current time and also is used to eliminate error build-up from small errors in interval time calculations. -
      -
    -

    Input Parameters:

    -
      -
    • ts: Provides the location in which to return the up-time.. -
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    -

    Assumptions:

    -
      - Called from the normal tasking context. The implementation must provide whatever mutual exclusion is necessary for correct operation. This can include disabling interrupts in order to assure atomic register operations. -
    - -
    4.4.4.4.3 up_alarm_cancel()
    -

    Function Prototype:

    -

      -#include <nuttx/arch.h>
-int up_alarm_cancel(FAR struct timespec *ts);
-
    -

    Description:

    - Cancel the alarm and return the time of cancellation of the alarm. These two steps need to be as nearly atomic as possible. nxsched_timer_expiration() will not be called unless the alarm is restarted with up_alarm_start(). If, as a race condition, the alarm has already expired when this function is called, then time returned is the current time. -
      -
    -

    Input Parameters:

    -
      -
    • ts: Location to return the expiration time. The current time should be returned if the timer is not active. ts may be NULL in which case the time is not returned
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    -

    Assumptions:

    -
      - May be called from interrupt level handling or from the normal tasking level. interrupts may need to be disabled internally to assure non-reentrancy. -
    - -
    4.4.4.4.4 up_alarm_start()
    -

    Function Prototype:

    -

      -#include <nuttx/arch.h>
-int up_alarm_start(FAR const struct timespec *ts);
-
    -

    Description:

    - Start the alarm. nxsched_timer_expiration() will be called when the alarm occurs (unless up_alarm_cancel is called to stop it). -
      -
    -

    Input Parameters:

    -
      -
    • ts: The time in the future at the alarm is expected to occur. When the alarm occurs the timer logic will call nxsched_timer_expiration().
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    -

    Assumptions:

    -
      - May be called from interrupt level handling or from the normal tasking level. Interrupts may need to be disabled internally to assure non-reentrancy. -
    - -
    4.4.4.4.5 up_timer_cancel()
    -

    Function Prototype:

    -

      -#include <nuttx/arch.h>
-int up_timer_cancel(FAR struct timespec *ts);
-
    -

    Description:

    - Cancel the interval timer and return the time remaining on the timer. These two steps need to be as nearly atomic as possible. nxsched_timer_expiration() will not be called unless the timer is restarted with up_timer_start(). If, as a race condition, the timer has already expired when this function is called, then that pending interrupt must be cleared so that nxsched_timer_expiration() is not called spuriously and the remaining time of zero should be returned. -
      -
    -

    Input Parameters:

    -
      -
    • ts: Location to return the remaining time. Zero should be returned if the timer is not active.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    -

    Assumptions:

    -
      - May be called from interrupt level handling or from the normal tasking level. interrupts may need to be disabled internally to assure non-reentrancy. -
    - -
    4.4.4.4.6 up_timer_start()
    -

    Function Prototype:

    -

      -#include <nuttx/arch.h>
-int up_timer_start(FAR const struct timespec *ts);
-
    -

    Description:

    - Start the interval timer. nxsched_timer_expiration() will be called at the completion of the timeout (unless up_timer_cancel() is called to stop the timing). -
      -
    -

    Input Parameters:

    -
      -
    • ts: Provides the time interval until nxsched_timer_expiration() is called.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    -

    Assumptions:

    -
      - May be called from interrupt level handling or from the normal tasking level. Interrupts may need to be disabled internally to assure non-reentrancy. -
    - -

    4.4.5 Watchdog Timer Interfaces

    -

    - NuttX provides a general watchdog timer facility. - This facility allows the NuttX user to specify a watchdog timer function - that will run after a specified delay. - The watchdog timer function will run in the context of the timer interrupt handler. - Because of this, a limited number of NuttX interfaces are available to he watchdog timer function. - However, the watchdog timer function may use mq_send(), sigqueue(), - or kill() to communicate with NuttX tasks. -

    - - -

    4.4.5.1 wd_start

    - -

    -Function Prototype: -

    -    #include <nuttx/wdog.h>
-    int wd_start(FAR struct wdog_s *wdog, int delay,
-                 wdentry_t wdentry, wdparm_t arg);
-
    - -

    -Description: This function adds a watchdog to the timer -queue. The specified watchdog function will be called from the -interrupt level after the specified number of ticks has elapsed. -Watchdog timers may be started from the interrupt level. -

    -Watchdog times execute in the context of the timer interrupt handler. -

    -Watchdog timers execute only once. -

    -To replace either the timeout delay or the function to be executed, -call wd_start again with the same wdog; only the most recent -wd_start() on a given watchdog ID has any effect. -

    -Input Parameters: -

      -
    • wdog. Watchdog ID -
    • delay. Delay count in clock ticks -
    • wdentry. Function to call on timeout -
    • arg. The parameter to pass to wdentry. - -

      -NOTE: The parameter must be of type wdparm_t. -

      -
    - -

    -Returned Value: -

      -
    • Zero (OK) is returned on success; a negated errno value is return to indicate the nature of any failure. -
    - -

    -Assumptions/Limitations: The watchdog routine runs in the -context of the timer interrupt handler and is subject to all ISR -restrictions. -

    -POSIX Compatibility: This is a NON-POSIX interface. -VxWorks provides the following comparable interface: -

    -    STATUS wdStart (WDOG_ID wdog, int delay, FUNCPTR wdentry, int parameter);
-
    - -

    -Differences from the VxWorks interface include: -

      -
    • The present implementation supports multiple parameters passed -to wdentry; VxWorks supports only a single parameter. The maximum -number of parameters is determined by -
    - -

    4.4.5.2 wd_cancel

    -

    -Function Prototype: -

    -    #include <nuttx/wdog.h>
-    int wd_cancel(FAR struct wdog_s *wdog);
-
    - -

    -Description: This function cancels a currently running -watchdog timer. Watchdog timers may be canceled from the interrupt -level. -

    -Input Parameters: -

      -
    • wdog. ID of the watchdog to cancel. -
    - -

    -Returned Value: -

      -
    • OK or ERROR -
    - -

    -Assumptions/Limitations: -

    -POSIX Compatibility: This is a NON-POSIX interface. -VxWorks provides the following comparable interface: -

    -    STATUS wdCancel (WDOG_ID wdog);
-
    - -

    4.4.5.3 wd_gettime

    -

    - Function Prototype: -

    -
    -    #include <nuttx/wdog.h>
-    int wd_gettime(FAR struct wdog_s *wdog);
-
    -

    - Description: - This function returns the time remaining before the specified watchdog expires. -

    -

    - Input Parameters: -

      -
    • wdog. Identifies the watchdog that the request is for.
      • -
    -

    -

    - Returned Value: - The time in system ticks remaining until the watchdog time expires. Zero - means either that wdog is not valid or that the wdog has already expired. -

    - -

    4.4.5.4 Watchdog Timer Callback

    -

    - When a watchdog expires, the callback function with this type is called: -

    -
    -    typedef void (*wdentry_t)(wdparm_t arg);
-
    -

    - The argument is passed as scalar wdparm_t values. For systems where the sizeof(pointer) < sizeof(uint32_t), the following union defines the alignment of the pointer within the uint32_t. For example, the SDCC MCS51 general pointer is 24-bits, but uint32_t is 32-bits (of course). -

    - We always have sizeof(pointer) <= sizeof(uintptr_t) by definition. -

    -
      -#if UINTPTR_MAX >= UINT32_MAX
-typedef uintptr_t wdparm_t;
-#else
-typedef uint32_t  wdparm_t;
-#endif
-
    - -

    4.5 Work Queues

    -

    Work Queues. - NuttX provides work queues. Work queues are threads that service a queue of work items to be performed. They are useful for off-loading work to a different threading context, for delayed processing, or for serializing activities. -

    - -

    4.5.1 Classes of Work Queues

    - -

    Classes of Work Queues. - There are three different classes of work queues, each with different properties and intended usage. These class of work queues along with the common work queue interface are described in the following paragraphs. -

    - -

    4.5.1.1 High Priority Kernel Work queue

    - -

    High Priority Kernel Work queue. - The dedicated high-priority work queue is intended to handle delayed processing from interrupt handlers. This work queue is required for some drivers but, if there are no complaints, can be safely disabled. The high priority worker thread also performs garbage collection -- completing any delayed memory deallocations from interrupt handlers. If the high-priority worker thread is disabled, then that clean up will be performed either by (1) the low-priority worker thread, if enabled, and if not (2) the IDLE thread instead (which runs at the lowest of priority and may not be appropriate if memory reclamation is of high priority) -

    -

    Device Driver Bottom Half. - The high-priority worker thread is intended to serve as the bottom half for device drivers. As a consequence it must run at a very high, fixed priority rivalling the priority of the interrupt handler itself. Typically, the high priority work queue should be the highest priority thread in your system (the default priority is 224). -

    -

    - Thread Pool. - The work queues can be configured to support multiple, low-priority threads. This is essentially a thread pool that provides multi-threaded servicing of the queue work. This breaks the strict serialization of the "queue" (and hence, the work queue is no longer a queue at all). -

    -

    - Multiple worker threads are required to support, for example, I/O operations that stall waiting for input. If there is only a single thread, then the entire work queue processing would stall in such cases. - Such behavior is necessary to support asynchronous I/O, AIO, for example. -

    -

    Compared to the Low Priority Kernel Work Queue. - For less critical, lower priority, application oriented worker thread support, consider enabling the lower priority work queue. The lower priority work queue runs at a lower priority, of course, but has the added advantage that it supports priority inheritance (if CONFIG_PRIORITY_INHERITANCE=y is also selected): The priority of the lower priority worker thread can then be adjusted to match the highest priority client. -

    -

    - Configuration Options. -

    -
      -
    • CONFIG_SCHED_HPWORK. - Enables the hight priority work queue. -
      • -
    • CONFIG_SCHED_HPNTHREADS. - The number of threads in the high-priority queue's thread pool. Default: 1 -
      • -
    • CONFIG_SCHED_HPWORKPRIORITY. - The execution priority of the high-priority worker thread. Default: 224 -
      • -
    • CONFIG_SCHED_HPWORKSTACKSIZE. - The stack size allocated for the worker thread in bytes. Default: 2048. -
      • -
    -

    - Common Configuration Options. - These options apply to all work queues: -

    -
      -
    • CONFIG_SIG_SIGWORK - The signal number that will be used to wake-up the worker thread. This same signal is used with the Default: 17 -
      • -
    - -

    4.5.1.2 Low Priority Kernel Work Queue

    -

    - Low Priority Kernel Work Queue. - This lower priority work queue is better suited for more extended, application oriented processing such as file system clean-up, memory garbage collection and asynchronous I/O operations. -

    -

    - Compared to the High Priority Work Queue. - The lower priority work queue runs at a lower priority than the high priority work queue, of course, and so is inappropriate to serve as a driver bottom half. - It is, otherwise, very similar to the high priority work queue and most of the discussion above for the high priority work queue applies equally here. - The lower priority work queue does have one important, however, that make it better suited for some tasks: -

    -

    Priority Inheritance. - The lower priority worker thread(s) support priority inheritance (if <config> CONFIG_PRIORITY_INHERITANCE is also selected): The priority of the lower priority worker thread can then be adjusted to match the highest priority client. -

    -
    - NOTE: This priority inheritance feature is not automatic. The lower priority worker thread will always a fixed priority unless additional logic implements that calls lpwork_boostpriority() to raise the priority of the lower priority worker thread (typically called before scheduling the work) and then calls the matching lpwork_restorepriority() when the work is completed (typically called within the work handler at the completion of the work). Currently, only the NuttX asynchronous I/O logic uses this dynamic prioritization feature. -
    -

    - The higher priority worker thread, on the other hand, is intended to serve as the bottom half for device drivers. As a consequence must run at a very high, fixed priority. Typically, it should be the highest priority thread in your system. -

    -

    - Configuration Options. -

    -
      -
    • CONFIG_SCHED_LPWORK. - If CONFIG_SCHED_LPWORK is selected then a lower-priority work queue will be enabled. -
      • -
    • CONFIG_SCHED_LPNTHREADS. - The number of threads in the low-priority queue's thread pool. Default: 1 -
      • -
    • CONFIG_SCHED_LPWORKPRIORITY. - The minimum execution priority of the lower priority worker thread. The priority of the all worker threads start at this priority. If priority inheritance is in effect, the priority may be boosted from this level. Default: 50. -
      • -
    • CONFIG_SCHED_LPWORKPRIOMAX. - The maximum execution priority of the lower priority worker thread. Lower priority worker threads will be started at CONFIG_SCHED_LPWORKPRIORITY but their priority may be boosted due to priority inheritance. The boosted priority of the low priority worker thread will not, however, ever exceed CONFIG_SCHED_LPWORKPRIOMAX. This limit would be necessary, for example, if the higher priority worker thread were to defer work to the lower priority thread. Clearly, in such a case, you would want to limit the maximum priority of the lower priority work thread. Default: 176. -
      • -
    • CONFIG_SCHED_LPWORKSTACKSIZE. - The stack size allocated for the lower priority worker thread. Default: 2048. -
      • -
    - -

    4.5.1.3 User-Mode Work Queue

    -

    - Work Queue Accessibility. - The high- and low-priority worker threads are kernel-mode threads. In the normal, flat NuttX build, these work queues are are useful to application code and may be shared. However, in the NuttX protected and kernel build modes, kernel mode code is isolated and cannot be accessed from user-mode code. -

    -

    - User-Mode Work Queue. - if either CONFIG_BUILD_PROTECTED or CONFIG_BUILD_KERNEL are selected, then the option to enable a special user-mode work queue is enable. The interface to the user-mode work queue is identical to the interface to the kernel-mode work queues and the user-mode work queue is functionally equivalent to the high priority work queue. It differs in that its implementation does not depend on internal, kernel-space facilities. -

    -

    - Configuration Options. -

    -
      -
    • CONFIG_LIB_USRWORK. - If CONFIG_LIB_USRWORK is also defined then the user-mode work queue will be enabled. -
    • CONFIG_LIB_USRWORKPRIORITY. - The execution priority of the user-mode priority worker thread. Default: 100 -
    • CONFIG_LIB_USRWORKSTACKSIZE. - The stack size allocated for the lower priority worker thread. Default: 2048. -
    - -

    4.5.2 Common Work Queue Interfaces

    -

    4.5.2.1 Work Queue IDs

    - -

    - Work queue IDs. - All work queues use the identical interface functions (at least identical in terms of the function signature). The first parameter passed to the work queue interface function identifies the work queue: -

    -

    - Kernel-Mode Work Queue IDs: -

    -

      -
    • - HPWORK. - This ID of the high priority work queue that should only be used for hi-priority, time-critical, driver bottom-half functions. -
      • -
    • - LPWORK. - This is the ID of the low priority work queue that can be used for any purpose. if CONFIG_SCHED_LPWORK is not defined, then there is only one kernel work queue and LPWORK is equal to HPWORK. -
      • -
    -

    - User-Mode Work Queue IDs: -

    -

      -
    • - USRWORK. - This is the ID of the user-mode work queue that can be used for any purpose by applications. In a flat build, LPWORK is equal to LPWORK so that user applications will use the lower priority work queue (if there is one). -
      • -
    - -

    4.5.2.2 Work Queue Interface Types

    - -
      -
    • - typedef void (*worker_t)(FAR void *arg); - Defines the type of the work callback. -
      • -
    • - struct work_s. - Defines one entry in the work queue. This is a client-allocated structure. Work queue clients should not reference any field in this structure since they are subject to change. The user only needs this structure in order to declare instances of the work structure. Handling of all fields is performed by the work queue interfaces described below. -
      • -
    - -

    4.5.2.3 Work Queue Interfaces

    -
    4.5.2.3.1 work_queue()
    -

    - Function Prototype: - 

      -#include <nuttx/wqueue.h>
-int work_queue(int qid, FAR struct work_s *work, worker_t worker,
-               FAR void *arg, uint32_t delay);
-
    -

    -

    - Description. - Queue work to be performed at a later time. All queued work will be performed on the worker thread of execution (not the caller's). -

    -

    - The work structure is allocated and must be initialized to all zero by the caller. - Otherwise, the work structure is completely managed by the work queue logic. - The caller should never modify the contents of the work queue structure directly. - If work_queue() is called before the previous work as been performed and removed from the queue, then any pending work will be canceled and lost. -

    -

    - Input Parameters: -

    -
      -
    • -

      - qid: - The work queue ID. -

      -
      • -
    • -

      - work: - The work structure to queue -

      -
      • -
    • -

      - worker: - The worker callback to be invoked. The callback will invoked on the worker thread of execution. -

      -
      • -
    • -

      - arg: - The argument that will be passed to the worker callback function when it is invoked. -

      -
      • -
    • -

      - delay: - Delay (in system clock ticks) from the time queue until the worker is invoked. Zero means to perform the work immediately. -

      -
      • -
    -

    - Returned Value: -

    -
      -

      - Zero is returned on success; a negated errno is returned on failure. -

      -
    - -
    4.5.2.3.2 work_cancel()
    -

    - Function Prototype: -#include <nuttx/wqueue.h> -int work_cancel(int qid, FAR struct work_s *work); - 

      -
    -

    -

    - Description. - Cancel previously queued work. This removes work from the work queue. After work has been cancelled, it may be re-queue by calling work_queue() again. -

    -

    - Input Parameters: -

    -
      -
    • -

      - qid: - The work queue ID. -

      -
      • -
    • -

      - work: - The previously queue work structure to cancel. -

      -
      • -
    -

    - Returned Value: -

    -
      -

      - Zero is returned on success; a negated errno is returned on failure. -

      -
        -
      • ENOENT: There is no such work queued.
        • -
      • EINVAL: An invalid work queue was specified.
        • -
      -
    - -
    4.5.2.3.3 work_signal()
    -

    - Function Prototype: -#include <nuttx/wqueue.h> -int work_signal(int qid); - 

      -
    -

    -

    - Description. - Signal the worker thread to process the work queue now. This function is used internally by the work logic but could also be used by the user to force an immediate re-assessment of pending work. -

    -

    - Input Parameters: -

    -
      -
    • -

      - qid: - The work queue ID. -

      -
    -

    - Returned Value: -

    -
      -

      - Zero is returned on success; a negated errno is returned on failure. -

      -
    - -
    4.5.2.3.4 work_available()
    -

    - Function Prototype: - 

      -#include <nuttx/wqueue.h>
-bool work_available(FAR struct work_s *work);
-
    -

    -

    - Description. -

    -

    - Input Parameters: - Check if the work structure is available. -

    -
      -
    • -

      - work: - The work queue structure to check. -

      -
    -

    - Returned Value: -

    -
      -

      - true if available; false if busy (i.e., there is still pending work). -

      -
    - -
    4.5.2.3.5 work_usrstart()
    -

    - Function Prototype: - 

      -#include <nuttx/config.h>
-#include <nuttx/wqueue.h>
-#if defined(CONFIG_LIB_USRWORK) && !defined(__KERNEL__)
-int work_usrstart(void);
-#endif
-
    -

    -

    - Description. - The function is only available as a user interface in the kernel-mode build. In the flat build, there is no user-mode work queue; in the protected mode, the user-mode work queue will automatically be started by the OS start-up code. But in the kernel mode, each user process will be required to start is own, private instance of the user-mode work thread using this interface. -

    -

    - Input Parameters: None -

    -

    - Returned Value: -

    -
      -

      - The task ID of the worker thread is returned on success. A negated errno value is returned on failure. -

      -
    - -
    4.5.2.3.6 lpwork_boostpriority()
    -

    - Function Prototype: - 

      -#include <nuttx/config.h>
-#include <nuttx/wqueue.h>
-#if defined(CONFIG_SCHED_LPWORK) && defined(CONFIG_PRIORITY_INHERITANCE)
-void lpwork_boostpriority(uint8_t reqprio);
-#endif
-
    -

    -

    - Description. - Called by the work queue client to assure that the priority of the low-priority worker thread is at least at the requested level, reqprio. This function would normally be called just before calling work_queue(). -

    -

    - Input Parameters: -

    -
      -
    • -

      - reqprio: - Requested minimum worker thread priority. -

      -
      • -
    -

    - Returned Value: None -

    - -
    4.5.2.3.7 lpwork_restorepriority()
    -

    - Function Prototype: - 

      -#include <nuttx/config.h>
-#include <nuttx/wqueue.h>
-#if defined(CONFIG_SCHED_LPWORK) && defined(CONFIG_PRIORITY_INHERITANCE)
-void lpwork_restorepriority(uint8_t reqprio);
-#endif
-
    -

    -

    - Description. - This function is called to restore the priority after it was previously boosted. This is often done by client logic on the worker thread when the scheduled work completes. It will check if we need to drop the priority of the worker thread. -

    -

    - Input Parameters: -

    -
      -
    • -

      - reqprio: - Previously requested minimum worker thread priority to be "unboosted". -

      -
      • -
    -

    - Returned Value: None -

    - -

    4.6 Address Environments

    -

    - CPUs that support memory management units (MMUs) may provide address environments within which tasks and their child threads execute. - The configuration indicates the CPUs ability to support address environments by setting the configuration variable CONFIG_ARCH_HAVE_ADDRENV=y. - That will enable the selection of the actual address environment support which is indicated by the selection of the configuration variable CONFIG_ARCH_ADDRENV=y. - These address environments are created only when tasks are created via exec() or exec_module() (see include/nuttx/binfmt/binfmt.h). -

    -

    - When CONFIG_ARCH_ADDRENV=y is set in the board configuration, the CPU-specific logic must provide a set of interfaces as defined in the header file include/nuttx/arch.h. - These interfaces are listed below and described in detail in the following paragraphs. -

    -

    - The CPU-specific logic must provide two categories in interfaces: -

    -
      -
    1. -

      - Binary Loader Support. - These are low-level interfaces used in binfmt/ to instantiate tasks with address environments. - These interfaces all operate on type group_addrenv_t which is an abstract representation of a task group's address environment and the type must be defined inarch/arch.h if CONFIG_ARCH_ADDRENV is defined. These low-level interfaces include: -

      - -
      2. -
    2. -

      - Tasking Support. - Other interfaces must be provided to support higher-level interfaces used by the NuttX tasking logic. - These interfaces are used by the functions in sched/ and all operate on the task group which as been assigned an address environment by up_addrenv_clone(). -

      -
        -
      • - 4.6.9 up_addrenv_attach(): - Clone the group address environment assigned to a new thread. - This operation is done when a pthread is created that share's the same address environment. -
        • -
      • - 4.6.10 up_addrenv_detach(): - Release the thread's reference to a group address environment when a task/thread exits. -
        • -
      -
      3. -
    3. -

      - Dynamic Stack Support. - CONFIG_ARCH_STACK_DYNAMIC=y indicates that the user process stack resides in its own address space. - This option is also required if CONFIG_BUILD_KERNEL and CONFIG_LIBC_EXECFUNCS are selected. - Why? - Because the caller's stack must be preserved in its own address space when we instantiate the environment of the new process in order to initialize it. -

      -

      - NOTE: The naming of the CONFIG_ARCH_STACK_DYNAMIC selection implies that dynamic stack allocation is supported. - Certainly this option must be set if dynamic stack allocation is supported by a platform. - But the more general meaning of this configuration environment is simply that the stack has its own address space. -

      -

      - If CONFIG_ARCH_STACK_DYNAMIC=y is selected then the platform specific code must export these additional interfaces: -

      - -
      4. -
    4. -

      - If CONFIG_ARCH_KERNEL_STACK is selected, then each user process will have two stacks: (1) a large (and possibly dynamic) user stack and (2) a smaller kernel stack. However, this option is required if both CONFIG_BUILD_KERNEL and CONFIG_LIBC_EXECFUNCS are selected. Why? Because when we instantiate and initialize the address environment of the new user process, we will temporarily lose the address environment of the old user process, including its stack contents. The kernel C logic will crash immediately with no valid stack in place. -

      -

      - If CONFIG_ARCH_KERNEL_STACK=y is selected then the platform specific code must export these additional interfaces: -

      - -
      5. -
    - -

    4.6.1 up_addrenv_create()

    -

    Function Prototype:

    -
      - int up_addrenv_create(size_t textsize, size_t datasize, size_t heapsize, FAR group_addrenv_t *addrenv); -
    -

    Description:

    -
      - This function is called when a new task is created in order to instantiate an address environment for the new task group. - up_addrenv_create() is essentially the allocator of the physical memory for the new task. -
    -

    Input Parameters:

    -
      -
    • textsize: The size (in bytes) of the .text address environment needed by the task. This region may be read/execute only.
      • -
    • datasize: The size (in bytes) of the .bss/.data address environment needed by the task. This region may be read/write only.
      • -
    • heapsize: The initial size (in bytes) of the heap address environment needed by the task. This region may be read/write only.
      • -
    • addrenv: The location to return the representation of the task address environment.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.2 up_addrenv_destroy()

    -

    Function Prototype:

    -

      - int up_addrenv_destroy(group_addrenv_t *addrenv); -
    -

    Description:

    -
      - This function is called when a final thread leaves the task group and the task group is destroyed. This function then destroys the defunct address environment, releasing the underlying physical memory allocated by up_addrenv_create(). -
    -

    Input Parameters:

    -
      -
    • addrenv: The representation of the task address environment previously returned by up_addrenv_create().
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.3 up_addrenv_vtext()

    -

    Function Prototype:

    -

      - int up_addrenv_vtext(FAR group_addrenv_t addrenv, FAR void **vtext); -
    -

    Description:

    -
      - Return the virtual .text address associated with the newly create address environment. - This function is used by the binary loaders in order get an address that can be used to initialize the new task. -
    -

    Input Parameters:

    -
      -
    • addrenv: The representation of the task address environment previously returned by up_addrenv_create().
      • -
    • vtext: The location to return the virtual address.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.4 up_addrenv_vdata()

    -

    Function Prototype:

    -

      - int up_addrenv_vdata(FAR group_addrenv_t *addrenv, size_t textsize, FAR void **vdata); -
    -

    Description:

    -
      - Return the virtual .text address associated with the newly create address environment. - This function is used by the binary loaders in order get an address that can be used to initialize the new task. -
    -

    Input Parameters:

    -
      -
    • addrenv: The representation of the task address environment previously returned by up_addrenv_create().
      • -
    • textsize: For some implementations, the text and data will be saved in the same memory region (read/write/execute) and, in this case, the virtual address of the data just lies at this offset into the common region.
      • -
    • vdata: The location to return the virtual address.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.5 up_addrenv_heapsize()

    -

    Function Prototype:

    -

      - ssize_t up_addrenv_heapsize(FAR const group_addrenv_t *addrenv); -
    -

    Description:

    -
      - Return the initial heap allocation size. - That is the amount of memory allocated by up_addrenv_create() when the heap memory region was first created. - This may or may not differ from the heapsize parameter that was passed to up_addrenv_create(). -
    -

    Input Parameters:

    -
      -
    • addrenv: The representation of the task address environment previously returned by up_addrenv_create().
      • -
    -

    Returned Value:

    -
      - The initial heap size allocated is returned on success; a negated errno value on failure. -
    - -

    4.6.6 up_addrenv_select()

    -

    Function Prototype:

    -

      - int up_addrenv_select(group_addrenv_t *addrenv, save_addrenv_t *oldenv); -
    -

    Description:

    -
      - After an address environment has been established for a task (via up_addrenv_create()), this function may be called to instantiate that address environment in the virtual address space. - This might be necessary, for example, to load the code for the task from a file or to access address environment private data. -
    -

    Input Parameters:

    -
      -
    • addrenv: The representation of the task address environment previously returned by up_addrenv_create().
      • -
    • oldenv: - The address environment that was in place before up_addrenv_select() was called. - This may be used with up_addrenv_restore() to restore the original address environment that was in place before up_addrenv_select() was called. - Note that this may be a task agnostic, platform-specific representation that may or may not be different from group_addrenv_t. -
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.7 up_addrenv_restore()

    -

    Function Prototype:

    -

      - int up_addrenv_restore(save_addrenv_t oldenv); -
    -

    Description:

    -
      - After an address environment has been temporarily instantiated by up_addrenv_select, - this function may be called to restore the original address environment. -
    -

    Input Parameters:

    -
      -
    • oldenv: The platform-specific representation of the address environment previously returned by up_addrenv_select().
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.8 up_addrenv_clone()

    -

    Function Prototype:

    -

      - int up_addrenv_clone(FAR const task_group_s *src, FAR struct task_group_s *dest); -
    -

    Description:

    -
      - Duplicate an address environment. This does not copy the underlying memory, only the representation that can be used to instantiate that memory as an address environment. -
    -

    Input Parameters:

    -
      -
    • src: The address environment to be copied.
      • -
    • dest: The location to receive the copied address environment.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.9 up_addrenv_attach()

    -

    Function Prototype:

    -

      - int up_addrenv_attach(FAR struct task_group_s *group, FAR struct tcb_s *tcb); -
    -

    Description:

    -
      -

      - This function is called from the core scheduler logic when a thread is created that needs to share the address environment of its task group. - In this case, the group's address environment may need to be "cloned" for the child thread. -

      -

      - NOTE: In most platforms, nothing will need to be done in this case. - Simply being a member of the group that has the address environment may be sufficient. -

      -
    -

    Input Parameters:

    -
      -
    • group: The task group to which the new thread belongs.
      • -
    • ctcb: The TCB of the thread needing the address environment.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.10 up_addrenv_detach()

    -

    Function Prototype:

    -

      - int up_addrenv_detach(FAR struct task_group_s *group, FAR struct task_group_s *tcb); -
    -

    Description:

    -
      - This function is called when a task or thread exits in order to release its reference to an address environment. The address environment, however, should persist until up_addrenv_destroy() is called when the task group is itself destroyed. Any resources unique to this thread may be destroyed now. -
    -

    Input Parameters:

    -
      -
    • group: The group to which the thread belonged.
      • -
    • tcb: The TCB of the task or thread whose the address environment will be released.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.11 up_addrenv_ustackalloc()

    -

    Function Prototype:

    -

      - int up_addrenv_ustackalloc(FAR struct tcb_s *tcb, size_t stacksize); -
    -

    Description:

    -
      -

      - This function is called when a new thread is created in order to instantiate an address environment for the new thread's stack. - up_addrenv_ustackalloc() is essentially the allocator of the physical memory for the new task's stack. -

      -
    -

    Input Parameters:

    -
      -
    • tcb: The TCB of the thread that requires the stack address environment.
      • -
    • stacksize: The size (in bytes) of the initial stack address environment needed by the task. This region may be read/write only.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.12 up_addrenv_ustackfree()

    -

    Function Prototype:

    -

      - int up_addrenv_ustackfree(FAR struct tcb_s *tcb); -
    -

    Description:

    -
      -

      - This function is called when any thread exits. - This function then destroys the defunct address environment for the thread's stack, releasing the underlying physical memory. -

      -
    -

    Input Parameters:

    -
      -
    • tcb: The TCB of the thread that no longer requires the stack address environment.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.13 up_addrenv_vustack()

    -

    Function Prototype:

    -

      - int up_addrenv_vustack(FAR const struct tcb_s *tcb, FAR void **vstack); -
    -

    Description:

    -
      -

      - Return the virtual address associated with the newly create stack address environment. -

      -
    -

    Input Parameters:

    -
      -
    • tcb:The TCB of the thread with the stack address environment of interest.
      • -
    • vstack: The location to return the stack virtual base address.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.14 up_addrenv_ustackselect()

    -

    Function Prototype:

    -

      - int up_addrenv_ustackselect(FAR const struct tcb_s *tcb); -
    -

    Description:

    -
      -

      - After an address environment has been established for a task's stack (via up_addrenv_ustackalloc(). - This function may be called to instantiate that address environment in the virtual address space. - This is a necessary step before each context switch to the newly created thread (including the initial thread startup). -

      -
    -

    Input Parameters:

    -
      -
    • tcb: The TCB of the thread with the stack address environment to be instantiated.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.15 up_addrenv_kstackalloc()

    -

    Function Prototype:

    -

      - int up_addrenv_kstackalloc(FAR struct tcb_s *tcb); -
    -

    Description:

    -
      -

      - This function is called when a new thread is created to allocate the new thread's kernel stack. - This function may be called for certain terminating threads which have no kernel stack. - It must be tolerant of that case. -

      -
    -

    Input Parameters:

    -
      -
    • tcb: The TCB of the thread that requires the kernel stack.
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.6.16 up_addrenv_kstackfree()

    -

    Function Prototype:

    -

      - int up_addrenv_kstackfree(FAR struct tcb_s *tcb); -
    -

    Description:

    -
      -

      - This function is called when any thread exits. This function frees the kernel stack. -

      -
    -

    Input Parameters:

    -
      -
    • - tcb: The TCB of the thread that no longer requires the kernel stack. -
      • -
    -

    Returned Value:

    -
      - Zero (OK) on success; a negated errno value on failure. -
    - -

    4.7 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 nx_start()

    -

    - To be provided -

    - -

    4.7.2 OS List Management APIs

    -

    - To be provided -

    - -

    4.7.3 nxsched_process_timer()

    -

    Function Prototype:

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

    Description. - This function handles system timer events. - The timer interrupt logic itself is implemented in the - architecture specific code, but must call the following OS - function periodically -- the calling interval must be - CONFIG_USEC_PER_TICK. -

    - -

    4.7.4 nxsched_timer_expiration()

    -

    Function Prototype:

    -

      -#include <nuttx/arch.h>
-void nxsched_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.5 nxsched_alarm_expiration()

    -

    Function Prototype:

    -

      -#include <nuttx/arch.h>
-void nxsched_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()

    -

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

    - -

    Description. - This function must be called from the architecture- - specific logic in order to display an interrupt to - the appropriate, registered handling logic. -

    - -

    4.8 Application OS vs. Internal OS Interfaces

    - -

    - NuttX provides a standard, portable OS interface for use by applications. - This standard interface is controlled by the specifications proved at OpenGroup.org. - These application interfaces, in general, should not be used directly by logic executing within the OS. The reason for this is that there are certain properties of the standard application interfaces that make them unsuitable for use within the OS - These properties include: -

    -
      -
    1. -

      - Use of the per-thread errno variable: - Handling of return values, particularly, in the case of returned error indications. - Most legacy POSIX OS interface return information via a per-thread errno. - There must be no alteration of the errno value that must be stable from the point of view of the application. - So, as a general rule, internal OS logic must never modify the errno and particularly not by the inappropriate use of application OS interfaces within OS itself. -

      -

      - Within the OS, functions do not return error information via the errno variable. Instead, the majority of internal OS function return error information as an integer value: Returned values greater than or equal to zero are success values; returned values less than zero indicate failures. - Failures are reported by returning a negated errno value from include/errno.h, -

      -
    2. -

      Cancellation Points: - Many of the application OS interfaces are cancellation points, i.e., when the task is operating in deferred cancellation state, it cannot be deleted or cancelled until it calls an application OS interface that is a cancellation point. -

      -

      - The POSIX specification is very specific about this, specific both in identifying which application OS interfaces are cancellation points and specific in the fact that it is prohibited for any OS operation other than those listed in the specification to generate cancellation points. - If internal OS logic were to re-use application OS interfaces directly then it could very easily violate this POSIX requirement by incorrectly generating cancellation points on inappropriate OS operations and could result in very difficult to analyze application failures. -

      -
      3. -
    3. -

      Use of per-task Resources: - Many resources are only valid in the task group context in which a thread operates. Above we mentioned one: errno is only valid for the thread that is currently executing. So, for example, the errno at the time of a call is a completely different variable than, say, the errno while running in a work queue task. -

      -

      - File descriptors are an even better example: An open file on file descriptor 5 on task A is not the same open file as might be used on file descriptor 5 on task B. -

      -

      - As a result, internal OS logic may not use application OS interfaces that use file descriptors or any other per-task resource. -

      -
      4. -
    -

    - Within NuttX, this is handled by supporting equivalent internal OS interfaces that do not break the above rules. - These internal interfaces are intended for use only within the OS and should not be used by application logic. - Some examples include: -

    -
      -
    • -

      - nxsem_wait(): - nxsem_wait() is functionally equivalent to the standard application interface sem_wait(). However, nxsem_wait() will not modify the errno value and will not cause a cancellation point. - (see include/nuttx/semaphore.h for other internal OS interfaces for semaphores). -

      -
      • -
    • -

      - nxsig_waitinfo(): - nxsig_waitinfo() is functionally equivalent to the standard application interface sigwaitinfo(). However, nxsig_waitinfo() will not modify the errno value and will not cause a cancellation point (see include/nuttx/signal.h for other internal OS interfaces for signals). -

      -
      • -
    • -

      - nxmq_send(): - nxmq_send() is functionally equivalent to the standard application interface mq_send(). However, nxmq_send() will not modify the errno value and will not cause a cancellation point (see include/nuttx/mqueue.h for other internal OS interfaces for POSIX message queues). -

      -
      • -
    • -

      - file_read(): - file_read() is functionally equivalent to the standard application interface read(). However, file_read() will not modify the errno value, will not cause a cancellation point, and uses a special internal data structure in place of the file descriptor (see include/nuttx/fs/fs.h for other internal OS interfaces for VFS functions). -

      -
      • -
    • -

      - psock_recvfrom(): - psock_recvfrom() is functionally equivalent to the standard application interface recvfrom(). However, psock_recvfrom() will not modify the errno value, will not cause a cancellation point, and uses a special internal data structure in place of the socket descriptor (see include/nuttx/net/net.h for other internal OS interfaces for sockets). -

      -
      • -
    - -

    4.9 boardctl() Application Interface

    - -

    Function Prototype:

    -

      - - include <sys/boardctl.h>
      - int boardctl(unsigned int cmd, uintptr_t arg); -       -
    -

    Description:

    -
      -

      - In a small embedded system, there will typically be a much greater interaction between application and low-level board features. - The canonically correct to implement such interactions is by implementing a character driver and performing the interactions via low level ioctl() calls. - This, however, may not be practical in many cases and will lead to "correct" but awkward implementations. -

      -

      - boardctl() is non-standard OS interface to alleviate the problem. - It basically circumvents the normal device driver ioctl() interlace and allows the application to perform direct IOCTL-like calls to the board-specific logic. - It is especially useful for setting up board operational and test configurations. -

      -

      - NOTE: The other interfaces described in this document are internal OS interface. - boardctl() is an application interface to the OS. - There is no point, in fact, of using boardctl() within the OS; - the board interfaces prototyped in include/nuttx/board.h may be called directly from within the OS. -

      -

      - Application interfaces are described in the NuttX User Guide. - This application interface interface is described here only because it is so non-standard and because it is so closely tied to board porting logic. -

      -
    -

    Input Parameters:

    -
      -
    • - cmd: Identifies the board command to be executed. - See include/sys/boardctl.h for the complete list of common board commands. - Provisions are made to support non-common, board-specific commands as well. -
      • -
    • - arg: The argument that accompanies the command. - The nature of the argument is determined by the specific command. -
      • -
    -

    Returned Value:

    -
      - On success zero (OK) is returned; - -1 (ERROR) is returned on failure with the errno variable set to indicate the nature of the failure. -
    - -

    4.10 Symmetric Multiprocessing (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.10.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.10.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.10.3 up_cpu_start()

    -

    Function Prototype:

    -

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

    Description:

    -
      -

      - In an SMP configuration, 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.10.4 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.10.5 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.11 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. - The user interfaces are provided in the standard header file include/sys/shm.h>. - All logic to support shared memory is implemented within the NuttX kernel with the exception of two low-level functions that are require to configure the platform-specific MMU resources. - Those interfaces are described below: -

    - -

    4.11.1 up_shmat()

    -

    Function Prototype:

    -

      -#include <nuttx/arch.h>
-#ifdef CONFIG_MM_SHM
-int up_shmat(FAR uintptr_t *pages, unsigned int npages, uintptr_t vaddr);
-#endif
-
    -

    Description:

    -
      - Attach, i.e, map, on shared memory region to a user virtual address. -
    -

    Input Parameters:

    -
      -
    • - pages: A pointer to the first element in a array of physical address, each corresponding to one page of memory. -
      • -
    • - npages: The number of pages in the list of physical pages to be mapped. -
      • -
    • - vaddr: The virtual address corresponding to the beginning of the (contiguous) virtual address region. -
      • -
    -

    Returned Value:

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

    4.11.2 up_shmdt()

    -

    Function Prototype:

    -

      -#include <nuttx/arch.h>
-#ifdef CONFIG_MM_SHM
-int up_shmdt(uintptr_t vaddr, unsigned int npages);
-#endif
-
    -

    Description:

    -
      - Detach, i.e, unmap, on shared memory region from a user virtual address. -
    -

    Input Parameters:

    -
      -
    • - vaddr: The virtual address corresponding to the beginning of the (contiguous) virtual address region. -
      • -
    • - npages: T The number of pages to be unmapped. -
      • -
    -

    Returned Value:

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

    4.12 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: - It can copy .text from the large program in non-volatile media into RAM as needed to execute a huge program from the small RAM. - Design and porting issues for this feature are discussed in a separate document. - Please see the NuttX Demand Paging design document for further information. -

    - -

    4.13 LED Support

    - -

    - A board architecture may or may not have LEDs. - If the board does have LEDs, then most architectures provide similar LED support that is enabled when CONFIG_ARCH_LEDS - is selected in the NuttX configuration file. - This LED support is part of architecture-specific logic and is not managed by the core NuttX logic. - However, the support provided by each architecture is sufficiently similar that it can be documented here. -

    - -

    4.13.1 Header Files

    - -

    - LED-related definitions are provided in two header files: -

      -
    • - LED definitions are provided for each board in the board.h that resides - in the <board-name>/include/board.h file (which is also - linked to include/arch/board/board.h when the RTOS is configured). - Those definitions are discussed below. -
      • -
    • - The board-specific logic provides unique instances of the LED interfaces. - This is because the implementation of LED support may be very different - on different boards. - Prototypes for these board-specific implementations are, however, provided - in architecture-common header files. - That header file is usually at <arch-name>/src/common/up_internal.h, - but could be at other locations in particular architectures. - These prototypes are discussed below. -
      • -
    -

    - -

    4.13.2 LED Definitions

    - -

    - The implementation of LED support is very specific to a board architecture. - Some boards have several LEDS, others have only one or two. - Some have none. - Others LED matrices and show alphanumeric data, etc. - The NuttX logic does not refer to specific LEDS, rather, it refers to an event to be shown on the LEDS - in whatever manner is appropriate for the board; - the way that this event is presented depends upon the hardware available on the board. -

    -

    - The model used by NuttX is that the board can show 8 events defined as follows in <board-name>/include/board.h: -

    -
      -#define LED_STARTED       ??
-#define LED_HEAPALLOCATE  ??
-#define LED_IRQSENABLED   ??
-#define LED_STACKCREATED  ??
-#define LED_INIRQ         ??
-#define LED_SIGNAL        ??
-#define LED_ASSERTION     ??
-#define LED_PANIC         ??
-
    -

    - The specific value assigned to each pre-processor variable can be whatever makes the implementation easiest for the board logic. - The meaning associated with each definition is as follows: -

    -
      -
    • - LED_STARTED is the value that describes the setting of the LEDs when the LED logic is first initialized. - This LED value is set but never cleared. -
      • -
    • - LED_HEAPALLOCATE indicates that the NuttX heap has been configured. - This is an important place in the boot sequence because if the memory is configured wrong, it will probably crash leaving this LED setting. - This LED value is set but never cleared. -
      • -
    • - LED_IRQSENABLED indicates that interrupts have been enabled. - Again, during bring-up (or if there are hardware problems), it is very likely that the system may crash just when interrupts are enabled, leaving this setting on the LEDs. - This LED value is set but never cleared. -
      • -
    • - LED_STACKCREATED is set each time a new stack is created. - If set, it means that the system attempted to start at least one new thread. - This LED value is set but never cleared. -
      • -
    • - LED_INIRQ is set and cleared on entry and exit from each interrupt. - If interrupts are working okay, this LED will have a dull glow. -
      • -
    • - LED_SIGNAL is set and cleared on entry and exit from a signal handler. - Signal handlers are tricky so this is especially useful during bring-up or a new architecture. -
      • -
    • - LED_ASSERTION is set if an assertion occurs. -
      • -
    • - LED_PANIC will blink at around 1Hz if the system panics and hangs. -
      • -
    - -

    4.13.3 Common LED interfaces

    - -

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

    -
      -#ifdef CONFIG_ARCH_LEDS
-void board_autoled_initialize(void);
-void board_autoled_on(int led);
-void board_autoled_off(int led);
-#else
-# define board_autoled_initialize()
-# define board_autoled_on(led)
-# define board_autoled_off(led)
-#endif
-
    -

    - Where: -

    -

      -
    • -

      - void board_autoled_initialize(void) is called early in power-up initialization to initialize the LED hardware. -

      -
      - NOTE: In most architectures, board_autoled_initialize() is called from board-specific initialization logic. - But there are a few architectures where this initialization function is still called from common chip architecture logic. - This interface is not, however, a common board interface in any event. -
      -
      - WARNING: This interface name will eventually be removed; do not use it in new board ports. - New implementations should not use the naming convention for common board interfaces, but should instead use the naming conventions for microprocessor-specific interfaces or the board-specific interfaces (such as stm32_led_initialize()). -
      -
      • -
    • -

      - board_autoled_on(int led) is called to instantiate the LED presentation of the event. - The led argument is one of the definitions provided in <board-name>/include/board.h. -

      -
      • -

      -

    • - board_autoled_off(int ledis called to terminate the LED presentation of the event. - The led argument is one of the definitions provided in <board-name>/include/board.h. - Note that only LED_INIRQ, LED_SIGNAL, LED_ASSERTION, and LED_PANIC - indications are terminated. -

      -
      • -
    - -

    4.14 I/O Buffer Management

    - -NuttX supports generic I/O buffer management (IOB) logic. -This logic was originally added to support network I/O buffering, but has been generalized to meet buffering requirements by all device drivers. -At the time of this writing, IOBs are currently used not only be networking but also by logic in drivers/syslog and drivers/wireless. -NOTE that some of the wording in this section still reflects those legacy roots as a part of the networking subsystem. -This objectives of this feature are: - -
      -
    1. - Provide common I/O buffer management logic for all drivers, -
      2. -
    2. - Support I/O buffer allocation from both the tasking and interrupt level contexts. -
      3. -
    3. - Use a fixed amount of pre-allocated memory. -
      4. -
    4. - No costly, non-deterministic dynamic memory allocation. -
      5. -
    5. - When the fixed number of pre-allocated I/O buffers is exhausted, further attempts to allocate memory from tasking logic will cause the task to block and wait until a an I/O buffer to be freed. -
      6. -
    6. - Each I/O buffer should be small, but can be chained together to support buffering of larger thinks such as full size network packets. -
      7. -
    7. - Support throttling logic to prevent lower priority tasks from hogging all available I/O buffering. -
      8. -
    - -

    4.14.1 Configuration Options

    - -
    -
    CONFIG_MM_IOB -
    Enables generic I/O buffer support. This setting will build the common I/O buffer (IOB) support library. - -
    CONFIG_IOB_NBUFFERS -
    Number of pre-allocated I/O buffers. Each packet is represented by a series of small I/O buffers in a chain. This setting determines the number of preallocated I/O buffers available for packet data. - - The default value is setup for network support. The default is 8 buffers if neither TCP/UDP or write buffering is enabled (neither CONFIG_NET_TCP_WRITE_BUFFERS nor CONFIG_NET_TCP), 24 if only TCP/UDP is enabled, and 36 if both TCP/UDP and write buffering are enabled. - -
    CONFIG_IOB_BUFSIZE -
    Payload size of one I/O buffer. Each packet is represented by a series of small I/O buffers in a chain. This setting determines the data payload each preallocated I/O buffer. The default value is 196 bytes. - -
    CONFIG_IOB_NCHAINS -
    Number of pre-allocated I/O buffer chain heads. These tiny nodes are used as containers to support queueing of I/O buffer chains. This will limit the number of I/O transactions that can be in-flight at any give time. The default value of zero disables this features. - -
    These generic I/O buffer chain containers are not currently used by any logic in NuttX. That is because their other other specialized I/O buffer chain containers that also carry a payload of usage specific information. - - The default value is zero if nether TCP nor UDP is enabled (i.e., neither CONFIG_NET_TCP && !CONFIG_NET_UDP or eight if either is enabled. - -
    CONFIG_IOB_THROTTLE -
    I/O buffer throttle value. TCP write buffering and read-ahead buffer use the same pool of free I/O buffers. In order to prevent uncontrolled incoming TCP packets from hogging all of the available, pre-allocated I/O buffers, a throttling value is required. This throttle value assures that I/O buffers will be denied to the read-ahead logic before TCP writes are halted. - - The default 0 if neither TCP write buffering nor TCP read-ahead buffering is enabled. Otherwise, the default is 8. - -
    CONFIG_IOB_DEBUG -
    Force I/O buffer debug. This option will force debug output from I/O buffer logic. This is not normally something that would want to do but is convenient if you are debugging the I/O buffer logic and do not want to get overloaded with other un-related debug output. - - NOTE that this selection is not available if DEBUG features are not enabled (CONFIG_DEBUG_FEATURES) with IOBs are being used to syslog buffering logic (CONFIG_SYSLOG_BUFFER). -
    - -

    4.14.2 Throttling

    - - -An allocation throttle was added. I/O buffer allocation logic supports a throttle value originally for read-ahead buffering to prevent the read-ahead logic from consuming all available I/O buffers and blocking the write buffering logic. This throttle logic is only needed for networking only if both write buffering and read-ahead buffering are used. Of use of I/O buffering might have other motivations for throttling. - -

    4.14.3 Public Types

    - -

    - This structure represents one I/O buffer. A packet is contained by one or more I/O buffers in a chain. The io_pktlen is only valid for the I/O buffer at the head of the chain. -

    - -
    -struct iob_s
-{
-  /* Singly-link list support */
-
-  FAR struct iob_s *io_flink;
-
-  /* Payload */
-
-#if CONFIG_IOB_BUFSIZE < 256
-  uint8_t  io_len;      /* Length of the data in the entry */
-  uint8_t  io_offset;   /* Data begins at this offset */
-#else
-  uint16_t io_len;      /* Length of the data in the entry */
-  uint16_t io_offset;   /* Data begins at this offset */
-#endif
-  uint16_t io_pktlen;   /* Total length of the packet */
-
-  uint8_t  io_data[CONFIG_IOB_BUFSIZE];
-};
-
    - -

    - This container structure supports queuing of I/O buffer chains. This structure is intended only for internal use by the IOB module. -

    - -
    -#if CONFIG_IOB_NCHAINS > 0
-struct iob_qentry_s
-{
-  /* Singly-link list support */
-
-  FAR struct iob_qentry_s *qe_flink;
-
-  /* Payload -- Head of the I/O buffer chain */
-
-  FAR struct iob_s *qe_head;
-};
-#endif /* CONFIG_IOB_NCHAINS > 0 */
-
    - -

    - The I/O buffer queue head structure. -

    - -
    -#if CONFIG_IOB_NCHAINS > 0
-struct iob_queue_s
-{
-  /* Head of the I/O buffer chain list */
-
-  FAR struct iob_qentry_s *qh_head;
-  FAR struct iob_qentry_s *qh_tail;
-};
-#endif /* CONFIG_IOB_NCHAINS > 0 */
-
    - -

    4.14.4 Public Function Prototypes

    - - - -

    4.14.4.1 iob_initialize()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-void iob_initialize(void);
-
    - -

    Description. - Set up the I/O buffers for normal operations. -

    - -

    4.14.4.2 iob_alloc()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-FAR struct iob_s *iob_alloc(bool throttled);
-
    - -

    Description. - Allocate an I/O buffer by taking the buffer at the head of the free list. -

    - -

    4.14.4.3 iob_tryalloc()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-FAR struct iob_s *iob_tryalloc(bool throttled);
-
    - -

    Description. - Try to allocate an I/O buffer by taking the buffer at the head of the free list without waiting for a buffer to become free. -

    - -

    4.14.4.4 iob_free()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-FAR struct iob_s *iob_free(FAR struct iob_s *iob);
-
    - -

    Description. - Free the I/O buffer at the head of a buffer chain returning it to the free list. The link to the next I/O buffer in the chain is return. -

    - -

    4.14.4.5 iob_free_chain()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-void iob_free_chain(FAR struct iob_s *iob);
-
    - -

    Description. - Free an entire buffer chain, starting at the beginning of the I/O buffer chain -

    - -

    4.14.4.6 iob_add_queue()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-#if CONFIG_IOB_NCHAINS > 0
-int iob_add_queue(FAR struct iob_s *iob, FAR struct iob_queue_s *iobq);
-#endif /* CONFIG_IOB_NCHAINS > 0 */
-
    - -

    Description. - Add one I/O buffer chain to the end of a queue. May fail due to lack of resources. -

    - -

    4.14.4.7 iob_tryadd_queue()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-#if CONFIG_IOB_NCHAINS > 0
-int iob_tryadd_queue(FAR struct iob_s *iob, FAR struct iob_queue_s *iobq);
-#endif /* CONFIG_IOB_NCHAINS > 0 */
-
    - -

    Description. - Add one I/O buffer chain to the end of a queue without waiting for resources to become free. -

    - -

    4.14.4.8 iob_remove_queue()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-#if CONFIG_IOB_NCHAINS > 0
-FAR struct iob_s *iob_remove_queue(FAR struct iob_queue_s *iobq);
-#endif /* CONFIG_IOB_NCHAINS > 0 */
-
    - -

    Description. - Remove and return one I/O buffer chain from the head of a queue. -

    - -

    Returned Value. - Returns a reference to the I/O buffer chain at the head of the queue. -

    - -

    4.14.4.9 iob_peek_queue()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-#if CONFIG_IOB_NCHAINS > 0
-FAR struct iob_s *iob_peek_queue(FAR struct iob_queue_s *iobq);
-#endif
-
    - -

    Description. - Return a reference to the I/O buffer chain at the head of a queue. This is similar to iob_remove_queue except that the I/O buffer chain is in place at the head of the queue. The I/O buffer chain may safely be modified by the caller but must be removed from the queue before it can be freed. -

    - -

    Returned Value. - Returns a reference to the I/O buffer chain at the head of the queue. -

    - -

    4.14.4.10 iob_free_queue()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-#if CONFIG_IOB_NCHAINS > 0
-void iob_free_queue(FAR struct iob_queue_s *qhead);
-#endif /* CONFIG_IOB_NCHAINS > 0 */
-
    - -

    Description. - Free an entire queue of I/O buffer chains. -

    - -

    4.14.4.11 iob_copyin()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-int iob_copyin(FAR struct iob_s *iob, FAR const uint8_t *src,
-               unsigned int len, unsigned int offset, bool throttled);
-
    - -

    Description. - Copy data len bytes from a user buffer into the I/O buffer chain, starting at offset, extending the chain as necessary. -

    - -

    4.14.4.12 iob_trycopyin()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-int iob_trycopyin(FAR struct iob_s *iob, FAR const uint8_t *src,
-                  unsigned int len, unsigned int offset, bool throttled);
-
    - -

    Description. - Copy data len bytes from a user buffer into the I/O buffer chain, starting at offset, extending the chain as necessary BUT without waiting if buffers are not available. -

    - -

    4.14.4.13 iob_copyout()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-int iob_copyout(FAR uint8_t *dest, FAR const struct iob_s *iob,
-                unsigned int len, unsigned int offset);
-
    - -

    Description. - Copy data len bytes of data into the user buffer starting at offset in the I/O buffer, returning that actual number of bytes copied out. -

    - -

    4.14.4.14 iob_clone()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-int iob_clone(FAR struct iob_s *iob1, FAR struct iob_s *iob2, bool throttled);
-
    - -

    Description. - Duplicate (and pack) the data in iob1 in iob2. iob2 must be empty. -

    - -

    4.14.4.15 iob_concat()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-void iob_concat(FAR struct iob_s *iob1, FAR struct iob_s *iob2);
-
    - -

    Description. - Concatenate iob_s chain iob2 to iob1. -

    - -

    4.14.4.16 iob_trimhead()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-FAR struct iob_s *iob_trimhead(FAR struct iob_s *iob, unsigned int trimlen);
-
    - -

    Description. - Remove bytes from the beginning of an I/O chain. Emptied I/O buffers are freed and, hence, the beginning of the chain may change. -

    - -

    4.14.4.17 iob_trimhead_queue()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-#if CONFIG_IOB_NCHAINS > 0
-FAR struct iob_s *iob_trimhead_queue(FAR struct iob_queue_s *qhead,
-                                     unsigned int trimlen);
-#endif
-
    - -

    Description. - Remove bytes from the beginning of an I/O chain at the head of the queue. Emptied I/O buffers are freed and, hence, the head of the queue may change. -

    -

    - This function is just a wrapper around iob_trimhead() that assures that the iob at the head of queue is modified with the trimming operations. -

    - -

    Returned Value. - The new iob at the head of the queue is returned. -

    - -

    4.14.4.18 iob_trimtail()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-FAR struct iob_s *iob_trimtail(FAR struct iob_s *iob, unsigned int trimlen);
-
    - -

    Description. - Remove bytes from the end of an I/O chain. Emptied I/O buffers are freed NULL will be returned in the special case where the entry I/O buffer chain is freed. -

    - -

    4.14.4.19 iob_pack()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-FAR struct iob_s *iob_pack(FAR struct iob_s *iob);
-
    - -

    Description. - Pack all data in the I/O buffer chain so that the data offset is zero and all but the final buffer in the chain are filled. Any emptied buffers at the end of the chain are freed. -

    - -

    4.14.4.20 iob_contig()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-int iob_contig(FAR struct iob_s *iob, unsigned int len);
-
    - -

    Description. - Ensure that there is len bytes of contiguous space at the beginning of the I/O buffer chain starting at iob. -

    - -

    4.14.4.21 iob_dump()

    -

    Function Prototype: -

    -#include <nuttx/mm/iob.h>
-#ifdef CONFIG_DEBUG_FEATURES
-void iob_dump(FAR const char *msg, FAR struct iob_s *iob, unsigned int len,
-              unsigned int offset);
-#endif
-
    - -

    Description. - Dump the contents of a I/O buffer chain -

    - - - - - -
    -

    5.0 NuttX File System

    -
    - -

    Overview. - NuttX includes an optional, scalable file system. - This file-system may be omitted altogether; NuttX does not depend on the presence - of any file system. -

    - -

    Pseudo Root File System. - A simple in-memory, pseudo file system can be enabled by default. - This is an in-memory file system because it does not require any - storage medium or block driver support. - Rather, file system contents are generated on-the-fly as referenced via - standard file system operations (open, close, read, write, etc.). - In this sense, the file system is pseudo file system (in the - same sense that the Linux /proc file system is also - referred to as a pseudo file system). -

    - -

    - Any user supplied data or logic can be accessed via the pseudo-file system. - Built in support is provided for character and block drivers in the - /dev pseudo file system directory. -

    - -

    Mounted File Systems - The simple in-memory file system can be extended my mounting block - devices that provide access to true file systems backed up via some - mass storage device. - NuttX supports the standard mount() command that allows - a block driver to be bound to a mountpoint within the pseudo file system - and to a file system. - At present, NuttX supports the standard VFAT and ROMFS file systems, - a special, wear-leveling NuttX FLASH File System (NXFFS), - as well as a Network File System client (NFS version 3, UDP). -

    - -

    Comparison to Linux - From a programming perspective, the NuttX file system appears very similar - to a Linux file system. - However, there is a fundamental difference: - The NuttX root file system is a pseudo file system and true file systems may be - mounted in the pseudo file system. - In the typical Linux installation by comparison, the Linux root file system - is a true file system and pseudo file systems may be mounted in the true, - root file system. - The approach selected by NuttX is intended to support greater scalability - from the very tiny platform to the moderate platform. -

    - - - - - -
    -

    6.0 NuttX Device Drivers

    -
    - -

    - NuttX supports a variety of device drivers including: -

      -
    • Character Device Drivers,
      • -
    • Block Device Drivers, and
      • -
    • Other Specialized Drivers.
      • -
    - These different device driver types are discussed in the following paragraphs. - Note: device driver support depends on the in-memory, pseudo file system - that is enabled by default. -

    - -

    6.1 Character Device Drivers

    - -

    - Character device drivers have these properties: -

    -
      -
    • -

      - include/nuttx/fs/fs.h. - All structures and APIs needed to work with character drivers are provided in this header file. -

      -
      • -
    • -

      - struct file_operations. - Each character device driver must implement an instance of struct file_operations. - That structure defines a call table with the following methods: -

        -

        int open(FAR struct file *filep);
        - int close(FAR struct file *filep);
        - ssize_t read(FAR struct file *filep, FAR char *buffer, size_t buflen);
        - ssize_t write(FAR struct file *filep, FAR const char *buffer, size_t buflen);
        - off_t seek(FAR struct file *filep, off_t offset, int whence);
        - int ioctl(FAR struct file *filep, int cmd, unsigned long arg);
        - int poll(FAR struct file *filep, struct pollfd *fds, bool setup);

        -
      -

      -
      • -
    • -

      - int register_driver(const char *path, const struct file_operations *fops, mode_t mode, void *priv);. - Each character driver registers itself by calling register_driver(), passing it the - path where it will appear in the pseudo-file-system and it's - initialized instance of struct file_operations. -

      -
      • -
    • -

      - User Access. - After it has been registered, the character driver can be accessed by user code using the standard - driver operations including - open(), close(), read(), write(), etc. -

      -
      • -
    • -

      - Specialized Character Drivers. - Within the common character driver framework, there are different specific varieties of specialized character drivers. - The unique requirements of the underlying device hardware often mandates some customization of the character driver. - These customizations tend to take the form of: -

      -
        -
      • - Device-specific ioctl() commands used to performed specialized operations on the device. - These ioctl() will be documented in header files under include/nuttx that detail the specific device interface. -
        • -
      • - Specialized I/O formats. - Some devices will require that read() and/or write() operations use data conforming to a specific format, rather than a plain stream of bytes. - These specialized I/O formats will be documented in header files under include/nuttx that detail the specific device interface. - The typical representation of the I/O format will be a C structure definition. -
        • -
      -

      - The specialized character drivers support by NuttX are documented in the following paragraphs. -

      -
      • -
    • -

      - Examples: - drivers/dev_null.c, drivers/fifo.c, drivers/serial.c, etc. -

      -
      • -
    - -

    6.1.1 Serial Device Drivers

    - -
      -
    • -

      - include/nuttx/serial/serial.h. - All structures and APIs needed to work with serial drivers are provided in this header file. -

      -
      • -
    • -

      - struct uart_ops_s. - Each serial device driver must implement an instance of struct uart_ops_s. - That structure defines a call table with the following methods: -

        -

        int setup(FAR struct uart_dev_s *dev);
        - void shutdown(FAR struct uart_dev_s *dev);
        - int attach(FAR struct uart_dev_s *dev);
        - void detach(FAR struct uart_dev_s *dev);
        - int ioctl(FAR struct file *filep, int cmd, unsigned long arg);
        - int receive(FAR struct uart_dev_s *dev, unsigned int *status);
        - void rxint(FAR struct uart_dev_s *dev, bool enable);
        - bool rxavailable(FAR struct uart_dev_s *dev);
        - #ifdef CONFIG_SERIAL_IFLOWCONTROL
        - bool rxflowcontrol(FAR struct uart_dev_s *dev, unsigned int nbuffered, bool upper);
        - #endif
        - void send(FAR struct uart_dev_s *dev, int ch);
        - void txint(FAR struct uart_dev_s *dev, bool enable);
        - bool txready(FAR struct uart_dev_s *dev);
        - bool txempty(FAR struct uart_dev_s *dev);

        -
      -

      -
      • -
    • -

      - int uart_register(FAR const char *path, FAR uart_dev_t *dev);. - A serial driver may register itself by calling uart_register(), passing it the - path where it will appear in the pseudo-file-system and it's - initialized instance of struct uart_ops_s. - By convention, serial device drivers are registered at paths like /dev/ttyS0, /dev/ttyS1, etc. - See the uart_register() implementation in drivers/serial.c. -

      -
      • -
    • -

      - User Access. - Serial drivers are, ultimately, normal character drivers and are accessed as other character drivers. -

      -
      • -
    • -

      - Examples: - arch/arm/src/stm32/stm32_serial.c, arch/arm/src/lpc214x/lpc214x_serial.c, arch/z16/src/z16f/z16f_serial.c, etc. -

      -
      • -
    - -

    6.1.1 Touchscreen Device Drivers

    - -

    - NuttX supports a two-part touchscreen driver architecture. -

    -
      -
    1. - An "upper half", generic driver that provides the common touchscreen interface to application level code, and -
      2. -
    2. - A "lower half", platform-specific driver that implements the low-level touchscreen controls to implement the touchscreen functionality. -
      3. -
    -

    - Files supporting the touchscreen controller (TSC) driver can be found in the following locations: -

    -
      -
    • Interface Definition. - The header files for NuttX touchscreen drivers reside in the include/nuttx/include/input directory. - The interface between the touchscreen controller "upper half" and "lower half" drivers are not common, but vary from controller-to-controller. - Because of this, each touchscreen driver has its own unique header file that describes the "upper half"/"lower half" interface in that directory. - The application level interface to each touchscreen driver, on the other hand, is the same for each touchscreen driver and is described include/nuttx/include/input/touchscreen.h. - The touchscreen driver uses a standard character driver framework but read operations return specially formatted data. -
      • -
    • "Upper Half" Driver. - The controller-specific, "upper half" touchscreen drivers reside in the directory drivers/input. -
      • -
    • "Lower Half" Drivers. - Platform-specific touchscreen drivers reside in either: (1) The arch/<architecture>/src/<hardware> directory for the processor architectures that have build in touchscreen controllers or (2) the boards/<arch>/<chip>/<board>/src/ directory for boards that use an external touchscreen controller chip. -
      • -
    - -

    6.1.2 Analog (ADC/DAC) Drivers

    -

    - The NuttX analog drivers are split into two parts: -

    -
      -
    1. - An "upper half", generic driver that provides the common analog interface to application level code, and -
      2. -
    2. - A "lower half", platform-specific driver that implements the low-level controls to implement the analog functionality. -
      3. -
    -
      -
    • - General header files for the NuttX analog drivers reside in include/nuttx/analog/. - These header files includes both the application level interface to the analog driver as well as the interface between the "upper half" and "lower half" drivers. -
      • -
    • - Common analog logic and share-able analog drivers reside in the drivers/analog/. -
      • -
    • - Platform-specific drivers reside in arch/<architecture>/src/<hardware> directory for the specific processor <architecture> and for the specific <chip> analog peripheral devices. -
      • -
    - -

    6.1.3.1 ADC Drivers

    -
      -
    • - include/nuttx/analog/adc.h. - All structures and APIs needed to work with ADC drivers are provided in this header file. - This header file includes: -
        -
      1. - Structures and interface descriptions needed to develop a low-level, - architecture-specific, ADC driver. -
        2. -
      2. - To register the ADC driver with a common ADC character driver. -
        3. -
      3. - Interfaces needed for interfacing user programs with the common ADC character driver. -
        4. -
      -
      • -
    • - drivers/analog/adc.c. - The implementation of the common ADC character driver. -
      • -
    - -

    6.1.3.2 DAC Drivers

    -
      -
    • - include/nuttx/analog/dac.h. - All structures and APIs needed to work with DAC drivers are provided in this header file. - This header file includes: -
        -
      1. - Structures and interface descriptions needed to develop a low-level, - architecture-specific, DAC driver. -
        2. -
      2. - To register the DAC driver with a common DAC character driver. -
        3. -
      3. - Interfaces needed for interfacing user programs with the common DAC character driver. -
        4. -
      -
      • -
    • - drivers/analog/dac.c. - The implementation of the common DAC character driver. -
      • -
    - -

    6.1.4 PWM Drivers

    -

    - For the purposes of this driver, a PWM device is any device that generates periodic output pulses of controlled frequency and pulse width. - Such a device might be used, for example, to perform pulse-width modulated output or frequency/pulse-count modulated output - (such as might be needed to control a stepper motor). -

    -

    - The NuttX PWM driver is split into two parts: -

    -
      -
    1. - An "upper half", generic driver that provides the common PWM interface to application level code, and -
      2. -
    2. - A "lower half", platform-specific driver that implements the low-level timer controls to implement the PWM functionality. -
      3. -
    -

    - Files supporting PWM can be found in the following locations: -

    -
      -
    • Interface Definition. - The header file for the NuttX PWM driver reside at include/nuttx/timers/pwm.h. - This header file includes both the application level interface to the PWM driver as well as the interface between the "upper half" and "lower half" drivers. - The PWM module uses a standard character driver framework. - However, since the PWM driver is a devices control interface and not a data transfer interface, - the majority of the functionality available to the application is implemented in driver ioctl calls. -
      • -
    • "Upper Half" Driver. - The generic, "upper half" PWM driver resides at drivers/pwm.c. -
      • -
    • "Lower Half" Drivers. - Platform-specific PWM drivers reside in arch/<architecture>/src/<hardware> directory for the specific processor <architecture> and for the specific <chip> PWM peripheral devices. -
      • -
    - -

    6.1.5 CAN Drivers

    -

    - NuttX supports only a very low-level CAN driver. - This driver supports only the data exchange and does not include any high-level CAN protocol. - The NuttX CAN driver is split into two parts: -

    -
      -
    1. - An "upper half", generic driver that provides the common CAN interface to application level code, and -
      2. -
    2. - A "lower half", platform-specific driver that implements the low-level timer controls to implement the CAN functionality. -
      3. -
    -

    - Files supporting CAN can be found in the following locations: -

    -
      -
    • Interface Definition. - The header file for the NuttX CAN driver resides at include/nuttx/can/can.h. - This header file includes both the application level interface to the CAN driver as well as the interface between the "upper half" and "lower half" drivers. - The CAN module uses a standard character driver framework. -
      • -
    • "Upper Half" Driver. - The generic, "upper half" CAN driver resides at drivers/can.c. -
      • -
    • "Lower Half" Drivers. - Platform-specific CAN drivers reside in arch/<architecture>/src/<hardware> directory for the specific processor <architecture> and for the specific <chip> CAN peripheral devices. -
      • -
    -

    - Usage Note: - When reading from the CAN driver multiple messages may be returned, depending on (1) the size the returned can messages, and (2) the size of the buffer provided to receive CAN messages. - Never assume that a single message will be returned... if you do this, you will lose CAN data under conditions where your read buffer can hold more than one small message. - Below is an example about how you should think of the CAN read operation: -

    -
      -#define BUFLEN 128  /* Arbitrary size of the CAN RX buffer */
-
-FAR struct can_msg_s *msg;
-char rxbuffer[BUFLEN];
-ssize_t nread;
-int nbytes;
-int msglen
-int i;
-
-/* Read messages into the RX buffer */
-
-nread = read(fd, rxbuffer, BUFLEN);
-
-/* Check for read errors */
-...
-
-/* Process each message in the RX buffer */
-
-for (i = 0; i <= nread - CAN_MSGLEN(0); i += msglen)
-{
-  /* Get the next message from the RX buffer */
-
-  msg    = (FAR struct can_msg_s *)&rxbuffer[i];
-  nbytes = can_dlc2bytes(msg->cm_hdr.ch_dlc);
-  msglen = CAN_MSGLEN(nbytes);
-
-  DEBUGASSERT(i + msglen < BUFLEN);
-
-  /* Process the next CAN message */
-  ...
-}
-
    - -

    6.1.6 Quadrature Encoder Drivers

    -

    - NuttX supports a low-level, two-part Quadrature Encoder driver. -

    -
      -
    1. - An "upper half", generic driver that provides the common Quadrature Encoder interface to application level code, and -
      2. -
    2. - A "lower half", platform-specific driver that implements the low-level timer controls to implement the Quadrature Encoder functionality. -
      3. -
    -

    - Files supporting the Quadrature Encoder can be found in the following locations: -

    -
      -
    • Interface Definition. - The header file for the NuttX Quadrature Encoder driver reside at include/nuttx/sensors/qencoder.h. - This header file includes both the application level interface to the Quadrature Encoder driver as well as the interface between the "upper half" and "lower half" drivers. - The Quadrature Encoder module uses a standard character driver framework. -
      • -
    • "Upper Half" Driver. - The generic, "upper half" Quadrature Encoder driver resides at drivers/sensors/qencoder.c. -
      • -
    • "Lower Half" Drivers. - Platform-specific Quadrature Encoder drivers reside in arch/<architecture>/src/<hardware> directory for the specific processor <architecture> and for the specific <chip> Quadrature Encoder peripheral devices. -
      • -
    - -

    6.1.7 Timer Drivers

    -

    - NuttX supports a low-level, two-part timer driver. -

    -
      -
    1. - An "upper half", generic driver that provides the common timer interface to application level code, and -
      2. -
    2. - A "lower half", platform-specific driver that implements the low-level timer controls to implement the timer functionality. -
      3. -
    -

    - Files supporting the timer driver can be found in the following locations: -

    -
      -
    • Interface Definition. - The header file for the NuttX timer driver reside at include/nuttx/timers/timer.h. - This header file includes both the application level interface to the timer driver as well as the interface between the "upper half" and "lower half" drivers. - The timer driver uses a standard character driver framework. -
      • -
    • "Upper Half" Driver. - The generic, "upper half" timer driver resides at drivers/timers/timer.c. -
      • -
    • "Lower Half" Drivers. - Platform-specific timer drivers reside in arch/<architecture>/src/<hardware> directory for the specific processor <architecture> and for the specific <chip> timer peripheral devices. -
      • -
    - -

    6.1.8 RTC Drivers

    -

    - NuttX supports a low-level, two-part RealTime Clock (RTC) driver. -

    -
      -
    1. - An "upper half", generic driver that provides the common RTC interface to application level code, and -
      2. -
    2. - A "lower half", platform-specific driver that implements the low-level timer controls to implement the RTC functionality. -
      3. -
    -

    - Files supporting the RTC driver can be found in the following locations: -

    -
      -
    • Interface Definition. - The header file for the NuttX RTC driver reside at include/nuttx/timers/rtc.h. - This header file includes both the application level interface to the RTC driver as well as the interface between the "upper half" and "lower half" drivers. - The RTC driver uses a standard character driver framework. -
      • -
    • "Upper Half" Driver. - The generic, "upper half" RTC driver resides at drivers/timers/rtc.c. -
      • -
    • "Lower Half" Drivers. - Platform-specific RTC drivers reside in arch/<architecture>/src/<hardware> directory for the specific processor <architecture> and for the specific <chip> RTC peripheral devices. -
      • -
    - -

    6.1.9 Watchdog Timer Drivers

    -

    - NuttX supports a low-level, two-part watchdog timer driver. -

    -
      -
    1. - An "upper half", generic driver that provides the common watchdog timer interface to application level code, and -
      2. -
    2. - A "lower half", platform-specific driver that implements the low-level timer controls to implement the watchdog timer functionality. -
      3. -
    -

    - Files supporting the watchdog timer driver can be found in the following locations: -

    -
      -
    • Interface Definition. - The header file for the NuttX watchdog timer driver reside at include/nuttx/timers/watchdog.h. - This header file includes both the application level interface to the watchdog timer driver as well as the interface between the "upper half" and "lower half" drivers. - The watchdog timer driver uses a standard character driver framework. -
      • -
    • "Upper Half" Driver. - The generic, "upper half" watchdog timer driver resides at drivers/timers/watchdog.c. -
      • -
    • "Lower Half" Drivers. - Platform-specific watchdog timer drivers reside in arch/<architecture>/src/<hardware> directory for the specific processor <architecture> and for the specific <chip> watchdog timer peripheral devices. -
      • -
    - -

    6.1.10 Keyboard/Keypad Drivers

    -

    - Keypads vs. Keyboards - Keyboards and keypads are really the same devices for NuttX. - A keypad is thought of as simply a keyboard with fewer keys. -

    -

    - Special Commands. - In NuttX, a keyboard/keypad driver is simply a character driver that may have an (optional) encoding/decoding layer on the data returned by the character driver. - A keyboard may return simple text data (alphabetic, numeric, and punctuation) or control characters (enter, control-C, etc.) when a key is pressed. - We can think about this the "normal" keyboard data stream. - However, in addition, most keyboards support actions that cannot be represented as text or control data. - Such actions include things like cursor controls (home, up arrow, page down, etc.), editing functions (insert, delete, etc.), volume controls, (mute, volume up, etc.) and other special functions. - In this case, some special encoding may be required to multiplex the normal text data and special command key press data streams. -

    -

    - Key Press and Release Events - Sometimes the time that a key is released is needed by applications as well. - Thus, in addition to normal and special key press events, it may also be necessary to encode normal and special key release events. -

    -

    - Encoding/Decoding Layer. - An optional encoding/decoding layer can be used with the basic character driver to encode the keyboard events into the text data stream. - The function interfaces that comprise that encoding/decoding layer are defined in the header file include/nuttx/input/kbd_code.h. - These functions provide an matched set of (a) driver encoding interfaces, and (b) application decoding interfaces. -

    -
      -
    1. -

      - Driver Encoding Interfaces. - These are interfaces used by the keyboard/keypad driver to encode keyboard events and data. -

      -
        -
      • -

        - kbd_press() -

        -

        Function Prototype:

        - 
          -#include <nuttx/streams.h>
-#include <nuttx/input/kbd_codec.h>
-void kbd_press(int ch, FAR struct lib_outstream_s *stream);
-
        -

        Description:

        -
          - Indicates a normal key press event. - Put one byte of normal keyboard data into the output stream. -
        -

        Input Parameters:

        -
          -
        • - ch: The character to be added to the output stream. -
          • -
        • - stream: An instance of lib_outstream_s to perform the actual low-level put operation. -
          • -
        -

        Returned Value:

        -
          - None. -
        -
        • -
      • -

        - kbd_release() -

        -

        Function Prototype:

        - 
          -#include <nuttx/streams.h>
-#include <nuttx/input/kbd_codec.h>
-void kbd_release(uint8_t ch, FAR struct lib_outstream_s *stream);
-
        -

        Description:

        -
          - Encode the release of a normal key. -
        -

        Input Parameters:

        -
          -
        • - ch: The character associated with the key that was released. -
          • -
        • - stream: An instance of lib_outstream_s to perform the actual low-level put operation. -
          • -
        -

        Returned Value:

        -
          - None. -
        -
        • -
      • -

        - kbd_specpress() -

        -

        Function Prototype:

        - 
          -#include <nuttx/streams.h>
-#include <nuttx/input/kbd_codec.h>
-void kbd_specpress(enum kbd_keycode_e keycode, FAR struct lib_outstream_s *stream);
-
        -

        Description:

        -
          - Denotes a special key press event. - Put one special keyboard command into the output stream. -
        -

        Input Parameters:

        -
          -
        • - keycode: The command to be added to the output stream. - The enumeration enum kbd_keycode_e keycode identifies all commands known to the system. -
          • -
        • - stream: An instance of lib_outstream_s to perform the actual low-level put operation. -
          • -
        -

        Returned Value:

        -
          - None. -
        -
        • -
      • -

        - kbd_specrel() -

        -

        Function Prototype:

        - 
          -#include <nuttx/streams.h>
-#include <nuttx/input/kbd_codec.h>
-void kbd_specrel(enum kbd_keycode_e keycode, FAR struct lib_outstream_s *stream);
-
        -

        Description:

        -
          - Denotes a special key release event. - Put one special keyboard command into the output stream. -
        -

        Input Parameters:

        -
          -
        • - keycode: The command to be added to the output stream. - The enumeration enum kbd_keycode_e keycode identifies all commands known to the system. -
          • -
        • - stream: An instance of lib_outstream_s to perform the actual low-level put operation. -
          • -
        -

        Returned Value:

        -
          - None. -
        -
        • -
      -
      2. -
    2. -

      - Application Decoding Interfaces. - These are user interfaces to decode the values returned by the keyboard/keypad driver. -

      -
        -
      • -

        - kbd_decode() -

        -

        Function Prototype:

        - 
          -#include <nuttx/streams.h>
-#include <nuttx/input/kbd_codec.h>
-int kbd_decode(FAR struct lib_instream_s *stream, FAR struct kbd_getstate_s *state, FAR uint8_t *pch);
-
        -

        Description:

        -
          - Get one byte of data or special command from the driver provided input buffer. -
        -

        Input Parameters:

        -
          -
        • - stream: An instance of lib_instream_s to perform the actual low-level get operation. -
          • -
        • - pch: The location to save the returned value. - This may be either a normal, character code or a special command (i.e., a value from enum kbd_getstate_s. -
          • -
        • - state: A user provided buffer to support parsing. - This structure should be cleared the first time that kbd_decode() is called. -
          • -
        -

        Returned Value:

        -
          -
        • - KBD_PRESS (0): - Indicates the successful receipt of normal, keyboard data. - This corresponds to a keypress event. - The returned value in pch is a simple byte of text or control data. -
          • -
        • - KBD_RELEASE (1): - Indicates a key release event. - The returned value in pch is the byte of text or control data corresponding to the released key. -
          • -
        • - KBD_SPECPRESS (2): - Indicates the successful receipt of a special keyboard command. - The returned value in pch is a value from enum kbd_getstate_s. -
          • -
        • - KBD_SPECREL (3): - Indicates a special command key release event. - The returned value in pch is a value from enum kbd_getstate_s. -
          • -
        • - KBD_ERROR (EOF): - An error has getting the next character (reported by the stream). - Normally indicates the end of file. -
          • -
        -
        • -
      -
      3. -
    -

    - I/O Streams. - Notice the use of the abstract I/O streams in these interfaces. - These stream interfaces are defined in include/nuttx/streams.h. -

    - -

    6.2 Block Device Drivers

    - -

    - Block device drivers have these properties: -

    -
      -
    • -

      - include/nuttx/fs/fs.h. - All structures and APIs needed to work with block drivers are provided in this header file. -

      -
      • -
    • -

      - struct block_operations. - Each block device driver must implement an instance of struct block_operations. - That structure defines a call table with the following methods: -

        -

        int open(FAR struct inode *inode);
        - int close(FAR struct inode *inode);
        - ssize_t read(FAR struct inode *inode, FAR unsigned char *buffer, size_t start_sector, unsigned int nsectors);
        - ssize_t write(FAR struct inode *inode, FAR const unsigned char *buffer, size_t start_sector, unsigned int nsectors);
        - int geometry(FAR struct inode *inode, FAR struct geometry *geometry);
        - int ioctl(FAR struct inode *inode, int cmd, unsigned long arg);

        -
      -

      -
      • -
    • -

      - int register_blockdriver(const char *path, const struct block_operations *bops, mode_t mode, void *priv);. - Each block driver registers itself by calling register_blockdriver(), passing it the - path where it will appear in the pseudo-file-system and it's - initialized instance of struct block_operations. -

      -
      • -
    • -

      - User Access. - Users do not normally access block drivers directly, rather, they access block drivers - indirectly through the mount() API. - The mount() API binds a block driver instance with a file system and with a mountpoint. - Then the user may use the block driver to access the file system on the underlying media. - Example: See the cmd_mount() implementation in apps/nshlib/nsh_fscmds.c. -

      -
      • -
    • -

      - Accessing a Character Driver as a Block Device. - See the loop device at drivers/loop.c. - Example: See the cmd_losetup() implementation in apps/nshlib/nsh_fscmds.c. -

      -
      • -
    • -

      - Accessing a Block Driver as Character Device. - See the Block-to-Character (BCH) conversion logic in drivers/bch/. - Example: See the cmd_dd() implementation in apps/nshlib/nsh_ddcmd.c. -

      -
      • -
    • -

      - Examples. - drivers/loop.c, drivers/mmcsd/mmcsd_spi.c, drivers/ramdisk.c, etc. -

      -
      • -
    - -

    6.3 Specialized Device Drivers

    - -

    - All device drivers that are accessible to application logic are either: (1) Character device drivers that can be accessed via the standard driver operations (open(), close(), read(), write(), etc.), or (2) block drivers that can be accessing only as part of mounting a file system or other special use cases as described in the preceding paragraph. -

    -

    - In addition to this, there are also specialized "drivers" that can be used only within the OS logic itself and are not accessible to application logic. These specialized drivers are discussed in the following paragraphs. -

    - -

    6.3.1 Ethernet Device Drivers

    - -
      -
    • -

      - include/nuttx/net/netdev.h. - All structures and APIs needed to work with Ethernet drivers are provided in this header file. - The structure struct net_driver_s defines the interface and is passed to the network via netdev_register(). -

      -
      • -
    • -

      - int netdev_register(FAR struct net_driver_s *dev, enum net_lltype_e lltype);. - Each Ethernet driver registers itself by calling netdev_register(). -

      -
      • -
    • -

      - Examples: - drivers/net/dm90x0.c, arch/drivers/arm/src/c5471/c5471_ethernet.c, arch/z80/src/ez80/ez80_emac.c, etc. -

      -
      • -
    - -

    6.3.2 SPI Device Drivers

    - -
      -
    • -

      - include/nuttx/spi/spi.h. - All structures and APIs needed to work with SPI drivers are provided in this header file. -

      -
      • -
    • -

      - struct spi_ops_s. - Each SPI device driver must implement an instance of struct spi_ops_s. - That structure defines a call table with the following methods: -

        -

        void lock(FAR struct spi_dev_s *dev);

        -

        void select(FAR struct spi_dev_s *dev, uint32_t devid, bool selected);
        - uint32_t setfrequency(FAR struct spi_dev_s *dev, uint32_t frequency);
        - void setmode(FAR struct spi_dev_s *dev, enum spi_mode_e mode);
        - void setbits(FAR struct spi_dev_s *dev, int nbits);
        - uint8_t status(FAR struct spi_dev_s *dev, uint32_t devid);
        - uint32_t send(FAR struct spi_dev_s *dev, uint32_t wd);
        - void exchange(FAR struct spi_dev_s *dev, FAR const void *txbuffer, FAR void *rxbuffer, size_t nwords);
        -

        int registercallback(FAR struct spi_dev_s *dev, mediachange_t callback, void *arg);

        -
      -

      -
    • -

      - Binding SPI Drivers. - SPI drivers are not normally directly accessed by user code, but are usually bound to another, - higher level device driver. - See for example, int mmcsd_spislotinitialize(int minor, int slotno, FAR struct spi_dev_s *spi) in drivers/mmcsd/mmcsd_spi.c. - In general, the binding sequence is: -

      -

      -

        -
      1. Get an instance of struct spi_dev_s from the hardware-specific SPI device driver, and
        2. -
      2. Provide that instance to the initialization method of the higher level device driver.
        3. -
      -

      -
      • -
    • -

      - Examples: - drivers/loop.c, drivers/mmcsd/mmcsd_spi.c, drivers/ramdisk.c, etc. -

      -
      • -
    - -

    6.3.3 I2C Device Drivers

    - -
      -
    • -

      - include/nuttx/i2c/i2c.h. - All structures and APIs needed to work with I2C drivers are provided in this header file. -

      -
      • -
    • -

      - struct i2c_ops_s. - Each I2C device driver must implement an instance of struct i2c_ops_s. - That structure defines a call table with the following methods: -

        - int transfer(FAR struct i2c_master_s *dev, FAR struct i2c_msg_s *msgs, int count);

        -

        -
      -
    • -

      - Binding I2C Drivers. - I2C drivers are not normally directly accessed by user code, but are usually bound to another, - higher level device driver. - In general, the binding sequence is: -

      -

      -

        -
      1. Get an instance of struct i2c_master_s from the hardware-specific I2C device driver, and
        2. -
      2. Provide that instance to the initialization method of the higher level device driver.
        3. -
      -

      -
      • -
    • -

      - Examples: - arch/z80/src/ez80/ez80_i2c.c, arch/z80/src/z8/z8_i2c.c, etc. -

      -
      • -
    - -

    6.3.4 Frame Buffer Drivers

    - -
      -
    • -

      - include/nuttx/video/fb.h. - All structures and APIs needed to work with frame buffer drivers are provided in this header file. -

      -
      • -
    • -

      - struct fb_vtable_s. - Each frame buffer device driver must implement an instance of struct fb_vtable_s. - That structure defines a call table with the following methods: -

      -

      - Get information about the video controller configuration and the configuration of each color plane. -

      -
        -

        int (*getvideoinfo)(FAR struct fb_vtable_s *vtable, FAR struct fb_videoinfo_s *vinfo);
        - int (*getplaneinfo)(FAR struct fb_vtable_s *vtable, int planeno, FAR struct fb_planeinfo_s *pinfo);

        -
      -

      - The following are provided only if the video hardware supports RGB color mapping: -

      -
        -

        int (*getcmap)(FAR struct fb_vtable_s *vtable, FAR struct fb_cmap_s *cmap);
        - int (*putcmap)(FAR struct fb_vtable_s *vtable, FAR const struct fb_cmap_s *cmap);

        -
      -

      - The following are provided only if the video hardware supports a hardware cursor: -

      -
        -

        int (*getcursor)(FAR struct fb_vtable_s *vtable, FAR struct fb_cursorattrib_s *attrib);
        - int (*setcursor)(FAR struct fb_vtable_s *vtable, FAR struct fb_setcursor_s *settings);

        -
      -
      • -
    • -

      - Binding Frame Buffer Drivers. - Frame buffer drivers are not normally directly accessed by user code, but are usually bound to another, - higher level device driver. - In general, the binding sequence is: -

      -

      -

        -
      1. Get an instance of struct fb_vtable_s from the hardware-specific frame buffer device driver, and
        2. -
      2. Provide that instance to the initialization method of the higher level device driver.
        3. -
      -

      -
      • -
    • -

      - Examples: - arch/sim/src/up_framebuffer.c. - See also the usage of the frame buffer driver in the graphics/ directory. -

      -
      • -
    - -

    6.3.5 LCD Drivers

    - -
      -
    • -

      - include/nuttx/lcd/lcd.h. - Structures and APIs needed to work with LCD drivers are provided in this header file. - This header file also depends on some of the same definitions used for the frame buffer driver as provided in include/nuttx/video/fb.h. -

      -
      • -
    • -

      - struct lcd_dev_s. - Each LCD device driver must implement an instance of struct lcd_dev_s. - That structure defines a call table with the following methods: -

      -

      - Get information about the LCD video controller configuration and the configuration of each LCD color plane. -

      -
        -

        - int (*getvideoinfo)(FAR struct lcd_dev_s *dev, FAR struct fb_videoinfo_s *vinfo);
        - int (*getplaneinfo)(FAR struct lcd_dev_s *dev, unsigned int planeno, FAR struct lcd_planeinfo_s *pinfo); -

        -
      -

      - The following are provided only if the video hardware supports RGB color mapping: -

      -
        -

        - int (*getcmap)(FAR struct lcd_dev_s *dev, FAR struct fb_cmap_s *cmap);
        - int (*putcmap)(FAR struct lcd_dev_s *dev, FAR const struct fb_cmap_s *cmap); -

        -
      -

      - The following are provided only if the video hardware supports a hardware cursor: -

      -
        -

        - int (*getcursor)(FAR struct lcd_dev_s *dev, FAR struct fb_cursorattrib_s *attrib);
        - int (*setcursor)(FAR struct lcd_dev_s *dev, FAR struct fb_setcursor_s *settings) -

        -
      -

      - Get the LCD panel power status (0: full off - CONFIG_LCD_MAXPOWER: full on). - On backlit LCDs, this setting may correspond to the backlight setting. -

      -
        -

        - int (*getpower)(struct lcd_dev_s *dev); -

        -
      -

      - Enable/disable LCD panel power (0: full off - CONFIG_LCD_MAXPOWER: full on). - On backlit LCDs, this setting may correspond to the backlight setting. -

      -
        -

        - int (*setpower)(struct lcd_dev_s *dev, int power); -

        -
      -

      - Get the current contrast setting (0-CONFIG_LCD_MAXCONTRAST) */ -

      -
        -

        - int (*getcontrast)(struct lcd_dev_s *dev); -

        -
      -

      - Set LCD panel contrast (0-CONFIG_LCD_MAXCONTRAST) -

      -
        -

        - int (*setcontrast)(struct lcd_dev_s *dev, unsigned int contrast); -

        -
      -

      -
    • -

      - Binding LCD Drivers. - LCD drivers are not normally directly accessed by user code, but are usually bound to another, - higher level device driver. - In general, the binding sequence is: -

      -

      -

        -
      1. Get an instance of struct lcd_dev_s from the hardware-specific LCD device driver, and
        2. -
      2. Provide that instance to the initialization method of the higher level device driver.
        3. -
      -

      -
      • -
    • -

      - Examples: - drivers/lcd/p14201.c, boards/arm/sam34/sam3u-ek/src/up_lcd.c. - See also the usage of the LCD driver in the graphics/ directory. -

      -
      • -
    - -

    6.3.6 Memory Technology Device Drivers

    - -
      -
    • -

      - include/nuttx/mtd/mtd.h. - All structures and APIs needed to work with MTD drivers are provided in this header file. -

      -
      • -
    • -

      - struct mtd_dev_s. - Each MTD device driver must implement an instance of struct mtd_dev_s. - That structure defines a call table with the following methods: -

      -

      - Erase the specified erase blocks (units are erase blocks): -

      -
        -

        int (*erase)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks);

        -
      -

      - Read/write from the specified read/write blocks: -

      -
        -

        ssize_t (*bread)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks, FAR uint8_t *buffer);
        - ssize_t (*bwrite)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks, FAR const uint8_t *buffer);

        -
      -

      - Some devices may support byte oriented reads (optional). - Most MTD devices are inherently block oriented so byte-oriented accesses are not supported. - It is recommended that low-level drivers not support read() if it requires buffering. -

      -
        -

        ssize_t (*read)(FAR struct mtd_dev_s *dev, off_t offset, size_t nbytes, FAR uint8_t *buffer);

        -
      -

      - Some devices may also support byte oriented writes (optional). - Most MTD devices are inherently block oriented so byte-oriented accesses are not supported. - It is recommended that low-level drivers not support read() if it requires buffering. - This interface is only available if CONFIG_MTD_BYTE_WRITE is defined. -

      -
        -

        ssize_t (*write)(FAR struct mtd_dev_s *dev, off_t offset, size_t nbytes, FAR const uint8_t *buffer);

        -
      -

      - Support other, less frequently used commands: -

      -
        -
      • MTDIOC_GEOMETRY: Get MTD geometry
        • -
      • MTDIOC_XIPBASE:: Convert block to physical address for eXecute-In-Place
        • -
      • MTDIOC_BULKERASE: Erase the entire device
        • -
      -

      - is provided via a single ioctl method (see include/nuttx/fs/ioctl.h): -

      -
        -

        int (*ioctl)(FAR struct mtd_dev_s *dev, int cmd, unsigned long arg);

        -
      -
      • -
    • -

      - Binding MTD Drivers. - MTD drivers are not normally directly accessed by user code, but are usually bound to another, - higher level device driver. - In general, the binding sequence is: -

      -

      -

        -
      1. Get an instance of struct mtd_dev_s from the hardware-specific MTD device driver, and
        2. -
      2. Provide that instance to the initialization method of the higher level device driver.
        3. -
      -

      -
      • -
    • -

      - Examples: - drivers/mtd/m25px.c and drivers/mtd/ftl.c -

      -
      • -
    - -

    6.3.7 SDIO Device Drivers

    - -
      -
    • -

      - include/nuttx/sdio.h. - All structures and APIs needed to work with SDIO drivers are provided in this header file. -

      -
      • -
    • -

      - struct sdio_dev_s. - Each SDIO device driver must implement an instance of struct sdio_dev_s. - That structure defines a call table with the following methods: -

      -

      - Mutual exclusion: -

      -
        -

        - #ifdef CONFIG_SDIO_MUXBUS
        - int (*lock)(FAR struct sdio_dev_s *dev, bool lock);
        - #endif -

        -
      -

      - Initialization/setup: -

      -
        -

        void (*reset)(FAR struct sdio_dev_s *dev);
        - sdio_capset_t (*capabilities)(FAR struct sdio_dev_s *dev);
        - sdio_statset_t (*status)(FAR struct sdio_dev_s *dev);
        - void (*widebus)(FAR struct sdio_dev_s *dev, bool enable);
        - void (*clock)(FAR struct sdio_dev_s *dev, enum sdio_clock_e rate);
        - int (*attach)(FAR struct sdio_dev_s *dev);
        -

      -

      - Command/Status/Data Transfer: -

      -
        -

        int (*sendcmd)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t arg);
        - int (*recvsetup)(FAR struct sdio_dev_s *dev, FAR uint8_t *buffer, size_t nbytes);
        - int (*sendsetup)(FAR struct sdio_dev_s *dev, FAR const uint8_t *buffer, size_t nbytes);
        - int (*cancel)(FAR struct sdio_dev_s *dev);
        - int (*waitresponse)(FAR struct sdio_dev_s *dev, uint32_t cmd);
        - int (*recv_r1)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R1);
        - int (*recv_r2)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t R2[4]);
        - int (*recv_r3)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R3);
        - int (*recv_r4)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R4);
        - int (*recv_r5)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R5);
        - int (*recv_r6)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R6);
        - int (*recv_r7)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R7);

        -
      -

      - Event/Callback support: -

      -
        -

        void (*waitenable)(FAR struct sdio_dev_s *dev, sdio_eventset_t eventset);
        - sdio_eventset_t (*eventwait)(FAR struct sdio_dev_s *dev, uint32_t timeout);
        - void (*callbackenable)(FAR struct sdio_dev_s *dev, sdio_eventset_t eventset);
        - int (*registercallback)(FAR struct sdio_dev_s *dev, worker_t callback, void *arg);

        -
      -

      - DMA support: -

      -
        - int (*dmarecvsetup)(FAR struct sdio_dev_s *dev, FAR uint8_t *buffer, size_t buflen);
        - int (*dmasendsetup)(FAR struct sdio_dev_s *dev, FAR const uint8_t *buffer, size_t buflen);

        -
      -
      • -
    • -

      - Binding SDIO Drivers. - SDIO drivers are not normally directly accessed by user code, but are usually bound to another, - higher level device driver. - In general, the binding sequence is: -

      -

      -

        -
      1. Get an instance of struct sdio_dev_s from the hardware-specific SDIO device driver, and
        2. -
      2. Provide that instance to the initialization method of the higher level device driver.
        3. -
      -

      -
      • -
    • -

      - Examples: - arch/arm/src/stm32/stm32_sdio.c and drivers/mmcsd/mmcsd_sdio.c -

      -
      • -
    - -

    6.3.8 USB Host-Side Drivers

    - -
      -
    • -

      - include/nuttx/usb/usbhost.h. - All structures and APIs needed to work with USB host-side drivers are provided in this header file. -

      -
      • -
    • -

      - struct usbhost_driver_s and struct usbhost_connection_s. - Each USB host controller driver must implement an instance of struct usbhost_driver_s and struct usbhost_connection_s: - struct usbhost_driver_s provides the interface between the USB host driver and the USB class driver; - struct usbhost_connection_s provides the interface between the USB host driver and platform-specific connection management and device enumeration logic. - These structures are defined in include/nuttx/usb/usbhost.h. -

      -

      - Examples: - arch/arm/src/lpc17xx_40xx/lpc17_40_usbhost.c, - arch/arm/src/stm32/stm32_otgfshost.c, - arch/arm/src/sama5/sam_ohci.c, and - arch/arm/src/sama5/sam_ehci.c. -

      -
      • -
    • -

      - struct usbhost_class_s. - Each USB host class driver must implement an instance of struct usbhost_class_s. - This structure is also defined in include/nuttx/usb/usbhost.h. -

      -

      - Examples: - drivers/usbhost/usbhost_storage.c -

      -
      • -
    • -

      - USB Host Class Driver Registry. - The NuttX USB host infrastructure includes a registry. - During its initialization, each USB host class driver must call the interface, usbhost_registerclass() - in order add its interface to the registry. - Later, when a USB device is connected, the USB host controller will look up the USB host class driver that is needed to support the connected device in this registry. -

      -

      - Examples: - drivers/usbhost/usbhost_registry.c, drivers/usbhost/usbhost_registerclass.c, and drivers/usbhost/usbhost_findclass.c, -

      -
      • -
    • -

      - Detection and Enumeration of Connected Devices. - Each USB host device controller supports two methods that are used to detect and enumeration newly connected devices - (and also detect disconnected devices): -

      -

      -

        -
      • -

        - int (*wait)(FAR struct usbhost_connection_s *drvr, FAR const bool *connected); -

        -

        - Wait for a device to be connected or disconnected. -

        -
        • -
      • -

        - int (*enumerate)(FAR struct usbhost_connection_s *drvr, int rhpndx); -

        -

        - Enumerate the device connected to a root hub port. - As part of this enumeration process, the driver will - (1) get the device's configuration descriptor, - (2) extract the class ID info from the configuration descriptor, - (3) call usbhost_findclass() to find the class that supports this device, - (4) call the create() method on the struct usbhost_registry_s interface to get a class instance, and - finally (5) call the connect() method of the struct usbhost_class_s interface. - After that, the class is in charge of the sequence of operations. -

        -
      -

      -
      • -
    • -

      - Binding USB Host-Side Drivers. - USB host-side controller drivers are not normally directly accessed by user code, - but are usually bound to another, higher level USB host class driver. - The class driver exports the standard NuttX device interface so that the connected USB device can be accessed just as with other, similar, on-board devices. - For example, the USB host mass storage class driver (drivers/usbhost/usbhost_storage.c) will register a standard, NuttX block driver interface (like /dev/sda) - that can be used to mount a file system just as with any other other block driver instance. - In general, the binding sequence is: -

      -

      -

        -
      1. -

        - Each USB host class driver includes an initialization entry point that is called from the - application at initialization time. - This driver calls usbhost_registerclass() during this initialization in order to makes itself available in the event the device that it supports is connected. -

        -

        - Examples: - The function usbhost_msc_initialize() in the file drivers/usbhost/usbhost_storage.c -

        -
        2. -
      2. -

        - Each application must include a waiter thread thread that (1) calls the USB host controller driver's wait() to detect the connection of a device, and then - (2) call the USB host controller driver's enumerate method to bind the registered USB host class driver to the USB host controller driver. -

        -

        - Examples: - The function nsh_waiter() in the file boards/arm/lpc17xx_40xx/olimex-lpc1766stk/src/lpc17_40_appinit.c. -

        -
        3. -
      3. -

        - As part of its operation during the binding operation, the USB host class driver will register an instances of a standard NuttX driver under the /dev directory. - To repeat the above example, the USB host mass storage class driver (drivers/usbhost/usbhost_storage.c) will register a standard, NuttX block driver interface (like /dev/sda) - that can be used to mount a file system just as with any other other block driver instance. -

        -

        - Examples: - See the call to register_blockdriver() in the function usbhost_initvolume() in the file drivers/usbhost/usbhost_storage.c. -

        -
        4. -
      -

      -
      • -
    - -

    6.3.9 USB Device-Side Drivers

    - -
      -
    • -

      - include/nuttx/usb/usbdev.h. - All structures and APIs needed to work with USB device-side drivers are provided in this header file. -

      -
      • -
    • -

      - include/nuttx/usb/usbdev_trace.h. - Declarations needed to work with the NuttX USB device driver trace capability. - That USB trace capability is detailed in separate document. -

      -
      • -
    • -

      - struct usbdev_s. - Each USB device controller driver must implement an instance of struct usbdev_s. - This structure is defined in include/nuttx/usb/usbdev.h. -

      -

      - Examples: - arch/arm/src/dm320/dm320_usbdev.c, arch/arm/src/lpc17xx_40xx/lpc17_40_usbdev.c, - arch/arm/src/lpc214x/lpc214x_usbdev.c, arch/arm/src/lpc313x/lpc313x_usbdev.c, and - arch/arm/src/stm32/stm32_usbdev.c. -

      -
      • -
    • -

      - struct usbdevclass_driver_s. - Each USB device class driver must implement an instance of struct usbdevclass_driver_s. - This structure is also defined in include/nuttx/usb/usbdev.h. -

      -

      - Examples: - drivers/usbdev/pl2303.c and drivers/usbdev/usbmsc.c -

      -
      • -
    • -

      - Binding USB Device-Side Drivers. - USB device-side controller drivers are not normally directly accessed by user code, - but are usually bound to another, higher level USB device class driver. - The class driver is then configured to export the USB device functionality. - In general, the binding sequence is: -

      -

      -

        -
      1. -

        - Each USB device class driver includes an initialization entry point that is called from the - application at initialization time. -

        -

        - Examples: - The function usbdev_serialinitialize() in the file drivers/usbdev/pl2303.c and - the function in the file drivers/usbdev/usbmsc.c -

        -
        2. -
      2. -

        - These initialization functions called the driver API, usbdev_register(). - This driver function will bind the USB class driver to the USB device controller driver, - completing the initialization. -

        -
        3. -
      -

      -
      • -
    - -

    6.3.10 SocketCAN Device Drivers

    - -
      -
    • -

      - include/nuttx/net/netdev.h. - All structures and APIs needed to work with drivers are provided in this header file. The structure struct net_driver_s defines the interface and is passed to the network via netdev_register(). -

      -
      • -
    • -

      - include/nuttx/can.h. - CAN & CAN FD frame data structures. -

      -
      • -
    • -

      - int netdev_register(FAR struct net_driver_s *dev, enum net_lltype_e lltype)'. - Each driver registers itself by calling netdev_register(). -

      -
      • -
    • -

      - Include/nuttx/net/can.h. - contains lookup tables for CAN dlc to CAN FD len sizes named -

      - - extern const uint8_t can_dlc_to_len[16]; -
      - - extern const uint8_t len_to_can_dlc[65]; - -
      • -
    • -

      - Initialization sequence is as follows. -

        -
      1. up_netinitialize(void) is called on startup of NuttX in this function you call your own init function to initialize your CAN driver
        2. -
      2. In your own init function you create the net_driver_s structure set required init values and register the required callbacks for SocketCAN
        3. -
      3. Then you ensure that the CAN interface is in down mode (usually done by calling the d_ifdown function)
        4. -
      4. Register the net_driver_s using netdev_register
        5. -
      -

      -
      • -
    • -

      - Receive sequence is as follows. -

        -
      1. Device generates interrupt
        2. -
      2. Process this interrupt in your interrupt handler
        3. -
      3. When a new CAN frame has been received you process this frame
        4. -
      4. When the CAN frame is a normal CAN frame you allocate the can_frame struct, when it's a CAN FD frame you allocate a canfd_frame struct (note you can of course preallocate and just use the pointer).
        5. -
      5. Copy the frame from the driver to the struct you've allocated in the previous step.
        6. -
      6. Point the net_driver_s d_buf pointer to the allocated can_frame
        7. -
      7. Call the can_input(FAR struct net_driver_s *dev) function include/nuttx/net/can.h
        8. -
      -

      -
      • -
    • -

      - Transmit sequence is as follows. -

        -
      1. Socket layer executes d_txavail callback
        2. -
      2. An example of the txavail function can be found in arch/arm/src/s32k1xx/s32k1xx_flexcan.c
        3. -
      3. An example of the txpoll function can be found in arch/arm/src/s32k1xx/s32k1xx_flexcan.c
        4. -
      4. In your transmit(struct driver_s *priv) function you check the length of net_driver_s.d_len whether it matches the size of a struct can_frame or struct canfd_frame then you cast the content of the net_driver_s.d_buf pointer to the correct CAN frame struct
        5. -
      -

      -
      • -
    - -

    6.4 SYSLOG

    - -

    6.4.1 SYSLOG Interfaces

    -

    6.4.1.1 Standard SYSLOG Interfaces

    - - The NuttX SYSLOG is an architecture for getting debug and status - information from the system. The syslogging interfaces are defined in the - header file include/syslog.h. The primary interface to SYSLOG sub-system - is the function syslog() and, to a lesser extent, its companion vsyslog(): - -

    6.4.1.2 syslog() and vsyslog()

    -

    Function Prototypes:

    -
      -#include <syslog.h>
-int syslog(int priority, FAR const IPTR char *format, ...);
-void vsyslog(int priority, FAR const IPTR char *src, va_list ap);
-
    -

    Description: - syslog() generates a log message. The priority argument is formed by ORing the facility and the level values (see include/syslog.h). The remaining arguments are a format, as in printf() and any arguments to the format. -

    -

    - The NuttX implementation does not support any special formatting characters beyond those supported by printf(). -

    -

    - The function vsyslog() performs the same task as syslog() with the difference that it takes a set of arguments which have been obtained using the stdarg variable argument list macros. -

    - -

    6.4.1.3 setlogmask()

    -

    - The additional setlogmask() interface can use use to filter SYSLOG output: -

    -

    Function Prototype:

    -
      -#include <syslog.h>
-int setlogmask(int mask);
-
    -

    Description: - The setlogmask() function sets the logmask and returns the previous mask. If the mask argument is zerio, the current logmask is not modified. -

    -

    - The SYSLOG priorities are: LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, and LOG_DEBUG. The bit corresponding to a priority p is LOG_MASK(p); LOG_UPTO(p) provides the mask of all priorities in the above list up to and including p. -

    -

    - Per OpenGroup.org "If the maskpri argument is 0, the current log mask is not modified." In this implementation, the value zero is permitted in order to disable all SYSLOG levels. -

    -

    - REVISIT: Per POSIX the SYSLOG mask should be a per-process value but in NuttX, the scope of the mask is dependent on the nature of the build: -

    -
      - -
    • -

      - Flat Build: There is one, global SYSLOG mask that controls all output. -

      • -
    • -

      - Protected Build: There are two SYSLOG masks. One within the kernel that controls only kernel output. And one in user-space that controls only user SYSLOG output. -

      • -
    • -

      - Kernel Build: The kernel build is compliant with the POSIX requirement: There will be one mask for for each user process, controlling the SYSLOG output only form that process. There will be a separate mask accessible only in the kernel code to control kernel SYSLOG output. -

    -

    - The above are all standard interfaces as defined at OpenGroup.org. Those interfaces are available for use by application software. The remaining interfaces discussed in this section are non-standard, OS-internal interfaces. -

    - -

    6.4.1.4 Debug Interfaces

    -

    - In NuttX, syslog output is really synonymous to debug output and, therefore, the debugging interface macros defined in the header file - include/debug.h are also syslogging interfaces. Those macros are simply wrappers around syslog(). The debugging interfaces differ from the syslog interfaces in that: -

    -
      - -
    • -

      - They do not take a priority parameter; the priority is inherent in the - debug macro name. -

      • -
    • -

      - They decorate the output stream with information such as the file name -

      • -
    • -

      - They can each be disabled via configuration options. -

      • -
    -

    - Each debug macro has a base name that represents the priority and a prefix that represents the sub-system. Each macro is individually initialized by both priority and sub-system. For example, uerr() is the macro used for error level messages from the USB subsystem and is enabled with CONFIG_DEBUG_USB_ERROR. -

    -

    - The base debug macro names, their priority, and configuration variable are summarized below: -

    -
      - -
    • -

      - info(). The info() macro is the lowest priority (LOG_INFO) and is intended to provide general information about the flow of program execution so that you can get an overview of the behavior of the program. info() is often very chatty and voluminous and usually more information than you may want to see. The info() macro is controlled via CONFIG_DEBUG_subsystem_INFO -

      • -
    • -

      - warn(). The warn() macro has medium priority (LOG_WARN) and is controlled by CONFIG_DEBUG_subsystem_WARN. The warn() is intended to - note exceptional or unexpected conditions that might be potential - errors or, perhaps, minor errors that easily recovered. -

      • -
    • -

      - err(). This is a high priority debug macro (LOG_ERROR) and controlled by CONFIG_DEBUG_subsystem_ERROR. The err() is reserved to indicate important error conditions. -

      • -
    • -

      - alert(). The highest priority debug macro (LOG_EMERG) and is controlled by CONFIG_DEBUG_ALERT. The alert() macro is reserved for use solely by assertion and crash handling logic. It also differs from the other macros in that it cannot be enabled or disabled per subsystem. -

      • -
    - -

    6.4.2 SYSLOG Channels

    -

    6.4.2.1 SYSLOG Channel Interfaces

    -

    - In the NuttX SYSLOG implementation, the underlying device logic the supports the SYSLOG output is referred to as a SYSLOG channel. Each SYSLOG channel is represented by an interface defined in include/nuttx/syslog/syslog.h: -

    -
      -    /* This structure provides the interface to a SYSLOG device */
-
-    typedef CODE int (*syslog_putc_t)(int ch);
-    typedef CODE int (*syslog_flush_t)(void);
-
-    struct syslog_channel_s
-    {
-      /* I/O redirection methods */
-
-      syslog_putc_t sc_putc;    /* Normal buffered output */
-      syslog_putc_t sc_force;   /* Low-level output for interrupt handlers */
-      syslog_flush_t sc_flush;  /* Flush buffered output (on crash) */
-
-      /* Implementation specific logic may follow */
-    };
-
    -

    - The channel interface is instantiated by calling syslog_channel(): -

    - -

    6.4.2.1 syslog_channel()

    -

    Function Prototype:

    -
      -#include <nuttx/syslog/syslog.h>
-int syslog_channel(FAR const struct syslog_channel_s *channel);
-
    -

    Description: - Configure the SYSLOG function to use the provided channel to generate SYSLOG output. -

    -

    - syslog_channel() is a non-standard, internal OS interface and is not available to applications. It may be called numerous times as necessary to change channel interfaces. - By default, all system log output goes to console (/dev/console). -

    -

    Input Parameters: -

      -
    • -

      - channel: Describes the interface to the channel to be used. -

      • -
    -

    Returned Value: -

      -

      - Zero (OK)is returned on success. A negated errno value is returned on any failure. -

      -
    - -

    6.4.2.2 SYSLOG Channel Initialization

    -

    - The initial, default SYSLOG channel is established with statically initialized global variables so that some level of SYSLOG output may be available immediately upon reset. This initialized data is in the file drivers/syslog/syslog_channel.c. The initial SYSLOG capability is determined by the selected SYSLOG channel: -

    -
      -
    • -

      - In-Memory Buffer (RAMLOG). Full SYSLOG capability as available at reset. -

      • -
    • -

      - Serial Console. If the serial implementation provides the low-level character output function up_putc(), then that low level serial output is available as soon as the serial device has been configured. -

      • -
    • -

      - For all other SYSLOG channels, all SYSLOG output goes to the bit- - bucket until the SYSLOG channel device has been initialized. -

      • -
    -

    - The syslog channel device is initialized when the bring-up logic calls syslog_initialize(): -

    - -

    6.4.2.3 syslog_initialize()

    -

    Function Prototype:

    -
      -#include <nuttx/syslog/syslog.h>
-#ifndef CONFIG_ARCH_SYSLOG
-int syslog_initialize(void);
-#else
-#  define syslog_initialize()
-#endif
-
    -

    Description: - One power up, the SYSLOG facility is non-existent or limited to very low-level output. This function is called later in the initialization sequence after full driver support has been initialized. It installs the configured SYSLOG drivers and enables full SYSLOG capability. -

    -

    - This function performs these basic operations: -

    -
      -
    • -

      - Initialize the SYSLOG device -

      • -
    • -

      - Call syslog_channel() to begin using that device. -

      • -
    • -

      - If CONFIG_ARCH_SYSLOG is selected, then the architecture-specific logic will provide its own SYSLOG device initialize which must include as a minimum a call to syslog_channel() to use the device. -

      • -
    -

    Returned Value: - Zero (OK) is returned on success; a negated errno value is returned on any failure. -

    -

    - Different types of SYSLOG devices have different OS initialization - requirements. Some are available immediately at reset, some are available - after some basic OS initialization, and some only after OS is fully - initialized. -

    -

    - There are other types of SYSLOG channel devices that may require even further initialization. For example, the file SYSLOG channel (described below) cannot be initialized until the necessary file systems have been mounted. -

    - -

    6.4.2.3 Interrupt Level SYSLOG Output

    -

    - As a general statement, SYSLOG output only supports //normal// output from NuttX tasks. However, for debugging purposes, it is also useful to get SYSLOG output from interrupt level logic. In an embedded system, that is often where the most critical operations are performed. -

    -

    - There are three conditions under which SYSLOG output generated from interrupt level processing can a included the SYSLOG output stream: -

    -
      -
    1. -

      Low-Level Serial Output. - If you are using a SYSLOG console channel (CONFIG_SYSLOG_CONSOLE) and if the underlying architecture supports the low-level up_putc() interface(CONFIG_ARCH_LOWPUTC), then the SYSLOG logic will direct the output to up_putc() which is capable of generating the serial output within the context of an interrupt handler. -

      -

      - There are a few issues in doing this however: -

      -
        -
      • -

        - up_putc() is able to generate debug output in any context because it disables serial interrupts and polls the hardware directly. These polls may take many milliseconds and during that time, all interrupts are disable within the interrupt handler. This, of course, interferes with the real-time behavior of the RTOS. -

        -
        • -
      • -

        - The output generated by up_putc() is immediate and in real-time. The normal SYSLOG output, on the other hand, is buffered in the serial driver and may be delayed with respect to the immediate output by many lines. Therefore, the interrupt level SYSLOG output provided through up_putc() is grossly out of synchronization with other debug output -

        -
        • -
      - -
      2. -
    2. -

      In-Memory Buffering. - If the RAMLOG SYSLOG channel is supported, then all SYSLOG output is buffered in memory. Interrupt level SYSLOG output is no different than normal SYSLOG output in this case. -

      -
      3. -
    3. -

      Serialization Buffer. - A final option is the use of an interrupt buffer to buffer the interrupt level SYSLOG output. In this case: -

      -
        -
      • -

        - SYSLOG output generated from interrupt level process in not sent to the SYSLOG channel immediately. Rather, it is buffered in the interrupt serialization buffer. -

        -
        • -
      • -

        - Later, when the next normal syslog output is generated, it will first empty the content of the interrupt buffer to the SYSLOG device in the proper context. It will then be followed by the normal syslog output. In this case, the interrupt level SYSLOG output will interrupt the normal output stream and the interrupt level SYSLOG output will be inserted into the correct position in the SYSLOG output when the next normal SYSLOG output is generated. -

        -
        • -
      -

      - The SYSLOG interrupt buffer is enabled with CONFIG_SYSLOG_INTBUFFER. When the interrupt buffer is enabled, you must also provide the size of the interrupt buffer with CONFIG_SYSLOG_INTBUFSIZE. -

      -
      4. -
    - -

    6.4.3 SYSLOG Channel Options

    -

    6.4.3.1 SYSLOG Console Device

    -

    - The typical SYSLOG device is the system console. If you are using a serial console, for example, then the SYSLOG output will appear on that serial port. -

    -

    - This SYSLOG channel is automatically selected by syslog_initialize() in the LATE initialization phase based on configuration options. The configuration options that affect this channel selection include: -

    -
      -
    • -

      - CONFIG_DEV_CONSOLE. This setting indicates that the system supports a console device, i.e., that the character device /dev/console exists. -

      • -
    • -

      - CONFIG_SERIAL_CONSOLE. This configuration option is automatically selected when a UART or USART is configured as the system console. There is no user selection. -

      • -
    • -

      - CONFIG_SYSLOG_CONSOLE. This configuration option is manually selected from the SYSLOG menu. This is the option that actually enables the SYSLOG console device. It depends on CONFIG_DEV_CONSOLE. -

      • -
    • -

      - CONFIG_ARCH_LOWPUTC. This is an indication from the architecture configuration that the platform supports the up_putc() interface. up_putc() is a very low level UART interface that can even be used from interrupt handling. -

      • -
    -

    - Interrupt level SYSLOG output will be lost unless: (1) the interrupt buffer - is enabled to support serialization, or (2) a serial console is used and - up_putc() is supported. -

    -

    - NOTE: The console channel uses the fixed character device at /dev/console. The console channel is not synonymous with stdout (or file descriptor 1). stdout is the current output from a task when, say, printf() if used. Initially, stdout does, indeed, use the /dev/console device. However, stdout may subsequently be redirected to some other device or file. This is always the case, for example, when a transient device is used for a console -- such as a USB console or a Telnet console. The SYSLOG channel is not redirected as stdout is; the SYSLOG channel will stayed fixed (unless it is explicitly changed via syslog_channel()). -

    -

    - References: drivers/syslog/syslog_consolechannel.c and - drivers/syslog/syslog_device.c -

    - -

    6.4.3.2 SYSLOG Character Device

    -

    - The system console device, /dev/console, is a character driver with some special properties. However, any character driver may be used as the SYSLOG output channel. For example, suppose you have a serial console on /dev/ttyS0 and you want SYSLOG output on /dev/ttyS1. Or suppose you support only a Telnet console but want to capture debug output /dev/ttyS0. -

    -

    - This SYSLOG device channel is selected with CONFIG_SYSLOG_CHAR and has no other dependencies. Differences from the SYSLOG console channel include: -

    -
      -
    • -

      - CONFIG_SYSLOG_DEVPATH. This configuration option string must be set provide the full path to the character device to be used. -

      • -
    • -

      - The forced SYSLOG output always goes to the bit-bucket. This means that interrupt level SYSLOG output will be lost unless the interrupt buffer is enabled to support serialization. -

      • -
    • -

      - CONFIG_SYSLOG_CHAR_CRLF. If CONFIG_SYSLOG_CHAR_CRLF is selected, then linefeeds in the SYSLOG output will be expanded to Carriage Return plus Linefeed. Since the character device is not a console device, the addition of carriage returns to line feeds would not be performed otherwise. You would probably want this expansion if you use a serial terminal program with the character device output. -

      • -
    -

    - References: drivers/syslog/syslog_devchannel.c and drivers/syslog/syslog_device.c -

    - -

    6.4.3.3 SYSLOG File Device

    -

    - Files can also be used as the sink for SYSLOG output. There is, however, a very fundamental difference in using a file as opposed the system console, a RAM buffer, or character device: You must first mount the file system that supports the SYSLOG file. That difference means that the file SYSLOG channel cannot be supported during the boot-up phase but can be instantiated later when board level logic configures the application environment, including mounting of the file systems. -

    -

    - The interface syslog_file_channel() is used to configure the SYSLOG file channel: -

    - -

    6.4.3.4 syslog_file_channel()

    -

    Function Prototype:

    -
      -#include <nuttx/syslog/syslog.h>
-#ifdef CONFIG_SYSLOG_FILE
-int syslog_file_channel(FAR const char *devpath);
-#endif
-
    -

    Description: - Configure to use a file in a mounted file system at devpath as the SYSLOG channel. -

    -

    - This tiny function is simply a wrapper around syslog_dev_initialize() and syslog_channel(). It calls syslog_dev_initialize() to configure the character file at devpath then calls syslog_channel() to use that device as the SYSLOG output channel. -

    -

    - File SYSLOG channels differ from other SYSLOG channels in that they cannot be established until after fully booting and mounting the target file system. This function would need to be called from board-specific bring-up logic AFTER mounting the file system containing devpath. -

    -

    - SYSLOG data generated prior to calling syslog_file_channel() will, of course, not be included in the file. -

    -

    - NOTE interrupt level SYSLOG output will be lost in this case unless the interrupt buffer is used. -

    - -

    Input Parameters: -

      -
    • -

      - devpath: The full path to the file to be used for SYSLOG output. This may be an existing file or not. If the file exists, - syslog_file_channel() will append new SYSLOG data to the end of the file. If it does not, then syslog_file_channel() will create the file. -

      • -
    -

    Returned Value: - Zero (OK) is returned on success; a negated errno value is returned on any failure. -

    -

    - References: drivers/syslog/syslog_filechannel.c, drivers/syslog/syslog_device.c, and include/nuttx/syslog/syslog.h. -

    - -

    6.4.3.5 SYSLOG RAMLOG Device

    -

    - The RAMLOG is a standalone feature that can be used to buffer any - character data in memory. There are, however, special configurations - that can be used to configure the RAMLOG as a SYSLOG channel. The RAMLOG - functionality is described in a more general way in the following - paragraphs. -

    - -

    6.4.4 RAM Logging Device

    -

    - The RAM logging driver is a driver that was intended to support debugging output (SYSLOG) when the normal serial output is not available. For example, if you are using a Telnet or USB serial console, the debug output will get lost -- or worse. For example, what if you want to debug the network over Telnet? -

    -

    - The RAM logging driver can also accept debug output data from interrupt handler with no special serialization buffering. As an added benefit, the RAM logging driver is much less invasive. Since no actual I/O is performed with the debug output is generated, the RAM logger tends to be much faster and will interfere much less when used with time critical drivers. -

    -

    - The RAM logging driver is similar to a pipe in that it saves the debugging output in a circular buffer in RAM. It differs from a pipe in numerous details as needed to support logging. -

    -

    - This driver is built when CONFIG_RAMLOG is defined in the Nuttx configuration. -

    - -

    6.4.4.1 dmesg

    -

    - When the RAMLOG (with SYSLOG) is enabled, a new NuttShell (NSH) command will appear: dmesg. The dmesg command will dump the contents of the circular buffer to the console (and also clear the circular buffer). -

    - -

    6.4.4.2 RAMLOG Configuration options

    -
      -
    • -

      - CONFIG_RAMLOG: Enables the RAM logging feature -

      • -
    • -

      - CONFIG_RAMLOG_SYSLOG: Use the RAM logging device for the SYSLOG interface. If this feature is enabled, then all debug output will be re-directed to the circular buffer in RAM. This RAM log can be viewed from NSH using the dmesg command. NOTE: Unlike the limited, generic character driver SYSLOG device, the RAMLOG can be used to capture debug output from - interrupt level handlers. -

      • -
    • -

      - CONFIG_RAMLOG_NPOLLWAITERS: The number of threads than can be waiting for this driver on poll(). Default: 4 -

      • -
    -
      -
    • -

      - CONFIG_RAMLOG_BUFSIZE: The size of the circular buffer to use. Default: 1024 bytes. -

      • -
    -

    - Other miscellaneous settings -

    -
      -
    • -

      - CONFIG_RAMLOG_CRLF: Pre-pend a carriage return before every linefeed that goes into the RAM log. -

      • -
    • -

      - CONFIG_RAMLOG_NONBLOCKING: Reading from the RAMLOG will never block if the RAMLOG is empty. If the RAMLOG is empty, then zero is returned (usually interpreted as end-of-file). If you do not define this, the NSH dmesg command will lock up when called! So you probably do want this! -

      • -
    • -

      - CONFIG_RAMLOG_NPOLLWAITERS: The maximum number of threads that may be waiting on the poll method. -

      • -
    - -

    6.5 Power Management

    - -

    6.5.1 Overview

    -

    - Power Management (PM) Sub-System. - NuttX supports a simple power management (PM) sub-system. This sub-system: -

    -
      -
    • -

      - Monitors activity from drivers (and from other parts of the system), and -

      -
      • -
    • -

      - Provides hooks to place drivers (and the whole system) into reduce power - modes of operation. -

      -
      • -
    -

    -

    -

    -

    - The PM sub-system integrates the MCU idle loop with a collection of device drivers to support: -

    -
      -
    • -

      - Reports of relevant driver or other system activity. -

      -
      • -
    • -

      - Registration and callback mechanism to interface with individual device drivers. -

      -
      • -
    • -

      - IDLE time polling of overall driver activity. -

      -
      • -
    • -

      - Coordinated, global, system-wide transitions to lower power usage states. -

      -
      • -
    -

    - Low Power Consumption States. - Various "sleep" and low power consumption states have various names and are sometimes used in conflicting ways. - In the NuttX PM logic, we will use the following terminology: -

    -
    -
    NORMAL -
    The normal, full power operating mode. -
    IDLE -
    This is still basically normal operational mode, the system is, - however, IDLE and some simple simple steps to reduce power - consumption provided that they do not interfere with normal - Operation. Simply dimming the a backlight might be an example - some that that would be done when the system is idle. -
    STANDBY -
    Standby is a lower power consumption mode that may involve more - extensive power management steps such has disabling clocking or - setting the processor into reduced power consumption modes. In - this state, the system should still be able to resume normal - activity almost immediately. -
    SLEEP -
    The lowest power consumption mode. The most drastic power - reduction measures possible should be taken in this state. It - may require some time to get back to normal operation from - SLEEP (some MCUs may even require going through reset). -
    -

    - These various states are represented with type enum pm_state_e in include/nuttx/power/pm.h. -

    - -

    - Power Management Domains. - Each PM interfaces includes a integer domain number. - By default, only a single power domain is supported (CONFIG_PM_NDOMAINS=1). - But that is configurable; any number of PM domains can be supported. - Multiple PM domains might be useful, for example, if you would want to control power states associated with a network separately from power states associated with a user interface. -

    - -

    6.5.2 Interfaces

    -

    - All PM interfaces are declared in the file include/nuttx/power/pm.h. -

    - -

    6.5.2.1 pm_initialize()

    -

    Function Prototype:

    -
      -#include <nuttx/power/pm.h>
-void pm_initialize(void);
-
    -

    Description: -This function is called by MCU-specific one-time at power on reset in order to initialize the power management capabilities. -This function must be called very early in the initialization sequence before any other device drivers are initialized (since they may attempt to register with the power management subsystem). -

    -

    Input Parameters: -None -

    -

    Returned Value: -None -

    - -

    6.5.2.2 pm_register()

    -

    Function Prototype:

    -
      -#include <nuttx/power/pm.h>
-int pm_register(FAR struct pm_callback_s *callbacks);
-
    -

    Description: - This function is called by a device driver in order to register to receive power management event callbacks. - Refer to the PM Callback section for more details. -

    -

    Input Parameters: -

    -
    callbacks -
    An instance of struct pm_callback_s providing the driver callback functions. -
    -

    -

    Returned Value: -Zero (OK) on success; otherwise a negated errno value is returned. -

    - -

    6.5.2.3 pm_unregister()

    -

    Function Prototype:

    -
      -#include <nuttx/power/pm.h>
-int pm_unregister(FAR struct pm_callback_s *callbacks);
-
    -

    Description: - This function is called by a device driver in order to unregister previously registered power management event callbacks. - Refer to the PM Callback section for more details. -

    -

    Input Parameters: -

    -
    callbacks -
    An instance of struct pm_callback_s providing the driver callback functions. -
    -

    -

    Returned Value: -Zero (OK) on success; otherwise a negated errno value is returned. -

    - -

    6.5.2.4 pm_activity()

    -

    Function Prototype:

    -
      -#include <nuttx/power/pm.h>
-void pm_activity(int domain, int priority);
-
    -

    Description: - This function is called by a device driver to indicate that it is performing meaningful activities (non-idle). - This increment an activity count and/or will restart a idle timer and prevent entering reduced power states. -

    -

    Input Parameters: -

    -
    domain -
    Identifies the domain of the new PM activity -
    priority -
    - Activity priority, range 0-9. - Larger values correspond to higher priorities. - Higher priority activity can prevent the system from entering reduced power states for a longer period of time. - As an example, a button press might be higher priority activity because it means that the user is actively interacting with the device. -
    -

    -

    Returned Value: - None -

    -

    Assumptions: - This function may be called from an interrupt handler (this is the ONLY PM function that may be called from an interrupt handler!). -

    - -

    6.5.2.5 pm_checkstate()

    -

    Function Prototype:

    -
      -#include <nuttx/power/pm.h>
-enum pm_state_e pm_checkstate(int domain);
-
    -

    Description: - This function is called from the MCU-specific IDLE loop to monitor the power management conditions. - This function returns the "recommended" power management state based on the PM configuration and activity reported in the last sampling periods. - The power management state is not automatically changed, however. - The IDLE loop must call pm_changestate() in order to make the state change. -

    -

    - These two steps are separated because the platform-specific IDLE loop may have additional situational information that is not available to the PM sub-system. - For example, the IDLE loop may know that the battery charge level is very low and may force lower power states even if there is activity. -

    -

    - NOTE: That these two steps are separated in time and, hence, the IDLE loop could be suspended for a long period of time between calling pm_checkstate() and pm_changestate(). - The IDLE loop may need to make these calls atomic by either disabling interrupts until the state change is completed. -

    -

    Input Parameters: -

    -
    domain -
    Identifies the PM domain to check -
    -

    -

    Returned Value: - The recommended power management state. -

    - -

    6.5.2.6 pm_changestate()

    -

    Function Prototype:

    -
      -#include <nuttx/power/pm.h>
- int pm_changestate(int domain, enum pm_state_e newstate);
-
    -

    Description: - This function is used by platform-specific power management logic. - It will announce the power management power management state change to all drivers that have registered for power management event callbacks. -

    -

    Input Parameters: -

    -
    domain -
    Identifies the domain of the new PM state -
    newstate -
    Identifies the new PM state -
    -

    -

    Returned Value: - 0 (OK) means that the callback function for all registered drivers returned OK (meaning that they accept the state change). - Non-zero means that one of the drivers refused the state change. - In this case, the system will revert to the preceding state. -

    -

    Assumptions: - It is assumed that interrupts are disabled when this function is called. - This function is probably called from the IDLE loop... the lowest priority task in the system. - Changing driver power management states may result in renewed system activity and, as a result, can - suspend the IDLE thread before it completes the entire state change unless interrupts are disabled throughout the state change. -

    - -

    6.5.3 Callbacks

    -

    - The struct pm_callback_s includes the pointers to the driver callback functions. - This structure is defined include/nuttx/power/pm.h. - These callback functions can be used to provide power management information to the driver. -

    - -

    6.5.3.1 prepare()

    -

    Function Prototype:

    -
      -int (*prepare)(FAR struct pm_callback_s *cb, int domain, enum pm_state_e pmstate);
-
    -

    Description: - Request the driver to prepare for a new power state. - This is a warning that the system is about to enter into a new power state. - The driver should begin whatever operations that may be required to enter power state. - The driver may abort the state change mode by returning a non-zero value from the callback function. -

    -

    Input Parameters: -

    -
    cb -
    Returned to the driver. - The driver version of the callback structure may include additional, driver-specific state data at the end of the structure. -
    domain -
    Identifies the activity domain of the state change -
    pmstate -
    Identifies the new PM state -
    -

    -

    Returned Value: - Zero (OK) means the event was successfully processed and that the driver is prepared for the PM state change. - Non-zero means that the driver is not prepared to perform the tasks needed achieve this power setting and will cause the state change to be aborted. - NOTE: The prepare() method will also be called when reverting from lower back to higher power consumption modes (say because another driver refused a lower power state change). - Drivers are not permitted to return non-zero values when reverting back to higher power - consumption modes! -

    - -

    6.5.3.1 notify()

    -

    Function Prototype:

    -
      -#include <nuttx/power/pm.h>
-void (*notify)(FAR struct pm_callback_s *cb, int domain, enum pm_state_e pmstate);
-
    -

    Description: - Notify the driver of new power state. - This callback is called after all drivers have had the opportunity to prepare for the new power state. -

    -

    Input Parameters: -

    -
    cb -
    Returned to the driver. - The driver version of the callback structure may include additional, driver-specific state data at the end of the structure. -
    domain -
    Identifies the activity domain of the state change -
    pmstate -
    Identifies the new PM state -
    -

    -

    Returned Value: - None. - The driver already agreed to transition to the low power consumption state when when it returned OK to the prepare() call. -

    - - - - - -
    -

    Appendix A: NuttX Configuration Settings

    -
    - -

    - At one time, this section provided a list of all NuttX configuration variables. - However, NuttX has since converted to use the kconfig-frontends tools. - 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 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. -

    - The version of NuttXConfigVariables.html for the last released version of NuttX can also be found online. -

    - - - - - -
    -

    Appendix B: Trademarks

    -
    - -
  • ARM, ARM7 ARM7TDMI, ARM9, ARM920T, ARM926EJS, Cortex-M3 are trademarks of Advanced RISC Machines, Limited.
    • -
  • Cygwin is a trademark of Red Hat, Incorporated.
    • -
  • Linux is a registered trademark of Linus Torvalds.
    • -
  • Eagle-100 is a trademark of Micromint USA, LLC. -
  • LPC2148 is a trademark of NXP Semiconductors.
    • -
  • TI is a trade name of Texas Instruments Incorporated.
    • -
  • UNIX is a registered trademark of The Open Group.
    • -
  • VxWorks is a registered trademark of Wind River Systems, Incorporated.
    • -
  • ZDS, ZNEO, Z16F, Z80, and Zilog are a registered trademark of Zilog, Inc.
    • - -

    - NOTE: NuttX is not licensed to use the POSIX trademark. NuttX uses the POSIX - standard as a development guideline only. -

    - -
    -
    - - - diff --git a/Documentation/NuttxUserGuide.html b/Documentation/NuttxUserGuide.html deleted file mode 100644 index f264cecea3..0000000000 --- a/Documentation/NuttxUserGuide.html +++ /dev/null @@ -1,10600 +0,0 @@ - - - -NuttX Users Manual - - - - - -
    - - - - -
    -

    NuttX Operating System

    User's Manual

    -

    by

    -

    Gregory Nutt

    -

    Last Updated: May 25, 2020

    -
    -
    - - - - - -
    -

    1.0 Introduction

     -
    - -

    - This manual provides general usage information for the NuttX RTOS from the - perspective of the firmware developer. -

    - - - - - -
    -

    1.1 Document Overview

     -
    - -

    - This user's manual is divided into three sections plus a index: -

    - - - - - - -
    -

    1.2 Intended Audience and Scope

     -
    - -

    - The intended audience for this document are firmware developers who are implementing applications on NuttX. - Specifically, this documented is limited to addressing only NuttX RTOS APIs that are available to the application developer. - As such, this document does not focus on any technical details of the organization or implementation of NuttX. - Those technical details are provided in the NuttX Porting Guide. -

    -

    - Information about configuring and building NuttX is also needed by the application developer. - That information can also be found in the NuttX Porting Guide. -

    - - - - - -
    -

    2.0 OS Interfaces

     -
    - -

    - This section describes each C-callable interface to the NuttX - Operating System. The description of each interface is presented - in the following format: -

    -Function Prototype: The C prototype of the interface function -is provided. -

    -Description: The operation performed by the interface function -is discussed. -

    -Input Parameters: All input parameters are listed along -with brief descriptions of each input parameter. -

    -Returned Value: All possible values returned by the interface -function are listed. Values returned as side-effects (through -pointer input parameters or through global variables) will be -addressed in the description of the interface function. -

    -Assumptions/Limitations: Any unusual assumptions made by -the interface function or any non-obvious limitations to the use -of the interface function will be indicated here. -

    -POSIX Compatibility: Any significant differences between the -NuttX interface and its corresponding POSIX interface will be noted -here. -

    -NOTE: In order to achieve an independent name space for the NuttX -interface functions, differences in function names and types are -to be expected and will not be identified as differences in these -paragraphs. -

    - - - - - -
    -

    2.1 Task Control Interfaces

     -
    - -

    - Tasks. - NuttX is a flat address OS. As such it does not support processes - in the way that, say, Linux does. - NuttX only supports simple threads running within the same address space. - However, the programming model makes a distinction between tasks - and pthreads: -

    - -

    - File Descriptors and Streams. - This applies, in particular, in the area of opened file descriptors and streams. - When a task is started using the interfaces in this section, it will be created - with at most three open files. -

    -

    - If CONFIG_DEV_CONSOLE is defined, the first three file descriptors (corresponding - to stdin, stdout, stderr) will be duplicated for the new task. - Since these file descriptors are duplicated, the child task can free close - them or manipulate them in any way without effecting the parent task. - File-related operations (open, close, etc.) within a task will have no effect - on other tasks. - Since the three file descriptors are duplicated, it is also possible to perform - some level of redirection. -

    -

    - pthreads, on the other hand, will always share file descriptors with the parent - thread. In this case, file operations will have effect only all pthreads the - were started from the same parent thread. -

    -

    Executing Programs within a File System. - NuttX also provides internal interfaces for the execution of separately built - programs that reside in a file system. - These internal interfaces are, however, non-standard and are documented with the - NuttX binary loader and - NXFLAT. -

    -

    Task Control Interfaces. - The following task control interfaces are provided by NuttX: -

    -

    - Non-standard task control interfaces inspired by VxWorks interfaces: -

    - -

    - Non-standard extensions to VxWorks-like interfaces to support POSIX Cancellation Points. -

    - -

    - Standard interfaces -

    - -

    - Standard vfork and exec[v|l] interfaces: -

    - -

    - Standard posix_spawn interfaces: -

    - -

    - Non-standard task control interfaces inspired by posix_spawn: -

    - - -

    2.1.1 task_create

    - -

    -Function Prototype: -

    - -

    -Description: - This function creates and activates a new task with a - specified priority and returns its system-assigned ID. -

    - -

    The entry address entry is the address of the "main" - function of the task. - This function will be called once the C environment has been set up. - The specified function will be called with four arguments. - Should the specified routine return, a call to exit() will automatically be made. -

    -

    - Note that an arbitrary number of arguments may be passed to the - spawned functions. -

    -

    - The arguments are copied (via strdup) so that the - life of the passed strings is not dependent on the life of the - caller to task_create(). -

    -

    - The newly created task does not inherit scheduler characteristics - from the parent task: The new task is started at the - default system priority and with the SCHED_FIFO scheduling - policy. These characteristics may be modified after the new - task has been started. -

    -

    - The newly created task does inherit the first three file - descriptors (corresponding to stdin, stdout, and stderr) and - redirection of standard I/O is supported. -

    -

    -Input Parameters: -

    -

    - Returned Value: -

    - - -

    -Assumptions/Limitations: -

    -POSIX Compatibility: This is a NON-POSIX interface. -VxWorks provides the following similar interface: -

    -   int taskSpawn(char *name, int priority, int options, int stackSize, FUNCPTR entryPt,
-                 int arg1, int arg2, int arg3, int arg4, int arg5,
-                 int arg6, int arg7, int arg8, int arg9, int arg10);
-
    - -

    - The NuttX task_create() differs from VxWorks' taskSpawn() in the - following ways: -

    - - -

    2.1.2 task_delete

    - -

    -Function Prototype: -

    - -

    - Description: - This function causes a specified task to cease to exist. - Its stack and TCB will be deallocated. - This function is the companion to task_create(). - This is the version of the function exposed to the user; - it is simply a wrapper around the internal, nxtask_terminate() function. -

    -

    - The logic in this function only deletes non-running tasks. - If the pid parameter refers to the currently running task, then processing is redirected to exit(). - This can only happen if a task calls task_delete() in order to delete itself. -

    -

    - This function obeys the semantics of pthread cancellation: - task deletion is deferred if cancellation is disabled or if deferred cancellation is supported (with Cancellation Points enabled). -

    -

    -Input Parameters: -

    -

    -Returned Value: -

    -

    -Assumptions/Limitations: -

    - task_delete() must be used with caution: - If the task holds resources (for example, allocated memory or semaphores needed by other tasks), then task_delete() can strand those resources. -

    -

    -POSIX Compatibility: - This is a NON-POSIX interface. - VxWorks provides the following similar interface: -

    - - -

    - The NuttX task_delete() differs from VxWorks' taskDelete() in - the following ways: -

    - - -

    2.1.3 task_restart

    -

    -Function Prototype: -

    -

    - Description: - This function "restarts" a task. - The task is first terminated and then reinitialized with same ID, priority, original entry point, stack size, and parameters it had when it was first started. -

    -

    - NOTES: -

    -
      -
    1. - The normal task exit clean up is not performed. - For example, file descriptors are not closed; any files opened prior to the restart will remain opened after the task is restarted. -
      2. -
    2. - Memory allocated by the task before it was restart is not freed. - A task that is subject to being restart must be designed in such a way as to avoid memory leaks. -
      3. -
    3. - Initialized data is not reset. - All global or static data is left in the same state as when the task was terminated. - This feature may be used by restart task to detect that it has been restarted, for example. -
      4. -
    -

    -Input Parameters: -

    -

    -Returned Value: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: This is a NON-POSIX interface. -VxWorks provides the following similar interface: -

    -    STATUS taskRestart (int tid);
-
    - -

    - The NuttX task_restart() differs from VxWorks' taskRestart() in the following ways: -

    - - -

    2.1.6 task_setcancelstate

    -

    -Function Prototype: -

    -

    -    #include <sched.h>
-    int task_setcancelstate(int state, int *oldstate);
-
    -

    -Description: -The task_setcancelstate() function atomically -sets both the calling task's cancellability state to the indicated -state and returns the previous cancellability state at the location -referenced by oldstate. -Legal values for state are TASK_CANCEL_ENABLE and TASK_CANCEL_DISABLE. -

    -

    -Any pending thread cancellation may occur at the time that the -cancellation state is set to TASK_CANCEL_ENABLE. -

    -

    -The cancellability state and type of any newly created tasks are TASK_CANCEL_ENABLE and TASK_CANCEL_DEFERRED respectively. -

    -Input Parameters: -

    -

    -

    -

    -

    -Returned Value: -

    -

    -Zero (OK) on success; ERROR is returned on any failure with the errno value set appropriately: -

    -

    -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: This is a non-standard interface. It extends the functionality of pthread_setcancelstate() to tasks and supports use of task_delete(). -

    - -

    2.1.7 task_setcanceltype

    -

    -Function Prototype: -

    -

    -    #include <sched.h>
-    int task_setcanceltype(int type, FAR int *oldtype);
-
    -

    -Description: -The task_setcanceltype() function atomically both sets the calling task's cancellability type to the indicated type and returns the previous cancellability type at the location referenced by oldtype. -Legal values for type are TASK_CANCEL_DEFERRED and TASK_CANCEL_ASYNCHRONOUS. -

    -

    -The cancellability state and type of any newly created tasks are TASK_CANCEL_ENABLE and TASK_CANCEL_DEFERRED respectively. -

    -

    -Input Parameters: -

    -

    -

    -

    -

    -Returned Value: -

    -

    -Zero (OK) on success; ERROR is returned on any failure with the errno value set appropriately: -

    -

    -

    -

    -

    -POSIX Compatibility: This is a non-standard interface. It extends the functionality of pthread_setcanceltype() to tasks and supports use of task_delete(). -

    - -

    2.1.8 task_testcancel

    -

    -Function Prototype: -

    -

    -

    -    #include <sched.h>
-    void task_testcancel(void);
-
    -

    -

    -Description: -

    -

    -The task_testcancel() function creates a Cancellation Point in the calling task. -The task_testcancel() function has no effect if cancellability is disabled. -

    -

    -Input Parameters: None -

    -

    -Returned Value: None -

    -

    -POSIX Compatibility: This is a non-standard interface. It extends the functionality of pthread_testcancel() to tasks and supports use of task_delete(). -

    - - -

    2.1.9 exit

    - -

    -Function Prototype: -

    -    #include <sched.h>
-    void exit(int code);
-
-    #include <nuttx/unistd.h>
-    void _exit(int code);
-
    - -

    -Description: This function causes the calling task to cease -to exist -- its stack and TCB will be deallocated. exit differs from -_exit in that it flushes streams, closes file descriptors and will -execute any function registered with atexit() or on_exit(). -

    -Input Parameters: -

    - -

    -Returned Value: None. - -

    -Assumptions/Limitations: - -

    -POSIX Compatibility: This is equivalent to the ANSI interface: -

    -    void exit(int code);
-
    -And the UNIX interface: -
    -    void _exit(int code);
-
    - -

    - The NuttX exit() differs from ANSI exit() in the following ways: -

    - - -

    2.1.10 getpid

    - -

    -Function Prototype: -

    -    #include <unistd.h>
-    pid_t getpid(void);
-
    - -

    -Description: This function returns the task ID of the -calling task. The task ID will be invalid if called at the interrupt -level. -

    -Input Parameters: None. -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    -POSIX Compatibility: -Compatible with the POSIX interface of the same name. -

    - -

    2.1.11 vfork

    -

    - Function Prototype: -

    - -

    - Description: - The vfork() function has the same effect as fork(), except that the behavior is undefined if the process created by vfork() either modifies any data other than a variable of type pid_t used to store the return value from vfork(), or returns from the function in which vfork() was called, or calls any other function before successfully calling _exit() or one of the exec family of functions. -

    -

    - NOTE: - vfork() is not an independent NuttX feature, but is implemented in architecture-specific logic (using only helper functions from the NuttX core logic). - As a result, vfork() may not be available on all architectures. -
    -

    - Input Parameters: - None. -

    -

    - Returned Value: - Upon successful completion, vfork() returns 0 to the child process and returns - the process ID of the child process to the parent process. - Otherwise, -1 is returned to the parent, no child process is created, and errno is set to indicate the error. -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - Compatible with the BSD/Linux interface of the same name. POSIX marks this interface as Obsolete. -

    - -

    2.1.12 exec

    -

    - Function Prototype: -

    - -

    - Description: - This non-standard, NuttX function is similar to execv() and posix_spawn() but differs in the following ways; -

    - -

    - This non-standard interface is included as a official NuttX API only because it is needed in certain build modes: exec() is probably the only want to load programs in the PROTECTED mode. Other file execution APIs rely on a symbol table provided by the OS. In the PROTECTED build mode, the OS cannot provide any meaningful symbolic information for execution of code in the user-space blob so that is the exec() function is really needed in that build case -

    - The interface is available in the FLAT build mode although it is not really necessary in that case. It is currently used by some example code under the apps/ that that generate their own symbol tables for linking test programs. So although it is not necessary, it can still be useful. -

    -

    - The interface would be completely useless and will not be supported in the KERNEL build mode where the contrary is true: An application process cannot provide any meaning symbolic information for use in linking a different process. -

    -

    - NOTE: - This function is flawed and useless without CONFIG_SCHED_ONEXIT and CONFIG_SCHED_HAVE_PARENT because without those features there is then no mechanism to unload the module once it exits. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - Zero (OK) is returned on success; - On any failure, exec() will return -1 (ERROR) and will set the errno value appropriately. -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - This is a non-standard interface unique to NuttX. - Motivation for inclusion of this non-standard interface in certain build modes is discussed above. -

    - -

    2.1.13 execv

    -

    - Function Prototype: -

    - -

    - Description: - The standard exec family of functions will replace the current process image with a new process image. - The new image will be constructed from a regular, executable file called the new process image file. - There will be no return from a successful exec, because the calling process image is overlaid by the new process image. -

    -

    - Simplified execl() and execv() functions are provided by NuttX for compatibility. - NuttX is a tiny embedded RTOS that does not support processes and hence the concept of overlaying a tasks process image with a new process image does not make any sense. - In NuttX, these functions are wrapper functions that: -

    -
      -
    1. - Call the non-standard binfmt function exec(), and then -
      2. -
    2. - exit(0). -
      3. -
    -

    - Note the inefficiency when execv() or execl() is called in the normal, two-step process: - (1) first call vfork() to create a new thread, then (2) call execv() or execl() to replace the new thread with a program from the file system. - Since the new thread will be terminated by the execv() or execl() call, it really served no purpose other than to support POSIX compatibility. -

    -

    - The non-standard binfmt function exec() needs to have (1) a symbol table that provides the list of symbols exported by the base code, and (2) the number of symbols in that table. - This information is currently provided to exec() from execv() or execl() via NuttX configuration settings: -

    - -

    - As a result of the above, the current implementations of execl() and execv() suffer from some incompatibilities that may or may not be addressed in a future version of NuttX. - Other than just being an inefficient use of MCU resource, the most serious of these is that - the exec'ed task will not have the same task ID as the vfork'ed function. - So the parent function cannot know the ID of the exec'ed task.

    -

    - Input Parameters: -

    - -

    - Returned Value: - This function does not return on success. - On failure, it will return -1 (ERROR) and will set the errno value appropriately. -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - Similar with the POSIX interface of the same name. - There are, however, several compatibility issues as detailed in the description above. -

    - -

    2.1.14 execl

    -

    - Function Prototype: -

    - -

    - Description: - execl() is functionally equivalent to execv(), differing only in the form of its input parameters. - See the description of execv() for additional information. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - This function does not return on success. - On failure, it will return -1 (ERROR) and will set the errno value appropriately. -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - Similar with the POSIX interface of the same name. - There are, however, several compatibility issues as detailed in the description of execv(). -

    - -

    2.1.14 posix_spawn and posix_spawnp

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawn() and posix_spawnp() functions will create a new, child task, constructed from a regular executable file. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - posix_spawn() and posix_spawnp() will return zero on success. - Otherwise, an error number will be returned as the function return value to indicate the error: -

    - -

    - Assumptions/Limitations: -

    - -

    - POSIX Compatibility: - The value of the argv[0] received by the child task is assigned by NuttX. - For the caller of posix_spawn(), the provided argv[0] will correspond to argv[1] received by the new task. -

    - -

    2.1.15 posix_spawn_file_actions_init

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawn_file_actions_init() function initializes the object referenced by file_actions to an empty set of file actions for subsequent use in a call to posix_spawn() or posix_spawnp(). -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h>. -

    - -

    2.1.16 posix_spawn_file_actions_destroy

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawn_file_actions_destroy() function destroys the object referenced by file_actions which was previously initialized by posix_spawn_file_actions_init(), returning any resources obtained at the time of initialization to the system for subsequent reuse. - A posix_spawn_file_actions_t may be reinitialized after having been destroyed, but must not be reused after destruction, unless it has been reinitialized. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.17 posix_spawn_file_actions_addclose

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawn_file_actions_addclose() function adds a close operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn() or posix_spawnp(). - The descriptor referred to by fd is closed as if close() had been called on it prior to the new child process starting execution. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.18 posix_spawn_file_actions_adddup2

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawn_file_actions_adddup2() function adds a dup2 operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn() or posix_spawnp(). - The descriptor referred to by fd2 is created as if dup2() had been called on fd1 prior to the new child process starting execution. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.19 posix_spawn_file_actions_addopen

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawn_file_actions_addopen() function adds an open operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn() or posix_spawnp(). - The descriptor referred to by fd is opened using the path, oflag, and mode arguments as if open() had been called on it prior to the new child process starting execution. - The string path is copied by the posix_spawn_file_actions_addopen() function during this process, so storage need not be persistent in the caller. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.20 posix_spawnattr_init

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawnattr_init() function initializes the object referenced by attr, to an empty set of spawn attributes for subsequent use in a call to posix_spawn() or posix_spawnp(). -

    -

    - Then the spawn attributes are no longer needed, they should be destroyed by calling posix_spawnattr_destroyed(). - In NuttX, however, posix_spawnattr_destroyed() is just stub: -

    - -

    - For portability, the convention of calling posix_spawnattr_destroyed() when the attributes are not longer needed should still be followed. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.21 posix_spawnattr_getflags

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawnattr_getflags() function will obtain the value of the spawn-flags attribute from the attributes object referenced by attr. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.22 posix_spawnattr_getschedparam

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawnattr_getschedparam() function will obtain the value of the spawn-schedparam attribute from the attributes object referenced by attr. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.23 posix_spawnattr_getschedpolicy

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawnattr_getschedpolicy() function will obtain the value of the spawn-schedpolicy attribute from the attributes object referenced by attr. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.24 posix_spawnattr_getsigmask

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawnattr_getsigdefault() function will obtain the value of the spawn-sigmask attribute from the attributes object referenced by attr. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.25 posix_spawnattr_setflags

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawnattr_setflags() function will set the spawn-flags attribute in an initialized attributes object referenced by attr. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.26 posix_spawnattr_setschedparam

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawnattr_setschedparam() function will set the spawn-schedparam attribute in an initialized attributes object referenced by attr. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.27 posix_spawnattr_setschedpolicy

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawnattr_setschedpolicy() function will set the spawn-schedpolicy attribute in an initialized attributes object referenced by attr. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.28 posix_spawnattr_setsigmask

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawnattr_setsigmask() function will set the spawn-sigmask attribute in an initialized attributes object referenced by attr. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.29 task_spawn

    -

    - Function Prototype: -

    - -

    - Description: - The task_spawn() function will create a new, child task, where the entry point to the task is an address in memory. -

    -

    - -

    - Returned Value: - task_spawn() will return zero on success. - Otherwise, an error number will be returned as the function return value to indicate the error: -

    -

    - POSIX Compatibility: - This is a non-standard interface inspired by posix_spawn(). -

    - -

    2.1.30 task_spawnattr_getstacksize

    -

    - Function Prototype: -

    - -

    - Description: - The task_spawnattr_getstacksize() function will obtain the value of the spawn-stacksize attribute from the attributes object referenced by attr. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.31 task_spawnattr_setstacksize

    -

    - Function Prototype: -

    - -

    - Description: - The task_spawnattr_setstacksize() function will set the spawn-stacksize attribute in an initialized attributes object referenced by attr. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

    - -

    2.1.32 posix_spawn_file_actions_init

    -

    - Function Prototype: -

    - -

    - Description: - The posix_spawn_file_actions_init() function initializes the object referenced by file_actions to an empty set of file actions for subsequent use in a call to posix_spawn() or posix_spawnp(). -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h>. -

    - - - - - -
    -

    2.2 Task Scheduling Interfaces

     -
    - -

    - By default, NuttX performs strict priority scheduling: Tasks of higher priority have exclusive access to the CPU until they become blocked. - At that time, the CPU is available to tasks of lower priority. - Tasks of equal priority are scheduled FIFO. -

    -

    - Optionally, a Nuttx task or thread can be configured with round-robin or sporadic scheduler. - The round-robin is similar to priority scheduling except that tasks with equal priority and share CPU time via time-slicing. - The time-slice interval is a constant determined by the configuration - setting CONFIG_RR_INTERVAL to a positive, non-zero value. - Sporadic scheduling scheduling is more complex, varying the priority of a thread over a replenishment period. - Support for sporadic scheduling is enabled by the configuration option CONFIG_SCHED_SPORADIC. -

    -

    - The OS interfaces described in the following paragraphs provide a POSIX- compliant interface to the NuttX scheduler: -

    - - -

    2.2.1 sched_setparam

    -

    - Function Prototype: -

    -    #include <sched.h>
-    int sched_setparam(pid_t pid, FAR const struct sched_param *param);
-
    -

    - Description: - This function sets the priority of the task specified by pid input parameter. -

    -

    - NOTE: Setting a task's priority to the same value has the similar - effect to sched_yield(): The task will be moved to after all - other tasks with the same priority. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, sched_setparam() returns 0 (OK). - On error, -1 (ERROR) is returned, and errno is set appropriately. -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. - Differences from the full POSIX implementation include: -

    - - -

    2.2.2 sched_getparam

    - -

    -Function Prototype: -

    -    #include <sched.h>
-    int sched_getparam(pid_t pid, FAR struct sched_param *param);
-
    - -

    -Description: This function gets the scheduling priority -of the task specified by pid. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.2.3 sched_setscheduler

    -

    - Function Prototype: -

    - -

    - Description: - sched_setscheduler() sets both the scheduling policy and the priority for the task identified by pid. - If pid equals zero, the scheduler of the calling thread will be set. - The parameter param holds the priority of the thread under the new policy. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, sched_setscheduler() returns OK (zero). On - error, ERROR (-1) is returned, and errno is set appropriately: -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.2.4 sched_getscheduler

    -

    -Function Prototype: -

    -

    - Description: - sched_getscheduler() returns the scheduling policy - currently applied to the task identified by pid. If - pid equals zero, the policy of the calling process will - be retrieved. -

    -Input Parameters: -

    -

    -Returned Value: -

    -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. - -

    2.2.5 sched_yield

    - -

    -Function Prototype: -

    -    #include <sched.h>
-    int sched_yield(void);
-
    - -

    -Description: This function forces the calling task to give -up the CPU (only to other tasks at the same priority). -

    -Input Parameters: None. -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.2.6 sched_get_priority_max

    - -

    -Function Prototype: -

    -    #include <sched.h>
-    int sched_get_priority_max (int policy)
-
    - -

    -Description: This function returns the value of the highest -possible task priority for a specified scheduling policy. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.2.7 sched_get_priority_min

    - -

    -Function Prototype: -

    -    #include <sched.h>
-    int sched_get_priority_min (int policy);
-
    - -

    -Description: This function returns the value of the lowest -possible task priority for a specified scheduling policy. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.2.8 sched_get_rr_interval

    - -

    -Function Prototype: -

    -    #include <sched.h>
-    int sched_get_rr_interval (pid_t pid, struct timespec *interval);
-
    - -

    - Description: - sched_rr_get_interval() writes the timeslice interval - for task identified by pid into the timespec structure - pointed to by interval. If pid is zero, the timeslice - for the calling process is written into 'interval. The - identified process should be running under the SCHED_RR - scheduling policy.' -

    -

    - Input Parameters: -

    - - -

    - Returned Value: - On success, sched_rr_get_interval() returns OK (0). On - error, ERROR (-1) is returned, and errno is set to: -

    - - -

    - Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX - interface of the same name. -

    - - - - - -
    -

    2.3 Task Control Interfaces

     -
    - -

    - Task Control Interfaces. -

    - - -

    - Parent and Child Tasks. - The task synchronization interfaces historically depend upon parent and child relationships between tasks. - But default, NuttX does not use any parent/child knowledge. - However, there are three important configuration options that can change that. -

    - -

    - Warning: - If you enable the CONFIG_SCHED_CHILD_STATUS feature, then your application must either (1) take responsibility for reaping the child status with wait(), waitpid() or waitid(), or (2) suppress retention of child status. - If you do not reap the child status, then you have a memory leak and your system will eventually fail. -

    - Retention of child status can be suppressed on the parent using logic like: -

    - - -

    2.3.1 sched_lock

    - -

    -Function Prototype: -

    -    #include <sched.h>
-    int sched_lock(void);
-
    - -

    -Description: This function disables context switching by -Disabling addition of new tasks to the ready-to-run task list. -The task that calls this function will be the only task that is -allowed to run until it either calls sched_unlock (the appropriate -number of times) or until it blocks itself. -

    -Input Parameters: None. -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    -POSIX Compatibility: This is a NON-POSIX interface. -VxWorks provides the comparable interface: -

    -    STATUS taskLock(void);
-
    - -

    2.3.2 sched_unlock

    - -

    -Function Prototype: -

    -    #include <sched.h>
-    int sched_unlock(void);
-
    - -

    -Description: This function decrements the preemption lock -count. Typically this is paired with sched_lock() and concludes -a critical section of code. Preemption will not be unlocked until -sched_unlock() has been called as many times as sched_lock(). -When the lockCount is decremented to zero, any tasks that were -eligible to preempt the current task will execute. -

    -Input Parameters: None. -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    -POSIX Compatibility: This is a NON-POSIX interface. -VxWorks provides the comparable interface: -

    -    STATUS taskUnlock(void);
-
    - -

    2.3.3 sched_lockcount

    - -

    -Function Prototype: -

    -    #include <sched.h>
-    int32_t sched_lockcount(void)
-
    - -

    -Description: This function returns the current value of -the lockCount. If zero, preemption is enabled; if non-zero, this -value indicates the number of times that sched_lock() has been called -on this thread of execution. -

    -Input Parameters: None. -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: None. -

    - -

    2.3.4 waitpid

    - -

    -Function Prototype: -

    -    #include <sys/wait.h>
-    ipid_t waitpid(pid_t pid, int *stat_loc, int options);
-
    - -

    - Description: -

    -
    - The following discussion is a general description of the waitpid() interface. - However, as of this writing, the implementation of waitpid() is incomplete (but usable). - If CONFIG_SCHED_HAVE_PARENT is defined, waitpid() will be a little more compliant to specifications. - Without CONFIG_SCHED_HAVE_PARENT, waitpid() simply supports waiting for any task to complete execution. - With CONFIG_SCHED_HAVE_PARENT, waitpid() will use SIGCHLD and can, therefore, wait for any child of the parent to complete. - The implementation is incomplete in either case, however: NuttX does not support any concept of process groups. - Nor does NuttX retain the status of exited tasks so if waitpid() is called after a task has exited, then no status will be available. - The options argument is currently ignored. -
    -

    - The waitpid() functions will obtain status information pertaining to one of the caller's child processes. - The waitpid() function will suspend execution of the calling thread until status information for one of the terminated child processes of the calling process is available, or until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process. - If more than one thread is suspended in waitpid() awaiting termination of the same process, exactly one thread will return the process status at the time of the target process termination. - If status information is available prior to the call to waitpid(), return will be immediate. -

    -

    - NOTE: - Because waitpid() is not fully POSIX compliant, it must be specifically enabled by setting CONFIG_SCHED_WAITPID in the NuttX configuration file. -

    -

    - Input Parameters: -

    - -

    - The pid argument specifies a set of child processes for which status is requested. - The waitpid() function will only return the status of a child process from this set: -

    - -

    - The options argument is constructed from the bitwise-inclusive OR of zero or more of the following flags, - defined in the <sys/wait.h> header: -

    - -

    - If the calling process has SA_NOCLDWAIT set or has SIGCHLD set to SIG_IGN, and the process has no unwaited-for children that were transformed into zombie processes, the calling thread will block until all of the children of the process containing the calling thread terminate, and waitpid() will fail and set errno to ECHILD. -

    -

    - If waitpid() returns because the status of a child process is available, these functions will return a value equal to the process ID of the child process. - In this case, if the value of the argument stat_loc is not a null pointer, information will be stored in the location pointed to by stat_loc. - The value stored at the location pointed to by stat_loc will be 0 if and only if the status returned is from a terminated child process that terminated by one of the following means: -

    -
      -
    1. - The process returned 0 from main(). -
      2. -
    2. - The process called _exit() or exit() with a status argument of 0. -
      3. -
    3. - The process was terminated because the last thread in the process terminated. -
      4. -
    -

    - Regardless of its value, this information may be interpreted using the following macros, which are defined in <sys/wait.h> and evaluate to integral expressions; the stat_val argument is the integer value pointed to by stat_loc. -

    - -

    - Returned Value: -

    -

    - If waitpid() returns because the status of a child process is available, it will return a value equal to the process ID of the child process for which status is reported. -

    -

    - If waitpid() returns due to the delivery of a signal to the calling process, -1 will be returned and errno set to EINTR. -

    -

    - If waitpid() was invoked with WNOHANG set in options, it has at least one child process specified by pid for which status is not available, and status is not available for any process specified by pid, 0 is returned. -

    -

    - Otherwise, (pid_t)-1errno set to indicate the error: -

    - - -

    - Assumptions/Limitations: -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name, but the implementation is incomplete (as detailed above). -

    - -

    2.3.5 waitid

    -

    -Function Prototype: -

    -    #include <sys/wait.h>
-    #ifdef CONFIG_SCHED_HAVE_PARENT
-    int waitid(idtype_t idtype, id_t id, FAR siginfo_t *info, int options);
-    #endif
-
    -

    - Description: -

    -
    - The following discussion is a general description of the waitid() interface. - However, as of this writing, the implementation of waitid() is incomplete (but usable). - If CONFIG_SCHED_HAVE_PARENT is defined, waitid() will be a little more compliant to specifications. - waitpid() simply supports waiting a specific child task (P_PID or for any child task P_ALL to complete execution. - SIGCHLD is used. - The implementation is incomplete in either case, however: NuttX does not support any concept of process groups. - Nor does NuttX retain the status of exited tasks so if waitpid() is called after a task has exited, then no status will be available. - The options argument is currently ignored. -
    -

    - The waitid() function suspends the calling thread until one child of the process containing the calling thread changes state. - It records the current state of a child in the structure pointed to by info. - If a child process changed state prior to the call to waitid(), waitid() returns immediately. - If more than one thread is suspended in wait() or waitpid() waiting termination of the same process, exactly one thread will return the process status at the time of the target process termination -

    -

    - The idtype and id arguments are used to specify which children waitid() will wait for. -

    -

    -

    -

    - The options argument is used to specify which state changes waitid() will will wait for. - It is formed by OR-ing together one or more of the following flags: -

    - - The info argument must point to a siginfo_t structure. - If waitid() returns because a child process was found that satisfied the conditions indicated by the arguments idtype and options, then the structure pointed to by info will be filled in by the system with the status of the process. - The si_signo member will always be equal to SIGCHLD. -

    -

    - Input Parameters: - See the description above. -

    -

    - Returned Value: - If waitid() returns due to the change of state of one of its children, 0 is returned. - Otherwise, -1 is returned and errno is set to indicate the error. -

    -

    - The waitid() function will fail if: -

    - -

    - Assumptions/Limitations: -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name, but the implementation is incomplete (as detailed in the description above). -

    - -

    2.3.6 wait

    -

    -Function Prototype: -

    -    #include <sys/wait.h>
-    #ifdef CONFIG_SCHED_HAVE_PARENT
-    pid_t wait(FAR int *stat_loc);
-    #endif
-
    -

    - Description: -

    -
    - The following discussion is a general description of the wait() interface. - However, as of this writing, the implementation of wait() is incomplete (but usable). - wait() is based on waitpaid(). - See the description of waitpaid() for further information. -
    -

    - The wait() function will suspend execution of the calling thread until status information for one of its terminated child processes is available, or until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process. - If more than one thread is suspended in wait() awaiting termination of the same process, exactly one thread will return the process status at the time of the target process termination. - If status information is available prior to the call towait(), return will be immediate. -

    -

    - The waitpid() function will behave identically to wait(), if its pid argument is (pid_t)-1 and the options argument is 0. - Otherwise, its behavior will be modified by the values of the pid and options arguments. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - See the values returned by waitpaid(). -

    -

    - Assumptions/Limitations: -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name, but the implementation is incomplete (as detailed in the description waitpaid()). -

    - -

    2.3.7 atexit

    - -

    -Function Prototype: -

    -    #include <stdlib.h>
-    int atexit(void (*func)(void));
-
    -

    - Description: - Registers a function to be called at program exit. - The atexit() function registers the given function to be called at normal process termination, whether via exit() or via return from the program's main(). -

    -

    - NOTE: CONFIG_SCHED_ATEXIT must be defined to enable this function. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, atexit() returns OK (0). - On error, ERROR (-1) is returned, and errno is set to indicate the cause of the failure. -

    - -

    - Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the ISO C interface of the same name. - Limitations in the current implementation: -

    -
      -
    1. Only a single atexit function can be registered unless CONFIG_SCHED_ATEXIT_MAX defines a larger number.
      2. -
    2. atexit() functions are not inherited when a new task is created.
      3. -
    - -

    2.3.8 on_exit

    - -

    -Function Prototype: -

    -    #include <stdlib.h>
-    int on_exit(CODE void (*func)(int, FAR void *), FAR void *arg)
-
    -

    - Description: - Registers a function to be called at program exit. - The on_exit() function registers the given function to be called at normal process termination, whether via exit() or via return from the program's main(). - The function is passed the status argument given to the last call to exit() and the arg argument from on_exit(). -

    -

    - NOTE: CONFIG_SCHED_ONEXIT must be defined to enable this function -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, on_exit() returns OK (0). - On error, ERROR (-1) is returned, and errno is set to indicate the cause of the failure. -

    - -

    - Assumptions/Limitations: -

    - POSIX Compatibility: - This function comes from SunOS 4, but is also present in libc4, libc5 and glibc. - It no longer occurs in Solaris (SunOS 5). - Avoid this function, and use the standard atexit() instead. -

    -
      -
    1. Only a single on_exit function can be registered unless CONFIG_SCHED_ONEXIT_MAX defines a larger number.
      2. -
    2. on_exit() functions are not inherited when a new task is created.
      3. -
    - - - - - -
    -

    2.4 Named Message Queue Interfaces

     -
    - -

    - NuttX supports POSIX named message queues for inter-task communication. - Any task may send or receive messages on named message queues. - Interrupt handlers may send messages via named message queues. -

    - - -

    2.4.1 mq_open

    - -

    -Function Prototype: -

    -    #include <mqueue.h>
-    mqd_t mq_open(const char *mqName, int oflags, ...);
-
    - -

    -Description: This function establish a connection between -a named message queue and the calling task. After a successful -call of mq_open(), the task can reference the message queue using -the address returned by the call. The message queue remains usable -until it is closed by a successful call to mq_close(). -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX interface -of the same name. -Differences from the full POSIX implementation include: -

    - -

    2.4.2 mq_close

    - -

    -Function Prototype: -

    -    #include <mqueue.h>
-    int mq_close(mqd_t mqdes);
-
    - -

    -Description: This function is used to indicate that the -calling task is finished with the specified message queued mqdes. -The mq_close() deallocates any system resources allocated by the -system for use by this task for its message queue. -

    -If the calling task has attached a notification request to the message -queue via this mqdes (see mq_notify()), this attachment will be -removed and the message queue is available for another task to attach -for notification. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    -

    -

    - POSIX Compatibility: Comparable to the POSIX interface -of the same name. - -

    2.4.3 mq_unlink

    - -

    -Function Prototype: -

    -    #include <mqueue.h>
-    int mq_unlink(const char *mqName);
-
    - -

    -Description: This function removes the message queue named -by "mqName." If one or more tasks have the message queue -open when mq_unlink() is called, removal of the message queue -is postponed until all references to the message queue have been -closed. -

    -Input Parameters: -

    - -

    -Returned Value: None. -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.4.4 mq_send

    -

    -Function Prototype: -

    -
    -    #include <mqueue.h>
-    int mq_send(mqd_t mqdes, const void *msg, size_t msglen, int prio);
-
    -

    -Description: - This function adds the specified message, msg, to the message queue, mqdes. - The msglen parameter specifies the length of the message in bytes pointed to by msg. - This length must not exceed the maximum message length from the mq_getattr(). -

    -

    - If the message queue is not full, mq_send() will place the msg - in the message queue at the position indicated by the prio argument. - Messages with higher priority will be inserted before lower priority messages - The value of prio must not exceed MQ_PRIO_MAX. -

    -

    - If the specified message queue is full and O_NONBLOCK is not - set in the message queue, then mq_send() will block until space - becomes available to the queue the message. -

    -

    - If the message queue is full and NON_BLOCK is set, the message - is not queued and ERROR is returned. -

    -

    - NOTE: - mq_send() may be called from an interrupt handler. - However, it behaves differently when called from the interrupt level: -

    - -

    - Input Parameters: -

    - -

    - Returned Value: - On success, mq_send() returns 0 (OK); - on error, -1 (ERROR) is returned, with errno set - to indicate the error: -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. -

    - -

    mq_timedsend

    -Function Prototype: -

    -
    -    #include <mqueue.h>
-    int mq_timedsend(mqd_t mqdes, const char *msg, size_t msglen, int prio,
-                     const struct timespec *abstime);
-
    -

    -Description: - This function adds the specified message, msg, - to the message queue, mqdes. - The msglen parameter specifies the length of the message in bytes pointed to by msg. - This length must not exceed the maximum message length from the mq_getattr(). -

    -

    - If the message queue is not full, mq_timedsend() will place the msg - in the message queue at the position indicated by the prio argument. - Messages with higher priority will be inserted before lower priority messages - The value of prio must not exceed MQ_PRIO_MAX. -

    -

    - If the specified message queue is full and O_NONBLOCK is not - set in the message queue, then mq_send() will block until space - becomes available to the queue the message or until a timeout occurs. -

    -

    - mq_timedsend() behaves just like mq_send(), except - that if the queue is full and the O_NONBLOCK flag is not enabled - for the message queue description, then abstime points to a - structure which specifies a ceiling on the time for which the call will block. - This ceiling is an absolute timeout in seconds and nanoseconds since the - Epoch (midnight on the morning of 1 January 1970). -

    -

    - If the message queue is full, and the timeout has already expired by the time - of the call, mq_timedsend() returns immediately. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, mq_send() returns 0 (OK); - on error, -1 (ERROR) is returned, with errno set - to indicate the error: -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. -

    - -

    2.4.5 mq_receive

    -

    - Function Prototype: -

    -
    -    #include <mqueue.h>
-    ssize_t mq_receive(mqd_t mqdes, void *msg, size_t msglen, int *prio);
-
    -

    - Description: - This function receives the oldest of the highest priority messages from the message - queue specified by mqdes. - If the size of the buffer in bytes, msgLen, is less than the - mq_msgsize attribute of the message queue, mq_receive() will - return an error. - Otherwise, the selected message is removed from the queue and copied to msg. -

    -

    - If the message queue is empty and O_NONBLOCK was not set, mq_receive() - will block until a message is added to the message queue. - If more than one task is waiting to receive a message, only the task with the highest - priority that has waited the longest will be unblocked. -

    -

    - If the queue is empty and O_NONBLOCK is set, ERROR will be returned. -

    -

    - Input Parameters: -

    - -

    - Returned Value:. - One success, the length of the selected message in bytes is returned. - On failure, -1 (ERROR) is returned and the errno is set appropriately: -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. -

    - -

    2.4.6 mq_timedreceive

    -

    - Function Prototype: -

    -
    -    #include <mqueue.h>
-    ssize_t mq_timedreceive(mqd_t mqdes, void *msg, size_t msglen,
-                            int *prio, const struct timespec *abstime);
-
    -

    - Description: - This function receives the oldest of the highest priority messages from the message - queue specified by mqdes. - If the size of the buffer in bytes, msgLen, is less than the - mq_msgsize attribute of the message queue, mq_timedreceive() will - return an error. - Otherwise, the selected message is removed from the queue and copied to msg. -

    -

    - If the message queue is empty and O_NONBLOCK was not set, mq_timedreceive() - will block until a message is added to the message queue (or until a timeout occurs). - If more than one task is waiting to receive a message, only the task with the highest - priority that has waited the longest will be unblocked. -

    -

    - mq_timedreceive() behaves just like mq_receive(), except - that if the queue is empty and the O_NONBLOCK flag is not enabled - for the message queue description, then abstime points to a structure - which specifies a ceiling on the time for which the call will block. - This ceiling is an absolute timeout in seconds and nanoseconds since the Epoch - (midnight on the morning of 1 January 1970). -

    -

    - If no message is available, and the timeout has already expired by the time of - the call, mq_timedreceive() returns immediately. -

    -

    - Input Parameters: -

    - -

    - Returned Value:. - One success, the length of the selected message in bytes is returned. - On failure, -1 (ERROR) is returned and the errno is set appropriately: -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. -

    - -

    2.4.7 mq_notify

    - -

    - Function Prototype: -

    -    #include <mqueue.h>
-    int mq_notify(mqd_t mqdes, FAR const struct sigevent *notification);
-
    -

    -

    - Description: If the notification input parameter - is not NULL, this function connects the task with the message queue such - that the specified signal will be sent to the task whenever the message - changes from empty to non-empty. One notification can be attached - to a message queue. -

    -

    - If notification; is NULL, the attached notification - is detached (if it was held by the calling task) and the queue - is available to attach another notification. -

    -

    - When the notification is sent to the registered task, its registration - will be removed. The message queue will then be available for - registration. -

    - Input Parameters: -

    -

    -

    - Returned Value: - On success mq_notify() returns 0; on error, -1 is returned, with - errno set to indicate the error: -

    -

    -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. - Differences from the full POSIX implementation include: -

    -

    - -

    2.4.8 mq_setattr

    - -

    -Function Prototype: -

    -    #include <mqueue.h>
-    int mq_setattr(mqd_t mqdes, const struct mq_attr *mqStat,
-                   struct mq_attr *oldMqStat);
-
    - -

    -Description: This function sets the attributes associated -with the specified message queue "mqdes." Only the "O_NONBLOCK" -bit of the "mq_flags" can be changed. -

    -If "oldMqStat" is non-null, mq_setattr() will store -the previous message queue attributes at that location (just as -would have been returned by mq_getattr()). -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.4.9 mq_getattr

    - -

    -Function Prototype: -

    -    #include <mqueue.h>
-    int mq_getattr(mqd_t mqdes, struct mq_attr *mqStat);
-
    - -

    -Description: This functions gets status information and -attributes associated with the specified message queue. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

    - - - - - -
    -

    2.5 Counting Semaphore Interfaces

     -
    - -

    - Semaphores. Semaphores are the basis for - synchronization and mutual exclusion in NuttX. NuttX supports - POSIX semaphores. -

    -

    - Semaphores are the preferred mechanism for gaining exclusive access to a - resource. sched_lock() and sched_unlock() can also be used for this purpose. - However, sched_lock() and sched_unlock() have other undesirable side-effects - in the operation of the system: sched_lock() also prevents higher-priority - tasks from running that do not depend upon the semaphore-managed resource - and, as a result, can adversely affect system response times. -

    -

    - Priority Inversion. - Proper use of semaphores avoids the issues of sched_lock(). - However, consider the following example: -

      -
    1. Some low-priority task, Task C, acquires a semaphore in order to - get exclusive access to a protected resource.
      2. -
    2. Task C is suspended to allow some high-priority task,
      3. - Task A, to execute. -
    3. Task A attempts to acquire the semaphore held by Task C and - gets blocked until Task C relinquishes the semaphore.
      4. -
    4. Task C is allowed to execute again, but gets suspended by some - medium-priority Task B.
      5. -
    -

    - At this point, the high-priority Task A cannot execute until - Task B (and possibly other medium-priority tasks) completes and until - Task C relinquishes the semaphore. In effect, the high-priority task, - Task A behaves as though it were lower in priority than the - low-priority task, Task C! This phenomenon is called priority - inversion. -

    -

    - Some operating systems avoid priority inversion by automatically - increasing the priority of the low-priority Task C (the operable - buzz-word for this behavior is priority inheritance). NuttX - supports this behavior, but only if CONFIG_PRIORITY_INHERITANCE - is defined in your OS configuration file. If CONFIG_PRIORITY_INHERITANCE - is not defined, then it is left to the designer to provide implementations - that will not suffer from priority inversion. - The designer may, as examples: -

    - -

    - Priority Inheritance. - As mentioned, NuttX does support priority inheritance provided that - CONFIG_PRIORITY_INHERITANCE is defined in your OS configuration file. - However, the implementation and configuration of the priority inheritance feature - is sufficiently complex that more needs to be said. - How can a feature that can be described by a single, simple sentence require such - a complex implementation: -

    - -

    - Locking versus Signaling Semaphores. - Semaphores (and mutexes) may be used for many different purposes. - One typical use is for mutual exclusion and locking of resources: - In this usage, the thread that needs exclusive access to a resources takes the semaphore to get access to the resource. - The same thread subsequently releases the semaphore count when it no longer needs exclusive access. - Priority inheritance is intended just for this usage case. -

    -

    - In a different usage case, a semaphore may to be used to signal an event: - One thread A waits on a semaphore for an event to occur. - When the event occurs, another thread B will post the semaphore waking the waiting thread A. - This is a completely different usage model; notice that in the mutual exclusion case, the same thread takes and posts the semaphore. In the signaling case, one thread takes the semaphore and a different thread posts the semaphore. Priority inheritance should never be used in this signaling case. - Subtle, strange behaviors may result. -

    -

    - When priority inheritance is enabled with CONFIG_PRIORITY_INHERITANCE, the default protocol for the semaphore will be to use priority inheritance. - For signaling semaphores, priority inheritance must be explicitly disabled by calling sem_setprotocol with SEM_PRIO_NONE. - For the case of pthread mutexes, pthread_mutexattr_setprotocol with PTHREAD_PRIO_NONE. -

    -

    - This is discussed in much more detail on this Wiki page. -

    -

    - POSIX semaphore interfaces: -

    - - -

    2.5.1 sem_init

    - -

    -Function Prototype: -

    -    #include <semaphore.h>
-    int sem_init(sem_t *sem, int pshared, unsigned int value);
-
    - -

    -Description: This function initializes the UN-NAMED semaphore -sem. Following a successful call to sem_init(), the semaphore -may be used in subsequent calls to sem_wait(), sem_post(), and -sem_trywait(). The semaphore remains usable until it is destroyed. -

    -Only sem itself may be used for performing synchronization. The -result of referring to copies of sem in calls to sem_wait(), -sem_trywait(), sem_post(), and sem_destroy(), is -not defined. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the full POSIX implementation include: -

    - -

    2.5.2 sem_destroy

    - -

    -Function Prototype: -

    -    #include <semaphore.h>
-    int sem_destroy(sem_t *sem);
-
    - -

    -Description: This function is used to destroy the un-named semaphore -indicated by sem. Only a semaphore that was created using -sem_init() may be destroyed using sem_destroy(). The effect -of calling sem_destroy() with a named semaphore is undefined. The -effect of subsequent use of the semaphore sem is undefined until -sem is re-initialized by another call to sem_init(). -

    -The effect of destroying a semaphore upon which other tasks are currently -blocked is undefined. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.5.3 sem_open

    - -

    -Function Prototype: -

    -    #include <semaphore.h>
-    sem_t *sem_open(const char *name, int oflag, ...);
-
    - -

    -Description: This function establishes a connection between -named semaphores and a task. Following a call to sem_open() with -the semaphore name, the task may reference the semaphore associated -with name using the address returned by this call. The semaphore -may be used in subsequent calls to sem_wait(), sem_trywait(), -and sem_post(). The semaphore remains usable until the semaphore -is closed by a successful call to sem_close(). -

    -If a task makes multiple calls to sem_open() with the same name, -then the same semaphore address is returned (provided there have -been no calls to sem_unlink()). -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the full POSIX implementation include: -

    - -

    2.5.4 sem_close

    - -

    -Function Prototype: -

    -    #include <semaphore.h>
-    int sem_close(sem_t *sem);
-
    - -

    -Description: This function is called to indicate that the -calling task is finished with the specified named semaphore, sem. -The sem_close() deallocates any system resources allocated by -the system for this named semaphore. -

    -If the semaphore has not been removed with a call to sem_unlink(), -then sem_close() has no effect on the named semaphore. However, -when the named semaphore has been fully unlinked, the semaphore -will vanish when the last task closes it. -

    -Care must be taken to avoid risking the deletion of a semaphore -that another calling task has already locked. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.5.5 sem_unlink

    - -

    -Function Prototype: -

    -    #include <semaphore.h>
-    int sem_unlink(const char *name);
-
    - -

    -Description: This function will remove the semaphore named by the -input name parameter. If one or more tasks have the semaphore named by -name open when sem_unlink() is called, destruction of the semaphore will -be postponed until all references have been destroyed by calls to -sem_close(). -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the full POSIX implementation include: -

    - -

    2.5.6 sem_wait

    - -

    -Function Prototype: -

    -    #include <semaphore.h>
-    int sem_wait(sem_t *sem);
-
    - -

    -Description: This function attempts to lock the semaphore -referenced by sem. If the semaphore as already locked by another -task, the calling task will not return until it either successfully acquires -the lock or the call is interrupted by a signal. -

    -Input Parameters: -

    - -

    -Returned Value: -

    -

    -If sem_wait returns -1 (ERROR) then the cause of the failure -will be indicated by the thread-specific errno. -The following lists the possible values for errno: -

    -

    -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.5.7 sem_timedwait

    - -

    -Function Prototype: -

    -    #include <semaphore.h>
-    int sem_timedwait(sem_t *sem, const struct timespec *abstime);
-
    - -

    -Description: - This function will lock the semaphore referenced by sem as in the sem_wait() function. - However, if the semaphore cannot be locked without waiting for another process or thread to unlock the semaphore by performing a sem_post() function, this wait will be terminated when the specified timeout expires. -

    - The timeout will expire when the absolute time specified by abstime passes, as measured by the clock on which timeouts are based (that is, when the value of that clock equals or exceeds abstime), or if the absolute time specified by abstime has already been passed at the time of the call. - This function attempts to lock the semaphore referenced by sem. - If the semaphore is already locked by another task, the calling task will not return until it either successfully acquires the lock or the call is interrupted by a signal. -

    -Input Parameters: -

    - -

    -Returned Value: -

    -

    -If sem_timedwait returns -1 (ERROR) then the cause of the failure -will be indicated by the thread-specific errno. -The following lists the possible values for errno: -

    -

    -
  • - EINVAL: - Indicates that the sem input parameter is not valid or the - thread would have blocked, and the abstime parameter specified - a nanoseconds field value less than zero or greater than or - equal to 1000 million. -
    • -
  • - ETIMEDOUT: - The semaphore could not be locked before the specified timeout expired. -
    • -
  • - EDEADLK: - A deadlock condition was detected. -
    • -
  • - EINTR: - Indicates that the wait was interrupt by a signal received by this task. - In this case, the semaphore has not be acquired. -
    • - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Derived from IEEE Std 1003.1d-1999. -

    - -

    2.5.8 sem_trywait

    - -

    -Function Prototype: -

    -    #include <semaphore.h>
-    int sem_trywait(sem_t *sem);
-
    - -

    -Description: This function locks the specified semaphore -only if the semaphore is currently not locked. In any event, the call -returns without blocking. -

    -Input Parameters: -

    - -

    -Returned Value: -

    -If sem_trywait returns -1 (ERROR) then the cause of the failure -will be indicated by the thread-specific errno. -The following lists the possible values for errno: -

    -

    -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.5.9 sem_post

    - -

    -Function Prototype: -

    -    #include <semaphore.h>
-    int sem_post(sem_t *sem);
-
    - -

    -Description: When a task has finished with a semaphore, -it will call sem_post(). This function unlocks the semaphore referenced -by sem by performing the semaphore unlock operation. -

    -If the semaphore value resulting from this operation is positive, then -no tasks were blocked waiting for the semaphore to become unlocked; -The semaphore value is simply incremented. -

    -If the value of the semaphore resulting from this operation is zero, then -on of the tasks blocked waiting for the semaphore will be allowed to -return successfully from its call to sem_wait(). -

    -NOTE: sem_post() may be called from an interrupt handler. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations:. -When called from an interrupt handler, it will appear as though the -interrupt task is the one that is performing the unlock. -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.5.10 sem_getvalue

    - -

    -Function Prototype: -

    -    #include <semaphore.h>
-    int sem_getvalue(sem_t *sem, int *sval);
-
    - -

    -Description: This function updates the location referenced -by sval argument to have the value of the semaphore referenced -by sem without effecting the state of the semaphore. The updated -value represents the actual semaphore value that occurred at some -unspecified time during the call, but may not reflect the actual -value of the semaphore when it is returned to the calling task. -

    -If sem is locked, the value return by sem_getvalue() will either -be zero or a negative number whose absolute value represents the -number of tasks waiting for the semaphore. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

    - -

    2.5.11 sem_getprotocol

    -

    -Function Prototype: -

    -

    -    #include <nuttx/semaphore.h>
-    int sem_getprotocol(FAR const pthread_mutexattr_t *attr, FAR int *protocol);
-
    -

    -Description: Return the value of the semaphore protocol attribute. -

    -

    -Input Parameters: -

    -

    -

    -

    -

    -Returned Value: -

    -

    -If successful, the sem_getprotocol() function will return zero (OK). -Otherwise, an -1 (ERROR) will be returned and the errno value will be set to indicate the nature of the error. -

    -

    -Assumptions/Limitations: -

    -

    -POSIX Compatibility: Non-standard NuttX interface. Should not be used in portable code. Analogous to pthread_muxtexattr_getprotocol(). -

    - -

    2.5.12 sem_setprotocol

    -

    -Function Prototype: -

    -

    -    #include <nuttx/semaphore.h>
-    int sem_setprotocol(FAR pthread_mutexattr_t *attr, int protocol);
-
    -

    -Description: Set semaphore protocol attribute. See the paragraph Locking versus Signaling Semaphores for some important information about the use of this interface. - -

    -

    -Input Parameters: -

    -

    -

    -

    -

    -Returned Value: -

    -

    -If successful, the sem_setprotocol() function will return zero (OK). -Otherwise, an -1 (ERROR) will be returned and the errno value will be set to indicate the nature of the error. -

    -

    -Assumptions/Limitations: -

    -

    -POSIX Compatibility: Non-standard NuttX interface. Should not be used in portable code. Analogous to pthread_muxtexattr_setprotocol(). -

    - - - - - -
    -

    2.6 Clocks and Timers

     -
    - - - -

    2.6.1 clock_settime

    -

    - Function Prototype: -

    -
    -    #include <time.h>
-    int clock_settime(clockid_t clockid, const struct timespec *tp);
-
    -

    - Description: -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the clock_settime() function will return zero (OK). - Otherwise, an non-zero error number will be returned to indicate the error: -

    - -

    2.6.2 clock_gettime

    -

    - Function Prototype: -

    -
    -    #include <time.h>
-    int clock_gettime(clockid_t clockid, struct timespec *tp);
-
    -

    - Description: -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the clock_gettime() function will return zero (OK). - Otherwise, an non-zero error number will be returned to indicate the error: -

    - -

    2.6.3 clock_getres

    -

    - Function Prototype: -

    -
    -    #include <time.h>
-    int clock_getres(clockid_t clockid, struct timespec *res);
-
    -

    - Description: -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the clock_getres() function will return zero (OK). - Otherwise, an non-zero error number will be returned to indicate the error: -

    - -

    2.6.4 mktime

    -

    - Function Prototype: -

    -
    -    #include <time.h>
-    time_t mktime(struct tm *tp);
-
    -

    - Description: -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the mktime() function will return zero (OK). - Otherwise, an non-zero error number will be returned to indicate the error: -

    - -

    2.6.5 gmtime

    -

    - Function Prototype: -

    -
    -    #include <time.h>
-    FAR struct tm *gmtime(FAR const time_t *timep);
-
    -

    - Description: - Represents GMT date/time in a type struct tm. - This function is not re-entrant. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the gmtime() function will return the pointer to a statically defined instance of struct tm. - Otherwise, a NULL will be returned to indicate the error: -

    - -

    2.6.6 localtime

    - -

    - Description: - Represents local date/time in a type struct tm. - This function is not re-entrant. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - Returned Value: - If successful, the localtime() function will return the pointer to a statically defined instance of struct tm. - Otherwise, a NULL will be returned to indicate the error: -

    - -

    2.6.7 asctime

    -

    - Function Prototype: -

    - -

    - Description: - asctime() convert the time provided in a struct tm to a string representation. - asctime() is not re-entrant. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the asctime() function will return a pointer to a statically defined string holding the converted time. - Otherwise, a NULL will be returned to indicate the error. -

    - -

    2.6.8 ctime

    -

    - Function Prototype: -

    - -

    - Description: - ctime() converts the time provided in seconds since the epoch to a string representation. - ctime() is not re-entrant. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the ctime() function will return the pointer to the converted string. - Otherwise, a NULL will be returned to indicate the error. -

    - -

    2.6.9 gmtime_r

    -

    - Function Prototype: -

    -
    -    #include <time.h>
-    struct tm *gmtime_r(const time_t *timep, struct tm *result);
-
    -

    - Description: - Represents GMT date/time in a type struct tm. - This function is re-entrant. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the gmtime_r() function will return the pointer, result, - provided by the caller. - Otherwise, a NULL will be returned to indicate the error: -

    - -

    2.6.10 localtime_r

    - -

    - Description: - Represents local date/time in a type struct tm. - This function is re-entrant. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - Returned Value: - If successful, the localtime_r() function will return the pointer, result, - provided by the caller. - Otherwise, a NULL will be returned to indicate the error: -

    - -

    2.6.11 asctime_r

    -

    - Function Prototype: -

    - -

    - Description: - asctime_r() converts the time provided in a struct tm to a string representation. - asctime-r() is re-entrant. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the asctime_r() function will return the pointer, buf, provided by the caller. - Otherwise, a NULL will be returned to indicate the error. -

    - -

    2.6.12 ctime_r

    -

    - Function Prototype: -

    - -

    - Description: - ctime_r() converts the time provided in seconds since the epoch to a string representation. - ctime() is re-entrant. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the ctime_r() function will return the pointer, buf, provided by the caller. - Otherwise, a NULL will be returned to indicate the error. -

    - -

    2.6.13 timer_create

    -

    - Function Prototype: -

    -
    -    #include <time.h>
-    int timer_create(clockid_t clockid, struct sigevent *evp, timer_t *timerid);
-
    -

    - Description: - The timer_create() function creates per-thread timer using the specified - clock, clock_id, as the timing base. - The timer_create() function returns, in - the location referenced by timerid, a timer ID of type timer_t used to identify - the timer in timer requests. - This timer ID is unique until the timer is deleted. - The particular clock, clock_id, is defined in <time.h>. - The timer whose ID is returned will be in a disarmed state upon return from - timer_create(). -

    -

    - The evp argument, if non-NULL, points to a sigevent structure. - This structure is allocated by the called and defines the asynchronous notification to occur. - If the evp argument is NULL, the effect is as if the evp argument pointed to - a sigevent structure with the sigev_notify member having the value SIGEV_SIGNAL, - the sigev_signo having a default signal number, and the sigev_value member - having the value of the timer ID. -

    -

    - Each implementation defines a set of clocks that can be used as timing bases - for per-thread timers. All implementations will support a clock_id of - CLOCK_REALTIME. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If the call succeeds, timer_create() will return 0 (OK) and update the - location referenced by timerid to a timer_t, which can be passed to the - other per-thread timer calls. If an error occurs, the function will return - a value of -1 (ERROR) and set errno to indicate the error. -

    - -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include: -

    - - -

    2.6.14 timer_delete

    -

    - Function Prototype: -

    -
    -    #include <time.h>
-    int timer_delete(timer_t timerid);
-
    -

    - Description: - The timer_delete() function deletes the specified timer, timerid, previously - created by the timer_create() function. - If the timer is armed when timer_delete() is called, the timer will be automatically disarmed before - removal. - The disposition of pending signals for the deleted timer is unspecified. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the timer_delete() function will return zero (OK). - Otherwise, the function will return a value of -1 (ERROR) and set - errno to indicate the error: -

    - -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. -

    - -

    2.6.15 timer_settime

    -

    - Function Prototype: -

    -
    -    #include <time.h>
-    int timer_settime(timer_t timerid, int flags, const struct itimerspec *value,
-                      struct itimerspec *ovalue);
-
    -

    - Description: - The timer_settime() function sets the time until the next expiration of the - timer specified by timerid from the it_value member of the value argument - and arm the timer if the it_value member of value is non-zero. If the - specified timer was already armed when timer_settime() is called, this call - will reset the time until next expiration to the value specified. If the - it_value member of value is zero, the timer will be disarmed. The effect - of disarming or resetting a timer with pending expiration notifications is - unspecified. -

    -

    - If the flag TIMER_ABSTIME is not set in the argument flags, timer_settime() - will behave as if the time until next expiration is set to be equal to the - interval specified by the it_value member of value. That is, the timer will - expire in it_value nanoseconds from when the call is made. If the flag - TIMER_ABSTIME is set in the argument flags, timer_settime() will behave as - if the time until next expiration is set to be equal to the difference between - the absolute time specified by the it_value member of value and the current - value of the clock associated with timerid. That is, the timer will expire - when the clock reaches the value specified by the it_value member of value. - If the specified time has already passed, the function will succeed and the - expiration notification will be made. -

    -

    - The reload value of the timer will be set to the value specified by the - it_interval member of value. When a timer is armed with a non-zero - it_interval, a periodic (or repetitive) timer is specified. -

    -

    - Time values that are between two consecutive non-negative integer multiples - of the resolution of the specified timer will be rounded up to the larger - multiple of the resolution. Quantization error will not cause the timer to - expire earlier than the rounded time value. -

    -

    - If the argument ovalue is not NULL, the timer_settime() function will store, - in the location referenced by ovalue, a value representing the previous - amount of time before the timer would have expired, or zero if the timer was - disarmed, together with the previous timer reload value. Timers will not - expire before their scheduled time. -

    - NOTE:At present, the ovalue argument is ignored. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If the timer_gettime() succeeds, a value of 0 (OK) will be returned. - If an error occurs, the value -1 (ERROR) will be returned, and - errno set to indicate the error. -

    - -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include: -

    - - -

    2.6.16 timer_gettime

    -

    - Function Prototype: -

    -
    -    #include <time.h>
-    int timer_gettime(timer_t timerid, struct itimerspec *value);
-
    -

    - Description: - The timer_gettime() function will store the amount of time until the - specified timer, timerid, expires and the reload value of the timer into the - space pointed to by the value argument. The it_value member of this structure - will contain the amount of time before the timer expires, or zero if the timer - is disarmed. This value is returned as the interval until timer expiration, - even if the timer was armed with absolute time. The it_interval member of - value will contain the reload value last set by timer_settime(). -

    -

    - Due to the asynchronous operation of this function, the time reported - by this function could be significantly more than that actual time - remaining on the timer at any time. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If successful, the timer_gettime() function will return zero (OK). - Otherwise, an non-zero error number will be returned to indicate the error: -

    - -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. -

    - -

    2.6.17 timer_getoverrun

    -

    - Function Prototype: -

    -
    -    #include <time.h>
-    int timer_getoverrun(timer_t timerid);
-
    -

    - Description: - Only a single signal will be queued to the process for a given timer at any - point in time. When a timer for which a signal is still pending expires, no - signal will be queued, and a timer overrun will occur. When a timer - expiration signal is delivered to or accepted by a process, if the - implementation supports the Realtime Signals Extension, the - timer_getoverrun() function will return the timer expiration overrun count for - the specified timer. The overrun count returned contains the number of extra - timer expirations that occurred between the time the signal was generated - (queued) and when it was delivered or accepted, up to but not including an - implementation-defined maximum of DELAYTIMER_MAX. If the number of such - extra expirations is greater than or equal to DELAYTIMER_MAX, then the - overrun count will be set to DELAYTIMER_MAX. The value returned by - timer_getoverrun() will apply to the most recent expiration signal delivery - or acceptance for the timer. If no expiration signal has been delivered - for the timer, or if the Realtime Signals Extension is not supported, the - return value of timer_getoverrun() is unspecified. -

    -

    - NOTE: This interface is not currently implemented in NuttX. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - If the timer_getoverrun() function succeeds, it will return the timer - expiration overrun count as explained above. timer_getoverrun() will fail if: -

    - -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include: -

    - - -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

    - -

    2.6.18 gettimeofday

    -

    - Function Prototype: -

    -
    -    #include <sys/time.h>
-    int gettimeofday(struct timeval *tp, void *tzp);
-
    -

    - Description: - This implementation of gettimeofday() is simply a thin wrapper around - clock_gettime(). - It simply calls clock_gettime() using the CLOCK_REALTIME timer and - converts the result to the required struct timeval. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - See clock_gettime(). -

    - - - - - -
    -

    2.7 Signal Interfaces

     -
    - -

    - Tasks and Signals. - NuttX provides signal interfaces for tasks and pthreads. - Signals are used to alter the flow control of tasks by communicating asynchronous events within or between task contexts. - Any task or interrupt handler can post (or send) a signal to a particular task using its task ID. - The task being signaled will execute task-specified signal handler function the next time that the task has priority. - The signal handler is a user-supplied function that is bound to a specific signal and performs whatever actions are necessary whenever the signal is received. -

    -

    - By default, here are no predefined actions for any signal. - The default action for all signals (i.e., when no signal handler has been supplied by the user) is to ignore the signal. - In this sense, all NuttX are real time signals by default. - If the configuration option CONFIG_SIG_DEFAULT=y is included, some signals will perform their default actions dependent upon addition configuration settings as summarized in the following table: -

    -

    -

    - Tasks may also suspend themselves and wait until a signal is received. -

    -

    - Tasks Groups. - NuttX supports both tasks and pthreads. - The primary difference between tasks and pthreads is the tasks are much more independent. - Tasks can create pthreads and those pthreads will share the resources of the task. - The main task and its children pthreads together are referred as a task group. - A task group is used in NuttX to emulate a POSIX process. -

    -
    - NOTE: - Behavior of features related to task groups depend of NuttX configuration settings. - See also the NuttX Tasking page and the Tasks vs. Threads FAQ for additional information on tasks and threads in NuttX. -
    -

    - Signaling Multi-threaded Task Groups. - The behavior of signals in the multi-thread task group is complex. - NuttX emulates a process model with task groups and follows the POSIX rules for signaling behavior. - Normally when you signal the task group you would signal using the task ID of the main task that created the group (in practice, a different task should not know the IDs of the internal threads created within the task group); that ID is remembered by the task group (even if the main task thread exits). -

    -

    - Here are some of the things that should happen when you signal a multi-threaded task group: -

    - -

    - You can mask out that signal using ''sigprocmask()'' (or ''pthread_sigmask()''). - That signal will then be effectively disabled and will never be received in those threads that have the signal masked. - On creation of a new thread, the new thread will inherit the signal mask of the parent thread that created it. - So you if block signal signals on one thread then create new threads, those signals will also be blocked in the new threads as well. -

    -

    - You can control which thread receives the signal by controlling the signal mask. - You can, for example, create a single thread whose sole purpose it is to catch a particular signal and respond to it: Simply block the signal in the main task; then the signal will be blocked in all of the pthreads in the group too. In the one "signal processing" pthread, enable the blocked signal. This thread will then be only thread that will receive the signal. -

    -

    - Signal Interfaces. - The following signal handling interfaces are provided by NuttX: -

    - - -

    2.7.1 sigemptyset

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigemptyset(sigset_t *set);
-
    - -

    -Description: This function initializes the signal set specified -by set such that all signals are excluded. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.7.2 sigfillset

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigfillset(sigset_t *set);
-
    - -

    -Description: This function initializes the signal set specified -by set such that all signals are included. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.7.3 sigaddset

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigaddset(sigset_t *set, int signo);
-
    - -

    -Description: This function adds the signal specified by -signo to the signal set specified by set. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.7.4 sigdelset

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigdelset(sigset_t *set, int signo);
-
    - -

    -Description: This function deletes the signal specified -by signo from the signal set specified by set. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.7.5 sigismember

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int  sigismember(const sigset_t *set, int signo);
-
    - -

    -Description: This function tests whether the signal specified -by signo is a member of the set specified by set. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.7.6 sigaction

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigaction(int signo, const struct sigaction *act,
-                  struct sigaction *oact);
-
    - -

    -Description: This function allows the calling task to -examine and/or specify the action to be associated with a specific -signal. -

    -The structure sigaction, used to describe an action to be taken, is defined -to include the following members: -

    -

    -If the argument act is not NULL, it points to a structure specifying the -action to be associated with the specified signal. If the argument oact -is not NULL, the action previously associated with the signal is stored -in the location pointed to by the argument oact. If the argument act is -NULL, signal handling is unchanged by this function call; thus, the call -can be used to inquire about the current handling of a given signal. -

    -When a signal is caught by a signal-catching function installed by the -sigaction() function, a new signal mask is calculated and installed for -the duration of the signal-catching function. This mask is formed by taking -the union of the current signal mask and the value of the sa_mask for the -signal being delivered, and then including the signal being delivered. If -and when the signal handler returns, the original signal mask is restored. -

    -Signal catching functions execute in the same address environment as the -task that called sigaction() to install the signal-catching function. -

    -Once an action is installed for a specific signal, it remains installed -until another action is explicitly requested by another call to -sigaction(). -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the POSIX implementation include: -

    - -

    2.7.7 sigignore

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigignore(int signo);
-
    - -

    -Description: The sigignore() function will set the disposition of signo to SIG_IGN. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    2.7.8 sigset

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    void (*sigset(int signo, void (*disp)(int)))(int);
-
    - -

    -Description: - The sigset() function will modify signal dispositions. - The signo argument specifies the signal. - The disp argument specifies the signal's disposition, which may be SIG_DFL, SIG_IGN, or the address of a signal handler. - If disp is the address of a signal handler, the system will add signo to the calling process's signal mask before executing the signal handler; when the signal handler returns, the system will restore the calling process's signal mask to its state prior to the delivery of the signal. - signo will be removed from the calling process's signal mask. -

    -

    - NOTE: The value SIG_HOLD for disp is not currently supported. -

    -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    2.7.9 sigprocmask

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigprocmask(int how, const sigset_t *set, sigset_t *oset);
-
    - -

    -Description: This function allows the calling task to -examine and/or change its signal mask. If the set is not NULL, -then it points to a set of signals to be used to change the currently -blocked set. The value of how indicates the manner in which the -set is changed. -

    -If there are any pending unblocked signals after the call to sigprocmask(), -those signals will be delivered before sigprocmask() returns. -

    -If sigprocmask() fails, the signal mask of the task is not changed. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.7.10 sighold

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sighold(int signo);
-
    - -

    -Description: The sighold() function will add signo to the calling process's signal mask -

    -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    2.7.11 sigrelse

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigrelse(int signo);
-
    - -

    -Description: The sighold() function will remove signo from the calling process's signal mask -

    -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    2.7.12 sigpending

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigpending(sigset_t *set);
-
    - -

    -Description: This function stores the returns the set of -signals that are blocked for delivery and that are pending for -the calling task in the space pointed to by set. -

    -If the task receiving a signal has the signal blocked via its -sigprocmask, the signal will pend until it is unmasked. Only one pending -signal (for a given signo) is retained by the system. This is consistent -with POSIX which states: "If a subsequent occurrence of a pending -signal is generated, it is implementation defined as to whether the signal -is delivered more than once." -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.7.13 sigsuspend

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigsuspend(const sigset_t *set);
-
    - -

    -Description: The sigsuspend() function replaces the signal mask -with the set of signals pointed to by the argument set and then suspends -the task until delivery of a signal to the task. -

    -If the effect of the set argument is to unblock a pending signal, then -no wait is performed. -

    -The original signal mask is restored when sigsuspend() returns. -

    -Waiting for an empty signal set stops a task without freeing any -resources (a very bad idea). -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the POSIX specification include: -

    - -

    2.7.14 sigpause

    -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigpause(int signo);
-
    - -

    -Description: The sigpause()) function will remove signo) from the calling process's signal mask and suspend the calling process until a signal is received. -The sigpause()) function will restore the process's signal mask to its original state before returning. -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    2.7.15 sigwaitinfo

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigwaitinfo(const sigset_t *set, struct siginfo *info);
-
    - -

    -Description: This function is equivalent to sigtimedwait() -with a NULL timeout parameter. (see below). -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. - -

    2.7.16 sigtimedwait

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigtimedwait(const sigset_t *set, struct siginfo *info,
-                     const struct timespec *timeout);
-
    - -

    -Description: This function selects the pending signal set -specified by the argument set. If multiple signals are pending in set, -it will remove and return the lowest numbered one. If no signals in set -are pending at the time of the call, the calling task will be suspended -until one of the signals in set becomes pending OR until the task -interrupted by an unblocked signal OR until the time interval specified by -timeout (if any), has expired. If timeout is NULL, then the timeout interval -is forever. -

    -If the info argument is non-NULL, the selected signal number is -stored in the si_signo member and the cause of the signal is store -in the si_code member. The content of si_value is only meaningful -if the signal was generated by sigqueue(). The following values -for si_code are defined in signal.h: -

    - -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the POSIX interface include: -

    - -

    2.7.17 sigqueue

    - -

    -Function Prototype: -

    -    #include <signal.h>
-    int sigqueue (int tid, int signo, union sigval value);
-
    - -

    -Description: This function sends the signal specified by -signo with the signal parameter value to the task specified -by tid. -

    -If the receiving task has the signal blocked via its sigprocmask, -the signal will pend until it is unmasked. Only one pending signal -(for a given signo) is retained by the system. This is consistent with -POSIX which states: "If a subsequent occurrence of a pending signal -is generated, it is implementation defined as to whether the signal -is delivered more than once." -

    -Input Parameters: -

    - -

    -Returned Value: -

    - -

    -Assumptions/Limitations: -

    - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the POSIX interface include: -

    - -

    2.7.18 kill

    - -

    -Function Prototype: -

    -   #include <sys/types.h>
-   #include <signal.h>
-   int kill(pid_t pid, int sig);
-
    - -

    -Description: - The kill() system call can be used to send any signal to - any task. -

    -

    - If the receiving task has the signal blocked via its sigprocmask, - the signal will pend until it is unmasked. Only one pending signal - (for a given signo) is retained by the system. This is consistent with - POSIX which states: "If a subsequent occurrence of a pending signal - is generated, it is implementation defined as to whether the signal - is delivered more than once." -

    -

    -Input Parameters: -

    - -

    - Returned Value: -

    -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. - Differences from the POSIX interface include: -

    - - -

    2.7.19 pause

    - -

    -Function Prototype: -

    -   #include <unistd.h>
-   int pause(void);
-
    - -

    -Description: - The pause() function will suspend the calling thread until delivery of a non-blocked signal. -

    -Input Parameters: - - -

    - Returned Value: - Since pause() suspends thread execution indefinitely unless interrupted a signal, there is no successful completion return value. - A value of -1 (ERROR will always be returned and errno set to indicate the error (EINTR). -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - In the POSIX description of this function is the pause() function will suspend the calling thread until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process. - This implementation only waits for any non-blocked signal to be received. -

    - - - - - -
    -

    2.8 Pthread Interfaces

     -
    - -

    - NuttX does not support processes in the way that, say, Linux does. - NuttX only supports simple threads or tasks running within the same address space. - However, NuttX does support the concept of a task group. - A task group is the functional analog of a process: - It is a group that consists of the main task thread and of all of the pthreads created by the main thread or any of the other pthreads within the task group. - Members of a task group share certain resources such as environment variables, file descriptors, FILE streams, sockets, pthread keys and open message queues. -

    -
    - NOTE: - Behavior of features related to task groups depend of NuttX configuration settings. - See also the NuttX Tasking page and the Tasks vs. Threads FAQ for additional information on tasks and threads in NuttX. -
    -

    - The following pthread interfaces are supported in some form by NuttX: -

    - -

    - No support for the following pthread interfaces is provided by NuttX: -

    - - -

    2.8.1 pthread_attr_init

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_attr_init(pthread_attr_t *attr);
-
    -

    -Description: -Initializes a thread attributes object (attr) with default values -for all of the individual attributes used by the implementation. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_attr_init() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

    -

    2.8.2 pthread_attr_destroy

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_attr_destroy(FAR pthread_attr_t *attr);
-
    -

    -Description: -An attributes object can be deleted when it is no longer needed. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_attr_destroy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

    -

    2.8.3 pthread_attr_setschedpolicy

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_attr_setschedpolicy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.4 pthread_attr_getschedpolicy

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_attr_getschedpolicy(FAR const pthread_attr_t *attr, FAR int *policy);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_attr_getschedpolicy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.5 pthread_attr_getschedpolicy

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_attr_setschedparam(pthread_attr_t *attr,
-                                   const struct sched_param *param);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_attr_getschedpolicy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.6 pthread_attr_getschedparam

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_attr_getschedparam(pthread_attr_t *attr,
-                                   struct sched_param *param);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_attr_getschedparam() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.7 pthread_attr_setinheritsched

    -

    -Function Prototype: -

    -

    -   #include <pthread.h>
-    int pthread_attr_setinheritsched(pthread_attr_t *attr,
-                                     int inheritsched);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_attr_setinheritsched() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

    -

    2.8.8 pthread_attr_getinheritsched

    -

    -Function Prototype: -

    -

    -   #include <pthread.h>
-     int pthread_attr_getinheritsched(const pthread_attr_t *attr,
-                                      int *inheritsched);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_attr_getinheritsched() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.9 pthread_attr_setstacksize

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_attr_setstacksize(pthread_attr_t *attr, long stacksize);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_attr_setstacksize() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.10 pthread_attr_getstacksize

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_attr_getstacksize(FAR const pthread_attr_t *attr, FAR size_t *stackaddr);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_attr_getstacksize() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.11 pthread_create

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_create(pthread_t *thread, pthread_attr_t *attr,
-                       pthread_startroutine_t startRoutine,
-                       pthread_addr_t arg);
-
    -

    -Description: -To create a thread object and runnable thread, a routine -must be specified as the new thread's start routine. An -argument may be passed to this routine, as an untyped -address; an untyped address may also be returned as the -routine's value. An attributes object may be used to -specify details about the kind of thread being created. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_create() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.12 pthread_detach

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_detach(pthread_t thread);
-
    -

    -Description: -A thread object may be "detached" to specify that the -return value and completion status will not be requested. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_detach() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.13 pthread_exit

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    void pthread_exit(pthread_addr_t pvValue);
-
    -

    -Description: -A thread may terminate it's own execution. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_exit() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.14 pthread_cancel

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_cancel(pthread_t thread);
-
    -

    -Description: - -

    The pthread_cancel() function will request that thread be canceled. -The target thread's cancellability state, enabled, or disabled, determines when the cancellation takes effect: When the cancellation is acted on, thread will be terminated. -When cancellability is disabled, all cancellations are held pending in the target thread until the thread re-enables cancellability.

    - -

    The target thread's cancellability state determines how the cancellation is acted on: -Either asynchronously or deferred. -Asynchronous cancellations will be acted upon immediately (when enabled), interrupting the thread with its processing in an arbitrary state.

    - -

    When cancellability is deferred, all cancellations are held pending in the target thread until the thread changes the cancellability type or a Cancellation Point function such as pthread_testcancel() is entered.

    - -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_cancel() function will return zero (OK). -Otherwise, an error number will be returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX interface of the same name. Except:

    - - -

    2.8.15 pthread_setcancelstate

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_setcancelstate(int state, int *oldstate);
-
    -

    -Description: -

    -

    -The pthread_setcancelstate() function atomically -sets both the calling thread's cancellability state to the indicated -state and returns the previous cancellability state at the location -referenced by oldstate. -Legal values for state are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE. -

    -

    -Any pending thread cancellation may occur at the time that the -cancellation state is set to PTHREAD_CANCEL_ENABLE. -

    -

    -Input Parameters: -

    -

    -

    -

    -

    -Returned Value: -

    -If successful, the pthread_setcancelstate() function will return -zero (OK). Otherwise, an error number will be returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.16 pthread_setcanceltype

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_setcanceltype(int type, FAR int *oldtype);
-
    -

    -Description: -The pthread_setcanceltype() function atomically both sets the calling thread's cancellability type to the indicated type and returns the previous cancellability type at the location referenced by oldtype. -Legal values for type are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS. -

    -

    -The cancellability state and type of any newly created threads are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED respectively. -

    -

    -Input Parameters: -

    -

    -

    -

    -

    -Returned Value: -

    -If successful, the pthread_setcancelstate() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error. -

    -

    -POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.17 pthread_testcancel

    -

    -Function Prototype: -

    -

    -

    -    #include <pthread.h>
-    void pthread_testcancel(void);
-
    -

    -

    -Description: -

    -

    -The pthread_testcancel() function creates a Cancellation Point in the calling thread. -The pthread_testcancel() function has no effect if cancellability is disabled. -

    -

    -Input Parameters: None -

    -

    -Returned Value: None -

    -

    -POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.18 pthread_cleanup_pop

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    void pthread_cleanup_pop(int execute);
-
    -

    -Description: -

    -

    -The pthread_cleanup_pop() function will remove the routine at the top of the calling thread's cancellation cleanup stack and optionally invoke it (if execute is non-zero). -

    -

    -Input Parameters: -

    -

    -

    -

    -

    -Returned Value: -

    -

    -If successful, the pthread_setcancelstate() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -

    -POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.19 pthread_cleanup_push

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    void pthread_cleanup_push(CODE void (*routine)(FAR void *), FAR void *arg);
-
    -

    -Description: -

    -

    -The pthread_cleanup_push() function will push the specified cancellation cleanup handler routine onto the calling thread's cancellation cleanup stack. -

    -

    -The cancellation cleanup handler will be popped from the cancellation cleanup stack and invoked with the argument arg when: -

    -

    -

    -

    -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_setcancelstate() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error. -

    -

    -POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.20 pthread_join

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_join(pthread_t thread, pthread_addr_t *ppvValue);
-
    -

    -Description: -A thread can await termination of another thread and retrieve -the return value of the thread. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_join() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.21 pthread_yield

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    void pthread_yield(void);
-
    -

    -Description: -A thread may tell the scheduler that its processor can be -made available. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: This call is nonstandard, but present on several -other systems. Use the POSIX sched_yield() instead. - -

    2.8.22 pthread_self

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    pthread_t pthread_self(void);
-
    -

    -Description: -A thread may obtain a copy of its own thread handle. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_self() function will return -copy of caller's thread handle. Otherwise, in exceptional circumstances, -the negated error code -ESRCH can be returned if the system -cannot deduce the identity of the calling thread. -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. The -ESRCH return value is -non-standard; POSIX says pthread_self() must always succeed. -NuttX implements pthread_self() as a macro only, not as a -function as required by POSIX. -

    - -

    2.8.23 pthread_getschedparam

    -

    - Function Prototype: -

    -
    -    #include <pthread.h>
-    int pthread_getschedparam(pthread_t thread, int *policy,
-                              struct sched_param *param);
-
    -

    - Description: - The pthread_getschedparam() functions will get the - scheduling policy and parameters of threads. - For SCHED_FIFO and SCHED_RR, the only - required member of the sched_param structure is the - priority sched_priority. -

    -

    - The pthread_getschedparam() function will retrieve the - scheduling policy and scheduling parameters for the thread whose thread - ID is given by thread and will store those values in - policy and param, respectively. - The priority value returned from pthread_getschedparam() - will be the value specified by the most recent pthread_setschedparam(), - pthread_setschedprio(), or pthread_create() call - affecting the target thread. - It will not reflect any temporary adjustments to its priority (such as might - result of any priority inheritance, for example). -

    -

    - The policy parameter may have the value SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC. - SCHED_RR requires the configuration setting CONFIG_RR_INTERVAL > 0; - SCHED_SPORADIC requires the configuration setting CONFIG_SCHED_SPORADIC=y. - (SCHED_OTHER and non-standard scheduler policies, in particular, are not supported). - The SCHED_FIFO and SCHED_RR policies will have a single - scheduling parameter: -

    - - -

    - The SCHED_SPORADIC policy has four additional scheduling parameters: -

    - -

    - Input Parameters: -

    - -

    - Returned Value: - 0 (OK) if successful. - Otherwise, the error code ESRCH if the value specified by - thread does not refer to an existing thread. -

    -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. -

    - -

    2.8.24 pthread_setschedparam

    -

    - Function Prototype: -

    -
    -    #include <pthread.h>
-    int pthread_setschedparam(pthread_t thread, int policy,
-                              const struct sched_param *param);
-
    -

    - Description: - The pthread_setschedparam() functions will set the scheduling policy - and parameters of threads. - For SCHED_FIFO and SCHED_RR, the only required member - of the sched_param structure is the priority sched_priority. -

    -

    - The pthread_setschedparam() function will set the scheduling policy - and associated scheduling parameters for the thread whose thread ID is given by - thread to the policy and associated parameters provided in - policy and param, respectively. -

    -

    - The policy parameter may have the value SCHED_FIFO or SCHED_RR. - (SCHED_OTHER and SCHED_SPORADIC, in particular, are not supported). - The SCHED_FIFO and SCHED_RR policies will have a single - scheduling parameter, sched_priority. -

    -

    - If the pthread_setschedparam() function fails, the scheduling - parameters will not be changed for the target thread. -

    -

    - Input Parameters: -

    - -

    - Returned Value: -

    -

    - If successful, the pthread_setschedparam() function will return - zero (OK). Otherwise, an error number will be - returned to indicate the error: -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: - Comparable to the POSIX interface of the same name. -

    - -

    2.8.25 pthread_key_create

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_key_create(pthread_key_t *key, void (*destructor)(void*))
-
    -

    -Description: -

    -

    -This function creates a thread-specific data key visible -to all threads in the system. Although the same key value -may be used by different threads, the values bound to -the key by pthread_setspecific() are maintained on a -per-thread basis and persist for the life of the calling -thread. -

    -

    -Upon key creation, the value NULL will be associated with -the new key in all active threads. Upon thread -creation, the value NULL will be associated with all -defined keys in the new thread. -

    -

    -Input Parameters: -

    -

    -

    -

    -

    -Returned Value: -

    -

    -If successful, the pthread_key_create() function will -store the newly created key value at *key and return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -

    -Assumptions/Limitations: -

    -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

    -

    - -

    2.8.26 pthread_setspecific

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_setspecific(pthread_key_t key, void *value)
-
    -

    -Description: -

    -The pthread_setspecific() function associates a thread-specific -value with a key obtained via a previous call to pthread_key_create(). -Different threads may bind different values to the same key. These values are -typically pointers to blocks of dynamically allocated memory that have been -reserved for use by the calling thread. -

    -The effect of calling pthread_setspecific() with a key value -not obtained from pthread_key_create() or after a key has been -deleted with pthread_key_delete() is undefined. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, pthread_setspecific() will return zero (OK). -Otherwise, an error number will be returned: -

    -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

    - -

    2.8.27 pthread_getspecific

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    void *pthread_getspecific(pthread_key_t key)
-
    -

    -Description: -

    -The pthread_getspecific() function returns the value -currently bound to the specified key on behalf of the -calling thread. -

    -The effect of calling pthread_getspecific() with a key value -not obtained from pthread_key_create() or after a key has been -deleted with pthread_key_delete() is undefined. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -The function pthread_getspecific() returns the thread-specific -data associated with the given key. If no thread specific data is -associated with the key, then the value NULL is returned. -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

    - -

    2.8.28 pthread_key_delete

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_key_delete(pthread_key_t key)
-
    -

    -Description: -

    -This POSIX function deletes a thread-specific data key previously -returned by pthread_key_create(). No cleanup actions -are done for data structures related to the deleted key or associated -thread-specific data in any threads. It is undefined behavior to use -key after it has been deleted. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_key_delete() function will -return zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.29 pthread_mutexattr_init

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_mutexattr_init(pthread_mutexattr_t *attr);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutexattr_init() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.30 pthread_mutexattr_destroy

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutexattr_destroy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.31 pthread_mutexattr_getpshared

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_mutexattr_getpshared(pthread_mutexattr_t *attr,
-                                     int *pshared);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutexattr_getpshared() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.32 pthread_mutexattr_setpshared

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-   int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
-                                    int pshared);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutexattr_setpshared() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.33 pthread_mutexattr_gettype

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-#ifdef CONFIG_PTHREAD_MUTEX_TYPES
-    int pthread_mutexattr_gettype(FAR const pthread_mutexattr_t *attr, FAR int *type);
-#endif
-
    -

    -Description: Return the mutex type from the mutex attributes. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutexattr_settype() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX interface of the same name. - -

    2.8.34 pthread_mutexattr_settype

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-#ifdef CONFIG_PTHREAD_MUTEX_TYPES
-    int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);
-#endif
-
    -

    -Description: Set the mutex type in the mutex attributes. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutexattr_settype() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX interface of the same name. - -

    2.8.35 pthread_mutexattr_getprotocol

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_mutexattr_getprotocol(FAR const pthread_mutexattr_t *attr,
-                                      FAR int *protocol);
-
    -

    -Description: Return the value of the mutex protocol attribute.. -

    -

    -Input Parameters: -

    -

    -

    -

    -

    -Returned Value: -

    -

    -If successful, the pthread_mutexattr_getprotocol() function will return zero (OK). -Otherwise, an error number will be returned to indicate the error. -

    -

    -Assumptions/Limitations: -

    -

    -POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.36 pthread_mutexattr_setprotocol

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_mutexattr_setprotocol(FAR pthread_mutexattr_t *attr,
-                                      int protocol);
-
    -

    -Description: Set mutex protocol attribute. See the paragraph Locking versus Signaling Semaphores for some important information about the use of this interface. -

    -

    -Input Parameters: -

    -

    -

    -

    -

    -Returned Value: -

    -

    -If successful, the pthread_mutexattr_setprotocol() function will return zero (OK). -Otherwise, an error number will be returned to indicate the error. -

    -

    -Assumptions/Limitations: -

    -

    -POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.37 pthread_mutex_init

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_mutex_init(pthread_mutex_t *mutex,
-                           pthread_mutexattr_t *attr);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutex_init() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX interface of the same name. - -

    2.8.38 pthread_mutex_destroy

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_mutex_destroy(pthread_mutex_t *mutex);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutex_destroy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.39 pthread_mutex_lock

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_mutex_lock(pthread_mutex_t *mutex);
-
    -

    -Description: - The mutex object referenced by mutex is locked by calling pthread_mutex_lock(). - If the mutex is already locked, the calling thread blocks until the mutex - becomes available. This operation returns with the mutex object referenced - by mutex in the locked state with the calling thread as its owner. -

    -

    - If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. - Attempting to re-lock the mutex causes deadlock. If a thread attempts to unlock - a mutex that it has not locked or a mutex which is unlocked, undefined behavior - results. -

    -

    - In NuttX, PTHREAD_MUTEX_NORMAL is not implemented. Rather, the behavior described - for PTHREAD_MUTEX_ERRORCHECK is the normal behavior. -

    -

    - If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. - If a thread attempts to re-lock a mutex that it has already locked, an error - will be returned. If a thread attempts to unlock a mutex that it has not - locked or a mutex which is unlocked, an error will be returned. -

    -

    - If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept - of a lock count. When a thread successfully acquires a mutex for the first time, - the lock count is set to one. Every time a thread re-locks this mutex, the lock count - is incremented by one. Each time the thread unlocks the mutex, the lock count is - decremented by one. When the lock count reaches zero, the mutex becomes available - for other threads to acquire. If a thread attempts to unlock a mutex that it has - not locked or a mutex which is unlocked, an error will be returned. -

    -

    - If a signal is delivered to a thread waiting for a mutex, upon return from - the signal handler the thread resumes waiting for the mutex as if it was - not interrupted. -

    -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutex_lock() function will return zero (OK). -Otherwise, an error number will be returned to indicate the error: -

    -

    -

    Note that this function will never return the error EINTR.

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.40 pthread_mutex_timedlock

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_mutex_timedlock(pthread_mutex_t *mutex, const struct timespec *abs_timeout);
-
    -

    -Description: - The pthread_mutex_timedlock() function will lock the mutex object referenced by mutex. - If the mutex is already locked, the calling thread will block until the mutex becomes available - as in the pthread_mutex_lock() function. - If the mutex cannot be locked without waiting for another thread to unlock the mutex, this wait - will be terminated when the specified abs_timeout expires. -

    -

    - The timeout will expire when the absolute time specified by abs_timeout passes, - as measured by the clock on which timeouts are based (that is, when the value of that clock - equals or exceeds abs_timeout), or if the absolute time specified by - abs_timeout has already been passed at the time of the call. -

    -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutex_trylock() function will return zero (OK). -Otherwise, an error number will be returned to indicate the error. -Note that the errno EINTR is never returned by pthread_mutex_timedlock(). -The returned errno is ETIMEDOUT if the mutex could not be locked before the specified timeout expired -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: - Comparable to the POSIX interface of the same name. - This implementation does not return EAGAIN when the mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded. -

    - -

    2.8.41 pthread_mutex_trylock

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_mutex_trylock(pthread_mutex_t *mutex);
-
    -

    -Description: - The function pthread_mutex_trylock() is identical to pthread_mutex_lock() - except that if the mutex object referenced by mutex is currently locked - (by any thread, including the current thread), the call returns immediately - with the errno EBUSY. -

    - If a signal is delivered to a thread waiting for a mutex, upon return from - the signal handler the thread resumes waiting for the mutex as if it was - not interrupted. -

    -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutex_trylock() function will return zero (OK). -Otherwise, an error number will be returned to indicate the error: -

    -

    -

    Note that this function will never return the error EINTR.

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.42 pthread_mutex_unlock

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_mutex_unlock(pthread_mutex_t *mutex);
-
    -

    -Description: -

    - The pthread_mutex_unlock() function releases the mutex object referenced - by mutex. The manner in which a mutex is released is dependent upon the - mutex's type attribute. If there are threads blocked on the mutex object - referenced by mutex when pthread_mutex_unlock() is called, resulting in - the mutex becoming available, the scheduling policy is used to determine - which thread will acquire the mutex. (In the case of PTHREAD_MUTEX_RECURSIVE - mutexes, the mutex becomes available when the count reaches zero and the - calling thread no longer has any locks on this mutex). -

    -

    - If a signal is delivered to a thread waiting for a mutex, upon return from - the signal handler the thread resumes waiting for the mutex as if it was - not interrupted. -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_mutex_unlock() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -

    Note that this function will never return the error EINTR.

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.42 pthread_condattr_init

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_condattr_init(pthread_condattr_t *attr);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_condattr_init() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.43 pthread_condattr_destroy

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_condattr_destroy(pthread_condattr_t *attr);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_condattr_destroy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.44 pthread_cond_init

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_cond_init(pthread_cond_t *cond, pthread_condattr_t *attr);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_cond_init() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.45 pthread_cond_destroy

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_cond_destroy(pthread_cond_t *cond);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_cond_destroy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.46 pthread_cond_broadcast

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_cond_broadcast(pthread_cond_t *cond);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_cond_broadcast() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.47 pthread_cond_signal

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_cond_signal(pthread_cond_t *dond);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    -Returned Value: -

    -If successful, the pthread_cond_signal() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.48 pthread_cond_wait

    -

    -Function Prototype: -

    -

    -    #include <pthread.h>
-    int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);
-
    -

    -Description: -

    -Input Parameters: -

    -

    -

    - Returned Value: -

    -If successful, the pthread_cond_wait() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

    -

    -Assumptions/Limitations: -

    -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

    2.8.49 pthread_cond_timedwait

    -

    - Function Prototype: -

    -
    -    #include <pthread.h>
-    int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex,
-                               const struct timespec *abstime);
-
    -

    - Description: -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: -

    -

    - If successful, the pthread_cond_timedwait() function will return - zero (OK). Otherwise, an error number will be - returned to indicate the error: -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.50 pthread_barrierattr_init

    -

    - Function Prototype: -

    -
    -    #include <pthread.h>
-    int pthread_barrierattr_init(FAR pthread_barrierattr_t *attr);
-
    -

    - Description: - The pthread_barrierattr_init() function will initialize a barrier - attribute object attr with the default value for all of the attributes - defined by the implementation. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - 0 (OK) on success or EINVAL if attr is invalid. -

    -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.51 pthread_barrierattr_destroy

    -

    - Function Prototype: -

    -
    -    #include <pthread.h>
-    int pthread_barrierattr_destroy(FAR pthread_barrierattr_t *attr);
-
    -

    - Description: - The pthread_barrierattr_destroy() function will destroy a barrier attributes object. - A destroyed attributes object can be reinitialized using pthread_barrierattr_init(); - the results of otherwise referencing the object after it has been destroyed are undefined. -

    -

    - Input Parameters: -

    - -

    - Returned Value: 0 (OK) on success or EINVAL if attr is invalid. -

    -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.52 pthread_barrierattr_setpshared

    -

    - Function Prototype: -

    -
    -    #include <pthread.h>
-    int pthread_barrierattr_setpshared(FAR pthread_barrierattr_t *attr, int pshared);
-
    -

    - Description: - The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit - a barrier to be operated upon by any thread that has access to the memory where the - barrier is allocated. - If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the barrier can - only be operated upon by threads created within the same process as the thread that - initialized the barrier. - If threads of different processes attempt to operate on such a barrier, the behavior is undefined. - The default value of the attribute is PTHREAD_PROCESS_PRIVATE. -

    -

    - Input Parameters: -

    - -

    - Returned Value: 0 (OK) on success or EINVAL if either - attr is invalid or pshared is not one of - PTHREAD_PROCESS_SHARED or PTHREAD_PROCESS_PRIVATE. -

    -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.53 pthread_barrierattr_getpshared

    -

    - Function Prototype: -

    -
    -    #include <pthread.h>
-    int pthread_barrierattr_getpshared(FAR const pthread_barrierattr_t *attr, FAR int *pshared);
-
    -

    - Description: - The pthread_barrierattr_getpshared() function will obtain the value of the - process-shared attribute from the attributes object referenced by attr. -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: 0 (OK) on success or EINVAL if - either attr or pshared is invalid. -

    -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.54 pthread_barrier_init

    -

    - Function Prototype: -

    -
    -    #include <pthread.h>
-    int pthread_barrier_init(FAR pthread_barrier_t *barrier,
-                             FAR const pthread_barrierattr_t *attr, unsigned int count);
-
    -

    - Description: - The pthread_barrier_init() function allocates any resources required to - use the barrier referenced by barrier and initialized the barrier with - the attributes referenced by attr. - If attr is NULL, the default barrier attributes will be used. - The results are undefined if pthread_barrier_init() is called when any - thread is blocked on the barrier. - The results are undefined if a barrier is used without first being initialized. - The results are undefined if pthread_barrier_init() is called specifying - an already initialized barrier. -

    -

    - Input Parameters: -

    - -

    - Returned Value: 0 (OK) on success or one of the following error numbers: -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.55 pthread_barrier_destroy

    -

    - Function Prototype: -

    -
    -    #include <pthread.h>
-    int pthread_barrier_destroy(FAR pthread_barrier_t *barrier);
-
    -

    - Description: - The pthread_barrier_destroy() function destroys the barrier referenced - by barrie and releases any resources used by the barrier. - The effect of subsequent use of the barrier is undefined until the barrier is - reinitialized by another call to pthread_barrier_init(). - The results are undefined if pthread_barrier_destroy() is called when - any thread is blocked on the barrier, or if this function is called with an - uninitialized barrier. -

    -

    - Input Parameters: -

    - -

    - Returned Value: 0 (OK) on success or one of the following error numbers: -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.56 pthread_barrier_wait

    -

    - Function Prototype: -

    -
    -    #include <pthread.h>
-    int pthread_barrier_wait(FAR pthread_barrier_t *barrier);
-
    -

    - Description: - The pthread_barrier_wait() function synchronizes participating - threads at the barrier referenced by barrier. - The calling thread is blocked until the required number of threads have called - pthread_barrier_wait() specifying the same barrier. - When the required number of threads have called pthread_barrier_wait() - specifying the barrier, the constant PTHREAD_BARRIER_SERIAL_THREAD - will be returned to one unspecified thread and zero will be returned to each of - the remaining threads. - At this point, the barrier will be reset to the state it had as a result of the most - recent pthread_barrier_init() function that referenced it. -

    -

    - The constant PTHREAD_BARRIER_SERIAL_THREAD is defined in - pthread.h and its value must be distinct from any other value - returned by pthread_barrier_wait(). -

    -

    - The results are undefined if this function is called with an uninitialized barrier. -

    -

    - If a signal is delivered to a thread blocked on a barrier, upon return from the - signal handler the thread will resume waiting at the barrier if the barrier wait - has not completed. - Otherwise, the thread will continue as normal from the completed barrier wait. - Until the thread in the signal handler returns from it, it is unspecified whether - other threads may proceed past the barrier once they have all reached it. -

    -

    - A thread that has blocked on a barrier will not prevent any unblocked thread that - is eligible to use the same processing resources from eventually making forward - progress in its execution. - Eligibility for processing resources will be determined by the scheduling policy. -

    -

    - Input Parameters: -

    - -

    - Returned Value: 0 (OK) on success or EINVAL if the barrier is not valid. -

    -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - - -

    2.8.57 pthread_once

    -

    - Function Prototype: -

    -
    -    #include <pthread.h>
-    int pthread_once(FAR pthread_once_t *once_control, CODE void (*init_routine)(void));
-
    -

    - Description: - The first call to pthread_once() by any thread with a given - once_control, will call the init_routine() with no arguments. - Subsequent calls to pthread_once() with the same once_control will have no effect. - On return from pthread_once(), init_routine() will have completed. -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: - 0 (OK) on success or EINVAL if either once_control or init_routine are invalid. -

    -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.58 pthread_kill

    -

    - Function Prototype: -

    -
    -    #include <signal.h>
-    #include <pthread.h>
-    int pthread_kill(pthread_t thread, int signo)
-
    -

    - Description: - The pthread_kill() system call can be used to send any - signal to a thread. See kill() for further information - as this is just a simple wrapper around the kill() - function. -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: -

    -

    - On success, the signal was sent and zero is returned. - On error one of the following error numbers is returned. -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - -

    2.8.59 pthread_sigmask

    -

    - Function Prototype: -

    -
    -    #include <signal.h>
-    #include <pthread.h>
-    int pthread_sigmask(int how, FAR const sigset_t *set, FAR sigset_t *oset);
-
    -

    - Description: - This function is a simple wrapper around sigprocmask(). - See the sigprocmask() function description for further information. -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: -

    - -

    - Assumptions/Limitations: -

    -

    - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    - - - - - -
    -

    2.9 Environment Variables

     -
    - -

    Overview. - NuttX supports environment variables that can be used to control the behavior of programs. - In the spirit of NuttX the environment variable behavior attempts to emulate the behavior of - environment variables in the multi-processing OS: -

    - -

    Programming Interfaces. - The following environment variable programming interfaces are provided by Nuttx and are - described in detail in the following paragraphs. -

    - -

    Disabling Environment Variable Support. - All support for environment variables can be disabled by setting CONFIG_DISABLE_ENVIRON - in the board configuration file. -

    - -

    2.9.1 getenv

    -

    - Function Prototype: -

    -
    -  #include <stdlib.h>
-  FAR char *getenv(const char *name);
-
    -

    - Description: - The getenv() function searches the environment list for a string that - matches the string pointed to by name. -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: - The value of the variable (read-only) or NULL on failure. -

    - -

    2.9.2 putenv

    -

    - Function Prototype: -

    -
    -  #include <stdlib.h>
-  int putenv(char *string);
-
    -

    - Description: - The putenv() function adds or changes the value of environment variables. - The argument string is of the form name=value. If name does not already - exist in the environment, then string is added to the environment. If - name does exist, then the value of name in the environment is changed to - value. -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: - Zero on success. -

    - -

    2.9.3 clearenv

    -

    - Function Prototype: -

    -
    -  #include <stdlib.h>
-  int clearenv(void);
-
    -

    - Description: - The clearenv() function clears the environment of all name-value pairs - and sets the value of the external variable environ to NULL. -

    -

    - Input Parameters: - None -

    -

    - Returned Value: - Zero on success. -

    - -

    2.9.4 setenv

    -

    - Function Prototype: -

    -
    -  #include <stdlib.h>
-  int setenv(const char *name, const char *value, int overwrite);
-
    -

    - Description: - The setenv() function adds the variable name to the environment with the - specified value if the variable name does not exist. If the name - does exist in the environment, then its value is changed to value if overwrite - is non-zero; if overwrite is zero, then the value of name is unaltered. -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: - Zero on success. -

    - -

    2.9.5 unsetenv

    -

    - Function Prototype: -

    -
    -  #include <stdlib.h>
-  int unsetenv(const char *name);
-
    -

    - Description: - The unsetenv() function deletes the variable name from the environment. -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: - Zero on success. -

    - - - - - -
    -

    2.10 File System Interfaces

     -
    - - - -

    2.10.1 NuttX File System Overview

    - -

    Overview. - NuttX includes an optional, scalable file system. - This file-system may be omitted altogether; NuttX does not depend on the presence - of any file system. -

    - -

    Pseudo Root File System. - A simple in-memory, pseudo file system can be enabled by default. - This is an in-memory file system because it does not require any - storage medium or block driver support. - Rather, file system contents are generated on-the-fly as referenced via - standard file system operations (open, close, read, write, etc.). - In this sense, the file system is pseudo file system (in the - same sense that the Linux /proc file system is also - referred to as a pseudo file system). -

    - -

    - Any user supplied data or logic can be accessed via the pseudo-file system. - Built in support is provided for character and block - driver nodes in the any - pseudo file system directory. - (By convention, however, all driver nodes should be in the /dev - pseudo file system directory). -

    - -

    Mounted File Systems - The simple in-memory file system can be extended my mounting block - devices that provide access to true file systems backed up via some - mass storage device. - NuttX supports the standard mount() command that allows - a block driver to be bound to a mount-point within the pseudo file system - and to a a file system. - At present, NuttX supports only the VFAT file system. -

    - -

    Comparison to Linux - From a programming perspective, the NuttX file system appears very similar - to a Linux file system. - However, there is a fundamental difference: - The NuttX root file system is a pseudo file system and true file systems may be - mounted in the pseudo file system. - In the typical Linux installation by comparison, the Linux root file system - is a true file system and pseudo file systems may be mounted in the true, - root file system. - The approach selected by NuttX is intended to support greater scalability - from the very tiny platform to the moderate platform. -

    - -

    File System Interfaces. - The NuttX file system simply supports a set of standard, file system APIs - (open(), close(), read(), write, etc.) - and a registration mechanism that allows devices drivers to a associated with nodes - in a file-system-like name space. -

    - -

    2.10.2 Driver Operations

    - - -

    2.10.2.1 fcntl.h

    - - - -

    2.10.2.2 unistd.h

    - - - -

    2.10.2.3 sys/ioctl.h

    - - - -

    2.10.2.4 poll.h

    - -
    2.10.2.4.1 poll
    -

    - Function Prototype: -

    -
    -  #include <poll.h>
-  int poll(struct pollfd *fds, nfds_t nfds, int timeout);
-
    -

    - Description: - poll() waits for one of a set of file descriptors to become ready to - perform I/O. If none of the events requested (and no error) has - occurred for any of the file descriptors, then poll() blocks until - one of the events occurs. -

    -

    - Configuration Settings. - In order to use the select with TCP/IP sockets test, you must have the following things - selected in your NuttX configuration file: -

    - -

    - In order to for select to work with incoming connections, you must also select: -

    - -

    - Input Parameters: -

    - -

    - Returned Value: -

    -

    - On success, the number of structures that have nonzero revents fields. - A value of 0 indicates that the call timed out and no file descriptors were ready. - On error, -1 is returned, and errno is set appropriately: -

    - - -

    2.10.2.5 sys/select.h

    - -
    2.10.2.5.1 select
    -

    - Function Prototype: -

    - -

    - Description: - select() allows a program to monitor multiple file descriptors, waiting - until one or more of the file descriptors become "ready" for some class - of I/O operation (e.g., input possible). A file descriptor is - considered ready if it is possible to perform the corresponding I/O - operation (e.g., read(2)) without blocking. -

    -

    - NOTE: poll() is the fundamental API for performing such monitoring - operation under NuttX. select() is provided for compatibility and - is simply a layer of added logic on top of poll(). As such, select() - is more wasteful of resources and poll() is the recommended API to be - used. -

    -

    - Input Parameters: -

    - -

    - Returned Value: -

    - - -

    2.10.3 Directory Operations

    - - - - -

    2.10.4 UNIX Standard Operations

    - - - -

    2.10.5 Standard I/O

    - - -

    2.10.6 Standard Library

    -

    - stdlib.h generally addresses other operating system interfaces. - However, the following may also be considered as file system interfaces: -

    - - -

    2.10.7 Asynchronous I/O

    - - -

    2.10.8 Standard String Operations

    - - -

    2.10.9 Pipes and FIFOs

    - -

    2.10.9.1 pipe

    -

    - Function Prototype: -

    - -

    - Description: -

    -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: -

    -

    - -

    2.10.9.2 mkfifo

    -

    - Function Prototype: -

    - -

    - Description: -

    -

    -

    - Input Parameters: -

    -

    -

    - Returned Value: -

    -

    - -

    2.10.10 mmap() and eXecute In Place (XIP)

    -

    - NuttX operates in a flat open address space and is focused on MCUs that do - support Memory Management Units (MMUs). Therefore, NuttX generally does not - require mmap() functionality and the MCUs generally cannot support true - memory-mapped files. -

    -

    - However, memory mapping of files is the mechanism used by NXFLAT, the NuttX - tiny binary format, to get files into memory in order to execute them. - mmap() support is therefore required to support NXFLAT. - There are two conditions where mmap() can be supported: -

    -
      -
    1. -

      - mmap() can be used to support eXecute In Place (XIP) on random access media - under the following very restrictive conditions: -

      -
        -
      1. -

        - The file-system supports the FIOC_MMAP ioctl command. - Any file system that maps files contiguously on the media should support this - ioctl command. - By comparison, most file system scatter files over the media in non-contiguous - sectors. As of this writing, ROMFS is the only file system that meets this requirement. -

        -
        2. -
      2. -

        - The underlying block driver supports the BIOC_XIPBASE ioctl command - that maps the underlying media to a randomly accessible address. - At present, only the RAM/ROM disk driver does this. -

        -
        3. -
      -

      - Some limitations of this approach are as follows: -

      -

        -
      1. -

        - Since no real mapping occurs, all of the file contents are "mapped" into memory. -

        -
        2. -
      2. -

        - All mapped files are read-only. -

        -
        3. -
      3. -

        - There are no access privileges. -

        -
        4. -
      -
      2. -
    2. -

      - If CONFIG_FS_RAMMAP is defined in the configuration, then mmap() will - support simulation of memory mapped files by copying files whole into RAM. - These copied files have some of the properties of standard memory mapped files. - There are many, many exceptions exceptions, however. - Some of these include: -

      -
        -
      1. -

        - The goal is to have a single region of memory that represents a single - file and can be shared by many threads. That is, given a filename a - thread should be able to open the file, get a file descriptor, and - call mmap() to get a memory region. Different file descriptors opened - with the same file path should get the same memory region when mapped. -

        -

        - The limitation in the current design is that there is insufficient - knowledge to know that these different file descriptors correspond to - the same file. So, for the time being, a new memory region is created - each time that rammmap() is called. Not very useful! -

        -
        2. -
      2. -

        - The entire mapped portion of the file must be present in memory. - Since it is assumed that the MCU does not have an MMU, on-demanding - paging in of file blocks cannot be supported. Since the while mapped - portion of the file must be present in memory, there are limitations - in the size of files that may be memory mapped (especially on MCUs - with no significant RAM resources). -

        -
        3. -
      3. -

        - All mapped files are read-only. You can write to the in-memory image, - but the file contents will not change. -

        -
        4. -
      4. -

        - There are no access privileges. -

        -
        5. -
      5. -

        - Since there are no processes in NuttX, all mmap() and munmap() - operations have immediate, global effects. Under Linux, for example, - munmap() would eliminate only the mapping with a process; the mappings - to the same file in other processes would not be effected. -

        -
        6. -
      6. -

        - Like true mapped file, the region will persist after closing the file - descriptor. However, at present, these ram copied file regions are - not automatically "unmapped" (i.e., freed) when a thread is terminated. - This is primarily because it is not possible to know how many users - of the mapped region there are and, therefore, when would be the - appropriate time to free the region (other than when munmap is called). -

        -

        - NOTE: Note, if the design limitation of a) were solved, then it would be - easy to solve exception d) as well. -

        -
        7. -
      -
      3. -
    - -

    2.10.11.1 mmap

    -

    - Function Prototype: -

    - -

    - Description: -

    -

    -

    - Input Parameters: -

    -

    -

    - Returned Value: -

    -

    - - - - - -
    -

    2.11 Network Interfaces

     -
    - -

    - NuttX supports a BSD-compatible socket interface layer. - These socket interface can be enabled by settings in the architecture configuration file. - Those socket APIs are discussed in the following paragraphs. -

    - - -

    2.11.1 socket

    -

    - Function Prototype: -

    - -

    - Description: - socket() creates an endpoint for communication and returns a descriptor. -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: - 0 on success; -1 on error with errno set appropriately: -

    - - -

    2.11.2 bind

    -

    - Function Prototype: -

    - -

    - Description: - bind() gives the socket sockfd the local address addr. - addr is addrlen bytes long. Traditionally, this is called - "assigning a name to a socket." When a socket is created with socket(), - it exists in a name space (address family) but has no name assigned. -

    -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: - 0 on success; -1 on error with errno set appropriately: -

    - - -

    2.11.3 connect

    -

    - Function Prototype: -

    - -

    - Description: - connect() connects the socket referred to by the file descriptor - sockfd to the address specified by addr. - The addrlen argument specifies the size of addr. - The format of the address in addr is determined by the address space - of the socket sockfd. - - If the socket sockfd is of type SOCK_DGRAM then addr is the address - to which datagrams are sent by default, and the only address from which - datagrams are received. If the socket is of type SOCK_STREAM or - SOCK_SEQPACKET, this call attempts to make a connection to the socket - that is bound to the address specified by addr. - - Generally, connection-based protocol sockets may successfully connect() - only once; connectionless protocol sockets may use connect() multiple - times to change their association. Connectionless sockets may dissolve - the association by connecting to an address with the sa_family member of - sockaddr set to AF_UNSPEC. -

    -

    -

    - Input Parameters: -

    -

    -

    -

    - Returned Value: - 0 on success; -1 on error with errno set appropriately: -

    -
  • EACCES or EPERM: - The user tried to connect to a broadcast address without having the - socket broadcast flag enabled or the connection request failed - because of a local firewall rule.
    • -
  • EADDRINUSE - Local address is already in use.
    • -
  • EAFNOSUPPORT - The passed address didn't have the correct address family in its - sa_family field.
    • -
  • EAGAIN - No more free local ports or insufficient entries in the routing - cache. For PF_INET.
    • -
  • EALREADY - The socket is non-blocking and a previous connection attempt has - not yet been completed.
    • -
  • EBADF - The file descriptor is not a valid index in the descriptor table.
    • -
  • ECONNREFUSED - No one listening on the remote address.
    • -
  • EFAULT - The socket structure address is outside the user's address space.
    • -
  • EINPROGRESS - The socket is non-blocking and the connection cannot be completed - immediately.
    • -
  • EINTR - The system call was interrupted by a signal that was caught.
    • -
  • EISCONN - The socket is already connected.
    • -
  • ENETUNREACH - Network is unreachable.
    • -
  • ENOTSOCK - The file descriptor is not associated with a socket.
    • -
  • ETIMEDOUT - Timeout while attempting connection. The server may be too busy - to accept new connections.
    • - - -

    2.11.4 listen

    -

    - Function Prototype: -

    - -

    - Description: - To accept connections, a socket is first created with socket(), a - willingness to accept incoming connections and a queue limit for incoming - connections are specified with listen(), and then the connections are - accepted with accept(). The listen() call applies only to sockets of - type SOCK_STREAM or SOCK_SEQPACKET. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, zero is returned. On error, -1 is returned, and - errno is set appropriately. -

    - - -

    2.11.5 accept

    -

    - Function Prototype: -

    - -

    - Description: - The accept() function is used with connection-based socket types - (SOCK_STREAM, SOCK_SEQPACKET and SOCK_RDM). - It extracts the first connection request on the queue of pending connections, - creates a new connected socket with most of the same properties as sockfd, - and allocates a new socket descriptor for the socket, which is returned. The - newly created socket is no longer in the listening state. The original - socket sockfd is unaffected by this call. Per file descriptor flags - are not inherited across an accept. -

    -

    - The sockfd argument is a socket descriptor that has been created with - socket(), bound to a local address with bind(), and is listening for - connections after a call to listen(). -

    -

    - On return, the addr structure is filled in with the address of the - connecting entity. The addrlen argument initially contains the size - of the structure pointed to by addr; on return it will contain the - actual length of the address returned. -

    -

    - If no pending connections are present on the queue, and the socket is - not marked as non-blocking, accept blocks the caller until a connection - is present. If the socket is marked non-blocking and no pending - connections are present on the queue, accept returns EAGAIN. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - Returns -1 on error. If it succeeds, it returns a non-negative integer - that is a descriptor for the accepted socket. -

    - - -

    2.11.6 send

    -

    - Function Prototype: -

    - -

    - Description: - The send() call may be used only when the socket is in a connected state - (so that the intended recipient is known). - The only difference between send() and write() is the - presence of flags. - With zero flags parameter, send() is equivalent to - write(). Also, send(s,buf,len,flags) is - equivalent to sendto(s,buf,len,flags,NULL,0). -

    -

    - Input Parameters: -

    - -

    - Returned Value: - See sendto(). -

    - -

    2.11.7 sendto

    -

    - Function Prototype: -

    - -

    - Description: - If sendto() is used on a connection-mode (SOCK_STREAM, SOCK_SEQPACKET) - socket, the parameters to and tolen are ignored (and the error EISCONN - may be returned when they are not NULL and 0), and the error ENOTCONN is - returned when the socket was not actually connected. -

    -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, returns the number of characters sent. On error, -1 is returned, - and errno is set appropriately: -

    - - -

    2.11.8 recv

    -

    - Function Prototype: -

    - -

    - Description: - The recv() call is identical to - recvfrom() with a NULL - from parameter. -

    -

    -

    - Input Parameters: -

    - -

    - Returned Value: - See recvfrom(). -

    - -

    2.11.9 recvfrom

    -

    - Function Prototype: -

    - -

    - Description: - recvfrom() receives messages from a socket, and may be used to receive - data on a socket whether or not it is connection-oriented. -

    -

    - If from is not NULL, and the underlying protocol provides the source - address, this source address is filled in. The argument fromlen - initialized to the size of the buffer associated with from, and modified - on return to indicate the actual size of the address stored there. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, returns the number of characters sent. - If no data is available to be received and the peer has performed an orderly shutdown, recv() will return 0. - Otherwise, on errors, -1 is returned, and errno is set appropriately: -

    - - -

    2.11.10 setsockopt

    -

    - Function Prototype: -

    - -

    - Description: - setsockopt() sets the option specified by the option argument, - at the protocol level specified by the level argument, to the value - pointed to by the value argument for the socket associated with the - file descriptor specified by the sockfd argument. -

    -

    - The level argument specifies the protocol level of the option. To set - options at the socket level, specify the level argument as SOL_SOCKET. -

    -

    - See sys/socket.h for a complete list of values for the option argument. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, returns the number of characters sent. - On error, -1 is returned, and errno is set appropriately: -

    - - -

    2.11.11 getsockopt

    -

    - Function Prototype: -

    - -

    - Description: - getsockopt() retrieve those value for the option specified by the - option argument for the socket specified by the sockfd argument. If - the size of the option value is greater than value_len, the value - stored in the object pointed to by the value argument will be silently - truncated. Otherwise, the length pointed to by the value_len argument - will be modified to indicate the actual length of the value. -

    -

    - The level argument specifies the protocol level of the option. To - retrieve options at the socket level, specify the level argument as - SOL_SOCKET. -

    -

    - See sys/socket.h for a complete list of values for the option argument. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - On success, returns the number of characters sent. - On error, -1 is returned, and errno is set appropriately: -

    - - - - - - -
    -

    2.12 Shared Memory Interfaces

     -
    -

    - 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. - Shared memory interfaces: -

    - - -

    2.12.1 shmget

    -

    - Function Prototype: -

    - -

    - Description: - The shmget() function will return the shared memory identifier associated with key. -

    -

    - A shared memory identifier, associated data structure, and shared memory segment of at least size bytes is created for key if one of the following is true: -

    - -

    - Upon creation, the data structure associated with the new shared memory identifier will be initialized as follows: -

    - -

    - When the shared memory segment is created, it will be initialized with all zero values. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - Upon successful completion, shmget() will return a non-negative integer, namely a shared memory identifier; otherwise, it will return -1 and set errno to indicate the error. -

    - -

    - POSIX Deviations -

    -

    - -

    2.12.2 shmat

    -

    - Function Prototype: -

    - -

    - Description: - The shmat() function attaches the shared memory segment associated with the shared memory identifier specified by shmid to the address space of the calling process. The segment is attached at the address specified by one of the following criteria: -

    - -

    - Input Parameters: -

    - -

    - Returned Value: - Upon successful completion, shmat() will increment the value of shm_nattch in the data structure associated with the shared memory ID of the attached shared memory segment and return the segment's start address. - - Otherwise, the shared memory segment will not be attached, shmat() will return -1, and errno will be set to indicate the error. -

    - - -

    2.12.3 shmctl

    -

    - Function Prototype: -

    - -

    - Description: - The shmctl() function provides a variety of shared memory control operations as specified by cmd. The following values for cmd are available: -

    - -

    - Input Parameters: -

    - -

    - Returned Value: - Upon successful completion, shmctl() will return 0; otherwise, it will return -1 and set errno to indicate the error. -

    - -

    - POSIX Deviations -

    -

    - -

    2.12.4 shmdt

    -

    - Function Prototype: -

    - -

    - Description: - The shmdt() function detaches the shared memory segment located at the address specified by shmaddr from the address space of the calling process. -

    -

    - Input Parameters: -

    - -

    - Returned Value: - Upon successful completion, shmdt() will decrement the value of shm_nattch in the data structure associated with the shared memory ID of the attached shared memory segment and return 0. -

    -

    - Otherwise, the shared memory segment will not be detached, shmdt() will return -1, and errno will be set to indicate the error. -

    - - - - - - -
    -

    3.0 OS Data Structures

     -
    - - - - - -
    -

    3.1 Scalar Types

     -
    - -

    -Many of the types used to communicate with NuttX are simple -scalar types. These types are used to provide architecture independence -of the OS from the application. The scalar types used at the NuttX -interface include: -

    - - - - - -
    -

    3.2 Hidden Interface Structures

     -
    - -

    -Several of the types used to interface with NuttX are -structures that are intended to be hidden from the application. -From the standpoint of the application, these structures (and -structure pointers) should be treated as simple handles to reference -OS resources. These hidden structures include: -

    -

    - In order to maintain portability, applications should not reference - specific elements within these hidden structures. These hidden - structures will not be described further in this user's manual. -

    - - - - - -
    -

    3.3 Access to the errno Variable

     -
    - -

    - A pointer to the thread-specific errno value is available through a - function call: -

    -

    - Function Prototype: -

    -

    -

    - Description: - __errno() returns a pointer to the thread-specific errno value. - Note that the symbol errno is defined to be __errno() so that the usual - access by referencing the symbol errno will work as expected. -

    -

    - There is a unique, private errno value for each NuttX task. - However, the implementation of errno differs somewhat from the use of - errno in most multi-threaded process environments: - In NuttX, each pthread will also have its own private copy of errno and the - errno will not be shared between pthreads. - This is, perhaps, non-standard but promotes better thread independence. -

    -Input Parameters: None -

    -Returned Values: -

    -

    -

    - - - - - -
    -

    3.4 User Interface Structures

     -
    - -

    3.4.1 main_t

    -

    -main_t defines the type of a task entry point. main_t is declared -in sys/types.h as: -

    -    typedef int (*main_t)(int argc, char *argv[]);
-
    - -

    3.4.2 struct sched_param

    - -

    -This structure is used to pass scheduling priorities to and from -NuttX; -

    -    struct sched_param
-    {
-      int sched_priority;
-    };
-
    - -

    3.4.3 struct timespec

    - -

    -This structure is used to pass timing information between the -NuttX and a user application: -

    -    struct timespec
-    {
-      time_t tv_sec;  /* Seconds */
-      long   tv_nsec; /* Nanoseconds */
-    };
-
    - -

    3.4.4 struct mq_attr

    - -

    -This structure is used to communicate message queue attributes -between NuttX and a MoBY application: -

    -    struct mq_attr {
-      size_t       mq_maxmsg;   /* Max number of messages in queue */
-      size_t       mq_msgsize;  /* Max message size */
-      unsigned     mq_flags;    /* Queue flags */
-      size_t       mq_curmsgs;  /* Number of messages currently in queue */
-    };
-
    - -

    3.4.5 struct sigaction

    - -

    -The following structure defines the action to take for given signal: -

    -    struct sigaction
-    {
-      union
-      {
-        void (*_sa_handler)(int);
-        void (*_sa_sigaction)(int, siginfo_t *, void *);
-      } sa_u;
-      sigset_t           sa_mask;
-      int                sa_flags;
-    };
-    #define sa_handler   sa_u._sa_handler
-    #define sa_sigaction sa_u._sa_sigaction
-
    - -

    3.4.6 struct siginfo/siginfo_t

    - -

    -The following types is used to pass parameters to/from signal -handlers: -

    -    typedef struct siginfo
-    {
-      int          si_signo;
-      int          si_code;
-      union sigval si_value;
-   } siginfo_t;
-
    - -

    3.4.7 union sigval

    - -

    -This defines the type of the struct siginfo si_value field and -is used to pass parameters with signals. -

    -    union sigval
-    {
-      int   sival_int;
-      void *sival_ptr;
-    };
-
    - -

    3.4.8 struct sigevent

    - -

    -The following is used to attach a signal to a message queue to -notify a task when a message is available on a queue. -

    -    struct sigevent
-    {
-      int          sigev_signo;
-      union sigval sigev_value;
-      int          sigev_notify;
-    };
-
    - - - - - - -
    -

    Index

     -
    - - - - - - - -
    -
  • accept
    • -
  • aio.h
    • -
  • aio_cancel
    • -
  • aio_error
    • -
  • aio_fsync
    • -
  • aio_read
    • -
  • aio_return
    • -
  • aio_suspend
    • -
  • aio_write
    • -
  • asctime
    • -
  • asctime_r
    • -
  • atexit -
  • bind
    • -
  • BIOC_XIPBASE
    • -
  • chdir
    • -
  • clock_getres
    • -
  • clock_gettime
    • -
  • Clocks
    • -
  • clock_settime
    • -
  • close
    • -
  • closedir
    • -
  • connect
    • -
  • creat
    • -
  • ctime
    • -
  • ctime_r
    • -
  • Data structures
    • -
  • Directory operations
    • -
  • dirent.h
    • -
  • Driver operations
    • -
  • dup
    • -
  • dup2
    • -
  • execl
    • -
  • eXecute In Place (XIP)
    • -
  • exec
    • -
  • execv
    • -
  • exit
    • -
  • FAT File System Support
    • -
  • fclose
    • -
  • fcntl
    • -
  • fcntl.h
    • -
  • fdopen
    • -
  • feof
    • -
  • ferror
    • -
  • File system, interfaces
    • -
  • File system, overview
    • -
  • fflush
    • -
  • fgetc
    • -
  • fgetpos
    • -
  • fgets
    • -
  • FIOC_MMAP
    • -
  • fopen
    • -
  • fprintf
    • -
  • fputc
    • -
  • fputs
    • -
  • fread
    • -
  • fseek
    • -
  • fsetpos
    • -
  • fstat
    • -
  • ftell
    • -
  • fwrite
    • -
  • getcwd
    • -
  • getpid
    • -
  • gets
    • -
  • getsockopt
    • -
  • gmtime
    • -
  • gmtime_r
    • -
  • Introduction -
  • ioctl
    • -
  • kill
    • -
  • lio_listio
    • -
  • listen
    • -
  • localtime_r
    • -
  • Locking versus Signaling Semaphores
    • -
  • lseek
    • -
  • Named Message Queue Interfaces -
  • mkdir
    • -
  • mkfifo
    • -
  • mktime
    • -
  • mq_close
    • -
  • mq_getattr
    • -
  • mq_notify
    • -
  • mq_open
    • -
  • mq_receive
    • -
  • mq_send
    • -
  • mq_setattr
    • -
  • mq_timedreceive
    • -
  • mq_timedsend
    • -
  • mq_unlink
    • -
  • mmap
    • -
  • Network Interfaces
    • -    		 -
  • on_exit -
  • open
    • -
  • opendir
    • -
  • OS Interfaces
    • -
  • pause
    • -
  • pipe
    • -
  • poll
    • -
  • poll.h
    • -
  • posix_spawn
    • -
  • posix_spawn_file_actions_addclose
    • -
  • posix_spawn_file_actions_adddup2
    • -
  • posix_spawn_file_actions_addopen
    • -
  • posix_spawn_file_actions_destroy
    • -
  • posix_spawn_file_actions_init
    • -
  • posix_spawnattr_init
    • -
  • posix_spawnattr_destroy
    • -
  • posix_spawnattr_getflags
    • -
  • posix_spawnattr_getschedparam
    • -
  • posix_spawnattr_getschedpolicy
    • -
  • posix_spawnattr_getsigmask
    • -
  • posix_spawnattr_setflags
    • -
  • posix_spawnattr_setschedparam
    • -
  • posix_spawnattr_setschedpolicy
    • -
  • posix_spawnattr_setsigmask
    • -
  • posix_spawnp
    • -
  • pread
    • -
  • printf
    • -
  • pwrite
    • -
  • Pthread Interfaces -
  • pthread_attr_destroy
    • -
  • pthread_attr_getinheritsched
    • -
  • pthread_attr_getschedparam
    • -
  • pthread_attr_getschedpolicy
    • -
  • pthread_attr_getstacksize
    • -
  • pthread_attr_init
    • -
  • pthread_attr_setinheritsched
    • -
  • pthread_attr_setschedparam
    • -
  • pthread_attr_setschedpolicy
    • -
  • pthread_attr_setstacksize
    • -
  • pthread_barrierattr_init
    • -
  • pthread_barrierattr_destroy
    • -
  • pthread_barrierattr_getpshared
    • -
  • pthread_barrierattr_setpshared
    • -
  • pthread_barrier_destroy
    • -
  • pthread_barrier_init
    • -
  • pthread_barrier_wait
    • -
  • pthread_cancel
    • -
  • pthread_condattr_init
    • -
  • pthread_cond_broadcast
    • -
  • pthread_cond_destroy
    • -
  • pthread_cond_init
    • -
  • pthread_cond_signal
    • -
  • pthread_cond_timedwait
    • -
  • pthread_cond_wait
    • -
  • pthread_create
    • -
  • pthread_detach
    • -
  • pthread_exit
    • -
  • pthread_getschedparam
    • -
  • pthread_getspecific
    • -
  • pthreads share some resources. -
  • pthread_join
    • -
  • pthread_key_create
    • -
  • pthread_key_delete
    • -
  • pthread_kill
    • -
  • pthread_mutexattr_destroy
    • -
  • pthread_mutexattr_getprotocol
    • -
  • pthread_mutexattr_getpshared
    • -
  • pthread_mutexattr_gettype
    • -
  • pthread_mutexattr_init
    • -
  • pthread_mutexattr_setprotocol
    • -
  • pthread_mutexattr_setpshared
    • -
  • pthread_mutexattr_settype
    • -
  • pthread_mutex_destroy
    • -
  • pthread_mutex_init
    • -
  • pthread_mutex_lock
    • -
  • pthread_mutex_timedlock
    • -
  • pthread_mutex_trylock
    • -
  • pthread_mutex_unlock
    • -
  • pthread_condattr_destroy
    • -
  • pthread_once
    • -
  • pthread_self
    • -
  • pthread_setcancelstate
    • -
  • pthread_setcanceltype
    • -
  • pthread_setschedparam
    • -
  • pthread_setspecific
    • -
  • pthread_sigmask
    • -
  • pthread_testcancel
    • -
  • pthread_yield
    • -
  • puts
    • -
  • RAM disk driver
    • -
  • read
    • -    		 -
  • readdir
    • -
  • readdir_r
    • -
  • recv
    • -
  • recvfrom
    • -
  • rename
    • -
  • rmdir
    • -
  • rewinddir
    • -
  • ROM disk driver
    • -
  • ROMFS
    • -
  • sched_getparam
    • -
  • sched_get_priority_max
    • -
  • sched_get_priority_min
    • -
  • sched_get_rr_interval
    • -
  • sched_lockcount
    • -
  • sched_lock
    • -
  • sched_setparam
    • -
  • sched_setscheduler
    • -
  • sched_unlock
    • -
  • sched_yield
    • -
  • select
    • -
  • Counting Semaphore Interfaces -
  • sem_close
    • -
  • sem_destroy
    • -
  • sem_getprotocol
    • -
  • sem_getvalue
    • -
  • sem_init
    • -
  • sem_open
    • -
  • sem_post
    • -
  • sem_setprotocol
    • -
  • sem_trywait
    • -
  • sem_unlink
    • -
  • sem_wait
    • -
  • sched_getscheduler
    • -
  • seekdir
    • -
  • send
    • -
  • sendto
    • -
  • setsockopt
    • -
  • sigaction
    • -
  • sigaddset
    • -
  • sigdelset
    • -
  • sigemptyset
    • -
  • sigfillset
    • -
  • sigismember
    • -
  • Signal Interfaces -
  • sigpending
    • -
  • sigprocmask
    • -
  • sigqueue
    • -
  • sigsuspend
    • -
  • sigtimedwait
    • -
  • sigwaitinfo
    • -
  • socket
    • -
  • sprintf
    • -
  • Standard I/O
    • -
  • stat
    • -
  • statfs
    • -
  • stdio.h
    • -
  • sys/select.h
    • -
  • sys/ioctl.h
    • -
  • Task Control Interfaces -
  • task_create
    • -
  • task_delete
    • -
  • task_restart
    • -
  • Task Scheduling Interfaces -
  • task_setcancelstate
    • -
  • task_setcanceltype
    • -
  • task_spawn
    • -
  • task_spawnattr_getstacksize
    • -
  • task_spawnattr_setstacksize
    • -
  • Task Switching Interfaces -
  • task_testcancel
    • -
  • telldir
    • -
  • timer_create
    • -
  • timer_delete
    • -
  • timer_getoverrun
    • -
  • timer_gettime
    • -
  • Timers
    • -
  • timer_settime
    • -
  • ungetc
    • -
  • unistd.h, - unistd.h
    • -
  • unlink
    • -
  • vfork
    • -
  • vfprintf
    • -
  • vprintf
    • -
  • vsprintf
    • -
  • wait
    • -
  • waitid
    • -
  • waitpid -
  • write
    • -
  • XIP
    • -
    - - - diff --git a/Documentation/NxWidgets.html b/Documentation/NxWidgets.html deleted file mode 100644 index 63765a328b..0000000000 --- a/Documentation/NxWidgets.html +++ /dev/null @@ -1,76 +0,0 @@ - - -NxWidgets - - - -
    - - - - -
    -

    NxWidgets

    -

    Last Updated: November 7, 2017

    -
    -

    NxWidgets

    -

    - In order to better support NuttX based platforms, a special graphical userinterface has been created called NXWidgets. - NXWidgets is written in C++ and integrates seamlessly with the NuttX NX graphics subsystem in order to provide graphic objects, or "widgets," in the NX Graphics Subsystem -

    -

    - Some of the features of NXWidgets include: -

    - -

    - Note: Many of the fundamental classed in NxWidgets derive from the Antony - Dzeryn's "Woopsi" project: http://woopsi.org/ which also has a BSD style - license. See the COPYING file for details. -

    -

    NXWidgets DOxygen Documentation

    -

    - Release notes, DOxygen documentation, as well as downloads for the latest NxWidgets releases are available online: -

    -