From 30280a913b0928b7615ec2cb7299bc3a8df9c104 Mon Sep 17 00:00:00 2001 From: Gregory Nutt Date: Mon, 29 Jun 2015 10:57:05 -0600 Subject: [PATCH] Remove the Documentation/ directory --- ChangeLog | 2 + Documentation/.gitignore | 3 - Documentation/NXGraphicsSubsystem.html | 4284 --------- Documentation/NXOrganization.gif | Bin 34880 -> 0 bytes Documentation/NfsHowto.html | 388 - Documentation/NuttShell.html | 4321 --------- Documentation/NuttX.html | 5226 ----------- Documentation/NuttX.png | Bin 4961 -> 0 bytes Documentation/NuttX2-a.png | Bin 1533 -> 0 bytes Documentation/NuttX2-b.png | Bin 1559 -> 0 bytes Documentation/NuttX2.png | Bin 3441 -> 0 bytes Documentation/NuttX320.png | Bin 4151 -> 0 bytes Documentation/NuttXBinfmt.html | 608 -- Documentation/NuttXCCodingStandard.html | 2573 ------ Documentation/NuttXDemandPaging.html | 674 -- Documentation/NuttXGettingStarted.html | 25 - Documentation/NuttXNxFlat.html | 803 -- Documentation/NuttXScreenShot.jpg | Bin 5872 -> 0 bytes Documentation/NuttxPortingGuide.html | 5967 ------------- Documentation/NuttxUserGuide.html | 10157 ---------------------- Documentation/NxWidgets.html | 92 - Documentation/README.html | 374 - Documentation/UsbTrace.html | 452 - Documentation/acronyms.txt | 57 - Documentation/backgd.gif | Bin 1097 -> 0 bytes Documentation/favicon.ico | Bin 3126 -> 0 bytes Documentation/pm.png | Bin 32504 -> 0 bytes Documentation/redirect.html | 20 - 28 files changed, 2 insertions(+), 36024 deletions(-) delete mode 100644 Documentation/.gitignore delete mode 100644 Documentation/NXGraphicsSubsystem.html delete mode 100644 Documentation/NXOrganization.gif delete mode 100644 Documentation/NfsHowto.html delete mode 100644 Documentation/NuttShell.html delete mode 100644 Documentation/NuttX.html delete mode 100644 Documentation/NuttX.png delete mode 100644 Documentation/NuttX2-a.png delete mode 100644 Documentation/NuttX2-b.png delete mode 100644 Documentation/NuttX2.png delete mode 100644 Documentation/NuttX320.png delete mode 100644 Documentation/NuttXBinfmt.html delete mode 100644 Documentation/NuttXCCodingStandard.html delete mode 100644 Documentation/NuttXDemandPaging.html delete mode 100644 Documentation/NuttXGettingStarted.html delete mode 100644 Documentation/NuttXNxFlat.html delete mode 100644 Documentation/NuttXScreenShot.jpg delete mode 100644 Documentation/NuttxPortingGuide.html delete mode 100644 Documentation/NuttxUserGuide.html delete mode 100644 Documentation/NxWidgets.html delete mode 100644 Documentation/README.html delete mode 100644 Documentation/UsbTrace.html delete mode 100644 Documentation/acronyms.txt delete mode 100644 Documentation/backgd.gif delete mode 100644 Documentation/favicon.ico delete mode 100644 Documentation/pm.png delete mode 100644 Documentation/redirect.html diff --git a/ChangeLog b/ChangeLog index 9be01bb95e..b7f87ac2ea 100755 --- a/ChangeLog +++ b/ChangeLog @@ -10627,3 +10627,5 @@ * Broke the NuttX GIT repository into several, smaller repositories. Eliminated the misc/ directory and the content under misc/Obsoleted and misc/sims (2015-06-27). + * Removed the Documentation/ directory (2015-06-29). + 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 ce3299b16e..0000000000 --- a/Documentation/NXGraphicsSubsystem.html +++ /dev/null @@ -1,4284 +0,0 @@ - - -NX Graphics Subsystem - - - - -
- - - - -
-

- NX Graphics Subsystem -

-

Last Updated: April 5, 2015

-
-
- - - - - -
-

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 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 both a small-footprint, single user implementaton (NXSU) and a somewhat - larger multi-user implentation (NXMU as described below). - Both conform to the same APIs as defined in include/nuttx/nx/nx.h and, hence, - are interchangable1. - 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 package. - NxWidgets is built on top of the core NuttX graphics subsystem, but is not a part of the core graphics subystems. -

- -

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. - NxTerm is only available when the multi-user NX implementation is selected (CONFIG_NX_MULTIUSER). -

- - - - - -
-

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 RGB triplet to 8-bit YUV 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 rectanges, 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(). - In the multi-user model, these callbacks will be invoked as part of the - processing performed by - nx_eventhandler(). -

- - -

2.3.3 NX Server Callbacks

- -

2.3.3.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.3.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.3.3 mousein()

-

Callback Function Prototype:

- -

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

-

- Input Parameters: -

-

-

- Returned Value: None -

- -

2.3.3.4 kbdin()

-

Callback Function Prototype:

- -

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

-

- Input Parameters: -

-

-

- Returned Value: None -

- -

2.3.4 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. -

-

- Multiple user mode only! -

-

- 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.5 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: -

- -

- Multiple user mode only! -

-

- Input Parameters: -

-

-

- Returned Value: -

- - -

2.3.6 nx_open()

-

Function Prototype:

- -

- Description: - Create, initialize and return an NX handle for use in subsequent - NX API calls. nx_open() is the single user equivalent of - nx_connect() plus - nx_run(). -

-

- Single user mode only! -

-

- 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(). - nx_disconnect() is muliti-user equivalent of - nx_close(). -

-

- Multiple user mode only! -

-

- Input Parameters: -

-

-

- Returned Value: None. -

- -

2.3.8 nx_close()

-

Function Prototype:

- -

- Description: - Close the single user NX interface. nx_close is single-user equivalent - of nx_disconnect(). -

-

- Single user mode only! -

-

- Input Parameters: -

-

-

- Returned Value: None -

- -

2.3.9 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 avaiable. -

-

- Input Parameters: -

-

-

- Returned Value: -

- - -

2.3.10 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.11 nx_openwindow()

-

Function Prototype:

- -

- Description: Create a new window. -

-

- Input Parameters: -

-

-

- Returned Value: -

- - -

2.3.12 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.13 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.14 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.15 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.16 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.17 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.18 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.19 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.20 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.21 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.22 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.23 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.24 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.25 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.26 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.27 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.28 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.29 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.30 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_openwindow()

-

Function Prototype:

- -

- Description: Create a new, framed window. -

-

- Input Parameters: -

-
handle -
The handle returned by nx_connect() - or nx_open(). -
cb -
Callbacks used to process window events -
arg -
User provided argument (see nx_openwindow()) -
-

-

- Returned Value: -

- - -

2.4.3 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.4 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.5 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.6 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.7 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.8 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.9 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.10 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.11 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.12 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.13 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.14 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.15 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.16 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.17 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.18 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.19 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.19 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.21 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.22 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.23 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.24 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.25 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.26 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 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 Multi-User (Only) 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 appy 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 to 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 EXTRADEFINES=$(EXTRADEFINES)
-  endif
-  ifeq ($(CONFIG_NXFONT_MYFONT),y)
-      @$(MAKE) -C nxfonts -f Makefile.sources TOPDIR=$(TOPDIR) NXFONTS_FONTID=2 EXTRADEFINES=$(EXTRADEFINES)
-  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 configs/sim/nx - and configs/sim/nx11. - There are two alternative configurations for building the simulation: -

-
    -
  1. - The configuration using the configuration file at configs/sim/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: -
      -cd <NuttX-Directory>/tools
-./configure sim/nx
-cd  <NuttX-Directory>
-make
-./nuttx
-
    -
    2. -
  2. -

    - The preferred configuration is at configs/sim/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: -

    -
      -cd <NuttX-Directory>/tools
-./configure sim/nx11
-cd  <NuttX-Directory>
-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. - See the patch file 0001-Quick-hacks-to-build-sim-nsh-ostest-on-x86_64-as-32-.patch - that can be found in NuttX files. -

      -
      • -

    • - 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()Change to CONFIG_NX_MULTIUSER=y in the - <NuttX-Directory>/.config file YES
nx_connectinstance()Change to CONFIG_NX_MULTIUSER=y in the - <NuttX-Directory>/.config file YES
nx_open()
YES
nx_disconnect()Change to CONFIG_NX_MULTIUSER=y in the - <NuttX-Directory>/.config file YES
nx_close()
YES
nx_eventhandler()Change to CONFIG_NX_MULTIUSER=y in the - <NuttX-Directory>/.config fileYES
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_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_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/NXOrganization.gif b/Documentation/NXOrganization.gif deleted file mode 100644 index 6bae8e5529bbc177caf108e035f4e5c61ca4d2ec..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 34880 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 - -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 number of things that you must configure in order to be able to use any file system: -
    2. -
      -
    • - CONFIG_NFILE_DESCRIPTORS > 0. You must include support for file descriptors. -
      • -
    • - CONFIG_DISABLE_MOUNTPOINT=n. You must include support for mount points in the pseudo-file system. -
      • -
    -
  2. - And there are several dependencies on the networking configuration. - At a minimum, you need to have the following selections: -
    3. -
      -
    • - CONFIG_NET=y. General networking support. -
      • -
    • - CONFIG_NET_UDP=y. Support for UDP. -
      • -
    -
- - - - - -
-

Mount Interface

 -
- - -
    -int mount(const char *source, const char *target, const char *filesystemtype, unsigned long mountflags, const void *data);
-
-

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

-

- Input Paramters: -

    -
  • source. A null-terminated string providing the fill path to a block driver in the NuttX pseudo-file system. -
  • target. The location in the NuttX pseudo-file system where the volume will be mounted. -
  • filesystemtype. A string identifying the type of file system to use. -
  • mountflags. Various flags that can be used to qualify how the file system is mounted. -
  • data. Opaque data that is passed to the file system with the mount occurs. -
-

-

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

    -
  • EACCES. - A component of a path was not searchable or mounting a read-onlyfilesystem was attempted without giving the MS_RDONLY flag. -
    • -
  • EBUSY. - source is already mounted. -
    • -
  • EFAULT. - One of the pointer arguments points outside the user address space. -
    • -
  • EINVAL. - source had an invalid superblock. -
    • -
  • ENODEV. - filesystemtype not configured -
    • -
  • ENOENT. - A pathname was empty or had a nonexistent component. -
    • -
  • ENOMEM. - Could not allocate a memory to copy filenames or data into. -
    • -
  • ENOTBLK. - source is not a block device -
    • -
-

-

- 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: -

-
    -#include <sys/mount.h>
-#include <nuttx/fs/nfs.h>
-
-struct nfs_args data;
-char *mountpoint;
-
-ret = mount(NULL, mountpoint, string "nfs", 0, (FAR void *)&data);
-
-

- 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: -

-
    -struct nfs_args
-{
-  uint8_t  addrlen;               /* Length of address */
-  uint8_t  sotype;                /* Socket type */
-  uint8_t  flags;                 /* Flags, determines if following are valid: */
-  uint8_t  timeo;                 /* Time value in deciseconds (with NFSMNT_TIMEO) */
-  uint8_t  retrans;               /* Times to retry send (with NFSMNT_RETRANS) */
-  uint16_t wsize;                 /* Write size in bytes (with NFSMNT_WSIZE) */
-  uint16_t rsize;                 /* Read size in bytes (with NFSMNT_RSIZE) */
-  uint16_t readdirsize;           /* readdir size in bytes (with NFSMNT_READDIRSIZE) */
-  char    *path;                  /* Server's path of the directory being mount */
-  struct   sockaddr_storage addr; /* File server address (requires 32-bit alignment) */
-};
-
- - - - - -
-

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: -

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

- 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). -

-
    -NuttShell (NSH)
-nsh> ls /mnt
-/mnt:
-nsh: ls: no such directory: /mnt
-nsh> nfsmount 10.0.0.1 /mnt/nfs /export/shared
-nsh> ls -l /mnt/nfs
-/mnt/nfs:
- drwxrwxrwx   4096 ..
- drwxrwxrwx   4096 testdir/
- -rw-rw-rw-      6 ctest.txt
- -rw-r--r--     15 btest.txt
- drwxrwxrwx   4096 .
-nsh> echo "This is a test" >/mnt/nfs/testdir/testfile.txt
-nsh> ls -l /mnt/nfs/testdir
-/mnt/nfs/testdir:
- -rw-rw-rw-     21 another.txt
- drwxrwxrwx   4096 ..
- drwxrwxrwx   4096 .
- -rw-rw-rw-     16 testfile.txt
-nsh> cat /mnt/nfs/testdir/testfile.txt
-This is a test
-
- - - - - -
-

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 the these two commands: -

-
    -# sudo apt-get install nfs-common
-# sudo apt-get install nfs-kernel-server
-
- -

- 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. -

-
    -# sudo mkdir /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. -

-
    -# sudo chmod 777 /export
-
-

- 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: -

-
    -directory machine1(option11,option12)
-
-

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

-
    -/export 10.0.0.2(rw)
-
-

- 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: -

-
    -# sudo /etc/init.d/nfs-kernel-server start
-
-

- 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. -

-
    -# sudo /etc/init.d/nfs-kernel-server start
-
-

Or

-
    -# exportfs -ra
-
-

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

-
    -# sudo showmount -e
-# sudo showmount -a
-
-

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

-

-

    -# rpcinfo –p
-program vers proto   port
-   100000   2   tcp    111  portmapper
-   100000   2   udp    111  portmapper
-   100011   1   udp   749  rquotad
-   100011   2   udp   749  rquotad
-   100005   1   udp    759  mountd
-   100005   1   tcp    761  mountd
-   100005   2   udp    764  mountd
-   100005   2   tcp    766  mountd
-   100005   3   udp    769  mountd
-   100005   3   tcp    771  mountd
-   100003   2   udp   2049  nfs
-   100003   3   udp   2049  nfs
-   300019   1   tcp    830  amd
-   300019   1   udp    831  amd
-   100024   1   udp    944  status
-   100024   1   tcp    946  status
-   100021   1   udp   1042  nlockmgr
-   100021   3   udp   1042  nlockmgr
-   100021   4   udp   1042  nlockmgr
-   100021   1   tcp   1629  nlockmgr
-   100021   3   tcp   1629  nlockmgr
-   100021   4   tcp   1629  nlockmgr
-
-

- 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 206d284960..0000000000 --- a/Documentation/NuttShell.html +++ /dev/null @@ -1,4321 +0,0 @@ - - -NuttShell - - -
- - - - -
-

NuttShell (NSH)

-

Last Updated: April 11, 2015

-
-
- - - - -
-

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 Base64 Decode (base64dec) -

- 2.4 Base64 Encode (base64enc) -

- 2.5 Terminate a Loop (break) -

- 2.6 Concatenate Files (cat) -

- 2.7 Change Current Working Directory (cd) -

- 2.8 Compare Files (cmp) -

- 2.9 Copy Files (cp) -

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

- 2.11 Copy and Convert Files (dd) -

- 2.12 Delete a Routing Table Entry (delroute) -

- 2.13 Show volume status (df) -

- 2.14 Echo Strings and Variables (echo) -

- 2.15 Execute User Code (exec) -

- 2.16 Exit NSH (exit) -

- 2.17 Show Memory Manager Status (free) -

- 2.18 Get File Via TFTP (get) -

- 2.19 Show Usage Command Usage (help) -

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

- 2.21 Manage Network Configuration (ifconfig) -

- 2.22 Take a network down (ifdown) -

- 2.23 Bring a network up (ifup) -

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

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

- 2.26 List Directory Contents (ls) -

- 2.27 Calculate MD5 (md5) -

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

- 2.29 Show Current Tasks and Threads (ps) -

- 2.30 Create a Directory (mkdir) -

- 2.31 Create a FAT Filesystem (mkfatfs) -

- 2.32 Create a FIFO (mkfifo) -

- 2.33 Create a RAMDISK (mkrd) -

- 2.34 Mount a File System (mount) -

- 2.35 Rename a File (mv) -

- 2.36 Mount an NFS file system (nfsmount) -

- 2.37 Check Network Peer (ping/ping6) -

- 2.38 Send File Via TFTP (put) -

- 2.39 Show Current Working Directory (pwd) -

- 2.40 Remove a File (rm) -

- 2.41 Remove a Directory (rmdir) -

- 2.42 Set an Environment Variable (set) -

- 2.43 Execute an NSH Script (sh) -

- 2.44 Wait for Seconds (sleep) -

- 2.45 Unmount a File System (umount) -

- 2.46 Unset an Environment Variable (unset) -

- 2.47 URL Decode (urldecode) -

- 2.48 URL Encode (urlencode) -

- 2.49 Wait for Microseconds (usleep) -

- 2.50 Get File Via HTTP (wget) -

- 2.51 Hexadecimal Dump of Memory (xd) -
- 3.0 Configuration Settings -

 - 3.1 Command Dependencies on Configuration Settings -

- 3.2 NSH-Specific Configuration Settings -
- 4.0 Customimizing the NuttShell -

- 4.1 The NSH Library and NSH Initialization -

- 4.2 NSH Commands -

- 4.3 NSH "Built-In" Applications -

- 4.4 Customizing NSH Initialization -
- Index -
-
- - - - - -
-

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 greating 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. -

-

- 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 filesystem 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, it is 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 small FLASH footprint results but then also only simple environment variables like $FOO can be used on the command line. -
    • -
- - - - - -
-

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 commnd). The syntax is as follows: -

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

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
-
    -

    -
    • -
- -

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: -

-
    - - - - - - -
    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 filesystem containing the following: -
      -`--init.d/
-     `-- rcS
-
    - Where rcS is the NSH start-up script. -
    • -
  • - NSH will then mount the ROMFS filesystem 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 configs/<board>/include will be used. - NOTE when the OS is configured, include/arch/board will be linked to configs/<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 containg the ROMFS - file system image. -

- -

- Further Information. - See the section on Customimizing 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>
-
-

- 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> -

-

- Example: -

-
    -nsh> addroute 1.1.1.1 2.2.2.2 3.3.3.3
-
- - - - - -
-

2.3 Base64 Decode (base64dec)

 -
- -

Command Syntax:

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

- Synopsis. - To be provided. -

- - - - - -
-

2.4 Base64 Encode (base64enc)

 -
- -

Command Syntax:

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

- Synopsis. - To be provided. -

- - - - - -
-

2.5 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.6 Concatenate Files (cat)

 -
- -

Command Syntax:

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

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

- - - - - -
-

2.7 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.8 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.9 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 filesystem indicated by <dest-path>. -

- - - - - -
-

2.10 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, -

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

-

- 24-hour time is used. -

- - - - - -
-

2.11 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 devic, 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.12 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> -

- Example: -

-
    -nsh> delroute 1.1.1.1 2.2.2.2
-
- - - - - -
-

2.13 Show Volument 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.14 Echo Strings and Variables (echo)

 -
- -

Command Syntax:

-
    -echo [<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). -

- - - - - -
-

2.15 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.16 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 telenet session. -

- - - - - -
-

2.17 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.18 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 test ("netascii") transfer - mode. Default: text. -
- - - - - -
-

2.19 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.20 Hexadecimal Dump of File or Device (hexdump)

 -
- -

Command Syntax:

-
    -hexdump <file or device>
-
-

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

- - -
- - - - - - - - - -
-

2.21 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 ifconfigcommand 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 uIP statistics are enabled (CONFIG_NET_STATISTICS), then - this command will also show the detailed state of uIP. -

    -
    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. -
- - - - - -
-

2.22 Take a network down (ifdown)

 -
- -

Command Syntax:

-
    -ifdown <nic-name>
-
-

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

-

- Example: -

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

2.23 Bring a network up (ifup)

 -
- -

Command Syntax:

-
    -ifup <nic-name>
-
-

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

-

- Example: -

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

2.24 Send a signal to a task (kill)

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

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

-
    -nsh> mkfifo /dev/fifo
-nsh> cat /dev/fifo &
-cat [2:128]
-nsh> ps
-PID   PRI SCHD TYPE   NP STATE    NAME
-    0   0 FIFO TASK      READY    Idle Task()
-    1 128 FIFO TASK      RUNNING  init()
-    2 128 FIFO PTHREAD   WAITSEM  (51ea50)
-nsh> kill -9 2
-nsh: cat: open failed: 4
-nsh> ps
-PID   PRI SCHD TYPE   NP STATE    NAME
-    0   0 FIFO TASK      READY    Idle Task()
-    1 128 FIFO TASK      RUNNING  init()
-nsh>
-
-

- NOTE: - NuttX does not support a FULL POSIX signalling system. - Standard signals like SIGCHLD, SIGINTR, SIGKILL, etc. do not exist in NuttX and sending those signal may not have the result that you 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. - But, as an example, kill -9 (SIGKILL) will not terminate a task. -

- - - - - -
-

2.25 Setup/teardown the Loop Device (losetup)

 -
- -

Command Syntax 1:

-
    -losetup [-o ] [-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.26 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 filesystem - 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.27 Calculate MD5 (md5)

 -
- -

Command Syntax:

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

- Synopsis. - To be provided. -

- - - - - -
-

2.28 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.29 Show Current Tasks and Threads (ps)

 -
- -

Command Syntax:

-
    -ps
-
-

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

-
    -nsh> ps
-PID   PRI SCHD TYPE   NP STATE    NAME
-    0   0 FIFO TASK      READY    Idle Task()
-    1 128 RR   TASK      RUNNING  init()
-    2 128 FIFO TASK      WAITSEM  nsh_telnetmain()
-    3 100 RR   PTHREAD   WAITSEM  <pthread>(21)
-nsh>
-
- - - - - -
-

2.30 Create a Directory (mkdir)

 -
- -

Command Syntax:

-
    -mkdir <path>
-
-

- Synopsis. - Create the directory at <path>. - All components of 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 filesystem 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 filesystem. -

-

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.31 Create a FAT Filesystem (mkfatfs)

 -
- -

Command Syntax:

-
    -mkfatfs [-F <fatsize>] <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. -

-

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

- - - - - -
-

2.32 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.33 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<n> (if <n> 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.34 Mount a File System (mount)

 -
- -

Command Syntax:

-
    -mount -t <fstype> <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 provied 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 filesystem. - 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 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. -
    4. -
-

- After the volume has been mounted in the NuttX - pseudo filesystem, - it may be access in the same way as other objects in thefile 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.35 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 filesystem. -

- - - - - -
-

2.36 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.37 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. -

- - - - - -
-

2.38 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 test ("netascii") transfer - mode. Default: text. -
- - - - - -
-

2.39 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.40 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 filesystem 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 filesystem. -

-

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.41 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 filesystem 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 filesystem. -

-

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.42 Set an Environment Variable (set)

 -
- -

Command Syntax:

-
    -set <name> <value>
-
-

- Synopsis. - Set the environment variable <name> to the string <value>. - For example, -

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

2.43 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.44 Wait for Seconds (sleep)

 -
- -

Command Syntax:

-
    -sleep <sec>
-
-

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

- - - - - -
-

2.45 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.46 Unset an Environment Variable (unset)

 -
- -

Command Syntax:

-
    -unset <name>
-
-

- Synopsis. - Remove the value associated with the environment variable - <name>. Example: -

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

2.47 URL Decode (urldecode)

 -
- -

Command Syntax:

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

- Synopsis. - To be provided. -

- - - - - -
-

2.48 URL Encode (urlencode)

 -
- -

Command Syntax:

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

- Synopsis. - To be provided. -

- - - - - -
-

2.49 Wait for Microseconds (usleep)

 -
- -

Command Syntax:

-
    -usleep <usec>
-
-

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

- - - - - -
- 2.50 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.51 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 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 configuation 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. -

- - - - - -
-

3.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
base64decCONFIG_NETUTILS_CODECS && CONFIG_CODECS_BASE64CONFIG_NSH_DISABLE_BASE64DEC
base64encCONFIG_NETUTILS_CODECS && CONFIG_CODECS_BASE64CONFIG_NSH_DISABLE_BASE64ENC
break!CONFIG_NSH_DISABLESCRIPT && !CONFIG_NSH_DISABLE_LOOPS 
catCONFIG_NFILE_DESCRIPTORS > 0CONFIG_NSH_DISABLE_CAT
cd!CONFIG_DISABLE_ENVIRON && CONFIG_NFILE_DESCRIPTORS > 0CONFIG_NSH_DISABLE_CD
cmpCONFIG_NFILE_DESCRIPTORS > 0CONFIG_NSH_DISABLE_CMP
cpCONFIG_NFILE_DESCRIPTORS > 0CONFIG_NSH_DISABLE_CP
date
CONFIG_NSH_DISABLE_DATE
ddCONFIG_NFILE_DESCRIPTORS > 0CONFIG_NSH_DISABLE_DD
delrouteCONFIG_NET && CONFIG_NET_ROUTECONFIG_NSH_DISABLE_DELROUTE
df!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_READABLE3CONFIG_NSH_DISABLE_DF
echo
CONFIG_NSH_DISABLE_ECHO
exec
CONFIG_NSH_DISABLE_EXEC
exit
CONFIG_NSH_DISABLE_EXIT
free
CONFIG_NSH_DISABLE_FREE
getCONFIG_NET && CONFIG_NET_UDP && - CONFIG_NFILE_DESCRIPTORS > 0 && MTU >= 5581CONFIG_NSH_DISABLE_GET
help5
CONFIG_NSH_DISABLE_HELP
hexdumpCONFIG_NFILE_DESCRIPTORS > 0CONFIG_NSH_DISABLE_HEXDUMP
ifconfigCONFIG_NETCONFIG_NSH_DISABLE_IFCONFIG
ifdownCONFIG_NETCONFIG_NSH_DISABLE_IFUPDOWN
ifupCONFIG_NETCONFIG_NSH_DISABLE_IFUPDOWN
kill!CONFIG_DISABLE_SIGNALSCONFIG_NSH_DISABLE_KILL
losetup!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0CONFIG_NSH_DISABLE_LOSETUP
lsCONFIG_NFILE_DESCRIPTORS > 0CONFIG_NSH_DISABLE_LS
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_FS_WRITABLE) || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS) && CONFIG_NFILE_DESCRIPTORS > 0)4CONFIG_NSH_DISABLE_MKDIR
mkfatfs!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_FATCONFIG_NSH_DISABLE_MKFATFS
mkfifoCONFIG_NFILE_DESCRIPTORS > 0CONFIG_NSH_DISABLE_MKFIFO
mkrd!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_WRITABLE4CONFIG_NSH_DISABLE_MKRD
mount!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_READABLE3CONFIG_NSH_DISABLE_MOUNT
mv(((!CONFIG_DISABLE_MOUNTPOINT && CONFIG_FS_WRITABLE) || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS) && CONFIG_NFILE_DESCRIPTORS > 0)4CONFIG_NSH_DISABLE_MV
nfsmount!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_NET && CONFIG_NFSCONFIG_NSH_DISABLE_NFSMOUNT
pingCONFIG_NET && CONFIG_NET_ICMP && - CONFIG_NET_ICMP_PING && !CONFIG_DISABLE_SIGNALSCONFIG_NSH_DISABLE_PING
ping6CONFIG_NET && CONFIG_NET_ICMPv6 && - CONFIG_NET_ICMPv6_PING && !CONFIG_DISABLE_SIGNALSCONFIG_NSH_DISABLE_PING6
ps
CONFIG_NSH_DISABLE_PS
putCONFIG_NET && CONFIG_NET_UDP && - CONFIG_NFILE_DESCRIPTORS > 0 && MTU >= 5581,2CONFIG_NSH_DISABLE_PUT
pwd!CONFIG_DISABLE_ENVIRON && CONFIG_NFILE_DESCRIPTORS > 0CONFIG_NSH_DISABLE_PWD
rm(((!CONFIG_DISABLE_MOUNTPOINT && CONFIG_FS_WRITABLE) || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS) && CONFIG_NFILE_DESCRIPTORS > 0)4CONFIG_NSH_DISABLE_RM
rmdir(((!CONFIG_DISABLE_MOUNTPOINT && CONFIG_FS_WRITABLE) || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS) && CONFIG_NFILE_DESCRIPTORS > 0)4CONFIG_NSH_DISABLE_RMDIR
set!CONFIG_DISABLE_ENVIRONCONFIG_NSH_DISABLE_SET
shCONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_NFILE_STREAMS > 0 && !CONFIG_NSH_DISABLESCRIPTCONFIG_NSH_DISABLE_SH
sleep!CONFIG_DISABLE_SIGNALSCONFIG_NSH_DISABLE_SLEEP
test!CONFIG_NSH_DISABLESCRIPTCONFIG_NSH_DISABLE_TEST
umount!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_READABLE3CONFIG_NSH_DISABLE_UMOUNT
unset!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
usleep!CONFIG_DISABLE_SIGNALSCONFIG_NSH_DISABLE_USLEEP
wgetCONFIG_NET && CONFIG_NET_TCP && - CONFIG_NFILE_DESCRIPTORS > 0CONFIG_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 optionss will probably be required to permit - creation of files for the correct operation of the put command.
- 3 - CONFIG_FS_READABLE is not a user configuration but is set automatically - if any readable filesystem is selected. At present, this is either CONFIG_FS_FAT - or CONFIG_FS_ROMFS.
- 4 - CONFIG_FS_WRITABLE is not a user configuration but is set automatically - if any writable filesystem is selected. At present, this is only CONFIG_FS_FAT.
- 5 - 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. - -

- - - - - -
-

3.2 NSH-Specific Configuration Settings

 -
- -

- The behavior of NSH can be modified with the following settings in - the configs/<board-name>/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 filesystem). 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. -
CONFIG_NSH_TMPDIR - If CONFIG_NSH_CMDPARMS is selected, then function output will be retained - in a temporary file. In that case, this string must be provided to - specify the full path to a directory where temporary files can be - created. This would be a good application of RAM disk: To provide - temporary storage for function output. -
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_NESTDEPTH - The maximum number of nested if-then[-else]-fi sequences that - are permissable. 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 filesystem 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 the 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 TELENET - 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/reponses -
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_MTU=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 configs/<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. -
- - - - - -
-

4.0 Customimizing 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 in Unix shell programming. - The paragraphs in this appendix will focus on customizing NSH: Adding new commands, changing the initialization sequence, etc. -

- - - - - -
-

4.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. -

- -

4.1.1 NSH Initialization sequence

- -

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

- -
    -
  1. -

    - If you have C++ static initializers, it will call your implementation of up_cxxinitialize() which will, in turn, call those static initializers. - For the case of the STM3240G-EVAL board, the implementation of up_cxxinitialize() can be found at nuttx/configs/stm3240g-eval/src/up_cxxinitialize.c. -

    -
  2. -

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

    -
  3. -

    - 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. -

    -
  4. -

    - 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. -

    -
- -

4.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 filesystem 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 configs/stm3240g-eval/src/up_nsh.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. -

    -
- - - - - -
-

4.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. -

- -

4.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, "e;Hello, World!"e;);
-  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 commnd, 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. -

- - - - - -
-

4.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. -

- -

4.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/binfmt/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-directores, 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 compatibility, but does not really add any new functionality. -

    -
    2. -
- -

4.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. -

- - - - - -
-

4.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 configs/stm3240g-eval/src/up_nsh.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.examplex/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 -

    -
- -

4.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 filesystem containing the following: -

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

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

    -
  • -

    - NSH will then mount the ROMFS filesystem 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: -

-
    - configs/hymini-stm32v/nsh2
    - configs/ntosd-dm320/nsh
    - configs/sim/nsh
    - configs/sim/nsh2
    - configs/sim/nx
    - configs/sim/nx11
    - configs/sim/touchscreen
    - configs/vsn/nsh     -
-

- 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. - The only example that uses a custom /etc/init.d/rcS file in the NuttX source tree is this one: configs/vsn/nsh. - The configs/vsn/nsh/defconfig file also has this definition: -

-
    CONFIG_NSH_ARCHROMFS=y -- Support an architecture specific ROMFS 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/nhslib OR if CONFIG_NSH_ARCHROMFS is defined to configs/<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 configs/<board>/includewill be used. - NOTE when the OS is configured, include/arch/board will be linked to configs/<board>/include. -

- -

- As mention above, the only example that uses a custom /etc/init.d/rcS file in the NuttX source tree is this one: configs/vsn/nsh. - The custom script for the configs/vsn case is located at configs/vsn/include/rcS.template. -

- -

- 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 containg 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. -

    -
-

- You can find the generated ROMFS file system for the configs/vsn case here: configs/vsn/include/rcS.template -

- - - - - -
-

Index

 -
- - - - - -
- - -
- - - diff --git a/Documentation/NuttX.html b/Documentation/NuttX.html deleted file mode 100644 index 2ba7ac9794..0000000000 --- a/Documentation/NuttX.html +++ /dev/null @@ -1,5226 +0,0 @@ - - -NuttX - - -
- - - - -
-

NuttX RTOS

-

Last Updated: June 9, 2015

-
-
- - - - -
-

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. -
-
- - - - - -
-

Overview

 -
- -

- Goals. - NuttX is a real timed 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: (1) 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. - (2) There is no MMU-based support for processes. - At present, NuttX assumes a flat address space. -

-
- 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 and round-robin 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, environment variables, filesystem.
    • -

    -

    		 -

    -

  • VxWorks-like task management and watchdog timers.
    • -

    -

    		 -

    -

  • BSD socket interface.
    • -

    -

    		 -

    -

  • Extensions to manage pre-emption.
    • -

    -

    		 -

    -

  • Optional tasks with address environments (Processes).
    • -

    -

    		 -

    -

  • 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.
    • -

    -

    		 -

    -

  • 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 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. -
    • -

    -

    		-

    -

  • ROMFS filesystem support.
    • -

    -

    		-

    -

  • BINFS pseudo-filesystem support.
    • -

    -

    		-

    -

  • Union filesystem - Supports combining and overlaying file systems.
    • -

    -

    		-

    -

  • 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.
    • -

    -

    		-

    -

  • Asynchronous I/O (AIO)
    • -

    -

    		-

    -

  • - Network, USB (host), USB (device), serial, I2C, I2S, NAND, CAN, ADC, DAC, PWM, Quadrature Encoder, Wireless, 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: frambuffer drivers, graphic- and segment-LCD drivers.
    • -

    -

    		-

    -

  • 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, IGMPv2 (client) stacks.
    • -

    -

    		-

    -

  • Stream and datagram sockets.
    • -

    -

    		-

    -

  • Raw socket and local, Unix domain socket support.
    • -

    -

    		-

    -

  • SLIP
    • -

    -

    		-

    -

  • A port cJSON
    • -

    -

    		-

    -

  • Small footprint (based on uIP).
    • -

    -

    		-

    -

  • BSD compatible socket layer.
    • -

    -

    		-

    -

  • Networking utilities (DHCP server and client, SMTP client, TELNET client, FTP server and client, TFTP client, HTTP server and client, NTP client). - Inheritable TELNET sessions (as "controlling terminal")
    • -

    -

    		-

    -

  • 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., the TI CC3000 WLAN module). -
    • -

    -
    - FLASH Support -

    		-

    -

  • MTD-inspired interface for Memory Technology Devices.
    • -

    -

    		 -

    -

  • NAND support.
    • -

    -

    		 -

    -

  • FTL. Simple Flash Translation Layer support file systems on FLASH.
    • -

    -

    		 -

    -

  • NXFFS. the NuttX wear-leveling FLASH file system.
    • -

    -

    		 -

    -

  • 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 PIC32, Atmel AVR, SAM3, SAM4, and SAMA5Dx, NXP LPC17xx, LPC214x, LPC313x, and LPC43xx, Silicon Laboraties EFM32, STMicro STM32 F1, F2, F3, and F4, and TI DM320.
    • -

    -

    		 -

    -

  • Device-dependent USB class drivers available for USB serial (CDC/ACM and a PL2303 emulation), for USB mass storage, and for a composite CDC/ACM and mass storage device.
    • -

    -

    		 -

    -

  • 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.
    • -

    -

    		 -

    -

  • - 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."
    • -

    -
    - Pascal Compiler with NuttX runtime P-Code interpreter add-on -

    		-

    -

  • The Pascal add-on is available for download from the - Bitbucket.org - website.
    • -

    -
    - -

    - 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 Yahoo! NuttX group. - You are cordially invited to join. - 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 7.10. - NuttX 7.10 is the 110th release of NuttX. - It was released on June 9, 2015, and is available for download from the - Bitbucket.org website. - Note that the release consists of two tarballs: nuttx-7.10.tar.gz and apps-7.10.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 NuttX 7.10 are available here. - Release notes for all released versions on NuttX are available in the Bitbucket GIT. - The ChangeLog for all releases of NuttX is available in the ChangeLog file that can viewed in the Bitbucket GIT. - The ChangeLog for the current release is at the bottom of that file. -

        -
      -
    • apps. -

        - Release notes for NuttX 7.10 are available here. - Release notes for all released versions on NuttX are available in the Bitbucket GIT - The ChangeLog for the all releases of apps/ is available in the ChangeLog file that can viewed in the Bitbucket GIT. - The ChangeLog for the current release is at the bottom of that file. -

        -
      -
    • NxWidgets. -

        - Release notes for NxWidgets 1.13 are available here. - Release notes for all released versions on NxWidgets are available in the BitBucket GIT - The ChangeLog for all releases of NxWidgets is available at the bottom of the ChangeLog file that can viewed in the Bitbucket GIT. -

        -
      -
    • pascal. -

        - Release notes for all released versions on pascal are available in the Bitbucket GIT - The ChangeLog for all releases of pascal is available at the bottom of the ChangeLog file that can viewed in the Bitbucket GIT. -

        -
      -
    • 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 - -
    • -
  • Renesas/Hitachi: - -
    • -     		-
  • 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)
      • -
    -
    • -
  • Atmel - -
    • -
  • Freescale - -
    • -
  • Host PC based simulations - -
    • -
  • Intel - -
    • -
  • MicroChip - -
    • -     		-
  • nuvoTon - -
    • -
  • NXP - -
    • -
  • Renesas/Hitachi: - -
    • -
  • Silicon Laboratories, Inc. - -
    • -
  • STMicroelectronics - -
    • -     		- -
  • 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. -

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - 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. -

      -
    -


    		-

    - TI Calypso. - This port supports the TI "Calypso" MCU used in various cell phones (and, in particular, - by the Osmocom-bb project). - Like the c5471, NuttX operates on the ARM7 of this dual core processor. - Board support is available for the Motorola C139, C155 and W220 phones and for the Pirelli DP-L10 phone. -

    -
      -

      - STATUS: - This port was contributed by Denis Carilki and includes the work of Denis Carikli, Alan Carvalho de Assis, and Stefan Richter. - Calypso support first appeared in NuttX-6.17 with LCD drivers. - Support for the Calypso keyboard was added in NuttX-6.24 by Denis Carilki. - Refer to the NuttX board README files for the Compal E88, Compal E99 and Pirelli DP-L10 phones 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. -

      -
    -
    - 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. -

      -
    -
    - ARM Cortex-A5. -

    		-

    - 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. -

      -
      • -
    -
    - 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 completed 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. -

      -
    -


    		-

    - 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. - This is a work in progress. - 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. -

      -
    -


    		-

    - NXP LPC11xx. - Support is provided for the NXP LPC11xx family of processors. - In particular, support is provided for LPCXpression 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. -

      -
    -
    - 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 Evalution 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. -

      -

      - 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 Evalution 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 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. -

    -


    		-

    - 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 suppport 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). - 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 32L152CDISCOVERY 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.
        • -
      -

      - STATUS. - Initial support for the STM32L-Discovery was released in NuttX-6.28. - This initial support includes 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. - As of this writing, a few more things are needed to make this a more complete port: 1) Verfication of more device drivers (timers, quadrature encoders, PWM, etc.), and 2) logic that actually uses the low-power consumption modes of the EnergyLite part. - 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 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 staill available for further application development while NSH is running. -

      -


    		-

    - STMicro STM32F152x/162x(STM32 F1 "EnergyLite" Medium+ Density Family). - Support for the STM32152 and STM32162 Medium+ density parts from Jussi Kivilinna and Sami Pelkonen was included in NuttX-7.3, extending the basic STM32F152x support. - 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. -

    -


    		-

    - 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). - This 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. -

    -
      -

      - 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 four MCUs and four 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. -

      - ISOTEL NetClamps VSN. - The ISOTEL NetClamps VSN V1.2 ready2go sensor network platform based on the - STMicro STM32F103RET6. Contributed by Uros Platise. - Refer to the NuttX board README file for further information. -

      -
      3. -
    3. -

      - HY-Mini STM32v board. - This board is based on the STM32F103VCT chip. Port contributed by Laurent Latil. - Refer to the NuttX board README file. -

      -
      4. -
    4. -

      - 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. -

      -
      5. -
    5. -

      - 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. -

      -
      6. -
    6. -

      - Spark (and emulated Spark). - The Spark boards are based on the STM32F103CBT6 chip and feature wireless networking using the TI CC3000 WLAN module. - See the Spark web site for hardware information; - The emulated Spark is a base board for the Maple Mini board (see above) developed by David Sidrane that supports Spark development while we all way breathlessly for or Spark boards. - see the NuttX board README file for further information about the NuttX port. -

      -

      - Initially Spark support was introduced in NuttX 6.31 and completed in NuttX 6.32. - Most of this work is the result of the effort of David Sidrane. -

      -
      7. -
    7. -

      - Olimexino-STM32. - This port uses the Olimexino STM32 board (STM32F103RBT6). - See the http://www.olimex.com for further information. - Contribued by David Sidrane. -

      -
      8. -
    -

    - 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. -

        -
        • -
      • -

        - NetClamps VSN. - Support for the NetClamps VSN was included in version 5.18 of NuttX. - Uros Platise added support for timers, RTC, I2C, FLASH, extended power management - and other features. -

        -
        • -
      • -

        - 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. -

        -
        • -
      • -

        - Spark. - David Sidrane has the emulated Spark board up-and-running with a functional CC3000 network, SST25 FAT file system, an NSH shell, and a composite USB CDC/ACM and USBMSC devices. This configuration is was first available NuttX 6.31 and completed in NuttX 6.32. - That is really quite a lot of high end functionality on an STM32 that only has 20KB of RAM! I am impressed! -

        -
        • -
      • -

        - 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. -

        -
        • -
      -
    -

    - 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 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 there 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 SViewtool STM32F103/F107 README file for further information. -

      -
      • -


    		-

    - STMicro STM32F205 (STM32 F2 family). - Architecture only support for the STM32F205RG was contributed as an anonymous contribution in NuttX-7.10 -

    -
      - STATUS: - There are currently on board configurations for any board using the STM32F205. -


    		-

    - 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. -
      • -
    -

    -
      - 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. -
    -


    		-

    - 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. - This port uses the Arduino Due development board that features the ATSAM3X8E MCU running at 84MHz. - See the Arduino Due page for more information. -

    -
      -

      - 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 Arduino Due port was released in NuttX-6.29. - Refer to the NuttX board README file for further information. -

      -
    -

    - 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 three 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. -
      • -
    -

    -

    - The Nucleus 2G board, the mbed board, and the LPCXpresso 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 occured 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). -

        -
        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. -
      -
    -

    - 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. -
    -
    - ARM Cortex-M4. -

    		-

    - FreeScale Kinetis K20. - Archicture support (only) was added in NuttX-7.10. - This support was taken from PX4 and is the work of Jakob Odersky. -

    -
      -

      - STATUS: - There are no K20 boards yet supported. - Work is underway on the the PJRC Teensy-3.1 board and that port is expected in NuttX-7.11. - Refer to the Teensy-3.1 board README file for further information. -

      -
    -


    		-

    - 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. -

      -
    -


    		-

    - 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. - Ethernet and SD card (SDHC) drivers also exist: - The SDHC driver is partially integrated in to the NSH configuration but has some outstanding issues; - the Ethernet driver is completely untested. - Additional work remaining includes: (1) integrate the Ethernet and SDHC drivers, and (2) develop support for USB host and device. - NOTE: Most of these remaining tasks (excluding the Ethernet driver) are the same as the pending K40 tasks described above. - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - STMicro STM32 F302 (STM32 F3 family). - Architecture (only) support for the STM32 F302 was contributed in NuttX-7.10 by Ben Dyer (vi the PX4 team and David Sidrane). -

    -
      -

      - STATUS: - There are currently no board configurations using the STM32 F302. -

      -
    -


    		-

    - STMicro STM32 F302 / STM32F3-Discovery (STM32 F3 family). - 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 STM32 F372/F373 (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 STM32401x (STM32 F4 family). -

      -

      - Nucleo F401RE. - This port uses the STMicro Nucleo F401RE board featuring the STM32F104RE 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. -
      • - Refer to the NuttX board README file for further information. -
        • -
      -

      -


    		-

    - STMicro STM32407x (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. -
        • -
      • - Refer to the NuttX 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. -

      -


    		-

    - 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). -

    -


    		-

    - 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 intial 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. -
      • -
    -

    - Refer to the STM32F429I-Discovery board README file for further information. -

    -


    		-

    - NCP LPC43xx. - Two 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 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. -

        -

        - 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. -

        • -
      -

      - 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. -

        -
        • -
      -


    		-

    - 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). -

    -
      -

      - STATUS: -

        -
      • - 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). -
        • -
      • - The fully verified port to the EK-TM4C123GXL was provided in NuttX-7.2. -
        • -
      • - An I2C driver was added in NuttX-7.7. -
        • -
      -

      - Refer to the EK-TM4C123GXL board README file for more detailed information about this port. -

      -
    -


    		-

    - 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. -
        • -
      -

      - 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.. -
        • -
      -

      - Refer to the DK-TM4C129X board README file for more detailed information about this port. -

      -
    -


    		-

    - TI/Tiva CC3200 Launchpad. - TI/Tiva CC3200 Launchpad -

    -
      -

      - STATUS: - This is very much a work in progress. - The basic port was released in NuttX-7.5. - This basic board supported includes an verified configuration for the NuttShell NSH). - Key wireless networking capability is still missing. - Refer to the CC3200 LaunchPad board README file for more detailed information about this port. -

      -
    -


    		-

    - 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 staill available for further application development while NSH is running. -

      -
    -


    		-

    - Atmel SAM4C. - 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 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 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 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 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 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 but not yet functional).
        • -
      • On-board AT24 I2C EEPROM.
        • -
      • On-board WM8904 Audio CODEC with CS2100-CP Fractional-N Multipier (not yet tested).
        • -
      • Support for the (optional) maXTouch Xplained Pro LCD module (still a work in progress).
        • -
      -

      - Refer to the NuttX board README file for further information. -

      -
    -


    		-

    - 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. -

        -
      -
    -


    		-

    - 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. -

      -
    -
    - 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, Cywgin, MinGW the GCC toolchain under Linux or Cygwin. -

    -
      -

      - STATUS: - The basic port was code-complete in NuttX-5.19 and verifed 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 interest in fleshing out the x86 port! - Refer to the NuttX README file for further information. -

      -
    -


    		-

    - RGMP. - RGMP stands for RTOS and GPOS on Multi-Processor. - RGMP is a project for running GPOS and RTOS simultaneously on multi-processor platforms - You can port your favorite RTOS to RGMP together with an unmodified Linux to form a hybrid operating system. - This makes your application able to use both RTOS and GPOS features. -

    -

    - See the RGMP Wiki for further information about RGMP. -

    -
      -

      - STATUS: - This initial port of NuttX to RGMP was provided in NuttX-6.3. - This initial RGP port provides only minimal driver support and does not use the native NuttX interrupt system. - This is a great, stable starting point for anyone interest in working with NuttX under RGMP! - Refer to the NuttX README file for further information. -

      -
    -
    - MicroChip PIC32MX (MIPS 24Kc). -

    		-

    - 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 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 avaiable from the Pinquino website. -
      3. -
    3. - The MIPS SDE toolchain available from the Mentor Graphics website. -
      4. -
    -
    - MicroChip PIC32MZ (MIPS M14K). -

    		-

    - PIC32MZEC Family. - 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. -

    -
      -

      - STATUS: - This is a collaborative effort between Kristopher Tate, David Sidrane and myself. - The basic port is functional and a NuttShell (NSH) configurqation is available. - The first official release was in NuttX-7.9. - Current efforts are focused on driver development. - 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),
        • -
      -

      - 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. -

      -
    -
    - 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 two eZ80Acclaim! ports: -

    -
      -
    • One uses the ZiLOG ez80f0910200kitg development kit, and -
    • The other uses the ZiLOG ez80f0910200zcog-d development kit. -
    -

    - Both boards are based on the eZ80F091 part and both use the Zilog ZDS-II - Windows command line tools. - The development environment is either Windows native or Cygwin under Windows. -

    -
      -

      - STATUS: - Integration and testing of NuttX on the ZiLOG ez80f0910200zcog-d is complete. - 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. -

      -
    -
    - 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. -

      -
        -
    - -
    * 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. - For Windows native GCC compilers, the generated dependencies are windows paths and not - directly usable in the Cygwin make. By default, dependencies are suppressed for these - compilers as well. -
      • -

      - NOTE: dependencies are suppress 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 neede 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 envionment. -

    -
    - - - - - -
    -

    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

     -
    - -
      -
    • 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. -
    • EnergyLite is a trademark of STMicroelectronics.
      • -
    • EFM32 is a trademark of Silicon Laboratories, Inc.
      • -
    • LPC2148 is a trademark of NXP Semiconductors.
      • -
    • TI is a tradename 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/NuttX.png b/Documentation/NuttX.png deleted file mode 100644 index 360e657dd20f3c2326d8a06b1f96e974f9a5099d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4961 zcmai2c{r5c+kb|JVZzuZDa-hhog&FL_Cm5H48jP-AR_BvdJM7@Ws9;!lx@Z~(qt!P z$%L#aQhgON6+@=s9l!VeqheeQFeb3gaF&y#9rbC!=+oEHE9K1&NT z2XO;3AkpLjHXlZ8b7&W_A6q|LlKW?DYpeeI${@vOKOF@Be zrw35SOy0hR$#_4KElnpcS-GQfRIRwESr!>TGW)Vl*K3Hbs9DOLvH|p@$qi;4zaR~_ zm2&&^9fi7`L}ZOZC~p5zT~kvSciuK( zXS}oc+aJE0D(CY@4K%r2jXWcG|5?gZu)}Lz!w7h7&}$5Sd1+xpqG7J!wM)U`|5WW^ zAohwd4q)O}>utcL^;==N)Q5QxN zZYON{)~-?|HDAXGnWQJZGWFu?(25M~9bF$$4;){*|Gr^#%+Z8>-@t!c zS_oFYvUuPIwAColF)pIa- z9TMby9j|XMo*MuRuZWZp((H`PJ+wb(cSPu-uT}*;)L5_(tgh^2zTS&o>2Df;eWd!7 z0KdS7K+s$qqL-6(r#JupWJ5wTyh*dUvdpT#YQpIRML*-b!B#2G+$Z!wbvR0VH@xMY z`-!r<0- zVSy_Aoz;%3Q_Abs3j^1RFTEF_A~cSG>89&mTKG2b&N;orXU{Zm*%@j54b&*=za1x~ z@%?D{+>b=6xMB%gL#6)hMJ=B*%@9E@oPP$(#i2O%r19h}^q`%?oBiQvMEBG7hV-2hyvvF!{SH5=+ zpE_*|8<~}NriEHwAwLzHs>tBQ8kK*@RbEaHHIIfmpG{0Qu1|&9kAgNHi?Vfr-dXxa0d^Jx*)RJ8KOEe+r-PIF32aJv#*tc5JgV>i>S|mK_zV632 znFckdQijIC2vl=GXDBCALQJBjSRv1*;F9t~h+7cZPgOx2Z{tE!BG#^L^(<5Us9QX? zkgL65;z?Vk891s4cfCpDVTulg6?4$ipo))Wb64@Muqb!lpOE=oHAB9Zs zvlh0G>5Oc7`lPmpAU|4Oby|g3yIQ4mfa)35I~*_4Rhrf0<%Cq}-WoR`8T0KNFEQju z%L$?D_;>qBzyCe)IbCJ7>Q9_l$wSTg+lx1MQHy@vwJOgZlMWTg;L#(k(^s?C_mt~j z{61B-5H<^LN?Tj6Y|k6Q+((rd;~Z!;Mwmp`8RXy3FNZ=ucl4&SQ^z7QL~q~>%e4DVb!X<2*IO88g<~xC;#3v z5o4f7a|sTZT)FGfyzs3cdfdE-y)8A2FutysN%|uwXEn&)=6cLNbOUy(Dfy791tf#& zW2`{!6N9C>=-o_;;FKD>0W{j+}_E9|c)sAVpV1nR%n`mKR+((<@%d zcO&-ws(hcnn7=VjBJDAY@gV`G?9@+Z?+)q`56YRz11W7TZQ<`9i;rD*1BR>qRHHrz zuva4o8Q5;xK=F*0d|(cfzmVfF_%6N&P*9zAP5FfF{Pk%ZAGPvx>UF~27el_156rs^ zZaY`=hN5qLfFXlKcfBsOw39#9V z#jm9|zIcnp(cxh|8qdv(8RmM)XHv%YUi-0Zm(IxlGiPgCrissfJ0IaLE%HMLH3q(v z2=LQLm5AI!M>3O|S4vkDo7~U^rdN-2u}{xroD>UFVpRc+b`4?9v$Qssu$@_q69|*< z^O3_MCjDyoX2Oj_qkqo+h4^fNMVUUCPF^QzFa5nR&-m4R|DanjWr6n;vQ{m4n(d!GzYlxH+Sfa! zxdaj#4FjX&&J6c}@A_4lKS8?&fs!D`cYe1q@Y8fA_r9(RI{3|#?h0ssqZAG%YQIo3 zr=DvTN7VPlXftYVrK$_*rg^hx4MJ%~G2<4@vmHA$gv^LgR>jZ)uOesSRgI>r zG7M$Z@P55{RhNweK7t-(&uqjUg|usn1xMQ5rarNx!g-+kb}LByrw6~!PgOmCc)r2_ z+xZ-EFX_TLUVzy0@#QzEVzV7QhYUKR_v-Yoos8)x8RxaHbo*2;9A+Liegd7uetQ4W z#2$nL4nA)ssG?y{Icb~Eq68Ak)_lABn(xf*zKHl3L)8;6y#cbMJ*xgF` zb6?*J-|kSz9}6+LqWa1_p0espvhmvtjRD_r;NyTZxxFL?(8WVCTF!y;@MwJ8+ID=C z$5L^lJ?3%Z+_pIy-*N@TwIM{baY6JA$nn3A-}39L8p~VzR}OxPQ_7Aa{_-3`7i&D( zZxzEwawTK7l>oN(9ha;&mg_l^{d}oMgO@V>9k471Yxgl$W+-1;kNY!!x=A+wh3d2t zJ{gFCny6!FX)LR$*hF-MrCPKrjTc|}AJ~OdeLHyE)xWnFcB z4vbj9!MvIf*W1ItVBw8q&vKhDmC&`GDG|bmk&8m#+#qNs%}fn2M$)zTy#9e@{~ir% zyS`8et-5D2V|xu49Z9SHbSixGjs3x~Dd7S%>fxKqZAfqWya%tc}rF`ei#4 z@wpM|$4FNdn0jBj&Q3l(SB`WE5f$-KCrh%CCzaV}|MQ`dWv)1Rl~+g5$AB~^GqQB% z^r$~v7vky0p->22nlJWl%JpbTgf5hh1K(DB;Mjq^-aM6O` zjT9+zmiLmOBy%L~PX8=8vvIg~r|8Jf-?3ru7jZaXo+6E7=Ul~8y40^YUE~G$PFz%M zloY;9I&ynf(x_GC)lfWY?J{6-e!$zm8?T$$66u~o7yWlnCFb3PWih?QfDnwy%4b>e zBxmR%;qb5H(e7Vv2PRscJ4J}_#g8fslbeg(b|M|)u}&MeT4IuFp4k>P{!wW_DL-xn=EAzlmJigF9F z1lX}$#7C6^r>&B)`!5iIR;}d}Ffs-USt~-zu?suutQ_sZ?2Ef1RPwsxZCSCFd?%zEm-UsHl z`E*8*OOKn9Df&d^NcT&esGDi-SP;X-rHpi!82`>e(XDLrGbFj$Jrv8jZ+hQqkLWL+ z<)rEo(CkFf^W7(&Si(>hTqbE8-gieeM$E^np=%QZJj~pV$d8Fth_#K_L9k~8`g z3d>*`ylRY2`*x1;ezjZ29@T&FD+ijS&v$_zi+xKBM12l2u3B~O!0%2)1ompTR_Keu zd1EEX2TiIE2_SH=Xbeq}d3c`sHts2Cx>p=WnX&mofhM5^&%=xd($wxn8AQx{f?S57 z)Zx0=&KPa}OE-$HJ^5dyP9YOmh>*n6LXK>93$%#+tx+c(rF3|`5WcBL%v(zH)%rtU zPYlk2FV?1pRkM%8JesBnOPI`rMY72&z~=(B`?=8QIZ`h32K%110ENc{oZwK0VK7-$ zEZ26-du8Ot`v5Ty#B7VSEfX{1xUX?t2Pptsb7jZQYQ<|W|8854&7n<|?G`zxv^tDk zG3B#dK3{F{?)Kn>e}z|W$^(^k{Jq5WZEkbowV@TOh`CPYM4v@YvXC1yF^=*_3D78 zddXerXy3Tjrp_rOiLCQjg!{}uDHQKMTUQrsfX4B5_XTp19@;GAj`LU#`vojC z1sHy?MBP@o>R9sKPUaDm&aSgZ{`Q5PlQhahh-1hv7OT6PE*n;9++zzKabUctfWaP@ zjBDv)q=3MNR4$-Fqz!{N{t1OM!Zal6??OkcXrxbb+-FYcOdW472e^_9_$~x?6*?W< znGo3htMr>YxRF3li5)wwU8x->=ks?$gkiAZFwO`Q>QI7vz!$z~5RhB)%g&*}$5IVa zY}g4O$l9;AYpSrY8mpk?)WVM4vs;F?{-W4`wqJ_hx!TxQ$-J$wajhkQ%-^-loy+fa ztW97@m%_fM-x&S*_@0RNI*ojzD!H#YSd5x0bZb3!S&o?RU&(M2WWw!q*TwP2g0{4P z-+Ph4J3D4dVXRCKL+HqQqHWONd66yz5D5u%q^zN@4qb}?d>|-5w(`dN#wJd;NUpo1 zToAkMM6^DmD_!e#FK(gyuvu?Oa&`Dkgv>$w#h_+EBjwPesNFC}GB1ksz`rQ0X%Z!Y2<*C{PDQ6*_9a*q6+vx(=YGV-lYy9W0- zNxL7P(QodGA%aKFyFRr$FnWPr_ILVzPTBr)BI&9+oQ70Ec>Hi2-GJnhlk!Z`Y%t4eTyl<3Raz=Mr?i)#(7;xAA x&AIb?RAGPIas&e+_B6)dfMCz#x$Pq;ur#+Zt2gli{|77HI066w diff --git a/Documentation/NuttX2-a.png b/Documentation/NuttX2-a.png deleted file mode 100644 index 20c2fd6e71ed034649f5c21e0facf4b724341879..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1533 zcma)6YgAHM6bAC9U2ACx*(z5{ry4;@(#le&1mmHQ3TP#!T@202CN=YsuUL1irHz%1 zrKXhxQAmWQmJd>5rnE5)%~0%xS^3Jxl#+_WIJbZEbJkh=eCONioV~w&etfy?K*kbq zC5S?ymiYToxd@8Bht)!4|5Y2a0ReO(m*I<2K6e;K$if3G1{F2`eTf=x7a*BM@qWBS z6w2D}d!SJzS63iO%M<vvH- z&8f3sytimVqb;5KteQ}aFY7#x55O+&A9CDJrx@>*oSbYhs5gBeuME(}-48n);~mg- zCZE&$WtlDLhj(1udk zNLxEabT=b(L>D7t#~7 zpBxQzk|L1;b+6H?p%_HO$VgF@5MTFDH1JQBEaQr?8c~u|9b8%|2fapmZVG#BYz{N8 z(lqt{=l8@bGYT<*)6=Kel@)O8ly`DuycJzjWsSfekvhGi>q#zr6;90o!>P&jZ z_!ej{u)$j9!HZ4Ve4JhRvNn=V&>z{#VgNr|%iMW`yPV%^$evm*Datwq7UKCHz`o(01K|?fdh?yS z{RgJHNnN}h05-VNn2yZ*Y~Ho*{)#om;E>7?G=r%B+_slT8PDrr=Pfps6GD~3Mr`=x z?zzIUxpJ2rp*ZG(tH6c#XiM1W+`W!N=1Vv#8A~Nw0*ueoPKL|KaT8GSfaG(jIix|@ zh;tB?y-BB7d~9^Yc)4t2`fLG~c7$rQ>)N*c2!B zrYNok##Y{dc`5E%g(EPk5cLNRTvT7UB|L|1lS9eK0|tOIN`&;7$9O-qideTfx79>j zUVypo=63ee>)U-Fx@vpfj1F4he%N(cy;eOV#$dv(J&rnczOiK|+UDWRWo^`&=I2f` z*}3`@f972oE6z>aQg!WC?wO_U7W~KC{*MWU&00$@WLns=aJ`5(qx@-sRHZK;{ucmg Bw~+t< diff --git a/Documentation/NuttX2-b.png b/Documentation/NuttX2-b.png deleted file mode 100644 index 5bdab5c29de3f300e5178a7245cc4f13d5162766..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1559 zcmah}SyWS36umDY3GzUw%4@)3#jz@hOrpqONQwfYhyi6(V?aQ{U;D3?PsI4;4@np;(H_ps7iSfvSK=lvOph&|n{b{p-5x+`aa`d!2Re`Pe@M2KZQ* z*_r_WEc|@EIXDVu%9M=XXP(3|aDY-cK5S6)c)=T-ka_+--r&p35w?m8aAnp(->?(_ z;JGsefudq6E>cqcwr!%Q%qdnj*8Up?z6XGG+0UC5d{nK!<{vQNHE&bY8NVC8*|V0e z%aS=Giax~(kFI6jY#!ni-$(eO+4<>R`p6b@!Ugq{!!K4{)?>~4sQ0Y;R(m!J01fhD zgM2_+417Vp6<7v*O~D+n%mmB=a|i+)ATNR-8_+I1vTmlOWwfTBm_KDq{M-i#+q|AF zs4jB3HofaEX7_ovooAra1g_)d5$hGBBGd(8_+l|k))=#jy=x3op^!oS8u9v zHq8sV63+;FnUa}iJU;ziJoMyu+s03~h6?82)ai7Yk$--5PogXI)yaGh9~INihWoec z$M}LYw02j>Gm`*q_N~qvwYvu*g|uTWi@8js3VI4e9Rx$J1TWRCZls|8X@H9*&zVS@?%4(98fQdeN_x zt4i1O`*meogMf7KwS_2w=||+TYEMO`;CwoV(^OiGzn?ZLKrZR6 zhv}*!;|+^kl4p^Nxj;pCB@Zc2Z?4pAe~o1(n!&Bv$mn3A$x?*mwOr_G}Nu~ zP={MaHstEY4ee29Tq1WTv6fGrB3i*~bTT7K5f@rs2@u*1Ki0sY6riI{C&`NsYZ^e5mJKJjv0jFcNsR4%G3 zXZ|KfWxy@$V7$gD)S(sPTReXn8>yy_As5N{RZAz4hP8twe9>}BLakA$EK6V=15JB~ z9Voccg^KjzBo+*QY!GV7Gs+`+j$02*-n$cS2*QLGg3!Qz)Gz{x6FBPgCn&}~J*Qr1 zE#Nbb+P*?gx}=4CP>a>>VGbRI`5&@wLAqB`ohmlTQ9JwqUJR=t*Y%-M6OFRL;Hc`F zj&}4w4XLU4Naw~hbH!Pt!Q^0k-HK8VHMOfXdF`P(Ze{bn@Yedo*%OQj_wXLXt59ys z&tqt6lH{qMiArp+mz(U#n5#vVU~|);$k2SFW+k%qm`^GLzC>_SXk4Md0km=aYb|=< z{#=flDq7dk;f{-94zp~AN?pTy-VuPwErtE%G>pQ zMYKE^U>H|YSSuqPb5dmelAHRB)q%bN^!;+tmypSp(n^w}aCEF!RB;h3N|Y<{4bjN$ zC^b-y_U^jp{C8P2%RDYdu6g%b%-JS^=!tT&p}-w!7c78zUOq4;D=oqsNJ&gKRk{Mu zxfM!-<|=}iw4G#7A360hOa<2FqK|8IYFr|oLq6Shl#!siI>|g;^qvox6YzML&>Qk- z2ks-C6U8yXyar*{h6lO0n?20I_HJ{iZA+YLYhi{S;t7{LNYk{Yj)-@bB$ZrM5(RdY zE#GyWi}R@9mTlUaok-tp3D%7N(`~1+ZFD9jQ*-b5bK-@M7xJD~i{|G*3e(R2B;fxC b<@Lf$m$KNk=i~Of;HeG#HU)Usu({~Jp-Qw0 diff --git a/Documentation/NuttX2.png b/Documentation/NuttX2.png deleted file mode 100644 index 422d1191fd21bbeafc908d5742a919a39e3d0211..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3441 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 CTEL?K diff --git a/Documentation/NuttX320.png b/Documentation/NuttX320.png deleted file mode 100644 index f736c41308bcc1a2c60ca2137f752f6b7f9e679a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4151 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 D7F - -NuttX Binary Loader - - -
    - - - - -
    -

    NuttX Binary Loader

    -

    Last Updated: August 22, 2014

    -
    -
    - - - - - -
    -

    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: -

    -
      -
    • - ELF. - Standard ELF formatted files. -
      • -
    • - NXFLAT. - NuttX NXFLAT formatted files. - More information about the NXFLAT binary format can be found in the - NXFLAT documentation. -
    - -

    - 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: -

    -
      -struct binfmt_s
-{
-  FAR struct binfmt_s *next;             /* Supports a singly-linked list */
-  int (*load)(FAR struct binary_s *bin); /* Verify and load binary into memory */
-};
-
    - -

    - 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: -

    -
      -struct symtab_s;
-struct binary_s
-{
-  /* Information provided to the loader to load and bind a module */
-
-  FAR const char *filename;            /* Full path to the binary to be loaded */
-  FAR const char **argv;               /* Argument list */
-  FAR const struct symtab_s *exports;  /* Table of exported symbols */
-  int nexports;                        /* The number of symbols in exports[] */
-
-  /* Information provided from the loader (if successful) describing the
-   * resources used by the loaded module.
-   */
-
-  main_t entrypt;                      /* Entry point into a program module */
-  FAR void *mapped;                    /* Memory-mapped, address space */
-  FAR void *alloc[BINFMT_NALLOC];      /* Allocated address spaces */
-
-  /* Constructors/destructors */
-
-#ifdef CONFIG_BINFMT_CONSTRUCTORS
-  FAR binfmt_ctor_t *ctors;            /* Pointer to a list of constructors */
-  FAR binfmt_dtor_t *dtors;            /* Pointer to a list of destructors */
-  uint16_t nctors;                     /* Number of constructors in the list */
-  uint16_t ndtors;                     /* Number of destructors in the list */
-#endif
-
-  /* Address environment.
-   *
-   * addrenv - This is the handle created by up_addrenv_create() that can be
-   *   used to manage the tasks address space.
-   */
-
-#ifdef CONFIG_ARCH_ADDRENV
-  group_addrenv_t addrenv;             /* Task group address environment */
-#endif
-
-  size_t mapsize;                      /* Size of the mapped address region (needed for munmap) */
-
-  /* Start-up information that is provided by the loader, but may be modified
-   * by the caller between load_module() and exec_module() calls.
-   */
-
-  uint8_t priority;                    /* Task execution priority */
-  size_t stacksize;                    /* Size of the stack in bytes (unallocated) */
-};
-
    - -
      -

      - 1The filename must be the full, absolute path to the file to be executed unless CONFIG_BINFMT_EXEPATH is defined. - In that case, filename may be a relative path; - a set of candidate absolute paths will be generated using the PATH environment variable and load_module() will attempt to load each file that is found at those absolute paths. -

      -
    - -

    - Where the types binfmt_ctor_t and binfmt_dtor_t define the type of one C++ constructor or destructor: -

    - -
      -typedef FAR void (*binfmt_ctor_t)(void);
-typedef FAR void (*binfmt_dtor_t)(void);
-
    - -

    2.3 Binary Loader Function Interfaces

    - -

    - Binary format management: -

    - -

    - Basic module management: -

    - -

    - PATH traversal logic: -

    - - -

    2.3.1 register_binfmt()

    - -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/binfmt.h>
-int register_binfmt(FAR struct binfmt_s *binfmt);
-
    -

    Description:

    -
      -Register a loader for a binary format. -
    -

    Returned Value:

    -
      -This is a NuttX internal function so it follows the convention that 0 (OK) is returned on success and a negated errno is returned on failure. -
    - -

    2.3.2 unregister_binfmt()

    -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/binfmt.h>
-int unregister_binfmt(FAR struct binfmt_s *binfmt);
-
    -

    Description:

    -
      -Register a loader for a binary format. -
    -

    Returned Value:

    -
      -This is a NuttX internal function so it follows the convention that 0 (OK) is returned on success and a negated errno is returned on failure. -
    - -

    2.3.3 load_module()

    -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/binfmt.h>
-int load_module(FAR struct binary_s *bin);
-
    -

    Description:

    -
      -

      - Load a module into memory, bind it to an exported symbol take, and prep the module for execution. -

      -

      - load_module() will use the filename field in the struct binary_s in order to locate the module to be loaded from the file system. - The filename must be the full, absolute path to the file to be executed unless CONFIG_BINFMT_EXEPATH is defined. - In that case, filename may be a relative path; - a set of candidate absolute paths will be generated using the PATH environment variable and load_module() will attempt to load each file that is found at those absolute paths. -

      -
    -

    Returned Value:

    -
      -This is an end-user function, so it follows the normal convention: -Returns 0 (OK) on success. -On failure, it returns -1 (ERROR) with errno set appropriately. -
    - -

    2.3.4 unload_module()

    -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/binfmt.h>
-int unload_module(FAR struct binary_s *bin);
-
    -

    Description:

    -
      -

      - Unload a (non-executing) module from memory. - If the module has been started (via exec_module()) and has not exited, calling this will be fatal. -

      -

      - However, this function must be called after the module exist. - How this is done is up to your logic. - Perhaps you register it to be called by on_exit()? -

    -

    Returned Value:

    -
      -This is a NuttX internal function so it follows the convention that 0 (OK) is returned on success and a negated errno is returned on failure. -
    - -

    2.3.5 exec_module()

    -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/binfmt.h>
-int exec_module(FAR const struct binary_s *bin);
-
    -

    Description:

    -
      -Execute a module that has been loaded into memory by load_module(). -
    -

    Returned Value:

    -
      -This is an end-user function, so it follows the normal convention: -Returns 0 (OK) on success. -On failure, it returns -1 (ERROR) with errno set appropriately. -
    - -

    2.3.7 exec()

    -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/binfmt.h>
-int exec(FAR const char *filename, FAR const char **argv,
-         FAR const struct symtab_s *exports, int nexports);
-
    -

    Description:

    -
      - This is a convenience function that wraps load_ and exec_module() into one call. -
    -

    Input Parameters:

    -
      -
    • filename: Full path to the binary to be loaded.
      • -
    • argv: Argument list.
      • -
    • exports: Table of exported symbols.
      • -
    • exports: The number of symbols in exports.
      • -
    -

    Returned Value:

    -
      - This is an end-user function, so it follows the normal convention: - Returns 0 (OK) on success. - On failure, it returns -1 (ERROR) with errno set appropriately. -
    - -

    2.3.8 exepath_init()

    -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/binfmt.h>
-#ifdef CONFIG_BINFMT_EXEPATH
-EXEPATH_HANDLE exepath_init(void);
-#endif
-
    -

    Description:

    -
      -

      - Initialize for the traversal of each value in the PATH variable. - The usage is sequence is as follows: -

      -
        -
      1. - Call exepath_init() to initialize for the traversal. - exepath_init() will return an opaque handle that can then be provided to exepath_next() and exepath_release(). -
        2. -
      2. - Call exepath_next() repeatedly to examine every file that lies in the directories of the PATH variable. -
        3. -
      3. - Call exepath_release() to free resources set aside by exepath_init(). -
        4. -
      -
    -

    Input Parameters: None

    -

    Returned Value:

    -
      - On success, exepath_init() return a non-NULL, opaque handle that may subsequently be used in calls to exepath_next() and exepath_release(). - On error, a NULL handle value will be returned. - The most likely cause of an error would be that the there is no value associated with the PATH variable. -
    - -

    2.3.9 exepath_next()

    -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/binfmt.h>
-#ifdef CONFIG_BINFMT_EXEPATH
-FAR char *exepath_next(EXEPATH_HANDLE handle, FAR const char *relpath);
-#endif
-
    -

    Description:

    -
      - Traverse all possible values in the PATH variable in attempt to find the full path to an executable file when only a relative path is provided. -
    -

    Input Parameters:

    -
      -
    • handle: The handle value returned by exepath_init().
      • -
    • relpath: The relative path to the file to be found.
      • -
    -

    Returned Value:

    -
      -

      - On success, a non-NULL pointer to a null-terminated string is provided. - This is the full path to a file that exists in the file system. - This function will verify that the file exists (but will not verify that it is marked executable). -

      -

      - NOTE: The string pointer return in the success case points to allocated memory. - This memory must be freed by the called by calling kmm_free(). -

      -

      - NULLrelpath from any absolute path in the PATH variable. - In this case, there is no point in calling exepath_next() further; exepath_release() must be called to release resources set aside by expath_init(). -

      -
    - -

    2.3.10- exepath_release()

    -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/binfmt.h>
-#ifdef CONFIG_BINFMT_EXEPATH
-void exepath_release(EXEPATH_HANDLE handle);
-#endif
-
    -

    Description:

    -
      - Release all resources set aside by exepath_init when the handle value was created. - The handle value is invalid on return from this function. - Attempts to all exepath_next() or exepath_release() with such a stale handle will result in undefined (i.e., not good) behavior. -
    -

    Input Parameters:

    -
      -
    • handle: The handle value returned by exepath_init().
      • -
    -

    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. -

    - -
      -struct symtab_s
-{
-  FAR const char *sym_name;          /* A pointer to the symbol name string */
-  FAR const void *sym_value;         /* The value associated witht the string */
-};
-
    - -

    - 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 dyanamically 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:

    -
      -#include <:nuttx/binfmt/symtab.h>
-FAR const struct symtab_s *
-symtab_findbyname(FAR const struct symtab_s *symtab,
-                  FAR const char *name, int nsyms);
-
    -

    Description:

    -
      - Find the symbol in the symbol table with the matching name. - This version assumes that table is not ordered with respect to symbol name and, hence, access time will be linear with respect to nsyms. -
    -

    Returned Value:

    -
      - A reference to the symbol table entry if an entry with the matching name is found; -NULL is returned if the entry is not found. -
    - -

    3.3.2 symtab_findorderedbyname()

    -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/symtab.h>
-FAR const struct symtab_s *
-symtab_findorderedbyname(FAR const struct symtab_s *symtab,
-                         FAR const char *name, int nsyms);
-
    -

    Description:

    -
      - Find the symbol in the symbol table with the matching name. - This version assumes that table ordered with respect to symbol name. -
    -

    Returned Value:

    -
      - A reference to the symbol table entry if an entry with the matching name is found; - NULL is returned if the entry is not found. -
    - -

    3.3.3 symtab_findbyvalue()

    -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/symtab.h>
-FAR const struct symtab_s *
-symtab_findbyvalue(FAR const struct symtab_s *symtab,
-                   FAR void *value, int nsyms);
-
    -

    Description:

    -
      - Find the symbol in the symbol table whose value closest (but not greater than), the provided value. - This version assumes that table is not ordered with respect to symbol name and, hence, access time will be linear with respect to nsyms. -
    -

    Returned Value:

    -
      - A reference to the symbol table entry if an entry with the matching name is found; - NULL is returned if the entry is not found. -
    - -

    3.3.4 symtab_findorderedbyvalue()

    -

    Function Prototype:

    -
      -#include <:nuttx/binfmt/symtab.h>
-FAR const struct symtab_s *
-symtab_findorderedbyvalue(FAR const struct symtab_s *symtab,
-                          FAR void *value, int nsyms);
-
    -

    Description:

    -
      - Find the symbol in the symbol table whose value closest (but not greater than), the provided value. - This version assumes that table is ordered with respect to symbol name. -
    -

    Returned Value:

    -
      - A reference to the symbol table entry if an entry with the matching name is found; - NULL is returned if the entry is not found. -
    - - - - - -
    -

    4.0 Configuration Variables

    -
    - -
      -

      - CONFIG_BINFMT_DISABLE: - By default, support for loadable binary formats is built. - This logic may be suppressed be defining this setting. -

      -

      - CONFIG_BINFMT_CONSTRUCTORS: - Build in support for C++ constructors in loaded modules. -

      -

      - CONFIG_SYMTAB_ORDEREDBYNAME: - Symbol tables are order by name (rather than value). -

      -
    - -

    - Additional configuration options may be required for the each enabled binary format. -

    - - diff --git a/Documentation/NuttXCCodingStandard.html b/Documentation/NuttXCCodingStandard.html deleted file mode 100644 index 7b17b054b9..0000000000 --- a/Documentation/NuttXCCodingStandard.html +++ /dev/null @@ -1,2573 +0,0 @@ - - -NuttX C Coding Standard - - - - -
    - - - - -
    -

    - NuttX C Coding Standard -

    -

    Last Updated: March 9, 2014

    -
    -
    - - - - - -
    -

    Table of Contents

    -
    - - - - - - - -
    -

    1.0 General Organization

    -
    - -

    1.1 File Organization

    - -

    - File Extensions - Use the .h extension for C header files and .c for C source files. -

    -

    - File header. - Every C, C++, make file, or script begins with a file header. - That file header is enclosed with a block comment (see below). - Within the block comment, the following must appear: -

    -
      -
    • - The relative path to the file from the top-level directory. -
      • -
    • - An optional, one-line description of the file contents. -
      • -
    • - A blank line -
      • -
    • - A copyright notice indented two additional spaces -
      • -
    • - A line identifying the author and contact information with the same indentation as the copyright notice. -
      • -
    • - A blank line
      • -
    • - Standard (modified) BSD licensing information. -
      • -
    -

    - Sample File Headers. - Sample file headers are provided in an Appendix to this document. - No software may be included in the NuttX source tree that does not have licensing information included in the file. - No software may be included in the NuttX source tree that does not have a (modified) BSD license or compatible license (such as the MIT license). - If the file does not following BSD licensing, then the appropriate license information should be provided in the header rather than the (modified) BSD licensing information and a NOTE should be included in the top-level COPYING file to indicate any variations from (modified) BSD licensing. -

    -

    - Grouping. - All like components in a C source or header file are grouped together. - Definitions do not appear arbitrarily through the file, rather, like definitions are grouped together and preceded by a block comment identifying the grouping. -

    -

    - Block Comments. - Each grouping in the file is separated with a block comment. - The block comment consists of: -

    -
      -
    • - A line that consists of the opening C comment (/*) followed by a series of asterisks extending to the length of the line (usually to column 78). -
      • -
    • - The name of the grouping, starting at column 4. - An asterisk preceives the name of the grouping in column 1. -
      • -
    • - A line that consists of the closing C comment (*/) at the end of the line (usually column 78) preceded by a series of asterisks extending to column 1. -
      • -
    -

    - Examples of Block Comments. - See Appendix A for examples of block comments. -

    -

    - Order of Groupings. - The following groupings should appear in all C source files in the following order: -

    -
      -
    1. - Included Files -
      2. -
    2. - Pre-processor Definitions -
      3. -
    3. - Private Types -
      4. -
    4. - Private Function Prototypes -
      5. -
    5. - Private Data (definitions) -
      6. -
    6. - Public Data (definitions) -
      7. -
    7. - Private Functions (definitions) -
      8. -
    8. - Public Functions (definitions) -
      9. -
    -

    - The following groupings should appear in all C header files in the following order: -

    -
      -
    1. - Included Files -
      2. -
    2. - Pre-processor Definitions -
      3. -
    3. - Public Types -
      4. -
    4. - Public Data (declarations) -
      5. -
    5. - Inline Functions (definitions) -
      6. -
    6. - Public Function Prototypes (declarations) -
      7. -
    -

    - Large vs. Small Files. - In larger files, block comments should be included for all groupings, even if they are empty; - the empty grouping provides important information in itself. - Smaller files may omit some of the block comments; - it is awkard if the block comments are larger than the file content! -

    -

    - Header File Idempotence. - C header file must protect against multipleinclusion through the use of macros that "guard" against multiple definitions if the header file is included multiple times. -

    -
      -
    • -

      - Each header file must contain the following pre-processor commands near the beginning of the header file: Between the file header and the "Included Files" block comment. - For example, -

      - 
        -#ifndef __INCLUDE_NUTTX_ARCH_H
-#define __INCLUDE_NUTTX_ARCH_H
-
      -

      - Notice that the definitions within of the header do not follow the usually rules: - The presence of the conditional test at the top of the file does not cause the - remaining definitions within the file to be indented. -

      -
      • -
    • -

      - Then conditional compilation is closed at the fine line of the header file with: -

      - 
        -#endif /* __INCLUDE_NUTTX_ARCH_H */
-
      -
      • -
    -

    - Forming Guard Names. - Then pre-processor macro name used in the guard is formed from the full, relative path to the header for from the top-level, controlled directory. - That pat is preceded by __ and _ replaces each character that would otherwise be invalid in a macro name. - So, for example, __INCLUDE_NUTTX_ARCH_H corresponds to the header file include/nuttx/arch.h -

    - -

    - Deoxygen Information. - NuttX does not use Deoxygen for documentation and no file should contain Doxygen tags. -

    - -

    - Sample File Formats. - C source and header file templates are provided in an Appendix to this document. -

    - -

    1.2 Lines

    -

    - Line Endings. - Files should be formatted with \n as the line ending (Unix line endings), not \r\n (Windows line endings). - There should be no extra whitespace at the end of the line. - In addition, all text files should end in a single newline (\n). This avoids the "No newline at end of file" warning generated by certain tools. -

    - -

    - Line Width. - Text should not extend past column 78 in the typical C source or header file. - Sometimes the nature of the content of a file may require that the lines exceed this limit. - This often occurs in header files with naturally long definitions. - If the line width must extend 78 lines, then some wider line width may be used in the file provided that it is used consistently. -

    - -

    - Line Wrapping. -

    -
    - - -
    -

    Incorrect

    -
      -  struct some_long_struct_name_s
-  {
-    struct some_long_struct_name_s *flink;  /* The forward link to the next instance of struct some_long_struct_name_s in a singly linked list */
-    int short_name1;   /* Short comment 1 */
-    int short_name2;   /* This is a very long comment describing subtle aspects of the short_name2 field */
-  };
-
-  struct some_medium_name_s *ptr = (struct some_medium_name_s *)malloc(sizeof(some_medium_name_s);
-
-  struct some_long_struct_name_s *ptr = (struct some_long_struct_name_s *)malloc(sizeof(some_long_struct_name_s);
-
-  ret = some_function_with_many parameters(long_parameter_name_1, long_parameter_name_2, long_parameter_name_3, long_parameter_name_4, long_parameter_name_5, long_parameter_name_6, long_parameter_name_7, long_parameter_name_8);
-
-  ret = some_function_with_many parameters(long_parameter_name_1,
-    long_parameter_name_2,
-    long_parameter_name_3
-    long_parameter_name_4,
-    long_parameter_name_5,
-    long_parameter_name_6,
-    long_parameter_name_7,
-    long_parameter_name_8);
-
     -
    -

    Correct

    -
      -  struct some_long_struct_name_s
-  {
-    /*  The forward link to the next instance of struct
-     * some_long_struct_name_s in a singly linked list
-     */
-
-    struct some_long_struct_name_s *flink;
-    int short_name1;   /* Short comment 1 */
-    int short_name2;   /* This is a very long comment describing subtle
-                        * aspects of the short_name2 field */
-  };
-
-  FAR struct some_medium_name_s *ptr = (FAR struct some_medium_name_s *)
-    malloc(sizeof(some_medium_name_s);
-
-  FAR struct some_medium_name_s *ptr =
-    (FAR struct some_medium_name_s *)malloc(sizeof(some_medium_name_s);
-
-  FAR struct some_long_struct_name_s *ptr =
-    (FAR struct some_long_struct_name_s *)
-      malloc(sizeof(some_long_struct_name_s);
-
-  ret = some_function_with_many parameters(long_parameter_name_1,
-                                           long_parameter_name_2,
-                                           long_parameter_name_3,
-                                           long_parameter_name_4,
-                                           long_parameter_name_5,
-                                           long_parameter_name_6,
-                                           long_parameter_name_7,
-                                           long_parameter_name_8);
-
     -
    - -

    - NOTE: - See the discussion of pointers for information about the FAR qualifier used above. -

    - -

    - Double Spacing. - A single blank line may be use to separate logical groupings as the designer feels fit. - Single blank lines are also required in certain contexts as defined in this standard. - Additional blanks lines (two or more) are prohibited. -

    - -

    - Columnar Organization. - Similar things should be aligned on the same column unless doing so would cause the line width to be exceeded. -

    -
    - - -
    -

    Acceptable

    -
      -  dog = cat;
-  monkey = oxen;
-  aardvark = macaque;
-
     -
    -

    Preferred

    -
      -  dog      = cat;
-  monkey   = oxen;
-  aardvark = macaque;
-
     -
    - -

    - Block Comments - The final asterisk (*) should occur at column 78 (or the line width of files with longer lines). - Note that the final comment delimiter of the block comment is an exception an lies at column 79. -

    - -

    1.3 Comments

    - -

    - Line Spacing - A single blank line should precede and follow each comment. - The only exception is for the file header block comment that begins on line one; - there is no preceding blank line in that case. -

    -
    - - -
    -

    Incorrect

    -
      -  /* Set a equal to b */
-  a = b;
-  /* Set b equal to c */
-  b = c;
-
     -
    -

    Correct

    -
      -
-  /* Set a equal to b */
-
-  a = b;
-
-  /* Set b equal to c */
-
-  b = c;
-
-
     -
    - -

    - Indentation - Comments should, typically, be placed before the code section to which they apply. - The comment identation should be the same as the follow identation rules as the following code (if applicable). -

    - -

    - Short, Single line comments. - Short comments must lie on a single line. - The comment delimiters must lie on the same line. -

    -
    - - -
    -

    Incorrect

    -
      -  /*
-   * This is a single line comment
-   */
-
     -
    -

    Correct

    -
      -  /* This is a single line comment */
-
     -
    - -

    - Multi-line comments. - If the comment is too long to fit on a single, it must be broken into a multi-line comment. - The comment must be begin on the first line of the multi-line comment with the opening comment delimiter (/*). - The following lines of the multi-line comment must be with an asterisk (*) aligned in the same column as the asterisk in the preceding line. - The closing comment delimiter must lie on a separate line with the asterisk (*) aligned in the same column as the asterisk in the preceding line. -

    -
    - - -
    -

    Incorrect

    -
      -  /*
-     This is the first line of a multi-line comment.
-     This is the second line of a multi-line comment.
-     This is the third line of a multi-line comment. */
-
-  /* This is the first line of another multi-line comment.  */
-  /* This is the second line of another multi-line comment. */
-  /* This is the third line of another multi-line comment.  */
-
-
     -
    -

    Correct

    -
      -  /* This is the first line of a multi-line comment.
-   * This is the second line of a multi-line comment.
-   * This is the third line of a multi-line comment.
-   */
-
-
     -
    - -

    - Comments to the Right of Statements. - Comments to the right of statements in C source files are discouraged - If such comments are used, they should at least be aligned so that the comment begins in the same comment on each line. -

    -
    - - - -
    -

    Incorrect

    -
      -  dog = cat; /* Make the dog be a cat */
-  monkey = oxen; /* Make the monkey be an oxen */
-  aardvark = macaque; /* Make the aardvark be a macaque */
-
     -
    -

    Acceptable

    -
      -  dog      = cat;     /* Make the dog be a cat */
-  monkey   = oxen;    /* Make the monkey be an oxen */
-  aardvark = macaque; /* Make the aardvark be a macaque */
-
     -
    -

    Preferred

    -
      -  /* Make the dog be a cat */
-
-  dog      = cat;
-
-  /* Make the monkey be an oxen */
-
-  monkey   = oxen;
-
-  /* Make the aardvark be a macaque */
-
-  aardvark = macaque;
-
     -
    - -

    - Comments to the Right of Data Definitions. - Comments to the right of a declaration with an enumeration or structure, on the other hand, are encourage. - Columnar alignment of comments is very desireable (but often cannot be achieved without violating the line width). -

    -
    - - - -
    -

    Incorrect

    -
      -struct animals_s
-{
-  int dog; /* This is a dog */
-  int cat; /* This is a cat */
-  double monkey; /* This is a monkey */
-  double oxen; /* This is an oxen */
-  bool aardvark; /* This is an aardvark */
-  bool macaque; /* This is a macaque */
-};
-
     -
    -

    Acceptable

    -
      -struct animals_s
-{
-  int dog;       /* This is a dog */
-  int cat;       /* This is a cat */
-  double monkey; /* This is a monkey */
-  double oxen;   /* This is an oxen */
-  bool aardvark; /* This is an aardvark */
-  bool macaque;  /* This is a macaque */
-};
-
     -
    -

    Preferred

    -
      -struct animals_s
-{
-  int    dog;      /* This is a dog */
-  int    cat;      /* This is a cat */
-  double monkey;   /* This is a monkey */
-  double oxen;     /* This is an oxen */
-  bool   aardvark; /* This is an aardvark */
-  bool   macaque;  /* This is a macaque */
-};
-
     -
    - -

    - Block comments. - Block comments are only used to delimit groupings with the overall file organization and should not be used unless the usage is consistent with delimiting logical groupings in the program. -

    - -

    - C Style Comments. - C99/C11/C++ style comments (beginning wih //) should not be used with NuttX. - NuttX generally follows C89 and all code outside of architecture specific directories must be compatible with C89. -

    -
    - - -
    -

    Incorrect

    -
      -// This is a structure of animals
-struct animals_s
-{
-  int    dog;      // This is a dog
-  int    cat;      // This is a cat
-  double monkey;   // This is a monkey
-  double oxen;     // This is an oxen
-  bool   aardvark; // This is an aardvark
-  bool   macaque;  // This is a macaque
-};
-
     -
    -

    Correct

    -
      -/* This is a structure of animals */
-
-struct animals_s
-{
-  int    dog;      /* This is a dog */
-  int    cat;      /* This is a cat */
-  double monkey;   /* This is a monkey */
-  double oxen;     /* This is an oxen */
-  bool   aardvark; /* This is an aardvark */
-  bool   macaque;  /* This is a macaque */
-};
-
     -
    - -

    - "Commenting Out" Large Code Blocks. - Do not use C or C++ comments to disable compilation of large blocks of code. - Instead, use #if 0 to do that. - Make sure there is a comment before the #if 0 to explain why the code is not compiled. -

    -
    - - -
    -

    Incorrect

    -
      -void some_function(void)
-{
-  ... compiled code ...
-
-  /*
-  ... disabled code ..
-   */
-
-  ... compiled code ...
-}
-
-void some_function(void)
-{
-  ... compiled code ...
-
-  //
-  // ... disabled code ..
-  //
-
-  ... compiled code ...
-}
-
     -
    -

    Correct

    -
      -void some_function(void)
-{
-  ... compiled code ...
-
-  /* The following code is disabled because it is no longer needed */
-
-#if 0
-  ... disabled code ..
-#endif
-
-  ... compiled code ...
-}
-
     -
    - -

    1.4 Braces

    - -

    Coding Standard:

    -
      -
    • - Always on Separate Lines. - Braces always appear on a separate line containing nothing else other that white space. -
      • -
    • - Never Comments on Braces. - Do not put comments on the same line as braces. -
      • -
    • - Special Indentation Rules. - Special indentation rules apply to braces. -
      • -
    - -
    - - -
    -

    Incorrect

    -
      -while (true)
-  {
-    if (valid)
-      {
-      ...
-      } /* if valid */
-    else
-      {
-      ...
-      } /* not valid */
-  } /* end forever */
-
     -
    -

    Correct

    -
      -while (true)
-  {
-    if (valid)
-      {
-      ...
-      }
-    else
-      {
-      ...
-      }
-  }
-
     -
    - -

    - Exceptions. - The exception is braces that following structure, enumeration, union, and function declarations. - There is no additional indentation for those braces; - those braces align with the beginning of the definition -

    -
    - - -
    -

    Incorrect

    -
      -enum kinds_of_dogs_e
-  {
-  ...
-  };
-
-struct dogs_s {
-  ...
-  union {
-  ...
-  } u;
-  ...
-};
-
-struct cats_s
-  {
-  ...
-    union
-     {
-     ...
-     } u;
-  ...
-  };
-
-int animals(int animal)
-  {
-  ...
-  }
-
     -
    -

    Correct

    -
      -enum kinds_of_dogs_e
-{
-  ...
-};
-
-struct dogs_s
-{
-  ...
-  union
-  {
-  ...
-  } u;
-  ...
-};
-
-struct cats_s
-{
-  ...
-  union
-  {
-  ...
-  } u;
-  ...
-};
-
-int animals(int animal)
-{
-  ...
-}
-
     -
    - -

    1.5 Indentation

    - -

    - Indentation Unit - Indentation is in units of two spaces; Each indentation level is twos spaces further to the right than the preceding identation levels. - The use of TAB characters for indentation is prohibited in C source and header files (they may be appropriate in make files and some scripts, however). -

    -
    - - -
    -

    Incorrect

    -
      -	if (x == y) {
-		dosomething(x);
-	}
-
-    if (x == y) {
-        dosomething(x);
-    }
-
     -
    -

    Correct

    -
      -  if (x == y)
-    {
-      dosomething(x);
-    }
-
     -
    - -

    - Alignment of Braces. - Note that since braces must be on a separate line (see above), this indentation by two spaces has an interesting property: - All C statements (and case selectors) like on lines that are odd multiples of 2 spaces: 2, 6, 10, ... (2*n + 1). - A braces lie on a separate line indented by an even multple of 2 spaces: 4, 8, 12, ... 2*n. -

    - -

    - Indentation of Pre-Processor Lines. - C Pre-processor commands following any conditional computation are also indented following basically the indentation same rules, differing in that the # always remains in column 1. -

    - -
    - - -
    -

    Incorrect

    -
      -#ifdef CONFIG_ABC
-#define ABC_THING1 1
-#define ABC_THING2 2
-#define ABC_THING3 3
-#endif
-
-#ifdef CONFIG_ABC
-  #define ABC_THING1 1
-  #define ABC_THING2 2
-  #define ABC_THING3 3
-#endif
-
     -
    -

    Correct

    -
      -#ifdef CONFIG_ABC
-#  define ABC_THING1 1
-#  define ABC_THING2 2
-#  define ABC_THING3 3
-#endif
-
-#ifdef CONFIG_ABC
-#  define ABC_THING1 1
-#  define ABC_THING2 2
-#  define ABC_THING3 3
-#endif
-
     -
    - -

    - Exception. - Each header file includes idempotence definitions at the beginning of the header file. - This conditional compilation does not cause any change to the indentation. -

    -
    - - -
    -

    Incorrect

    -
      -#ifndef __INCLUDE_SOMEHEADER_H
-#  define __INCLUDE_SOMEHEADER_H
-...
-#  define THING1 1
-#  define THING2 2
-#  define THING3 3
-...
-#endif /* __INCLUDE_SOMEHEADER_H */
-
     -
    -

    Correct

    -
      -#ifndef __INCLUDE_SOMEHEADER_H
-#define __INCLUDE_SOMEHEADER_H
-...
-#define THING1 1
-#define THING2 2
-#define THING3 3
-...
-#endif /* __INCLUDE_SOMEHEADER_H */
-
     -
    - -

    1.6 Parentheses

    - -

    Coding Standard:

    -
      -
    • - Space after key words. - Do not put a left parenthesis (() immediately after any C keywords (for, switch, while, do, return, etc.). - Put a space before the left parenthesis in these cases. -
      • -
    • - Otherwise, no space before left parentheses. - Otherwise, there should be no space before the left parentheses -
      • -
    • - No space betwen function name and argument list. - There should be no space between a function name and an argument list. -
      • -
    • - Never space before the right parentheses. - There should never be space before a right parenthesis ()). -
      • -
    • - No parentheses around returned values. - Returned values should never be enclosed in parentheses unless the parentheses are required to force the correct order of operations in a computed return value. -
      • -
    -
    - - -
    -

    Incorrect

    -
      -int do_foobar ( void )
-{
-  int ret = 0;
-  int i;
-
-  for( i = 0; ( ( i < 5 ) || ( ret < 10 ) ); i++ )
-    {
-      ret = foobar ( i );
-    }
-
-  return ( ret );
-}
-
     -
    -

    Correct

    -
      -int do_foobar(void)
-{
-  int ret = 0;
-  int i;
-
-  for (i = 0; i < 5 || ret < 10; i++)
-    {
-      ret = foobar(i);
-    }
-
-  return ret;
-}
-
     -
    - -

    - NOTE: - Many people do not trust their understanding of the precedence of operators and so use lots of parentheses in expressions to force the order of evaluation even though the parentheses may have no effect. - This will certainly avoid errors due to an unexpected order of evaluation, but can also make the code ugly and overly complex (as in the above example). - In general, NuttX does not use unnecessary parentheses to force order of operations. - There is no particular policy in this regard. - However, you are are advised to check your C Programming Language book if necessary and avoid unnecessary parenthesis when possible. -

    - - - - - -
    -

    2.0 Data and Type Definitions

    -
    - -

    2.1 One Definition/Declaration Per Line

    - -
    - - -
    -

    Incorrect

    -
      -  extern long time, money;
-  char **ach, *bch;
-  int i, j, k;
-
     -
    -

    Correct

    -
      -  extern long time;
-  extern long money;
-  FAR char **ach;
-  FAR char *bch;
-  int i;
-  int j;
-  int k;
-
     -
    - -

    - NOTE: - See the discussion of pointers for information about the FAR qualifier used above. -

    - -

    2.2 Global Variables

    - -

    Coding Standard:

    -
      -
    • - Short global variable names. - Names should be terse, but generally descriptive of what the variable is for. - Try to say something with the variable name, but don't try to say too much. - For example, the variable name of g_filelen is preferable to something like g_lengthoffile. -
      • -
    • - Global variable prefix. - All global variables begin with the prefix g_ to indicate the scope of variable. -
      • -
    • - Module name prefix - If a global variable belongs in a module with a name of, say xyz, then that module should be included as part of the prefix like: g_xyz_. -
      • -
    • - Lowercase, - Use all lower case letters. -
      • -
    • - Minimal use of '_'. - Preferably there are no '_' separators within the name. - Long variable names might require some delimitation using '_'. - Long variable names, however, are discouraged. -
      • -
    • - Use structures. - If possible, wrap all global variables within a structure to minimize the liklihood of name collisions. -
      • -
    • - Avoid global variables when possible. - Use of global variables, in general, is discourage unless there is no other reasonable solution. -
      • -
    -
    - - - -
    -

    Incorrect

    -
      -extern int someint;
-uint32_t dwA32BitInt;
-uint32_t gAGlobalVariable;
-
     -
    -

    Acceptable

    -
      -extern int g_someint;
-uint32_t g_a32bitint;
-uint32_t g_aglobal;
-
     -
    -

    Preferred

    -
      -struct my_variables_s
-{
-  uint32_t a32bitint;
-  uint32_t aglobal;
-};
-
-extern int g_someint;
-struct my_variables_s g_myvariables;
-
     -
    - -

    2.3 Parameters and Local Variables

    - -

    Coding Standard:

    -
      -
    • - Common naming standard. - Naming for function parameters and local variables is the same. -
      • -
    • - Short variable names. - Names should be terse, but generally descriptive of what the variable is for. - Try to say something with the variable name, but don't try to say too much. - For example, the variable name of len is preferable to something like lengthofiobuffer. -
      • -
    • - No special ornamentation. - There is no special ornamentation of the name to indication that the variable is a local variable. - The prefix p or pp may be used on names of pointers (or pointer to pointers) if it helps to distinguish the variable from some other local variable with a similar name. - Even this convention is discouraged when not necessary. -
      • -
    • - Lowercase - Use all lower case letters. -
      • -
    • - Minimal use of single character variable names. - Short variable names are preferred. - However, single character variable names should be avoided. - Exceptions to this include i, j, and k which are reserved only for use as loop indices - (part of our Fortran legacy). -
      • -
    • - Minimal use of '_'. - Preferably there are no '_' separators within the name. - Long variable names might require some delimitation using '_'. - Long variable names, however, are discouraged. -
      • -
    -
    - - -
    -

    Incorrect

    -
      -uint32_t somefunction(int a, uint32_t dwBValue)
-{
-  uint32_t this_is_a_long_variable_name = 1;
-  int i;
-
-  for (i = 0; i < a; i++)
-    {
-      this_is_a_long_variable_name *= dwBValue--;
-    }
-
-  return this_is_a_long_variable_name;
-}
-
     -
    -

    Correct

    -
      -uint32_t somefunction(int limit, uint32_t value)
-{
-  uint32_t ret = 1;
-  int i;
-
-  for (i = 0; i < limit; i++)
-    {
-      ret *= value--;
-    }
-
-  return ret;
-}
-
     -
    - -

    - NOTE: - You will see the local variable named ret is frequently used in the code base for the name of a local variable whose value will be returned or to received the returned value from a called function. -

    - -

    2.4 Type Definitions

    - -

    Coding Standard:

    -
      -
    • - Short type names. - Type names should be terse, but generally descriptive of what the type is for. - Try to say something with the type name, but don't try to say too much. - For example, the type name of fhandle_t is preferable to something like openfilehandle_t. -
      • -
    • - Type name suffix. - All typedef'ed names end with the suffix _t. -
      • -
    • - Module name prefix - If a type belongs in a module with a name of, say xyz, then that module should be included as a prefix to the type name like: xyz_. -
      • -
    • - Lowercase. - Use all lower case letters. -
      • -
    • - Minimal use of '_'. - Preferably there are few '_' separators within the type name. - Long type names might require some delimitation using '_'. - Long type names, however, are discouraged. -
      • -
    -
    - - -
    -

    Incorrect

    -
      -typedef void *myhandle;
-typedef int myInteger;
-
     -
    -

    Correct

    -
      -typedef FAR void *myhandle_t;
-typedef int myinteger_t;
-
     -
    - -

    - NOTE: - See the discussion of pointers for information about the FAR qualifier used above. -

    - -

    2.5 Structures

    - -

    Structure Naming

    -
      -
    • - No un-named structures. - All structures must be named, even if they are part of a type definition. - The exception to this rule is for structures that are defined within another union or structure. In those cases, the structure name should always be omitted. -
      • -
    • - No structure definitions within Type Definition. - The practice of defining a structure within a type definition is discouraged. - It is preferred that the structure definition and the type definition be separate definitions. - In general, the NuttX coding style discourages any typdef-ing of structures; - normally the full structure name is used as types throughout the code. -
      • -
    • - Short structure names. - Structure names should be terse, but generally descriptive of what the structure contains. - Try to say something with the structure name, but don't try to say too much. - For example, the structure name of xyz_info_s is preferable to something like xyz_datainputstatusinformation_s. -
      • -
    • - Structure name suffix. - All structure names end with the suffix _s. -
      • -
    • - Module name prefix - If a structure belongs to a module with a name of, say xyz, then that module should be included as a prefix to the structure name like: xyz_. -
      • -
    • - Lowercase. - Use all lower case letters. -
      • -
    • - Minimal use of '_'. - Preferably there are few '_' separators within the structure name. - Long variable names might require some delimitation using '_'. - Long variable names, however, are discouraged. -
      • -
    - -

    Structure Field Naming

    -
      -
    • - Common variable naming. - Structure field naming is generally the same as for local variables. -
      • -
    • - One definition per line. - The one definition per line rule applies to structure fields, - including bit field definitions. -
      • -
    • - Each field should be commented. - Each structure field should be commented. - Commenting should follow the standard conventions. -
      • -
    • - Optional structure field prefix. - It make be helpful to add a two-letter prefix to each field name so that is is clear which structure the field belongs to. - Although a good practice, that convention has not been used consistently in NuttX. -
      • -
    • - Lowercase. - Use all lower case letters. -
      • -
    • - Minimal use of '_'. - Preferably there are few '_' separators within the field name. - Long variable names might require some delimitation using '_'. - Long variable names, however, are discouraged. -
      • -
    -

    - Other Applicable Coding Standards. - See sections related to line formatting, use of braces, indentation, and comments. -

    -

    - Size Optimizations. - When declaring fields in structures, order the declarations in such a way as to minimize memory waste due of data alignment. - This essentially means that that fields should be organized by data size, not by functionality: - Put all pointers togeter, all uint8_t's together, all uint32_t's together. - Data types withi well known like uint8_t and uint32_t should also be place in either ascending or descending size order. -

    -
    - - -
    -

    Incorrect

    -
      -typedef struct
-{
-  ...
-  int val1, val2, val3; /* Values 1-3 */
-  ...
-} xzy_info_t;
-
-struct xyz_information
-{
-  ...
-  uint8_t bita : 1,  /* Bit A */
-          bitb : 1,  /* Bit B */
-          bitc : 1;  /* Bit C */
-  ...
-};
-
     -
    -

    Correct

    -
      -struct xyz_info_s
-{
-  ...
-  int val1; /* Value 1 */
-  int val2; /* Value 2 */
-  int val3; /* Value 3 */
-  ...
-};
-
      -
      -typdef struct xyz_info_s xzy_info_t;
-
      -

      (The use of typedef'ed structures is acceptable but discouraged)

       -
      -struct xyz_info_s
-{
-  ...
-  uint8_t bita : 1,  /* Bit A */
-  uint8_t bitb : 1,  /* Bit B */
-  uint8_t bitc : 1,  /* Bit C */
-  ...
-};
-
     -
    - -

    2.6 Unions

    -

    - Union and Field Names. - Naming of unions and fields within unions follow the same naming rules as for structures and structure fields. - The only difference is that the suffix _u is used to identify unions. -

    -

    - Other Applicable Coding Standards. - See sections related to line formatting, use of braces, indentation, and comments. -

    -
    - -
    -

    Example

    -
      -union xyz_union_u
-{
-  uint8_t  b[4]; /* Byte values */
-  uint16_t h[2]; /* Half word values */
-  uint32_t w;    /* Word Value */
-};
-
-struct xyz_info_s
-{
-  ...
-  union
-  {
-    uint8_t  b[4]; /* Byte values */
-    uint16_t h[2]; /* Half word values */
-    uint32_t w;    /* Word Value */
-  } u;
-  ...
-};
-
     -
    -

    - NOTE: - Note that the union name u is used often. - This is another exception to the prohibition against using single character variable and field names. - The short field name u clearly identifies a union field and prevents the full name to the union value from being excessively long. -

    - -

    2.7 Enumerations

    -

    - Enumeration Naming. - Naming of enumerations follow the same naming rules as for structure and union naming. - The only difference is that the suffix _e is used to identify an enumeration. -

    -

    - Enumeration Value Naming. - Enumeration values, however, following a naming convention more similar to macros. -

    -
      -
    • - Uppercase. - Enumeration values are always in upper case. -
      • -
    • - Use of '_' encouraged. - Unlike other naming, use of the underscore character _ to break up enumeration names is encouraged. -
      • -
    • - Prefix. - Each value in the enumeration should begin with an upper-case prefix that identifies the value as a member of the enumeration. - This prefix should, ideally, derive from the name of the enumeration. -
      • -
    • - No dangling commas. - There should be no dangling comma on the final value of the enumeration. - The most commonly used tool chain are tolerant of such dangling commas, but others will not. -
      • -
    -

    - Other Applicable Coding Standards. - See sections related to line formatting, use of braces, indentation, and comments. -

    -
    - -
    -

    Example

    -
      -enum xyz_state_e
-{
-  XYZ_STATE_UNINITIALIZED = 0, /* Uninitialized state */
-  XYZ_STATE_WAITING,           /* Waiting for input state */
-  XYZ_STATE_BUSY,              /* Busy processing input state */
-  XYZ_STATE_ERROR,             /* Halted due to an error */
-  XYZ_STATE_TERMINATING,       /* Terminating stated */
-  XYZ_STATE_TERMINATED         /* Terminating stated */
-};
-
     -
    - -

    2.8 C Pre-processor Macros

    - -

    Coding Standard:

    - -

    - Macro Naming. - Macro naming following a naming convention similar to the naming of enumeration values. -

    -
      -
    • - Uppercase. - Macro names are always in upper case. -
      • -
    • - Lowercase Exceptions. - There are3 a few lower case values in NuttX macro names. Such as a lower-case p for a period or decimal point (such as VOLTAGE_3p3V). - I have also used lower-case v for a version number (such as CONFIG_NET_IPv6). - However, these are exceptions to the rule rather than illustrating a rule. -
      • -
    • - Macros that could be functions. - Lower-case macro names are also acceptable if the macro is a substitute for a function name that might be used in some other context. - In that case, normal function naming applies. -
      • -
    • - Use of '_' encouraged. - Unlike other naming, use of the underscore character _ to break up macro names is encouraged. -
      • -
    • - Prefix. - Each related macro value should begin with an upper-case prefix that identifies the value as part of a set of values (and also to mimimize the likelihood of naming collisions). -
      • -
    • - Single space after #define. - A single space character should separate the #define from the macro name. - Tabs are never used. -
      • -
    • - Normal commenting rules. - Normal commenting rules apply. -
      • -
    • - Line continuations. - Macro definitions may be continued on the next line by terminating the line with the \ character just before the newline character. - There should be a single space before the \ character. - Aligned \ characters on multiple line continuations are discouraged because they are a maintenance problem. -
      • -
    • - Parentheses around macro argument expansions. - Macros may have argument lists. - In the macros expansion, each argument should be enclosed in parentheses. -
      • -
    • - Real statements. - If a macro functions as a statement, then the macro expansion should be wrapped in do { ... } while (0) to assume that the macros is, indeed, a statement. -
      • -
    • - Magic numbers are prohibited in code. - Any numeric value is not intuitively obvious, must be properly named and provided as either a pre-processor macro or an enumeration value. -
      • -
    • - Side effects. - Be careful of side effects. -
      • -
    -

    - Other Applicable Coding Standards. - See sections related to line formatting, indentation, and comments. -

    -
    - - -
    -

    Incorrect

    -
      -#define max(a,b) a > b ? a : b
-
-#define ADD(x,y) x + y
-
-#ifdef HAVE_SOMEFUNCTION
-int somefunction(struct somestruct_s* psomething);
-#else
-#define SOMEFUNCTION() (0)
-#endif
-
-#	define	IS_A_CAT(c)		((c) == A_CAT)
-
-#define LONG_MACRO(a,b)                                  \
-  {                                                      \
-    int value;                                           \
-    value = b-1;                                         \
-    a = b*value;                                         \
-  }
-
-#define DO_ASSIGN(a,b) a = b
-
     -
    -

    Correct

    -
      -#define MAX(a,b) (((a) > (b)) ? (a) : (b))
-
-#define ADD(x,y) ((x) + (y))
-
-#ifdef HAVE_SOMEFUNCTION
-int somefunction(struct somestruct_s* psomething);
-#else
-#  define somefunction(p) (0)
-#endif
-
-# define IS_A_CAT(c)  ((c) == A_CAT)
-
-#define LONG_MACRO(a,b) \
-  { \
-    int value; \
-    value = (b)-1; \
-    (a) = (b)*value; \
-  }
-
-#define DO_ASSIGN(a,b) do { (a) = (b); } while (0)
-
     -
    - -

    2.9 Pointer Variables

    -

    - Pointer Naming. - Pointers following same naming conventions as for other variable types. - A pointer (or pointer-to-a-pointer) variable may be prefaced with p (or pp) with no intervening underscore character _ in order to identify that variable is a pointer. - That convention is not encouraged, however, and is only appropriate if there is some reason to be concerned that there might otherwise be confusion with another variable that differs only in not being a pointer. -

    - White Space. - The asterisk used in the declaration of a pointer variable or to dereference a pointer variable should be placed immediately before the variable name with no intervening spaces. - A space should precede the asterisk in a cast to a pointer type. -

    -
    - - -
    -

    Incorrect

    -
      -int somefunction(struct somestruct_s* psomething);
-
-ptr = (struct somestruct_s*)value;
-
     -
    -

    Correct

    -
      -int somefunction(FAR struct somestruct_s *something);
-
-ptr = (FAR struct somestruct_s *)value;
-
     -
    - -

    - FAR, NEAR, DSEG and CODE pointers. - Some architectures require a qualifier on pointers to identify the address space into which the pointer refers. - The macros FAR, NEAR, DSEG and CODE are defined in include/nuttx/compiler.h to provide meaning for this qualifiers when needed. - For portability, the general rule is that pointers to data that may lie in the stack, heap, .bss, or .data should be prefaced by the qualifier FAR; pointers to functions probably lie in a code address space and should have the qualifier CODE. - The typical effect of these macros on architectures where they have meaning to determine the size of the pointer (size in the sense of the width of the pointer value in bits). -

    - -

    2.10 Initializers

    -

    - Applicable Coding Standards. - See the section related to parentheses. -

    -

    - C89 Compatibility. - All common NuttX code must conform to ANSII C89 requirements. - Newer C standards permit more flexible initialization with named initializers and array initializers. - However, these are not backward compatible with C89 and cannot be used in common code. - Newer C99 features may be included in architecture-specific sub-directories where there is no possibility of the use of such older toolchains. - C11 is included in NuttX, but has not been verified and, hence, it not encourage anywhere. -

    - - - - - -
    -

    3.0 Functions

    -
    - -

    3.1 Function Headers

    - -

    Coding Standard:

    -
      -
    • - Function headers. - Each function is preceded by a function header. The function header is a block comment that provides information about the function. - The block comment consists of the following: -

        -
      • - The block comment begins with a line that consists of the opening C comment in column 1 (/*) followed by a series of asterisks extending to the length of the line (usually to column 78). -
        • -
      • - The block comment ends with a line that consists of series of asterisks beginning at column 2 and extending to the near the end line (usually to column 77) followed by the closing C comment in (usually at column 78 for a total length of 79 characters). -
        • -
      • - Information about the function is included in lines between the first and final lines. - Each of these begin with a space in column 1, an sterisk (*) in column 2, and a space in column 3. -
        • -

      -
      • -
    • - Function header preceded by one blank line. - Exactly one blank line precedes each function header. -
      • -
    • - Function header followed by one blank line. - Exactly one blank line is placed after function header and before the function definition. -
      • -
    • - Function header sections. - Within the function header, the following data sections must be provided: -

        -
      • - * Name: followed by the name of the function on the same line. -
        • -
      • - * Description: followed by a description of the function beginning on the second line. - Each line of the function description is indented by two additional spaces. -
        • -
      • - * Input Parameters: followed by a description of the of each input parameter beginning on the second line. - Each input parameter begins on a separator line indented by two additional spaces. - The description needs to include (1) the name of the input parameters, and (2) a short description of the input parameter. -
        • -
      • - * Returned Value: followed by a description of the of returned value(s) beginning on the second line. - The description of the returned value should identify all error values returned by the function. -
        • -
      • - * Assumptions/Limitations: followed by a any additional information that is needed to use the function correctly. - This section is optional and may be omitted with there is no such special information required for use of the function. -
        • -

      - Each of these data sections is separated by a single line like " * ". -
      • -
    -

    - Function header template. - Refer to Appendix A for the template for a function header. -

    - -

    3.2 Function Naming

    - -

    Coding Standard:

    -
      -
    • - Short function names. - Function names should be terse, but generally descriptive of what the function is for. - Try to say something with the function name, but don't try to say too much. - For example, the variable name of xyz_putvalue is preferable to something like xyz_savethenewvalueinthebuffer. -
      • -
    • - Lowercase. - Use all lower case letters. -
      • -
    • - Module prefix. - All functions in the same module, or sub-system, or within the same file should have a name beginning with a common prefix separated from the remainder of the function name with the underscore, '_', character. - For example, for a module called xyz, all of the functions should begin with xyz_. -
      • -
    • - Extended prefix. - Other larger functional grouping should have another level in the naming convention. - For example, if module xyz contains a set of functions that manage a set of I/O buffers (IOB), then those functions all should get naming beginning with a common prefix like xyz_iob_. -
      • -
    • - Use of '_' discouraged. - Further use of the '_' separators is discouraged in function naming. - Long function names might require some additional elimitation using '_'. - Long function names, however, are also discouraged. -
      • -
    • - Verbs and Objects. - The remainder of the function name should be either in the form of verb-object or object-verb. - It does not matter which as long as the usage is consistent within the module. - Common verbs include get and set (or put) for operations that retrieve or store data, respectively. - The verb is is reserved for functions that perform some test and return a boolean value to indicate the result of the test. - In this case, the object should indicate what is testing and the return value of true should be consistent with result of the test being true. -
      • -
    - -

    3.3 Parameter Lists

    - -

    - Coding Standards. - See general rules for parameter naming. - See also the sections related to the use of parentheses. -

    -

    - Use of const Parameters. - Use of the const storage class is encouraged. - This is appropriate to indicate that the function will not modify the object. -

    - -

    3.4 Function Body

    - -

    Coding Standard:

    -
      -
    • - Single compound statement. - The function body consists of a single compound statement. -
      • -
    • - Braces in column 1 - The opening and close braces of the compound statement must be placed in column one. -
      • -
    • - First definition or statement in column 3. - The first data definitions or statements in the function body are idented by two spaces. - Standards for statements are covered in the following paragaraph -
      • -
    • - Local variables first. - Because NuttX conforms to the older C89 standard, all variables that have scope over the entire compound statement must be defined at the beginning of the compound statement. - A single blank line must follow the local variable definitions. -
      • -
    • - Long functions are discouraged. - As a rule of thumb, the length of a function should be limited so that it would fit on a single page (if you were to print the source code). -
      • -
    • - Space after the function boady - A one (and only one) blank line must follow the closing right brace of the function body. -
      • -
    - -

    Returned Values

    - -

    - OS Internal Functions. - In general, OS internal functions return a type int to indicate success or failure conditions. - Non-negative values indicate success. - The return value of zero is the typical success return value, but other successful return can be represented with other positive values. - Errors are always reported with negative values. - These negative values must be a well-defined errno as defined in the file nuttx/include/errno.h. -

    - -

    - Application/OS Interface. - All but a few OS interfaces conform to documented standards that have precedence over the coding standards of this document. -

    - -

    - Checking Return Values. - Callers of internal OS functions should always check return values for an error. - At a minimum, a debug statement should indicate that an error has occurred. - The calling logic intentionally ignores the returned value, then the function return value should be explicitly cast to (void) to indicate that the return value is intentionally ignored. - An exception of for standard functions for which people have historically ignored the returned values, such as printf() or close. - All calls to malloc or realloc must be checked for failures to allocate memory. -

    - - - - - -
    -

    4.0 Statements

    -
    - -

    4.1 One Statement Per Line

    - -

    Coding Standard:

    -
      -
    • - One statement per line. - There should never be more than one statement on a line. -
      • -
    • - No more than one assignment per statement. - Related to this, there should never be multiple assignments in the same statement. -
      • -
    • - Statements should never be on the same line as any keyword. - Statements should never be on the same line as case selectors or any C keyword. -
      • -
    -

    - Other Applicable Coding Standards. - See the section related to the use of braces. -

    - -
    - - -
    -

    Incorrect

    -
      -  if (var1 < var2) var1 = var2;
-
-  case 5: var1 = var2; break;
-
-  var1 = 5; var2 = 6; var3 = 7;
-
-  var1 = var2 = var3 = 0;
-
     -
    -

    Correct

    -
      -  if (var1 < var2)
-    {
-      var1 = var2;
-    }
-
-  case 5:
-    {
-      var1 = var2;
-    }
-    break;
-
-  var1 = 5;
-  var2 = 6;
-  var3 = 7;
-
-  var1 = 0;
-  var2 = 0;
-  var3 = 0;
-
     -
    - -

    4.2 Casts

    - -

    Coding Standard:

    -
      -
    • - No space in cast. - There should be no space between a cast and the value being cast. -
      • -
    -
    - - -
    -

    Incorrect

    -
      -struct something_s *x = (struct something_s*) y;
-
     -
    -

    Correct

    -
      -struct something_s *x = (struct something_s *)y;
-
     -
    - -

    4.3 Operators

    -

    - Spaces before and after binary operators. - All binary operators (operators that come between two values), such as +, -, =, !=, ==, >, etc. should have a space before and after the operator, for readability. As examples: -

    -
    - - -
    -

    Incorrect

    -
      -for=bar;
-if(a==b)
-for(i=0;i>5;i++)
-
     -
    -

    Correct

    -
      -for = bar;
-if (a == b)
-for (i = 0; i > 5; i++)
-
     -
    - -

    - No space separating unary operators. - Unary operators (operators that operate on only one value), such as ++, should not have a space between the operator and the variable or number they are operating on. -

    -
    - - -
    -

    Incorrect

    -
      -x ++;
-
     -
    -

    Correct

    -
      -x++;
-
     -
    - -

    -

    4.4 if then else Statement

    - -

    Coding Standard:

    -
      -
    • - Keywords on separate lines. - if <condition> and else must lie on separate lines with nothing else present on the line. -
      • -
    • - Indentation and parentheses. - if <condition> follows the standard indentation and parentheses rules. -
      • -
    • - Alignment. - The if in the if <condition> line and the else must be aligned at the same column. -
      • -
    • - Statement(s) always enclosed in braces. - Statement(s) following the if <condition> and else lines must always be enclosed in braces. - Braces must follow the if <condition> and else lines even in the case where these is no contained statement! -
      • -
    • - Braces and indentation. - The placement of braces and statements must follow the standard rules for braces and indentation. -
      • -
    • - Followed by a single blank line. - The final right brace must be followed by a blank line. -
      • -
    -

    - Other Applicable Coding Standards. - See sections related to use of braces and indentation. -

    - -
    - - -
    -

    Incorrect

    -
      -  if(var1 < var2) var1 = var2;
-
-  if(var > 0)
-    var--;
-  else
-    var = 0;
-
-  if (var1 > 0) {
-    var1--;
-  } else {
-    var1 = 0;
-  }
-  var2 = var1;
-
     -
    -

    Correct

    -
      -  if (var1 < var2
-    {
-      var1 = var2;
-    }
-
-  if (var > 0)
-    {
-      var--;
-    }
-  else
-    {
-      var = 0;
-    }
-
-  if (var1 > 0)
-    {
-      var1--;
-    }
-  else
-    {
-      var1 = 0;
-    }
-
-  var2 = var1;
-
     -
    - -

    - <condition> ? <then> : <else> -

    -
      -
    • - Only if the expression is short. - Use of this form is only appropriate if the entire sequence is short and fits neatly on the line. -
      • -
    • - Multiple lines forbidden. - This form is forbidden if it extends to more than one line. -
      • -
    • - Use of parentheses. - The condition and the entire sequence are often enclosed in parentheses. - These are, however, not required if the expressions evaluate properly without them. -
      • -
    -

    - Other Applicable Coding Standards. - See sections related to parentheses. -

    -
    - -
    -

    Example

    -
      -  int arg1 = arg2 > arg3 ? arg2 : arg3;
-  int arg1 = ((arg2 > arg3) ? arg2 : arg3);
-
     -
    - -

    4.5 switch Statement

    - -

    Coding Standard:

    -
      -
    • - Falling through. - Falling through a case statement into the next case statement is be permitted as long as a comment is included. -
      • -
    • - default case. - The default case should always be present and trigger an error if it is reached when it should not be. -
      • -
    • - Case logic in braces. - It is preferable that all case logic (except for the break) be enclosed in braces. - If you need to instantiate local variables in case logic, then that logic must be surrounded with braces. -
      • -
    • - break outside of braces. - break statements are normally indented by two spaces. - When used conditionally with case logic, the placement of the break statement follows normal indentation rules. -
      • -
    -

    - Other Applicable Coding Standards. - See sections related to use of braces, indentation, and comments. -

    -
    - -
    -

    Example

    -
      -  switch (...)
-    {
-      case 1:  /* Example of a comment following a case selector */
-      ...
-
-      /* Example of a comment preceding a case selector */
-
-      case 2:
-        {
-          /* Example of comment following the case selector */
-
-          int value;
-          ...
-        }
-        break;
-
-      default:
-        break;
-    }
-
     -
    - -

    4.6 while Statement

    -

    Coding Standard:

    -
      -
    • - Keywords on separate lines. - while <condition> must lie on a separate line with nothing else present on the line. -
      • -
    • - Indentation and parentheses. - while <condition> follows the standard indentation and parentheses rules. -
      • -
    • - Statements enclosed in braces - Statement(s) following the while <condition> must always be enclosed in braces, even if only a single statement follows. -
      • -
    • - No braces on null statements. - No braces are required if no statements follow the while <condition>. - The single semicolon (null statement) is sufficient; -
      • -
    • - Braces and indentation. - The placement of braces and statements must follow the standard rules for braces and indentation. -
      • -
    • - Followed by a single blank line. - The final right brace must be followed by a blank line. -
      • -
    -

    - Other Applicable Coding Standards. - See sections related to use of braces, indentation, and comments. -

    -
    - - -
    -

    Incorrect

    -
      -  while( notready() )
-    {
-    }
-  ready = true;
-
-  while (*ptr != '\0') ptr++;
-
     -
    -

    Correct

    -
      -  while (notready());
-
-  ready = true;
-
-  while (*ptr != '\0')
-    {
-      ptr++;
-    }
-
-
     -
    - -

    4.7 do while Statement

    -

    Coding Standard:

    -
      -
    • - Keywords on separate lines. - do and while <condition> must lie on separate lines with nothing else present on the line. -
      • -
    • - Indentation and parentheses. - do .. while <condition> follows the standard indentation and parentheses rules. -
      • -
    • - Statements enclosed in braces - Statement(s) following the do must always be enclosed in braces, even if only a single statement follows. -
      • -
    • - Braces and indentation. - The placement of braces and statements must follow the standard rules for braces and indentation. -
      • -
    • - Followed by a single blank line. - The final right brace must be followed by a blank line. -
      • -
    -

    - Other Applicable Coding Standards. - See sections related to use of braces, indentation, and comments. -

    -
    - - -
    -

    Incorrect

    -
      -  do {
-    ready = !notready();
-  } while (!ready);
-  senddata();
-
-  do ptr++; while (*ptr != '\0');
-
     -
    -

    Correct

    -
      -  do
-    {
-      ready = !notready();
-    }
-  while (!ready);
-
-  senddata();
-
-  do
-    {
-      ptr++;
-    }
-  while (*ptr != '\0');
-
     -
    - -

    4.8 Use of goto

    -

    Coding Standard:

    -
      -
    • - Limited Usage of goto. - All use of the goto statement is prohibited except for one usage: - for handling error conditions in complex, nested logic. - A simple goto in those conditions can greatly improve the readability and complexity of the code. -
      • -
    • - Label Naming. - Labels must all lower case. - The underscore character _ is permitted to break up long labels. -
      • -
    • - Error Exit Labels. - The error exit label is normally called errout. - Multiple error labels are often to required to unwind to recover resources committe in logic prior to the error to otherwise undo preceding operations. - Naming for these other labels would be some like errout_with_allocation, errout_with_openfile, etc. -
      • -
    • - Label Positioning. - Labels are never indented. - Labels must always begin in column 1. -
      • -
    -
    - -
    -

    Example

    -
      -   FAR struct some_struct_s *ptr;
-   int fd;
-   int ret;
-   ...
-
-   if (arg == NULL)
-     {
-       ret = -EINVAL;
-       goto errout;
-     }
-   ...
-   ptr = (FAR struct some_struct_s *)malloc(sizeof(struct some_struct_s));
-   if (!ptr)
-     {
-       ret = -ENOMEM;
-       goto errout;
-     }
-   ...
-   fd = open(filename, O_RDONLY);
-   if (fd < 0)
-     {
-       errcode = -errno;
-       DEBUGASSERT(errcode > 0);
-       goto errotout_with_alloc;
-     }
-   ...
-   ret = readfile(fd);
-   if (ret < 0)
-     {
-       goto errout_with_openfile;
-     }
-   ...
-errout_with_openfile:
-  close(fd);
-
-errout_with_alloc:
-  free(ptr);
-
-error:
-  return ret;
-
     -
    -

    - NOTE: - See the discussion of pointers for information about the FAR qualifier used above. -

    - - - - - -
    -

    Appendix A

    -
    - -

    A.1 C Source File Structure

    -
    -/****************************************************************************
- * <Relative path to the file>
- * <Optional one line file description>
- *
- *   Copyright (C) <Year> <Copyright holder's name>. All rights reserved.
- *   Author: <Author's name> <Contact e-mail>
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * 1. Redistributions of source code must retain the above copyright
- *    notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
- *    notice, this list of conditions and the following disclaimer in
- *    the documentation and/or other materials provided with the
- *    distribution.
- * 3. Neither the name NuttX nor the names of its contributors may be
- *    used to endorse or promote products derived from this software
- *    without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
- * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
- * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
- * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
- * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
- * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
- * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
- * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
- * POSSIBILITY OF SUCH DAMAGE.
- *
- ****************************************************************************/
-
-/****************************************************************************
- * Included Files
- ****************************************************************************/
-
    -

    All header files are included here.

    -
    -/****************************************************************************
- * Pre-processor Definitions
- ****************************************************************************/
-
    -

    All C pre-processor macros are defined here.

    -
    -/****************************************************************************
- * Private Types
- ****************************************************************************/
-
    -

    Any types, enumerations, structures or unions used by the file are defined here.

    -
    -/****************************************************************************
- * Private Function Prototypes
- ****************************************************************************/
-
    -

    Prototypes of all static functions in the file are provided here.

    -
    -/****************************************************************************
- * Private Data
- ****************************************************************************/
-
    -

    All static data definitions appear here.

    -
    -/****************************************************************************
- * Public Data
- ****************************************************************************/
-
    -

    All data definitions with global scope appear here.

    -
    -/****************************************************************************
- * Private Functions
- ****************************************************************************/
-
-/****************************************************************************
- * Name: <Static function name>
- *
- * Description:
- *   Description of the operation of the static function.
- *
- * Input Parameters:
- *   A list of input parameters, one-per-line, appears here along with a
- *   description of each input parameter.
- *
- * Returned Value:
- *   Description of the value returned by this function (if any),
- *   including an enumeration of all possible error values.
- *
- * Assumptions/Limitations:
- *   Anything else that one might need to know to use this function.
- *
- ****************************************************************************/
-
    -

    All static functions in the file are defined in this grouping. -Each is preceded by a function header similar to the above.

    -
    -/****************************************************************************
- * Public Functions
- ****************************************************************************/
-
-/****************************************************************************
- * Name: <Global function name>
- *
- * Description:
- *   Description of the operation of the function.
- *
- * Input Parameters:
- *   A list of input parameters, one-per-line, appears here along with a
- *   description of each input parameter.
- *
- * Returned Value:
- *   Description of the value returned by this function (if any),
- *   including an enumeration of all possible error values.
- *
- * Assumptions/Limitations:
- *   Anything else that one might need to know to use this function.
- *
- ****************************************************************************/
-
    -

    All global functions in the file are defined here.

    - -

    A.2 C Header File Structure

    - -
    -/****************************************************************************
- * <Relative path to the file>
- * <Optional one line file description>
- *
- *   Copyright (C) <Year> <Copyright holder's name>. All rights reserved.
- *   Author: <Author's name> <Contact e-mail>
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * 1. Redistributions of source code must retain the above copyright
- *    notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
- *    notice, this list of conditions and the following disclaimer in
- *    the documentation and/or other materials provided with the
- *    distribution.
- * 3. Neither the name NuttX nor the names of its contributors may be
- *    used to endorse or promote products derived from this software
- *    without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
- * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
- * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
- * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
- * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
- * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
- * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
- * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
- * POSSIBILITY OF SUCH DAMAGE.
- *
- ****************************************************************************/
-
    -

    Header file idempotence definitions go here

    -
    -/****************************************************************************
- * Included Files
- ****************************************************************************/
-
    -

    All header files are included here.

    -
    -/****************************************************************************
- * Pre-processor Definitions
- ****************************************************************************/
-
    -

    All C pre-processor macros are defined here.

    -
    -/****************************************************************************
- * Public Types
- ****************************************************************************/
-
-#ifndef __ASSEMBLY__
-
    -

    Any types, enumerations, structures or unions are defined here.

    -
    -/****************************************************************************
- * Public Data
- ****************************************************************************/
-
-#ifdef __cplusplus
-#define EXTERN extern "C"
-extern "C"
-{
-#else
-#define EXTERN extern
-#endif
-
-
    -

    All data declarations with global scope appear here, preceded by the definition EXTERN.

    -
    -/****************************************************************************
- * Inline Functions
- ****************************************************************************/
-
-/****************************************************************************
- * Name: <Inline function name>
- *
- * Description:
- *   Description of the operation of the inline function.
- *
- * Input Parameters:
- *   A list of input parameters, one-per-line, appears here along with a
- *   description of each input parameter.
- *
- * Returned Value:
- *   Description of the value returned by this function (if any),
- *   including an enumeration of all possible error values.
- *
- * Assumptions/Limitations:
- *   Anything else that one might need to know to use this function.
- *
- ****************************************************************************/
-
    -

    Any static inline functions may be defined in this grouping. -Each is preceded by a function header similar to the above.

    -
    -/****************************************************************************
- * Public Function Prototypes
- ****************************************************************************/
-
-/****************************************************************************
- * Name: <Global function name>
- *
- * Description:
- *   Description of the operation of the function.
- *
- * Input Parameters:
- *   A list of input parameters, one-per-line, appears here along with a
- *   description of each input parameter.
- *
- * Returned Value:
- *   Description of the value returned by this function (if any),
- *   including an enumeration of all possible error values.
- *
- * Assumptions/Limitations:
- *   Anything else that one might need to know to use this function.
- *
- ****************************************************************************/
-
    -

    All global functions in the file are prototyped here. The keyword extern or the definition EXTERN are never used with function prototypes.

    -
    -#undef EXTERN
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* __INCLUDE_ASSERT_H */
-
    -

    Ending with the header file idempotence #endif.

    - - - diff --git a/Documentation/NuttXDemandPaging.html b/Documentation/NuttXDemandPaging.html deleted file mode 100644 index afaaacf862..0000000000 --- a/Documentation/NuttXDemandPaging.html +++ /dev/null @@ -1,674 +0,0 @@ - - -On-Demand Paging - - -
    - - - - -
    -

    On-Demand Paging

    -

    Last Updated: February 4, 2010

    -
    -
    - - - - - -
    -

    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. - This feature was first discussed in this email thread: - https://groups.yahoo.com/neo/groups/nuttx/conversations/messages/213. -

    -

    - 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 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. -

      -
    • - g_waitingforfill. - A doubly linked list that will be used to implement a prioritized list of the TCBs of tasks that are waiting for a page fill. -
      • -
    • - g_pgworker. - The process ID of of the thread that will perform the page fills -
      • -
    -

    -

    - During OS initialization in sched/os_start.c, the following steps - will be performed: -

      -
    • - The g_waitingforfill queue will be initialized. -
      • -
    • - The special, page fill worker thread, will be started. - The pid of the page will worker thread will be saved in g_pgworker. - Note that we need a special worker thread to perform fills; - we cannot use the "generic" worker thread facility because we cannot be - assured that all actions called by that worker thread will always be resident in memory. -
      • -
    -

    -

    - 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. -

      -
    • - It is assumed that this function is called from the level of an exception handler and that all interrupts are disabled. -
      • -
    • - The pg_miss() must be "locked" in memory. - Calling pg_miss() cannot cause a nested page fault. -
      • -
    • - It is assumed that currently executing task (the one at the head of the ready-to-run list) is the one that cause the fault. - This will always be true unless the page fault occurred in an interrupt handler. - Interrupt handling logic must always be available and "locked" into memory so that page faults never come from interrupt handling. -
      • -
    • - The architecture-specific page fault exception handling has already verified that the exception did not occur from interrupt/exception handling logic. -
      • -
    • - As mentioned above, the task causing the page fault must not be the page fill worker thread because that is the only way to complete the page fill. -
      • -
    -

    - -

    Fill Initiation

     - -

    - The page fill worker thread will be awakened on one of three conditions: -

      -
    • - When signaled by pg_miss(), the page fill worker thread will be awakenend (see above), -
      • -
    • - From pg_callback() after completing last fill (when CONFIG_PAGING_BLOCKINGFILL is defined... see below), or -
      • -
    • - A configurable timeout expires with no activity. - This timeout can be used to detect failure conditions such things as fills that never complete. -
      • -
    -

    - -

    - 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 progess. -

    -
      - NOTE: - I think that this is the only state in which a TCB does not reside in some list. - Here is it in limbo, outside of the normally queuing while the page file is in progress. - While here, it will be marked with TSTATE_TASK_INVALID. -
    - -

    - 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: -

      -
    • - Call the architecture-specific function up_checkmapping() to see if the page fill - still needs to be performed. - In certain conditions, the page fault may occur on several threads and be queued multiple times. - In this corner case, the blocked task will simply be restarted (see the logic below for the - case of normal completion of the fill operation). -
      • -
    • - Call up_allocpage(tcb, &vpage). - This architecture-specific function will set aside page in memory and map to virtual address (vpage). - If all available pages are in-use (the typical case), - this function will select a page in-use, un-map it, and make it available. -
      • -
    • - Call the architecture-specific function up_fillpage(). - Two versions of the up_fillpage function are supported -- a blocking and a non-blocking version based upon the configuratin setting CONFIG_PAGING_BLOCKINGFILL. -
        -
      • - If CONFIG_PAGING_BLOCKINGFILL is defined, then up_fillpage is blocking call. - In this case, up_fillpage() will accept only (1) a reference to the TCB that requires the fill. - Architecture-specific context information within the TCB will be sufficient to perform the fill. - And (2) the (virtual) address of the allocated page to be filled. - The resulting status of the fill will be provided by return value from up_fillpage(). -
        • -
      • - If CONFIG_PAGING_BLOCKINGFILL is defined, then up_fillpage is non-blocking call. - In this case up_fillpage() will accept an additional argument: - The page fill worker thread will provide a callback function, pg_callback. - This function is non-blocking, it will start an asynchronous page fill. - After calling the non-blocking up_fillpage(), the page fill worker thread will wait to be signaled for the next event -- the fill completion event. - The callback function will be called when the page fill is finished (or an error occurs). - The resulting status of the fill will be providing as an argument to the callback functions. - This callback will probably occur from interrupt level. -
      -
      • -
    -

    -

    - 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: -

      -
    • - Verify that g_pftcb is non-NULL. -
      • -
    • - Find the higher priority between the task waiting for the fill to complete in g_pftcb and the task waiting at the head of the g_waitingforfill list. - That will be the priority of he highest priority task waiting for a fill. -
      • -
    • - If this higher priority is higher than current page fill worker thread, then boost worker thread's priority to that level. - Thus, the page fill worker thread will always run at the priority of the highest priority task that is waiting for a fill. -
      • -
    • - Save the result of the fill operation. -
      • -
    • - Signal the page fill worker thread. -
      • -
    -

    - -

    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: -

      -
    • - Verify consistency of state information and g_pftcb. -
      • -
    • - Verify that the page fill completed successfully, and if so, -
      • -
    • - Call up_unblocktask(g_pftcb) to make the task that just received the fill ready-to-run. -
      • -
    • - Check if the g_waitingforfill list is empty. - If not: -
        -
      • - Remove the highest priority task waiting for a page fill from g_waitingforfill, -
        • -
      • - Save the task's TCB in g_pftcb, -
        • -
      • - If the priority of the thread in g_pftcb, is higher in priority than the default priority of the page fill worker thread, then set the priority of the page fill worker thread to that priority. -
        • -
      • - Call pg_startfill() which will start the next fill (as described above). -
        • -
      -
      • -
    • - Otherwise, -
        -
      • - Set g_pftcb to NULL. -
        • -
      • - Restore the default priority of the page fill worker thread. -
        • -
      • - Wait for the next fill related event (a new page fault). -
        • -
      -
      • -
    -

    - - - - - -
    -

    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 avaialable 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: -

      -
    • - There is a one-to-one relationship between pages in the virtual address space and between pages of .text in the non-volatile mass storage device. -
      • -
    • - There are, however, far fewer physical pages available than virtual pages. - Only a subset of physical pages will be mapped to virtual pages at any given time. - This mapping will be performed on-demand as needed for program execution. -
    -

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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: -

      -
    • - The size of the locked, memory resident .text area is 32K, and -
      • -
    • - The size of the DATA area is 64K. -
      • -
    • - The size of one, managed page is 1K. -
      • -
    • - The size of the whole .text image on the non-volatile, mass storage device is 1024K. -
      • -
    -

    - 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: -

      -
    • - In the first phase, create a partially linked objected containing all interrupt/exception handling logic, the page fill worker thread plus all parts of the IDLE thread (which must always be available for execution). -
      • -
    • - All of the .text and .rodata sections of this partial link should be collected into a single section. -
      • -
    • - The second link would link the partially linked object along with the remaining object to produce the final binary. - The linker script should position the "special" section so that it lies in a reserved, "non-swappable" region. -
    -

    - -

    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: -

    -
      -
      - void up_block_task(FAR struct tcb_s *tcb, tstate_t task_state); -
      -
      - 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 by the on-demand paging logic in order to block the task that requires the - page fill, and to -
      -
      - void up_unblock_task(FAR struct tcb_s *tcb); -
      -
      - 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 will be called -
      -
    - -

    - New, additional functions that must be implemented just for on-demand paging support: -

    - -
      -
      - int up_checkmapping(FAR struct tcb_s *tcb); -
      -
      - The function up_checkmapping() returns an indication if the page fill still needs to performed or not. - In certain conditions, the page fault may occur on several threads and be queued multiple times. - This function will prevent the same page from be filled multiple times. -
      -
      - int up_allocpage(FAR struct tcb_s *tcb, FAR void *vpage); -
      -
      - This architecture-specific function will set aside page in memory and map to its correct virtual address. - Architecture-specific context information saved within the TCB will provide the function with the information needed to identify the virtual miss address. - This function will return the allocated physical page address in vpage. - The size of the underlying physical page is determined by the configuration setting CONFIG_PAGING_PAGESIZE. - NOTE: This function must always return a page allocation. - If all available pages are in-use (the typical case), then this function will select a page in-use, un-map it, and make it available. -
      -
      int up_fillpage(FAR struct tcb_s *tcb, FAR const void *vpage, void (*pg_callback)(FAR struct tcb_s *tcb, int result)); -
      - The actual filling of the page with data from the non-volatile, must be performed by a separate call to the architecture-specific function, up_fillpage(). - This will start asynchronous page fill. - The common paging logic will provide a callback function, pg_callback, that will be called when the page fill is finished (or an error occurs). - This callback is assumed to occur from an interrupt level when the device driver completes the fill operation. - -
    - - - diff --git a/Documentation/NuttXGettingStarted.html b/Documentation/NuttXGettingStarted.html deleted file mode 100644 index a165a36b13..0000000000 --- a/Documentation/NuttXGettingStarted.html +++ /dev/null @@ -1,25 +0,0 @@ - - -NuttX Getting Started - - - -
    - - - - -
    -

    Getting Started with NuttX

    -

    Last Updated: December 31, 2011

    -
    -
    -

    Getting Started. - There is no "Getting Started" Guide for NuttX yet. - However, most everything that you need to get started with NuttX can be found in the README.txt file located in the top-level NuttX directory. - That README.txt can also be read online in the NuttX GIT repository - here. - Just click on "Links to HEAD: (view)" on that page. -

    - - diff --git a/Documentation/NuttXNxFlat.html b/Documentation/NuttXNxFlat.html deleted file mode 100644 index 62eb03e735..0000000000 --- a/Documentation/NuttXNxFlat.html +++ /dev/null @@ -1,803 +0,0 @@ - - -NXFLAT - - - -
    - - - - -
    -

    NXFLAT

    -

    Last Updated: September 1, 2012

    -
    -
    - - - - -
    -

    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: -

    -
      -
    • Place separately linked programs in a file system, and
      • -
    • Execute those programs by dynamically linking them to the base NuttX code.
      • -
    -

    - 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: -

    -
      -
    • - A dynamic loader that is built into the NuttX core - (See GIT). -
      • -
    • - Minor changes to RTOS to support position independent code, and -
      • -
    • - A linker to bind ELF binaries to produce the NXFLAT binary format - (See GIT). -
      • -
    - -

    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: -

    -
      -
    • NXFLAT does not support shared libraries, because
      • -
    • NXFLAT does not support exportation of symbol values from a module
      • -
    -

    - 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. -

    - -
      -

      - 1MMU: "Memory Management Unit"
      - 2PIC: "Position Independent Code" -

      -
    - -

    1.3 Limitations

     - -
      -
    • ROMFS (or RAM mapping) Only -
        -

        - The current NXFLAT release will work only with either (1) NXFLAT executable modules residing on a ROMFS file system, or (2) executables residing on other file systems provided that CONFIG_FS_RAMMAP is defined. - This limitation is because the loader depends on the capability to mmap() the code segment. - See the NuttX User Guide for further information. -

        -

        - NUTTX does not provide any general kind of file mapping capability. - In fact, true file mapping is only possible with MCUs that provide an MMU1. - Without an MMU, file system may support eXecution In Place (XIP) to mimic file mapping. - Only the ROMFS file system supports that kind of XIP execution need by NXFLAT. -

        -

        - It is also possible to simulate file mapping by allocating memory, copying the NXFLAT binary file into memory, and executing from the copy of the executable file in RAM. - That capability can be enabled with the CONFIG_FS_RAMMAP configuration option. - With that option enabled, NXFLAT will work that kind of file system but will require copying of all NXFLAT executables to RAM. -

        -
      -
      • -
    • GCC/ARM/Cortex-M3/4 Only -
        -

        - At present, the NXFLAT toolchain is only available for ARM and Cortex-M3/4 (thumb2) targets. -

        -
      -
      • -
    • Read-Only Data in RAM -
        -

        - With older GCC compilers (at least up to 4.3.3), read-only data must reside in RAM. - In code generated by GCC, all data references are indexed by the PIC2 base register (that is usually R10 or sl for the ARM processors). - The includes read-only data (.rodata). - Embedded firmware developers normally like to keep .rodata in FLASH with the code sections. - But because all data is referenced with the PIC base register, all of that data must lie in RAM. - A NXFLAT change to work around this is under investigation3. -

        -

        - Newer GCC compilers (at least from 4.6.3), read-only data is no long GOT-relative, but is now accessed PC-relative. With PC relative addressing, read-only data must reside in the I-Space. -

        -
      -
      • -
    • Globally Scoped Function Function Pointers -
        -

        - If a function pointer is taken to a statically defined function, then (at least for ARM) GCC will generate a relocation that NXFLAT cannot handle. - The workaround is make all such functions global in scope. - A fix would involve a change to the GCC compiler as described in Appendix B. -

        -
      -
      • -
    • Special Handling of Callbacks -
        -

        - Callbacks through function pointers must be avoided or, when then cannot be avoided, handled very specially. - The reason for this is that the PIC module requires setting of a special value in a PIC register. - If the callback does not set the PIC register, then the called back function will fail because it will be unable to correctly access data memory. - Special logic is in place to handle some NuttX callbacks: Signal callbacks and watchdog timer callbacks. - But other callbacks (like those used with qsort() must be avoided in an NXFLAT module. -

        -
      -
      • -
    - -

      - 1MMU: "Memory Management Unit"
      - 2PIC: "Position Independent Code"
      - 3A work around is under consideration: - At run time, the .rodata offsets will be indexed by a RAM address. - If the dynamic loader were to offset those .rodata offsets properly, it - still might be possible to reference .rodata in ROM. - That work around is still a topic of investigation at this time. -

    - -

    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: -

    -
      - -
    • - You must have already configured Nuttx in <some-dir>/nuttx -
      • -
    • - Download the buildroot package buildroot-0.x.y into <some-dir> -
    • -
      • - Unpack <some-dir>/buildroot-0.x.y.tar.gz using a command like tar zxf buildroot-0.x.y. - This will result in a new directory like <some-dir>/buildroot-0.x.y - -
    • - Move this into position: mv <some-dir>/buildroot-0.x.y<some-dir>/buildroot -
      • -
    • - cd <some-dir>/buildroot -
      • -
    • - Copy a configuration file into the top buildroot directory: cp configs/abc-defconfig-x.y.z .config. -
      • -
    • - Enable building of the NXFLAT tools by make menuconfig. - Select to build the NXFLAT toolchain with GCC (you can also select omit building GCC with and only build the - NXFLAT toolchain for use with your own GCC toolchain). -
      • -
    • - Make the toolchain: make. - When the make completes, the tool binaries will be available under - <some-dir>/buildroot/build_abc/staging_dir/bin -
      • -
    - -

    1.2 mknxflat

     - -

    - mknxflat is used to build a thunk file. - See below for usage. - -

      -Usage: mknxflat [options] <bfd-filename>
-
-Where options are one or more of the following.  Note
-that a space is always required between the option and
-any following arguments.
-
-  -d Use dynamic symbol table. [symtab]
-  -f <cmd-filename>
-      Take next commands from <cmd-filename> [cmd-line]
-  -o <out-filename>
-     Output to  [stdout]
-  -v Verbose output [no output]
-  -w Import weakly declared functions, i.e., weakly
-     declared functions are expected to be provided at
-     load-time [not imported]
-
    - -

    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. -

    - -
      -Usage: ldnxflat [options] <bfd-filename>
-
-Where options are one or more of the following.  Note
-that a space is always required between the option and
-any following arguments.
-
-  -d Use dynamic symbol table [Default: symtab]
-  -e <entry-point>
-     Entry point to module [Default: _start]
-  -o <out-filename>
-     Output to <out-filename> [Default: <bfd-filename>.nxf]
-  -s <stack-size>
-     Set stack size to <stack-size> [Default: 4096]
-  -v Verbose output. If -v is applied twice, additional
-     debug output is enabled [Default: no verbose output].
-
    - -

    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. -
    -
      -USAGE: ./mksymtab <cvs-file> <symtab-file>
-
-Where:
-
-  <cvs-file>   : The path to the input CSV file
-  <symtab-file>: The path to the output symbol table file
-  -d           : Enable debug output
-
    -

    - For example, -

    -
      -cd nuttx/tools
-cat ../syscall/syscall.csv ../libc/libc.csv | sort >tmp.csv
-./mksymtab.exe tmp.csv tmp.c
-
    - -

    1.5 Making an NXFLAT module

     - -

    - Below is a snippet from an NXFLAT make file (simplified from NuttX - - Hello, World! example. -

    -

      - -
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Target 1hello.r1:hello.o


        		abc-nuttx-elf-ld -r -d -warn-common -o $@ $^
        Target 2hello-thunk.S:hello.r1


        		mknxflat -o $@ $^
        Target 3hello.r2:hello-thunk.S


        		 - abc-nuttx-elf-ld -r -d -warn-common -T binfmt/libnxflat/gnu-nxflat-gotoff.ld -no-check-sections -o $@ hello.o hello-thunk.o -
        Target 4hello:hello.r2


        		ldnxflat -e main -s 2048 -o $@ $^
      - -

      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. -

      - -
        -

        int register_binfmt(FAR struct binfmt_s *binfmt) -

          -

          Description: - Register a loader for a binary format -

          -

          Returned Value: - This is a NuttX internal function so it follows the convention that - 0 (OK) is returned on success and a negated errno is returned on - failure. -

          -
        - -

        int unregister_binfmt(FAR struct binfmt_s *binfmt) -

          -

          Description: - Register a loader for a binary format -

          -

          Returned Value: - This is a NuttX internal function so it follows the convention that - 0 (OK) is returned on success and a negated errno is returned on - failure. -

          -
        -
      - -

      NXFLAT Initialization - These interfaces are specific to NXFLAT. - Normally, an application needs only call nxflat_initialize() during its initialization - to have full NXFLAT support. -

      - -
        -

        int nxflat_initialize(void) -

          -

          Description: - NXFLAT support is built unconditionally. However, it order to - use this binary format, this function must be called during system - format in order to register the NXFLAT binary format. - This function calls register_binfmt() appropriately. -

          -

          Returned Value: - This is a NuttX internal function so it follows the convention that - 0 (OK) is returned on success and a negated errno is returned on - failure. -

          -
        - -

        void nxflat_uninitialize(void) -

          -

          Description: - Unregister the NXFLAT binary loader -

          -

          Returned Value: - None -

          -
        -
      - -

      Binary Loader Interfaces. - The remaining APIs are called by user applications to maintain modules in the file system. -

      - -
        -

        int load_module(FAR struct binary_s *bin) -

          -

          Description: - Load a module into memory, bind it to an exported symbol take, and - prep the module for execution. -

          -

          Returned Value: - This is an end-user function, so it follows the normal convention: - Returns 0 (OK) on success. On failure, it returns -1 (ERROR) with - errno set appropriately. -

          -
        - -

        int unload_module(FAR struct binary_s *bin) -

          -

          Description: - Unload a (non-executing) module from memory. If the module has - been started (via exec_module()), calling this will be fatal. -

          -

          Returned Value: - This is a NuttX internal function so it follows the convention that - 0 (OK) is returned on success and a negated errno is returned on - failure. -

          -
        - -

        int exec_module(FAR const struct binary_s *bin) -

          -

          Description: - Execute a module that has been loaded into memory by load_module(). -

          -

          Returned Value: - This is an end-user function, so it follows the normal convention: - Returns the PID of the exec'ed module. On failure, it.returns - -1 (ERROR) and sets errno appropriately. -

          -
        -
      - - - - - -
      -

      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: -

      -

        -        ldr     r1, .L0         <-- Fetch the offset to 'x'
-        ldr     r0, [r10, r1]   <-- Load the value of 'x' with PIC offset`
-        ...
-.L0:    .word   x               <-- Offset to 'x'
-
      - -

      - Then when PIC is enabled (say with the -fpic compiler option), it will generate code like - this: -

      - -
        -        ldr     r1, .L0         <-- Fetch the offset to the GOT entry
-        ldr     r1, [r10,r1]    <-- Fetch the (relocated) address of 'x' from the GOT
-        ldr     r0, [r1, #0]    <-- Fetch the value of 'x'
-        ...
-.L1     .word   x(GOT)          <-- Offset to entry in the GOT
-
      - -

      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: -

      -

        - - - - - - - - - - - - - -
        Virtual
        .text
        .got
        .data
        .bss
      -

      - 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: -

      - -
        - - - - - - - - - - - - - -
        FlashRAM
        .text.got

        		.data

        		.bss
      - -

      - 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/NuttXScreenShot.jpg b/Documentation/NuttXScreenShot.jpg deleted file mode 100644 index f5a9dc1fe721b12d9744247bbcb80ca8cd85ba82..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 5872 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 S*v^Ll{>86T{NGF0d;SGL89Ma< diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html deleted file mode 100644 index ee746d9a30..0000000000 --- a/Documentation/NuttxPortingGuide.html +++ /dev/null @@ -1,5967 +0,0 @@ - - -NuttX Porting Guide - - - - -
      - - - - -
      -

      - NuttX RTOS Porting Guide -

      -

      Last Updated: May 18, 2015

      -
      -
      - - - - - -
      -

      Table of Contents

      -
      - - - - - - - -
      -

      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 configs/README.txt. -

      - - - - - -
      -

      2.0 Directory Structure

      -
      - -

      - Directory Structure. - The general directly 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>/
-|   |-- binfmt/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   |-- (binfmt-specific sub-directories)/
-|   |   |   `-- (binfmt-specific source files)
-|   |   `-- (common binfmt source files)
-|   |-- configs/
-|   |   |-- <board-name>/
-|   |   |   |-- include/
-|   |   |   |   `-- (other board-specific header files)
-|   |   |   |-- src/
-|   |   |   |   `-- (board-specific source files)
-|   |   |   |---<config-name>/
-|   |   |   |   `-- (board configuration-specific source files)
-|   |   |   `---(other configuration sub-directories for this board)/
-|   |   `-- <(other board directories)>/
-|   |-- 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)
-|   |-- libc/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   `-- (libc source files)
-|   |-- libxx/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   `-- (libxx management 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)
-|   |-- sched/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   `-- (sched source files)
-|   |-- syscall/
-|   |   |-- Makefile
-|   |   |-- Kconfig
-|   |   `-- (syscall source files)
-|   `-- tools/
-|       `-- (miscellaneous scripts and programs)
-`- apps
-    |-- netutils/
-    |   |-- Makefile
-    |   |-- Kconfig
-    |   |-- (network feature sub-directories)/
-    |   |   `-- (network feature source files)
-    |   `-- (netutils common files)
-    |--  nshlib/
-    |   |-- Makefile
-    |   |-- Kconfig
-    |   `-- NuttShell (NSH) files
-    |-- (Board-specific applications)/
-    |   |-- Makefile
-    |   |-- Kconfig
-    |   |-- (Board-specific application sub-directories)/
-    |   |   `-- (Board-specific application source files)
-    |   `-- (Board-specific common files)
-    `-- examples/
-        `-- (example)/
-            |-- Makefile
-            |-- Kconfig
-            `-- (example source files)
-
      - -

      - Configuration Files. - The NuttX configuration consists of: -

      -
        -
      • - Processor architecture specific files. - These are the files contained in the arch/<arch-name>/ directory - and are discussed in a paragraph below. -
        • -
      • - Chip/SoC specific files. - Each processor processor architecture is embedded in chip or System-on-a-Chip (SoC) architecture. - The full chip architecture includes the processor architecture plus chip-specific interrupt logic, - clocking logic, general purpose I/O (GIO) logic, and specialized, internal peripherals (such as UARTs, USB, etc.). -

        - These chip-specific files are contained within chip-specific sub-directories in the - arch/<arch-name>/ directory and are selected via - the CONFIG_ARCH_name selection. -

        -
        • -
      • - 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 network, USB, etc.). -

        - These board-specific configuration files can be found in the - configs/<board-name>/ sub-directories and are discussed - in a paragraph below. -

        -
        • -
      - -

      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 irqsave(void): - Used to disable all interrupts. -
          • -
        • - void irqrestore(irqstate_t flags): - Used to restore interrupt enables to the same state as before irqsave() 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 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: This target will not run on Cygwin probably for many reasons but - first off because it uses some of the same symbols as does cygwind.dll. -

        - -
      • arch/arm: - This directory holds common ARM architectures. At present, this includes - the following subdirectories: -
          -
        • arch/arm/include and arch/arm/src/common: - Common ARM logic. -
          • - -
        • arch/arm/include/c5471 and arch/arm/src/c5471: - TI TMS320C5471 (also called TMS320DM180 or just C5471). - NuttX operates on the ARM7 of this dual core processor. - This port is complete, verified, and included in the NuttX release 0.1.1. -
          • - -
        • arch/arm/include/dm320 and arch/arm/src/dm320: - TI TMS320DM320 (also called just DM320). - NuttX operates on the ARM9EJS of this dual core processor. - This port complete, verified, and included in the NuttX release 0.2.1. -
          • - -
        • arch/arm/include/lpc214x and arch/arm/src/lpc214x: - These directories provide support for NXP LPC214x family of - processors. - 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 configuration is also available. -
          • - -
        -
        • - -
      • configs/mcu123-lpc214x: - The mcu123.com lpc214x development board. - This is a work in progress. -
        • - -
      • arch/z16f: - Zilog z16f Microcontroller. - This port uses the Zilog z16f2800100zcog Development Kit. - This port was released with nuttx-0.3.7. -
        • - -
      • arch/z80: - This directory holds 8-bit ZiLOG architectures. At present, this includes the - Zilog z80, ez80Acclaim! and z8Encore! Microcontrollers. -
          -
        • arch/z80/include and arch/z80/src/common: - Common logic. -
          • - -
        • arch/z80/include/z80 and arch/z80/src/z80: - The Z80 port was released in nuttx-0.3.6 has been verified using only a - z80 instruction simulator called z80sim. - This port also uses the SDCC toolchain (http://sdcc.sourceforge.net/) - (verified with version 2.6.0 and 2.7.0). -
          • - -
        • arch/z80/include/ez80 and arch/z80/src/ez80: - The ez80Acclaim! port uses the ZiLOG ez80f0910200kitg development kit, eZ80F091 part, - with the Zilog ZDS-II Windows command line tools. - The development environment is Cygwin under WinXP. - This is a work in progress. Verified ez80 support will be announced in a future NuttX release. -
          • - -
        • arch/z80/include/z8 and arch/z80/src/z8: - The Z8Encore! port uses either the ZiLOG z8encore000zco development kit, Z8F6403 part, - or the z8f64200100kit development kit, Z8F6423 part with the Zilog ZDS-II Windows command line - tools. The development environment is Cygwin under WinXP. - The initial release, verified only on the ZDS-II ez8 simulator, was released in nuttx-0.3.9. -
          • -
        -
        • -
      - -

      - Deprecated Architecture Directories. - The following architecture directories are deprecated. They have been - replaced by the logic in arm/arm and will deleted when - arch/arm is fully verified. -

      -
        -
      • arch/c5471: - Replaced with arch/arm/include/c5471 and - arch/arm/src/c5471. -
        • - -
      • arch/dm320: - Replaced with arch/arm/include/dm320 and - arch/arm/src/dm320. -
        • -
      -

      - Other ports for the for the TI TMS320DM270 and for MIPS are in various states - of progress -

      - -

      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/configs

      -

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

      - -

      2.4.1 Subdirectory Structure

      -

      - The configs directory contains board specific configuration files. Each board must - provide a subdirectory <board-name> under configs/ with the following characteristics: -

      -
        -<board-name>
-|-- Kconfig
-|-- include/
-|   |-- board.h
-|   `-- (board-specific header files)
-|-- src/
-|   |-- Makefile
-|   `-- (board-specific source files)
-|-- <config1-dir>
-|   |-- Make.defs
-|   |-- defconfig
-|   `-- setenv.sh
-|-- <config2-dir>
-|   |-- Make.defs
-|   |-- defconfig
-|   `-- setenv.sh
-|   ...
-`-- (other board-specific configuration sub-directories)/
-
      - -

      2.4.2 Summary of Files

      -

      2.4.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 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.4.2.2 Board Specific Configuration Sub-Directories

      -

      - The configs/<board-name>/ sub-directory holds all of the - files that are necessary to configure NuttX for the particular board. - A board may have various different configurations using the common source files. - Each board configuration is described by three files: Make.defs, defconfig, and setenv.sh. - Typically, each set of configuration files is retained in a separate configuration sub-directory - (<config1-dir>, <config2-dir>, .. in the above diagram). - - 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=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. -

        -
        • -
      • -

        - setenv.sh: This is a script that can be included that will be installed at - the top level of the directory structure and can be sourced to set any - necessary environment variables. - You will most likely have to customize the default setenv.sh script in order - for it to work correctly in your environment. -

        -
        • -
      - -

      2.4.3 Supported Boards

      -

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

      -
        -
      • configs/avr32dev1: - This is a port of NuttX to the Atmel AVR32DEV1 board. That board is - based on the Atmel AT32UC3B0256 MCU and uses a specially patched - version of the GNU toolchain: The patches provide support for the - AVR32 family. That patched GNU toolchain is available only from the - Atmel website. STATUS: This port is functional but very basic. There - are configurations for NSH and the OS test. -
        • - -
      • configs/c5471evm: - This is a port to the Spectrum Digital C5471 evaluation board. The - C5471 is a dual core processor from TI with an ARM7TDMI general purpose - processor and a c54 DSP. It is also known as TMS320DA180 or just DA180. - NuttX runs on the ARM core and is built with with a GNU arm-nuttx-elf toolchain - under Linux or Cygwin. This port is complete and verified. -
        • - -
      • configs/demo9s12ne64: - Freescale DMO9S12NE64 board based on the MC9S12NE64 hcs12 cpu. This - port uses the m9s12x GCC toolchain. STATUS: (Still) under development; it - is code complete but has not yet been verified. -
        • - -
      • configs/ea3131: - Embedded Artists EA3131 Development bard. This board is based on the - an NXP LPC3131 MCU. This OS is built with the arm-nuttx-elf toolchain. - STATUS: This port is complete and mature. -
        • - -
      • configs/eagle100: - Micromint Eagle-100 Development board. This board is based on the - an ARM Cortex-M3 MCU, the Luminary LM3S6918. This OS is built with the - arm-nuttx-elf toolchain. STATUS: This port is complete and mature. -
        • - -
      • configs/ez80f0910200kitg - ez80Acclaim! Microcontroller. This port use the Zilog ez80f0910200kitg - development kit, eZ80F091 part, and the Zilog ZDS-II Windows command line - tools. The development environment is Cygwin under WinXP. -
        • - -
      • configs/ez80f910200zco: - ez80Acclaim! Microcontroller. This port use the Zilog ez80f0910200zco - development kit, eZ80F091 part, and the Zilog ZDS-II Windows command line - tools. The development environment is Cygwin under WinXP. -
        • - -
      • configs/lm3s6965-ek: - Stellaris LM3S6965 Evaluation Kit. This board is based on the - an ARM Cortex-M3 MCU, the Luminary/TI LM3S6965. This OS is built with the - arm-nuttx-elf toolchain. STATUS: This port is complete and mature. -
        • - -
      • configs/lm3s8962-ek: - Stellaris LMS38962 Evaluation Kit. STATUS: contributed. -
        • - -
      • configs/lpcxpresso-lpc1768: - Embedded Artists base board with NXP LPCExpresso LPC1768. This board - is based on the NXP LPC1768. The Code Red toolchain is used by default. -
        • - -
      • configs/mbed: - The configurations in this directory support the mbed board (http://mbed.org) - that features the NXP LPC1768 microcontroller. This OS is also built - with the arm-nuttx-elf toolchain. STATUS: Contributed. -
        • - -
      • configs/mcu123-lpc214x: - This port is for the NXP LPC2148 as provided on the mcu123.com - lpc214x development board. - This OS is also built with the arm-nuttx-elf toolchain* under Linux or Cygwin. - The port supports serial, timer0, spi, and usb. -
        • - -
      • configs/mirtoo: - This is the port to the DTX1-4000L "Mirtoo" module. - This module uses MicroChipPIC32MX250F128D. - See the Dimitech website for further information. -
        • - -
      • configs/mx1ads: - This is a port to the Motorola MX1ADS development board. That board - is based on the Freescale i.MX1 processor. The i.MX1 is an ARM920T. - STATUS: This port is nearly code complete but was never fully - integrated due to tool-related issues. -
        • - -
      • configs/ne64badge: - Future Electronics Group NE64 /PoE Badge board based on the - MC9S12NE64 hcs12 cpu. This port uses the m9s12x GCC toolchain. - STATUS: The port is code-complete but was never fully tested. -
        • - -
      • configs/ntosd-dm320: - This port uses the Neuros OSD with a GNU arm-nuttx-elf toolchain* under Linux or Cygwin. - See Neuros Wiki - for further information. - NuttX operates on the ARM9EJS of this dual core processor. - STATUS: This port is code complete, verified, and included in the - NuttX 0.2.1 release. -
        • - -
      • configs/nucleus2g: - This port uses the Nucleus 2G board (with Babel CAN board). - This board features an NXP LPC1768 processor. - See the 2G Engineering website for more information about the Nucleus 2G. -
        • - -
      • configs/olimex-lpc1766stk: - This port uses the Olimex LPC1766-STK board and a GNU GCC toolchain under - Linux or Cygwin. STATUS: Complete and mature. -
        • - -
      • configs/olimex-lpc2378: - This port uses the Olimex-lpc2378 board and a GNU arm-nuttx-elf toolchain under - Linux or Cygwin. STATUS: ostest and NSH configurations available. -
        • - -
      • configs/olimex-strp711: - This port uses the Olimex STR-P711 board arm-nuttx-elf toolchain* under Linux or Cygwin. - See the Olimex web site - for further information. - STATUS: Configurations for the basic OS test and NSH are complete and verified. -
        • - -
      • configs/pcblogic-pic32mx: - This is the port of NuttX to the PIC32MX board from PCB Logic Design Co. - This board features the MicroChip 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: Code complete but testing has been stalled due to tool related problems - (PICkit 2 does not work with the PIC32). -
        • - -
      • configs/qemu-i486: - Port of NuttX to QEMU in i486 mode. This port will also run on real i486 - hardware (Google the Bifferboard). -
        • - -
      • configs/rgmp: - RGMP stands for RTOS and GPOS on Multi-Processor. RGMP is a project for - running GPOS and RTOS simultaneously on multi-processor platforms. You can - port your favorite RTOS to RGMP together with an unmodified Linux to form a - hybrid operating system. This makes your application able to use both RTOS - and GPOS features. - See the RGMP Wiki for further information about RGMP. -
        • - -
      • configs/sam3u-ek: - The port of NuttX to the Atmel SAM3U-EK development board. -
        • - -
      • configs/skp16c26: - Renesas M16C processor on the Renesas SKP16C26 StarterKit. This port - uses the GNU m32c toolchain. STATUS: The port is complete but untested - due to issues with compiler internal errors. -
        • - -
      • configs/stm3210e-eval: - STMicro STM3210E-EVAL development board based on the STMicro STM32F103ZET6 - microcontroller (ARM Cortex-M3). This port uses the GNU Cortex-M3 - toolchain. -
        • - -
      • configs/sim: - A user-mode port of NuttX to the x86 Linux 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. -
        • - -
      • configs/us7032evb1: - This is a port of the Hitachi SH-1 on the Hitachi SH-1/US7032EVB1 board. - 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 limited 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. -
        • - -
      • configs/vsn: - ISOTEL NetClamps VSN V1.2 ready2go sensor network platform based on the - STMicro STM32F103RET6. Contributed by Uros Platise. - See the Isotel web site for further information - about the NetClamps board. -
        • - -
      • configs/xtrs: - TRS80 Model 3. This port uses a vintage computer based on the Z80. - An emulator for this computer is available to run TRS80 programs on a - Linux platform (http://www.tim-mann.org/xtrs.html). -
        • - -
      • configs/z16f2800100zcog - z16f Microcontroller. - This port use the Zilog z16f2800100zcog development kit and the - Zilog ZDS-II Windows command line tools. - The development environment is Cygwin under WinXP. -
        • - -
      • configs/z80sim: - z80 Microcontroller. This port uses a Z80 instruction set simulator - called z80sim. - This port also the SDCC toolchain under Linux or Cygwin(verified with version 2.6.0). -
        • - -
      • configs/z8encore000zco - z8Encore! Microcontroller. This port use the Zilog z8encore000zco - development kit, Z8F6403 part, and the Zilog ZDS-II Windows command line - tools. The development environment is Cygwin under WinXP. -
        • - -
      • configs/z8encore000zco - z8Encore! Microcontroller. This port use the Zilog z8f64200100kit - development kit, Z8F6423 part, and the Zilog ZDS-II Windows command line - tools. The development environment is Cygwin under WinXP. -
        • - -
      • configs/z8f64200100kit: - z8Encore! Microcontroller. This port use the Zilog z8f64200100kit - development kit, Z8F6423 part, and the Zilog ZDS-II Windows command line - tools. The development environment is Cygwin under WinXP. -
        • -
      - -

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

      - -

      2.4.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 configs/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 configs/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 configs/Kconfig to support your new board configuration. -

      -

      - In configs/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 configs/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 configs/myboard and we add the following to the long list of defaults (again in alphabetical order): -

      -
        -    default "myboar"              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 configs/myboard: -

      -
        -if ARCH_BOARD_MYBOARD
-source "configs/myboard/Kconfig"
-endif
-
      -

      - This includes additional, board-specific configuration variable definitions in configs/myboard/Kconfig. -

      - -

      2.5 nuttx/drivers

      - -

      - This directory holds architecture-independent device drivers. -

      -
        -drivers/
-|-- Kconfig
-|-- Makefile
-|-- analog/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Common ADC and DAC driver source files)
-|-- bch/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (bch driver source files)
-|-- input/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Common touchscreen and keypad driver source files)
-|-- lcd/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Common LCD driver source files)
-|-- mmcsd/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Common MMC/SD card driver source files)
-|-- mtd/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Common memory technology device driver source files)
-|-- net/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Common network driver source files)
-|-- sensors/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Common sensor driver source files)
-|-- serial/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Files for the Calypso SERCOMM driver)
-|-- serial/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Common front-end character drivers for chip-specific UARTs)
-|-- usbdev/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Common USB device driver source files)
-|-- usbhost/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Common USB host driver source files)
-|-- wireless/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Common wireless driver source files)
-`-- (Various common driver source files)
-
      - -

      2.6 nuttx/fs

      - -

      - This directory contains the NuttX file system. - This file system is described below. -

      -
        -fs/
-|-- Kconfig
-|-- Makefile
-|-- fat/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (FAT file system source files)
-|-- mmap/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (RAM-based file mapping source files)
-|-- nfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (NFS client file system source files)
-|-- nxffs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (NuttX Flash File System (NXFFS) source files)
-|-- romfs/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (ROMFS file system source files)
- `-- (common file system source files)
-
      - -

      2.7 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)
-|-- nxfont/
-|   |-- Make.defs
-|   `-- (NuttX graphics font-related (NXFONT) source files)
-|-- nxglib/
-|   |-- Make.defs
-|   `-- (NuttX graphics library (NXGL) source files)
-|-- nxmu/
-|   |-- Make.defs
-|   `-- (NuttX graphics multi-user (NXMU) server source files)
-|-- nxsu/
-|   |-- Make.defs
-|   `-- (NuttX graphics single-user (NXSU) source files)
-`-- (common file system source files)
-
      - -

      2.8 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)
-|-- nuttx/
-|   |-analog/
-|   |  `-- (Analog driver header files)
-|   |-audio/
-|   |  `-- (Audio driver header files)
-|   |-binfmt/
-|   |  `-- (Binary format header files)
-|   |-fs/
-|   |  `-- (File System header files)
-|   |-input/
-|   |  `-- (Input device driver header files)
-|   |-lcd/
-|   |  `-- (LCD driver header files)
-|   |-mtd/
-|   |  `-- (Memory technology device header files)
-|   |-serial/
-|   |  `-- (Serial driver header files)
-|   |-net/
-|   |  `-- (Networking header files)
-|   |-nx/
-|   |  `-- (NX graphics header files)
-|   |-power/
-|   |  `-- (Power management header files)
-|   |-sensors/
-|   |  `-- (Sensor device driver header files)
-|   |-sercomm/
-|   |  `-- (SERCOMM driver header files)
-|   |-serial/
-|   |  `-- (Serial driver header files)
-|   |-spi/
-|   |  `-- (SPI driver header files)
-|   |-syslog/
-|   |  `-- (SYSLOG header files)
-|   |-usb/
-|   |  `-- (USB driver header files)
-|   `-wireless/
-|      `-- (Wireless device driver header files)
-`- sys/
-    `-- (More standard header files)
-
      - -

      2.9 nuttx/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 (libuc.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/
-|-- libgen/
-|   `-- (Implementation of functions from libgen.h)
-|-- math/
-|   `-- (Implementation of functions from fixedmath.h)
-|-- misc/
-|   `-- (Implementation of miscellaneous library functions)
-|-- mqueue/
-|   `-- (Implementation of some functions from mqueue.h)
-|-- net/
-|   `-- (Implementation of network-related library functions)
-|-- 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)
-|-- stdio/
-|   `-- (Implementation of functions from stdio.h)
-|-- stdlib/
-|   `-- (Implementation of functions from stdlib.h)
-|-- string/
-|   `-- (Implementation of functions from string.h)
-|-- time/
-|   `-- (Implementation of some functions from time.h)
-`-- unistd/
-    `-- (Implementation of some functions from unistd.h)
-
      - -

      2.10 nuttx/libxx

      -

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

      - -

      2.11 nuttx/mm

      -

      - This is the NuttX memory manager. -

      - -

      2.12 nuttx/net

      -

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

      - -

      2.13 nuttx/sched

      -

      - The files forming core of the NuttX RTOS reside here. -

      - -

      2.14 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.15 nuttx/tools

      -

      - This directory holds a collection of tools and scripts to simplify - configuring, building and maintaining NuttX. -

      -
        -tools/
-|-- Makefile.host
-|-- Makefile.export
-|-- README.txt
-|-- configure.sh / configure.bat
-|-- cfgparser.c
-|-- cfgparser.h
-|-- copydir.sh / copydir.bat
-|-- define.sh / define.bat
-|-- incdir.sh / indir.bat
-|-- indent.sh
-|-- link.sh / link.bat
-|-- mkconfig.c
-|-- mkdeps.sh / mkdeps.bat
-|-- mkexport.sh
-|-- mkimage.sh
-|-- mknulldeps.sh
-|-- mkromfsimg.sh
-|-- mksyscall.c
-|-- mkversion.c
-|-- unlink.sh / unlink.bat
-|-- version.sh
-`-- 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.16 nuttx/Makefile

      -

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

      - -

      2.17 apps/netutils

      -

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

      -
        -netutils/
-|-- Kconfig
-|-- Makefile
-|-- dhcdp/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (DHCP client source files)
-|-- dhcpd/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (DHCP server source files)
-|-- ftpc/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (FTP client source files)
-|-- ftpd/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (FTP server source files)
-|-- resolv/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (resolv source files)
-|-- resolv/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (resolv source files)
-|-- smtp/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (smtp source files)
-|-- telnetd/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (Telnet client source files)
-|-- tftpc/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (TFTP client source files)
-|-- thttpd/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (thttpd HTTP server source files)
-|-- netlib/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (netlib source files)
-|-- weblclient/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (webclient source files)
-|-- webserver/
-|   |-- Kconfig
-|   |-- Make.defs
-|   `-- (uIP webserver source files)
-`-- (netutils common files)
-
      - -

      2.18 apps/nshlib

      -

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

      - -

      2.19 apps/examples

      -

      - Example and test programs to build against. -

      - - - - - -
      -

      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 configs/<board-name>/[<config-dir>/]Make.defs to ${TOPDIR}/Make.defs,
      • -
      • Copy configs/<board-name>/[<config-dir>/]setenv.sh to ${TOPDIR}/setenv.sh, and
        • -
      • Copy configs/<board-name>/[<config-dir>/]defconfig to ${TOPDIR}/.config
        • -
      - -

      - Where <board-name> is the name of one of the sub-directories of the - NuttX configs/ 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. -

      -

      - Automated Configuration. - There is a script that automates these steps. The following steps will - accomplish the same configuration: -

      -
        -  cd tools
-  ./configure.sh <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: -

      -
        -  cd tools
-  configure.bat <board-name>[\<config-dir>]
-
      -

      - See tools/README.txt for more information about these scripts. -

      - -

      - If your application directory is not in the standard location (../apps or ../apps-<version>), - then you should also specify the location of the application directory on the command line like: -

      -
        -  cd tools
-  ./configure.sh -a <app-dir> <board-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:
-        -d
-                Enable script debug
-        -h
-                show this help message and exit
-        -v <major.minor>
-                The NuttX version number expressed 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}
-source ./setenv.sh
-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.
        • -
      • The makefile fragment Make.defs that provides customized build targets, and
        • -
      • The shell script setenv.sh that sets up the configuration environment for the build.
        • -
      -

      -The setenv.sh contains Linux/Cygwin environmental settings that are needed for the build. -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. -The setenv.sh only needs to be source'ed at the beginning of a session. -The system can be re-made subsequently by just typing make. -

      -

      - 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}/configs/<board-name>/include at ${TOPDIR}/include/arch/board.
        • -
      • Creating a link to ${TOPDIR}/configs/<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//include//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/arch.h. - These board_ definitions provide the interface between the board-level logic and the architecture-specific logic. -

        -

        - There is also a configs//include/board.h header file that can be used to communicate other board-specific information between the architecture logic and even application logic. - Any definitions which are common between a single architecture and several boards should go in this board.h header file; - include/nuttx/arch.his reserved for board-related definitions common to all architectures. -

        -
      • -

        - 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 configs//src/.h and should not be used outside of that directory since board-specific definitions have no meaning outside of the board directory. -

        • -
      - -

      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 task_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 most be - stopped, its context saved and moved into one of the - waiting task lists. It it was the task at the head - of the ready-to-run list, then a context 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 _exit()

      -

      Function Prototype: void _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 uint8_t *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. -
      -

      - This API is NOT required if CONFIG_DISABLE_SIGNALS - is defined. -

      - -

      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 - (irqsave() 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 - (irqrestore() 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 System Time and Clock

      - -

      4.3.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.3.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_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_rtcinitialize(). - Initialize the hardware RTC per the selected configuration. - This function is called once during the OS initialization sequence -
        • -
      • 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.3.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.3.4 Tickless OS

      -

      4.3.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.3.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.3.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/Cywgin 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_systimer() 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 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.3.4.4 Tickless Imported Intefaces

      -

      - 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: -

      -
        -
      • - up_timer_initialize(): - Initializes the timer facilities. Called early in the intialization sequence (by up_intialize()). -
        • -
      • - 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.3.4.4.1 up_timer_initialize()
      -

      Function Prototype:

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

      Description:

      -
        - Initializes all platform-specific timer facilities. This function is called early in the initialization sequence by up_intialize(). 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.3.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 up_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 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.3.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. sched_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. iterrupts may need to be disabled internally to assure non-reentrancy. -
      - -
      4.3.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. sched_timer_expiration() will be called when the alarm occurs (unless up_alaram_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 sched_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.3.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. sched_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 sched_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. iterrupts may need to be disabled internally to assure non-reentrancy. -
      - -
      4.3.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. sched_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 sched_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.3.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.3.5.1 wd_create/wd_static

      - -

      -Function Prototype: -

      -    #include <nuttx/wdog.h>
-    WDOG_ID wd_create(void);
-    void wd_static(FAR struct wdog_s *wdog);
-
      - -

      -Description: The wd_create() function will create a timer by allocating the appropriate resources for the watchdog. The wd_create() function returns a pointer to a fully initialized, dynamically allocated struct wdog_s instance (which is typedef'ed as WDOG_ID); -

      -

      -wd_static() performs the equivalent initialization of a statically allocated struct wdog_s instance. No allocation is performed in this case. The initializer definition, WDOG_INITIALIZER is also available for initialization of static instances of struct wdog_s. NOTE: wd_static() is also implemented as a macro definition. -

      -

      -Input Parameters: None. -

      -Returned Value: -

        -
      • Pointer to watchdog that may be used as a handle in subsequent NuttX calls (i.e., the watchdog ID), or NULL if insufficient resources are available to create the watchdogs. -
      - -

      -Assumptions/Limitations: -

      - POSIX Compatibility: This is a NON-POSIX interface. -VxWorks provides the following comparable interface: -

      -    WDOG_ID wdCreate (void);
-
      - -

      -Differences from the VxWorks interface include: -

        -
      • The number of available watchdogs is fixed (configured at -initialization time). -
      - -

      4.3.5.2 wd_delete

      - -

      -Function Prototype: -

      -    #include <nuttx/wdog.h>
-    int wd_delete(WDOG_ID wdog);
-
      - -

      -Description: The wd_delete function will deallocate a watchdog timer previously allocated via wd_create(). The watchdog timer will be removed from the timer queue if has been started. -

      -

      -This function need not be called for statically allocated timers (but it is not harmful to do so). -

      -Input Parameters: -
        -
      • wdog. The watchdog ID to delete. This is actually a -pointer to a watchdog structure. -
      - -

      -Returned Value: -

        -
      • OK or ERROR -
      - -

      -Assumptions/Limitations: It is the responsibility of the -caller to assure that the watchdog is inactive before deleting -it. -

      -POSIX Compatibility: This is a NON-POSIX interface. -VxWorks provides the following comparable interface: -

      -    STATUS wdDelete (WDOG_ID wdog);
-
      - -

      -Differences from the VxWorks interface include: -

        -
      • Does not make any checks to see if the watchdog is being used -before deallocating it (i.e., never returns ERROR). -
      - -

      4.3.5.3 wd_start

      - -

      -Function Prototype: -

      -    #include <nuttx/wdog.h>
-    int wd_start(WDOG_ID wdog, int delay, wdentry_t wdentry,
-                 int argc, ....);
-
      - -

      -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 -
      • argc. The number of uint32_t parameters to pass to wdentry. -
      • .... uint32_t size parameters to pass to wdentry -
      - -

      -Returned Value: -

        -
      • OK or ERROR -
      - -

      -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.3.5.4 wd_cancel

      -

      -Function Prototype: -

      -    #include <nuttx/wdog.h>
-    int wd_cancel(WDOG_ID 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.3.5.5 wd_gettime

      -

      - Function Prototype: -

      -
      -    #include <nuttx/wdog.h>
-    Sint wd_gettime(WDOG_ID 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.3.5.6 Watchdog Timer Callback

      -

      - When a watchdog expires, the callback function with this type is called: -

      -
      -    typedef void (*wdentry_t)(int argc, ...);
-
      -

      - Where argc is the number of wdparm_t type arguments that follow. -

      -

      - The arguments are 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. -

      -
        -union wdparm_u
-{
-  FAR void     *pvarg; /* The size one generic point */
-  uint32_t      dwarg; /* Big enough for a 32-bit value in any case */
-  uintptr_t     uiarg; /* sizeof(uintptr_t) >= sizeof(pointer) */
-};
-
-#if UINTPTR_MAX >= UINT32_MAX
-typedef uintptr_t wdparm_t;
-#else
-typedef uint32_t  wdparm_t;
-#endif
-
      - -

      4.4 Work Queues

      -

      Work Queues. - NuttX provides work queues. Work queues are threads the service a queue of work items to be performed. There are useful for off-loading work to a different threading context, for delayed processing, or for serializing activities. -

      - -

      4.4.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 the common work queue interface are described in the following paragraphs. -

      - -

      4.4.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 higher 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). -

      -

      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 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 prioirity work queue. -
        • -
      • CONFIG_SCHED_HPWORKPRIORITY. - The execution priority of the high-priority worker thread. Default: 224 -
        • -
      • CONFIG_SCHED_HPWORKPERIOD. - How often the worker thread re-checks for work in units of microseconds. This work period is really only necessary if the the high priority thread is performing periodic garbage collection. The worker thread will be awakened immediately with it is queued work to be done. If the high priority worker thread is performing garbage collection, then the default is 50*1000 (50 MS). Otherwise, if the lower priority worker thread is performing garbage collection, the default is 100*1000. -
      • 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.4.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 inapproperiate to serve as a driver bottom half. The lower priority work queue has the other advantages, however, that make it better suited for some tasks: -

      -
        -
      • -

        Priority Inheritance. - The lower priority worker thread(s) support priority inheritance (if 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. -

        -
        • -
      • -

        - Thread Pool. - The low-priority work queue can be configured to support multiple, low-priority threads. This is essentially a thread pool that provides multi-threaded servicing of the low-priority work thread. This breaks the strict serialization of the "queue" (and hence, the low-priority 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 low-priority queue processing would stall in such cases. Such behavior is necessary to support asynchronous I/O, AIO, for example. -

        -
        • -
      -

      - 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 thread 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 exceedCONFIG_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_LPWORKPERIOD. - How often the lower priority worker thread checks for garbage collection in units of microseconds. Default: 50*1000 (50 MS). -
        • -
      • CONFIG_SCHED_LPWORKSTACKSIZE. - The stack size allocated for the lower priority worker thread. Default: 2048. -
        • -
      - -

      4.4.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_USRWORKPERIOD - How often the lower priority worker thread is awakened in units of microseconds. Default: 100*1000 (100 MS). -
      • CONFIG_LIB_USRWORKSTACKSIZE. - The stack size allocated for the lower priority worker thread. Default: 2048. -
      - -

      4.4.2 Common Work Queue Interfaces

      -

      4.4.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.4.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 subjec 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.4.2.3 Work Queue Interfaces

      -
      4.4.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 by caller, but completely managed by the work queue logic. The caller should never modify the contents of the work queue structure; the caller should not call work_queue() again until either (1) the previous work has been performed and removed from the queue, or (2) work_cancel() has been called to cancel the work and remove it from the work queue. -

      -

      - 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.4.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.4.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.4.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.4.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.4.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.4.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.5 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 evironment 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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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 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.5.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 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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.6 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 not 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 to to indicate the nature of the 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 os_start()

      -

      - To be provided -

      - -

      4.7.2 OS List Management APIs

      -

      - To be provided -

      - -

      4.7.3 sched_process_timer()

      -

      Function Prototype: void sched_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 - MSEC_PER_TICK. -

      - -

      4.7.4 sched_timer_expiration()

      -

      Function Prototype:

      -

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

      Description:

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

      Input Parameters:

      -
        - None -
      -

      Returned Value:

      -
        - None -
      -

      Assumptions:

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

      4.7.5 sched_alaram_expiration()

      -

      Function Prototype:

      -

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

      Description:

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

      Input Parameters:

      -
        - None -
      -

      Returned Value:

      -
        - None -
      -

      Assumptions:

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

      4.7.6 irq_dispatch()

      -

      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 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.8.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.8.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.9 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.10 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.10.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.10.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.10.3 Common LED interfaces

      - -

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

      -
        -#ifdef CONFIG_ARCH_LEDS
-void board_led_initialize(void);
-void board_led_on(int led);
-void board_led_off(int led);
-#else
-# define board_led_initialize()
-# define board_led_on(led)
-# define board_led_off(led)
-#endif
-
      -

      - Where: -

      -

        -
      • -

        - void board_led_initialize(void) is called early in power-up initialization to initialize the LED hardware. -

        -
        - NOTE: In most architectures, board_led_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 nott, 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 instted use the naming conventions for microprocessor-specific interfaces or the board-specific interfaces (such as stm32_led_initialize()). -
        -
        • -
      • -

        - board_led_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_led_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. -

        -
        • -
      - - - - - -
      -

      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. - Or, a simple in-memory, pseudo file system can be enabled. - This simple file system can be enabled setting the CONFIG_NFILE_DESCRIPTORS - option to a non-zero value (see Appendix A). - 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 requires that the in-memory, pseudo file system - is enabled by setting the CONFIG_NFILE_DESCRIPTORS in the NuttX configuration file to a - non-zero value. -

      - -

      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/chip/lm_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/<chip> directory for the processor architectures that have build in touchscreen controllers or (2) the configs/<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/<chip> 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/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/<chip> 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 reside at include/nuttx/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/<chip> directory for the specific processor <architecture> and for the specific <chip> CAN peripheral devices. -
        • -
      - -

      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/<chip> 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/<chip> 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/<chip> 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/<chip> 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 uIP 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, enum spi_dev_e 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, enum spi_dev_e devid);
          - uint16_t send(FAR struct spi_dev_s *dev, uint16_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: -

          -

          uint32_t setfrequency(FAR struct i2c_dev_s *dev, uint32_t frequency);
          - int setaddress(FAR struct i2c_dev_s *dev, int addr, int nbits);
          - int write(FAR struct i2c_dev_s *dev, const uint8_t *buffer, int buflen);
          - int read(FAR struct i2c_dev_s *dev, uint8_t *buffer, int buflen);

          -

          -
        -
      • -

        - 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_dev_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/nokia6100.c, drivers/lcd/p14201.c, configs/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);
          - uint8_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 (*recvR1)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R1);
          - int (*recvR2)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t R2[4]);
          - int (*recvR3)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R3);
          - int (*recvR4)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R4);
          - int (*recvR5)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R5);
          - int (*recvR6)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R6);
          - int (*recvR7)(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: -

        -
          -

          bool (*dmasupported)(FAR struct sdio_dev_s *dev);
          - 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/lpc17_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 configs/nucleus2g/src/up_nsh.c and - the function nsh_waiter() in the file configs/olimex-lpc1766stk/src/up_nsh.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/lpc17_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.4 Power Management

      - -

      6.4.1 Overview

      -

      - NuttX supports a simple power management (PM) sub-system. This sub-system: -

      -
        -
      • -

        - Monitors driver activity, 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. -

        -
        • -
      -

      - 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 - somethat 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. -

      - -

      6.4.2 Interfaces

      -

      - All PM interfaces are declared in the file include/nuttx/power/pm.h. -

      - -

      6.4.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 initialize (since they may attempt to register with the power management subsystem). -

      -

      Input Parameters: -None -

      -

      Returned Value: -None -

      - -

      6.4.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.4.2.3 pm_activity()

      -

      Function Prototype:

      -
        -#include <nuttx/power/pm.h>
-void pm_activity(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: -

      -
      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.4.2.4 pm_checkstate()

      -

      Function Prototype:

      -
        -#include <nuttx/power/pm.h>
-enum pm_state_e pm_checkstate(void);
-
      -

      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: - None -

      -

      Returned Value: - The recommended power management state. -

      - -

      6.4.2.5 pm_changestate()

      -

      Function Prototype:

      -
        -#include <nuttx/power/pm.h>
- int pm_changestate(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: -

      -
      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.4.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.4.3.1 prepare()

      -

      Function Prototype:

      -
        -int (*prepare)(FAR struct pm_callback_s *cb, 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. -
      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.4.3.1 notify()

      -

      Function Prototype:

      -
        -#include <nuttx/power/pm.h>
-void (*notify)(FAR struct pm_callback_s *cb, 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. -
      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 70d8a6c7fa..0000000000 --- a/Documentation/NuttxUserGuide.html +++ /dev/null @@ -1,10157 +0,0 @@ - - - -NuttX Users Manual - - - - -
      - - - - -
      -

      NuttX Operating System

      User's Manual

      -

      by

      -

      Gregory Nutt

      -

      Last Updated: June 12, 2015

      -
      -
      - - - - - -
      -

      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: -

      -
        -
      • tasks are threads which have a degree of independence -
      • pthreads share some resources. -
      -

      - 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: -

      - -

      - 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: -

        -#include <sched.h>
-int task_create(char *name, int priority, int stack_size, main_t entry, char * const argv[]);
-
      - -

      -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: -

        -
      • name. Name of the new task
        • -
      • priority. Priority of the new task
        • -
      • stack_size. size (in bytes) of the stack needed
        • -
      • entry. Entry point of a new task
        • -
      • argv. A pointer to an array of input parameters. Up to - CONFIG_MAX_TASK_ARG parameters may be provided. - If fewer than CONFIG_MAX_TASK_ARG parameters are - passed, the list should be terminated with a NULL argv[] value. - If no parameters are required, argv may be NULL. -
      -

      - Returned Value: -

      -
        -
      • - Returns the non-zero task ID of the new task or - ERROR if memory is insufficient or the task cannot be - created (errno is not set). -
        • -
      - -

      -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: -

      -
        -
      • Interface name -
      • Various differences in types of arguments -
      • There is no options argument. -
      • A variable number of parameters can be passed to a task (VxWorks supports ten). -
      - -

      2.1.2 task_init

      - -

      -Function Prototype: -

      -   #include <sched.h>
-   int task_init(struct tcb_s *tcb, char *name, int priority, uint32_t *stack, uint32_t stack_size,
-                 maint_t entry, char * const argv[]);
-
      - -

      -Description: -

      - This function initializes a Task Control Block (TCB) - in preparation for starting a new thread. It performs a subset - of the functionality of task_create() (see above). -

      -

      - Unlike task_create(), task_init() does not activate the task. - This must be done by calling task_activate(). -

      -

      -Input Parameters: -

        -
      • tcb. Address of the new task's TCB -
      • name. Name of the new task (not used) -
      • priority. Priority of the new task -
      • stack. Start of the pre-allocated stack -
      • stack_size. size (in bytes) of the pre-allocated stack -
      • entry. Entry point of a new task -
      • argv. A pointer to an array of input parameters. Up to - CONFIG_MAX_TASK_ARG parameters may be provided. - If fewer than CONFIG_MAX_TASK_ARG parameters are - passed, the list should be terminated with a NULL argv[] value. - If no parameters are required, argv may be NULL. -
      -

      -

      -Returned Value: -

      -
        -

      • OK, or ERROR if the task cannot be initialized.

        -

        This function can only failure is it is unable to assign - a new, unique task ID to the TCB (errno is not set).

        -
      -

      -Assumptions/Limitations: -

        -
      • task_init() is provided to support internal OS functionality. It is -not recommended for normal usage. task_create() is the preferred -mechanism to initialize and start a new task. -
      -

      -POSIX Compatibility: This is a NON-POSIX interface. -VxWorks provides the following similar interface: -

      -   STATUS taskInit(WIND_TCB *pTcb, char *name, int priority, int options, uint32_t *pStackBase, 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_init() differs from VxWorks' taskInit() in the - following ways: -

      -
        -
      • Interface name -
      • Various differences in types or arguments -
      • There is no options argument. -
      • A variable number of parameters can be passed to a task (VxWorks supports ten). -
      - -

      2.1.3 task_activate

      - -

      -Function Prototype: -

      -    #include <sched.h>
-    int task_activate(struct tcb_s *tcb);
-
      - -

      -Description: This function activates tasks created by task_init(). -Without activation, a task is ineligible for execution by the -scheduler. -

      -Input Parameters: -

        -
      • tcb. The TCB for the task for the task (same as the -task_init argument). -
      - -

      -Returned Value: -

        -
      • OK, or ERROR if the task cannot be activated (errno is not set). -
      - -

      -Assumptions/Limitations: -

        -
      • task_activate() is provided to support internal OS functionality. It is -not recommended for normal usage. task_create() is the preferred -mechanism to initialize and start a new task. -
      -

      -POSIX Compatibility: This is a NON-POSIX interface. -VxWorks provides the following similar interface: -

      -    STATUS taskActivate(int tid);
-
      - -

      - The NuttX task_activate() differs from VxWorks' taskActivate() in the - following ways: -

      -
        -
      • Function name -
      • With VxWork's taskActivate, the pid argument is supposed to be -the pointer to the WIND_TCB cast to an integer. -
      - -

      2.1.4 task_delete

      - -

      -Function Prototype: -

        -#include <sched.h>
-int task_delete(pid_t pid);
-
      - -

      - 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(). -

      -Input Parameters: -

        -
      • - pid. - The task ID of the task to delete. - An ID of zero signifies the calling task. - Any attempt by the calling task will be automatically re-directed to exit(). -
      -

      -Returned Value: -

        -
      • - OK, or ERROR if the task cannot be deleted. - This function can fail if the provided pid does not correspond to a task (errno is not set). -
        • -
      -

      -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: -

      -
        -STATUS taskDelete(int tid);
-
      - -

      - The NuttX task_delete() differs from VxWorks' taskDelete() in - the following ways: -

      -
        -
      • No support is provided for calling the tasks deletion routines (because the VxWorks taskDeleteHookAdd() is not supported). - However, if atexit() or on_exit support is enabled, those will be called when the task deleted. -
      • Deletion of self is supported, but only because task_delete() will re-direct processing to exit(). -
      - -

      2.1.5 task_restart

      -

      -Function Prototype: -

        -#include <sched.h>
-int task_restart(pid_t pid);
-
      -

      - 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: -

        -
      • pid. - The task ID of the task to delete. - An ID of zero would signify the calling task (However, support for a task to restart itself has not been implemented). -
      -

      -Returned Value: -

        -
      • - OK, or ERROR if the task ID is invalid or the task could - not be restarted. - This function can fail if: - (1) A pid of zero or the pid of the calling task is provided (functionality not implemented) - (2) The pid is not associated with any task known to the system. -
        • -
      -

      -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: -

      -
        -
      • - Restart of the currently running task is not supported by NuttX. -
        • -
      • - The VxWorks description says that the ID, priority, etc. take - the value that they had when the task was terminated. -
        • -
      - -

      2.1.6 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: -

        -
      • code. (ignored) -
      - -

      -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: -

      -
        -
      • The code parameter is ignored. -
      - -

      2.1.7 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: -

        -
      • The task ID of the calling task. -
      - -

      -Assumptions/Limitations: -

      -POSIX Compatibility: -Compatible with the POSIX interface of the same name. -

      - -

      2.1.8 vfork

      -

      - Function Prototype: -

      - 
        -#include <unistd.h>
-pid_t vfork(void);
-
      -

      - 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 Unix interface of the same name. -

      - -

      2.1.9 execv

      -

      - Function Prototype: -

      - 
        -#include <unistd.h>
-#ifdef CONFIG_LIBC_EXECFUNCS
-int execv(FAR const char *path, FAR char *const argv[]);
-#endif
-
      -

      - 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 Unix 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: -

      -
        -
      • - CONFIG_LIBC_EXECFUNCS: - Enable execv() and execl() support -
        • -
      • - CONFIG_EXECFUNCS_SYMTAB: - Symbol table used by execv() or execl(). -
        • -
      • - CONFIG_EXECFUNCS_NSYMBOLS: - Number of symbols in the symbol table -
        • -
      -

      - 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: -

      -
        -
      • - path: - The path to the program to be executed. - If CONFIG_BINFMT_EXEPATH is defined in the configuration, then this may be a relative path from the current working directory. - Otherwise, path must be the absolute path to the program. -
      • -
        • - argv: - A pointer to an array of string arguments. - The end of the array is indicated with a NULL entry. - -
      -

      - 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 Unix interface of the same name. - There are, however, several compatibility issues as detailed in the description above. -

      - -

      2.1.10 execl

      -

      - Function Prototype: -

      - 
        -#include <unistd.h>
-#ifdef CONFIG_LIBC_EXECFUNCS
-int execl(FAR const char *path, ...);
-#endif
-
      -

      - Description: - execl() is functionally equivalent to execv(), differing only in the form of its input parameters. - See the decription of execv() for additional information. -

      -

      - Input Parameters: -

      -
        -
      • - path: - The path to the program to be executed. - If CONFIG_BINFMT_EXEPATH is defined in the configuration, then this may be a relative path from the current working directory. - Otherwise, path must be the absolute path to the program. -
      • -
        • - ...: - A list of the string arguments to be recevied by the program. - Zero indicates the end of the list. - -
      -

      - 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 Unix interface of the same name. - There are, however, several compatibility issues as detailed in the description of execv(). -

      - -

      2.1.11 posix_spawn and posix_spawnp

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawn(FAR pid_t *pid, FAR const char *path,
-      FAR const posix_spawn_file_actions_t *file_actions,
-      FAR const posix_spawnattr_t *attr,
-      FAR char *const argv[], FAR char *const envp[]);
-int posix_spawnp(FAR pid_t *pid, FAR const char *file,
-      FAR const posix_spawn_file_actions_t *file_actions,
-      FAR const posix_spawnattr_t *attr,
-      FAR char *const argv[], FAR char *const envp[]);
-
      -

      - Description: - The posix_spawn() and posix_spawnp() functions will create a new, child task, constructed from a regular executable file. -

      -

      - Input Parameters: -

      -
        -
      • -

        - pid: - Upon successful completion, posix_spawn() and posix_spawnp() will return the task ID of the child task to the parent task, in the variable pointed to by a non-NULL pid argument. - If the pid argument is a null pointer, the process ID of the child is not returned to the caller. -

        -
        • -
      • -

        - path or file: - The path argument to posix_spawn() is the absolute path that identifies the file to execute. - The file argument to posix_spawnp() may also be a relative path and will be used to construct a pathname that identifies the file to execute. - In the case of a relative path, the path prefix for the file will be obtained by a search of the directories passed as the environment variable PATH. -

        -

        - NOTE: NuttX provides only one implementation: - If CONFIG_BINFMT_EXEPATH is defined, then only posix_spawnp() behavior is supported; otherwise, only posix_spawn behavior is supported. -

        • -
      • -

        - file_actions: - If file_actions is a null pointer, then file descriptors open in the calling process will remain open in the child process (unless CONFIG_FDCLONE_STDIO is defined). - If file_actions is not NULL, then the file descriptors open in the child process will be those open in the calling process as modified by the spawn file actions object pointed to by file_actions. -

        -
        • -
      • -

        - attr: - If the value of the attr parameter is NULL, the all default values for the POSIX spawn attributes will be used. - Otherwise, the attributes will be set according to the spawn flags. - The posix_spawnattr_t spawn attributes object type is defined in spawn.h. - It will contains these attributes, not all of which are supported by NuttX: -

        -
          -
        • - POSIX_SPAWN_SETPGROUP: - Setting of the new task's process group is not supported. - NuttX does not support process groups. -
          • -
        • - POSIX_SPAWN_SETSCHEDPARAM: - Set new tasks priority to the sched_param value. -
          • -
        • - POSIX_SPAWN_SETSCHEDULER: - Set the new task's scheduler policy to the sched_policy value. -
          • -
        • - POSIX_SPAWN_RESETIDS - Resetting of the effective user ID of the child process is not supported. - NuttX does not support effective user IDs. -
          • -
        • - POSIX_SPAWN_SETSIGMASK: - Set the new task's signal mask. -
          • -
        • - POSIX_SPAWN_SETSIGDEF: - Resetting signal default actions is not supported. - NuttX does not support default signal actions. -
          • -
        -
        • -
      • -

        - argv: - argv[] is the argument list for the new task. argv[] is an array of pointers to null-terminated strings. - The list is terminated with a null pointer. -

        -
        • -
      • -

        - envp: - The envp[] argument is not used by NuttX and may be NULL. - In standard implementations, envp[] is an array of character pointers to null-terminated strings that provide the environment for the new process image. - The environment array is terminated by a null pointer. - In NuttX, the envp[] argument is ignored and the new task will inherit the environment of the parent task unconditionally.

        -
        • -
      -

      - 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: -

      -
        -
      • - EINVAL: - The value specified by file_actions or attr is invalid. -
        • -
      • - Any errors that might have been return if vfork() and excec[l|v]() had been called. -
        • -
      -

      - Assumptions/Limitations: -

      -
        -
      • - NuttX provides only posix_spawn() or posix_spawnp() behavior depending upon the setting of CONFIG_BINFMT_EXEPATH: - If CONFIG_BINFMT_EXEPATH is defined, then only posix_spawnp() behavior is supported; otherwise, only posix_spawn() behavior is supported. -
        • -
      • - The envp argument is not used and the environ variable is not altered (NuttX does not support the environ variable). -
        • -
      • - Process groups are not supported (See POSIX_SPAWN_SETPGROUP above). -
        • -
      • - Effective user IDs are not supported (See POSIX_SPAWN_RESETIDS above). -
        • -
      • - Signal default actions cannot be modified in the newly task executed because NuttX does not support default signal actions (See POSIX_SPAWN_SETSIGDEF). -
        • -
      -

      - 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.12 posix_spawn_file_actions_init

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawn_file_actions_init(FAR posix_spawn_file_actions_t *file_actions);
-
      -

      - 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: -

      -
        -
      • - file_actions: - The address of the posix_spawn_file_actions_t to be initialized. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h>. -

      - -

      2.1.13 posix_spawn_file_actions_destroy

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawn_file_actions_destroy(FAR posix_spawn_file_actions_t *file_actions);
-
      -

      - 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: -

      -
        -
      • - file_actions: - The address of the posix_spawn_file_actions_t to be destroyed. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.14 posix_spawn_file_actions_addclose

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawn_file_actions_addclose(FAR posix_spawn_file_actions_t *file_actions, int fd);
-
      -

      - 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: -

      -
        -
      • - file_actions: - The address of the posix_spawn_file_actions_t object to which the close operation will be appended. -
        • -
      • - fd: - The file descriptor to be closed. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.15 posix_spawn_file_actions_adddup2

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawn_file_actions_adddup2(FAR posix_spawn_file_actions_t *file_actions, int fd1, int fd2);
-
      -

      - 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: -

      -
        -
      • - file_actions: - The address of the posix_spawn_file_actions_t object to which the dup2 operation will be appended. -
        • -
      • - fd1: - The file descriptor to be be duplicated. - The first file descriptor to be argument to dup2(). -
        • -
      • - fd2: - The file descriptor to be be created. - The second file descriptor to be argument to dup2(). -
        • -
      -

      - 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_addopen

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawn_file_actions_addopen(FAR posix_spawn_file_actions_t *file_actions,
-      int fd, FAR const char *path, int oflags, mode_t mode);
-
      -

      - 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: -

      -
        -
      • - file_actions: - The address of the posix_spawn_file_actions_t object to which the open operation will be appended. -
        • -
      • - fd: - The file descriptor to be opened. -
        • -
      • - path: - The path to be opened. -
        • -
      • - oflags: - Open flags. -
        • -
      • - mode: - File creation mode/ -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.17 posix_spawnattr_init

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawnattr_init(FAR posix_spawnattr_t *attr);
-
      -

      - 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: -

      -
        -#define posix_spawnattr_destroy(attr) (0)
-
      -

      - For portability, the convention of calling posix_spawnattr_destroyed() when the attributes are not longer needed should still be followed. -

      -

      - Input Parameters: -

      -
        -
      • - attr: - The address of the spawn attributes to be initialized. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.18 posix_spawnattr_getflags

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawnattr_getflags(FAR const posix_spawnattr_t *attr, FAR short *flags);
-
      -

      - Description: - The posix_spawnattr_getflags() function will obtain the value of the spawn-flags attribute from the attributes object referenced by attr. -

      -

      - Input Parameters: -

      -
        -
      • - attr: - The address spawn attributes to be queried. -
        • -
      • - flags: - The location to return the spawn flags -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.19 posix_spawnattr_getschedparam

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawnattr_getschedparam(FAR const posix_spawnattr_t *attr, FAR struct sched_param *param);
-
      -

      - Description: - The posix_spawnattr_getschedparam() function will obtain the value of the spawn-schedparam attribute from the attributes object referenced by attr. -

      -

      - Input Parameters: -

      -
        -
      • - attr: - The address spawn attributes to be queried. -
        • -
      • - param: - The location to return the spawn-schedparam value. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.20 posix_spawnattr_getschedpolicy

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawnattr_getschedpolicy(FAR const posix_spawnattr_t *attr, FAR int *policy);
-
      -

      - Description: - The posix_spawnattr_getschedpolicy() function will obtain the value of the spawn-schedpolicy attribute from the attributes object referenced by attr. -

      -

      - Input Parameters: -

      -
        -
      • - attr: - The address spawn attributes to be queried. -
        • -
      • - policy: - The location to return the spawn-schedpolicy value. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.21 posix_spawnattr_getsigmask

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-#ifndef CONFIG_DISABLE_SIGNALS
-int posix_spawnattr_getsigmask(FAR const posix_spawnattr_t *attr, FAR sigset_t *sigmask);
-#endif
-
      -

      - Description: - The posix_spawnattr_getsigdefault() function will obtain the value of the spawn-sigmask attribute from the attributes object referenced by attr. -

      -

      - Input Parameters: -

      -
        -
      • - attr: - The address spawn attributes to be queried. -
        • -
      • - sigmask: - The location to return the spawn-sigmask value. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.22 posix_spawnattr_setflags

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawnattr_setflags(FAR posix_spawnattr_t *attr, short flags);
-
      -

      - Description: - The posix_spawnattr_setflags() function will set the spawn-flags attribute in an initialized attributes object referenced by attr. -

      -

      - Input Parameters: -

      -
        -
      • - attr: - The address spawn attributes to be used. -
        • -
      • - flags: - The new value of the spawn-flags attribute. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.23 posix_spawnattr_setschedparam

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawnattr_setschedparam(FAR posix_spawnattr_t *attr, FAR const struct sched_param *param);
-
      -

      - Description: - The posix_spawnattr_setschedparam() function will set the spawn-schedparam attribute in an initialized attributes object referenced by attr. -

      -

      - Input Parameters: -

      -
        -
      • - attr: - The address spawn attributes to be used. -
        • -
      • - param: - The new value of the spawn-schedparam attribute. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.24 posix_spawnattr_setschedpolicy

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawnattr_setschedpolicy(FAR posix_spawnattr_t *attr, int policy);
-
      -

      - Description: - The posix_spawnattr_setschedpolicy() function will set the spawn-schedpolicy attribute in an initialized attributes object referenced by attr. -

      -

      - Input Parameters: -

      -
        -
      • - attr: - The address spawn attributes to be used. -
        • -
      • - policy: - The new value of the spawn-schedpolicy attribute. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.25 posix_spawnattr_setsigmask

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-#ifndef CONFIG_DISABLE_SIGNALS
-int posix_spawnattr_setsigmask(FAR posix_spawnattr_t *attr, FAR const sigset_t *sigmask);
-#endif
-
      -

      - Description: - The posix_spawnattr_setsigmask() function will set the spawn-sigmask attribute in an initialized attributes object referenced by attr. -

      -

      - Input Parameters: -

      -
        -
      • - attr: - The address spawn attributes to be used. -
        • -
      • - sigmask: - The new value of the spawn-sigmask attribute. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.26 task_spawn

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int task_spawn(FAR pid_t *pid, FAR const char *name, main_t entry,
-      FAR const posix_spawn_file_actions_t *file_actions,
-      FAR const posix_spawnattr_t *attr,
-      FAR char *const argv[], FAR char *const envp[]);
-
      -

      - Description: - The task_spawn() function will create a new, child task, where the entry point to the task is an address in memory. -

      -

      -
        -
      • -

        - pid: - Upon successful completion, task_spawn() will return the task ID of the child task to the parent task, in the variable pointed to by a non-NULL pid argument. - If the pid argument is a null pointer, the process ID of the child is not returned to the caller. -

        -
        • -
      • -

        - name: - The name to assign to the child task. -

        -
        • -
      • -

        - entry: - The child task's entry point (an address in memory). -

        -
        • -
      • -

        - file_actions: - If file_actions is a null pointer, then file descriptors open in the calling process will remain open in the child process (unless CONFIG_FDCLONE_STDIO is defined). - If file_actions is not NULL, then the file descriptors open in the child process will be those open in the calling process as modified by the spawn file actions object pointed to by file_actions. -

        -
        • -
      • -

        - attr: - If the value of the attr parameter is NULL, the all default values for the POSIX spawn attributes will be used. - Otherwise, the attributes will be set according to the spawn flags. - The posix_spawnattr_t spawn attributes object type is defined in spawn.h. - It will contains these attributes, not all of which are supported by NuttX: -

        -
          -
        • - POSIX_SPAWN_SETPGROUP: - Setting of the new task's process group is not supported. - NuttX does not support process groups. -
          • -
        • - POSIX_SPAWN_SETSCHEDPARAM: - Set new tasks priority to the sched_param value. -
          • -
        • - POSIX_SPAWN_SETSCHEDULER: - Set the new task's scheduler policy to the sched_policy value. -
          • -
        • - POSIX_SPAWN_RESETIDS - Resetting of the effective user ID of the child process is not supported. - NuttX does not support effective user IDs. -
          • -
        • - POSIX_SPAWN_SETSIGMASK: - Set the new task's signal mask. -
          • -
        • - POSIX_SPAWN_SETSIGDEF: - Resetting signal default actions is not supported. - NuttX does not support default signal actions. -
          • -
        -

        - And the non-standard: -

        -
          -
        • - TASK_SPAWN_SETSTACKSIZE: - Set the stack size for the new task. -
          • -
        -
        • -
      • -

        - argv: - argv[] is the argument list for the new task. argv[] is an array of pointers to null-terminated strings. - The list is terminated with a null pointer. -

        -
        • -
      • -

        - envp: - The envp[] argument is not used by NuttX and may be NULL. -

        -
        • -
      -

      - 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.26 task_spawnattr_getstacksize

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int task_spawnattr_getstacksize(FAR const posix_spawnattr_t *attr, FAR size_t *stacksize);
-
      -

      - Description: - The task_spawnattr_getstacksize() function will obtain the value of the spawn-stacksize attribute from the attributes object referenced by attr. -

      -

      - Input Parameters: -

      -
        -
      • - attr: - The address spawn attributes to be queried. -
        • -
      • - policy: - The location to return the spawn-stacksize value. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.26 task_spawnattr_setstacksize

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int task_spawnattr_setstacksize(FAR posix_spawnattr_t *attr, size_t stacksize);
-
      -

      - Description: - The task_spawnattr_setstacksize() function will set the spawn-stacksize attribute in an initialized attributes object referenced by attr. -

      -

      - Input Parameters: -

      -
        -
      • - attr: - The address spawn attributes to be used. -
        • -
      • - policy: - The new value of the spawn-stacksize attribute. -
        • -
      -

      - Returned Value: - On success, this function returns 0; on failure it will return an error number from <errno.h> -

      - -

      2.1.12 posix_spawn_file_actions_init

      -

      - Function Prototype: -

      - 
        -#include <spawn.h>
-int posix_spawn_file_actions_init(FAR posix_spawn_file_actions_t *file_actions);
-
      -

      - 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: -

      -
        -
      • - file_actions: - The address of the posix_spawn_file_actions_t to be initialized. -
        • -
      -

      - 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 - scheduler. This 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. -

      -

      - 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, 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: -

      -
        -
      • - pid. - The task ID of the task. - If pid is zero, the priority of the calling task is set. -
        • -
      • - param. - A structure whose member sched_priority is the integer priority. - The range of valid priority numbers is from SCHED_PRIORITY_MIN through SCHED_PRIORITY_MAX. -
        • -
      -

      - Returned Value: - On success, sched_setparam() returns 0 (OK). - On error, -1 (ERROR) is returned, and errno is set appropriately. -

      -
        - -
      • - EINVAL. - The parameter param is invalid or does not make sense for the current scheduling policy. -
        • -
      • - EPERM. - The calling task does not have appropriate privileges. -
        • -
      • - ESRCH. - The task whose ID is pid could not be found. -
        • -
      -

      - Assumptions/Limitations: -

      -

      - POSIX Compatibility: - Comparable to the POSIX interface of the same name. - Differences from the full POSIX implementation include: -

      -
        -
      • The range of priority values for the POSIX call is 0 to 255.
        • -
      - -

      2.2.2 sched_getparam

      - -

      -Function Prototype: -

      -    #include <sched.h>
-    int sched_getparam (pid_t pid, struct sched_param *param);
-
      - -

      -Description: This function gets the scheduling priority -of the task specified by pid. -

      -Input Parameters: -

        -
      • - pid. The task ID of the task. - If pid is zero, the priority of the calling task is returned. -
        • -
      • - param. - A structure whose member sched_priority is the integer priority. - The task's priority is copied to the sched_priority element of this structure. -
        • -
      - -

      -Returned Value: -

        -
      • 0 (OK) if successful, otherwise -1 (ERROR). -
      - -

      -Assumptions/Limitations: -

      - POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.2.3 sched_setscheduler

      -

      - Function Prototype: -

      -
        -#include <sched.h>
-int sched_setscheduler (pid_t pid, int policy, const struct sched_param *param);
-
      -

      - Description: - sched_setscheduler() sets both the scheduling policyand 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: -

      -
        -
      • - pid. - The task ID of the task. - If pid is zero, the priority of the calling task is set. -
        • -
      • - policy. - Scheduling policy requested (either SCHED_FIFO or SCHED_RR). -
        • -
      • - param. - A structure whose member sched_priority is the integer priority. - The range of valid priority numbers is from SCHED_PRIORITY_MIN through SCHED_PRIORITY_MAX. -
        • -
      -

      - Returned Value: - On success, sched_setscheduler() returns OK (zero). On - error, ERROR (-1) is returned, and errno is set appropriately: -

      -
        -
      • EINVAL: The scheduling policy is not one of the recognized policies.
        • -
      • ESRCH: The task whose ID is pid could not be found.
        • -
      -

      - Assumptions/Limitations: -

      -

      - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

      - -

      2.2.4 sched_getscheduler

      -

      -Function Prototype: -

        -#include <sched.h>
-int sched_getscheduler (pid_t pid);
-
      -

      - 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: -

        -
      • pid. - The task ID of the task to query. - If pid is zero, the calling task is queried. -
        • -
      -

      -Returned Value: -

        -
      • - On success, sched_getscheduler() returns the policy for - the task (either SCHED_FIFO or SCHED_RR). - On error, ERROR (-1) is returned, and errno is set appropriately: -
          -
        • ESRCH: The task whose ID is pid could not be found.
          • -
        -
        • -
      -

      -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: -

        -
      • 0 (OK) or -1 (ERROR) -
      - -

      -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: -

        -
      • policy. Scheduling policy requested. -
      - -

      -Returned Value: -

        -
      • The maximum priority value or -1 (ERROR). -
      - -

      -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: -

        -
      • policy. Scheduling policy requested. -
      - -

      -Returned Value: -

        -
      • The minimum priority value or -1 (ERROR) -
      - -

      -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: -

      -
        -
      • pid. The task ID of the task. If pid is zero, the -priority of the calling task is returned. -
      • interval. A structure used to return the time slice. -
      - -

      - Returned Value: - On success, sched_rr_get_interval() returns OK (0). On - error, ERROR (-1) is returned, and errno is set to: -

      -
        -
      • EFAULT: Cannot copy to interval
        • -
      • EINVAL: Invalid pid.
        • -
      • ENOSYS: The system call is not yet implemented.
        • -
      • ESRCH: The process whose ID is pid could not be found.
        • -
      - -

      - Assumptions/Limitations: -

      - POSIX Compatibility: Comparable to the POSIX - interface of the same name. -

      - - - - - -
      -

      2.3 Task Control Interfaces

       -
      - -

      - Task Control Interfaces. -

      -
        -
      • -

        - Scheduler locking interfaces. - This non-standard interfaces are used to enable and disable pre-emption and to test is pre-emption is currently enabled. -

        - -
        • -
      • -

        - Task synchronization interfaces. - wait(), waitpid() or waitid() may be used to wait for termination of child tasks. -

        - -
      • -

        - Task Exit Hooks. - atexit() and on_exit() may be use to register callback functions that are executed when a task group terminates. - 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 task thread or any of the other pthreads within the task broup. - 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 the discussion of "Parent and Child Tasks," below. - See also the NuttX Threading Wiki page and the Tasks vs. Threads FAQ for additional information on tasks and threads in NuttX. -
        -

        - A task group terminates when the last thread within the group exits. -

        - -
        • -
      - -

      - 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. -

      -
        -
      • -

        - CONFIG_SCHED_HAVE_PARENT. - If this setting is defined, then it instructs NuttX to remember the task ID of the parent task when each new child task is created. - This support enables some additional features (such as SIGCHLD) and modifies the behavior of other interfaces. - For example, it makes waitpid() more standards complete by restricting the waited-for tasks to the children of the caller. -

        -
        • -
      • -

        - CONFIG_SCHED_CHILD_STATUS - If this option is selected, then the exit status of the child task will be retained after the child task exits. - This option should be selected if you require knowledge of a child process' exit status. - Without this setting, wait(), waitpid() or waitid() may fail. - For example, if you do: -

        -
          -
        1. - Start child task -
          2. -
        2. - Wait for exit status (using wait(), waitpid() or waitid()). -
          3. -
        -

        - This may fail because the child task may run to completion before the wait begins. - There is a non-standard work-around in this case: - The above sequence will work if you disable pre-emption using sched_lock() prior to starting the child task, then re-enable pre-emption with sched_unlock() after the wait completes. - This works because the child task is not permitted to run until the wait is in place. -

        -

        - The standard solution would be to enable CONFIG_SCHED_CHILD_STATUS. - In this case the exit status of the child task is retained after the child exits and the wait will successful obtain the child task's exit status whether it is called before the child task exits or not. -

        -
        • -
      • -

        - CONFIG_PREALLOC_CHILDSTATUS. - To prevent runaway child status allocations and to improve allocation performance, child task exit status structures are pre-allocated when the system boots. - This setting determines the number of child status structures that will be pre-allocated. - If this setting is not defined or if it is defined to be zero then a value of 2*MAX_TASKS is used. -

        -

        - Note that there cannot be more that CONFIG_MAX_TASKS tasks in total. - However, the number of child status structures may need to be significantly larger because this number includes the maximum number of tasks that are running PLUS the number of tasks that have exit'ed without having their exit status reaped (via wait(), waitpid() or waitid()). -

        -

        - Obviously, if tasks spawn children indefinitely and never have the exit status reaped, then you may have a memory leak! - (See Warning below) -

        -
        • -
      -

      - 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: -

      -
        -struct sigaction sa;
-
-sa.sa_handler = SIG_IGN;
-sa.sa_flags = SA_NOCLDWAIT;
-int ret = sigaction(SIGCHLD, &sa, NULL);
-
      - -

      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: -

        -
      • OK or ERROR. -
      - -

      -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: -

        -
      • OK or ERROR. -
      - -

      -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: -

        -
      • The current value of the lockCount. -
      - -

      -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: -

      -
        -
      • pid. The task ID of the thread to waid for
        • -
      • stat_loc. The location to return the exit status
        • -
      • options. ignored
        • -
      -

      - 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: -

      -
        -
      • - If pid is equal to (pid_t)-1), status is requested for any child process. - In this respect, waitpid() is then equivalent to wait(). -
        • -
      • - If pid is greater than 0, it specifies the process ID of a single child process for which status is requested. -
        • -
      • - If pid is 0, status is requested for any child process whose process group ID is equal to that of the calling process. -
        • -
      • - If pid is less than (pid_t)-1), status is requested for any child process whose process group ID is equal to the absolute value of pid. -
        • -
      -

      - 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: -

      -
        -
      • - WCONTINUED. - The waitpid() function will report the status of any continued child process specified by pid whose status has not been reported since it continued from a job control stop. -
        • -
      • - WNOHANG. - The waitpid() function will not suspend execution of the calling thread if status is not immediately available for one of the child processes specified by pid. -
        • -
      • - WUNTRACED. - The status of any child processes specified by pid that are stopped, and whose status has not yet been reported since they stopped, will also be reported to the requesting process. -
        • -
      -

      - 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. -

      -
        -
      • - WIFEXITED(stat_val). - Evaluates to a non-zero value if status was returned for a child process that terminated normally. -
        • -
      • - WEXITSTATUS(stat_val). - If the value of WIFEXITED(stat_val) is non-zero, this macro evaluates to the low-order 8 bits of the status argument that the child process passed to _exit() or exit(), or the value the child process returned from main(). -
        • -
      • - WIFSIGNALED(stat_val). - Evaluates to a non-zero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught (see >signal.h<). -
        • -
      • - WTERMSIG(stat_val). - If the value of WIFSIGNALED(stat_val) is non-zero, this macro evaluates to the number of the signal that caused the termination of the child process. -
        • -
      • - WIFSTOPPED(stat_val). - Evaluates to a non-zero value if status was returned for a child process that is currently stopped. -
        • -
      • - WSTOPSIG(stat_val). - If the value of WIFSTOPPED(stat_val) is non-zero, this macro evaluates to the number of the signal that caused the child process to stop. -
        • -
      • - WIFCONTINUED(stat_val). - Evaluates to a non-zero value if status was returned for a child process that has continued from a job control stop. -
        • -
      -

      - 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: -

      -
        -
      • - ECHILD. - The process specified by pid does not exist or is not a child of the calling process, or the process group specified by pid does not exist or does not have any member process that is a child of the calling process. -
        • -
      • - EINTR. - The function was interrupted by a signal. - The value of the location pointed to by stat_loc is undefined. -
        • -
      • - EINVAL. - The options argument is not valid. -
        • -
      - -

      - 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. -

      -

      -

        -
      • - If idtype is P_PID, waitid() will wait for the child with a process ID equal to (pid_t)id. -
        • -
      • - If idtype is P_PGID, waitid() will wait for any child with a process group ID equal to (pid_t)id. -
        • -
      • - If idtype is P_ALL, waitid() will wait for any children and id is ignored. -
      -

      - 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: -

      -
        -
      • - WEXITED: - Wait for processes that have exited. -
        • -
      • - WSTOPPED: - Status will be returned for any child that has stopped upon receipt of a signal. -
        • -
      • - WCONTINUES: - Status will be returned for any child that was stopped and has been continued. -
        • -
      • - WNOHANG: - Return immediately if there are no children to wait for. -
        • -
      • - WNOWAIT: - Keep the process whose status is returned in info in a waitable state. - This will not affect the state of the process; - the process may be waited for again after this call completes. -
        • -
      - 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: -

      -
        -
      • - ECHILD: -
        • - The calling process has no existing unwaited-for child processes. -
      • - EINTR: -
        • - The waitid() function was interrupted by a signal. -
      • - EINVAL: - An invalid value was specified for options, or idtype and id specify an invalid set of processes. -
        • -
      -

      - 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: -

      -
        -
      • stat_loc. The location to return the exit status
        • -
      -

      - 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: -

      -
        -
      • func. A pointer to the function to be called when the task exits.
        • -
      -

      - 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. - Limitiations 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: -

      -
        -
      • func. A pointer to the function to be called when the task exits.
        • -
      • arg. An argument that will be provided to the on_exit() function when the task exits.
        • -
      -

      - 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: -

        -
      • mqName. Name of the queue to open -
      • oflags. Open flags. These may be any combination of: -
          -
        • O_RDONLY. Open for read access. -
        • O_WRONLY. Open for write access. -
        • O_RDWR. Open for both read & write access. -
        • O_CREAT. Create message queue if it does not already -exist. -
        • O_EXCL. Name must not exist when opened. -
        • O_NONBLOCK. Don't wait for data. -
        - -
      • ... Optional parameters. -When the O_CREAT flag is specified, POSIX requires that a third -and fourth parameter be supplied: -
          -
        • mode. The mode parameter is of type mode_t. In the POSIX -specification, this mode value provides file permission bits for the -message queue. This parameter is required but not used in the present -implementation. -
        • attr. A pointer to an mq_attr that is provided to initialize. -the message queue. If attr is NULL, then the messages queue is created -with implementation-defined default message queue attributes. If attr is -non-NULL, then the message queue mq_maxmsg attribute is set to the -corresponding value when the queue is created. The mq_maxmsg attribute -determines the maximum number of messages that can be queued before -addition attempts to send messages on the message queue fail or cause the -sender to block; the mq_msgsize attribute determines the maximum size of a -message that can be sent or received. Other elements of attr are ignored -(i.e, set to default message queue attributes). -
        -
      - -

      -Returned Value: -

        -
      • A message queue descriptor or -1 (ERROR) -
      - -

      -Assumptions/Limitations: -

      - POSIX Compatibility: Comparable to the POSIX interface -of the same name. -Differences from the full POSIX implementation include: -

        -
      • The mq_msgsize attributes determines the maximum size of a message that -may be sent or received. In the present implementation, this maximum -message size is limited at 22 bytes. -
      - -

      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: -

        -
      • mqdes. Message queue descriptor. -
      - -

      -Returned Value: -

        -
      • 0 (OK) if the message queue is closed successfully, otherwise, --1 (ERROR). -
      - -

      -Assumptions/Limitations: -

      -

        -
      • - The behavior of a task that is blocked on either a mq_send() or mq_receive() is undefined when mq_close() is called. -
        • -
      • - The result of using this message queue descriptor after successful return from mq_close() is undefined. -
        • -
      -

      - 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: -

        -
      • mqName. Name of the message queue -
      - -

      -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: -

      -
        -
      • - It does not check the size of the queue. - It will always post the message, even if there is already too many messages in queue. - This is because the interrupt handler does not have the option of waiting for the message queue to become non-full. -
        • -
      • - It doesn't allocate new memory (because you cannot allocate memory from an interrup handler). - Instead, there are are pool of pre-allocated message structures that may be used just for sending messages from interrupt handlers. - The number of such pre-allocated messages is a configuration parameter. -
        • -
      -

      - Input Parameters: -

      -
        -
      • mqdes. Message queue descriptor.
        • -
      • msg. Message to send.
        • -
      • msglen. The length of the message in bytes.
        • -
      • prio. The priority of the message.
        • -
      -

      - Returned Value: - On success, mq_send() returns 0 (OK); - on error, -1 (ERROR) is returned, with errno set - to indicate the error: -

      -
        -
      • - EAGAIN. - The queue was empty, and the O_NONBLOCK flag was set for the message queue description referred to by mqdes. -
        • -
      • - EINVAL. - Either msg or mqdes is NULL or the value of prio is invalid. -
        • -
      • - EPERM. - Message queue opened not opened for writing. -
        • -
      • - EMSGSIZE. - msglen was greater than the maxmsgsize attribute of the message queue. -
        • -
      • - EINTR. - The call was interrupted by a signal handler. -
        • -
      -

      - 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: -

      -
        -
      • mqdes. Message queue descriptor.
        • -
      • msg. Message to send.
        • -
      • msglen. The length of the message in bytes.
        • -
      • prio. The priority of the message.
        • -
      -

      - Returned Value: - On success, mq_send() returns 0 (OK); - on error, -1 (ERROR) is returned, with errno set - to indicate the error: -

      -
        -
      • - EAGAIN. - The queue was empty, and the O_NONBLOCK flag was set for the message queue description referred to by mqdes. -
        • -
      • - EINVAL. - Either msg or mqdes is NULL or the value of prio is invalid. -
        • -
      • - EPERM. - Message queue opened not opened for writing. -
        • -
      • - EMSGSIZE. - msglen was greater than the maxmsgsize attribute of the message queue. -
        • -
      • - EINTR. - The call was interrupted by a signal handler. -
        • -
      -

      - 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: -

      -
        -
      • mqdes. Message Queue Descriptor.
        • -
      • msg. Buffer to receive the message.
        • -
      • msglen. Size of the buffer in bytes.
        • -
      • prio. If not NULL, the location to store message priority. -
      -

      - 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: -

      -
        -
      • - EAGAIN - The queue was empty and the O_NONBLOCK flag was set for the message queue description referred to by mqdes. -
        • -
      • - EPERM - Message queue opened not opened for reading. -
        • -
      • - EMSGSIZE - msglen was less than the maxmsgsize attribute of the message queue. -
        • -
      • - EINTR - The call was interrupted by a signal handler. -
        • -
      • - EINVAL - Invalid msg or mqdes -
        • -
      -

      - 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: -

      -
        -
      • mqdes. Message Queue Descriptor.
        • -
      • msg. Buffer to receive the message.
        • -
      • msglen. Size of the buffer in bytes.
        • -
      • prio. If not NULL, the location to store message priority. -
      • abstime. The absolute time to wait until a timeout is declared. -
      -

      - 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: -

      -
        -
      • - EAGAIN: - The queue was empty and the O_NONBLOCK flag was set for the message queue description referred to by mqdes. -
        • -
      • - EPERM: - Message queue opened not opened for reading. -
        • -
      • - EMSGSIZE: - msglen was less than the maxmsgsize attribute of the message queue. -
        • -
      • - EINTR: - The call was interrupted by a signal handler. -
        • -
      • - EINVAL: - Invalid msg or mqdes or abstime -
        • -
      • - ETIMEDOUT: - The call timed out before a message could be transferred. -
        • -
      -

      - 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, 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: -

        -
      • - mqdes. Message queue descriptor -
        • -
      • notification. Real-time signal structure containing: -
          -
        • sigev_notify. Should be SIGEV_SIGNAL (but actually ignored) -
        • sigev_signo. The signo to use for the notification -
        • sigev_value. Value associated with the signal -
        -
      -

      -

      - Returned Value: - On success mq_notify() returns 0; on error, -1 is returned, with - errno set to indicate the error: -

        -
      • - EBADF. The descriptor specified in mqdes is invalid. -
        • -
      • - EBUSY. Another process has already registered to receive notification - for this message queue. -
        • -
      • - EINVAL. sevp->sigev_notify is not one of the permitted values; or - sevp->sigev_notify is SIGEV_SIGNAL and sevp->sigev_signo is not a - valid signal number. -
        • -
      • - ENOMEM. Insufficient memory. -
        • -
      -

      -

      - Assumptions/Limitations: -

      -

      - POSIX Compatibility: Comparable to the POSIX interface of the same name. - Differences from the full POSIX implementation include: -

        -
      • - The notification signal will be sent to the registered task even if - another task is waiting for the message queue to become non-empty. This is - inconsistent with the POSIX specification which states, "If a process - has registered for notification of message arrival at a message queue and - some process is blocked in mq_receive waiting to receive a message - when a message arrives at the queue, the arriving message will satisfy the - appropriate mq_receive() ... The resulting behavior is as if the - message queue remains empty, and no notification will be sent." -
        • -
      -

      - -

      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: -

        -
      • mqdes. Message queue descriptor -
      • mqStat. New attributes -
      • oldMqState. Old attributes -
      - -

      -Returned Value: -

        -
      • 0 (OK) if attributes are set successfully, otherwise -1 -(ERROR). -
      - -

      -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: -

        -
      • mqdes. Message queue descriptor -
      • mqStat. Buffer in which to return attributes. The returned -attributes include: -
          -
        • mq_maxmsg. Max number of messages in queue. -
        • mq_msgsize. Max message size. -
        • mq_flags. Queue flags. -
        • mq_curmsgs. Number of messages currently in queue. -
        - -
      - -

      -Returned Value: -

        -
      • 0 (OK) if attributes provided, -1 (ERROR) otherwise. -
      - -

      -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-affects - 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: -

      -
        -
      • Implement all tasks that need the semaphore-managed resources at the - same priority level,
        • -
      • Boost the priority of the low-priority task before the semaphore is - acquired, or
        • -
      • Use sched_lock() in the low-priority task.
        • -
      -

      - 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: -

      -
        -
      • - CONFIG_SEM_PREALLOCHOLDERS. - First of all, in NuttX priority inheritance is implement on POSIX counting - semaphores. The reason for this is that these semaphores are the most - primitive waiting mechanism in NuttX; Most other waiting facilities are - based on semaphores. So if priority inheritance is implemented for POSIX - counting semaphores, then most NuttX waiting mechanisms will have this - capability. -

        - Complexity arises because counting semaphores can have numerous - holders of semaphore counts. Therefore, in order to implement - priority inheritance across all holders, then internal data - structures must be allocated to manage the various holders associated - with a semaphore. - The setting CONFIG_SEM_PREALLOCHOLDERS defines the maximum - number of different threads (minus one per semaphore instance) that can - take counts on a semaphore with priority inheritance support. - This setting defines the size of a single pool of pre-allocated structures. - It may be set to zero if priority inheritance is disabled OR if you - are only using semaphores as mutexes (only one holder) OR if no more - than two threads participate using a counting semaphore. -

        -

        - The cost associated with setting CONFIG_SEM_PREALLOCHOLDERS - is slightly increased code size and around 6-12 bytes times the value - of CONFIG_SEM_PREALLOCHOLDERS. -

        -
        • -
      • - CONFIG_SEM_NNESTPRIO: - In addition, there may be multiple threads of various priorities that - need to wait for a count from the semaphore. - These, the lower priority thread holding the semaphore may have to - be boosted numerous time and, to make things more complex, will have - to keep track of all of the boost priorities values in in order to - correctly restore the priorities after a count has been handed out - to the higher priority thread. - The CONFIG_SEM_NNESTPRIO defines the size of an array, - one array per active thread. - This setting is the maximum number of higher priority threads (minus - 1) than can be waiting for another thread to release a count on a semaphore. - This value may be set to zero if no more than one thread is expected to - wait for a semaphore. -

        - The cost associated with setting CONFIG_SEM_NNESTPRIO - is slightly increased code size and (CONFIG_SEM_PREALLOCHOLDERS + 1) - times the maximum number of active threads. -

        -
        • -
      • - Increased Susceptibility to Bad Thread Behavior. - These various structures tie the semaphore implementation more tightly to - the behavior of the implementation. For examples, if a thread executes while - holding counts on a semaphore, or if a thread exits without call sem_destroy() - then. Or what if the thread with the boosted priority re-prioritizes itself? - The NuttX implement of priority inheritance attempts to handle all of these - types of corner cases, but it is very likely that some are missed. - The worst case result is that memory could by stranded within the priority - inheritance logic. -
        • -
      -

      - 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: -

        -
      • sem. Semaphore to be initialized -
      • pshared. Process sharing (not used) -
      • value. Semaphore initialization value -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) if unsuccessful. -
      - -

      -Assumptions/Limitations: -

      - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the full POSIX implementation include: -

        -
      • pshared is not used. -
      - -

      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: -

        -
      • sem. Semaphore to be destroyed. -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) if unsuccessful. -
      - -

      -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: -

        -
      • name. Semaphore name -
      • oflag. Semaphore creation options. This may one of -the following bit settings: -
          -
        • oflag = 0: Connect to the semaphore only if it already -exists. -
        • oflag = O_CREAT: Connect to the semaphore if it exists, -otherwise create the semaphore. -
        • oflag = O_CREAT with O_EXCL (O_CREAT|O_EXCL): Create -a new semaphore unless one of this name already exists. -
        -
      • ... Optional parameters. -NOTE: When the O_CREAT flag is specified, POSIX requires that a third -and fourth parameter be supplied: -
          -
        • mode. The mode parameter is of type mode_t. -This parameter is required but not used in the present -implementation. -
        • value. The value parameter is type unsigned int. The semaphore -is created with an initial value of value. Valid initial values for -semaphores must be less than or equal to SEM_VALUE_MAX (defined in -include/limits.h). -
        -
      - -

      -Returned Value: -

        -
      • A pointer to sem_t or -1 (ERROR) if unsuccessful. -
      - -

      -Assumptions/Limitations: -

      - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the full POSIX implementation include: -

        -
      • Treatment of links/connections is highly simplified. It is -just a counting semaphore. -
      - -

      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: -

        -
      • sem. Semaphore descriptor -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) if unsuccessful. -
      - -

      -Assumptions/Limitations: -

        -
      • Care must be taken to avoid deletion of a semaphore that another task -has already locked. -
      • sem_close() must not be called with an un-named semaphore. -
      -

      - 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: -

        -
      • name. Semaphore name -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) if unsuccessful. -
      - -

      -Assumptions/Limitations: -

        -
      • Care must be taken to avoid deletion of a semaphore that another task -has already locked. -
      • sem_unlink() must not be called with an un-named semaphore. -
      -

      - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the full POSIX implementation include: -

        -
      • Treatment of links/connections is highly simplified. It is -just a counting semaphore. -
      • Calls to sem_open() to re-create or re-connect to the semaphore may -refer to the same semaphore; POSIX specifies that a new semaphore with the -same name should be created after sem_unlink() is called. -
      - -

      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: -

        -
      • sem. Semaphore descriptor. -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) is unsuccessful -
      -

      -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: -

      -

        -
      • EINVAL: Indicates that the sem input parameter is -not valid. -
      • 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: Comparable to the POSIX -interface of the same name. - -

      2.5.7 sem_timedwait

      - -

      -Function Prototype: -

      -    #include <semaphore.h>
-    #include <time.h>
-    int sem_wait(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 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: -

        -
      • - sem. Semaphore descriptor. -
        • -
      • - abstime. The absolute time to wait until a timeout is declared. -
        • -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) is unsuccessful -
      -

      -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: -

      -

        -
      -
    • - 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: -

        -
      • sem. The semaphore descriptor -
      - -

      -Returned Value: -

        -
      • 0 (OK) or -1 (ERROR) if unsuccessful -
      -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: -

      -

        -
      • EINVAL: Indicates that the sem input parameter is -not valid. -
      • EAGAIN: Indicates that the semaphore was not acquired. -
      -

      - -

      -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: -

        -
      • sem. Semaphore descriptor -
      - -

      -Returned Value: -

        -
      • 0 (OK) or -1 (ERROR) if unsuccessful. -
      - -

      -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: -

        -
      • sem. Semaphore descriptor -
      • sval. Buffer by which the value is returned -
      - -

      -Returned Value: -

        -
      • 0 (OK) or -1 (ERROR) if unsuccessful. -
      - -

      -Assumptions/Limitations: -

      - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

      - - - - - -
      -

      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: -

      -
        -
      • parm.
        • -
      -

      - 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: -

      -
        -
      • parm.
        • -
      -

      - 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: -

      -
        -
      • parm.
        • -
      -

      - 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: -

      -
        -
      • parm.
        • -
      -

      - 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: -

      -
        -
      • timep. - Represents GMT calendar time. - This is an absolute time value representing the number of seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time (UTC). -
        • -
      -

      - 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

      -
        -#include <time.h>
-#ifdef CONFIG_LIBC_LOCALTIME
-#  define localtime(c) gmtime(c)
-#else
-FAR struct tm *localtime(FAR const time_t *timep);
-#endif
-
      -

      - Description: - Represents local date/time in a type struct tm. - This function is not re-entrant. -

      -

      - Input Parameters: -

      -
        -
      • timep. - Represents GMT calendar time. - This is an absolute time value representing the number of seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time (UTC). -
      -

      - 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: -

      -
        -#include <time.h>
-#ifdef CONFIG_TIME_EXTENDED
-FAR char *asctime(FAR const struct tm *tp);
-#endif
-
      -

      - Description: - asctime() convert the time provided in a struct tm to a string representation. - asctime() is not re-entrant. -

      -

      - Input Parameters: -

      -
        -
      • tp. - Pointer to the time to be converted. -
        • -
      -

      - 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: -

      -
        -#include <time.h>
-#ifdef CONFIG_TIME_EXTENDED
-FAR char *ctime(FAR const time_t *timep);
-#endif
-
      -

      - Description: - ctime() converts the time provided in seconds since the epoch to a string representation. - ctime() is not re-entrant. -

      -

      - Input Parameters: -

      -
        -
      • timep. - The current time represented as seconds since the epoch. -
        • -
      -

      - 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: -

      -
        -
      • timep. - Represents GMT calendar time. - This is an absolute time value representing the number of seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time (UTC). -
      • result. - A user-provided buffer to receive the converted time structure. -
      -

      - 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

      -
        -#include <time.h>
-#ifdef CONFIG_LIBC_LOCALTIME
-#  define localtime_r(c,r) gmtime_r(c,r)
-#else
-FAR struct tm *localtime_r(FAR const time_t *timep, FAR struct tm *result);
-#endif
-
      -

      - Description: - Represents local date/time in a type struct tm. - This function is re-entrant. -

      -

      - Input Parameters: -

      -
        -
      • timep. - Represents GMT calendar time. - This is an absolute time value representing the number of seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time (UTC). -
      • result. - A user-provided buffer to receive the converted time structure. -
      -

      - 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: -

      -
        -#include <time.h>
-#ifdef CONFIG_TIME_EXTENDED
-FAR char *asctime_r(FAR const struct tm *tp, FAR char *buf);
-#endif
-
      -

      - Description: - asctime_r() converts the time provided in a struct tm to a string representation. - asctime-r() is re-entrant. -

      -

      - Input Parameters: -

      -
        -
      • tp. - Pointer to the time to be converted. -
        • -
      • buf. - The user provider buffer. of size >= 26 characters, to receive the converted time. -
        • -
      -

      - 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: -

      -
        -#include <time.h>
-#ifdef CONFIG_TIME_EXTENDED
-#endif
-
      -

      - Description: - ctime_r() converts the time provided in seconds since the epoch to a string representation. - ctime() is re-entrant. -

      -

      - Input Parameters: -

      -
        -
      • timep. - The current time represented as seconds since the epoch. -
        • -
      • buf. - The user provider buffer. of size >= 26 characters, to receive the converted time. -
        • -
      -

      - 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: -

      -
        -
      • clockid. Specifies the clock to use as the timing base. - Must be CLOCK_REALTIME.
        • -
      • evp. Refers to a user allocated sigevent structure that defines the - asynchronous notification. evp may be NULL (see above).
        • -
      • timerid. The pre-thread timer created by the call to timer_create().
        • -
      -

      - 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. -

      -
        -
      • EAGAIN. The system lacks sufficient signal queuing resources to honor the - request.
        • -
      • EAGAIN. The calling process has already created all of the timers it is - allowed by this implementation.
        • -
      • EINVAL. The specified clock ID is not defined.
        • -
      • ENOTSUP. The implementation does not support the creation of a timer attached - to the CPU-time clock that is specified by clock_id and associated with a - thread different thread invoking timer_create().
        • -
      -

      - POSIX Compatibility: - Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include: -

      -
        -
      • Only CLOCK_REALTIME is supported for the clockid argument.
        • -
      - -

      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: -

      -
        -
      • timerid. - The pre-thread timer, previously created by the call to timer_create(), to be deleted.
        • -
      -

      - 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: -

      -
        -
      • EINVAL. The timer specified timerid is not valid.
        • -
      -

      - 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: -

      -
        -
      • timerid. The pre-thread timer, previously created by the call to timer_create(), to be be set.
        • -
      • flags. Specify characteristics of the timer (see above)
        • -
      • value. Specifies the timer value to set
        • -
      • ovalue. A location in which to return the time remaining from the previous timer setting (ignored).
        • -
      -

      - 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. -

      -
        -
      • EINVAL. The timerid argument does not correspond to an ID returned by timer_create() but not yet deleted by timer_delete().
        • -
      • EINVAL. A value structure specified a nanosecond value less than zero or greater than or equal to 1000 million, - and the it_value member of that structure did not specify zero seconds and nanoseconds.
        • -
      -

      - POSIX Compatibility: - Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include: -

      -
        -
      • The ovalue argument is ignored.
        • -
      - -

      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: -

      -
        -
      • timerid. Specifies pre-thread timer, previously created by the call to - timer_create(), whose remaining count will be returned.
        • -
      -

      - 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: -

      -
        -
      • EINVAL. - The timerid argument does not correspond to an ID returned by - timer_create() but not yet deleted by timer_delete().
        • -
      -

      - 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: -

      -
        -
      • timerid. Specifies pre-thread timer, previously created by the call to - timer_create(), whose overrun count will be returned.
        • -
      -

      - Returned Value: - If the timer_getoverrun() function succeeds, it will return the timer - expiration overrun count as explained above. timer_getoverrun() will fail if: -

      -
        -
      • EINVAL. - The timerid argument does not correspond to an ID returned by - timer_create() but not yet deleted by timer_delete().
        • -
      -

      - POSIX Compatibility: - Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include: -

      -
        -
      • This interface is not currently implemented by NuttX.
        • -
      - -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: -

      -
        -
      • tp. The current time will be returned to this user provided location.
        • -
      • tzp. A reference to the timezone -- IGNORED.
        • -
      -

      - Returned Value: - See clock_gettime(). -

      - - - - - -
      -

      2.7 Signal Interfaces

       -
      - -

      - Tasks and Signals. - NuttX provides signal interfaces for tasks and pthreads. - Signals are used toalter 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. -

      -

      - There 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. -

      -

      - 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 the NuttX Threading Wiki page and the Tasks vs. Threads FAQ for additional information on tasks and threads in NuttX. -
      -

      - Signalling 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 signalling 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: -

      -
        -
      • - If a task group receives a signal then one and only one indeterminate thread in the task group which is not blocking the signal will receive the signal. -
        • -
      • - If a task group receives a signal and more than one thread is waiting on that signal, then one and only one indeterminate thread out of that waiting group will receive the signal. -
        • -
      -

      - 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: -

        -
      • set. Signal set to initialize. -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) if the signal set cannot be initialized. -
      - -

      -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: -

        -
      • set. Signal set to initialize -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) if the signal set cannot be initialized. -
      - -

      -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: -

        -
      • set. Signal set to add signal to -
      • signo. Signal to add -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) if the signal number is invalid. -
      - -

      -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: -

        -
      • set. Signal set to delete the signal from -
      • signo. Signal to delete -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) if the signal number is invalid. -
      - -

      -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: -

        -
      • set. Signal set to test -
      • signo. Signal to test for -
      - -

      -Returned Value: -

        -
      • 1 (TRUE), if the specified signal is a member of the set, -
      • 0 (OK or FALSE), if it is not, or -
      • -1 (ERROR) if the signal number is invalid. -
      - -

      -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: -

        -
      • sa_u.sa_handler. A pointer to a signal-catching function. -
      • sa_u.sa_sigaction. An alternative form for the signal catching -function. -
      • sa_mask. Additional set of signals to be blocked during -execution of the signal-catching function. -
      • sa_flags: Special flags to affect behavior of a signal. -
      -

      -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: -

        -
      • sig. Signal of interest -
      • act. Location of new handler -
      • oact. Location to store old handler -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) if the signal number is invalid. -
      - -

      -Assumptions/Limitations: -

      - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the POSIX implementation include: -

        -
      • - There are no default actions so the special value SIG_DFL is treated like SIG_IGN. -
        • -
      • - All sa_flags in struct sigaction of act input are ignored (all treated like SA_SIGINFO). - The one exception is if CONFIG_SCHED_CHILD_STATUS is defined; - then SA_NOCLDWAIT is supported but only for SIGCHLD. -
        • -
      - -

      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: -

        -
      • signo. The signal number to act on -
      - -

      -Returned Value: -

        -
      • Zero is returned upon successful completion, otherwise -1 (ERROR) is returned with the errno set appropriately. The errno value of EINVAL, for example, would indicate that signo argument is not a valid signal number. -
      - -

      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' signal mask before executing the signal handler; when the signal handler returns, the system will restore the calling process' signal mask to its state prior to the delivery of the signal. - signo will be removed from the calling process' signal mask. -

      -

      - NOTE: The value SIG_HOLD for disp is not currently supported. -

      -

      -Input Parameters: -

        -
      • signo. The signal number to operate on -
      • disp. The new disposition of the signal -
      - -

      -Returned Value: -

        -
      • -Upon successful completion, sigset() will the previous disposition of the signal. -Otherwise, SIG_ERR will be returned and errno set to indicate the error. -
      - -

      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: -

        -
      • how. How the signal mast will be changed: -
          -
        • SIG_BLOCK. The resulting set is the union of the -current set and the signal set pointed to by the set input parameter. -
        • SIG_UNBLOCK. The resulting set is the intersection -of the current set and the complement of the signal set pointed -to by the set input parameter. -
        • SIG_SETMASK. The resulting set is the signal set -pointed to by the set input parameter. -
        - -
      • set. Location of the new signal mask -
      • oset. Location to store the old signal mask -
      - -

      -Returned Value: -

        -
      • 0 (OK), or -1 (ERROR) if how is invalid. -
      - -

      -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' signal mask -

      -

      -Input Parameters: -

        -
      • signo. Identifies the signal to be blocked. -
      - -

      -Returned Value: -

        -
      • Zero is returned upon successful completion, otherwise -1 (ERROR) is returned with the errno set appropriately. The errno value of EINVAL, for example, would indicate that signo argument is not a valid signal number. -
      - -

      2.7.11 sigrelse

      - -

      -Function Prototype: -

      -    #include <signal.h>
-    int sigrelse(int signo);
-
      - -

      -Description: The sighold() function will remove signo from the calling process' signal mask -

      -

      -Input Parameters: -

        -
      • signo. Identifies the signal to be unblocked. -
      - -

      -Returned Value: -

        -
      • Zero is returned upon successful completion, otherwise -1 (ERROR) is returned with the errno set appropriately. The errno value of EINVAL, for example, would indicate that signo argument is not a valid signal number. -
      - -

      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: -

        -
      • set. The location to return the pending signal set. -
      - -

      -Returned Value: -

        -
      • 0 (OK) or -1 (ERROR) -
      - -

      -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: -

        -
      • set. The value of the signal mask to use while -suspended. -
      - -

      -Returned Value: -

        -
      • -1 (ERROR) always -
      - -

      -Assumptions/Limitations: -

      - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the POSIX specification include: -

        -
      • POSIX does not indicate that the original signal mask is restored. -
      • POSIX states that sigsuspend() "suspends the task until -delivery of a signal whose action is either to execute a signal-catching -function or to terminate the task." Only delivery of the signal -is required in the present implementation (even if the signal is ignored). -
      - -

      2.7.14 sigpause

      -

      -Function Prototype: -

      -    #include <signal.h>
-    int sigpause(int signo);
-
      - -

      -Description: The sigpause()) function will remove signo) from the calling process' signal mask and suspend the calling process until a signal is received. -The sigpause()) function will restore the process' signal mask to its original state before returning. -

      -Input Parameters: -

        -
      • set. Identifies the signal to be unblocked while waiting. -
      - -

      -Returned Value: -

        -
      • sigpause always returns -1 (ERROR). On a successful wait for a signal, the errno will be set to EINTR. -
      - -

      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: -

        -
      • set. The set of pending signals to wait for. -
      • info. The returned signal values -
      - -

      -Returned Value: -

        -
      • Signal number that cause the wait to be terminated, otherwise --1 (ERROR) is returned. -
      - -

      -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: -

        -
      • SI_USER. Signal sent from kill, raise, or abort -
      • SI_QUEUE. Signal sent from sigqueue -
      • SI_TIMER. Signal is result of timer expiration -
      • SI_ASYNCIO. Signal is the result of asynchronous IO completion -
      • SI_MESGQ. Signal generated by arrival of a message on an empty message queue. -
      - -

      -Input Parameters: -

        -
      • set. The set of pending signals to wait for. -
      • info. The returned signal values -
      • timeout. The amount of time to wait -
      - -

      -Returned Value: -

        -
      • Signal number that cause the wait to be terminated, otherwise --1 (ERROR) is returned. -
      - -

      -Assumptions/Limitations: -

      - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the POSIX interface include: -

        -
      • Values for si_codes differ -
      • No mechanism to return cause of ERROR. (It can be inferred -from si_code in a non-standard way). -
      • POSIX states that "If no signal is pending at the time of the -call, the calling task will be suspended until one or more signals -in set become pending or until it is interrupted by an unblocked, -caught signal." The present implementation does not require -that the unblocked signal be caught; the task will be resumed even if -the unblocked signal is ignored. -
      - -

      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: -

        -
      • tid. ID of the task to receive signal -
      • signo. Signal number -
      • value. Value to pass to task with signal -
      - -

      -Returned Value: -

        -
      • - On success (at least one signal was sent), zero (OK) is returned. - On error, -1 (ERROR) is returned, and errno is set appropriately. -
          -
        • EGAIN. The limit of signals which may be queued has been reached.
          • -
        • EINVAL. signo was invalid.
          • -
        • EPERM. The task does not have permission to send the signal to the receiving process.
          • -
        • ESRCH. No process has a PID matching pid.
          • -
        -
      - -

      -Assumptions/Limitations: -

      - POSIX Compatibility: Comparable to the POSIX -interface of the same name. -Differences from the POSIX interface include: -

        -
      • Default action is to ignore signals. -
      • Signals are processed one at a time in order -
      • POSIX states that, "If signo is zero (the null signal), error -checking will be performed but no signal is actually sent." -There is no null signal in the present implementation; a zero signal will -be sent. -
      - -

      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: -

        -
      • pid. The id of the task to receive the signal. - The POSIX kill() specification encodes process group - information as zero and negative pid values. - Only positive, non-zero values of pid are supported by this - implementation. ID of the task to receive signal -
      • signo. The signal number to send. - If signo is zero, no signal is sent, but all error checking is performed. -
      - -

      - Returned Value: -

        -
      • OK or ERROR -
      -

      - -

      - Assumptions/Limitations: -

      -

      - POSIX Compatibility: - Comparable to the POSIX interface of the same name. - Differences from the POSIX interface include: -

      -
        -
      • Default action is to ignore signals.
        • -
      • Signals are processed one at a time in order
        • -
      • Sending of signals to 'process groups' is not supported in NuttX.
        • -
      - -

      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: -
        -
      • None -
      - -

      - 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 broup. - 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 the NuttX Threading Wiki 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: -

      -
        -
      • pthread_atfork. register fork handlers.
        • -
      • pthread_attr_getdetachstate. get and set the detachstate attribute.
        • -
      • pthread_attr_getguardsize. get and set the thread guardsize attribute.
        • -
      • pthread_attr_getinheritsched. get and set the inheritsched attribute.
        • -
      • pthread_attr_getscope. get and set the contentionscope attribute.
        • -
      • pthread_attr_getstack. get and set stack attributes.
        • -
      • pthread_attr_getstackaddr. get and set the stackaddr attribute.
        • -
      • pthread_attr_setdetachstate. get and set the detachstate attribute.
        • -
      • pthread_attr_setguardsize. get and set the thread guardsize attribute.
        • -
      • pthread_attr_setscope. get and set the contentionscope attribute.
        • -
      • pthread_attr_setstack. get and set stack attributes.
        • -
      • pthread_attr_setstackaddr. get and set the stackaddr attribute.
        • -
      • pthread_cleanup_pop. establish cancellation handlers.
        • -
      • pthread_cleanup_push. establish cancellation handlers.
        • -
      • pthread_condattr_getclock. set the clock selection condition variable attribute.
        • -
      • pthread_condattr_getpshared. get the process-shared condition variable attribute.
        • -
      • pthread_condattr_setclock. set the clock selection condition variable attribute.
        • -
      • pthread_condattr_setpshared. set the process-shared condition variable attribute.
        • -
      • pthread_getconcurrency. get and set the level of concurrency.
        • -
      • pthread_getcpuclockid. access a thread CPU-time clock.
        • -
      • pthread_mutex_getprioceiling. get and set the priority ceiling of a mutex.
        • -
      • pthread_mutex_setprioceiling. get and set the priority ceiling of a mutex.
        • -
      • pthread_mutex_timedlock. lock a mutex.
        • -
      • pthread_mutexattr_getprioceiling. get and set the prioceiling attribute of the mutex attributes object.
        • -
      • pthread_mutexattr_getprotocol. get and set the protocol attribute of the mutex attributes object.
        • -
      • pthread_mutexattr_setprioceiling. get and set the prioceiling attribute of the mutex attributes object.
        • -
      • pthread_mutexattr_setprotocol. get and set the protocol attribute of the mutex attributes object.
        • -
      • pthread_rwlock_destroy. destroy and initialize a read-write lock object.
        • -
      • pthread_rwlock_init. destroy and initialize a read-write lock object.
        • -
      • pthread_rwlock_rdlock. lock a read-write lock object for reading.
        • -
      • pthread_rwlock_timedrdlock. lock a read-write lock for reading.
        • -
      • pthread_rwlock_timedwrlock. lock a read-write lock for writing.
        • -
      • pthread_rwlock_tryrdlock. lock a read-write lock object for reading.
        • -
      • pthread_rwlock_trywrlock. lock a read-write lock object for writing.
        • -
      • pthread_rwlock_unlock. unlock a read-write lock object.
        • -
      • pthread_rwlock_wrlock. lock a read-write lock object for writing.
        • -
      • pthread_rwlockattr_destroy. destroy and initialize the read-write lock attributes object.
        • -
      • pthread_rwlockattr_getpshared. get and set the process-shared attribute of the read-write lock attributes object.
        • -
      • pthread_rwlockattr_init. destroy and initialize the read-write lock attributes object.
        • -
      • pthread_rwlockattr_setpshared. get and set the process-shared attribute of the read-write lock attributes object.
        • -
      • pthread_setcanceltype. set cancelability state.
        • -
      • pthread_setconcurrency. get and set the level of concurrency.
        • -
      • pthread_spin_destroy. destroy or initialize a spin lock object.
        • -
      • pthread_spin_init. destroy or initialize a spin lock object.
        • -
      • pthread_spin_lock. lock a spin lock object.
        • -
      • pthread_spin_trylock. lock a spin lock object.
        • -
      • pthread_spin_unlock. unlock a spin lock object.
        • -
      • pthread_testcancel. set cancelability state.
        • -
      - -

      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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_attr_init() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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(pthread_attr_t *attr);
-
      -

      -Description: -An attributes object can be deleted when it is no longer needed. -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_attr_destroy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_attr_setschedpolicy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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(pthread_attr_t *attr, int *policy);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_attr_getschedpolicy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_attr_getschedpolicy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_attr_getschedparam() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_attr_setinheritsched() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_attr_getinheritsched() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_attr_setstacksize() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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(pthread_attr_t *attr, long *stackaddr);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_attr_getstacksize() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_create() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_detach() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_exit() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -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 cancelability state determines -when the cancellation takes effect. When the -cancellation is acted on, thread will be terminated.

      - -

      When cancelability is disabled, all cancels are held pending -in the target thread until the thread changes the cancelability. -When cancelability is deferred, all cancels are held pending in -the target thread until the thread changes the cancelability or -calls pthread_testcancel().

      - -

      Cancelability is asynchronous; all cancels are acted upon -immediately (when enable), interrupting the thread with its processing.

      - -

      -Input Parameters: -

      -

        -
      • thread. -Identifies the thread to be canceled.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_cancel() function will return zero (OK). -Otherwise, an error number will be returned to indicate the error: -

      -

        -
      • ESRCH. -No thread could be found corresponding to that specified by the given thread ID.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. Except:

      -
        -
      • The thread-specific data destructor functions will be called for thread. -However, these destructors are not currently supported.
        • -
      • Cancellation types are not supported. The thread will be canceled -at the time that pthread_cancel() is called or, if cancellation is disabled, at -the time when cancellation is re-enabled.
        • -
      • pthread_testcancel() is not supported.
        • -
      • Thread cancellation at cancellation points is not supported.
        • -
      - -

      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 cancelability state to the indicated -state and returns the previous cancelability state at the location -referenced by oldstate. -Legal values for state are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE.<.li> - -

      Any pending thread cancellation may occur at the time that the -cancellation state is set to PTHREAD_CANCEL_ENABLE.

      - -Input Parameters: -

      -

        -
      • state -New cancellation state. One of PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.<.li> -
      • oldstate. -Location to return the previous cancellation state. -
      -

      -Returned Value: -

      -If successful, the pthread_setcancelstate() function will return -zero (OK). Otherwise, an error number will be returned to indicate the error: -

      -

        -
      • ESRCH. -No thread could be found corresponding to that specified by the given thread ID.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.16 pthread_testcancelstate

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_setcancelstate(void);
-
      -

      -Description: -

      NOT SUPPORTED -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_setcancelstate() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.17 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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_join() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.18 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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_yield() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.19 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: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_self() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.20 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 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. -

      -

      - Input Parameters: -

      -
        -
      • - thread. - The ID of thread whose scheduling parameters will be queried. -
        • -
      • - policy. - The location to store the thread's scheduling policy. -
        • -
      • - param. - The location to store the thread's priority. -
        • -
      -

      - 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.21 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: -

      -
        -
      • - thread. - The ID of thread whose scheduling parameters will be modified. -
        • -
      • - policy. - The new scheduling policy of the thread. - Either SCHED_FIFO or SCHED_RR. - SCHED_OTHER and SCHED_SPORADIC are not supported. -
        • -
      • - param. - The location to store the thread's priority. -
        • -
      -

      - Returned Value: -

      -

      - If successful, the pthread_setschedparam() function will return - zero (OK). Otherwise, an error number will be - returned to indicate the error: -

      -
        -
      • - EINVAL. - The value specified by policy or one of the scheduling parameters - associated with the scheduling policy policy is invalid. -
        • -
      • - ENOTSUP. - An attempt was made to set the policy or scheduling parameters to an unsupported - value (SCHED_OTHER and SCHED_SPORADIC in particular are - not supported) -
        • -
      • - EPERM. - The caller does not have the appropriate permission to set either the scheduling - parameters or the scheduling policy of the specified thread. - Or, the implementation does not allow the application to modify one of the - parameters to the value specified. - -
        • -
      • - ESRCH. - The value specified by thread does not refer to a existing thread. -
        • -
      -

      - Assumptions/Limitations: -

      -

      - POSIX Compatibility: - Comparable to the POSIX interface of the same name. -

      - -

      2.8.22 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: -

      -

        -
      • key is a pointer to the key to create. -
      • destructor is an optional destructor() function that may -be associated with each key that is invoked when a -thread exits. However, this argument is ignored in -the current implementation. -
      -

      -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: -

      -

        -
      • EAGAIN. The system lacked sufficient resources -to create another thread-specific data key, or the -system-imposed limit on the total number of keys -per task {PTHREAD_KEYS_MAX} has been exceeded -
      • ENONMEM Insufficient memory exists to create the key. -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

        -
      • The present implementation ignores the destructor argument. -
      - -

      2.8.23 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: -

      -

        -
      • key. The data key to set the binding for. -
      • value. The value to bind to the key. -
      -

      -Returned Value: -

      -If successful, pthread_setspecific() will return zero (OK). -Otherwise, an error number will be returned: -

      -

        -
      • ENOMEM. Insufficient memory exists to associate the value -with the key. -
      • EINVAL. The key value is invalid. -
      -

      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. -

        -
      • pthread_setspecific() may be called from a thread-specific data -destructor function. -
      - -

      2.8.24 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: -

      -

        -
      • key. The data key to get the binding for. -
      -

      -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. -

        -
      • pthread_getspecific() may be called from a thread-specific data -destructor function. -
      - -

      2.8.25 pthread_key_delete

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_key_delete(pthread_key_t key)
-
      -

      -Description: -

      -This POSIX function should delete a thread-specific data -key previously returned by pthread_key_create(). However, -this function does nothing in the present implementation. -

      -Input Parameters: -

      -

        -
      • key. The key to delete -
      -

      -Returned Value: -

      -

        -
      • Always returns EINVAL. -
      -

      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.26 pthread_mutexattr_init

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_mutexattr_init(pthread_mutexattr_t *attr);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_mutexattr_init() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.27 pthread_mutexattr_destroy

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_mutexattr_destroy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.28 pthread_mutexattr_getpshared

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_mutexattr_getpshared(pthread_mutexattr_t *attr,
-                                     int *pshared);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_mutexattr_getpshared() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.29 pthread_mutexattr_setpshared

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-   int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
-                                    int pshared);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_mutexattr_setpshared() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.30 pthread_mutexattr_gettype

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-#ifdef CONFIG_MUTEX_TYPES
-    int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type);
-#endif
-
      -

      -Description: Return the mutex type from the mutex attributes. -

      -Input Parameters: -

      -

        -
      • attr. The mutex attributes to query
        • -
      • type. Location to return the mutex type. See - pthread_mutexattr_setttyp() - for a description of possible mutex types that may be returned.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_mutexattr_settype() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • EINVAL. Parameters attr and/or attr are invalid.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX interface of the same name. - -

      2.8.31 pthread_mutexattr_settype

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-#ifdef CONFIG_MUTEX_TYPES
-    int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);
-#endif
-
      -

      -Description: Set the mutex type in the mutex attributes. -

      -Input Parameters: -

      -

        -
      • attr. The mutex attributes in which to set the mutex type.
        • -
      • type. The mutex type value to set. The following values are supported: -
          -
        • PTHREAD_MUTEX_NORMAL. This type of mutex does not detect deadlock. A thread - attempting to re-lock this mutex without first unlocking it will deadlock. - Attempting to unlock a mutex locked by a different thread results in undefined - behavior. Attempting to unlock an unlocked mutex results in undefined behavior.
          • -
        • PTHREAD_MUTEX_ERRORCHECK. This type of mutex provides error checking. - A thread attempting to re-lock this mutex without first unlocking it will return with an error. - A thread attempting to unlock a mutex which another thread has locked will return with an error. - A thread attempting to unlock an unlocked mutex will return with an error.
          • -
        • PTHREAD_MUTEX_RECURSIVE. A thread attempting to re-lock this mutex without first - unlocking it will succeed in locking the mutex. The re-locking deadlock which can occur with mutexes - of type PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this mutex - require the same number of unlocks to release the mutex before another thread can acquire the mutex. - A thread attempting to unlock a mutex which another thread has locked will return with an error. - A thread attempting to unlock an unlocked mutex will return with an error.
          • -
        • PTHREAD_MUTEX_DEFAULT. The default mutex type (PTHREAD_MUTEX_NORMAL).
          • -
        -

        - In NuttX, PTHREAD_MUTEX_NORMAL is not implemented. Rather, the behavior described - for PTHREAD_MUTEX_ERRORCHECK is the normal behavior. -

        -
      -

      -Returned Value: -

      -If successful, the pthread_mutexattr_settype() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • EINVAL. Parameters attr and/or attr are invalid.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX interface of the same name. - -

      2.8.32 pthread_mutex_init

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_mutex_init(pthread_mutex_t *mutex,
-                           pthread_mutexattr_t *attr);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_mutex_init() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.33 pthread_mutex_destroy

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_mutex_destroy(pthread_mutex_t *mutex);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_mutex_destroy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.34 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: -

      -

        -
      • mutex. A reference to the mutex to be locked.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_mutex_lock() function will return zero (OK). -Otherwise, an error number will be returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -

      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.35 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: -

      -

        -
      • mutex. A reference to the mutex to be locked.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_mutex_trylock() function will return zero (OK). -Otherwise, an error number will be returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -

      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.36 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: -

      -

        -
      • mutex.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_mutex_unlock() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -

      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.37 pthread_condattr_init

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_condattr_init(pthread_condattr_t *attr);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_condattr_init() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.38 pthread_condattr_destroy

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_condattr_destroy(pthread_condattr_t *attr);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_condattr_destroy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.39 pthread_cond_init

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_cond_init(pthread_cond_t *cond, pthread_condattr_t *attr);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_cond_init() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.40 pthread_cond_destroy

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_cond_destroy(pthread_cond_t *cond);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_cond_destroy() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.41 pthread_cond_broadcast

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_cond_broadcast(pthread_cond_t *cond);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_cond_broadcast() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.42 pthread_cond_signal

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_cond_signal(pthread_cond_t *dond);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      -Returned Value: -

      -If successful, the pthread_cond_signal() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.43 pthread_cond_wait

      -

      -Function Prototype: -

      -

      -    #include <pthread.h>
-    int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);
-
      -

      -Description: -

      -Input Parameters: -

      -

        -
      • To be provided.
        • -
      -

      - Returned Value: -

      -If successful, the pthread_cond_wait() function will return -zero (OK). Otherwise, an error number will be -returned to indicate the error: -

      -

        -
      • To be provided.
        • -
      -Assumptions/Limitations: -

      -POSIX Compatibility: Comparable to the POSIX -interface of the same name. - -

      2.8.44 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: -

      -

      -

        -
      • To be provided.
        • -
      -

      - Returned Value: -

      -

      - If successful, the pthread_cond_timedwait() function will return - zero (OK). Otherwise, an error number will be - returned to indicate the error: -

      -
        -
      • To be provided.
        • -
      -

      - Assumptions/Limitations: -

      -

      - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

      - -

      2.8.45 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: -

      -
        -
      • - attr. Barrier attributes to be initialized. -
        • -
      -

      - 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.46 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: -

      -
        -
      • - attr. Barrier attributes to be destroyed. -
        • -
      -

      - 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.47 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: -

      -
        -
      • attr. Barrier attributes to be modified.
        • -
      • pshared. The new value of the pshared attribute.
        • -
      -

      - 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.48 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: -

      -

      -

        -
      • attr. Barrier attributes to be queried.
        • -
      • pshared. The location to stored the current value of the pshared attribute.
        • -
      -

      - 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.49 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: -

      -
        -
      • - barrier. - The barrier to be initialized. -
        • -
      • - attr. - Barrier attributes to be used in the initialization. -
        • -
      • - count. - The count to be associated with the barrier. - The count argument specifies the number of threads that must call - pthread_barrier_wait() before any of them successfully return from the call. - The value specified by count must be greater than zero. -
        • -
      -

      - Returned Value:0 (OK) on success or on of the following error numbers: -

      -
        -
      • - EAGAIN. - The system lacks the necessary resources to initialize another barrier. -
        • -
      • - EINVAL. - The barrier reference is invalid, or the values specified by attr are invalid, or - the value specified by count is equal to zero. -
        • -
      • - ENOMEM. - Insufficient memory exists to initialize the barrier. -
        • -
      • - EBUSY. - The implementation has detected an attempt to reinitialize a barrier while it is in use. -
        • -
      -

      - Assumptions/Limitations: -

      -

      - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

      - -

      2.8.50 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: -

      -
        -
      • barrier. The barrier to be destroyed.
        • -
      -

      - Returned Value: 0 (OK) on success or on of the following error numbers: -

      -
        -
      • - EBUSY. - The implementation has detected an attempt to destroy a barrier while it is in use. -
        • -
      • - EINVAL. - The value specified by barrier is invalid. -
        • -
      -

      - Assumptions/Limitations: -

      -

      - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

      - -

      2.8.51 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: -

      -
        -
      • barrier. The barrier on which to wait.
        • -
      -

      - 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.52 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: -

      -

      -

        -
      • - once_control. - Determines if init_routine() should be called. - once_control should be declared and initialized as follows: - 
          pthread_once_t once_control = PTHREAD_ONCE_INIT;
-
        - PTHREAD_ONCE_INIT is defined in pthread.h. -
        • -
      • - init_routine. - The initialization routine that will be called once. -
        • -
      -

      - 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.53 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: -

      -

      -

        -
      • - thread. - The id of the thread to receive the signal. Only positive, non-zero values of tthreadt are supported. -
        • -
      • - signo. - The signal number to send. If signo is zero, no signal is sent, but all error checking is performed. -
        • -
      -

      - Returned Value: -

      -

      - On success, the signal was sent and zero is returned. - On error one of the following error numbers is returned. -

      -
        -
      • - EINVAL. - An invalid signal was specified. -
        • -
      • - EPERM. - The thread does not have permission to send the signal to the target thread. -
        • -
      • - ESRCH. - No thread could be found corresponding to that specified by the given thread ID. -
        • -
      • - ENOSYS. - Do not support sending signals to process groups. -
        • -
      -

      - Assumptions/Limitations: -

      -

      - POSIX Compatibility: Comparable to the POSIX interface of the same name. -

      - -

      2.8.54 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: -

      -

      -

        -
      • - how. How the signal mast will be changed: -
          -
        • - SIG_BLOCK: - The resulting set is the union of the current set and the signal set pointed to by set. -
          • -
        • - SIG_UNBLOCK: - The resulting set is the intersection of the current set and the complement of the signal set pointed to by set. -
          • -
        • - SIG_SETMASK: - The resulting set is the signal set pointed to by set. -
          • -
        -
        • -
      • - set. Location of the new signal mask. -
        • -
      • - oset. Location to store the old signal mask. -
        • -
      -

      - Returned Value: -

      -
        - 0 (OK) on success or EINVAL if how is invalid. -
      -

      - 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: -

      -
        -
      • Task environments. - When a new task is created using task_create, the environment - of the child task is an inherited, exact copy of the environment of the parent. - However, after child task has been created, subsequent operations by the child task on - its environment does not alter the environment of the parent. - No do operations by the parent effect the child's environment. - The environments start identical but are independent and may diverge. -
        • -
      • Thread environments. - When a pthread is created using pthread_create, the child - thread also inherits that environment of the parent. - However, the child does not receive a copy of the environment but, rather, shares the same - environment. - Changes to the environment are visible to all threads with the same parentage. -
        • -
      -

      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: -

      -

      -

        -
      • - name. - The name of the variable to find. -
        • -
      -

      - 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: -

      -

      -

        -
      • - string - name=value string describing the environment setting to add/modify. -
        • -
      -

      - 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: -

      -

      -

        -
      • - name - The name of the variable to change. -
        • -
      • - value - The new value of the variable. -
        • -
      • - value - Replace any existing value if non-zero. -
        • -
      -

      - 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: -

      -

      -

        -
      • - name - The name of the variable to delete. -
        • -
      -

      - 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. - Or, a simple in-memory, pseudo file system can be enabled. - This simple file system can be enabled setting the CONFIG_NFILE_DESCRIPTORS - option to a non-zero value. - 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

      - -
        -  #include <fcntl.h>
-  int creat(const char *path, mode_t mode);
-  int open(const char *path, int oflag, ...);
-  int fcntl(int fd, int cmd, ...);
-
      - -

      2.10.2.2 unistd.h

      - -
        -  #include <unistd.h>
-  int     close(int fd);
-  int     dup(int fd);
-  int     dup2(int fd1, int fd2);
-  off_t   lseek(int fd, off_t offset, int whence);
-  ssize_t pread(int fd, void *buf, size_t nbytes, off_t offset);
-  ssize_t pwrite(int fd, const void *buf, size_t nbytes, off_t offset);
-  ssize_t read(int fd, void *buf, size_t nbytes);
-  int     unlink(const char *path);
-  ssize_t write(int fd, const void *buf, size_t nbytes);
-
      - -

      2.10.2.3 sys/ioctl.h

      - -
        -  #include <sys/ioctl.h>
-  #ifdef CONFIG_LIBC_IOCTL_VARIADIC
-  int ioctl(int fd, int req, ...);
-  #else
-  int ioctl(int fd, int req, unsigned long arg);
-  #endif
-
      - -

      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 poll() API, the following must be defined - in your NuttX configuration file: -

      -
        -
      • CONFIG_NFILE_DESCRIPTORS Defined to be greater than 0
        • -
      • CONFIG_DISABLE_POLL NOT defined
        • -
      -

      - In order to use the select with TCP/IP sockets test, you must also have the following additional things - selected in your NuttX configuration file: -

      -
        -
      • CONFIG_NET Defined for general network support
        • -
      • CONFIG_NET_TCP Defined for TCP/IP support
        • -
      • CONFIG_NSOCKET_DESCRIPTORS Defined to be greater than 0
        • -
      • CONFIG_NET_TCP_READAHEAD Define to enable read-ahead buffering
        • -
      • CONFIG_NET_NTCP_READAHEAD_BUFFERS Defined to be greater than zero
        • -
      -

      - In order to for select to work with incoming connections, you must also select: -

      -
        -
      • CONFIG_NET_TCPBACKLOG - Incoming connections pend in a backlog until accept() is called. - The size of the backlog is selected when listen() is called.
        • -
      -

      - Input Parameters: -

      -
        -
      • fds. List of structures describing file descriptors to be monitored.
        • -
      • nfds. The number of entries in the list.
        • -
      • timeout. Specifies an upper limit on the time for which poll() will - block in milliseconds. A negative value of timeout means an infinite - timeout.
        • -
      -

      - 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: -

      -
        -
      • EBADF. An invalid file descriptor was given in one of the sets.
        • -
      • EFAULT. The fds address is invalid
        • -
      • EINTR. A signal occurred before any requested event.
        • -
      • EINVAL. The nfds value exceeds a system limit.
        • -
      • ENOMEM. There was no space to allocate internal data structures.
        • -
      • ENOSYS. One or more of the drivers supporting the file descriptor does not support the poll method.
        • -
      - -

      2.10.2.5 sys/select.h

      - -
      2.10.2.5.1 select
      -

      - Function Prototype: -

      -
        -#include <sys/select.h>
-int select(int nfds, FAR fd_set *readfds, FAR fd_set *writefds,
-           FAR fd_set *exceptfds, FAR struct timeval *timeout);
-
      -

      - 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: -

      -
        -
      • nfds. the maximum file descriptor number (+1) of any descriptor in any of the three sets.
        • -
      • readfds. the set of descriptions to monitor for read-ready events
        • -
      • writefds. the set of descriptions to monitor for write-ready events
        • -
      • exceptfds. the set of descriptions to monitor for error events
        • -
      • timeout. Return at this time if none of these events of interest occur.
        • -
      -

      - Returned Value: -

      -
        -
      • 0: Timer expired
        • -
      • >0: The number of bits set in the three sets of descriptors
        • -
      • -1: An error occurred (errno will be set appropriately, - see poll()).
        • -
      - -

      2.10.3 Directory Operations

      - -
        -#include <dirent.h>
-
-int        closedir(DIR *dirp);
-FAR DIR   *opendir(const char *path);
-FAR struct dirent *readdir(FAR DIR *dirp);
-int        readdir_r(FAR DIR *dirp, FAR struct dirent *entry, FAR struct dirent **result);
-void       rewinddir(FAR DIR *dirp);
-void       seekdir(FAR DIR *dirp, int loc);
-int        telldir(FAR DIR *dirp);
-
      -       - -

      2.10.4 UNIX Standard Operations

      -
        -#include <unistd.h>
-
-pid_t   vfork(void);
-pid_t   getpid(void);
-void    _exit(int status) noreturn_function;
-unsigned int sleep(unsigned int seconds);
-void    usleep(unsigned long usec);
-int     pause(void);
-
-int     close(int fd);
-int     dup(int fd);
-int     dup2(int fd1, int fd2);
-int     fsync(int fd);
-off_t   lseek(int fd, off_t offset, int whence);
-ssize_t read(int fd, FAR void *buf, size_t nbytes);
-ssize_t write(int fd, FAR const void *buf, size_t nbytes);
-
-int     pipe(int fd[2]);
-
-int     chdir(FAR const char *path);
-FAR char *getcwd(FAR char *buf, size_t size);
-
-int     unlink(FAR const char *pathname);
-int     rmdir(FAR const char *pathname);
-
-#ifdef CONFIG_LIBC_EXECFUNCS
-int     execl(FAR const char *path, ...);
-int     execv(FAR const char *path, FAR char *const argv[]);
-#endif
-
-int     getopt(int argc, FAR char *const argv[], FAR const char *optstring);
-
      - - -

      2.10.5 Standard I/O

      -
        -#include <stdio.h>
-
-void   clearerr(register FILE *stream);
-int    fclose(FILE *stream);
-int    fflush(FILE *stream);
-int    feof(FILE *stream);
-int    ferror(FILE *stream);
-int    fileno(FAR FILE *stream);
-int    fgetc(FILE *stream);
-int    fgetpos(FILE *stream, fpos_t *pos);
-char  *fgets(char *s, int n, FILE *stream);
-FILE  *fdopen(int fd, const char *type);
-FILE  *fopen(const char *path, const char *type);
-int    fprintf(FILE *stream, const char *format, ...);
-int    fputc(int c, FILE *stream);
-int    fputs(const char *s, FILE *stream);
-size_t fread(void *ptr, size_t size, size_t n_items, FILE *stream);
-int    fseek(FILE *stream, long int offset, int whence);
-int    fsetpos(FILE *stream, fpos_t *pos);
-long   ftell(FILE *stream);
-size_t fwrite(const void *ptr, size_t size, size_t n_items, FILE *stream);
-char  *gets(char *s);
-int    ungetc(int c, FAR FILE *stream);
-
-int    printf(const char *format, ...);
-int    puts(const char *s);
-int    rename(const char *source, const char *target);
-int    sprintf(char *dest, const char *format, ...);
-int    asprintf (FAR char **ptr, FAR const char *fmt, ...);
-int    snprintf(FAR char *buf, size_t size, const char *format, ...);
-int    sscanf(const char *buf, const char *fmt, ...);
-void   perror(FAR const char *s);
-int    avsprintf(FAR char **ptr, const char *fmt, va_list ap);
-
-int    vprintf(const char *s, va_list ap);
-int    vfprintf(FILE *stream, const char *s, va_list ap);
-int    vsprintf(char *buf, const char *s, va_list ap);
-int    avsprintf(FAR char **ptr, const char *fmt, va_list ap);
-int    vsnprintf(FAR char *buf, size_t size, const char *format, va_list ap);
-int    vsscanf(char *buf, const char *s, va_list ap);
-
-FAR FILE *fdopen(int fd, FAR const char *type);
-int    dprintf(int fd, FAR const char *fmt, ...);
-int    vdprintf(int fd, FAR const char *fmt, va_list ap);
-
-FAR char *tmpnam(FAR char *s);
-FAR char *tempnam(FAR const char *dir, FAR const char *pfx);
-
-#include <sys/stat.h>
-
-int mkdir(FAR const char *pathname, mode_t mode);
-int mkfifo(FAR const char *pathname, mode_t mode);
-int stat(const char *path, FAR struct stat *buf);
-#if 0 /* Not yet supported */
-int fstat(int fd, FAR struct stat *buf);
-#endif
-
-#include <sys/statfs.h>
-
-int statfs(FAR const char *path, FAR struct statfs *buf);
-int fstatfs(int fd, FAR struct statfs *buf);
-
      - -

      2.10.6 Standard Library

      -

      - stdlib.h generally addresses other operating system interfaces. - However, the following may also be considered as file system interfaces: -

      -
        -#include <stdlib.h>
-
-int mktemp(FAR char *template);
-int mkstemp(FAR char *template);
-
      - -

      2.10.7 Asynchronous I/O

      -
        -#include <aio.h>
-
-int aio_cancel(int, FAR struct aiocb *aiocbp);
-int aio_error(FAR const struct aiocb *aiocbp);
-int aio_fsync(int, FAR struct aiocb *aiocbp);
-int aio_read(FAR struct aiocb *aiocbp);
-ssize_t aio_return(FAR struct aiocb *aiocbp);
-int aio_suspend(FAR const struct aiocb *const list[], int nent,
-                FAR const struct timespec *timeout);
-int aio_write(FAR struct aiocb *aiocbp);
-int lio_listio(int mode, FAR struct aiocb *const list[], int nent,
-               FAR struct sigevent *sig);
-
      - -

      2.10.8 Standard String Operations

      -
        -#include <string.h>
-
-char  *strchr(const char *s, int c);
-FAR char *strdup(const char *s);
-const char *strerror(int);
-size_t strlen(const char *);
-size_t strnlen(const char *, size_t);
-char  *strcat(char *, const char *);
-char  *strncat(char *, const char *, size_t);
-int    strcmp(const char *, const char *);
-int    strncmp(const char *, const char *, size_t);
-int    strcasecmp(const char *, const char *);
-int    strncasecmp(const char *, const char *, size_t);
-char  *strcpy(char *dest, const char *src);
-char  *strncpy(char *, const char *, size_t);
-char  *strpbrk(const char *, const char *);
-char  *strchr(const char *, int);
-char  *strrchr(const char *, int);
-size_t strspn(const char *, const char *);
-size_t strcspn(const char *, const char *);
-char  *strstr(const char *, const char *);
-char  *strtok(char *, const char *);
-char  *strtok_r(char *, const char *, char **);
-
-void  *memset(void *s, int c, size_t n);
-void  *memcpy(void *dest, const void *src, size_t n);
-int    memcmp(const void *s1, const void *s2, size_t n);
-void  *memmove(void *dest, const void *src, size_t count);
-
-# define bzero(s,n) (void)memset(s,0,n)
-
      - -

      2.10.9 Pipes and FIFOs

      - -

      2.10.9.1 pipe

      -

      - Function Prototype: -

      -
        -#include <unistd.h>
-int pipe(int fd[2]);
-
      -

      - Description: -

        -

        - pipe() creates a pair of file descriptors, pointing to a pipe inode, and - places them in the array pointed to by fd. - fd[0] is for reading, fd[1] is for writing. -

        -
      -

      -

      - Input Parameters: -

        -
      • fd[2]. The user provided array in which to catch the pipe file descriptors.
        • -
      -

      -

      -

      - Returned Value: -

        -

        - 0 is returned on success; otherwise, -1 is returned with errno set appropriately. -

        -
      -

      - -

      2.10.9.2 mkfifo

      -

      - Function Prototype: -

      -
        -#include <sys/stat.h>
-int mkfifo(FAR const char *pathname, mode_t mode);
-
      -

      - Description: -

        -

        - mkfifo() makes a FIFO device driver file with name pathname. - Unlike Linux, a NuttX FIFO is not a special file type but simply a device driver instance. - mode specifies the FIFO's permissions (but is ignored in the current implementation). -

        -

        - Once the FIFO has been created by mkfifo(), any thread can open it for - reading or writing, in the same way as an ordinary file. - However, it must have been opened from both reading and writing before input or output can be performed. - This FIFO implementation will block all attempts to open a FIFO read-only until at least one thread has opened the FIFO for writing. -

        -

        - If all threads that write to the FIFO have closed, subsequent calls to read() on the FIFO will return 0 (end-of-file). -

        -
      -

      -

      - Input Parameters: -

        -
      • pathname. - The full path to the FIFO instance to attach to or to create (if not already created). -
        • -
      • mode. - Ignored for now -
        • -
      -

      -

      - Returned Value: -

        -

        - 0 is returned on success; otherwise, -1 is returned with errno set appropriately. -

        -
      -

      - -

      2.10.10 FAT File System Support

      -

      2.10.10.1 mkfatfs

      -

      - Function Prototype: -

      -
        -#include <nuttx/fs/mkfatfs.h>
-int mkfatfs(FAR const char *pathname, FAR struct fat_format_s *fmt);
-
      -

      - Description: -

        -

        - The mkfats() formats a FAT file system image on the block - device specified by pathname -

        -

        Assumptions: The caller must assure that the block driver is not mounted and not in - use when this function is called. - The result of formatting a mounted device is indeterminate (but likely not good). -

        -
      -

      -

      - Input Parameters: -

        -
      • - pathname - The full path to the registered block driver in the file system. -
        • -
      • - fmt - A reference to an instance of a structure that provides caller-selectable - attributes of the created FAT file system. -
          -
          -struct fat_format_s
-{
-   uint8_t  ff_nfats;           /* Number of FATs */
-   uint8_t  ff_fattype;         /* FAT size: 0 (autoselect), 12, 16, or 32 */
-   uint8_t  ff_clustshift;      /* Log2 of sectors per cluster: 0-5, 0xff (autoselect) */
-   uint8_t  ff_volumelabel[11]; /* Volume label */
-   uint16_t ff_backupboot;      /* Sector number of the backup boot sector (0=use default)*/
-   uint16_t ff_rootdirentries;  /* Number of root directory entries */
-   uint16_t ff_rsvdseccount;    /* Reserved sectors */
-   uint32_t ff_hidsec;          /* Count of hidden sectors preceding fat */
-   uint32_t ff_volumeid;        /* FAT volume id */
-   uint32_t ff_nsectors;        /* Number of sectors from device to use: 0: Use all */
-};
-
          -
        • - -
      -

      -

      - Returned Value: -

        -

        - Zero (OK) on success; - -1 (ERROR) on failure with errno set appropriately: -

          -
        • EINVAL - - NULL block driver string, bad number of FATS in fmt, - bad FAT size in fmt, bad cluster size in fmt -
          • -
        • ENOENT - - pathname does not refer to anything in the file-system. -
          • -
        • ENOTBLK - - pathname does not refer to a block driver -
          • -
        • EACCESS - - block driver does not support write or geometry methods -
          • -
        -

        -
      -

      - -

      2.10.11 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: -

      -
        -#include <sys/mman.h>
-int mkfatfs(FAR const char *pathname, FAR struct fat_format_s *fmt);
-FAR void *mmap(FAR void *start, size_t length, int prot, int flags, int fd, off_t offset)
-
      -

      - Description: -

        - Provides minimal mmap() as needed to support eXecute In Place (XIP) - operation (as described above). -
      -

      -

      - Input Parameters: -

        -
      • - start - A hint at where to map the memory -- ignored. - The address of the underlying media is fixed and cannot be re-mapped without MMU support. -
        • -
      • - length - The length of the mapping -- ignored. - The entire underlying media is always accessible. -
        • -
      • - prot - See the PROT_* definitions in sys/mman.h. -
          -
        • - PROT_NONE - Will cause an error. -
          • -
        • - PROT_READ - PROT_WRITE and PROT_EXEC also assumed. -
          • -
        • - PROT_WRITE - PROT_READ and PROT_EXEC also assumed. -
          • -
        • - PROT_EXEC - PROT_READ and PROT_WRITE also assumed. -
          • -
        -
        • -
      • - flags - See the MAP_* definitions in sys/mman.h. -
          -
        • - MAP_SHARED - Required -
          • -
        • - MAP_PRIVATE - Will cause an error -
          • -
        • - MAP_FIXED - Will cause an error -
          • -
        • - MAP_FILE - Ignored -
          • -
        • - MAP_ANONYMOUS - Will cause an error -
          • -
        • - MAP_ANON - Will cause an error -
          • -
        • - MAP_GROWSDOWN - Ignored -
          • -
        • - MAP_DENYWRITE - Will cause an error -
          • -
        • - MAP_EXECUTABLE - Ignored -
          • -
        • - MAP_LOCKED - Ignored -
          • -
        • - MAP_NORESERVE - Ignored -
          • -
        • - MAP_POPULATE - Ignored -
          • -
        • - AP_NONBLOCK - Ignored -
          • -
        -
        • -
      • - fd - file descriptor of the backing file -- required. -
        • -
      • - offset - The offset into the file to map. -
        • -
      -

      -

      - Returned Value: -

        -

        - On success, mmap() returns a pointer to the mapped area. - On error, the value MAP_FAILED is returned, and errno is set appropriately. -

          -
        • ENOSYS - - Returned if any of the unsupported mmap() features are attempted. -
          • -
        • EBADF - - fd is not a valid file descriptor. -
          • -
        • EINVAL - - Length is 0. flags contained neither MAP_PRIVATE or MAP_SHARED, or - contained both of these values. -
          • -
        • ENODEV - - The underlying file-system of the specified file does not support memory mapping. -
          • -
        -

        -
      -

      - - - - - -
      -

      2.11 Network Interfaces

       -
      - -

      - NuttX includes a simple interface layer based on uIP (see http://www.sics.se). - NuttX supports subset of a standard socket interface to uIP. - These network feature 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: -

      -
        -#include <sys/socket.h>
-int socket(int domain, int type, int protocol);
-
      -

      - Description: - socket() creates an endpoint for communication and returns a descriptor. -

      -

      - Input Parameters: -

      -

      -

        -
      • domain: (see sys/socket.h)
        • -
      • type: (see sys/socket.h)
        • -
      • protocol: (see sys/socket.h)
        • -
      -

      - Returned Value: - 0 on success; -1 on error with errno set appropriately: -

      -
        -
      • EACCES. - Permission to create a socket of the specified type and/or protocol is denied.
        • -
      • EAFNOSUPPORT. - The implementation does not support the specified address family.
        • -
      • EINVAL. - Unknown protocol, or protocol family not available.
        • -
      • EMFILE. - Process file table overflow.
        • -
      • ENFILE - The system limit on the total number of open files has been reached.
        • -
      • ENOBUFS or ENOMEM. - Insufficient memory is available. The socket cannot be created until sufficient resources are freed.
        • -
      • EPROTONOSUPPORT. - The protocol type or the specified protocol is not supported within this domain.
        • -
      - -

      2.11.2 bind

      -

      - Function Prototype: -

      -
        -#include <sys/socket.h>
-int bind(int sockfd, const struct sockaddr *addr, socklen_t addrlen);
-
      -

      - 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: -

      -

      -

        -
      • sockfd: Socket descriptor from socket.
        • -
      • addr: Socket local address.
        • -
      • addrlen: Length of addr.
        • -
      -

      - Returned Value: - 0 on success; -1 on error with errno set appropriately: -

      -
        -
      • EACCES - The address is protected, and the user is not the superuser.
        • -
      • EADDRINUSE - The given address is already in use.
        • -
      • EBADF - sockfd is not a valid descriptor.
        • -
      • EINVAL - The socket is already bound to an address.
        • -
      • ENOTSOCK - sockfd is a descriptor for a file, not a socket.
        • -
      - -

      2.11.3 connect

      -

      - Function Prototype: -

      -
        -#include <sys/socket.h>
-int connect(int sockfd, const struct sockaddr *addr, socklen_t addrlen);
-
      -

      - 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: -

      -

      -

        -
      • sockfd: Socket descriptor returned by socket()
        • -
      • addr: Server address (form depends on type of socket)
        • -
      • addrlen: Length of actual addr
        • -
      -

      - 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: -

      -
        -#include <sys/socket.h>
-int listen(int sockfd, int backlog);
-
      -

      - 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: -

      -
        -
      • sockfd: Socket descriptor of the bound socket.
        • -
      • backlog: The maximum length the queue of pending connections may grow. - If a connection request arrives with the queue full, the client may receive an error - with an indication of ECONNREFUSED or, if the underlying protocol supports retransmission, - the request may be ignored so that retries succeed.
        • -
      -

      - Returned Value: - On success, zero is returned. On error, -1 is returned, and - errno is set appropriately. -

      -
        -
      • EADDRINUSE: Another socket is already listening on the same port.
        • -
      • EBADF: The argument sockfd is not a valid descriptor.
        • -
      • ENOTSOCK: The argument sockfd is not a socket.
        • -
      • EOPNOTSUPP: The socket is not of a type that supports the listen operation.
        • -
      - -

      2.11.5 accept

      -

      - Function Prototype: -

      -
        -#include <sys/socket.h>
-int accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen);
-
      -

      - 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: -

      -
        -
      • sockfd: Socket descriptor of the listening socket.
        • -
      • addr: Receives the address of the connecting client.
        • -
      • addrlen: Input: allocated size of addr, Return: returned size of addr.
        • -
      -

      - Returned Value: - Returns -1 on error. If it succeeds, it returns a non-negative integer - that is a descriptor for the accepted socket. -

      -
        -
      • EAGAIN or EWOULDBLOCK: - The socket is marked non-blocking and no connections are present to be accepted.
        • -
      • EBADF: - The descriptor is invalid.
        • -
      • ENOTSOCK: - The descriptor references a file, not a socket.
        • -
      • EOPNOTSUPP: - The referenced socket is not of type SOCK_STREAM.
        • -
      • EINTR: - The system call was interrupted by a signal that was caught before a valid connection arrived.
        • -
      • ECONNABORTED: - A connection has been aborted.
        • -
      • EINVAL: - Socket is not listening for connections.
        • -
      • EMFILE: - The per-process limit of open file descriptors has been reached.
        • -
      • ENFILE: - The system maximum for file descriptors has been reached.
        • -
      • EFAULT: - The addr parameter is not in a writable part of the user address space.
        • -
      • ENOBUFS or ENOMEM: - Not enough free memory.
        • -
      • EPROTO: - Protocol error.
        • -
      • EPERM: - Firewall rules forbid connection.
        • -
      - -

      2.11.6 send

      -

      - Function Prototype: -

      -
        -#include <sys/socket.h>
-ssize_t send(int sockfd, const void *buf, size_t len, int flags);
-
      -

      - 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: -

      -
        -
      • sockfd: Socket descriptor of socket -
      • buf: Data to send -
      • len: Length of data to send -
      • flags: Send flags -
      -

      - Returned Value: - See sendto(). -

      - -

      2.11.7 sendto

      -

      - Function Prototype: -

      -
        -#include <sys/socket.h>
- ssize_t sendto(int sockfd, const void *buf, size_t len, int flags,
-               const struct sockaddr *to, socklen_t tolen);
-
      -

      - 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: -

      -
        -
      • sockfd: Socket descriptor of socket -
      • buf: Data to send -
      • len: Length of data to send -
      • flags: Send flags -
      • to: Address of recipient -
      • tolen: The length of the address structure -
      -

      - Returned Value: - On success, returns the number of characters sent. On error, -1 is returned, - and errno is set appropriately: -

      -
        -
      • EAGAIN or EWOULDBLOCK. - The socket is marked non-blocking and the requested operation would block. -
      • EBADF. - An invalid descriptor was specified. -
      • ECONNRESET. - Connection reset by peer. -
      • EDESTADDRREQ. - The socket is not connection-mode, and no peer address is set. -
      • EFAULT. - An invalid user space address was specified for a parameter. -
      • EINTR. - A signal occurred before any data was transmitted. -
      • EINVAL. - Invalid argument passed. -
      • EISCONN. - The connection-mode socket was connected already but a recipient - was specified. (Now either this error is returned, or the recipient - specification is ignored.) -
      • EMSGSIZE. - The socket type requires that message be sent atomically, and the - size of the message to be sent made this impossible. -
      • ENOBUFS. - The output queue for a network interface was full. This generally - indicates that the interface has stopped sending, but may be - caused by transient congestion. -
      • ENOMEM. - No memory available. -
      • ENOTCONN. - The socket is not connected, and no target has been given. -
      • ENOTSOCK. - The argument s is not a socket. -
      • EOPNOTSUPP. - Some bit in the flags argument is inappropriate for the socket type. -
      • EPIPE. - The local end has been shut down on a connection oriented socket. - In this case the process will also receive a SIGPIPE unless - MSG_NOSIGNAL is set. -
      - -

      2.11.8 recv

      -

      - Function Prototype: -

      -
        -#include <sys/socket.h>
-ssize_t recv(int sockfd, void *buf, size_t len, int flags);
-
      -

      - Description: - The recv() call is identical to - recvfrom() with a NULL - from parameter. -

      -

      -

      - Input Parameters: -

      -
        - -
      • sockfd: Socket descriptor of socket
        • -
      • buf: Buffer to receive data
        • -
      • len: Length of buffer
        • -
      • flags: Receive flags
        • -
      -

      - Returned Value: - See recvfrom(). -

      - -

      2.11.9 recvfrom

      -

      - Function Prototype: -

      -
        -#include <sys/socket.h>
-ssize_t recvfrom(int sockfd, void *buf, size_t len, int flags,
-                 struct sockaddr *from, socklen_t *fromlen);
-
      -

      - 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: -

      -
        -
      • sockfd: Socket descriptor of socket.
        • -
      • buf: Buffer to receive data.
        • -
      • len: Length of buffer.
        • -
      • flags: Receive flags.
        • -
      • from: Address of source.
        • -
      • fromlen: The length of the address structure.
        • -
      -

      - 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. - Othwerwise, on errors, -1 is returned, and errno is set appropriately: -

      -
        -
      • EAGAIN. - The socket is marked non-blocking and the receive operation would block, - or a receive timeout had been set and the timeout expired before data - was received. -
      • EBADF. - The argument sockfd is an invalid descriptor. -
      • ECONNREFUSED. - A remote host refused to allow the network connection (typically because - it is not running the requested service). -
      • EFAULT. - The receive buffer pointer(s) point outside the process's address space. -
      • EINTR. - The receive was interrupted by delivery of a signal before any data were - available. -
      • EINVAL. - Invalid argument passed. -
      • ENOMEM. - Could not allocate memory. -
      • ENOTCONN. - The socket is associated with a connection-oriented protocol and has - not been connected. -
      • ENOTSOCK. - The argument sockfd does not refer to a socket. -
      - -

      2.11.10 setsockopt

      -

      - Function Prototype: -

      -
        -#include <sys/socket.h>
-int setsockopt(int sockfd, int level, int option,
-               const void *value, socklen_t value_len);
-
      -

      - 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: -

      -
        -
      • sockfd: Socket descriptor of socket
        • -
      • level: Protocol level to set the option
        • -
      • option: identifies the option to set
        • -
      • value: Points to the argument value
        • -
      • value_len: The length of the argument value
        • -
      -

      - Returned Value: - On success, returns the number of characters sent. - On error, -1 is returned, and errno is set appropriately: -

      -
        -
      • BADF. - The sockfd argument is not a valid socket descriptor. -
      • DOM. - The send and receive timeout values are too big to fit into the - timeout fields in the socket structure. -
      • INVAL. - The specified option is invalid at the specified socket level or the - socket has been shut down. -
      • ISCONN. - The socket is already connected, and a specified option cannot be set - while the socket is connected. -
      • NOPROTOOPT. - The option is not supported by the protocol. -
      • NOTSOCK. - The sockfd argument does not refer to a socket. -
      • NOMEM. - There was insufficient memory available for the operation to complete. -
      • NOBUFS. - Insufficient resources are available in the system to complete the call. -
      - -

      2.11.11 getsockopt

      -

      - Function Prototype: -

      -
        -#include <sys/socket.h>
-int getsockopt(int sockfd, int level, int option, void *value, socklen_t *value_len);
-
      -

      - 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 thevalue. -

      -

      - 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: -

      -
        -
      • sockfd: Socket descriptor of socket -
      • level: Protocol level to set the option -
      • option: Identifies the option to get -
      • value: Points to the argument value -
      • value_len: The length of the argument value -
      -

      - Returned Value: - On success, returns the number of characters sent. - On error, -1 is returned, and errno is set appropriately: -

      -
        -
      • BADF. - The sockfd argument is not a valid socket descriptor.
        • -
      • INVAL. - The specified option is invalid at the specified socket level or the - socket has been shutdown.
        • -
      • NOPROTOOPT. - The option is not supported by the protocol.
        • -
      • NOTSOCK. - The sockfd argument does not refer to a socket.
        • -
      • NOBUFS. - Insufficient resources are available in the system to complete the call.
        • -
      - - - - - -
      -

      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: -

      -
        -#include <sys/shm.h>
-#include <sys/ipc.h>
-int shmget(key_t key, size_t size, int shmflg);
-
      -

      - 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: -

      -
        -
      • -

        - The argument key is equal to IPC_PRIVATE. -

        -
        • -
      • -

        - The argument key does not already have a shared memory identifier associated with it and (shmflg & IPC_CREAT) is non-zero. -

        -
        • -
      -

      - Upon creation, the data structure associated with the new shared memory identifier will be initialized as follows: -

      -
        -
      • -

        - The low-order nine bits of shm_perm.mode are set equal to the low-order nine bits of shmflg. -

        -
        • -
      • -

        - The value of shm_segsz is set equal to the value of size. -

        -
        • -
      • -

        - The values of shm_lpid, shm_nattch, shm_atime, and shm_dtime are set equal to 0. -

        -
        • -
      • -

        - The value of shm_ctime is set equal to the current time. -

        -
        • -
      -

      - When the shared memory segment is created, it will be initialized with all zero values. -

      -

      - Input Parameters: -

      -
        -
      • - key: The key that is used to access the unique shared memory identifier. -
        • -
      • - size: The shared memory region that is created will be at least this size in bytes. -
        • -
      • - shmflg: See IPC_* definitions in sys/ipc.h. Only the values IPC_PRIVATE or IPC_CREAT are supported. -
        • -
      -

      - 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. -

      -
        -
      • - EACCES. - A shared memory identifier exists for key but operation permission as specified by the low-order nine bits of shmflg would not be granted. -
        • -
      • - EEXIST. - A shared memory identifier exists for the argument key but (shmflg & IPC_CREAT) && (shmflg & IPC_EXCL) are non-zero. -
        • -
      • - EINVAL. - A shared memory segment is to be created and the value of size is less than the system-imposed minimum or greater than the system-imposed maximum. -
        • -
      • - EINVAL. - No shared memory segment is to be created and a shared memory segment exists for key but the size of the segment associated with it is less than size and size is not 0. -
        • -
      • - ENOENT. - A shared memory identifier does not exist for the argument key and (shmflg & IPC_CREAT) is 0. -
        • -
      • - ENOMEM. - A shared memory identifier and associated shared memory segment will be created, but the amount of available physical memory is not sufficient to fill the request. -
        • -
      • - ENOSPC. - A shared memory identifier is to be created, but the system-imposed limit on the maximum number of allowed shared memory identifiers system-wide would be exceeded. -
        • -
      -

      - POSIX Deviations -

      -

        -
      • -

        - The values of shm_perm.cuid, shm_perm.uid, shm_perm.cgid, and shm_perm.gid should be set equal to the effective user ID and effective group ID, respectively, of the calling process. - The NuttX ipc_perm structure, however, does not support these fields because user and group IDs are not yet supported by NuttX. -

        -
        • -
      - -

      2.12.2 shmat

      -

      - Function Prototype: -

      -
        -#include <sys/shm.h>
-void *shmat(int shmid, FAR const void *shmaddr, int shmflg);
-
      -

      - 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: -

      -
        -
      • -

        - If shmaddr is a null pointer, the segment is attached at the first available address as selected by the system. -

        -
        • -
      • -

        - If shmaddr is not a null pointer and (shmflg & SHM_RND) is non-zero, the segment is attached at the address given by (shmaddr - ((uintptr_t)shmaddr % SHMLBA)). -

        -
        • -
      • -

        - If shmaddr is not a null pointer and (shmflg & SHM_RND) is 0, the segment is attached at the address given by shmaddr. -

        -
        • -
      • -

        - The segment is attached for reading if (shmflg & SHM_RDONLY) is non-zero and the calling process has read permission; otherwise, if it is 0 and the calling process has read and write permission, the segment is attached for reading and writing. -

        -
        • -
      -

      - Input Parameters: -

      -
        -
      • shmid: Shared memory identifier
        • -
      • smaddr: Determines mapping of the shared memory region
        • -
      • shmflg: See SHM_* definitions in include/sys/shm.h. Only SHM_RDONLY and SHM_RND are supported.
        • -
      -

      - 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. -

      -
        -
      • - EACCES. - Operation permission is denied to the calling process -
        • -
      • - EINVAL. - The value of shmid is not a valid shared memory identifier, the shmaddr is not a null pointer, and the value of (shmaddr -((uintptr_t)shmaddr % SHMLBA)) is an illegal address for attaching shared memory; or the shmaddr is not a null pointer, (shmflg & SHM_RND) is 0, and the value of shmaddr is an illegal address for attaching shared memory. -
        • -
      • - EMFILE. - The number of shared memory segments attached to the calling process would exceed the system-imposed limit. -
        • -
      • - ENOMEM. - The available data space is not large enough to accommodate the shared memory segment. -
        • -
      - -

      2.12.3 shmctl

      -

      - Function Prototype: -

      -
        -#include <sys/shm.h>
-#include <sys/ipc.h>
-int shmctl(int shmid, int cmd, FAR struct shmid_ds *buf);
-
      -

      - Description: - The shmctl() function provides a variety of shared memory control operations as specified by cmd. The following values for cmd are available: -

      -
        -
      • -

        - IPC_STAT. - Place the current value of each member of the shmid_ds data structure associated with shmid into the structure pointed to by buf. -

        -
        • -
      • -

        - IPC_SET. - Set the value of the shm_perm.mode member of the shmid_ds data structure associated with shmid to the corresponding value found in the structure pointed to by buf. -

        -
        • -
      • -

        - IPC_RMID. - Remove the shared memory identifier specified by shmid from the system and destroy the shared memory segment and shmid_ds data structure associated with it. -

        -
        • -
      -

      - Input Parameters: -

      -
        -
      • shmid: Shared memory identifier
        • -
      • cmd: shmctl() command
        • -
      • buf: Data associated with the shmctl() command
        • -
      -

      - Returned Value: - Upon successful completion, shmctl() will return 0; otherwise, it will return -1 and set errno to indicate the error. -

      -
        -
      • - EACCES. - The argument cmd is equal to IPC_STAT and the calling process does not have read permission. -
        • -
      • - EINVAL. - The value of shmid is not a valid shared memory identifier, or the value of cmd is not a valid command. -
        • -
      • - EPERM. - The argument cmd is equal to IPC_RMID or IPC_SET and the effective user ID of the calling process is not equal to that of a process with appropriate privileges and it is not equal to the value of shm_perm.cuid or shm_perm.uid in the data structure associated with shmid. -
        • -
      • - EOVERFLOW. - The cmd argument is IPC_STAT and the gid or uid value is too large to be stored in the structure pointed to by the buf argument. -
        • -
      -

      - POSIX Deviations -

      -

        -
      • - IPC_SET. - Does not set the the shm_perm.uid or shm_perm.gidmembers of the shmid_ds data structure associated with shmid because user and group IDs are not yet supported by NuttX -
        • -
      • - IPC_SET. - Does not restrict the operation to processes with appropriate privileges or matching user IDs in shmid_ds data structure associated with shmid. Again because user IDs and user/group privileges are are not yet supported by NuttX -
        • -
      • - IPC_RMID. - Does not restrict the operation to processes with appropriate privileges or matching user IDs in shmid_ds data structure associated with shmid. Again because user IDs and user/group privileges are are not yet supported by NuttX -
        • -
      - -

      2.12.4 shmdt

      -

      - Function Prototype: -

      -
        -#include <sys/shm.h>
-int shmdt(FAR const void *shmaddr);
-
      -

      - 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: -

      -
        -
      • shmid: Shared memory identifier
        • -
      -

      - 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. -

      -
        -
      • - EINVAL. - The value of shmaddr is not the data segment start address of a shared memory segment. -
        • -
      - - - - - -
      -

      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: -

        -
      • pid_t -
      • size_t -
      • sigset_t -
      • time_t -
      - - - - - -
      -

      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: -

        -
      • struct tcb_s -
      • mqd_t -
      • sem_t -
      • WDOG_ID -
      • pthread_key_t -
      -

      - 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: -

      -

        -#include <errno.h>
-#define errno *get_errno_ptr()
-int *get_errno_ptr(void);
-
      -

      - Description: - get_errno_ptr() returns a pointer to the thread-specific errno value. - Note that the symbol errno is defined to be get_errno_ptr() 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: -

      -

        -
      • A pointer to the thread-specific errno value. -
      -

      - - - - - -
      -

      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)
      • -
    • 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
      • -
    • lseek
      • -
    • Named Message Queue Interfaces -
    • mkdir
      • -
    • mkfatfs
      • -
    • 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_getpshared
      • -
    • pthread_mutexattr_gettype
      • -
    • pthread_mutexattr_init
      • -
    • pthread_mutexattr_setpshared
      • -
    • pthread_mutexattr_settype
      • -
    • pthread_mutex_destroy
      • -
    • pthread_mutex_init
      • -
    • pthread_mutex_lock
      • -
    • pthread_mutex_trylock
      • -
    • pthread_mutex_unlock
      • -
    • pthread_condattr_destroy
      • -
    • pthread_once
      • -
    • pthread_self
      • -
    • pthread_setcancelstate
      • -
    • pthread_setschedparam
      • -
    • pthread_setspecific
      • -
    • pthread_sigmask
      • -
    • pthread_testcancelstate
      • -
    • 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_getvalue
      • -
    • sem_init
      • -
    • sem_open
      • -
    • sem_post
      • -
    • 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_activate
      • -
    • Task Control Interfaces -
    • task_create
      • -
    • task_delete
      • -
    • task_init
      • -
    • task_restart
      • -
    • Task Scheduling Interfaces -
    • task_spawn
      • -
    • task_spawnattr_getstacksize
      • -
    • task_spawnattr_setstacksize
      • -
    • Task Switching Interfaces -
    • 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 548ab5e0aa..0000000000 --- a/Documentation/NxWidgets.html +++ /dev/null @@ -1,92 +0,0 @@ - - -NxWidgets - - -
      - - - - -
      -

      NxWidgets

      -

      Last Updated: March 27, 2012

      -
      -

      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: -

      -
        -
      • Conservative C++. - NXWidgets is written entirely in C++ but using only selected "embedded friendly" C++ constructs that are fully supported under NuttX. - No additional C++ support libraries are required. -
        • -
      • NX Integration. - NXWidgets integrate seamlessly with the NX graphics subsystem. - Think of the X server under Linux … the NX graphics system is like a tiny X server that provides windowing under NuttX. - By adding NXWidgets, you can support graphics objects like buttons and text boxes in the NX windows and toolbars. -
        • -
      • Small Footprint. - NXWidgets is tailored for use MCUs in embedded applications. - It is ideally suited for mid- and upper-range of most MCU families. - A complete NXWidgets is possible in as little as 40K of FLASH and maybe 4K of SRAM. -
        • -
      • Output Devices. - NXWidgets will work on the high-end frame buffer devices as well as on LCDs connected via serial or parallel ports to a small MCU. -
        • -
      • Input Devices. - NXWidgets will accept position and selection inputs from a mouse or a touchscreen. - It will also support character input from a keyboard such as a USB keyboard. - NXWidgets supports on very special widget called CKeypad that will provide keyboard input via an on-screen keypad that can be operated via mouse or touchscreen inputs. -
        • -
      • Many Graphic Objects. - Some of the graphic objects supported by NXWidgets include labels, buttons, text boxes, button arrays, check boxes, cycle buttons, images, sliders, scrollable list boxes, progress bars, and more. -
        • -
      • DOxygen Documentation - DOxygen documentation is available. -
        • -
      -

      - 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: -

      -
        -
      • - NxWidgets-1.0: - Documentation, and - Downloads -
        • -
      • http://nuttx.org/nxwidgets_v1_0/ - NxWidgets-1.1: - Documentation, - Release notes, and - Downloads -
        • -
      • - NxWidgets-1.2: - Documentation, - Release notes, and - Downloads -
        • -
      • - NxWidgets-1.3: - Documentation, - Release notes, and - Downloads -
        • -

        -

        - Thanks go to Jose Pablo Carballo for contributing this! -

        -

        - - diff --git a/Documentation/README.html b/Documentation/README.html deleted file mode 100644 index 62fc47541d..0000000000 --- a/Documentation/README.html +++ /dev/null @@ -1,374 +0,0 @@ - - -README Files - - -
        - - - - -
        -

        NuttX README Files

        -

        Last Updated: June 21, 2015

        -
        -

        - Additional information can be found in the Documentation/ directory and - also in README files that are scattered throughout the source tree. - Below is a guide to the available README files. - Some README files contain more important information than others. - The key README files are shown in BOLDFACE/ITALIC below. -

        - - - diff --git a/Documentation/UsbTrace.html b/Documentation/UsbTrace.html deleted file mode 100644 index 7efb7ebccb..0000000000 --- a/Documentation/UsbTrace.html +++ /dev/null @@ -1,452 +0,0 @@ - - -NuttX USB Trace Capability - - - -
        - - - - -
        -

        NuttX USB Device Trace

        -

        Last Updated: March 20, 2011

        -
        -
        -

        USB Device Tracing Controls. - The NuttX USB device subsystem supports a fairly sophisticated tracing facility. - The basic trace cabability is controlled by these NuttX configuration settings: -

        -
          -
        • CONFIG_USBDEV_TRACE: Enables USB tracing
          • -
        • CONFIG_USBDEV_TRACE_NRECORDS: Number of trace entries to remember
          • -
        -

        Trace IDs. - The trace facility works like this: - When enabled, USB events that occur in either the USB device driver or in the USB class driver are logged. - These events are described in include/nuttx/usb/usbdev_trace.h. - The logged events are identified by a set of event IDs: -

        -
          - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
          TRACE_INIT_IDInitialization events
          TRACE_EP_IDEndpoint API calls
          TRACE_DEV_IDUSB device API calls
          TRACE_CLASS_IDUSB class driver API calls
          TRACE_CLASSAPI_IDOther class driver system API calls
          TRACE_CLASSSTATE_IDTrack class driver state changes
          TRACE_INTENTRY_IDInterrupt handler entry
          TRACE_INTDECODE_IDDecoded interrupt event
          TRACE_INTEXIT_IDInterrupt handler exit
          TRACE_OUTREQQUEUED_IDRequest queued for OUT endpoint
          TRACE_INREQQUEUED_IDRequest queued for IN endpoint
          TRACE_READ_IDRead (OUT) action
          TRACE_WRITE_IDWrite (IN) action
          TRACE_COMPLETE_IDRequest completed
          TRACE_DEVERROR_IDUSB controller driver error event
          TRACE_CLSERROR_IDUSB class driver error event
        -

        Logged Events. - Each logged event is 32-bits in size and includes -

        -
          -
        1. 8-bits of the trace ID (values associated with the above)
          2. -
        2. 8-bits of additional trace ID data, and
          3. -
        3. 16-bits of additonal data.
          4. -
        -

        8-bit Trace Data - The 8-bit trace data depends on the specific event ID. As examples, -

        -
          -
        • - For the USB serial and mass storage class, the 8-bit event data is provided in include/nuttx/usb/usbdev_trace.h. -
          • -
        • - For the USB device driver, that 8-bit event data is provided within the USB device driver itself. - So, for example, the 8-bit event data for the LPC1768 USB device driver is found in arch/arm/src/lpc17xx/lpc17_usbdev.c. -
          • -
        -

        16-bit Trace Data. - The 16-bit trace data provided additional context data relevant to the specific logged event. -

        -

        Trace Control Interfaces. - Logging of each of these kinds events can be enabled or disabled using the interfaces described in include/nuttx/usb/usbdev_trace.h. -

        -

        Enabling USB Device Tracing. - USB device tracing will be configured if CONFIG_USBDEV and either of the following are set in the NuttX configuration file: -

        -
          -
        • CONFIG_USBDEV_TRACE, or
          • -
        • CONFIG_DEBUG and CONFIG_DEBUG_USB
          • -
        -

        Log Data Sink. - The logged data itself may go to either (1) an internal circular buffer, or (2) may be provided on the console. - If CONFIG_USBDEV_TRACE is defined, then the trace data will go to the circular buffer. - The size of the circular buffer is determined by CONFIG_USBDEV_TRACE_NRECORDS. - Otherwise, the trace data goes to console. -

        -

        Example. - Here is an example of USB trace output using apps/examples/usbserial for an LPC1768 platform with the following NuttX configuration settings: -

        -
          -
        • CONFIG_DEBUG, CONFIG_DEBUG_VERBOSE, CONFIG_USB -
        • CONFIG_EXAMPLES_USBSERIAL_TRACEINIT, CONFIG_EXAMPLES_USBSERIAL_TRACECLASS, - CONFIG_EXAMPLES_USBSERIAL_TRACETRANSFERS, CONFIG_EXAMPLES_USBSERIAL_TRACECONTROLLER, - CONFIG_EXAMPLES_USBSERIAL_TRACEINTERRUPTS -
        -

        Console Output:

        -
          - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
           ABDE
           usbserial_main: Registering USB serial driver
           uart_register: Registering /dev/ttyUSB0
           usbserial_main: Successfully registered the serial driver
          1Class API call 1: 0000
          2Class error: 19:0000
           usbserial_main: ERROR: Failed to open /dev/ttyUSB0 for reading: 107
           usbserial_main: Not connected. Wait and try again.
          3Interrupt 1 entry: 0039
          4Interrupt decode 7: 0019
          5Interrupt decode 32: 0019
          6Interrupt decode 6: 0019
          7Class disconnect(): 0000
          8Device pullup(): 0001
          9Interrupt 1 exit: 0000
        -

        - The numbered items are USB USB trace output. - You can look in the file drivers/usbdev/usbdev_trprintf.c to see examctly how each output line is formatted. - Here is how each line should be interpreted: -

        -
          - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
           USB EVENT ID8-bit
          EVENT
          DATA          		MEANING16-bit
          EVENT
          DATA
          1TRACE_CLASSAPI_ID11USBSER_TRACECLASSAPI_SETUP10000
          2TRACE_CLSERROR_ID119USBSER_TRACEERR_SETUPNOTCONNECTED10000
          3TRACE_INTENTRY_ID11LPC17_TRACEINTID_USB20039
          4TRACE_INTDECODE_ID27LPC17_TRACEINTID_DEVSTAT20019
          5TRACE_INTDECODE_ID232LPC17_TRACEINTID_SUSPENDCHG20019
          6TRACE_INTDECODE_ID26LPC17_TRACEINTID_DEVRESET20019
          7TRACE_CLASS_ID13(See TRACE_CLASSDISCONNECT1)0000
          8TRACE_DEV_ID16(See TRACE_DEVPULLUP1)0001
          9TRACE_INTEXIT_ID11LPC17_TRACEINTID_USB20000
          -

          NOTES:
          - 1See include/nuttx/usb/usbdev_trace.h
          - 2See arch/arm/src/lpc17xx/lpc17_usbdev.c -

          -
        -

        - In the above example you can see that: -

        -
          -
        • 1. - The serial class USB setup method was called for the USB serial class. - This is the corresponds to the following logic in drivers/usbdev/pl2303.c: - 
            -static int pl2303_setup(FAR struct uart_dev_s *dev)
-{
-  ...
-  usbtrace(PL2303_CLASSAPI_SETUP, 0);
-  ...
-
          -
          • -
        • 2. - An error occurred while processing the setup command because no configuration has yet been selected by the host. - This corresponds to the following logic in drivers/usbdev/pl2303.c: - 
            -static int pl2303_setup(FAR struct uart_dev_s *dev)
-{
-  ...
-  /* Check if we have been configured */
-
-  if (priv->config == PL2303_CONFIGIDNONE)
-    {
-      usbtrace(TRACE_CLSERROR(USBSER_TRACEERR_SETUPNOTCONNECTED), 0);
-      return -ENOTCONN;
-    }
-  ...
-
          -
        • 3-6. - Here is a USB interrupt that suspends and resets the device. -
          • -
        • 7-8. - During the interrupt processing the serial class is disconnected -
          • -
        • 9. - And the interrupt returns -
          • -
        -

        USB Monitor. - The USB monitor is an application in the apps/system/usbmonitor that provides a convenient way to get debug trace output. - If tracing is enabled, the USB device will save encoded trace output in in-memory buffer; - if the USB monitor is also enabled, that trace buffer will be periodically emptied and dumped to the - system logging device (the serial console in most configurations). - The following are some of the relevant configuration options: -

        -
          - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
          - Device Drivers -> USB Device Driver Support -
          - CONFIG_USBDEV_TRACE=y - - Enable USB trace feature -
          - CONFIG_USBDEV_TRACE_NRECORDS=nnnn - - Buffer nnnn records in memory. - If you lose trace data, then you will need to increase the size of this buffer - (or increase the rate at which the trace buffer is emptied). -
          - CONFIG_USBDEV_TRACE_STRINGS=y - - Optionally, convert trace ID numbers to strings. - This feature may not be supported by all drivers. -
          - Application Configuration -> NSH LIbrary -
          - CONFIG_NSH_USBDEV_TRACE=n - - Make sure that any built-in tracing from NSH is disabled. -
          - CONFIG_NSH_ARCHINIT=y - - Enable this option only if your board-specific logic has logic to automatically start the USB monitor. - Otherwise the USB monitor can be started or stopped with the usbmon_start and usbmon_stop commands from the NSH console. -
          - Application Configuration -> System NSH Add-Ons -
          - CONFIG_SYSTEM_USBMONITOR=y - - Enable the USB monitor daemon -
          - CONFIG_SYSTEM_USBMONITOR_STACKSIZE=nnnn - - Sets the USB monitor daemon stack size to nnnn. - The default is 2KiB. -
          - CONFIG_SYSTEM_USBMONITOR_PRIORITY=50 - - Sets the USB monitor daemon priority to nnnn. - This priority should be low so that it does not interfere with other operations, but not so low that you cannot dump the buffered USB data sufficiently rapidly. - The default is 50. -
          - CONFIG_SYSTEM_USBMONITOR_INTERVAL=nnnn - - Dump the buffered USB data every nnnn seconds. - If you lose buffered USB trace data, then dropping this value will help by increasing the rate at which the USB trace buffer is emptied. -
          - CONFIG_SYSTEM_USBMONITOR_TRACEINIT=y
          - CONFIG_SYSTEM_USBMONITOR_TRACECLASS=y
          - CONFIG_SYSTEM_USBMONITOR_TRACETRANSFERS=y
          - CONFIG_SYSTEM_USBMONITOR_TRACECONTROLLER=y
          - CONFIG_SYSTEM_USBMONITOR_TRACEINTERRUPTS=y
          -           		- Selects which USB event(s) that you want to be traced. -
          -
        -

        - NOTE: If USB debug output is also enabled, both outputs will appear on the serial console. - However, the debug output will be asynchronous with the trace output and, hence, difficult to interpret. -

        - - diff --git a/Documentation/acronyms.txt b/Documentation/acronyms.txt deleted file mode 100644 index 00321607ba..0000000000 --- a/Documentation/acronyms.txt +++ /dev/null @@ -1,57 +0,0 @@ -AIC Advanced Interrupt Controller (Atmel SAM) -ADC Analog to Digital Conversion -ARP Address Resolution Protocol (networking) -BCH Block to Character -BINFMT Binary Format (Dynamic Loader) -CAN Controller Area Network -CP15 Coprocessor 15 (ARM) -DEVIF Device Interface (networking) -DAC Digital to Analog Conversion -DEV Device -DMA Direct Memory Access (hardware) -DMAC DMA Controller (hardware) -DRAM Dynamic RAM -FAT File Allocation Table (file systems) -FTL FLASH Translation Layer (MTD) -HSMCI High Speed Memory Card Interface (Atmel) -I/O Input/Output -IP Internet Protocol (version 4?) (networking) -IPv6 Internet Protocol Version 6 (networking) -IRQ Interrupt Request -I2C Inter-Integrated Circuit -I2S Inter IC Sound -ICMP Internet Control Message Protocol (networking) -IOB I/O Buffer (networking) -LIBC The "C" Library -MCI Memory Card Interface -MM Memory Management/Manager -MMAP Memory Map -MMC Multi-Media Card -MMCSD See MMC and SD -MTD Memory Technology Device -NFS Network File System -NETDEV Network Device (networking) -NSH NuttShell -NX NuttX, the NuttX Graphics server (graphics) -NXFFS NuttX Flash File System -NXWM The NuttX Window Manager (graphics) -PID Peripheral ID (Atmel SAM) -PWM Pulse Width Modulation -PKT "Raw" Packet socket (networking) -RAM Random Access Memory -RTC Real Time Clock -RTCC Real Time Clock/Calendar -SAIC Secure Advanced Interrupt Controller (Atmel SAM) -SD Secure Digital -SDIO Secure Digital I/O -SMC Static Memory Controller (hardware) -SPI Serial Periperhal Interface -TCP Transmission Control Protocol (networking) -TSC Touchscreen Controller -TWI Two-Wire Interface -UDP User Datagram Protocol (networking) -UART Universal Asynchronous Receiver/Transmitter -USB Universal Serial Bus -USART Universal Synchronous/Asynchronous Receiver/Transmitter -WDT Watchdog Timer -XDMAC Extended DMA Controller (Atmel) diff --git a/Documentation/backgd.gif b/Documentation/backgd.gif deleted file mode 100644 index e81f153aa2b42c18c627621aba029e7db952e154..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1097 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 diff --git a/Documentation/pm.png b/Documentation/pm.png deleted file mode 100644 index d84d8642dc0fe7620c4243a06c0c84c0b7a4c892..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 32504 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 - - -The NuttX RTOS - - - - - - -
        -

        The NuttX RTOS

        -
        -

        -
        - The NuttX RTOS web site has moved to nuttx.org. - Please update your bookmarks and wait while you are redirected there. -
         - -

      - 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: -