+ + NX Graphics Subsystem ++Last Updated: July 14, 2015 + |
+
+ Table of Contents+ |
+
+ 1.0 Introduction+ |
+
+ 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.
+
+ |
+ 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: +
+include/nuttx/video/fb.h).
+ include/nuttx/lcd/lcd.h).
+ By default, NX is configured to use the frame buffer driver unless CONFIG_NX_LCDDRIVER is defined =y in your NuttX configuration file.
+ + 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. +
+ ++
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. +
+ +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.
+
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. +
+ +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. +
+ +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. +
+ +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+ |
+
include/nuttx/nx/nxglib.h
+ include/nuttx/nx/nx.h
+ include/nutt/nxtk.h
+ include/nutt/nxfont.h
+ 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.
+
+ 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:
+
+typedef int16_t nxgl_coord_t; ++ +
+ struct nxgl_point_s. Describes a point on the display:
+
+struct nxgl_point_s
+{
+ nxgl_coord_t x; /* X position, range: 0 to screen width - 1 */
+ nxgl_coord_t y; /* Y position, range: 0 to screen height - 1 */
+};
+
+
+
+ struct nxgl_size_s. Describes the size of a rectangular region.
+
+struct nxgl_size_s
+{
+ nxgl_coord_t w; /* Width in pixels */
+ nxgl_coord_t h; /* Height in rows */
+};
+
+
+
+ struct nxgl_rect_s. Describes a positioned rectangle on the display.
+
+struct nxgl_rect_s
+{
+ struct nxgl_point_s pt1; /* Upper, left-hand corner */
+ struct nxgl_point_s pt2; /* Lower, right-hand corner */
+};
+
+
+
+ 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_run_s
+{
+ b16_t x1; /* Left X position, range: 0 to x2 */
+ b16_t x2; /* Right X position, range: x1 to screen width - 1 */
+ nxgl_coord_t y; /* Top Y position, range: 0 to screen height - 1 */
+};
+
+
+
+ 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
+
+struct nxgl_trapezoid_s
+{
+ struct nxgl_run_s top; /* Top run */
+ struct nxgl_run_s bot; /* bottom run */
+};
+
+
+nxgl_rgb2yuv()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_rgb2yuv(uint8_t r, uint8_t g, uint8_t b, uint8_t *y, uint8_t *u, uint8_t *v); ++
+ Description: + Convert 8-bit RGB triplet to 8-bit YUV triplet. +
+ +nxgl_yuv2rgb()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_yuv2rgb(uint8_t y, uint8_t u, uint8_t v, uint8_t *r, uint8_t *g, uint8_t *b); ++
+ Description: + Convert 8-bit RGB triplet to 8-bit YUV triplet. +
+ +nxgl_rectcopy()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_rectcopy(FAR struct nxgl_rect_s *dest, + FAR const struct nxgl_rect_s *src); ++
+ Description:
+ This is essentially memcpy()for rectangles. We don't do structure
+ assignments because some compilers are not good at that.
+
nxgl_rectoffset()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_rectoffset(FAR struct nxgl_rect_s *dest, + FAR const struct nxgl_rect_s *src, + nxgl_coord_t dx, nxgl_coord_t dy); ++
+ Description: + Offset the rectangle position by the specified dx, dy values. +
+ +nxgl_vectoradd()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_vectoradd(FAR struct nxgl_point_s *dest, + FAR const struct nxgl_point_s *v1, + FAR const struct nxgl_point_s *v2); ++
+ Description: + Add two 2x1 vectors and save the result to a third. +
+ +nxgl_vectorsubtract()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_vectsubtract(FAR struct nxgl_point_s *dest, + FAR const struct nxgl_point_s *v1, + FAR const struct nxgl_point_s *v2); ++
+ Description:
+ Add subtract vector v2 from vector v1 and return the result in vector dest.
+
nxgl_rectintersect()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_rectintersect(FAR struct nxgl_rect_s *dest, + FAR const struct nxgl_rect_s *src1, + FAR const struct nxgl_rect_s *src2); ++
+ Description: + Return the rectangle representing the intersection of the two rectangles. +
+ +nxgl_rectunion()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_rectunion(FAR struct nxgl_rect_s *dest, + FAR const struct nxgl_rect_s *src1, + FAR const struct nxgl_rect_s *src2); ++
+ Description:
+ Given two rectanges, src1 and src2, return the larger rectangle that
+ contains both, dest.
+
nxgl_nonintersecting()Function Prototype:
++#include <nuttx/nx/nxglib.h> +nxgl_nonintersecting(FAR struct nxgl_rect_s result[4], + FAR const struct nxgl_rect_s *rect1, + FAR const struct nxgl_rect_s *rect2); ++
+ 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()).
+
nxgl_rectoverlap()Function Prototype:
++#include <nuttx/nx/nxglib.h> +bool nxgl_rectoverlap(FAR struct nxgl_rect_s *rect1, + FAR struct nxgl_rect_s *rect2); ++
+ Description: + Return true if the two rectangles overlap. +
+ +nxgl_rectinside()Function Prototype:
++#include <nuttx/nx/nxglib.h> +bool nxgl_rectinside(FAR const struct nxgl_rect_s *rect, + FAR const struct nxgl_point_s *pt); ++
+ Description:
+ Return true if the point pt lies within rect.
+
nxgl_rectsize()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_rectsize(FAR struct nxgl_size_s *size, + FAR const struct nxgl_rect_s *rect); ++
+ Description: + Return the size of the specified rectangle. +
+ +nxgl_nullrect()Function Prototype:
++#include <nuttx/nx/nxglib.h> +bool nxgl_nullrect(FAR const struct nxgl_rect_s *rect); ++
+ Description: + Return true if the area of the retangle is <= 0. +
+ +nxgl_runoffset()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_runoffset(FAR struct nxgl_run_s *dest, + FAR const struct nxgl_run_s *src, + nxgl_coord_t dx, nxgl_coord_t dy); ++
+ Description:
+ Offset the run position by the specified dx, dy values.
+
nxgl_runcopy()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_runcopy(FAR struct nxgl_run_s *dest, + FAR const struct nxgl_run_s *src); ++
+ Description:
+ This is essentially memcpy()for runs. We don't do structure assignments
+ because some compilers are not good at that.
+
nxgl_trapoffset()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_trapoffset(FAR struct nxgl_trapezoid_s *dest, + FAR const struct nxgl_trapezoid_s *src, + nxgl_coord_t dx, nxgl_coord_t dy); ++
+ Description:
+ Offset the trapezoid position by the specified dx, dy values.
+
nxgl_trapcopy()Function Prototype:
++#include <nuttx/nx/nxglib.h> +void nxgl_trapcopy(FAR struct nxgl_trapezoid_s *dest, + FAR const struct nxgl_trapezoid_s *src); ++
+ Description:
+ This is essentially memcpy()for trapezoids. We don't do structure
+ assignments because some compilers are not good at that.
+
nxgl_colorcopyFunction Prototype:
++#include <nuttx/nx/nxglib.h> +nxgl_colorcopy(nxgl_mxpixel_t dest[CONFIG_NX_NPLANES], + const nxgl_mxpixel_t src[CONFIG_NX_NPLANES]); ++
+ 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.
+
nxgl_splitlineFunction Prototype:
++#include <nuttx/nx/nxglib.h> +int nxgl_splitline(FAR struct nxgl_vector_s *vector, FAR struct nxgl_trapezoid_s *traps, + FAR struct nxgl_rect_s *rect, nxgl_coord_t linewidth); ++
+ 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: +
+y1 == y2 then the line is horizontal and is better represented as a rectangle.
+ x1 == x2 then the line is vertical and also better represented as a rectangle.
+ + Input parameters: +
+
vector
+ traps
+ rect
+ + Returned value: +
+
+ 0: Line successfully broken up into three trapezoids.
+ Values in traps[0], traps[1], and traps[2] are valid.
+
+ 1: Line successfully represented by one trapezoid.
+ Value in traps[1] is valid.
+
+ 2: Line successfully represented by one rectangle.
+ Value in rect is valid
+
+ <0: On errors, a negated errno value is returned.
+
+
nxgl_circlepts+#include <nuttx/nx/nxglib.h> +void nxgl_circlepts(FAR const struct nxgl_point_s *center, nxgl_coord_t radius, + FAR struct nxgl_point_s *circle); ++
+ 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: +
+
center
+ radius
+ circle
+ + Returned value: None +
+ +nxgl_circletraps+#include <nuttx/nx/nxglib.h> +oid nxgl_circletraps(FAR const struct nxgl_point_s *center, nxgl_coord_t radius, + FAR struct nxgl_trapezoid_s *circle); ++
+ 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: +
+
center
+ radius
+ circle
+ + Returned value: None +
+ +
+ The default server message queue name used by the
+ nx_run() macro:
+
+#define NX_DEFAULT_SERVER_MQNAME "/dev/nxs" ++ +
+ Mouse button bits: +
++#define NX_MOUSE_NOBUTTONS 0x00 +#define NX_MOUSE_LEFTBUTTON 0x01 +#define NX_MOUSE_CENTERBUTTON 0x02 +#define NX_MOUSE_RIGHTBUTTON 0x04 ++ +
+ The interface to the NX server is managed using a opaque handle: +
++typedef FAR void *NXHANDLE; ++ +
+ The interface to a specific window is managed using an opaque handle: +
++typedef FAR void *NXWINDOW; ++ +
+ 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().
+
+struct nx_callback_s
+{
+ void (*redraw)(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
+ bool more, FAR void *arg);
+ void (*position)(NXWINDOW hwnd, FAR const struct nxgl_size_s *size,
+ FAR const struct nxgl_point_s *pos,
+ FAR const struct nxgl_rect_s *bounds,
+ FAR void *arg);
+#ifdef CONFIG_NX_XYINPUT
+ void (*mousein)(NXWINDOW hwnd, FAR const struct nxgl_point_s *pos,
+ uint8_t buttons, FAR void *arg);
+#endif
+#ifdef CONFIG_NX_KBD
+ void (*kbdin)(NXWINDOW hwnd, uint8_t nch, FAR const uint8_t *ch, FAR void *arg);
+#endif
+};
+
+
+redraw()Callback Function Prototype:
++void redraw(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, + bool more, FAR void *arg); ++
+ Description: + NX requests that the client re-draw the portion of the window within + with rectangle. +
++ Input Parameters: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd()
+ rect
+ more
+ arg
+ nx_openwindow())
+ + Returned Value: None +
+ +position()Callback Function Prototype:
++void position(NXWINDOW hwnd, FAR const struct nxgl_size_s *size, + FAR const struct nxgl_point_s *pos, + FAR const struct nxgl_rect_s *bounds, + FAR void *arg); ++
+ Description: + The size or position of the window has changed (or the window was + just created with zero size. +
++ Input Parameters: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd()
+ size
+ pos
+ bounds
+ arg
+ nx_openwindow())
+ + Returned Value: None +
+ +mousein()Callback Function Prototype:
++#ifdef CONFIG_NX_XYINPUT +void mousein(NXWINDOW hwnd, FAR const struct nxgl_point_s *pos, + uint8_t buttons, FAR void *arg); +#endif ++
+ Description: + New mouse data is available for the window +
++ Input Parameters: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd()
+ pos
+ buttons
+ NX_MOUSE_* definitions
+ arg
+ nx_openwindow())
+ + Returned Value: None +
+ +kbdin()Callback Function Prototype:
++#ifdef CONFIG_NX_KBD +void (*kbdin)(NXWINDOW hwnd, uint8_t nch, FAR const uint8_t *ch, FAR void *arg); +#endif ++
+ Description: + New keyboard/keypad data is available for the window. +
++ Input Parameters: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd()
+ nch
+ ch
+ arg
+ nx_openwindow())
+ + Returned Value: None +
+ +nx_runinstance() (and nx_run() macro)Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +#ifdef CONFIG_NX_MULTIUSER +int nx_runinstance(FAR const char *mqname, FAR struct fb_vtable_s *fb); +#define nx_run(fb) nx_runinstance(NX_DEFAULT_SERVER_MQNAME, dev) +#endif ++
+ 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: +
mqname
+ dev
+
+ Returned Value:
+ This function usually does not return. If it does return, it will
+ return ERROR and errno will be set appropriately.
+
nx_connectinstance() (and nx_connect() macro)Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +#ifdef CONFIG_NX_MULTIUSER +NXHANDLE nx_connectinstance(FAR const char *svrmqname); +#define nx_connect(cb) nx_connectinstance(NX_DEFAULT_SERVER_MQNAME) +#endif ++
+ 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: +
+nx_connect() 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: +
svrmqname
+ + Returned Value: +
+errno is set appropriately.
+nx_open()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +#ifndef CONFIG_NX_MULTIUSER +NXHANDLE nx_open(FAR struct fb_vtable_s *dev); +#endif ++
+ 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: +
dev
+ cb
+ + Returned Value: +
+errno is set appropriately.
+nx_disconnect()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +#ifdef CONFIG_NX_MULTIUSER +void nx_disconnect(NXHANDLE handle); +#endif ++
+ 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: +
handle
+ nx_connect().
+ + Returned Value: None. +
+ +nx_close()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +#ifndef CONFIG_NX_MULTIUSER +void nx_close(NXHANDLE handle); +#endif ++
+ Description:
+ Close the single user NX interface. nx_close is single-user equivalent
+ of nx_disconnect().
+
+ Single user mode only! +
++ Input Parameters: +
handle
+ nx_open().
+ + Returned Value: None +
+ +nx_eventhandler()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +#ifdef CONFIG_NX_MULTIUSER +int nx_eventhandler(NXHANDLE handle); +#else +# define nx_eventhandler(handle) (OK) +#endif ++
+ 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: +
handle
+ nx_connect().
+ + Returned Value: +
+OK: No errors occurred. If CONFIG_NX_BLOCKING is defined,
+ then one or more server messages were processed.
+ ERROR: An error occurred and errno has been set appropriately.
+ Of particular interest, it will return errno == EHOSTDOWN when the
+ server is disconnected. After that event, the handle can no longer be used.
+ nx_eventnotify()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +#if defined(CONFIG_NX_MULTIUSER) && !defined(CONFIG_DISABLE_SIGNALS) +int nx_eventnotify(NXHANDLE handle, int signo); +#else +# define nx_eventnotify(handle, signo) (OK) +#endif ++
+ 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():
+
nx_eventnotify() again.
+ + Input Parameters: +
handle
+ nx_connect().
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_openwindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +NXWINDOW nx_openwindow(NXHANDLE handle, + FAR const struct nx_callback_s *cb, + FAR void *arg); ++
+ Description: Create a new window. +
++ Input Parameters: +
handle
+ nx_connect()
+ or nx_open().
+ cb
+ arg
+ + Returned Value: +
+errno is set appropriately.
+nx_closewindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_closewindow(NXWINDOW hwnd); ++
+ Description:
+ Destroy a window created by nx_openwindow() window.
+
+ Input Parameters: +
hwnd
+ nx_openwindow()
+ that identifies the window to be destroyed.
+ This handle must not have been one returned by
+ nx_requestbkgd().
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_requestbkgd()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_requestbkgd(NXHANDLE handle, + FAR const struct nx_callback_s *cb, + FAR void *arg); ++
+ 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: +
+CONFIG_NX_MULTIUSER as well.
+ + This API only requests the handle of the background window. That + handle will be returned asynchronously in a subsequent position and + redraw callbacks. +
++ Cautions: +
+nx_setposition(),
+ nx_setsize(),
+ nx_raise(), or
+ nx_lower().
+ nx_requestbkgd() nor
+ nx_releasebkgd () should be called more than once.
+ Multiple instances of the background window are not supported.
+ + Input Parameters: +
handle
+ nx_connect()
+ or nx_open().
+ cb
+ arg
+ nx_openwindow())
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_releasebkgd()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_releasebkgd(NXWINDOW hwnd); ++
+ Description:
+ Release the background window previously acquired using
+ nx_requestbkgd()
+ and return control of the background to NX.
+
+ Input Parameters: +
handle
+ nx_requestbkgd().
+ This handle must not have been one created by
+ nx_openwindow().
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_getposition()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_getposition(NXWINDOW hwnd); ++
+ 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: +
hwnd
+ nx_openwindow() or
+ nx_requestbkgd().
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_setposition()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_setposition(NXWINDOW hwnd, FAR struct nxgl_point_s *pos); ++
+ Description: + Set the position and size for the selected window. +
++ Input Parameters: +
hwnd
+ nx_openwindow().
+ This handle must not have been created by
+ nx_requestbkgd().
+ pos
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_setsize()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_setsize(NXWINDOW hwnd, FAR struct nxgl_size_s *size); ++
+ Description: Set the size of the selected window. +
++ Input Parameters: +
hwnd
+ nx_openwindow().
+ This handle must not have been created by
+ nx_requestbkgd().
+ size
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_raise()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_raise(NXWINDOW hwnd); ++
+ Description: Bring the specified window to the top of the display. +
++ Input Parameters: +
hwnd
+ nx_openwindow().
+ This handle must not have been created by
+ nx_requestbkgd().
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_lower()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_lower(NXWINDOW hwnd); ++
+ Description: Lower the specified window to the bottom of the display. +
++ Input Parameters: +
hwnd
+ nx_openwindow().
+ This handle must not have been created by
+ nx_requestbkgd().
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_fill()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_fill(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Fill the specified rectangle in the window with the specified color. +
++ Input Parameters: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd()
+ rect
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_getrectangle()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +void nx_getrectangle(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, + unsigned int plane, FAR uint8_t *dest, + unsigned int deststride); ++
+ 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: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd()
+ rect
+ plane
+ dest
+ deststride
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_filltrapezoid()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_filltrapezoid(NXWINDOW hwnd, FAR const struct nxgl_rect_s *clip, + FAR const struct nxgl_trapezoid_s *trap, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Fill the specified trapezoidal region in the window with the specified color. +
++ Input Parameters: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd()
+ clip
+ trap
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_drawline()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_drawline(NXWINDOW hwnd, FAR struct nxgl_vector_s *vector, + nxgl_coord_t width, nxgl_mxpixel_t color[CONFIG_NX_NPLANES], + uint8_t caps); ++
+ 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: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd()
+ vector
+ width
+ color
+ caps
+ +/* Line caps */ + +#define NX_LINECAP_NONE 0x00, /* No line caps */ +#define NX_LINECAP_PT1 0x01 /* Line cap on pt1 on of the vector only */ +#define NX_LINECAP_PT2 0x02 /* Line cap on pt2 on of the vector only */ +#define NX_LINECAP_BOTH 0x03 /* Line cap on both ends of the vector only */ +
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_drawcircle()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_drawcircle(NXWINDOW hwnd, FAR const struct nxgl_point_s *center, + nxgl_coord_t radius, nxgl_coord_t width, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Draw a circular outline using the specified line thickness and color. +
++ Input Parameters: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd()
+ center
+ radius
+ width
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_fillcircle()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_fillcircle(NXWINDOW hwnd, FAR const struct nxgl_point_s *center, + nxgl_coord_t radius, nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Fill a circular region using the specified color. +
++ Input Parameters: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd()
+ center
+ radius
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_setbgcolor()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_setbgcolor(NXHANDLE handle, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: Set the color of the background. +
++ Input Parameters: +
handle
+ nx_openwindow()
+ or nx_requestbkgd()
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_move()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_move(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, + FAR const struct nxgl_point_s *offset); ++
+ Description: Move a rectangular region within the window. +
++ Input Parameters: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd() that specifies
+ the window within which the move is to be done
+ rect
+ offset
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_bitmap()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +int nx_bitmap(NXWINDOW hwnd, FAR const struct nxgl_rect_s *dest, + FAR const void *src[CONFIG_NX_NPLANES], + FAR const struct nxgl_point_s *origin, + unsigned int stride); ++
+ Description: + Copy a rectangular region of a larger image into the rectangle in the + specified window. +
++ Input Parameters: +
hwnd
+ nx_openwindow()
+ or nx_requestbkgd() that specifies the
+ window that will receive the bitmap image.
+ dest
+ src
+ CONFIG_NX_NPLANES (probably 1).
+ origin
+ stride
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nx_kbdin()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +#ifdef CONFIG_NX_KBD +int nx_kbdchin(NXHANDLE handle, uint8_t ch); +int nx_kbdin(NXHANDLE handle, uint8_t nch, FAR const uint8_t *ch); +#endif ++
+ 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
+
nx_mousein()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> + +#ifdef CONFIG_NX_XYINPUT +int nx_mousein(NXHANDLE handle, nxgl_coord_t x, nxgl_coord_t y, uint8_t buttons); +#endif ++
+ 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
+
NXTK)+ NXTK implements where the framed window. + NX framed windows consist of three components within one NX window: +
++ 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: +
+nxtk_openwindow();
+ Separate toolbar sub-window callbakcs are reigistered when the toolbar
+ is added using nxtk_opentoolbar().
+ (NOTES: (1) only the client sub-window receives keyboard input and,
+ (2) border callbacks are not currently accessible by the user).
+ NXTK Types()+ This is the handle that can be used to access the window data region. +
++typedef FAR void *NXTKWINDOW; ++ +
nxtk_openwindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +NXTKWINDOW nxtk_openwindow(NXHANDLE handle, + FAR const struct nx_callback_s *cb, + FAR void *arg); ++
+ Description: Create a new, framed window. +
++ Input Parameters: +
handle
+ nx_connect()
+ or nx_open().
+ cb
+ arg
+ nx_openwindow())
+ + Returned Value: +
+errno is set appropriately.
+nxtk_closewindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_closewindow(NXTKWINDOW hfwnd); ++
+ Description:
+ Close the window opened by nxtk_openwindow().
+
+ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_getposition()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_getposition(NXTKWINDOW hfwnd); ++
+ 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
+ nxtk_openwindow().
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_setposition()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_setposition(NXTKWINDOW hfwnd, FAR struct nxgl_point_s *pos); ++
+ 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
+ nxtk_openwindow().
+ pos
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_setsize()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_setsize(NXTKWINDOW hfwnd, FAR struct nxgl_size_s *size); ++
+ 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
+ nxtk_openwindow().
+ size
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_raise()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_raise(NXTKWINDOW hfwnd); ++
+ Description: + Bring the window containing the specified client sub-window to the top + of the display. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow()
+ specifying the window to be raised.
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_lower()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_lower(NXTKWINDOW hfwnd); ++
+ Description: + Lower the window containing the specified client sub-window to the + bottom of the display. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow()
+ specifying the window to be lowered.
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_fillwindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_fillwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Fill the specified rectangle in the client window with the specified color. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+ rect
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_getwindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +void nxtk_getwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, + unsigned int plane, FAR uint8_t *dest, + unsigned int deststride); ++
+ 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
+ nxtk_openwindow().
+ rect
+ plane
+ dest
+ deststride
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_filltrapwindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_filltrapwindow(NXTKWINDOW hfwnd, + FAR const struct nxgl_trapezoid_s *trap, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Fill the specified trapezoid in the client window with the specified color +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+ trap
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_drawlinewindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_drawlinewindow(NXTKWINDOW hfwnd, FAR struct nxgl_vector_s *vector, + nxgl_coord_t width, nxgl_mxpixel_t color[CONFIG_NX_NPLANES], + uint8_t caps); ++
+ 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: +
hfwnd
+ nxtk_openwindow().
+ vector
+ width
+ color
+ caps
+ +/* Line caps */ + +#define NX_LINECAP_NONE 0x00, /* No line caps */ +#define NX_LINECAP_PT1 0x01 /* Line cap on pt1 on of the vector only */ +#define NX_LINECAP_PT2 0x02 /* Line cap on pt2 on of the vector only */ +#define NX_LINECAP_BOTH 0x03 /* Line cap on both ends of the vector only */ +
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_drawcirclewindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_drawcirclewindow(NXTKWINDOW hfwnd, FAR const struct nxgl_point_s *center, + nxgl_coord_t radius, nxgl_coord_t width, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Draw a circular outline using the specified line thickness and color. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+ center
+ radius
+ width
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_fillcirclewindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_fillcirclewindow(NXWINDOW hfwnd, FAR const struct nxgl_point_s *center, + nxgl_coord_t radius, nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Fill a circular region using the specified color. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+ center
+ radius
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_movewindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_movewindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, + FAR const struct nxgl_point_s *offset); ++
+ Description: + Move a rectangular region within the client sub-window of a framed window. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow()
+ specifying the client sub-window within which the move is to be done.
+ rect
+ offset
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_bitmapwindow()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_bitmapwindow(NXTKWINDOW hfwnd, + FAR const struct nxgl_rect_s *dest, + FAR const void *src[CONFIG_NX_NPLANES], + FAR const struct nxgl_point_s *origin, + unsigned int stride); ++
+ Description: + Copy a rectangular region of a larger image into the rectangle in the + specified client sub-window. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow()
+ specifying the client sub-window that will receive the bitmap.
+ dest
+ src
+ CONFIG_NX_NPLANES (probably 1).
+ origin
+ stride
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_opentoolbar()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_opentoolbar(NXTKWINDOW hfwnd, nxgl_coord_t height, + FAR const struct nx_callback_s *cb, + FAR void *arg); ++
+ Description: + Create a tool bar at the top of the specified framed window. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+ height
+ cb
+ arg
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_closetoolbar()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_closetoolbar(NXTKWINDOW hfwnd); ++
+ Description: + Remove the tool bar at the top of the specified framed window. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_filltoolbar()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_filltoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Fill the specified rectangle in the toolbar sub-window with the specified color. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+ rect
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_gettoolbar()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_gettoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, + unsigned int plane, FAR uint8_t *dest, + unsigned int deststride); ++
+ 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
+ nxtk_openwindow().
+ rect
+ plane
+ dest
+ deststride
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_filltraptoolbar()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_filltraptoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_trapezoid_s *trap, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Fill the specified trapezoid in the toolbar sub-window with the specified color. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+ trap
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_drawlinetoolbar()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_drawlinetoolbar(NXTKWINDOW hfwnd, FAR struct nxgl_vector_s *vector, + nxgl_coord_t width, nxgl_mxpixel_t color[CONFIG_NX_NPLANES], + uint8_t caps); + ++
+ 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: +
hfwnd
+ nxtk_openwindow().
+ vector
+ width
+ color
+ caps
+ +/* Line caps */ + +#define NX_LINECAP_NONE 0x00, /* No line caps */ +#define NX_LINECAP_PT1 0x01 /* Line cap on pt1 on of the vector only */ +#define NX_LINECAP_PT2 0x02 /* Line cap on pt2 on of the vector only */ +#define NX_LINECAP_BOTH 0x03 /* Line cap on both ends of the vector only */ +
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_drawcircletoolbar()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_drawcircletoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_point_s *center, + nxgl_coord_t radius, nxgl_coord_t width, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Draw a circular outline using the specified line thickness and color. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+ center
+ radius
+ width
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_fillcircletoolbar()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_fillcircletoolbar(NXWINDOW hfwnd, FAR const struct nxgl_point_s *center, + nxgl_coord_t radius, nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); ++
+ Description: + Fill a circular region using the specified color. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+ center
+ radius
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_movetoolbar()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_movetoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, + FAR const struct nxgl_point_s *offset); ++
+ Description: + Move a rectangular region within the toolbar sub-window of a framed window. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+ rect
+ offset
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
nxtk_bitmaptoolbar()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nx.h> +#include <nuttx/nx/nxtk.h> + +int nxtk_bitmaptoolbar(NXTKWINDOW hfwnd, + FAR const struct nxgl_rect_s *dest, + FAR const void *src[CONFIG_NX_NPLANES], + FAR const struct nxgl_point_s *origin, + unsigned int stride); ++
+ Description: + Copy a rectangular region of a larger image into the rectangle in the + specified toolbar sub-window. +
++ Input Parameters: +
hfwnd
+ nxtk_openwindow().
+ dest
+ src
+ origin
+ stride
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately
+
NXFONTS)NXFONTS Types()+ This structures provides the metrics for one glyph: +
+
+struct nx_fontmetric_s
+{
+ uint32_t stride : 2; /* Width of one font row in bytes */
+ uint32_t width : 6; /* Width of the font in bits */
+ uint32_t height : 6; /* Height of the font in rows */
+ uint32_t xoffset : 6; /* Top, left-hand corner X-offset in pixels */
+ uint32_t yoffset : 6; /* Top, left-hand corner y-offset in pixels */
+ uint32_t unused : 6;
+};
+
+
++ This structure binds the glyph metrics to the glyph bitmap: +
+
+struct nx_fontbitmap_s
+{
+ struct nx_fontmetric_s metric; /* Character metrics */
+ FAR const uint8_t *bitmap; /* Pointer to the character 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).
+
+struct nx_fontset_s
+{
+ uint8_t first; /* First bitmap character code */
+ uint8_t nchars; /* Number of bitmap character codes */
+ FAR const struct nx_fontbitmap_s *bitmap;
+};
+
+
++ This structure describes the overall fontset: +
+
+struct nx_font_s
+{
+ uint8_t mxheight; /* Max height of one glyph in rows */
+ uint8_t mxwidth; /* Max width of any glyph in pixels */
+ uint8_t mxbits; /* Max number of bits per character code */
+ uint8_t spwidth; /* The width of a space in pixels */
+};
+
+
+nxf_getfonthandle()Function Prototype:
++#include <nuttx/nx/nxfonts.h> + +NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid); ++
+ Description: + Given a numeric font ID, return a handle that may be subsequently be used to access the font data sets. +
++ Input Parameters: +
fontid
+ + Returned Value: + A handle that may be subsequently be used to access the font data sets. +
+ +nxf_getfontset()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nxfonts.h> + +FAR const struct nx_font_s *nxf_getfontset(NXHANDLE handle); ++
+ Description: + Return information about the current font set. +
++ Input Parameters: +
handle
+ nxf_getfonthandle().
+
+ Returned Value:
+ An instance of struct nx_font_s describing the font set.
+
nxf_getbitmap()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nxfonts.h> + +FAR const struct nx_fontbitmap_s *nxf_getbitmap(NXHANDLE handle, uint16_t ch); ++
+ Description: + Return font bitmap information for the selected character encoding. +
++ Input Parameters: +
ch
+ handle
+ nxf_getfonthandle().
+
+ Returned Value:
+ An instance of struct nx_fontbitmap_s describing the glyph.
+
nxf_convert_*bpp()Function Prototype:
++#include <nuttx/nx/nxglib.h> +#include <nuttx/nx/nxfonts.h> + +int nxf_convert_2bpp(FAR uint8_t *dest, uint16_t height, + uint16_t width, uint16_t stride, + FAR const struct nx_fontbitmap_s *bm, + nxgl_mxpixel_t color); +int nxf_convert_4bpp(FAR uint8_t *dest, uint16_t height, + uint16_t width, uint16_t stride, + FAR const struct nx_fontbitmap_s *bm, + nxgl_mxpixel_t color); +int nxf_convert_8bpp(FAR uint8_t *dest, uint16_t height, + uint16_t width, uint16_t stride, + FAR const struct nx_fontbitmap_s *bm, + nxgl_mxpixel_t color); +int nxf_convert_16bpp(FAR uint16_t *dest, uint16_t height, + uint16_t width, uint16_t stride, + FAR const struct nx_fontbitmap_s *bm, + nxgl_mxpixel_t color); +int nxf_convert_24bpp(FAR uint32_t *dest, uint16_t height, + uint16_t width, uint16_t stride, + FAR const struct nx_fontbitmap_s *bm, + nxgl_mxpixel_t color); +int nxf_convert_32bpp(FAR uint32_t *dest, uint16_t height, + uint16_t width, uint16_t stride, + FAR const struct nx_fontbitmap_s *bm, + nxgl_mxpixel_t color); ++
+ Description: Convert the 1BPP font to a new pixel depth. +
++ Input Parameters: +
dest
+ height
+ width
+ stride
+ bm
+ color
+
+ Returned Value:
+ OK on success;
+ ERROR on failure with errno set appropriately.
+
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.
+
apps/examples/nx.
+ This is a test of windows, optionally with toolbars.
+ Two windows are created, re-sized, moved, raise lowered.
+ Simulated mouse and keyboard input is provided.
+ apps/examples/nxhello.
+ This is intended to be simplest NX test:
+ It simply displays the words "Hello, World!" centered on the display.
+ apps/examples/nxtext.
+ This illustrates how fonts may be managed to provide scrolling text windows.
+ Pop-up windows are included to verify the clipping and re-drawing of the text display.
+ + 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
+ |
+
+ 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.
+
+
libnx/nx
+ graphics/nxglib and libnx/nxglib
+ graphics/nxbe
+ nxmu and nxsu below).
+ It contains most of the important window management logic: clipping, window controls,
+ window drawing, etc.
+
+ graphics/nxsu1
+ nxbe), it implements a
+ single threaded, single user windowing system.
+ The files in this directory present the window APIs described in
+ include/nuttx/nx/nx.h.
+ The single user front-end is selected when CONFIG_NX_MULTIUSER is not
+ defined in the NuttX configuration file.
+
+ graphics/nxmu and libnx/nxmu
+ nxbe), it implements a
+ multi-threaded, multi-user windowing system.
+ The files in this directory present the window APIs described in
+ include/nuttx/nx/nx.h.
+ The multi-user front end includes a graphics server that executes on its own thread;
+ multiple graphics clients then communicate with the server via a POSIX message
+ queue to serialize window operations from many threads.
+ The multi-user front-end is selected when CONFIG_NX_MULTIUSER is defined
+ in the NuttX configuration file.
+
+ libnx/nxfonts
+ include/nuttx/nx/nxfonts.h.
+
+ libnx/nxtk
+ include/nuttx/nx/nxtk.h.
+
+ nuttx/../nxwidgets
+ graphics/nxterm
+ include/nuttx/nx/nxterm.h.
+
+ 1
+ Appendix B NX Configuration Options+ |
+
CONFIG_NX
+ Enables overall support for graphics library and NX
+ CONFIG_NX_NPLANES:
+ CONFIG_NX_DISABLE_1BPP, CONFIG_NX_DISABLE_2BPP,
+ CONFIG_NX_DISABLE_4BPP, CONFIG_NX_DISABLE_8BPP
+ CONFIG_NX_DISABLE_16BPP, CONFIG_NX_DISABLE_24BPP, and
+ CONFIG_NX_DISABLE_32BPP:
+ CONFIG_NX_PACKEDMSFIRST:
+ CONFIG_NX_LCDDRIVER:
+ include/nuttx/video/fb.h).
+ If this option is defined, NX will build to use an LCD driver (see include/nuttx/lcd/lcd.h).
+ CONFIG_NX_ANTIALIASING:
+ CONFIG_NX_XYINPUT:
+ CONFIG_NX_KBD:
+ CONFIG_NX_WRITEONLY:
+ CONFIG_NX_LCDDRIVER and CONFIG_LCD_NOGETRUN
+ are defined.
+ CONFIG_NX_MULTIUSER:
+ CONFIG_NX_BLOCKING
+ nx_eventhandler() will not return until a message is received and processed.
+ CONFIG_NX_MXSERVERMSGS and CONFIG_NX_MXCLIENTMSGS
+ CONFIG_PREALLOC_MQ_MSGS controls how many
+ messages are pre-allocated).
+ CONFIG_NXTK_BORDERWIDTH:
+ CONFIG_NXTK_BORDERCOLOR1, CONFIG_NXTK_BORDERCOLOR2, and CONFIG_NXTK_BORDERCOLOR3:
+ CONFIG_NXTK_BORDERCOLOR2
+ CONFIG_NXTK_BORDERCOLOR3
+ CONFIG_NXTK_AUTORAISE:
+ CONFIG_NXFONTS_CHARBITS:
+ CONFIG_NXFONT_SANS17X22:
+ ID FONTID_SANS17X22 == 14).
+ CONFIG_NXFONT_SANS20X26:
+ ID FONTID_SANS20X26 == 15).
+ CONFIG_NXFONT_SANS23X27:
+ ID FONTID_SANS23X27 == 1).
+ CONFIG_NXFONT_SANS22X29:
+ ID FONTID_SANS22X29 == 2).
+ CONFIG_NXFONT_SANS28X37:
+ ID FONTID_SANS28X37 == 3).
+ CONFIG_NXFONT_SANS39X48:
+ ID FONTID_SANS39X48 == 4).
+ CONFIG_NXFONT_SANS17X23B:
+ ID FONTID_SANS17X23B == 16).
+ CONFIG_NXFONT_SANS20X27B:
+ ID FONTID_SANS20X27B == 17).
+ CONFIG_NXFONT_SANS22X29B:
+ FONTID_SANS22X29B == 5).
+ CONFIG_NXFONT_SANS28X37B:
+ FONTID_SANS28X37B == 6).
+ CONFIG_NXFONT_SANS40X49B:
+ FONTID_SANS40X49B == 7).
+ CONFIG_NXFONT_SERIF22X29:
+ FONTID_SERIF22X29 == 8).
+ CONFIG_NXFONT_SERIF29X37:
+ FONTID_SERIF29X37 == 9).
+ CONFIG_NXFONT_SERIF38X48:
+ FONTID_SERIF38X48 == 10).
+ CONFIG_NXFONT_SERIF22X28B:
+ FONTID_SERIF22X28B == 11).
+ CONFIG_NXFONT_SERIF27X38B:
+ FONTID_SERIF27X38B == 12).
+ CONFIG_NXFONT_SERIF38X49B:
+ FONTID_SERIF38X49B == 13).
+ General NxTerm settings.
+CONFIG_NXTERM:
+ NxTerm output text/graphics options:
+CONFIG_NXTERM_BPP:
+ CONFIG_NX_DISABLE_*BPP)
+ CONFIG_NXTERM_CURSORCHAR:
+ CONFIG_NXTERM_MXCHARS:
+ CONFIG_NXTERM_CACHESIZE:
+ CONFIG_NXTERM_CACHESIZE setting will control the size of the font cache (in number of glyphs).
+ Only that number of the most recently used glyphs will be retained.
+ Default: 16.
+ + NOTE: There can still be a race condition between the NxTerm driver and the + NX task. If you every see character corruption (especially when printing + a lot of data or scrolling), then increasing the value of+CONFIG_NXTERM_CACHESIZE+ is something that you should try. + Alternatively, you can reduce the size ofCONFIG_MQ_MAXMSGSIZEwhich will force NxTerm task to pace the server task. +CONFIG_NXTERM_CACHESIZEshould be larger thanCONFIG_MQ_MAXMSGSIZEin any event. +
CONFIG_NXTERM_LINESEPARATION:
+ CONFIG_NXTERM_NOWRAP:
+ NxTerm input options:
+CONFIG_NXTERM_NXKBDIN:
+ /dev/console).
+ If this option is set, then the interfacenxterm_kdbin() is enabled.
+ That interface may be driven by window callback functions so that keyboard input only goes to the top window.
+ CONFIG_NXTERM_KBDBUFSIZE:
+ CONFIG_NXTERM_NXKBDIN is enabled, then this value may be used to
+ define the size of the per-window keyboard input buffer. Default: 16
+ CONFIG_NXTERM_NPOLLWAITERS:
+
+ 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. +
++ Locate a font in BDF format. + There are many good BDF bitmap fonts bundled with X-11. + See this link, as an example, +
+
+ 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.
+
+ 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:
+
+ Define CONFIG_NXFONT_MYFONT=y in your NuttX configuration file.
+
+ 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:
+
+ 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
+...
+
+ + 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: +
+
+ 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 ++
+ 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 ++
+ 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 ++
+ 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.
+
+ 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
+};
+
+
+ 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:
+
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 ++
+ 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: +
++ 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. +
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:
+
| Function | +Special Setup/Notes | +Verified |
|---|---|---|
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 | +
| Function | +Special Setup/Notes | +Verified |
|---|---|---|
redraw() |
+ YES | +|
position() |
+ YES | +|
mousein() |
+ YES | +|
kbdin() |
+ YES | +
| Function | +Special Setup/Notes | +Verified |
|---|---|---|
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 file |
+ YES | +
nx_eventnotify() |
+ This is not used in the current version of apps/examples/nx,
+ was tested in a previous version) |
+ NO | +
nx_openwindow() |
+ Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the
+ <NuttX-Directory>/.config file |
+
+ YES | +
nx_closewindow() |
+ Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the
+ <NuttX-Directory>/.config file |
+ YES | +
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 file |
+ YES | +
nx_setsize() |
+ Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the
+ <NuttX-Directory>/.config file |
+ YES | +
nx_raise() |
+ Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the
+ <NuttX-Directory>/.config file |
+ YES | +
nx_lower() |
+ Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the
+ <NuttX-Directory>/.config file |
+ YES | +
nx_fill() |
+ Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the
+ <NuttX-Directory>/.config file |
+ YES | +
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 file |
+ YES | +
nx_bitmap() |
+ Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the
+ <NuttX-Directory>/.config file. |
+ YES | +
nx_kbdin() |
+ YES | +|
nx_mousein() |
+ YES | +
| Function | +Special Setup/Notes | +Verified |
|---|---|---|
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 | +
| Function | +Special Setup/Notes | +Verified |
|---|---|---|
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 | +
+ NFS Client How-To+Last Updated: June 18, 2012 + |
+
+ Table of Contents+ |
+
+
|
+
+ 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:
+
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.
+ CONFIG_NET=y. General networking support.
+ CONFIG_NET_UDP=y. Support for UDP.
+
+ Mount Interface+ |
+
+ A low-level, C-callable interface is provided to mount a file system.
+ That interface is called mount() and is mentioned in the porting guide and is prototyped in the header file include/sys/mount.h:
+
+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:
+
<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.
+ <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).
+ <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.
+ + 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).
/etc/exports will typically look like this:
+
++directory machine1(option11,option12) ++
+ So for our example we export
+/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.
+
+# 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.
+
+ NuttShell (NSH)+Last Updated: February 8, 2016 + |
+
+ Table of Contents+ |
+
+
+ The NSH Library.
+ The
+ 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
+ Simple, Re-directed, and Background Commands. + The NuttShell (NSH) is a simple shell application. + NSH supports the following commands forms: + +
Where: +
+
+ [nice [-d <niceness>>]] <cmd> [> <file>|>> <file>] [&]
+
+ Where + 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. + +
+ Will execute the program named 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.
+
+ An +if <cmd> +then + [sequence of <cmd>] +else + [sequence of <cmd>] +fi ++ +
Looping Constructs.
+
+until <cmd> +do + [sequence of <cmd>] +done ++ + The + +
+
+ Environment Variables: + +
+ NSH Start-Up Script.
+ NSH supports options to provide a start up script for NSH. In general
+ this capability is enabled with
+ 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
/etc, resulting in:
++|--dev/ +| `-- ram0 +`--etc/ + `--init.d/ + `-- rcS ++ +# Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX + +mkrd -m 1 -s 512 1024 +mkfatfs /dev/ram1 +mount -t vfat /dev/ram1 /tmp ++ /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
+ NOTE:
+
+ All of the startup-behavior is contained in + Further Information. + See the section on Customizing the NuttShell for additional, more detailed information about the NSH start-up script and how to modify it. + + +
Command Syntax: ++[ <expression> ] +test <expression> ++
+ Synopsis.
+ These are two alternative forms of the same command. They support
+ evaluation of a boolean expression which sets 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 + +
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 ++ +
Command Syntax: ++arp [-a <ipaddr> |-d <ipaddr> |-s <ipaddr> <hwaddr>] ++ + Synopsis. + Access the OS ARP table. + +
+ Example: + ++nsh> arp -a 10.0.0.1 +nsh: arp: no such ARP entry: 10.0.0.1 + +nsh> arp -s 10.0.0.1 00:13:3b:12:73:e6 +nsh> arp -a 10.0.0.1 +HWAddr: 00:13:3b:12:73:e6 + +nsh> arp -d 10.0.0.1 +nsh> arp -a 10.0.0.1 +nsh: arp: no such ARP entry: 10.0.0.1 ++ +
Command Syntax: ++base64dec [-w] [-f] <string or filepath> ++ + Synopsis. + To be provided. + + +
Command Syntax: ++base64enc [-w] [-f] <string or filepath> ++ + Synopsis. + To be provided. + + +
Command Syntax: ++basename <path> [<suffix>] ++
+ Synopsis.
+ Extract the final string from a + +
Command Syntax: ++break ++
+ Synopsis.
+ The + +
Command Syntax: ++cat+
+ Synopsis.
+ This command copies and concatentates all of the files at
Command Syntax: ++cd [<dir-path>|-|~|..] ++
+ Synopsis.
+ Changes the current working directory ( + Forms: +
Command Syntax: ++cmp <path1> <path2> ++
+ Synopsis.
+ Compare of the contents of the file at
Command Syntax: ++cp <source-path> <dest-path> ++
+ Synopsis.
+ Copy of the contents of the file at
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:
+ +data -s "Sep 1 11:30:00 2011" ++ + + 24-hour time is used. + + +
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: + +
+nsh> ls -l /dev +/dev: + brw-rw-rw- 0 ram0 + crw-rw-rw- 0 zero +nsh> dd if=/dev/zero of=/dev/ram0 ++ + +nsh> ls -l /dev +/dev: + crw-rw-rw- 0 null + brw-rw-rw- 0 ram0 +nsh> dd if=/dev/ram0 of=/dev/null ++ +
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 ++ +
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
Command Syntax: ++dirname <path> ++
+ Synopsis.
+ Extract the path string leading up to the full + +
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). + + +
Command Syntax: ++exec <hex-address> ++
+ Synopsis.
+ Execute the user logic at address
Command Syntax: ++exit ++
+ Synopsis.
+ Exit NSH. Only useful for the serial front end if you have started some other tasks (perhaps
+ using the
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: +
Command Syntax: ++get [-b|-n] [-f <local-path>] -h <ip-address> <remote-path> ++
+ Synopsis.
+ Copy the file at Other options: +
Command Syntax: ++help [-v] [<cmd>] ++ + Synopsis. + Presents summary information about NSH commands to console. + +Options: +
Command Syntax: ++hexdump <file or device> ++ + Synopsis. + Dump data in hexadecimal format from a file or character device. + + + | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| + + | +|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ 2.24 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:
+
+ With one or no arguments, ifconfig will shows the
+ current configuration of the network and, perhaps, the status of ethernet
+ device:
+
+ifconfig +ifconfig [nic_name] ++
+ As an example: +
++nsh> ifconfig +eth0 HWaddr 00:18:11:80:10:06 + IPaddr:10.0.0.2 DRaddr:10.0.0.1 Mask:255.255.255.0 ++
+ If network statistics are enabled (CONFIG_NET_STATISTICS), then
+ this command will also show the detailed state of network.
+
+ 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 ++
+NOTE: This commands depends upon having the procfs file system configured into the system. +The procfs file system must also have been mounted with a command like: +
++nsh> mount -t procfs /proc ++ + +
+ 2.25 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.26 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.27 Install an OS module (insmod)+ |
+
Command Syntax:
++insmod <file-path> <module-name> ++
+ Synopsis. + Install the loadable OS module at <file-path> as module <module-name>. +
+Example:
++nsh> ls -l /mnt/romfs +/mnt/romfs: + dr-xr-xr-x 0 . + -r-xr-xr-x 9153 chardev +nsh> ls -l /dev +/dev: + crw-rw-rw- 0 console + crw-rw-rw- 0 null + brw-rw-rw- 0 ram0 + crw-rw-rw- 0 ttyS0 +nsh> lsmod +NAME INIT UNINIT ARG TEXT SIZE DATA SIZE +nsh> insmod /mnt/romfs/chardev mydriver +nsh> ls -l /dev +/dev: + crw-rw-rw- 0 chardev + crw-rw-rw- 0 console + crw-rw-rw- 0 null + brw-rw-rw- 0 ram0 + crw-rw-rw- 0 ttyS0 +nsh> lsmod +NAME INIT UNINIT ARG TEXT SIZE DATA SIZE +mydriver 20404659 20404625 0 20404580 552 204047a8 0 ++ +
+ 2.28 Send a signal to a task (kill)+ |
+
Command Syntax:
++kill -<signal> <pid> ++
+ Synopsis. + Send the <signal> to the task identified by <pid>. +
+Example:
++nsh> mkfifo /dev/fifo +nsh> cat /dev/fifo & +cat [2:128] +nsh> ps +PID PRI POLICY TYPE NPX STATE EVENT SIGMASK COMMAND + 0 0 FIFO Kthread --- Ready 00000000 Idle Task + 1 128 RR Task --- Running 00000000 init + 2 128 FIFO pthread --- Waiting Semaphore 00000000 <pthread>(51ea50) +nsh> kill -9 2 +nsh> ps +PID PRI POLICY TYPE NPX STATE EVENT SIGMASK COMMAND + 0 0 FIFO Kthread --- Ready 00000000 Idle Task + 1 128 RR Task --- Running 00000000 init +nsh> ++
+ NOTE:
+ NuttX does not support a FULL POSIX 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.29 Setup/teardown the Loop Device (losetup)+ |
+
Command Syntax 1:
++losetup [-o <offset>] [-r] <dev-path> <file-path> ++
+ Synopsis.
+ Setup the loop device at <dev-path> to access the file at <file-path> as a block device.
+ In the following example a 256K file is created (dd) and losetup is
+ used to make the file accessible as a block device.
+ A FAT file system is created (mkfatfs) and mounted (mount).
+ Files can then be managed on the loop-mounted file.
+
+nsh> dd if=/dev/zero of=/tmp/image bs=512 count=512 +nsh> ls -l /tmp +/tmp: + -rw-rw-rw- 262144 IMAGE +nsh> losetup /dev/loop0 /tmp/image +nsh> ls -l /dev +/dev: + brw-rw-rw- 0 loop0 +nsh> mkfatfs /dev/loop0 +nsh> mount -t vfat /dev/loop0 /mnt/example +nsh> ls -l /mnt +ls -l /mnt +/mnt: + drw-rw-rw- 0 example/ +nsh> echo "This is a test" >/mnt/example/atest.txt +nsh> ls -l /mnt/example +/mnt/example: + -rw-rw-rw- 16 ATEST.TXT +nsh> cat /mnt/example/atest.txt +This is a test +nsh> ++ + +
Command Syntax 2:
++losetup d <dev-path> ++
+ Synopsis. + Teardown the setup for the loop device at <dev-path>. +
+ +
+ 2.30 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:
+-R |
+ Show the contents of specified directory and all of its + sub-directories. | +
-s |
+ Show the size of the files along with the filenames in the + listing | +
-l |
+ Show size and mode information along with the filenames + in the listing. | +
+ 2.31 Show information about installed OS modules (lsmod)+ |
+
Command Syntax:
++lsmod ++
+ Synopsis. + Show information about the currently installed OS modules. This information includes: +
+NAME, string).INIT, hexadecimal).UNINIT, hexadecimal).ARG, hexadecimal).TEXT, hexadecimal).SIZE, decimal).DATA, hexadecimal).SIZE, decimal).Example:
++nsh> lsmod +NAME INIT UNINIT ARG TEXT SIZE DATA SIZE +mydriver 20404659 20404625 0 20404580 552 204047a8 0 ++ +
+ 2.32 Calculate MD5 (md5)+ |
+
Command Syntax:
++md5 [-f] <string or filepath> ++
+ Synopsis. + To be provided. +
+ +
+ 2.33 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.34 Show Current Tasks and Threads (ps)+ |
+
Command Syntax:
++ps ++
+ Synopsis. + Show the currently active threads and tasks. For example, +
++nsh> ps +PID PRI POLICY TYPE NPX STATE EVENT SIGMASK COMMAND + 0 0 FIFO Kthread --- Ready 00000000 Idle Task + 1 128 RR Task --- Running 00000000 init + 2 128 FIFO Task --- Waiting Semaphore 00000000 nsh_telnetmain() + 3 100 RR pthread --- Waiting Semaphore 00000000 <pthread>(21) +nsh> ++
+NOTE: This commands depends upon having the procfs file system configured into the system. +The procfs file system must also have been mounted with a command like: +
++nsh> mount -t procfs /proc ++ + +
+ 2.35 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.36 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.37 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.38 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.39 Mount a File System (mount)+ |
+
Command Syntax:
+
+mount -t <fstype> [-o <options>] <block-device> <dir-path>
+
+
+ Synopsis.
+ The mount command performs one of two different operations.
+ If no parameters are provided on the command line after the mount command, then the mount command will enumerate all of the current mountpoints on the console.
+
+ If the mount parameters are 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:
+
<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>
+ <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>
+ <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.
+ + 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.40 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.41 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.42 Lookup a network address (nslookup)+ |
+
Command Syntax:
++nslookup <host-name> ++
+ Synopsis.
+ Lookup and print the IP address associated with <host-name>.
+
+ 2.43 Change a User's Password (passwd)+ |
+
Command Syntax:
++passwd <username> <password> ++
+ Synopsis. + Set the password for the existing user <username> to <password>. +
+ +
+ 2.44 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.45 Shut the system down (poweroff)+ |
+
Command Syntax:
++poweroff ++
+ Synopsis. + Shutdown and power off the system immediately. + This command depends on hardware support to power down the system. +
+
+ NOTE: Supporting both the poweroff and shutdown commands is redundant.
+
+ 2.46 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.47 Show Current Working Directory (pwd)+ |
+
Command Syntax:
++pwd ++
+ Synopsis. + Show the current working directory. +
++nsh> cd /dev +nsh> pwd +/dev +nsh> ++ + +
+nsh> echo $PWD +/dev +nsh> ++ +
+ 2.48 Reboot the system (reboot)+ |
+
Command Syntax:
++reboot ++
+ Synopsis. + Reset and reboot the system immediately. + This command depends on hardware support to reset the system. +
++
+ NOTE: Supporting both the reboot and shutdown commands is redundant.
+
+ 2.49 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.50 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.51 Remove on OS Module (rmmod)+ |
+
Command Syntax:
++rmmod <module-name> ++
+ Synopsis. + Remove the loadable OS module with the <module-name>. + NOTE: An OS module can only be removed if it is not busy. +
+Example:
++nsh> lsmod +NAME INIT UNINIT ARG TEXT SIZE DATA SIZE +mydriver 20404659 20404625 0 20404580 552 204047a8 0 +nsh> rmmod mydriver +nsh> lsmod +NAME INIT UNINIT ARG TEXT SIZE DATA SIZE +nsh> ++ +
+ 2.52 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.53 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.54 Shut the system down (shutdown)+ |
+
Command Syntax:
++shutdown [--reboot] ++
+ Synopsis. + Shutdown and power off the system or, optionally, reset and reboot the system immediately. + This command depends on hardware support to power down or reset the system; one, both, or neither behavior may be supported. +
+
+ NOTE: The shutdown command duplicates the behavior of the poweroff and eboot commands.
+
+ 2.55 Wait for Seconds (sleep)+ |
+
Command Syntax:
++sleep <sec> ++
+ Synopsis.
+ Pause execution (sleep) for <sec> seconds.
+
+ 2.56 Time execution of another command (time)+ |
+
Command Syntax:
++time "<command>" ++
+ Synopsis. + Perform command timing. + This command will execute the following <command> string and then show how much time was required to execute the command. + Time is shown with a resolution of 100 microseconds which may be beyond the resolution of many configurations. + Note that the <command> must be enclosed in quotation marks if it contains spaces or other delimiters. +
+Example:
++nsh> time "sleep 2" + +2.0100 sec +nsh> ++
+ The additional 10 millseconds in this example is due to the way that the sleep command works: It always waits one system clock tick longer than requested and this test setup used a 10 millisecond periodic system + timer. + Sources of error could include various quantization errors, competing CPU usage, and the additional overhead of the time command execution itself which is included in the total. +
++ The reported time is the elapsed time from starting of the command to completion of the command. + This elapsed time may not necessarily be just the processing time for the command. + It may included interrupt level processing, for example. + In a busy system, command processing could be delayed if pre-empted by other, higher priority threads competing for CPU time. + So the reported time includes all CPU processing from the start of the command to its finish possibly including unrelated processing time during that interval. +
++ Notice that: +
++nsh> time "sleep 2 &" +sleep [3:100] + +0.0000 sec +nsh> ++
+ Since the sleep command is executed in background, the sleep command completes almost immediately. + As opposed to the following where the time command is run in background with the sleep command: +
++nsh> time "sleep 2" & +time [3:100] +nsh> +2.0100 sec ++ +
+ 2.57 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.58 Print system information (uname)+ |
+
Command Syntax:
++uname [-a | -imnoprsv] ++
+ Synopsis. + Print certain system information. With no options, the output is the same as -s. +
+
-a |
+ + Print all information, in the following order, except omit -p and -i if unknown: + | +
-s, -o |
+ + Print the operating system name (NuttX) + | +
-n |
+
+ Print the network node hostname (only availabel if CONFIG_NET=y)
+ |
+
-r |
+ + Print the kernel release + | +
-v |
+ + Print the kernel version + | +
-m |
+ + Print the machine hardware name + | +
-i |
+ + Print the machine platform name + | +
-p |
+ + Print "unknown" + | +
+ 2.59 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.60 URL Decode (urldecode)+ |
+
Command Syntax:
++urldecode [-f] <string or filepath> ++
+ Synopsis. + To be provided. +
+ +
+ 2.61 URL Encode (urlencode)+ |
+
Command Syntax:
++urlencode [-f] <string or filepath> ++
+ Synopsis. + To be provided. +
+ +
+ 2.62 Add a New User (useradd)+ |
+
Command Syntax:
++useradd <username> <password> ++
+ Synopsis. + Add a new user with <username> and <password>. +
+ +
+ 2.63 Delete a user (userdel)+ |
+
Command Syntax:
++userdel <username> ++
+ Synopsis. + Delete the user with the name <username>. +
+ +
+ 2.64 Wait for Microseconds (usleep)+ |
+
Command Syntax:
++usleep <usec> ++
+ Synopsis.
+ Pause execution (sleep) of <usec> microseconds.
+
+ 2.65 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.66 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
+| Command | +Depends on Configuration | +Can Be Disabled with | +
|---|---|---|
[ |
+ !CONFIG_NSH_DISABLESCRIPT |
+ CONFIG_NSH_DISABLE_TEST |
+
addroute |
+ CONFIG_NET && CONFIG_NET_ROUTE |
+ CONFIG_NSH_DISABLE_ADDROUTE |
+
arp |
+ CONFIG_NET && CONFIG_NET_ARP |
+ CONFIG_NSH_DISABLE_ARP |
+
base64dec |
+ CONFIG_NETUTILS_CODECS && CONFIG_CODECS_BASE64 |
+ CONFIG_NSH_DISABLE_BASE64DEC |
+
base64enc |
+ CONFIG_NETUTILS_CODECS && CONFIG_CODECS_BASE64 |
+ CONFIG_NSH_DISABLE_BASE64ENC |
+
basename |
+ + | CONFIG_NSH_DISABLE_BASENAME |
+
break |
+ !CONFIG_NSH_DISABLESCRIPT && !CONFIG_NSH_DISABLE_LOOPS |
+ + |
cat |
+ CONFIG_NFILE_DESCRIPTORS > 0 |
+ CONFIG_NSH_DISABLE_CAT |
+
cd |
+ !CONFIG_DISABLE_ENVIRON && CONFIG_NFILE_DESCRIPTORS > 0 |
+ CONFIG_NSH_DISABLE_CD |
+
cmp |
+ CONFIG_NFILE_DESCRIPTORS > 0 |
+ CONFIG_NSH_DISABLE_CMP |
+
cp |
+ CONFIG_NFILE_DESCRIPTORS > 0 |
+ CONFIG_NSH_DISABLE_CP |
+
date |
+ CONFIG_NSH_DISABLE_DATE |
+ |
dd |
+ CONFIG_NFILE_DESCRIPTORS > 0 |
+ CONFIG_NSH_DISABLE_DD |
+
delroute |
+ CONFIG_NET && CONFIG_NET_ROUTE |
+ CONFIG_NSH_DISABLE_DELROUTE |
+
df |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_READABLE3 |
+ CONFIG_NSH_DISABLE_DF |
+
dirname |
+ + | CONFIG_NSH_DISABLE_DIRNAME |
+
echo |
+ CONFIG_NSH_DISABLE_ECHO |
+ |
exec |
+ CONFIG_NSH_DISABLE_EXEC |
+ |
exit |
+ CONFIG_NSH_DISABLE_EXIT |
+ |
free |
+ CONFIG_NSH_DISABLE_FREE |
+ |
get |
+ CONFIG_NET && CONFIG_NET_UDP &&
+ CONFIG_NFILE_DESCRIPTORS > 0 && MTU >= 5581 |
+ CONFIG_NSH_DISABLE_GET |
+
help5 |
+ CONFIG_NSH_DISABLE_HELP |
+ |
hexdump |
+ CONFIG_NFILE_DESCRIPTORS > 0 |
+ CONFIG_NSH_DISABLE_HEXDUMP |
+
ifconfig |
+ CONFIG_NET && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_NET |
+ CONFIG_NSH_DISABLE_IFCONFIG |
+
ifdown |
+ CONFIG_NET && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_NET |
+ CONFIG_NSH_DISABLE_IFUPDOWN |
+
ifup |
+ CONFIG_NET && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_NET |
+ CONFIG_NSH_DISABLE_IFUPDOWN |
+
insmod |
+ CONFIG_MODULE |
+ CONFIG_NSH_DISABLE_MODCMDS |
+
kill |
+ !CONFIG_DISABLE_SIGNALS |
+ CONFIG_NSH_DISABLE_KILL |
+
losetup |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_DEV_LOOP |
+ CONFIG_NSH_DISABLE_LOSETUP |
+
ls |
+ CONFIG_NFILE_DESCRIPTORS > 0 |
+ CONFIG_NSH_DISABLE_LS |
+
lsmod |
+ CONFIG_MODULE && CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_MODULE |
+ CONFIG_NSH_DISABLE_MODCMDS |
+
md5 |
+ CONFIG_NETUTILS_CODECS && CONFIG_CODECS_HASH_MD5 |
+ CONFIG_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)4 |
+ CONFIG_NSH_DISABLE_MKDIR |
+
mkfatfs |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_FAT |
+ CONFIG_NSH_DISABLE_MKFATFS |
+
mkfifo |
+ CONFIG_NFILE_DESCRIPTORS > 0 |
+ CONFIG_NSH_DISABLE_MKFIFO |
+
mkrd |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_WRITABLE4 |
+ CONFIG_NSH_DISABLE_MKRD |
+
mount |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_READABLE3 |
+ CONFIG_NSH_DISABLE_MOUNT |
+
mv |
+ (((!CONFIG_DISABLE_MOUNTPOINT && CONFIG_FS_WRITABLE) || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS) && CONFIG_NFILE_DESCRIPTORS > 0)4 |
+ CONFIG_NSH_DISABLE_MV |
+
nfsmount |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_NET && CONFIG_NFS |
+ CONFIG_NSH_DISABLE_NFSMOUNT |
+
nslookup |
+ CONFIG_LIBC_NETDB && CONFIG_NETDB_DNSCLIENT |
+ CONFIG_NSH_DISABLE_NSLOOKUP |
+
passwd |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_WRITABLE && CONFIG_NSH_LOGIN_PASSWD |
+ CONFIG_NSH_DISABLE_PASSWD |
+
ping |
+ CONFIG_NET && CONFIG_NET_ICMP &&
+ CONFIG_NET_ICMP_PING && !CONFIG_DISABLE_SIGNALS |
+ CONFIG_NSH_DISABLE_PING |
+
ping6 |
+ CONFIG_NET && CONFIG_NET_ICMPv6 &&
+ CONFIG_NET_ICMPv6_PING && !CONFIG_DISABLE_SIGNALS |
+ CONFIG_NSH_DISABLE_PING6 |
+
poweroff |
+ CONFIG_BOARDCTL_POWEROFF |
+ CONFIG_NSH_DISABLE_POWEROFF |
+
ps |
+ CONFIG_FS_PROCFS && !CONFIG_FS_PROCFS_EXCLUDE_PROC |
+ CONFIG_NSH_DISABLE_PS |
+
put |
+ CONFIG_NET && CONFIG_NET_UDP &&
+ CONFIG_NFILE_DESCRIPTORS > 0 && MTU >= 5581,2 |
+ CONFIG_NSH_DISABLE_PUT |
+
pwd |
+ !CONFIG_DISABLE_ENVIRON && CONFIG_NFILE_DESCRIPTORS > 0 |
+ CONFIG_NSH_DISABLE_PWD |
+
reboot |
+ CONFIG_BOARD_RESET |
+ CONFIG_NSH_DISABLE_REBOOT |
+
rm |
+ (((!CONFIG_DISABLE_MOUNTPOINT && CONFIG_FS_WRITABLE) || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS) && CONFIG_NFILE_DESCRIPTORS > 0)4 |
+ CONFIG_NSH_DISABLE_RM |
+
rmdir |
+ (((!CONFIG_DISABLE_MOUNTPOINT && CONFIG_FS_WRITABLE) || !CONFIG_DISABLE_PSEUDOFS_OPERATIONS) && CONFIG_NFILE_DESCRIPTORS > 0)4 |
+ CONFIG_NSH_DISABLE_RMDIR |
+
rmmod |
+ CONFIG_MODULE |
+ CONFIG_NSH_DISABLE_MODCMDS |
+
set |
+ !CONFIG_DISABLE_ENVIRON |
+ CONFIG_NSH_DISABLE_SET |
+
sh |
+ CONFIG_NFILE_DESCRIPTORS > 0 && |
+ CONFIG_NSH_DISABLE_SH |
+
shutdown |
+ CONFIG_BOARDCTL_POWEROFF || CONFIG_BOARD_RESET |
+ CONFIG_NSH_DISABLE_SHUTDOWN |
+
sleep |
+ !CONFIG_DISABLE_SIGNALS |
+ CONFIG_NSH_DISABLE_SLEEP |
+
test |
+ !CONFIG_NSH_DISABLESCRIPT |
+ CONFIG_NSH_DISABLE_TEST |
+
time |
+ + | CONFIG_NSH_DISABLE_TIME |
+
umount |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_READABLE3 |
+ CONFIG_NSH_DISABLE_UMOUNT |
+
uname |
+ br | +CONFIG_NSH_DISABLE_UNAME |
+
unset |
+ !CONFIG_DISABLE_ENVIRON |
+ CONFIG_NSH_DISABLE_UNSET |
+
urldecode |
+ !CONFIG_NETUTILS_CODECS && CONFIG_CODECS_URLCODE
+ | CONFIG_NSH_DISABLE_URLDECODE |
+
urlencode |
+ !CONFIG_NETUTILS_CODECS && CONFIG_CODECS_URLCODE
+ | CONFIG_NSH_DISABLE_URLENCODE |
+
useradd |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_WRITABLE && CONFIG_NSH_LOGIN_PASSWD |
+ CONFIG_NSH_DISABLE_USERADD |
+
userdel |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_WRITABLE && CONFIG_NSH_LOGIN_PASSWD |
+ CONFIG_NSH_DISABLE_USERDEL |
+
usleep |
+ !CONFIG_DISABLE_SIGNALS |
+ CONFIG_NSH_DISABLE_USLEEP |
+
wget |
+ CONFIG_NET && CONFIG_NET_TCP &&
+ CONFIG_NFILE_DESCRIPTORS > 0 |
+ CONFIG_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:
+
| Configuration | +Description | +
|---|---|
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
+ Normally, the serial console device is a UART and RS-232 interface.
+ However, if
+ If there are more than one USB slots, then a USB device minor number may also need to be provided: + +
+ If USB tracing is enabled (
|
+
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")
+
|
+
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. +
+ +| Configuration | +Description | +
|---|---|
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:
+
| Configuration | +Description | +
|---|---|
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: +
+ +| Configuration | +Description | +
|---|---|
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:
+
| Configuration | +Description | +
|---|---|
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.
+
| Configuration | +Description | +
|---|---|
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 Customizing the NuttShell+ |
+
+ Overview. + The NuttShell (NSH) is a simple shell application that may be used with NuttX. + It supports a variety of commands and is (very) loosely based on the bash shell and the common utilities used 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.
+
+ 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:
+
+ 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.
+
+ This function then calls nsh_initialize() which initializes the NSH library.
+ nsh_initialize() is described in more detail below.
+
+ 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.
+
+ 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.
+
nsh_initialize()
+ The NSH initialization function, nsh_initialize(), be found in apps/nshlib/nsh_init.c.
+ It does only three things:
+
+ 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.
+
+ 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/stm32_appinit.c.
+ This it does things like: (1) Initialize SPI devices, (2) Initialize SDIO, and (3) mount any SD cards that may be inserted.
+
+ 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.
+
+ New commands can be added to the NSH very easily. + You simply need to add two things: +
++ The implementation of your command, and +
++ 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:
+
+ 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. +
+ +
+ 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:
+
+ It supports registration mechanism so that builtin applications can dynamically register themselves at build time, and +
++ 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: +
+
+ apps/builtin/builtin_proto.h:
+ Prototypes of application task entry points.
+
+ 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:
+
+ 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.
+
+ 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.
+
+ 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:
+
+ 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.
+
+ 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 ++ +
+ 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. +
+ +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.
+
+ 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: +
+ +
+ You can extend the initialization logic in configs/stm3240g-eval/src/stm32_appinit.c.
+ The logic there is called each time that NSH is started and is good place in particular for any device-related initialization.
+
+ 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().
+
+ 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 +
++ 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
+
+ In most of these cases, the configuration sets up the default /etc/init.d/rcS script.
+ The default script is here: apps/nshlib/rcS.template.
+ (The funny values in the template like XXXMKRDMINORXXX get replaced via sed at build time).
+ This default configuration creates a ramdisk and mounts it at /tmp as discussed above.
+
+ If that default behavior is not what you want, then you can provide your own custom rcS script by defining CONFIG_NSH_ARCHROMFS=y in the configuration file.
+
+ Modifying the ROMFS Image.
+ The contents of the /etc directory are retained in the file apps/nshlib/nsh_romfsimg.h OR, if CONFIG_NSH_ARCHROMFS is defined, include/arch/board/nsh_romfsimg.h.
+ In order to modify the start-up behavior, there are three things to study:
+
+ Configuration Options.
+ The additional CONFIG_NSH_ROMFSETC configuration options discussed with the other NSH-specific configuration settings.
+
+ 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: +
++ The configuration settings then installed configuration. +
+
+ 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.
+
+ 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).
+
+ The file apps/nshlib/rcS.template (OR, if CONFIG_NSH_ARCHROMFS is defined include/arch/board/rcs.template.
+
+ 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.
+
+ 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:
+
+ The genromfs tool that is used to generate the ROMFS file system image.
+
+ The xxd tool that is used to create the C header file.
+
+ 5.0 Shell Login+ |
+
+ 5.1 Enabling Shell Logins+ |
+
+ NuttShell sessions can be protected by requiring that the user supply username and password credentials at the beginning of the session. + Logins can be enabled for standard USB or serial consoles with: +
++CONFIG_NSH_CONSOLE_LOGIN=y ++
+ Logins for Telnet sessions can be enabled separately with: +
++CONFIG_NSH_TELNET_LOGIN=y ++
+ Logins can be enabled for either or both session types. + On a successful login, the user will have access to the NSH session: +
++login: admin +password: +User Logged-in! + +NuttShell (NSH) +nsh> ++
+ After each failed login attempt, a delay can be set up. + The purpose of this delay is to discourage attempts to crack the password by brute force. + That delay is configured with +
++CONFIG_NSH_LOGIN_FAILDELAY=0 ++
+ This setting provides the login failure delay in units of milliseconds. + The system will pause this amount of time after each failed login attempt. + After a certain number of failed login attempts, the session will be closed. + That number is controlled by: +
++CONFIG_NSH_LOGIN_FAILCOUNT=3 ++ +
+ 5.2 Verification of Credentials+ |
+
+ There are three ways that NSH can be configured to verify user credentials at login time: +
++ The simplest implementation simply uses fixed login credentials and is selected with: +
++CONFIG_NSH_LOGIN_FIXED=y ++
+ The fixed login credentials are selected via: +
++CONFIG_NSH_LOGIN_USERNAME=admin +CONFIG_NSH_LOGIN_PASSWORD="Administrator" ++
+ This is not very flexible since there can be only one user and the password is fixed in the FLASH image. This option is also not very secure because a malicious user could get the password by just looking at the .text stings in the flash image.
+
+ NSH can also be configured to defer the entire user credential verification to platform-specific logic with this setting: +
++CONFIG_NSH_LOGIN_PLATFORM=y ++
+ In this case, NSH will call a platform-specific function to perform the verification of user credentials. + The platform-specific logic must provide a function with the following prototype: +
++int platform_user_verify(FAR const char *username, FAR const char *password); ++
+ which is prototyped an described in apps/include/nsh.h and which may be included like:
+
+#include <apps/nsh.h> ++
+ An appropriate place to implement this function might be in the directory apps/platform/<board>.
+
+ A final option is to use a password file contained encrypted password information. + This final option is selected with the following and described in more detail in the + following paragraph. +
++CONFIG_NSH_LOGIN_PASSWD=y ++
+ 5.3 Password Files+ |
+
+ NuttX can also be configured to support a password file, by default at /etc/passwd.
+ This option enables support for a password file:
+
+CONFIG_NSH_LOGIN_PASSWD=y ++
+This options requires that you have selected CONFIG_FSUTILS_PASSWD=y to enable the access methods of apps/fsutils/passwd:
+
+CONFIG_FSUTILS_PASSWD=y ++
+ And this determines the location of the password file in a mounted volume: +
++CONFIG_FSUTILS_PASSWD_PATH="/etc/passwd" ++
+ /etc/passwd is a standard location, but you will need to locate the password where ever you have a mounted volume.
+
+ The password file can be a fixed list of users in a ROMFS file system or a modifiable list maintained in a file in some writable file system. If the password file lies in a read-only file system like ROMFS, then you should also indicate that the password file is read-only. +
++CONFIG_FSUTILS_PASSWD_READONLY=y ++
+ If the password file is writable, then additional NSH commands will be enabled to modify the password file: useradd, userdel, and passwd. If you do not wish you have these commands available, then they should be specifically disabled.
+
+ The password file logic requires a few additional settings: +
+ The size of dynamically allocated and freed buffer that is used for file access: +
++CONFIG_FSUTILS_PASSWD_IOBUFFER_SIZE=512 ++
+ And the 128-bit encryption key. The password file currently uses the Tiny Encryption Algorithm (TEA), but could be extended to use something more powerful. +
++CONFIG_FSUTILS_PASSWD_KEY1=0x12345678 +CONFIG_FSUTILS_PASSWD_KEY2=0x9abcdef0 +CONFIG_FSUTILS_PASSWD_KEY3=0x12345678 +CONFIG_FSUTILS_PASSWD_KEY4=0x9abcdef0 ++
+ Password can only be decrypted with access to this key. Note that this key could potentially be fished out of your FLASH image, but without any symbolic information, that would be a difficult job since the TEA KEY is binary data and not distinguishable from other binary data in the FLASH image. +
+
+ If the password file is enabled (CONFIG_NSH_LOGIN_PASSWD=y), then the fixed user credentials will not be used for the NSH session login. Instead, the password file will be consulted to verify the user credentials.
+
+ 5.4 Creating a Password File for a ROMFS File System+ |
+
+ What we want to accomplish is a ROMFS file system, mounted at /etc and containing the password file, passwd like:
+
+NuttShell (NSH) +nsh> ls -Rl /etc +/etc: + dr-xr-xr-x 0 . + dr-xr-xr-x 0 init.d/ + -r--r--r-- 39 passwd +/etc/init.d: + dr-xr-xr-x 0 .. + -r--r--r-- 110 rcS +nsh> ++
+ Where /etc/init.d/rcS is the start-up script; /etc/passwd is a the password file. Note that here we assume that you are already using a start-up script. We can then piggyback the passwd file into the /etc file system already mounted for the NSH start up file as described above above.
+
+ I use the sim/nsh configuration to create a new password file, but other configurations could also be used. That configuration already supports a ROMFS file system, passwords, and login prompts. First, I make these changes to that configuration. +
++ Disable logins +
++- CONFIG_NSH_CONSOLE_LOGIN=y ++ # CONFIG_NSH_CONSOLE_LOGIN is not set + # CONFIG_NSH_TELNET_LOGIN is not set ++
+ Move the password file to a write-able file system: +
++- CONFIG_FSUTILS_PASSWD_PATH="/etc/passwd" ++ CONFIG_FSUTILS_PASSWD_PATH="/tmp/passwd" ++
+ Make the password file modifiable +
++- CONFIG_FSUTILS_PASSWD_READONLY=y +# CONFIG_FSUTILS_PASSWD_READONLY is not set ++
+ Now rebuild the simulation. No login should be required to enter the
+ shell and you should find the useradd, userdel, and passwd commands available in the help summary, provided that they are enabled.
+ Make certain that the useradd command is not disabled:
+
+# CONFIG_NSH_DISABLE_USERADD is not set ++
+ Use the NSH useradd command to add new uses with new user passwords like:
+
+nsh> useradd <username> <password> ++
+ Do this as many times as you would like. Each time that you do this a new
+ entry with an encrypted password will be added to the passwd file at
+ /tmp/passwd. You can see the content of the password file like:
+
+nsh> cat /tmp/passwd ++
+ When you are finished, you can simply copy the /tmp/passwd content from the
+ cat command and paste it into an editor. Make sure to remove any
+ carriage returns that may have ended up on the file if you are using
+ Windows.
+
+ Then create/re-create the nsh_romfsimg.h file as described below.
+
+ The content on the nsh_romfsimg.h header file is generated from a template directory structure. Create the directory structure:
+
+mkdir etc +mkdir etc/init.d ++
+ And copy your existing startup script into etc/init.c as rcS.
+
+ Save your new password file in the etc/ directory as passwd.
+
+ Create the new ROMFS image. +
++genromfs -f romfs_img -d etc -V MyVolName ++
+ Convert the ROMFS image to a C header file +
++xxd -i romfs_img >nsh_romfsimg.h ++
+ Edit nsh_romfsimg.h: Mark both data definitions as const so that the data will be stored in FLASH.
+
+ Edit nsh_romfsimg.h, mark both data definitions as const so that that will be stored in FLASH.
+
+ There is a good example of how to do this in the NSH simulation configuration at configs/sim/nsh. The ROMFS support files are provided at configs/sim/include and the README.txt file at the location provides detailed information about creating and modifying the ROMFS file system. +
+ +
+ Index+ |
+
+ NuttX RTOS+Last Updated: March 27, 2016 + |
+
+ Table of Contents+ |
+
+
|
+
+ 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 + Because of this standards conformance, software developed under other + standard OSs (such as Linux) should port easily to NuttX. + + | |
| + Real-Time + | +|
|
+ + Fully pre-emptible; fixed priority, round-robin, and "sporadic" scheduling. + + | |
| + Totally Open + | +|
|
+ + Non-restrictive BSD license. + + | |
| + GNU Toolchains + | +|
|
+ + Compatible GNU toolchains based on buildroot + available for + download + to provide a complete development environment for many architectures. + + |
+ Feature Set. + Key features of NuttX include: +
+
| + Standards Compliant Core Task Management + | +|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + | |
|
+ + | |
|
+ + |
+|
|
+ + |
+|
|
+ + | |
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + | |
|
+ + |
+|
|
+ |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
| + File system + | +|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + procfs/ pseudo-filesystem support. |
+|
|
+ +
|
+|
|
+ + |
+|
|
+ + get and put), HTML (wget), and Zmodem (sz and rz).
+ |
+|
|
+
+ 1
+ FAT long file name support may be subject to certain Microsoft patent restrictions if enabled.
+ See the top-level |
+|
| + Device Drivers + | +|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + /dev/null, /dev/zero, /dev/random, and loop drivers.
+ |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
| + C/C++ Libraries + | +|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
| + Networking + | +|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
|
+ + |
+|
| + FLASH Support + | +|
|
+ + | |
|
+ + | |
|
+ + | |
|
+ + | |
|
+ + | |
| + USB Host Support + | +|
|
+ + | |
|
+ + | |
|
+ + | |
|
+ + | |
| + USB Device Support + | +|
|
+ + | |
|
+ + | |
|
+ + | |
|
+ + | |
| + Graphics Support + | +|
|
+ + | |
|
+ + | |
|
+ + | |
|
+ + | |
|
+ + | |
|
+ + | |
|
+ + | |
| + Input Devices + | +|
|
+ + | |
| + Analog Devices + | +|
|
+ + | |
| + Motor Control + | +|
|
+ + |
+ NuttX Add-Ons. + The following packages are available to extend the basic NuttX feature set: +
+| + NuttShell (NSH) + | +|
|
+ + | |
| + BAS 2.4 + | +|
|
+ + | |
| + Pascal Compiler with NuttX runtime P-Code interpreter add-on + | +|
|
+ + |
+
+ 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? + +
|
+|
| + 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: + +
|
+
+ 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+ |
+
+ 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. +
+ +
+ In addition to the ever-changing GIT repository, there are frozen released versions of NuttX available.
+ The current release is NuttX 7.15.
+ NuttX 7.15 is the 115th release of NuttX.
+ It was released on March 27, 2016, and is available for download from the
+ Bitbucket.org website.
+ Note that the release consists of two tarballs: nuttx-7.15.tar.gz and apps-7.15.tar.gz.
+ Both may be needed (see the top-level nuttx/README.txt file for build information).
+
+ Release notes for NuttX 7.15 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. +
+
+ Release notes for NuttX 7.15 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.
+
+ 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. +
++ 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. +
++ 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: +
+
+
|
+
+
|
+
+
|
+
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: +
+
+
|
+
+
|
+
+
|
+ + | ++ | +
+ 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: + +
|
+|
+ NXP LPC315x.
+ Support for the NXP LPC315x family has been incorporated into the code base as of NuttX-6.4.
+ Support was added for the Embedded Artists EA3152 board in NuttX-6.11.
+
+
+ STATUS: + Basic support is in place for both the LPC3152 MCU and the EA3152 board. + Verification of the port was deferred due to tool issues + However, because of the high degree of compatibility between the LPC313x and LPC315x family, it + is very likely that the support is in place (or at least very close). + At this point, verification of the EA3152 port has been overcome by events and + may never happen. + However, the port is available for anyone who may want to use it. + Refer to the NuttX board README file for further information. + + |
+|
| + Other ARMv4. + | +|
|
+ + MoxaRT + A port to the Moxa NP51x0 series of 2-port advanced RS-232/422/485 serial device servers was contributed by Anton D. Kachalov in NuttX-7.11. + This port includes a NuttShell (NSH) configuraion with support for the Faraday FTMAC100 Ethernet MAC Driver. + + |
+|
| + ARM Cortex-A5. + | +|
|
+ + Atmel SAMA5D2. + +
|
+|
|
+ + Atmel SAMA5D3. + There are ports to two Atmel SAMA5D3 boards: + +
|
+|
|
+ + Atmel SAMA5D4. + There is a port in progress on one Atmel SAMA5D4 board: + +
|
+|
|
+ + 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: + +
|
+|
| + ARM Cortex-A9. + | +|
|
+ + NXP/Freescale i.MX6. + A port is underway for the following i.MX6 board + +
|
+|
| + ARM Cortex-R4. + | +|
|
+ + TI/Hercules TMS570LS04xx. + A port is underway for the Texas Instruments Hercules TMS570LS04x/03x LaunchPad Evaluation Kit (LAUNCHXL-TMS57004) featuring the Hercules TMS570LS0432PZ chip. + +
+ STATUS. + This is currently in progress but the effort is stalled due to tool-related issues. + Refer to the NuttX board README file for further information. + ++ Toolchain: + The TMS570 is a big-endian ARM platform and requires a big-endian ARM toolchain. + All testing has been performed using a big-endian NuttX buildroot toolchain. + Instructions for building this toolchain are included in the board README file. + + |
+|
| + 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 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 +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: + +
|
+|
|
+ + 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: + +
|
+|
|
+ + 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: + +
+ 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 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 NSHfree 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). + +
| |
|
+ + 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: + +
+ 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: + +
+ 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. + +
|
+|
|
+ + STMicro STM32F205 (STM32 F2 family). + Architecture only support for the STM32F205RG was contributed as an anonymous contribution in NuttX-7.10 + +
|
+|
|
+ + STMicro STM32F207 (STM32 F2 family). +
|
+|
|
+ + 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 these boards: +
+ 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. + +
+ 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. + +
|
+|
| + ARM Cortex-M4. + | +|
|
+ + FreeScale Kinetis K20/Teensy-3.x. + Architecture support (only) was added in NuttX-7.10. + This support was taken from PX4 and is the work of Jakob Odersky. + Support was added for the PJRC Teensy-3.1 board in NuttX-7.11. + Backward compatible support for the Teensy-3.0 is included. + +
+ STATUS: + Refer to the Teensy-3.1 board README file for further information. + + |
+|
|
+ + 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 became stable in NuttX-7.14 thanks to the efforts of Andrew Webster. + Additional work remaining includes: (1) integrate th SDHC drivers, and (2) develop support for USB host and device. + NOTE: Most of these remaining tasks are the same as the pending K40 tasks described above. + Refer to the NuttX board README file for further information. + ++ MK60N512VLL100. + Architecture support for the MK60N512VLL100 was contributed by Andrew Webster in NuttX-7.14. + + |
+|
|
+ + 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 F303 (STM32 F3 family). + +
+ STM32F3-Discovery. + This port uses the STMicro STM32F3-Discovery board featuring the STM32F303VCT6 MCU (STM32 F3 family). + Refer to the STMicro web site for further information about this board. + +
+ STATUS: + The basic port for the STM32F3-Discover was first released in NuttX-6.26. + Many of the drivers previously released for the STM32 F1, Value Line, and F2 and F4 may be usable on this platform as well. + New drivers will be required for ADC and I2C which are very different on this platform. + Refer to the NuttX board README file for further information. + ++ STMicro ST Nucleo F303RE board.. + Contributed by Paul Alexander Patience. + +
+ STATUS: + The basic port for the Nucleo F303RE was first released in NuttX-7.12. + + |
+|
|
+ + 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: +
|
+|
|
+ + 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: +
+ 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: + +
+ 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: + +
+ See the Mikroelektronika website for more information about this board and the NuttX board README file for further information about the NuttX port. + +
+ STATUS: + The basic port for the Mikromedia STM32 M4 was contributed by Ken Petit and was first released in NuttX-6.128. + All drivers for the STM32 F4 family may be used with this board as well. + ++ Olimex STM32 H405. + Support for the Olimex STM32 H405 development board was contributed by Martin Lederhilger and appeared in NuttX-7.3. + See the NuttX board README file for further information about the NuttX port. + ++ Olimex STM32 H407. + Support for the Olimex STM32 H407 development board was contributed by Neil Hancock and appeared in NuttX-7.14. + See the NuttX board README file for further information about the NuttX port. + + |
+|
|
+ + 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: + +
+ Refer to the STM32F429I-Discovery board README file for further information. + + |
+|
|
+ + STMicro STM32 F446. + Architecture-only support is available for the STM32 F446 family (meaning that the parts are supported, but there is not example board supported in the system). + This support was contributed by David Sidrane and made available in NuttX-7.11. + + |
+|
|
+ + STMicro STM32 F46xx. + Architecture-only support is available for the STM32 F46xx family (meaning that the parts are supported, but there is not example board supported in the system). + This support was contributed by Paul Alexander Patienc and made available in NuttX-7.15. + + |
+|
|
+ + STMicro STM32 L476. + Two boards are supported in this family: + +
Status: +
+ NuttX-7.15. + Only the first initial release of support for this family is present. + This is an ongoing, work-in-progress. + It includes these basics: + +
|
+|
|
+ + NCP LPC43xx. + Several board ports are available for this higher end, NXP Cortex-M4F part: + +
+ NXG Technologies LPC4330-Xplorer. + This NuttX port is for the LPC4330-Xplorer board from NGX Technologies featuring the NXP LPC4330FET100 MCU. + See the NXG website for further information about this board. + +
+ 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. + +
+ NXP LPC4370-Link2. + This is the NuttX port to the NXP LPC4370-Link2 development board featuring the NXP LPC4370FET100 MCU. + +
+ WaveShare LPC4337-WS. + This is the NuttX port to the WaveShare LPC4337-WS development board featuring the NXP LPC4337JBD144 MCU. + +
|
+|
|
+ + 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: +
|
+|
|
+ + TI Tiva TM4C1294. + This port uses the TI Tiva C Series TM4C1294 Connected LaunchPad (EK-TM4C1294XL). + +
+ STATUS: +
|
+|
|
+ + TI Tiva TM4C129X. + This port uses the TI Tiva C Series TM4C129X Connected Development Kit (DK-TM4C129X). + +
+ STATUS: +
|
+|
|
+ + 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: + +
+ 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 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 NSHfree 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. + +
|
+|
|
+ + Atmel SAM4S. + There are ports to two Atmel SAM4S board: + +
|
+|
|
+ + 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. + +
|
+|
|
+ + Development Environments: + 1) Linux with native Linux GNU toolchain, 2) Cygwin/MSYS with Cygwin GNU Cortex-M3 or 4 toolchain, 3) Cygwin/MSYS with Windows native GNU Cortex-M3 or M4 toolchain (CodeSourcery or devkitARM), or 4) Native Windows. A DIY toolchain for Linux or Cygwin is provided by the NuttX + buildroot package. + + |
+|
| + ARM Cortex-M7. + | +|
|
+ + Atmel SAMV71. + This port uses Atmel SAM V71 Xplained Ultra Evaluation Kit (SAMV71-XULT). + This board features the ATSAMV71Q21 Cortex-M7 microcontroller. + Refer to the Atmel web site for further information about this board. + +
+ STATUS: + The basic port is complete and there are several different, verified configurations available. + All configurations use the NuttShell (NSH) and a serial console. + The first release of the SAMV71-XULT port was available in NuttX-7.9. + Support for the connect maXTouch Xplained Pro LCD as added in NuttX-7.10. + ++ Additional drivers, with status as of 2015-04-03, include: + +
+ Additional Drivers added in NuttX-7.11 include: + +
+ Additional Drivers added in NuttX-7.13 include: + +
+ And in NuttX-7.14: + +
|
+|
|
+ + Atmel SAME70. + This port uses Atmel SAM E70 Xplained Evaluation Kit (ATSAME70-XPLD). + This board is essentially a lower cost version of the SAMV71-XULT board featuring the ATSAME70Q21 Cortex-M7 microcontroller. + See the Atmel SAMV71 for supported features. + Also refer to the NuttX board README file for further information. + + |
+|
|
+ + STMicro STM32 F745/F746. + This port uses the STMicro STM32F746G-DISCO development board featuring the STM32F746NGH6 MCU. The STM32F746NGH6 is a 216MHz Cortex-M7 operation with 1024Kb Flash. + Refer to the STMicro web site for further information about this board. + +
+ STATUS: + The basic port is complete and there are two, verified configurations available. + Both configurations use the NuttShell (NSH) and a serial console; one includes Ethernet support. + DMA supports is available. + The STM32 F7 peripherals are very similar to some members of the STM32 F4 and additional drivers can easily be ported the F7 as discussed in this Wiki page: Porting Drivers to the STM32 F7 + The first release of the STM32F746G_DISCO port was available in NuttX-7.11. + + + Refer to the NuttX board README file for further information. + + |
+|
|
+ + STMicro STM32 F756. + Architecture-only support is available for the STM32 F756 family (meaning that the parts are supported, but there is not example board supported in the system). + This support was made available in NuttX-7.11. + + |
+|
|
+ + Development Environments: + The same basic development environment is recommended for the Cortex-M7 as for the Cortex-M4. + It would be wise to use the latest GNU toolchains for this part because as of this writing (2015-02-09), support for the Cortex-M7 is a very new GCC feature. + + |
+|
| + Atmel AVR. + | +|
|
+ + AVR ATMega. + +
+ SoC Robotics ATMega128. + This port of NuttX to the Amber Web Server from SoC Robotics + is partially completed. + The Amber Web Server is based on an Atmel ATMega128. + +
+ STATUS: + Work on this port has stalled due to toolchain issues. Complete, but untested code for this port appears in the NuttX 6.5 release. + Refer to the NuttX board README file for further information. + ++ LowPowerLab MoteinoMEGA. + This port of NuttX to the MoteinoMEGA from LowPowerLab. + The MoteinoMEGA is based on an Atmel ATMega1284P. + See the LowPowerlab website and the board README file for further information. + +
+ STATUS: + The basic function port support the NuttShell (NSH) was contribute by Jedi Tek'Enum and first appeared in the NuttX 7.8 release. + ++ Arduino MEGA2560. + Extension of the AVR architecture to support the ATMega2560 and specifi support for the Arduion MEGA2560 board were contributed by Dimitry Kloper and first released in NuttX-7.14. + +
+ STATUS: + The basic port was released in NuttX-7.14 including a simple "Hello, World!" and OS test configurations. + Extensive effort was made to the use the special capabilities of the Atmel Studio AVR compiler to retain strings in FLASH memory and so keep the SRAM memory usage to a minimum. + Refer to the NuttX board README file for further information. + + |
+|
|
+ + AVR AT90USB64x and AT90USB6128x. + +
+ Micropendous 3 AT90USB64x and AT90USB6128x. + This port of NuttX to the Opendous Micropendous 3 board. The Micropendous3 is + may be populated with an AT90USB646, 647, 1286, or 1287. I have only the AT90USB647 + version for testing. This version have very limited memory resources: 64K of + FLASH and 4K of SRAM. + +
+ STATUS: + The basic port was released in NuttX-6.5. This basic port consists only of + a "Hello, World!!" example that demonstrates initialization of the OS, + creation of a simple task, and serial console output. + Refer to the NuttX board README file for further information. + ++ PJRC Teensy++ 2.0 AT90USB1286. + This is a port of NuttX to the PJRC Teensy++ 2.0 board. + This board was developed by PJRC. + The Teensy++ 2.0 is based on an Atmel AT90USB1286 MCU. + +
+ STATUS: + The basic port was released in NuttX-6.5. This basic port consists of + a "Hello, World!!" example that demonstrates initialization of the OS, + creation of a simple task, and serial console output as well as a somewhat + simplified NuttShell (NSH) configuration (see the + NSH User Guide). + ++ An SPI driver and a USB device driver exist for the AT90USB as well + as a USB mass storage configuration. However, this configuration is not + fully debugged as of the NuttX-6.5 release. + Refer to the NuttX board README file for further information. + + | |
|
+ AVR-Specific Issues. + The basic AVR port is solid. + The biggest issue for using AVR is its tiny SRAM memory and its Harvard architecture. + Because of the Harvard architecture, constant data that resides to flash is inaccessible using "normal" memory reads and writes (only SRAM data can be accessed "normally"). + Special AVR instructions are available for accessing data in FLASH, but these have not been integrated into the normal, general purpose OS. + +
+ Most NuttX test applications are console-oriented with lots of strings used for
| |
|
+ + 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 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: + +
+ 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. + + |
+|
+
+
+ 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: + +
+ 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. + ++ STATUS: + The basic port is code complete and fully verified in NuttX 6.18. + Available configurations include the NuttShell (NSH - see the NSH User Guide). + USB has not yet been fully tested but on first pass appears to be functional. + Refer to the NuttX board README file for further information. + + |
+|
|
+ + PIC32MX795F512L. + There one two board ports using this chip: + +
+ 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. + ++ 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: + +
|
+|
| + 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: + +
+ 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: + +
|
+|
|
+ + 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
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 eZ80 Acclaim!. + | +|
|
+ + Zilog eZ80Acclaim! Microcontroller. + There are two eZ80Acclaim! ports: + +
+ 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: + +
+ 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: + +
+ Fortunately, this conversion is done simply using the + 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
+ NOTE: dependencies may be suppressed by setting the make variable + Supported Windows Native Toolchains. + At present, the following Windows native toolchains are in use: +
|
+|
+ 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: + +
+ 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 + At present, this build environment also requires: + +
|
+
+
+
+ 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: + +++ |
+|
| + 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 |
+
+ 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+ |
+
| Getting Started | +|
| User Guide | +|
| Porting Guide | +|
| Configuration Variables1 | +|
| NuttShell (NSH) | +|
| NuttX Binary Loader | +|
| NXFLAT Binary Format | +|
| NX Graphics Subsystem | +|
| NxWidgets | +|
| Demand Paging | +|
| NuttX README Files | +|
| NuttX To-Do List | +|
| USB Device Driver Tracing | +
+ 1 + This configuration variable document is auto-generated using the kconfig2html tool + That tool analyzes the NuttX+ + +Kconfigfiles 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 intoolsdirectory README file. +
+ Trademarks+ |
+
+ 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 new file mode 100644 index 0000000000..360e657dd2 Binary files /dev/null and b/Documentation/NuttX.png differ diff --git a/Documentation/NuttX2-a.png b/Documentation/NuttX2-a.png new file mode 100644 index 0000000000..20c2fd6e71 Binary files /dev/null and b/Documentation/NuttX2-a.png differ diff --git a/Documentation/NuttX2-b.png b/Documentation/NuttX2-b.png new file mode 100644 index 0000000000..5bdab5c29d Binary files /dev/null and b/Documentation/NuttX2-b.png differ diff --git a/Documentation/NuttX2.png b/Documentation/NuttX2.png new file mode 100644 index 0000000000..422d1191fd Binary files /dev/null and b/Documentation/NuttX2.png differ diff --git a/Documentation/NuttX320.png b/Documentation/NuttX320.png new file mode 100644 index 0000000000..f736c41308 Binary files /dev/null and b/Documentation/NuttX320.png differ diff --git a/Documentation/NuttXBinfmt.html b/Documentation/NuttXBinfmt.html new file mode 100644 index 0000000000..49a999846c --- /dev/null +++ b/Documentation/NuttXBinfmt.html @@ -0,0 +1,608 @@ + + +
+ 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: +
++ 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+ |
+
+ 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.
+
+ 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); ++ +
PATH traversal logic:
+register_binfmt()Function Prototype:
++#include <:nuttx/binfmt/binfmt.h> +int register_binfmt(FAR struct binfmt_s *binfmt); ++
Description:
+Returned Value:
+OK) is returned on success and a negated errno is returned on failure.
+unregister_binfmt()Function Prototype:
++#include <:nuttx/binfmt/binfmt.h> +int unregister_binfmt(FAR struct binfmt_s *binfmt); ++
Description:
+Returned Value:
+OK) is returned on success and a negated errno is returned on failure.
+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:
+OK) on success.
+On failure, it returns -1 (ERROR) with errno set appropriately.
+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:
+OK) is returned on success and a negated errno is returned on failure.
+exec_module()Function Prototype:
++#include <:nuttx/binfmt/binfmt.h> +int exec_module(FAR const struct binary_s *bin); ++
Description:
+load_module().
+Returned Value:
+OK) on success.
+On failure, it returns -1 (ERROR) with errno set appropriately.
+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:
+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:
+OK) on success.
+ On failure, it returns -1 (ERROR) with errno set appropriately.
+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:
+
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().
+ exepath_next() repeatedly to examine every file that lies in the directories of the PATH variable.
+ exepath_release() to free resources set aside by exepath_init().
+ Input Parameters: None
+Returned Value:
+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.
+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:
+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().
+
exepath_release()Function Prototype:
++#include <:nuttx/binfmt/binfmt.h> +#ifdef CONFIG_BINFMT_EXEPATH +void exepath_release(EXEPATH_HANDLE handle); +#endif ++
Description:
+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. +
+ +
+ 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.
+
+ 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:
+
+sym_values.
+ Of other kinds of values need to be supported, then typing information would also need to be included in the structure.
+ symtab_findbyname()symtab_findorderedbyname()symtab_findbyvalue()symtab_findorderedbyvalue()
+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:
+nsyms.
+Returned Value:
+NULL is returned if the entry is not found.
+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:
+Returned Value:
+NULL is returned if the entry is not found.
+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:
+nsyms.
+Returned Value:
+NULL is returned if the entry is not found.
+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:
+Returned Value:
+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 new file mode 100644 index 0000000000..d1e96795c7 --- /dev/null +++ b/Documentation/NuttXCCodingStandard.html @@ -0,0 +1,2599 @@ + + +
+ + NuttX C Coding Standard ++Last Updated: July 28, 2015 + |
+
+ Table of Contents+ |
+
if then else Statementswitch Statementwhile Statementdo while Statementgoto
+
+ 1.0 General 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: +
+
+ 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: +
+/*) followed by a series of asterisks extending to the length of the line (usually to column 78).
+ */) 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: +
++ The following groupings should appear in all C header files in the following order: +
++ 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. +
+ +
+ 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.
+
+ General. + Within a comment, the text must be standard English conforming to standard English rules of grammar and spelling (US English spelling). + Of course, this is not the place to summarize all English grammar, but as examples of common grammatic issues in 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 ...
+}
+
+ |
Coding Standard:
+|
+ 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)
+{
+ ...
+}
+
+ |
+ Indentation Unit. + Indentation is in units of two spaces; Each indentation level is twos spaces further to the right than the preceding identation levels. +
+|
+ Incorrect +
+ if (x == y) {
+ dosomething(x);
+ }
+
+ if (x == y) {
+ dosomething(x);
+ }
+
+ |
|
+ Correct +
+ if (x == y)
+ {
+ dosomething(x);
+ }
+
+ |
+ Use of TAB Characters. + The use of TAB characters for indentation is prohibited in C source and header files. + TAB characters are, however, used in make files, assembly language source files, Kconfig files and some script files. + When TAB characters are used in these files, spaces may not be used for indentation. + The correct TAB setting is 4 spaces (not 8) in these cases. +
++ 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 */ ++ |
Coding Standard:
+() immediately after any C keywords (for, switch, while, do, return, etc.).
+ Put a space before the left parenthesis in these cases.
+ )).
+ |
+ 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+ |
+
|
+ 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.
+
Coding Standard:
+g_filelen is preferable to something like g_lengthoffile.
+ g_ to indicate the scope of variable.
+ xyz, then that module should be included as part of the prefix like: g_xyz_.
+ '_'.
+ Preferably there are no '_' separators within the name.
+ Long variable names might require some delimitation using '_'.
+ Long variable names, however, are discouraged.
+ |
+ 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;
+
+ |
Coding Standard:
+len is preferable to something like lengthofiobuffer.
+ 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.
+ i, j, and k which are reserved only for use as loop indices
+ (part of our Fortran legacy).
+ '_'.
+ 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.
+
Coding Standard:
+fhandle_t is preferable to something like openfilehandle_t.
+ typedef'ed names end with the suffix _t.
+ xyz, then that module should be included as a prefix to the type name like: xyz_.
+ '_'.
+ 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.
+
Structure Naming
+typdef-ing of structures;
+ normally the full structure name is used as types throughout the code.
+ xyz_info_s is preferable to something like xyz_datainputstatusinformation_s.
+ _s.
+ xyz, then that module should be included as a prefix to the structure name like: xyz_.
+ '_'.
+ 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
+'_'.
+ 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. */
+ ...
+};
+
+ |
+ 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.
+
+ 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. +
+'_' encouraged.
+ Unlike other naming, use of the underscore character _ to break up enumeration names is encouraged.
+ + 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. */
+};
+
+ |
Coding Standard:
+ ++ Macro Naming. + Macro naming following a naming convention similar to the naming of enumeration values. +
+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.
+ '_' encouraged.
+ Unlike other naming, use of the underscore character _ to break up macro names is encouraged.
+ #define.
+ A single space character should separate the #define from the macro name.
+ Tabs are never used.
+ \ 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.
+ do { ... } while (0) to assume that the macros is, indeed, a statement.
+ + 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)
+
+ |
+ 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).
+
+ 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+ |
+
Coding Standard:
+/*) followed by a series of asterisks extending to the length of the line (usually to column 78).
+ *) in column 2, and a space in column 3.
+ * 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.
+ * ".
+ + Function header template. + Refer to Appendix A for the template for a function header. +
+ +Coding Standard:
+xyz_putvalue is preferable to something like xyz_savethenewvalueinthebuffer.
+ '_', character.
+ For example, for a module called xyz, all of the functions should begin with xyz_.
+ xyz_iob_.
+ '_' 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.
+ true should be consistent with result of the test being true.
+ + 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.
+
Coding Standard:
+
+ 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+ |
+
Coding Standard:
++ 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;
+
+ |
Coding Standard:
+|
+ Incorrect ++struct something_s *x = (struct something_s*) y; ++ |
|
+ Correct ++struct something_s *x = (struct something_s *)y; ++ |
+ 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++; ++ |
+
if then else StatementCoding Standard:
+if <condition> and else must lie on separate lines with nothing else present on the line.
+ if <condition> follows the standard indentation and parentheses rules.
+ if in the if <condition> line and the else must be aligned at the same column.
+ 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!
+ + 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>
+
+ Other Applicable Coding Standards. + See sections related to parentheses. +
+|
+ Example ++ int arg1 = arg2 > arg3 ? arg2 : arg3; + int arg1 = ((arg2 > arg3) ? arg2 : arg3); ++ |
switch StatementCoding Standard:
+default case.
+ The default case should always be present and trigger an error if it is reached when it should not be.
+ 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;
+ }
+
+ |
while StatementCoding Standard:
+while <condition> must lie on a separate line with nothing else present on the line.
+ while <condition> follows the standard indentation and parentheses rules.
+ while <condition> must always be enclosed in braces, even if only a single statement follows.
+ while <condition>.
+ The single semicolon (null statement) is sufficient;
+ + 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++;
+ }
+
+
+ |
do while StatementCoding Standard:
+do and while <condition> must lie on separate lines with nothing else present on the line.
+ do .. while <condition> follows the standard indentation and parentheses rules.
+ do must always be enclosed in braces, even if only a single statement follows.
+ + 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');
+
+ |
gotoCoding Standard:
+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.
+ _ is permitted to break up long labels.
+ 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.
+ |
+ 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+ |
+
+/**************************************************************************** + * <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.
+ ++/**************************************************************************** + * <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.
+ On-Demand Paging+Last Updated: February 4, 2010 + |
+
+ Table of Contents+ |
+
+
|
+||||||||||||
+
|
+||||||||||||
+
|
+
+ Introduction+ |
+
+ 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? +
+ 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. +
+ +g_waitingforfillg_pftcbg_pgworkerpg_callback()pg_miss()TCB
+ NuttX Common Logic Design Description+ |
+
+ 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:
+
g_waitingforfill queue will be initialized.
+ 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 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:
+
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.
+ 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.
+
+ 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. +
pg_miss() must be "locked" in memory.
+ Calling pg_miss() cannot cause a nested page fault.
+ + The page fill worker thread will be awakened on one of three conditions: +
pg_miss(), the page fill worker thread will be awakenend (see above),
+ pg_callback() after completing last fill (when CONFIG_PAGING_BLOCKINGFILL is defined... see below), or
+
+ 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.
+
+ 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:
+
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).
+ 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.
+ 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.
+ 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().
+ 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
+
+ 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:
+
g_pftcb is non-NULL.
+ 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.
+
+ 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: +
g_pftcb.
+ up_unblocktask(g_pftcb) to make the task that just received the fill ready-to-run.
+ g_waitingforfill list is empty.
+ If not:
+ g_waitingforfill,
+ g_pftcb,
+ 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.
+ pg_startfill() which will start the next fill (as described above).
+ g_pftcb to NULL.
+
+ Architecture-Specific Support Requirements+ |
+
+ Memory Regions. + Chip specific logic will map the virtual and physical address spaces into three general regions: +
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().
+ + This memory organization is illustrated in the following table. + Notice that: +
| SRAM | +Virtual Address Space | +Non-Volatile Storage | +
|---|---|---|
| + | DATA | ++ |
| + | Virtual Page n (n > m) | +Stored Page n | +
| + | Virtual Page n-1 | +Stored Page n-1 | +
| DATA | +... | +... | +
| Physical Page m (m < n) | +... | +... | +
| Physical Page m-1 | +... | +... | +
| ... | +... | +... | +
| Physical Page 1 | +Virtual Page 1 | +Stored Page 1 | +
| Locked Memory | +Locked Memory | +Memory Resident | +
+ Example. + As an example, suppose that the size of the SRAM is 192K (as in the NXP LPC3131). And suppose further that: +
+ Then, the size of the locked, memory resident code is 32K (m=32 pages). + The size of the physical page region is 96K (96 pages), and the + size of the data region is 64 pages. + And the size of the virtual paged region must then be greater than or equal to (1024-32) or 992 pages (n). +
+ ++ Building the Locked, In-Memory Image. + One way to accomplish this would be a two phase link: +
.text and .rodata sections of this partial link should be collected into a single section.
+
+ 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);
+ void up_unblock_task(FAR struct tcb_s *tcb);
+ + New, additional functions that must be implemented just for on-demand paging support: +
+ +int up_checkmapping(FAR struct tcb_s *tcb);
+ 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);
+ 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));
+ 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.
+
+
+ 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.
+
+ NXFLAT+Last Updated: September 1, 2012 + |
+
+ Table of Contents+ |
+
+
|
+
+ 1.0 Overview+ |
+
+ NXFLAT is a customized and simplified version of binary format implemented a few years ago called + XFLAT + With the NXFLAT binary format you will be able to do the following: +
++ This allows you to extend the NuttX base code after it has been written into FLASH. + One motivation for implementing NXFLAT is support clean CGI under an HTTPD server. +
++ This feature is especially attractive when combined with the NuttX ROMFS support: + ROMFS allows you to execute programs in place (XIP) in flash without copying anything + other than the .data section to RAM. + In fact, the initial NXFLAT release only worked on ROMFS. + Later extensions also support execution NXFLAT binaries from an SRAM copy as well. +
++ This NuttX feature includes: +
++ NXFLAT is derived from XFLAT. + XFLAT is a toolchain add that provides full shared library and XIP executable + support for processors that have no Memory Management Unit (MMU1). + NXFLAT is greatly simplified for the deeply embedded environment targeted by Nuttx: +
++ Rather, the NXFLAT module only imports symbol values. + In the NXFLAT model, the (PIC2) NXFLAT module resides in a FLASH file system and + when it is loaded at run time, it is dynamically linked only to the (non-PIC) base NuttX + code: + The base NuttX exports a symbol table; the NXFLAT module imports those symbol value + to dynamically bind the module to the base code. +
+ +
+ 1MMU: "Memory Management Unit"
+ 2PIC: "Position Independent Code"
+
+ 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.
+
+ At present, the NXFLAT toolchain is only available for ARM and Cortex-M3/4 (thumb2) targets. +
+
+ 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. +
++ 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. +
+
+ 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.
+
+ 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. +
+ +
+ 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+ |
+
+ 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: +
+<some-dir>/nuttx
+ buildroot-0.x.y into <some-dir>
+ <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
+
+ mv <some-dir>/buildroot-0.x.y<some-dir>/buildroot
+ cd <some-dir>/buildroot
+ cp configs/abc-defconfig-x.y.z .config.
+ 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.
+ When the make completes, the tool binaries will be available under
+ <some-dir>/buildroot/build_abc/staging_dir/bin
+
+ 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] +
+ 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]. ++ +
+ 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:
+
nuttx/syscall/syscall.csv that describes the NuttX RTOS interface, and
+ nuttx/libc/libc.csv that describes the NuttX C library interface.
+ nuttx/libc/math.cvs that descirbes any math library.
+ +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 ++ +
+ Below is a snippet from an NXFLAT make file (simplified from NuttX + + Hello, World! example. +
+
| Target 1 | +hello.r1: |
+ hello.o |
+
|---|---|---|
abc-nuttx-elf-ld -r -d -warn-common -o $@ $^ |
+ ||
| Target 2 | +hello-thunk.S: |
+ hello.r1 |
+
mknxflat -o $@ $^ |
+ ||
| Target 3 | +hello.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 4 | +hello: |
+ 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/.
+
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.
+ 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.
+ 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:
+include/nuttx/binfmt/binfmt.h.
+ A brief summary of the APIs prototyped in that header file are listed below.
+ include/nuttx/binfmt/nxflat.h.
+ include/nuttx/binfmt/nxflat.h.
+ 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:
+
| Flash | RAM | +
|---|---|
.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 new file mode 100644 index 0000000000..f5a9dc1fe7 Binary files /dev/null and b/Documentation/NuttXScreenShot.jpg differ diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html new file mode 100644 index 0000000000..f5f927dea1 --- /dev/null +++ b/Documentation/NuttxPortingGuide.html @@ -0,0 +1,5910 @@ + + +
+ + NuttX RTOS Porting Guide ++Last Updated: March 28, 2016 + |
+
+ Table of Contents+ |
+
up_initialize()up_idle()up_initial_state()up_create_stack()up_use_stack()up_stack_frame()up_release_stack()up_unblock_task()up_block_task()up_release_pending()up_reprioritize_rtr()_exit()up_assert()up_schedule_sigaction()up_allocate_heap()up_interrupt_context()up_disable_irq()up_enable_irq()up_prioritize_irq()up_putc()up_addrenv_create()up_addrenv_destroy()up_addrenv_vtext()up_addrenv_vdata()up_addrenv_heapsize()up_addrenv_select()up_addrenv_restore()up_addrenv_clone()up_addrenv_attach()up_addrenv_detach()up_addrenv_ustackalloc()up_addrenv_ustackfree()up_addrenv_vustack()up_addrenv_ustackselect()up_addrenv_kstackalloc()up_addrenv_kstackfree()
+ boardctl() Application Interfaceup_testset()up_cpu_index()up_cpu_start()up_cpu_initialize()up_cpu_pause()up_cpu_resume()
+ os_start()sched_process_timer()sched_timer_expiration()sched_alarm_expiration()irq_dispatch()
+
+ 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>/ +| |-- audio/ +| | |-- Makefile +| | |-- Kconfig +| | `-- (common audio source files) +| |-- 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) +| `-- tools/ +| |-- Makefile +| |-- Kconfig +| `-- (wireless management source files) +`- 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: +
+arch/<arch-name>/ directory
+ and are discussed in a paragraph below.
+
+ 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.
+
+ These board-specific configuration files can be found in the
+ configs/<board-name>/ sub-directories and are discussed
+ in a paragraph below.
+
+ General documentation for the NuttX OS resides in this directory. +
+ +
+ 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) ++ +
include/<chip-name>/
+ This sub-directory contains chip-specific header files.
+ include/arch.h:
+ This is a hook for any architecture specific definitions that may
+ be needed by the system. It is included by include/nuttx/arch.h.
+ include/types.h:
+ This provides architecture/toolchain-specific definitions for
+ standard types. This file should typedef:
+
+ _int8_t, _uint8_t, _int16_t, _uint16_t, _int32_t, _uint32_t_t
+ and if the architecture supports 24- or 64-bit integers
+
+ _int24_t, _uint24_t, int64_t, uint64_t
+ + NOTE that these type names have a leading underscore character. This + file will be included(indirectly) by include/stdint.h and typedef'ed to + the final name without the underscore character. This roundabout way of + doings things allows the stdint.h to be removed from the include/ + directory in the event that the user prefers to use the definitions + provided by their toolchain header files +
++ And finally +
+
+ irqstate_t
+ + Must be defined to the be the size required to hold the interrupt + enable/disable state. +
++ This file will be included by include/sys/types.h and be made + available to all files. +
+include/irq.h:
+ This file needs to define some architecture specific functions (usually
+ inline if the compiler supports inlining) and some structures. These include:
+ struct xcptcontext:
+ This structures represents the saved context of a thread.
+ irqstate_t up_irq_save(void):
+ Used to disable all interrupts.
+ In the case of multi-CPU platforms, this function disables interrupts on CPUs.
+ void up_irq_restore(irqstate_t flags):
+ Used to restore interrupt enables to the same state as before up_irq_save() was called.
+
+ This file must also define NR_IRQS, the total number of IRQs supported
+ by the board.
+
include/syscall.h:
+ This file needs to define some architecture specific functions (usually
+ inline if the compiler supports inlining) to support software interrupts
+ or syscalls that can be used all from user-mode applications into
+ kernel-mode NuttX functions.
+ This directory must always be provided to prevent compilation errors.
+ However, it need only contain valid function declarations if the architecture
+ supports the CONFIG_BUILD_PROTECTED or CONFIG_BUILD_KERNELconfigurations.
+ uintptr_t sys_call0(unsigned int nbr):
+ nbr is one of the system call numbers that can be found in include/sys/syscall.h.
+ This function will perform a system call with no (additional) parameters.
+ uintptr_t sys_call1(unsigned int nbr, uintptr_t parm1):
+ nbr is one of the system call numbers that can be found in include/sys/syscall.h.
+ This function will perform a system call with one (additional) parameter.
+ uintptr_t sys_call2(unsigned int nbr, uintptr_t parm1, uintptr_t parm2):
+ nbr is one of the system call numbers that can be found in include/sys/syscall.h.
+ This function will perform a system call with two (additional) parameters.
+ uintptr_t sys_call3(unsigned int nbr, uintptr_t parm1, uintptr_t parm2, uintptr_t parm3):
+ nbr is one of the system call numbers that can be found in include/sys/syscall.h.
+ This function will perform a system call with three (additional) parameters.
+ uintptr_t sys_call4(unsigned int nbr, uintptr_t parm1, uintptr_t parm2, uintptr_t parm3, uintptr_t parm4):
+ nbr is one of the system call numbers that can be found in include/sys/syscall.h.
+ This function will perform a system call with four (additional) parameters.
+ uintptr_t sys_call5(unsigned int nbr, uintptr_t parm1, uintptr_t parm2, uintptr_t parm3, uintptr_t parm4, uintptr_t parm5):
+ nbr is one of the system call numbers that can be found in include/sys/syscall.h.
+ This function will perform a system call with five (additional) parameters.
+ uintptr_t sys_call6(unsigned int nbr, uintptr_t parm1, uintptr_t parm2, uintptr_t parm3, uintptr_t parm4, uintptr_t parm5, uintptr_t parm6):
+ nbr is one of the system call numbers that can be found in include/sys/syscall.h.
+ This function will perform a system call with six (additional) parameters.
+
+ This file must also define NR_IRQS, the total number of IRQs supported
+ by the board.
+
src/<chip-name>/
+ This sub-directory contains chip-specific source files.
+ src/Makefile:
+ This makefile will be executed to build the targets src/libup.a and
+ src/up_head.o. The up_head.o file holds the entry point into the system
+ (power-on reset entry point, for example). It will be used in
+ the final link with libup.a and other system archives to generate the
+ final executable.
+ 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).
+
+ 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.
+ 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 +
+ +
+ The binfmt/ subdirectory contains logic for loading binaries in the file
+ system into memory in a form that can be used to execute them.
+
+ The audio/ subdirectory contains the NuttX audio sub-system.
+
+ 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.
+
+ 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)/ ++ +
include/:
+ This directory contains board specific header files.
+ This directory will be linked as include/arch/board at configuration time
+ and can be included via #include <arch/board/header.h>.
+ These header file can only be included by files in arch/<arch-name>/include/
+ and arch/<arch-name>/src/.
+ src/:
+ This directory contains board specific drivers.
+ This directory will be linked as <config>/arch/<arch-name>/src/board at configuration
+ time and will be integrated into the build system.
+ src/Makefile:
+ This makefile will be invoked to build the board specific drivers.
+ It must support the following targets: libext$(LIBEXT), clean, and distclean.
+
+ 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:
+ CC, LD, AR, NM, OBJCOPY, OBJDUMPCFLAGS, 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: +
+include/nuttx/config.h which is included by
+ most C files in the system.
+ 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.
+
+ All of the specific boards supported by NuttX are identified in the README.txt file. +
+
+ 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.
+
+ This sub-directory holds the NuttX cryptographic sub-system. +
+ ++ 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) ++ +
+ 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) ++ +
+ 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) ++ +
+ 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>+ 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) ++ +
+ This is a (almost) empty directory that has a holding place for generated static libraries. + The NuttX build system generates a collection of such static libraries in this directory during the compile phaase. + These libraries are then in a known place for the final link phase where they are accessed to generated the final binaries. +
+ ++ 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) ++ +
+ This directory holds a tiny, minimal standard std C++ that can be used to + build some, simple C++ applications in NuttX. +
+ ++ This is the NuttX memory manager. +
+ ++ This directory contains the implementation of the NuttX networking layer including internal socket APIs. +
+ ++ The files forming core of the NuttX RTOS reside here. +
+ +
+ 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.
+
+ 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 +|-- cmpconfig.c +|-- cnvwindeps.c +|-- copydir.sh / copydir.bat +|-- define.sh / define.bat +|-- incdir.sh / indir.bat +|-- indent.sh +|-- link.sh / link.bat +|-- mkconfig.c +|-- mkexport.sh +|-- mkimage.sh +|-- mknulldeps.sh +|-- mkromfsimg.sh +|-- mksyscall.c +|-- mkversion.c +|-- mkwindeps.sh +|-- 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.
+
+ This directory holds support for hardware-independent wireless support. +
+ +
+ The top-level Makefile in the ${TOPDIR} directory contains all of the top-level control
+ logic to build NuttX.
+ Use of this Makefile to build NuttX is described below.
+
+ 3.0 Configuring and Building+ |
+
+ 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:
+
configs/<board-name>/[<config-dir>/]Make.defs to ${TOPDIR}/Make.defs,configs/<board-name>/[<config-dir>/]setenv.sh to ${TOPDIR}/setenv.sh, andconfigs/<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.
+
+ 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:
+
Makefile that controls the NuttX build.
++ That directory also holds: +
+.config that describes the current configuration.Make.defs that provides customized build targets, andsetenv.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: +
+include/nuttx/config.h using the ${TOPDIR}/.config file.${TOPDIR}/.version with version 0.0 if one does not exist.include/nuttx/version.h using the ${TOPDIR}/.version file.${TOPDIR}/arch/<arch-name>/include at ${TOPDIR}/include/arch.${TOPDIR}/configs/<board-name>/include at ${TOPDIR}/include/arch/board.${TOPDIR}/configs/<board-name>/src at ${TOPDIR}/arch/<arch-name>/src/board${APPDIR}/include at ${TOPDIR}/include/apps
+ 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.
+
+ 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; theuis like the Greek letter micron: µ. So it would beµPwhich 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 likearch_instead -- then I would not have to answer this question so often. +
+ Microprocessor-Specific Interfaces.
+ An interface which is unique to a certain microprocessor should be prefixed with the name of the microprocessor, for example stm32_, and be prototyped in some header file in the arch/ directories.
+
+ There is also a arch/<architecture>/include/<chip>/chip.h header file that can be used to communicate other microprocessor-specific information between the board logic and even application logic.
+ Application logic may, for example, need to know specific capabilities of the chip.
+ Prototypes in that chip.h header file should follow the microprocessor-specific naming convention.
+
+ Common Board Interfaces.
+ Any interface that is common to all boards should be prefixed with board_ and should also be prototyped in include/nuttx/arch.h.
+ These board_ definitions provide the interface between the board-level logic and the architecture-specific logic.
+
+ There is also a configs/<board>/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/<board>/src/<board>.h and should not be used outside of that directory since board-specific definitions have no meaning outside of the board directory.
+
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.
+
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. +
+ +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.
+
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 stackadj_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 taskTCB_FLAG_TTYPE_PTHREAD: User pthreadTCB_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.
+
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 stackadj_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.
+
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 +
+ +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 taskTCB_FLAG_TTYPE_PTHREAD: User pthreadTCB_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
+
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.
+ 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.
+ 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. +
+ +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: +
++ 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
+ _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. +
+ +up_assert()Function Prototype:
+ void up_assert(FAR const uint8_t *filename, int linenum);
+
Description. + Assertions may be handled in an architecture-specific way. +
+ +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: +
+
+ This API is NOT required if CONFIG_DISABLE_SIGNALS
+ is defined.
+
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().
+
up_interrupt_context()Function Prototype: bool up_interrupt_context(void)
Description. + Return true if we are currently executing in the interrupt handler context. +
+ +up_disable_irq()Function Prototype:
++#ifndef CONFIG_ARCH_NOINTC + void up_disable_irq(int irq); +#endif ++ +
Description. + Disable the IRQ specified by 'irq' + On many architectures, there are three levels of interrupt enabling: (1) + at the global level, (2) at the level of the interrupt controller, + and (3) at the device level. In order to receive interrupts, they + must be enabled at all three levels. +
++ This function implements enabling of the device specified by 'irq' + at the interrupt controller level if supported by the architecture + (up_irq_save() supports the global level, the device level is hardware + specific). +
+ If the architecture does not support up_disable_irq,
+ CONFIG_ARCH_NOINTC should be defined in the NuttX configuration file.
+ Since this API cannot be supported on all architectures, it should be
+ avoided in common implementations where possible.
+
up_enable_irq()Function Prototype:
++#ifndef CONFIG_ARCH_NOINTC + void up_enable_irq(int irq); +#endif ++ +
Description. + This function implements disabling of the device specified by 'irq' + at the interrupt controller level if supported by the architecture + (up_irq_restore() supports the global level, the device level is hardware + specific). +
+
+ If the architecture does not support up_disable_irq,
+ CONFIG_ARCH_NOINTC should be defined in the NuttX configuration file.
+ Since this API cannot be supported on all architectures, it should be
+ avoided in common implementations where possible.
+
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.
+
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 +
+ +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.
+
CONFIG_USEC_PER_TICK and if there you require accurate up-time for the MCU, then there are measures that you can take:
+
+CONFIG_USEC_PER_TICK to a different value so that an exactly CONFIG_USEC_PER_TICK can be realized.
+ 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: +
++accumulator = 0; +match = 328; ++
+if (match == 328)
+ {
+ accumulator += 32; // 100*(328 - 327.68)
+ }
+else
+ {
+ accumulator -= 68; // (100*(327 - 327.68)
+ }
+
+
+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. +
+ ++ To enable hardware module use the following configuration options: +
+
CONFIG_RTC
+ CONFIG_RTC_EXTERNAL
+ CONFIG_RTC_EXTERNAL will configure the operating
+ system so that it defers initialization of its time facilities.
+ CONFIG_RTC_DATETIME
+ 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
+ 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
+ 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
+ + which requires the following base functions to read and set time: +
+up_rtc_initialize().
+ Initialize the builtin, MCU hardware RTC per the selected configuration.
+ This function is called once very early in the OS initialization sequence.
+ NOTE that initialization of external RTC hardware that depends on the
+ availability of OS resources (such as SPI or I2C) must be deferred
+ until the system has fully booted. Other, RTC-specific initialization
+ functions are used in that case.
+ up_rtc_time().
+ Get the current time in seconds. This is similar to the standard time() function.
+ This interface is only required if the low-resolution RTC/counter hardware implementation selected.
+ It is only used by the RTOS during initialization to set up the system time when CONFIG_RTC is set
+ but neither CONFIG_RTC_HIRES nor CONFIG_RTC_DATETIME are set.
+ up_rtc_gettime().
+ Get the current time from the high resolution RTC clock/counter.
+ This interface is only supported by the high-resolution RTC/counter hardware implementation.
+ It is used to replace the system timer (g_system_tick).
+ up_rtc_settime().
+ Set the RTC to the provided time.
+ All RTC implementations must be able to set their time based on a standard timespec.
+ + 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:
+
+ 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: +
+
CONFIG_USEC_PER_TICK microseconds.
+ + 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: +
+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.
+ 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. +
+ +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.
+
+
+ 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. +
+
+ 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:
+
+
up_alarm_cancel():
+ Cancels the alarm.
+ up_alarm_start():
+ Enables (or re-enables) the alaram.
+
+ If CONFIG_SCHED_TICKLESS_ALARM is notdefined, then the platform code must provide the following verify similar functions:
+
+
up_timer_cancel():
+ Cancels the interval timer.
+ up_timer_start():
+ Starts (or re-starts) the interval timer.
+
+ 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: +
+sched_alarm_expiration(). Called by the platform-specific logic when the alarm expires.
+ sched_timer_expiration(). Called by the platform-specific logic when the interval time expires.
+ up_timer_initialize()Function Prototype:
++#include <nuttx/arch.h> +void up_timer_initialize(void); ++
Description:
+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:
+Returned Value:
+OK) on success; a negated errno value on failure.
+Assumptions:
+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, sinceup_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:
+OK) on success; a negated errno value on failure.
+Assumptions:
+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 returnedReturned Value:
+OK) on success; a negated errno value on failure.
+Assumptions:
+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:
+OK) on success; a negated errno value on failure.
+Assumptions:
+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:
+OK) on success; a negated errno value on failure.
+Assumptions:
+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:
+OK) on success; a negated errno value on failure.
+Assumptions:
+
+ 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.
+
+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: +
+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: +
+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: +
+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: +
+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: +
+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: +
+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: +
+Assumptions/Limitations: +
+POSIX Compatibility: This is a NON-POSIX interface. +VxWorks provides the following comparable interface: +
+ STATUS wdCancel (WDOG_ID wdog); ++ +
+ 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. +
+ ++ 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).
+
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
+
+
+Work Queues. + NuttX provides work queues. Work queues are threads that service a queue of work items to be performed. They are useful for off-loading work to a different threading context, for delayed processing, or for serializing activities. +
+ +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. +
+ +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> 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
+ + 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> 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 matchinglpwork_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.
+ + 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.
++ 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).
+ 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.
+ 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.
+
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.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.
+
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).
+
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.
+
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 +
+ +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 +
+ +
+ 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: +
+
+ 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:
+
up_addrenv_create():
+ Create an address environment.
+ up_addrenv_destroy():
+ Destroy an address environment.
+ up_addrenv_vtext():
+ Returns the virtual base address of the .text address environment.
+ up_addrenv_vdata():
+ Returns the virtual base address of the .bss/.data address environment.
+ up_addrenv_heapsize():
+ Return the initial heap size.
+ up_addrenv_select():
+ Instantiate an address environment.
+ up_addrenv_restore():
+ Restore an address environment.
+ up_addrenv_clone():
+ Copy an address environment from one location to another.
+
+ 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().
+
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.
+ up_addrenv_detach():
+ Release the thread's reference to a group address environment when a task/thread exits.
+
+ 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:
+
up_addrenv_ustackalloc():
+ Create a stack address environment
+ up_addrenv_ustackfree():
+ Destroy a stack address environment.
+ up_addrenv_vustack():
+ Returns the virtual base address of the stack
+ up_addrenv_ustackselect():
+ Instantiate a stack address environment
+
+ 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:
+
up_addrenv_kstackalloc():
+ Allocate the process kernel stack.
+ up_addrenv_kstackfree():
+ Free the process kernel stack.
+ up_addrenv_create()Function Prototype:
+int up_addrenv_create(size_t textsize, size_t datasize, size_t heapsize, FAR group_addrenv_t *addrenv);
+Description:
+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:
+OK) on success; a negated errno value on failure.
+up_addrenv_destroy()Function Prototype:
+
int up_addrenv_destroy(group_addrenv_t *addrenv);
+Description:
+up_addrenv_create().
+Input Parameters:
+addrenv: The representation of the task address environment previously returned by up_addrenv_create().Returned Value:
+OK) on success; a negated errno value on failure.
+up_addrenv_vtext()Function Prototype:
+
int up_addrenv_vtext(FAR group_addrenv_t addrenv, FAR void **vtext);
+Description:
+.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:
+OK) on success; a negated errno value on failure.
+up_addrenv_vdata()Function Prototype:
+
int up_addrenv_vdata(FAR group_addrenv_t *addrenv, size_t textsize, FAR void **vdata);
+Description:
+.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:
+OK) on success; a negated errno value on failure.
+up_addrenv_heapsize()Function Prototype:
+
ssize_t up_addrenv_heapsize(FAR const group_addrenv_t *addrenv);
+Description:
+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:
+errno value on failure.
+up_addrenv_select()Function Prototype:
+
int up_addrenv_select(group_addrenv_t *addrenv, save_addrenv_t *oldenv);
+Description:
+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:
+OK) on success; a negated errno value on failure.
+up_addrenv_restore()Function Prototype:
+
int up_addrenv_restore(save_addrenv_t oldenv);
+Description:
+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:
+OK) on success; a negated errno value on failure.
+up_addrenv_clone()Function Prototype:
+
int up_addrenv_clone(FAR const task_group_s *src, FAR struct task_group_s *dest);
+Description:
+Input Parameters:
+src: The address environment to be copied.dest: The location to receive the copied address environment.Returned Value:
+OK) on success; a negated errno value on failure.
+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:
+OK) on success; a negated errno value on failure.
+up_addrenv_detach()Function Prototype:
+
int up_addrenv_detach(FAR struct task_group_s *group, FAR struct task_group_s *tcb);
+Description:
+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:
+OK) on success; a negated errno value on failure.
+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:
+OK) on success; a negated errno value on failure.
+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:
+OK) on success; a negated errno value on failure.
+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:
+OK) on success; a negated errno value on failure.
+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:
+OK) on success; a negated errno value on failure.
+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:
+OK) on success; a negated errno value on failure.
+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:
+OK) on success; a negated errno value on failure.
+boardctl() Application InterfaceFunction 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:
+OK) is returned;
+ -1 (ERROR) is returned on failure with the errno variable to to indicate the nature of the failure.
++According to Wikipedia: "Symmetric multiprocessing (SMP) involves a symmetric multiprocessor system hardware and software architecture where two or more identical processors connect to a single, shared main memory, have full access to all I/O devices, and are controlled by a single operating system instance that treats all processors equally, reserving none for special purposes. Most multiprocessor systems today use an SMP architecture. In the case of multi-core processors, the SMP architecture applies to the cores, treating them as separate processors. +
++"SMP systems are tightly coupled multiprocessor systems with a pool of homogeneous processors running independently, each processor executing different programs and working on different data and with capability of sharing common resources (memory, I/O device, interrupt system and so on) and connected using a system bus or a crossbar." +
++For a technical description of the NuttX implementation of SMP, see the NuttX SMP Wiki Page. +
+ + None + + +up_testset()Function Prototype:
+
+#include <nuttx/spinlock.h> +#ifdef CONFIG_SPINLOCK +spinlock_t up_testset(volatile FAR spinlock_t *lock); +#endif ++ +
Description:
++ Perform and atomic test and set operation on the provided spinlock. +
+Input Parameters:
+lock: The address of spinlock object.
+ Returned Value:
+
+ The spinlock is always locked upon return.
+ The value of previous value of the spinlock variable is returned, either SP_LOCKED if the spinlock was previously locked (meaning that the test-and-set operation failed to obtain the lock) or SP_UNLOCKED if the spinlock was previously unlocked (meaning that we successfully obtained the lock)
+
up_cpu_index()Function Prototype:
+
+#include <nuttx/arch.h> +#ifdef CONFIG_SMP +int up_cpu_index(void); +#else +# define up_cpu_index() (0) +#endif ++ +
Description:
+
+ Return an index in the range of 0 through (CONFIG_SMP_NCPUS-1) that corresponds to the currently executing CPU.
+
Input Parameters:
+Returned Value:
+
+ An integer index in the range of 0 through (CONFIG_SMP_NCPUS-1) that corresponds to the currently executing CPU.
+
up_cpu_start()Function Prototype:
+
+#include <nuttx/arch.h> +#ifdef CONFIG_SMP +int up_cpu_start(int cpu); +#endif ++ +
Description:
++ In an SMP configution, only one CPU is initially active (CPU 0). + System initialization occurs on that single thread. + At the completion of the initialization of the OS, just before beginning normal multitasking, the additional CPUs would be started by calling this function. +
+
+ Each CPU is provided the entry point to is IDLE task when started.
+ A TCB for each CPU's IDLE task has been initialized and placed in the CPU's g_assignedtasks[cpu] list.
+ A stack has also been allocated and initialized.
+
+ The OS initialization logic calls this function repeatedly until each CPU has been started, 1 through (CONFIG_SMP_NCPUS-1).
+
Input Parameters:
+cpu: The index of the CPU being started.
+ This will be a numeric value in the range of from one to (CONFIG_SMP_NCPUS-1)).
+ (CPU 0 is already active).
+ Returned Value:
+
+ Zero (OK) is returned on success; a negated errno value on failure.
+
up_cpu_initialize()Function Prototype:
+
+#include <nuttx/arch.h> +#ifdef CONFIG_SMP +int up_cpu_initialize(void); +#endif ++ +
Description:
+
+ After the CPU has been started (via up_cpu_start()) the system will call back into the architecture-specific code with this function on the thread of execution of the newly started CPU.
+ This gives the architecture-specific a chance to perform ny initial, CPU-specific initialize on that thread.
+
Input Parameters:
+Returned Value:
+
+ Zero (OK) is returned on success; a negated errno value on failure.
+
up_cpu_pause()Function Prototype:
+
+#include <nuttx/arch.h> +#ifdef CONFIG_SMP +int up_cpu_pause(int cpu); +#endif ++ +
Description:
+
+ Save the state of the current task at the head of the g_assignedtasks[cpu] task list and then pause task execution on the CPU.
+
+ This function is called by the OS when the logic executing on one CPU needs to modify the state of the g_assignedtasks[cpu] list for another CPU.
+
Input Parameters:
+cpu: The index of the CPU to be paused.
+ This will not be the index of the currently executing CPU.
+ Returned Value:
+
+ Zero (OK) is returned on success; a negated errno value on failure.
+
up_cpu_resume()Function Prototype:
+
+#include <nuttx/arch.h> +#ifdef CONFIG_SMP +int up_cpu_resume(int cpu); +#endif ++ +
Description:
+
+ Restart the cpu after it was paused via up_cpu_pause(), restoring the state of the task at the head of the g_assignedtasks[cpu] list, and resume normal tasking.
+
+ This function is called after up_cpu_pause() in order resume operation of the CPU after modifying its g_assignedtasks[cpu] list.
+
Input Parameters:
+cpu: The index of the CPU being resumed.
+ This will not be the index of the currently executing CPU.
+ Returned Value:
+
+ Zero (OK) is returned on success; a negated errno value on failure.
+
+ These are standard interfaces that are exported by the OS + for use by the architecture specific logic. +
+ +os_start()+ To be provided +
+ ++ To be provided +
+ +sched_process_timer()Function Prototype:
++#include <nuttx/arch.h> +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.
+
sched_timer_expiration()Function Prototype:
+
+#include <nuttx/arch.h> +void sched_timer_expiration(void); ++
Description:
+ Description: ifCONFIG_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:
+Returned Value:
+Assumptions:
+sched_alaram_expiration()Function Prototype:
+
+#include <nuttx/arch.h> +void sched_timer_expiration(void); + +Description:
+ Description: ifCONFIG_SCHED_TICKLESSis 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:
+Returned Value:
+Assumptions:
+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. +
+ +
+ 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:
+
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:
+
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:
+OK) is returned on success; a negated errno value is returned on failure.
+up_shmdt()Function Prototype:
+
+#include <nuttx/arch.h> +#ifdef CONFIG_MM_SHM +int up_shmdt(uintptr_t vaddr, unsigned int npages); +#endif + +Description:
+
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:
+OK) is returned on success; a negated errno value is returned on failure.
++ 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. +
+ +
+ 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.
+
+ LED-related definitions are provided in two header files: +
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.
+ <arch-name>/src/common/up_internal.h,
+ but could be at other locations in particular architectures.
+ These prototypes are discussed below.
+ + 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.
+
+ The include/nuttx/board.h has declarations like:
+
+#ifdef CONFIG_ARCH_LEDS +void board_autoled_initialize(void); +void board_autoled_on(int led); +void board_autoled_off(int led); +#else +# define board_autoled_initialize() +# define board_autoled_on(led) +# define board_autoled_off(led) +#endif ++
+ Where: +
+
+ void board_autoled_initialize(void) is called early in power-up initialization to initialize the LED hardware.
+
+ NOTE: In most architectures, board_autoled_initialize() is called from board-specific initialization logic.
+ But there are a few architectures where this initialization function is still called from common chip architecture logic.
+ This interface is 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_autoled_on(int led) is called to instantiate the LED presentation of the event.
+ The led argument is one of the definitions provided in <board-name>/include/board.h.
+
+
board_autoled_off(int ledis called to terminate the LED presentation of the event.
+ The led argument is one of the definitions provided in <board-name>/include/board.h.
+ Note that only LED_INIRQ, LED_SIGNAL, LED_ASSERTION, and LED_PANIC
+ indications are terminated.
+
+
+ 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 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: +
+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.
+ 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.
+
+ 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.
+
+ NuttX supports a two-part touchscreen driver architecture. +
++ Files supporting the touchscreen controller (TSC) driver can be found in the following locations: +
+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.
+ drivers/input.
+ 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.
+ + The NuttX analog drivers are split into two parts: +
+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.
+ drivers/analog/.
+ arch/<architecture>/src/<chip> directory for the specific processor <architecture> and for the specific <chip> analog peripheral devices.
+ 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:
+ drivers/analog/adc.c.
+ The implementation of the common ADC character driver.
+ 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:
+ drivers/analog/dac.c.
+ The implementation of the common DAC character driver.
+ + 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: +
++ Files supporting PWM can be found in the following locations: +
+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.
+ drivers/pwm.c.
+ arch/<architecture>/src/<chip> directory for the specific processor <architecture> and for the specific <chip> PWM peripheral devices.
+ + 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: +
++ Files supporting CAN can be found in the following locations: +
+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.
+ drivers/can.c.
+ arch/<architecture>/src/<chip> directory for the specific processor <architecture> and for the specific <chip> CAN peripheral devices.
+ + NuttX supports a low-level, two-part Quadrature Encoder driver. +
++ Files supporting the Quadrature Encoder can be found in the following locations: +
+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.
+ drivers/sensors/qencoder.c.
+ arch/<architecture>/src/<chip> directory for the specific processor <architecture> and for the specific <chip> Quadrature Encoder peripheral devices.
+ + NuttX supports a low-level, two-part timer driver. +
++ Files supporting the timer driver can be found in the following locations: +
+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.
+ drivers/timers/timer.c.
+ arch/<architecture>/src/<chip> directory for the specific processor <architecture> and for the specific <chip> timer peripheral devices.
+ + NuttX supports a low-level, two-part RealTime Clock (RTC) driver. +
++ Files supporting the RTC driver can be found in the following locations: +
+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.
+ drivers/timers/rtc.c.
+ arch/<architecture>/src/<chip> directory for the specific processor <architecture> and for the specific <chip> RTC peripheral devices.
+ + NuttX supports a low-level, two-part watchdog timer driver. +
++ Files supporting the watchdog timer driver can be found in the following locations: +
+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.
+ drivers/timers/watchdog.c.
+ arch/<architecture>/src/<chip> directory for the specific processor <architecture> and for the specific <chip> watchdog timer peripheral devices.
+ + 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.
+
+ 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:
+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:
+
+ 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:
+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:
+
+ 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:
+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:
+
+ 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:
+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:
++ 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:
+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.
+
+ 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.
+
+ 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.
+
+ 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. +
+ +
+ 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.
+
+ 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:
+
+
struct spi_dev_s from the hardware-specific SPI device driver, and
+ Examples:
+ drivers/loop.c, drivers/mmcsd/mmcsd_spi.c, drivers/ramdisk.c, etc.
+
+ include/nuttx/i2c/i2c.h.
+ All structures and APIs needed to work with I2C drivers are provided in this header file.
+
+ struct i2c_ops_s.
+ Each I2C device driver must implement an instance of struct i2c_ops_s.
+ That structure defines a call table with the following methods:
+
int transfer(FAR struct i2c_master_s *dev, FAR struct i2c_msg_s *msgs, int count);
+
+ + Binding I2C Drivers. + I2C drivers are not normally directly accessed by user code, but are usually bound to another, + higher level device driver. + In general, the binding sequence is: +
++
struct i2c_master_s from the hardware-specific I2C device driver, and
+ Examples:
+ arch/z80/src/ez80/ez80_i2c.c, arch/z80/src/z8/z8_i2c.c, etc.
+
+ 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: +
++
struct fb_vtable_s from the hardware-specific frame buffer device driver, and
+ Examples:
+ arch/sim/src/up_framebuffer.c.
+ See also the usage of the frame buffer driver in the graphics/ directory.
+
+ 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: +
++
struct lcd_dev_s from the hardware-specific LCD device driver, and
+ 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.
+
+ 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 geometryMTDIOC_XIPBASE:: Convert block to physical address for eXecute-In-PlaceMTDIOC_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: +
++
struct mtd_dev_s from the hardware-specific MTD device driver, and
+ Examples:
+ drivers/mtd/m25px.c and drivers/mtd/ftl.c
+
+ 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: +
++
struct sdio_dev_s from the hardware-specific SDIO device driver, and
+ Examples:
+ arch/arm/src/stm32/stm32_sdio.c and drivers/mmcsd/mmcsd_sdio.c
+
+ 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:
+
+
+ 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
+
+ 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/lpc17_appinit.c and
+ the function nsh_waiter() in the file configs/olimex-lpc1766stk/src/lpc17_appinit.c.
+
+ 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.
+
+ 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: +
++
+ 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
+
+ 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.
+
+ Power Management (PM) Sub-System. + NuttX supports a simple power management (PM) sub-system. This sub-system: +
++ Monitors activity from drivers (and from other parts of the syste), and +
++ Provides hooks to place drivers (and the whole system) into reduce power + modes of operation. +
++
+ The PM sub-system integrates the MCU idle loop with a collection of device drivers to support: +
++ Reports of relevant driver or other system activity. +
++ Registration and callback mechanism to interface with individual device drivers. +
++ IDLE time polling of overall driver activity. +
++ Coordinated, global, system-wide transitions to lower power usage states. +
++ Low Power Consumption States. + Various "sleep" and low power consumption states have various names and are sometimes used in conflicting ways. + In the NuttX PM logic, we will use the following terminology: +
+NORMAL
+ IDLE
+ 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
+ SLEEP
+ SLEEP (some MCUs may even require going through reset).
+
+ These various states are represented with type enum pm_state_e in include/nuttx/power/pm.h.
+
+ Power Management Domains.
+ Each PM interfaces includes a integer domain number.
+ By default, only a single power domain is supported (CONFIG_PM_NDOMAINS=1).
+ But that is configurable; any number of PM domains can be supported.
+ Multiple PM domains might be useful, for example, if you would want to control power states associated with a network separately from power states associated with a user interface.
+
+ All PM interfaces are declared in the file include/nuttx/power/pm.h.
+
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 +
+ +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
+ struct pm_callback_s providing the driver callback functions.
+ Returned Value:
+Zero (OK) on success; otherwise a negated errno value is returned.
+
pm_activity()Function Prototype:
++#include <nuttx/power/pm.h> +void pm_activity(int domain, int priority); ++
Description: + This function is called by a device driver to indicate that it is performing meaningful activities (non-idle). + This increment an activity count and/or will restart a idle timer and prevent entering reduced power states. +
+Input Parameters: +
domain
+ priority
+ 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!). +
+ +pm_checkstate()Function Prototype:
++#include <nuttx/power/pm.h> +enum pm_state_e pm_checkstate(int domain); ++
Description:
+ This function is called from the MCU-specific IDLE loop to monitor the power management conditions.
+ This function returns the "recommended" power management state based on the PM configuration and activity reported in the last sampling periods.
+ The power management state is not automatically changed, however.
+ The IDLE loop must call pm_changestate() in order to make the state change.
+
+ These two steps are separated because the platform-specific IDLE loop may have additional situational information that is not available to the PM sub-system. + For example, the IDLE loop may know that the battery charge level is very low and may force lower power states even if there is activity. +
+
+ NOTE: That these two steps are separated in time and, hence, the IDLE loop could be suspended for a long period of time between calling pm_checkstate() and pm_changestate().
+ The IDLE loop may need to make these calls atomic by either disabling interrupts until the state change is completed.
+
Input Parameters: +
domain
+ Returned Value: + The recommended power management state. +
+ +pm_changestate()Function Prototype:
++#include <nuttx/power/pm.h> + int pm_changestate(int domain, enum pm_state_e newstate); ++
Description: + This function is used by platform-specific power management logic. + It will announce the power management power management state change to all drivers that have registered for power management event callbacks. +
+Input Parameters: +
domain
+ newstate
+ 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. +
+ +
+ 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.
+
prepare()Function Prototype:
++int (*prepare)(FAR struct pm_callback_s *cb, int domain, enum pm_state_e pmstate); ++
Description: + Request the driver to prepare for a new power state. + This is a warning that the system is about to enter into a new power state. + The driver should begin whatever operations that may be required to enter power state. + The driver may abort the state change mode by returning a non-zero value from the callback function. +
+Input Parameters: +
cb
+ domain
+ pmstate
+ 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!
+
notify()Function Prototype:
++#include <nuttx/power/pm.h> +void (*notify)(FAR struct pm_callback_s *cb, int domain, enum pm_state_e pmstate); ++
Description: + Notify the driver of new power state. + This callback is called after all drivers have had the opportunity to prepare for the new power state. +
+Input Parameters: +
cb
+ domain
+ pmstate
+ 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+ |
+
+ 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 new file mode 100644 index 0000000000..a91959e198 --- /dev/null +++ b/Documentation/NuttxUserGuide.html @@ -0,0 +1,10180 @@ + + + +
+ NuttX Operating System
+ |
+
+ 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: +
+errno Variable
+ 1.2 Intended Audience and Scope+ |
+
+ The intended audience for this document are firmware developers who are implementing applications on NuttX. + Specifically, this documented is limited to addressing only NuttX RTOS APIs that are available to the application developer. + As such, this document does not focus on any technical details of the organization or implementation of NuttX. + Those technical details are provided in the NuttX Porting Guide. +
++ Information about configuring and building NuttX is also needed by the application developer. + That information can also be found in the NuttX Porting Guide. +
+ +
+ 2.0 OS Interfaces+ |
+
+ This section describes each C-callable interface to the NuttX + Operating System. The description of each interface is presented + in the following format: +
+Function Prototype: The C prototype of the interface function +is provided. +
+Description: The operation performed by the interface function +is discussed. +
+Input Parameters: All input parameters are listed along +with brief descriptions of each input parameter. +
+Returned Value: All possible values returned by the interface +function are listed. Values returned as side-effects (through +pointer input parameters or through global variables) will be +addressed in the description of the interface function. +
+Assumptions/Limitations: Any unusual assumptions made by +the interface function or any non-obvious limitations to the use +of the interface function will be indicated here. +
+POSIX Compatibility: Any significant differences between the +NuttX interface and its corresponding POSIX interface will be noted +here. +
+NOTE: In order to achieve an independent name space for the NuttX +interface functions, differences in function names and types are +to be expected and will not be identified as differences in these +paragraphs. +
+ +
+ 2.1 Task Control Interfaces+ |
+
+ Tasks. + NuttX is a flat address OS. As such it does not support processes + in the way that, say, Linux does. + NuttX only supports simple threads running within the same address space. + However, the programming model makes a distinction between tasks + and pthreads: +
++ File Descriptors and Streams. + This applies, in particular, in the area of opened file descriptors and streams. + When a task is started using the interfaces in this section, it will be created + with at most three open files. +
+ + If CONFIG_DEV_CONSOLE is defined, the first three file descriptors (corresponding + to stdin, stdout, stderr) will be duplicated for the new task. + Since these file descriptors are duplicated, the child task can free close + them or manipulate them in any way without effecting the parent task. + File-related operations (open, close, etc.) within a task will have no effect + on other tasks. + Since the three file descriptors are duplicated, it is also possible to perform + some level of redirection. + ++ pthreads, on the other hand, will always share file descriptors with the parent + thread. In this case, file operations will have effect only all pthreads the + were started from the same parent thread. +
+Executing Programs within a File System. + NuttX also provides internal interfaces for the execution of separately built + programs that reside in a file system. + These internal interfaces are, however, non-standard and are documented with the + NuttX binary loader and + NXFLAT. +
+Task Control Interfaces. + The following task control interfaces are provided by NuttX: +
++ Non-standard task control interfaces inspired by VxWorks interfaces: +
++ Standard interfaces +
+
+ Standard vfork and exec[v|l] interfaces:
+
+ Standard posix_spawn interfaces:
+
+ Non-standard task control interfaces inspired by posix_spawn:
+
+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 taskpriority. Priority of the new taskstack_size. size (in bytes) of the stack neededentry. Entry point of a new taskargv. 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: +
+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: +
++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: +
+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: +
++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: +
errno is not set).
++Assumptions/Limitations: +
+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 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: +
+taskDeleteHookAdd() is not supported).
+ However, if atexit() or on_exit support is enabled, those will be called when the task deleted.
+ task_delete() will re-direct processing to exit().
++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: +
++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: +
+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: +
++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: +
+code parameter is ignored.
++Function Prototype: +
+ #include <unistd.h> + pid_t getpid(void); ++ +
+Description: This function returns the task ID of the +calling task. The task ID will be invalid if called at the interrupt +level. +
+Input Parameters: None. +
+Returned Value: +
+Assumptions/Limitations: +
+POSIX Compatibility: +Compatible with the POSIX interface of the same name. +
+ ++ 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. +
+ ++ 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:
+
binfmt function exec(), and then
+ exit(0).
+
+ 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. +
+ ++ 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(). +
+ ++ 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.
+ vfork() and excec[l|v]() had been called.
+ + Assumptions/Limitations: +
+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.
+ envp argument is not used and the environ variable is not altered (NuttX does not support the environ variable).
+ POSIX_SPAWN_SETPGROUP above).
+ POSIX_SPAWN_RESETIDS above).
+ 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.
+
+ 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>.
+
+ +
+ 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>
+
+ +
+ 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>
+
+ 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>
+
+ 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>
+
+ 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>
+
+ 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>
+
+ 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>
+
+ 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>
+
+ 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>
+
+ 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>
+
+ 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>
+
+ 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>
+
+ 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>
+
+ 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().
+
+ 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>
+
+ 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>
+
+ 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 or sporadic scheduler.
+ The round-roben is similar to priority scheduling except that tasks with equal priority and share CPU time via time-slicing.
+ The time-slice interval is a constant determined by the configuration
+ setting CONFIG_RR_INTERVAL to a positive, non-zero value.
+ Sporadic scheduling scheduling is more complex, varying the priority of a thread over a replenishment period.
+ Support for sporadic scheduling is enabled by the configuration option CONFIG_SCHED_SPORADIC.
+
+ The OS interfaces described in the following paragraphs provide a POSIX- compliant interface to the NuttX scheduler: +
++ 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: +
++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: +
OK) if successful, otherwise -1 (ERROR).
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+ 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. +
+ ++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: +
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. + +
+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: +
OK) or -1 (ERROR)
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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: +
ERROR).
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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: +
ERROR)
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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 intervalEINVAL: 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:
+
wait(), waitpid() or waitid()).
+
+ 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.
+
+struct sigaction sa; + +sa.sa_handler = SIG_IGN; +sa.sa_flags = SA_NOCLDWAIT; +int ret = sigaction(SIGCHLD, &sa, NULL); ++ +
+Function Prototype: +
+ #include <sched.h> + int sched_lock(void); ++ +
+Description: This function disables context switching by +Disabling addition of new tasks to the ready-to-run task list. +The task that calls this function will be the only task that is +allowed to run until it either calls sched_unlock (the appropriate +number of times) or until it blocks itself. +
+Input Parameters: None. +
+Returned Value: +
+Assumptions/Limitations: +
+POSIX Compatibility: This is a NON-POSIX interface. +VxWorks provides the comparable interface: +
+ STATUS taskLock(void); ++ +
+Function Prototype: +
+ #include <sched.h> + int sched_unlock(void); ++ +
+Description: This function decrements the preemption lock +count. Typically this is paired with sched_lock() and concludes +a critical section of code. Preemption will not be unlocked until +sched_unlock() has been called as many times as sched_lock(). +When the lockCount is decremented to zero, any tasks that were +eligible to preempt the current task will execute. +
+Input Parameters: None. +
+Returned Value: +
+Assumptions/Limitations: +
+POSIX Compatibility: This is a NON-POSIX interface. +VxWorks provides the comparable interface: +
+ STATUS taskUnlock(void); ++ +
+Function Prototype: +
+ #include <sched.h> + int32_t sched_lockcount(void) ++ +
+Description: This function returns the current value of +the lockCount. If zero, preemption is enabled; if non-zero, this +value indicates the number of times that sched_lock() has been called +on this thread of execution. +
+Input Parameters: None. +
+Returned Value: +
+Assumptions/Limitations: +
+ POSIX Compatibility: None. +
+ ++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 ofwaitpid()is incomplete (but usable). + IfCONFIG_SCHED_HAVE_PARENTis defined,waitpid()will be a little more compliant to specifications. + WithoutCONFIG_SCHED_HAVE_PARENT,waitpid()simply supports waiting for any task to complete execution. + WithCONFIG_SCHED_HAVE_PARENT,waitpid()will useSIGCHLDand 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 ifwaitpid()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 forstat_loc. The location to return the exit statusoptions. 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:
+
pid is equal to (pid_t)-1), status is requested for any child process.
+ In this respect, waitpid() is then equivalent to wait().
+ pid is greater than 0, it specifies the process ID of a single child process for which status is requested.
+ pid is 0, status is requested for any child process whose process group ID is equal to that of the calling process.
+ 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:
+
main().
+ _exit() or exit() with a status argument of 0.
+
+ 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). +
+ ++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 ofwaitid()is incomplete (but usable). + IfCONFIG_SCHED_HAVE_PARENTis defined,waitid()will be a little more compliant to specifications. +waitpid()simply supports waiting a specific child task (P_PIDor for any child taskP_ALLto complete execution. +SIGCHLDis 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 ifwaitpid()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.
+
+
idtype is P_PID, waitid() will wait for the child with a process ID equal to (pid_t)id.
+ idtype is P_PGID, waitid() will wait for any child with a process group ID equal to (pid_t)id.
+ 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.
+ 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:
+ EINTR:
+ 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). +
+ ++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 ofwait()is incomplete (but usable). +wait()is based onwaitpaid(). + See the description ofwaitpaid()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()).
+
+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: +
+atexit function can be registered unless CONFIG_SCHED_ATEXIT_MAX defines a larger number.atexit() functions are not inherited when a new task is created.+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.
+
on_exit function can be registered unless CONFIG_SCHED_ONEXIT_MAX defines a larger number.on_exit() functions are not inherited when a new task is created.
+ 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. +
++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: +
ERROR)
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX interface +of the same name. +Differences from the full POSIX implementation include: +
+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: +
OK) if the message queue is closed successfully, otherwise,
+-1 (ERROR).
++Assumptions/Limitations: +
+
mq_send() or mq_receive() is undefined when mq_close() is called.
+ mq_close() is undefined.
+ + POSIX Compatibility: Comparable to the POSIX interface +of the same name. + +
+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. + +
+Function Prototype: +
++ #include <mqueue.h> + int mq_send(mqd_t mqdes, const void *msg, size_t msglen, int prio); ++
+Description:
+ This function adds the specified message, msg, to the message queue, mqdes.
+ The msglen parameter specifies the length of the message in bytes pointed to by msg.
+ This length must not exceed the maximum message length from the mq_getattr().
+
+ If the message queue is not full, mq_send() will place the msg
+ in the message queue at the position indicated by the prio argument.
+ Messages with higher priority will be inserted before lower priority messages
+ The value of prio must not exceed MQ_PRIO_MAX.
+
+ If the specified message queue is full and O_NONBLOCK is not
+ set in the message queue, then mq_send() will block until space
+ becomes available to the queue the message.
+
+ If the message queue is full and NON_BLOCK is set, the message
+ is not queued and ERROR is returned.
+
+ NOTE:
+ mq_send() may be called from an interrupt handler.
+ However, it behaves differently when called from the interrupt level:
+
+ Input Parameters: +
+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. +
+ ++ #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. +
+ ++ 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. +
+ ++ 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. +
+ ++ 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: +
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."
+ +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: +
OK) if attributes are set successfully, otherwise -1
+(ERROR).
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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: +
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:
+
+ At this point, the high-priority Task A cannot execute until + Task B (and possibly other medium-priority tasks) completes and until + Task C relinquishes the semaphore. In effect, the high-priority task, + Task A behaves as though it were lower in priority than the + low-priority task, Task C! This phenomenon is called priority + inversion. +
+
+ Some operating systems avoid priority inversion by automatically
+ increasing the priority of the low-priority Task C (the operable
+ buzz-word for this behavior is priority inheritance). NuttX
+ supports this behavior, but only if CONFIG_PRIORITY_INHERITANCE
+ is defined in your OS configuration file. If CONFIG_PRIORITY_INHERITANCE
+ is not defined, then it is left to the designer to provide implementations
+ that will not suffer from priority inversion.
+ The designer may, as examples:
+
+ Priority Inheritance.
+ As mentioned, NuttX does support priority inheritance provided that
+ CONFIG_PRIORITY_INHERITANCE is defined in your OS configuration file.
+ However, the implementation and configuration of the priority inheritance feature
+ is sufficiently complex that more needs to be said.
+ How can a feature that can be described by a single, simple sentence require such
+ a complex implementation:
+
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.
+
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: +
++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: +
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: +
+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: +
OK), or -1 (ERROR) if unsuccessful.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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.
+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: +
ERROR) if unsuccessful.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the full POSIX implementation include: +
+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: +
OK), or -1 (ERROR) if unsuccessful.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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: +
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: +
+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: +
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. + +
+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.
+
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: +
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. +
+ ++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: +
OK) or -1 (ERROR) if unsuccessful
+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. + +
+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: +
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. + +
+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: +
OK) or -1 (ERROR) if unsuccessful.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. +
+ +
+ 2.6 Clocks and Timers+ |
+
+ 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:
+
+ 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:
+
+ 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:
+
+ 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:
+
+ 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:
+
+#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:
+
+ Function Prototype: +
++#include <time.h> +#if defined(CONFIG_LIBC_LOCALTIME) || defined(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.
+
+ Function Prototype: +
++#include <time.h> +#if defined(CONFIG_LIBC_LOCALTIME) || defined(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.
+
+ 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:
+
+#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:
+
+ Function Prototype: +
++#include <time.h> +#if defined(CONFIG_LIBC_LOCALTIME) || defined(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.
+
+ Function Prototype: +
++#include <time.h> +#if defined(CONFIG_LIBC_LOCALTIME) || defined(CONFIG_TIME_EXTENDED) +FAR char *ctime_r(FAR const time_t *timep, FAR char *buf); +#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.
+
+ 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: +
+CLOCK_REALTIME is supported for the clockid argument.+ 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. +
+ ++ 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.
+
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 setovalue. 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: +
+ovalue argument is ignored.+ 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. +
+ ++ 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: +
++POSIX Compatibility: Comparable to the POSIX +interface of the same name. +
+ ++ 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: +
++ 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: +
++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: +
OK), or -1 (ERROR) if the signal set cannot be initialized.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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: +
OK), or -1 (ERROR) if the signal set cannot be initialized.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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: +
OK), or -1 (ERROR) if the signal number is invalid.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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: +
OK), or -1 (ERROR) if the signal number is invalid.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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: +
ERROR) if the signal number is invalid.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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: +
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: +
SIG_DFL is treated like SIG_IGN.
+ 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.
+ +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: +
ERROR) is returned with the errno value of EINVAL, for example, would indicate that signo argument is not a valid signal number.
++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: +
sigset() will the previous disposition of the signal.
+Otherwise, SIG_ERR will be returned and errno set to indicate the error.
++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: +
OK), or -1 (ERROR) if how is invalid.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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: +
ERROR) is returned with the errno value of EINVAL, for example, would indicate that signo argument is not a valid signal number.
++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: +
ERROR) is returned with the errno value of EINVAL, for example, would indicate that signo argument is not a valid signal number.
++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: +
OK) or -1 (ERROR)
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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: +
ERROR) always
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the POSIX specification include: +
+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.
++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: +
ERROR) is returned.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX interface of the same name. + +
+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: +
ERROR) is returned.
++Assumptions/Limitations: +
+ POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the POSIX interface include: +
+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: +
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: +
+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: +
+ Assumptions/Limitations: +
++ POSIX Compatibility: + Comparable to the POSIX interface of the same name. + Differences from the POSIX interface include: +
++Function Prototype: +
+ #include <unistd.h> + int pause(void); ++ +
+Description:
+ The pause() function will suspend the calling thread until delivery of a non-blocked signal.
+
+ 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: +
++ pthread control interfaces. + Interfaces that allow you to create and manage pthreads. +
++ Thread Specific Data. + These interfaces can be used to create pthread keys and then to access thread-specific data using these keys. + Each task group has its own set of pthread keys. + NOTES: (1) pthread keys create in one task group are not accessible in other task groups. + (2) The main task thread does not had thread-specific data. +
++ pthread Mutexes. +
++ Condition Variables. +
++ Barriers. +
++ Initialization. +
+ ++ Signals. +
+ ++ 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.+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. +
+
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. +
+
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. +
+
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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.+POSIX Compatibility: Comparable to the POSIX +interface of the same name. Except:
++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.+POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+ Function Prototype: +
++ #include <pthread.h> + int pthread_getschedparam(pthread_t thread, int *policy, + struct sched_param *param); ++
+ Description:
+ The pthread_getschedparam() functions will get the
+ scheduling policy and parameters of threads.
+ For SCHED_FIFO and SCHED_RR, the only
+ required member of the sched_param structure is the
+ priority sched_priority.
+
+ The pthread_getschedparam() function will retrieve the
+ scheduling policy and scheduling parameters for the thread whose thread
+ ID is given by thread and will store those values in
+ policy and param, respectively.
+ The priority value returned from pthread_getschedparam()
+ will be the value specified by the most recent pthread_setschedparam(),
+ pthread_setschedprio(), or pthread_create() call
+ affecting the target thread.
+ It will not reflect any temporary adjustments to its priority (such as might
+ result of any priority inheritance, for example).
+
+ The policy parameter may have the value SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC.
+ SCHED_RR requires the configuration setting CONFIG_RR_INTERVAL > 0;
+ SCHED_SPORADIC requires the configuration setting CONFIG_SCHED_SPORADIC=y.
+ (SCHED_OTHER and non-standard scheduler policies, in particular, are not supported).
+ The SCHED_FIFO and SCHED_RR policies will have a single
+ scheduling parameter:
+
sched_priority
+ The thread priority.
+
+ The SCHED_SPORADIC policy has four additional scheduling parameters:
+
sched_ss_low_priority
+ Low scheduling priority for sporadic server.
+ sched_ss_repl_period
+ Replenishment period for sporadic server.
+ sched_ss_init_budget
+ Initial budget for sporadic server.
+ sched_ss_max_repl
+ Maximum pending replenishments for sporadic server.
+ + 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. +
+ ++ 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.
+
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. +
+ ++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.
++POSIX Compatibility: Comparable to the POSIX +interface of the same name. +
+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. +
+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. +
+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: +
+
EINVAL.
++Assumptions/Limitations: +
+POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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 querytype. 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.+POSIX Compatibility: Comparable to the POSIX interface of the same name. + +
+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.+POSIX Compatibility: Comparable to the POSIX interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. + +
+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. + +
+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. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+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. +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +
+ 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. +
+ ++ 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. +
+ ++ 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. +
+ ++ 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. +
+ ++ 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. +
+ ++ 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. +
+ ++ 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. +
+ ++ 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. +
+ + ++ 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. +
+ ++ 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. +
+ ++ 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: +
+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: +
+Programming Interfaces. + The following environment variable programming interfaces are provided by Nuttx and are + described in detail in the following paragraphs. +
+getenvputenvclearenvsetenvunsetenvDisabling Environment Variable Support.
+ All support for environment variables can be disabled by setting CONFIG_DISABLE_ENVIRON
+ in the board configuration file.
+
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. +
+ +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. +
+ +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. +
+ +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. +
+ +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+ |
+
mmap() and eXecute In Place (XIP)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.
+
fcntl.hunistd.hsys/ioctl.hpoll.hsys/select.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, ...); ++ +
+ #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); ++ +
+ #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 ++ +
+ 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 0CONFIG_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 supportCONFIG_NET_TCP Defined for TCP/IP supportCONFIG_NSOCKET_DESCRIPTORS Defined to be greater than 0CONFIG_NET_TCP_READAHEAD Define to enable read-ahead bufferingCONFIG_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 invalidEINTR. 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.+ 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 eventswritefds. the set of descriptions to monitor for write-ready eventsexceptfds. the set of descriptions to monitor for error eventstimeout. 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()).+#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); ++ + +
+#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); ++ + +
+#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 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 vasprintf(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); ++ +
+ 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); ++ +
+#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); ++ +
+#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) ++ +
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.
+
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.
+
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
+ 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:
+
+ mmap() can be used to support eXecute In Place (XIP) on random access media
+ under the following very restrictive conditions:
+
+ 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.
+
+ 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.
+
+ Some limitations of this approach are as follows: +
+
+ Since no real mapping occurs, all of the file contents are "mapped" into memory. +
++ All mapped files are read-only. +
++ There are no access privileges. +
+
+ 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:
+
+ 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!
+
+ 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). +
++ All mapped files are read-only. You can write to the in-memory image, + but the file contents will not change. +
++ There are no access privileges. +
+
+ 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.
+
+ 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. +
+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: +
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. +
+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.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.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.+ 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.+ 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.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().
+
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.
+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: +
+
+ Returned Value:
+ See recvfrom().
+
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.
+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 socketlevel: Protocol level to set the optionoption: identifies the option to setvalue: Points to the argument valuevalue_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.
+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:
+
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.
+
+ 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.
+
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 identifiersmaddr: Determines mapping of the shared memory regionshmflg: 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.
+ 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 identifiercmd: shmctl() commandbuf: 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
+ 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: +
+ 3.2 Hidden Interface Structures+ |
+
+Several of the types used to interface with NuttX are +structures that are intended to be hidden from the application. +From the standpoint of the application, these structures (and +structure pointers) should be treated as simple handles to reference +OS resources. These hidden structures include: +
+ In order to maintain portability, applications should not reference + specific elements within these hidden structures. These hidden + structures will not be described further in this user's manual. +
+ +
+ 3.3 Access to the
+ |
+
+ 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: +
+
errno value.
+
+ 3.4 User Interface Structures+ |
+
+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[]); ++ +
+This structure is used to pass scheduling priorities to and from +NuttX; +
+ struct sched_param
+ {
+ int sched_priority;
+ };
+
+
++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 */
+ };
+
+
++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 */
+ };
+
+
++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
+
+
++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;
+
+
++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;
+ };
+
+
++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+ |
+
+ NxWidgets+Last Updated: March 27, 2012 + |
+
+ In order to better support NuttX based platforms, a special graphical userinterface has been created called NXWidgets. + NXWidgets is written in C++ and integrates seamlessly with the NuttX NX graphics subsystem in order to provide graphic objects, or "widgets," in the NX Graphics Subsystem +
++ Some of the features of NXWidgets include: +
++ Note: Many of the fundamental classed in NxWidgets derive from the Antony + Dzeryn's "Woopsi" project: http://woopsi.org/ which also has a BSD style + license. See the COPYING file for details. +
++ Release notes, DOxygen documentation, as well as downloads for the latest NxWidgets releases are available online: +
++ Thanks go to Jose Pablo Carballo for contributing this! +
+ + + diff --git a/Documentation/README.html b/Documentation/README.html new file mode 100644 index 0000000000..305aa8afa7 --- /dev/null +++ b/Documentation/README.html @@ -0,0 +1,429 @@ + + +
+ NuttX README Files+Last Updated: March 25, 2016 + |
+
+ 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.
+
+ Below is a guide to the available README files in the NuttX source tree: +
+ ++nuttx/ + |- README.txt + |- arch/ + | | + | |- arm/ + | | `- src + | | `- lpc214x/README.txt + | |- sh/ + | | |- include/ + | | | `-README.txt + | | |- src/ + | | | `-README.txt + | |- x86/ + | | |- include/ + | | | `-README.txt + | | `- src/ + | | `-README.txt + | |- z80/ + | | |- src/z80 + | | | `- README.txt + | | `- src/z180 + | | |- README.txt + | | `- z180_mmu.txt + | `- README.txt + |- binfmt/ + | |- libpcode/ + | `- README.txt + |- audio/ + | `- README.txt + |- configs/ + | |- amber/ + | | `- README.txt + | |- arduino-mega2560/ + | | `- README.txt + | |- arduino-due/ + | | `- README.txt + | |- avr32dev1/ + | | `- README.txt + | |- c5471evm/ + | | `- README.txt + | |- cc3200-launchpad/ + | | `- README.txt + | |- cloudctrl/ + | | `- README.txt + | |- compal_e86/ + | | `- README.txt + | |- compal_e88/ + | | `- README.txt + | |- compal_e99/ + | | `- README.txt + | |- demo9s12ne64/ + | | `- README.txt + | |- dk-tm4c129x/ + | | `- README.txt + | |- ea3131/ + | | `- README.txt + | |- ea3152/ + | | `- README.txt + | |- eagle100/ + | | `- README.txt + | |- efm32-g8xx-stk/ + | | `- README.txt + | |- efm32gg-stk3700/ + | | `- README.txt + | |- ekk-lm3s9b96/ + | | `- README.txt + | |- ez80f910200kitg/ + | | |- ostest/README.txt + | | `- README.txt + | |- ez80f910200zco/ + | | |- dhcpd/README.txt + | | |- httpd/README.txt + | | |- nettest/README.txt + | | |- nsh/README.txt + | | |- ostest/README.txt + | | |- poll/README.txt + | | `- README.txt + | |- fire-stm32v2/ + | | `- README.txt + | |- freedom-kl25z/ + | | `- README.txt + | |- freedom-kl26z/ + | | `- README.txt + | |- hymini-stm32v/ + | | |- RIDE/README.txt + | | `- README.txt + | |- kwikstik-k40/ + | | `- README.txt + | |- launchxl-tms57004/ + | | `- README.txt + | |- lincoln60/ + | | `- README.txt + | |- lm3s6432-s2e/ + | | `- README.txt + | |- lm3s6965-ek/ + | | `- README.txt + | |- lm3s8962-ek/ + | | `- README.txt + | |- lpc4330-xplorer/ + | | `- README.txt + | |- lpc4337-ws/ + | | `- README.txt + | |- lpc4357-evb/ + | | `- README.txt + | |- lpc4370-link2/ + | | `- README.txt + | |- lpcxpresso-lpc1115/ + | | `- README.txt + | |- lpcxpresso-lpc1768/ + | | `- README.txt + | |- maple/ + | | `- README.txt + | |- mbed/ + | | `- README.txt + | |- mcu123-lpc214x/ + | | `- README.txt + | |- micropendous3/ + | | `- README.txt + | |- mikroe-stm32f4/ + | | `- README.txt + | |- mirtoo/ + | | `- README.txt + | |- mt-db-x3// + | | `- README.txt + | |- moteino-mega/ + | | `- README.txt + | |- mx1ads/ + | | `- README.txt + | |- ne64badge/ + | | `- README.txt + | |- ntosd-dm320/ + | | |- doc/README.txt + | | `- README.txt + | |- nucleo-f4x1re/ + | | `- README.txt + | |- nucleus2g/ + | | `- README.txt + | |- nutiny-nuc120/ + | | `- README.txt + | |- olimex-efm32g880f129-stk/ + | | `- README.txt + | |- olimex-lpc1766stk/ + | | `- README.txt + | |- olimex-lpc2378/ + | | `- README.txt + | |- olimex-lpc-h3131/ + | | `- README.txt + | |- olimex-stm32-h405/ + | | `- README.txt + | |- olimex-stm32-h407/ + | | `- README.txt + | |- olimex-stm32-p107/ + | | `- README.txt + | |- olimex-stm32-p207/ + | | `- README.txt + | |- olimex-strp711/ + | | `- README.txt + | |- open1788/ + | | `- README.txt + | |- p112/ + | | `- README.txt + | |- pcblogic-pic32mx/ + | | `- README.txt + | |- pcduino-a10/ + | | `- README.txt + | |- pic32mx-starterkit/ + | | `- README.txt + | |- pic32mx7mmb/ + | | `- README.txt + | |- pic32mz-starterkit/ + | | `- README.txt + | |- pirelli_dpl10/ + | | `- README.txt + | |- qemu-i486/ + | | `- README.txt + | |- rgmp/ + | | `- README.txt + | |- sabre-6quad/ + | | `- README.txt + | |- sama5d2-xult/ + | | `- README.txt + | |- sama5d3x-ek/ + | | `- README.txt + | |- sama5d3-xplained/ + | | `- README.txt + | |- sama5d4-ek/ + | | `- README.txt + | |- samd20-xplained/ + | | `- README.txt + | |- samd21-xplained/ + | | `- README.txt + | |- saml21-xplained/ + | | `- README.txt + | |- sam3u-ek/ + | | `- README.txt + | |- sam4e-ek/ + | | `- README.txt + | |- sam4l-xplained/ + | | `- README.txt + | |- sam4s-xplained/ + | | `- README.txt + | |- sam4s-xplained-pro/ + | | `- README.txt + | |- same70-xplained/ + | | `- README.txt + | |- samv71-xult/ + | | `- README.txt + | |- shenzhou/ + | | `- README.txt + | |- sim/ + | | |- include/README.txt + | | `- README.txt + | |- skp16c26/ + | | `- README.txt + | |- spark/ + | | `- README.txt + | |- stm3210e-eval/ + | | |- RIDE/README.txt + | | `- README.txt + | |- stm3220g-eval/ + | | `- README.txt + | |- stm3240g-eval/ + | | `- README.txt + | |- stm32_tiny/ + | | `- README.txt + | |- stm32f3discovery/ + | | `- README.txt + | |- stm32f4discovery/ + | | `- README.txt + | |- stm32f429i-disco/ + | | |- ltdc/README.txt + | | `- README.txt + | |- stm32f746g-disco/ + | | `- README.txt + | |- stm32l476vg-disco/ + | | `- README.txt + | |- stm32ldiscovery/ + | | `- README.txt + | |- stm32vldiscovery/ + | | `- README.txt + | |- sure-pic32mx/ + | | `- README.txt + | |- teensy-2.0/ + | | `- README.txt + | |- teensy-3.1/ + | | `- README.txt + | |- teensy-lc/ + | | `- README.txt + | |- tm4c123g-launchpad/ + | | `- README.txt + | |- tm4c1294-launchpad/ + | | `- README.txt + | |- twr-k60n512/ + | | `- README.txt + | |- "u-blox-c027/ + | | `- README.txt + | |- ubw32/ + | | `- README.txt + | |- us7032evb1/ + | | `- README.txt + | |- viewtool-stm32f107/ + | | `- README.txt + | |- xtrs/ + | | `- README.txt + | |- z16f2800100zcog/ + | | |- ostest/README.txt + | | |- pashello/README.txt + | | `- README.txt + | |- z80sim/ + | | `- README.txt + | |- z8encore000zco/ + | | |- ostest/README.txt + | | `- README.txt + | |- z8f64200100kit/ + | | |- ostest/README.txt + | | `- README.txt + | |- zkit-arm-1769/ + | | `- README.txt + | |- zp214xpa/ + | | `- README.txt + | `- README.txt + |- drivers/ + | |- eeprom/ + | | `- README.txt + | |- lcd/ + | | `- README.txt + | |- mtd/ + | | `- README.txt + | |- sensors/ + | | `- README.txt + | |- sercomm/ + | | `- README.txt + | |- syslog/ + | | `- README.txt + | `- README.txt + |- fs/ + | |- binfs/ + | | `- README.txt + | |- mmap/ + | | `- README.txt + | |- nxffs/ + | | `- README.txt + | |- smartfs/ + | | `- README.txt + | |- procfs/ + | | `- README.txt + | `- unionfs/ + | `- README.txt + |- graphics/ + | `- README.txt + |- lib/ + | `- README.txt + |- libc/ + | `- README.txt + |- libnx/ + | `- README.txt + |- libxx/ + | `- README.txt + |- mm/ + | |- shm/ + | | `- README.txt + | `- README.txt + |- net/ + | `- README.txt + |- syscall/ + | `- README.txt + `- tools/ + `- README.txt ++ +
+ Below is a guide to the available README files in the semi-optional apps/ source tree:
+
+apps/ + |- README.txt + |- examples/ + | |- bastest/README.txt + | |- json/README.txt + | |- pashello/README.txt + | `- README.txt + |- gpsutils/ + | `- "minmea/README.txt + |- graphics/ + | `- "tiff/README.txt + |- interpreters/ + | |- bas/README.txt + | |- ficl/README.txt + | `- README.txt + |- modbus/ + | `- README.txt + |- netutils/ + | | |- discover/README.txt + | | |- ftpc/README.txt + | | |- json/README.txt + | | |- telnetd/README.txt + | `- README.txt + |- nshlib/ + | `- README.txt + |- NxWidgets/ + | `- README.txt + `- system/ + |- cdcacm/README.txt + |- i2c/README.txt + |- inifile/README.txt + |- install/README.txt + |- nxplayer/README.txt + |- symtab/README.txt + |- usbmsc/README.txt + |- zmodem/README.txt + `- zoneinfo/README.txt ++ +
+ Additional README.txt files in the other, related repositories: +
+ ++NxWidgets + |- Doxygen + | `- README.txt + |- tools + | `- README.txt + |- UnitTests + | `- README.txt + `- README.txt + +buildroot/ + `- README.txt + +tools/ + `- README.txt + +uClibc++/ + `- README.txt + +pascal/ + `- README + ++ + diff --git a/Documentation/UsbTrace.html b/Documentation/UsbTrace.html new file mode 100644 index 0000000000..7efb7ebccb --- /dev/null +++ b/Documentation/UsbTrace.html @@ -0,0 +1,452 @@ + + +
+ 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 tracingCONFIG_USBDEV_TRACE_NRECORDS: Number of trace entries to rememberTrace 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_ID |
+ Initialization events | +
TRACE_EP_ID |
+ Endpoint API calls | +
TRACE_DEV_ID |
+ USB device API calls | +
TRACE_CLASS_ID |
+ USB class driver API calls | +
TRACE_CLASSAPI_ID |
+ Other class driver system API calls | +
TRACE_CLASSSTATE_ID |
+ Track class driver state changes | +
TRACE_INTENTRY_ID |
+ Interrupt handler entry | +
TRACE_INTDECODE_ID |
+ Decoded interrupt event | +
TRACE_INTEXIT_ID |
+ Interrupt handler exit | +
TRACE_OUTREQQUEUED_ID |
+ Request queued for OUT endpoint | +
TRACE_INREQQUEUED_ID |
+ Request queued for IN endpoint | +
TRACE_READ_ID |
+ Read (OUT) action | +
TRACE_WRITE_ID |
+ Write (IN) action | +
TRACE_COMPLETE_ID |
+ Request completed | +
TRACE_DEVERROR_ID |
+ USB controller driver error event | +
TRACE_CLSERROR_ID |
+ USB class driver error event | +
Logged Events. + Each logged event is 32-bits in size and includes +
+8-bit Trace Data + The 8-bit trace data depends on the specific event ID. As examples, +
+include/nuttx/usb/usbdev_trace.h.
+ 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, orCONFIG_DEBUG and CONFIG_DEBUG_USBLog 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 |
+
| 1 | +Class API call 1: 0000 |
+
| 2 | +Class error: 19:0000 |
+
| + | usbserial_main: ERROR: Failed to open /dev/ttyUSB0 for reading: 107 |
+
| + | usbserial_main: Not connected. Wait and try again. |
+
| 3 | +Interrupt 1 entry: 0039 |
+
| 4 | +Interrupt decode 7: 0019 |
+
| 5 | +Interrupt decode 32: 0019 |
+
| 6 | +Interrupt decode 6: 0019 |
+
| 7 | +Class disconnect(): 0000 |
+
| 8 | +Device pullup(): 0001 |
+
| 9 | +Interrupt 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 ID | +8-bit EVENT DATA |
+ MEANING | +16-bit EVENT DATA |
+
|---|---|---|---|---|
| 1 | +TRACE_CLASSAPI_ID1 |
+ 1 | +USBSER_TRACECLASSAPI_SETUP1 |
+ 0000 | +
| 2 | +TRACE_CLSERROR_ID1 |
+ 19 | +USBSER_TRACEERR_SETUPNOTCONNECTED1 |
+ 0000 | +
| 3 | +TRACE_INTENTRY_ID1 |
+ 1 | +LPC17_TRACEINTID_USB2 |
+ 0039 | +
| 4 | +TRACE_INTDECODE_ID2 |
+ 7 | +LPC17_TRACEINTID_DEVSTAT2 |
+ 0019 | +
| 5 | +TRACE_INTDECODE_ID2 |
+ 32 | +LPC17_TRACEINTID_SUSPENDCHG2 |
+ 0019 | +
| 6 | +TRACE_INTDECODE_ID2 |
+ 6 | +LPC17_TRACEINTID_DEVRESET2 |
+ 0019 | +
| 7 | +TRACE_CLASS_ID1 |
+ 3 | +(See TRACE_CLASSDISCONNECT1) |
+ 0000 | +
| 8 | +TRACE_DEV_ID1 |
+ 6 | +(See TRACE_DEVPULLUP1) |
+ 0001 | +
| 9 | +TRACE_INTEXIT_ID1 |
+ 1 | +LPC17_TRACEINTID_USB2 |
+ 0000 | +
NOTES:
+ 1See include/nuttx/usb/usbdev_trace.h
+ 2See arch/arm/src/lpc17xx/lpc17_usbdev.c
+
+ In the above example you can see that: +
+drivers/usbdev/pl2303.c:
+
+static int pl2303_setup(FAR struct uart_dev_s *dev)
+{
+ ...
+ usbtrace(PL2303_CLASSAPI_SETUP, 0);
+ ...
+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;
+ }
+ ...
+
+ 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 new file mode 100644 index 0000000000..00321607ba --- /dev/null +++ b/Documentation/acronyms.txt @@ -0,0 +1,57 @@ +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 new file mode 100644 index 0000000000..e81f153aa2 Binary files /dev/null and b/Documentation/backgd.gif differ diff --git a/Documentation/favicon.ico b/Documentation/favicon.ico new file mode 100644 index 0000000000..2563e58430 Binary files /dev/null and b/Documentation/favicon.ico differ diff --git a/Documentation/pm.png b/Documentation/pm.png new file mode 100644 index 0000000000..d84d8642dc Binary files /dev/null and b/Documentation/pm.png differ diff --git a/Documentation/redirect.html b/Documentation/redirect.html new file mode 100644 index 0000000000..13e75cd05e --- /dev/null +++ b/Documentation/redirect.html @@ -0,0 +1,20 @@ + + + +
+ The NuttX RTOS+ |
+