commit 80e7408a7161c9f9b01c8ba2ee1e8a04eaca5ef4 Author: patacongo Date: Sat Feb 17 23:21:28 2007 +0000 NuttX RTOS git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@3 42af7a65-404d-4744-a932-0658087f49c3 diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html new file mode 100644 index 00000000000..576e2c86d76 --- /dev/null +++ b/Documentation/NuttxPortingGuide.html @@ -0,0 +1,121 @@ + + + +Nuttx Porting Manual + + + + +
+ +

Nuttx Operating System

+

Porting Guide

+ +

by

+

Gregory Nutt

+

Last Update: February 8, 2007

+
+ +

Table of Contents

+
  • 1.0 1.0 Introduction
    • +
  • 2.0 Directory Structure
    • + +
  • 3.0 Configuring and Building
    • + +
    +

    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 archectures + into the build. +

    +

    + See also arch/README.txt. +

    + +

    General Philosophy. + +

    +

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

    + + + +

    2.1 Documentation

    +

    2.2 arch

    +

    2.3 drivers

    +

    2.4 examples

    +

    2.5 fs

    +

    2.6 include

    +

    2.7 lib

    +

    2.8 mm

    +

    2.9 sched

    +

    2.10 tools

    + +
    +

    3.0 Configuring and Building

    + + + + + diff --git a/Documentation/NuttxUserGuide.html b/Documentation/NuttxUserGuide.html new file mode 100644 index 00000000000..c8e26278d34 --- /dev/null +++ b/Documentation/NuttxUserGuide.html @@ -0,0 +1,4105 @@ + + + +Nuttx Users Manual + + + + +
    +Nuttx Operating System +

    +User's Manual + +

    +by +

    +Gregory Nutt +

    +Last Update: January 28, 2007 +

    + +

    1.0 Introduction

    + +

    +This user's manual is divided into five sections: +

    +
    + +

    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 Values: 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 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. + +

    2.1.1 task_create

    + +

    +Function Prototype: +

    +   #include <sched.h>
+    int task_create(
+        char *name,
+        int priority,
+        int stack_size,
+        main_t entry,
+        char *arg1, char *arg2, char *arg3, char *arg4);
+
    + +

    +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 four (and only four) arguments must be passed for the + spawned functions. +

    +

    + The newly created task does not inherity characteristics + from the parent task: The new task is started at the + default system priority and with the SCHED_FIFO scheduling + policy. These characteristcs may be modified after the new + task has been started. +

    +

    +Input Parameters: +

    +

    + Returned Values: +

    + + +

    +Assumptions/Limitations: +

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

    +   int taskSpawn(
+      char *name,
+      int priority,
+      int options,
+      int stackSize,
+      FUNCPTR entryPt,
+      int arg1, int arg2, int arg3, int arg4, int arg5,
+      int arg6, int arg7, int arg8, int arg9, int arg10);
+
    + +

    +The Nuttx task_create() differs from VxWorks' taskSpawn() in the +following ways: +

    + +

    2.1.2 task_init

    + +

    +Function Prototype: +

    +   #include <sched.h>
+   STATUS task_init(
+      _TCB *tcb,
+      char *name,
+      int priority,
+      uint32 *stack,
+      uint32 stack_size,
+      maint_t entry,
+      int arg1, int arg2, int arg3, int arg4);
+
    + +

    +Description: +

    + This function initializes a Task Control Block (TCB) + in preparation for starting a new thread. +

    +

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

    +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    + +

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

    + +

    2.1.3 task_activate

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    STATUS task_activate( _TCB *tcb );
+
    + +

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

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

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

    + +

    2.1.4 task_delete

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    STATUS 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: +

    + +

    +Returned Values: +

    + +

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

    + +

    2.1.5 exit

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    void exit( int code );
+
+    #include <nuttx/unistd.h>
+    void _exit( int code );
+
    + +

    +Description: This function causes the calling task to cease +to exist -- its stack and TCB will be deallocated. exit differs from +_exit in that it flushs streams, closes file descriptors and will +execute any function registered with atexit(). +

    +Input Parameters: +

    + +

    +Returned Values: None. + +

    +Assumptions/Limitations: + +

    +POSIX Compatibility: This is equivalent to the ANSI interface: +

    +    void exit( int code );
+
    +And the unix interface: +
    +    void _exit( int code );
+
    + +

    +The Nuttx exit() differs from ANSI exit() in +the following ways: +

    + +

    2.1.6 task_restart

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    STATUS 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. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

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

    +    STATUS taskRestart (int tid);
+
    + +

    +The Nuttx task_restart() differs from VxWorks' taskRestart() in +the following ways: +

    + +

    2.1.7 getpid

    + +

    +Function Prototype: +

    +    #include <unistd.h>
+    pid_t getpid( void );
+
    + +

    +Description: This function returns the task ID of the +calling task. The task ID will be invalid if called at the interrupt +level. +

    +Input Parameters: None. +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

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

    2.2 Task Scheduling Interfaces

    + +

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

    +The OS interfaces described in the following paragraphs provide +a POSIX- compliant interface to the Nuttx scheduler. However, these +POSIX interfaces assume a greater range of scheduling options +than those provided by the Nuttx scheduler. As a result, many of +these POSIX interfaces are little more than stubs. + +

    2.2.1 sched_setparam

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    int sched_setparam( pid_t pid, const struct sched_param *param );
+
    + +

    +Description: This function sets the priority of the task +specified by pid input parameter. +

    +NOTE: Setting a task's priority to the same value has the similar +effect to sched_yield() -- The task will be moved to after all +other tasks with the same priority. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the full POSIX implementation include: +

    + +

    2.2.2 sched_getparam

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    int sched_getparam (pid_t pid, struct sched_param *param);
+
    + +

    +Description: This function gets the scheduling priority +of the task specified by pid. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.2.3 sched_setscheduler

    +

    +Function Prototype: +

    +    #include <sched.h>
+    int sched_setscheduler (pid_t pid, int policy, const struct sched_param *param);
+
    +

    + Description: + sched_setscheduler() sets both the scheduling policy + and the priority for the task identified by pid. + If pid equals zero, the scheduler of the calling + thread will be set. + The parameter 'param' holds the priority of the thread under the new policy. +

    +

    +Input Parameters: +

    +

    + Returned Values: + On success, sched_setscheduler() returns OK (zero). On + error, ERROR (-1) is returned, and errno is set appropriately: +

    + + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.2.4 sched_getscheduler

    +

    +Function Prototype: +

    +    #include <sched.h>
+    int sched_getscheduler (pid_t pid);
+
    +

    + Description: + sched_getscheduler() returns the scheduling policy + currently applied to the process identified by pid. If + pid equals zero, the policy of the calling process will + be retrieved. + * + * Inputs: + * + * Return Value: + + This function returns the current scheduling +policy. +

    +Input Parameters: +

    +

    +Returned Values: +

    +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the full POSIX implementation include: +

    + +

    2.2.5 sched_yield

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    int sched_yield( void );
+
    + +

    +Description: This function forces the calling task to give +up the CPU (only to other tasks at the same priority). +

    +Input Parameters: None. +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.2.6 sched_get_priority_max

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    int sched_get_priority_max (int policy)
+
    + +

    +Description: This function returns the value of the highest +possible task priority for a specified scheduling policy. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.2.7 sched_get_priority_min

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    int sched_get_priority_min (int policy);
+
    + +

    +Description: This function returns the value of the lowest +possible task priority for a specified scheduling policy. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.2.8 sched_get_rr_interval

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    int sched_get_rr_interval (pid_t pid, struct timespec *interval);
+
    + +

    + Description: + sched_rr_get_interval() writes the timeslice interval + for task identified by pid into the timespec structure + pointed to by interval. If pid is zero, the timeslice + for the calling process is written into 'interval. The + identified process should be running under the SCHED_RR + scheduling policy.' +

    +

    + Input Parameters: +

    + + +

    + Returned Values: + On success, sched_rr_get_interval() returns OK (0). On + error, ERROR (-1) is returned, and errno is set to: +

    + + +

    + Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX + interface of the same name. +

    + +

    2.3 Task Switching Interfaces

    + +

    2.3.1 sched_lock

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    STATUS 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 Values: +

    + +

    +Assumptions/Limitations: +

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

    +    STATUS taskLock( void );
+
    + +

    2.3.2 sched_unlock

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    STATUS 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 Values: +

    + +

    +Assumptions/Limitations: +

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

    +    STATUS taskUnlock( void );
+
    + +

    2.3.3 sched_lockcount

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    sint32 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 Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: None. +

    + +

    2.4 Named Message Queue Interfaces

    + +

    +The Nuttx supports POSIX named message queues for intertask communication. +Any task may send or receive messages on named message queues. +Interrupt handlers may send messages via named message queues. + +

    2.4.1 mq_open

    + +

    +Function Prototype: +

    +    #include <mqueue.h>
+    mqd_t mq_open( const char *mqName, int oflags, ... );
+
    + +

    +Description: This function establish a connection between +a named message queue and the calling task. After a successful +call of mq_open(), the task can reference the message queue using +the address returned by the call. The message queue remains usable +until it is closed by a successful call to mq_close(). +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX interface +of the same name. +Differences from the full POSIX implementation include: +

    + +

    2.4.2 mq_close

    + +

    +Function Prototype: +

    +    #include <mqueue.h>
+    int mq_close( mqd_t mqdes );
+
    + +

    +Description: This function is used to indicate that the +calling task is finished with the specified message queued mqdes. +The mq_close() deallocates any system resources allocated by the +system for use by this task for its message queue. +

    +If the calling task has attached a notification request to the message +queue via this mqdes (see mq_notify()), this attachment will be +removed and the message queue is available for another task to attach +for notification. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    +

    +

    + POSIX Compatibility: Comparable to the POSIX interface +of the same name. + +

    2.4.3 mq_unlink

    + +

    +Function Prototype: +

    +    #include <mqueue.h>
+    int mq_unlink( const char *mqName );
+
    + +

    +Description: This function removes the message queue named +by "mqName." If one or more tasks have the message queue +open when mq_unlink() is called, removal of the message queue +is postponed until all references to the message queue have been +closed. +

    +Input Parameters: +

    + +

    +Returned Values: None. +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.4.4 mq_send

    + +

    +Function Prototype: +

    +    #include <mqueue.h>
+    int mq_send( mqd_t mqdes, const void *msg, size_t msgLen, int msgPrio );
+
    + +

    +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 in the message +in the message queue at the position indicated by the "msgPrio" +argument. Messages with higher priority will be inserted before +lower priority messages. The value of "msgPrio" 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 osNON_BLOCK is set, the message +is not queued and ERROR is returned. +

    +Input Parameters: +

    + +

    +Returned Values: None. +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the full POSIX implementation include: +

    + +

    2.4.5 mq_receive

    + +

    +Function Prototype: +

    +    #include <mqueue.h>
+    int mq_receive( mqd_t mqdes, void *msg, size_t msgLen, int *msgPrio );
+
    + +

    +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 select message is removed from the queue and copied +to "msg." +

    +If the message queue is empty and O_NONBLOCK was not set, mq_receive() +will block until a message is added to the message queue. If more +than one task is waiting to receive a message, only the task with +the highest priority that has waited the longest will be unblocked. +

    +If the queue is empty and O_NONBLOCK is set, ERROR will be +returned. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the full POSIX implementation include: +

    + +

    2.4.6 mq_notify

    + +

    +Function Prototype: +

    +    #include <mqueue.h>
+    int mq_notify( mqd_t mqdes, const struct sigevent *notification );
+
    + +

    +Description: If the "notification" input parameter +is not NULL, this function connects the task with the message queue such +that the specified signal will be sent to the task whenever the message +changes from empty to non-empty. One notification can be attached +to a message queue. +

    +If "notification" is NULL, the attached notification +is detached (if it was held by the calling task) and the queue +is available to attach another notification. +

    +When the notification is sent to the registered task, its registration +will be removed. The message queue will then be available for +registration. +

    +Input Parameters: +

    + +

    +Returned Values: None. +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX interface +of the same name. +Differences from the full POSIX implementation include: +

    + +

    2.4.7 mq_setattr

    + +

    +Function Prototype: +

    +    #include <mqueue.h>
+    int mq_setattr( mqd_t mqdes, const struct mq_attr *mqStat,
+                     struct mq_attr *oldMqStat);
+
    + +

    +Description: This function sets the attributes associated +with the specified message queue "mqdes." Only the "O_NONBLOCK" +bit of the "mq_flags" can be changed. +

    +If "oldMqStat" is non-null, mq_setattr() will store +the previous message queue attributes at that location (just as +would have been returned by mq_getattr()). +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.4.8 mq_getattr

    + +

    +Function Prototype: +

    +    #include <mqueue.h>
+    int mq_getattr( mqd_t mqdes, struct mq_attr *mqStat);
+
    + +

    +Description: This functions gets status information and +attributes associated with the specified message queue. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.5 Counting Semaphore Interfaces

    + +

    +Semaphores. Semaphores are the basis for +synchronization and mutual exclusion in Nuttx. Nuttx supports +POSIX semaphores. +

    +Semaphores are the preferred mechanism for gaining exclusive access to a +resource. sched_lock() and sched_unlock() can also be used for this purpose. +However, sched_lock() and sched_unlock() have other undesirable side-affects +in the operation of the system: sched_lock() also prevents higher-priority +tasks from running that do not depend upon the semaphore-managed resource +and, as a result, can adversely affect system response times. +

    +Priority Inversion. Proper use of semaphores avoids the issues of +sched_lock(). However, consider the following example: +

      +
    1. Some low-priority task, Task C, acquires a semphore in order to +get exclusive access to a protected resource. +
    2. Task C is suspended to allow some high-priority task, +Task A, to execute. +
    3. Task A attempts to acquire the semaphore held by Task C and +gets blocked until Task C relinquishes the semaphore. +
    4. Task C is allowed to execute again, but gets suspended by some +medium-priority Task B. +
    +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 mutex semaphores). The Nuttx does not +support this behavior. As a consequence, it is left to the designer to +provide implementations that will not suffer from priority inversion. +The designer may, as examples: +

    +

    + +

    2.5.1 sem_init

    + +

    +Function Prototype: +

    +    #include <semaphore.h>
+    int sem_init ( sem_t *sem, int pshared, unsigned int value );
+
    + +

    +Description: This function initializes the UN-NAMED semaphore +sem. Following a successful call to sem_init(), the semaphore +may be used in subsequent calls to sem_wait(), sem_post(), and +sem_trywait(). The semaphore remains usable until it is destroyed. +

    +Only sem itself may be used for performing synchronization. The +result of referring to copies of sem in calls to sem_wait(), +sem_trywait(), sem_post(), and sem_destroy(), is +not defined. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the full POSIX implementation include: +

    + +

    2.5.2 sem_destroy

    + +

    +Function Prototype: +

    +    #include <semaphore.h>
+    int sem_destroy ( sem_t *sem );
+
    + +

    +Description: This function is used to destroy the un-named semaphore +indicated by sem. Only a semaphore that was created using +sem_init() may be destroyed using sem_destroy(). The effect +of calling sem_destroy() with a named semaphore is undefined. The +effect of subsequent use of the semaphore sem is undefined until +sem is re-initialized by another call to sem_init(). +

    +The effect of destroying a semaphore upon which other tasks are currently +blocked is undefined. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.5.3 sem_open

    + +

    +Function Prototype: +

    +    #include <semaphore.h>
+    sem_t *sem_open ( const char *name, int oflag, ...);
+
    + +

    +Description: This function establishes a connection between +named semaphores and a task. Following a call to sem_open() with +the semaphore name, the task may reference the semaphore associated +with name using the address returned by this call. The semaphore +may be used in subsequent calls to sem_wait(), sem_trywait(), +and sem_post(). The semaphore remains usable until the semaphore +is closed by a successful call to sem_close(). +

    +If a task makes multiple calls to sem_open() with the same name, +then the same semaphore address is returned (provided there have +been no calls to sem_unlink()). +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the full POSIX implementation include: +

    + +

    2.5.4 sem_close

    + +

    +Function Prototype: +

    +    #include <semaphore.h>
+    int sem_close ( sem_t *sem );
+
    + +

    +Description: This function is called to indicate that the +calling task is finished with the specified named semaphore, sem. +The sem_close() deallocates any system resources allocated by +the system for this named semaphore. +

    +If the semaphore has not been removed with a call to sem_unlink(), +then sem_close() has no effect on the named semaphore. However, +when the named semaphore has been fully unlinked, the semaphore +will vanish when the last task closes it. +

    +Care must be taken to avoid risking the deletion of a semaphore +that another calling task has already locked. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.5.5 sem_unlink

    + +

    +Function Prototype: +

    +    #include <semaphore.h>
+    int sem_unlink ( const char *name );
+
    + +

    +Description: This function will remove the semaphore named by the +input name parameter. If one or more tasks have the semaphore named by +name oepn when sem_unlink() is called, destruction of the semaphore will +be postponed until all references have been destroyed by calls to +sem_close(). +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the full POSIX implementation include: +

    + +

    2.5.6 sem_wait

    + +

    +Function Prototype: +

    +    #include <semaphore.h>
+    int sem_wait ( sem_t *sem );
+
    + +

    +Description: This function attempts to lock the semaphore +referenced by sem. If the semaphore as already locked by another +task, the calling task will not return until it either successfully acquires +the lock or the call is interrupted by a signal. +

    +Input Parameters: +

    + +

    +Returned Values: +

    +

    +If sem_wait returns -1 (ERROR) then the cause of the failure +will be indicated by the thread-specific errno value (a pointer +to this value can be obtained using get_errno_ptr()). The following +lists the possible values for errno: +

    +

    +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.5.7 sem_trywait

    + +

    +Function Prototype: +

    +    #include <semaphore.h>
+    int sem_trywait ( sem_t *sem );
+
    + +

    +Description: This function locks the specified semaphore +only if the semaphore is currently not locked. In any event, the call +returns without blocking. +

    +Input Parameters: +

    + +

    +Returned Values: +

    +If sem_wait returns -1 (ERROR) then the cause of the failure +will be indicated by the thread-specific errno value (a pointer +to this value can be obtained using get_errno_ptr()). The following +lists the possible values for errno: +

    +

    +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.5.8 sem_post

    + +

    +Function Prototype: +

    +    #include <semaphore.h>
+    int sem_post ( sem_t *sem );
+
    + +

    +Description: When a task has finished with a semaphore, +it will call sem_post(). This function unlocks the semaphore referenced +by sem by performing the semaphore unlock operation. +

    +If the semaphore value resulting from this operation is positive, then +no tasks were blocked waiting for the semaphore to become unlocked; +The semaphore value is simply incremented. +

    +If the value of the semaphore resulting from this operation is zero, then +on of the tasks blocked waiting for the semaphore will be allowed to +return successfully from its call to sem_wait(). +

    +NOTE: sem_post() may be called from an interrupt handler. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: This function cannot be called +from an interrupt handler. It assumes the currently executing +task is the one that is performing the unlock. +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.5.9 sem_getvalue

    + +

    +Function Prototype: +

    +    #include <semaphore.h>
+    int sem_getvalue ( sem_t *sem, int *sval );
+
    + +

    +Description: This function updates the location referenced +by sval argument to have the value of the semaphore referenced +by sem without effecting the state of the semaphore. The updated +value represents the actual semaphore value that occurred at some +unspecified time during the call, but may not reflect the actual +value of the semaphore when it is returned to the calling task. +

    +If sem is locked, the value return by sem_getvalue() will either +be zero or a negative number whose absolute value represents the +number of tasks waiting for the semaphore. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    + +

    2.6 Watchdog Timer Interfaces

    + +

    +The 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 +the watchdog timer function. However, the watchdog timer function +may use mq_send(), and sigqueue() to communicate with Nuttx tasks. + +

    2.6.1 wd_create

    + +

    +Function Prototype: +

    +    #include <wdog.h>
+    WDOG_ID wd_create (void);
+
    + +

    +Description: The wd_create function will create a watchdog +by allocating the appropriate resources for the watchdog. +

    +Input Parameters: None. +

    +Returned Values: +

    + +

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

    + +

    2.6.2 wd_delete

    + +

    +Function Prototype: +

    +    #include <wdog.h>
+    STATUS wd_delete (WDOG_ID wdId);
+
    + +

    +Description: The wd_delete function will deallocate a +watchdog. The watchdog will be removed from the timer queue if +has been started. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +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 wdId);
+
    + +

    +Differences from the VxWorks interface include: +

    + +

    2.6.3 wd_start

    + +

    +Function Prototype: +

    +    #include <wdog.h>
+    STATUS wd_start( WDOG_ID wdId, int delay, wdentry_t wdentry,
+                     int parm1, int parm2, int parm3, int parm4 );
+
    + +

    +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, but +with the PIC/PID address environment that was in place when wd_start() +was called. +

    +Watchdog timers execute only once. +

    +To replace either the timeout delay or the function to be executed, +call wd_start again with the same wdId; only the most recent +wd_start() on a given watchdog ID has any effect. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +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 wdId, int delay, FUNCPTR wdentry, int parameter);
+
    + +

    +Differences from the VxWorks interface include: +

    + +

    2.6.4 wd_cancel

    + +

    +Function Prototype: +

    +    #include <wdog.h>
+    STATUS wd_cancel (WDOG_ID wdId);
+
    + +

    +Description: This function cancels a currently running +watchdog timer. Watchdog timers may be canceled from the interrupt +level. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

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

    +    STATUS wdCancel (WDOG_ID wdId);
+
    + +
    + +

    2.7 Signal Interfaces

    + +

    +The Nuttx provides signal interfaces for tasks. Signals are +used to alter the flow control of tasks by communicating asynchronous +events within or between task contexts. Any task or interrupt +handler can post (or send) a signal to a particular task. 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. +

    +Signal handlers execute in the context of the task that registered +the signal handler. +

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

    +Tasks may also suspend themselves and wait until a signal is received. + +

    2.7.1 sigemptyset

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int sigemptyset(sigset_t *set);
+
    + +

    +Description: This function initializes the signal set specified +by set such that all signals are excluded. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.7.2 sigfillset

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int sigfillset(sigset_t *set);
+
    + +

    +Description: This function initializes the signal set specified +by set such that all signals are included. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.7.3 sigaddset

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int sigaddset(sigset_t *set, int signo);
+
    + +

    +Description: This function adds the signal specified by +signo to the signal set specified by set. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.7.4 sigdelset

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int sigdelset(sigset_t *set, int signo);
+
    + +

    +Description: This function deletes the signal specified +by signo from the signal set specified by set. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.7.5 sigismember

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int  sigismember(const sigset_t *set, int signo);
+
    + +

    +Description: This function tests whether the signal specified +by signo is a member of the set specified by set. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.7.6 sigaction

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int sigaction( int signo, const struct sigaction *act,
+                   struct sigaction *oact );
+
    + +

    +Description: This function allows the calling task to +examine and/or specify the action to be associated with a specific +signal. +

    +The structure sigaction, used to describe an action to be taken, is defined +to include the following members: +

    +

    +If the argument act is not NULL, it points to a structure specifying the +action to be associated with the specified signal. If the argument oact +is not NULL, the action previously associated with the signal is stored +in the location pointed to by the argument oact. If the argument act is +NULL, signal handling is unchanged by this function call; thus, the call +can be used to enquire about the current handling of a given signal. +

    +When a signal is caught by a signal-catching function installed by the +sigaction() function, a new signal mask is calculated and installed for +the duration of the signal-catching function. This mask is formed by taking +the union of the current signal mask and the value of the sa_mask for the +signal being delivered, and then including the signal being delivered. If +and when the signal handler returns, the original signal mask is restored. +

    +Signal catching functions execute in the same address environment as the +task that called sigaction() to install the signal-catching function. +

    +Once an action is installed for a specific signal, it remains installed +until another action is explicitly requested by another call to +sigaction(). +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the POSIX implementation include: +

    + +

    2.7.7 sigprocmask

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int sigprocmask(int how, const sigset_t *set, sigset_t *oset);
+
    + +

    +Description: This function allows the calling task to +examine and/or change its signal mask. If the set is not NULL, +then it points to a set of signals to be used to change the currently +blocked set. The value of how indicates the manner in which the +set is changed. +

    +If there are any pending unblocked signals after the call to sigprocmask(), +those signals will be delivered before sigprocmask() returns. +

    +If sigprocmask() fails, the signal mask of the task is not changed. +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.7.8 sigpending

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int sigpending( sigset_t *set );
+
    + +

    +Description: This function stores the returns the set of +signals that are blocked for delivery and that are pending for +the calling task in the space pointed to by set. +

    +If the task receiving a signal has the signal blocked via its +sigprocmask, the signal will pend until it is unmasked. Only one pending +signal (for a given signo) is retained by the system. This is consistent +with POSIX which states: "If a subsequent occurrence of a pending +signal is generated, it is implementation defined as to whether the signal +is delivered more than once." +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.7.9 sigsuspend

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int sigsuspend( const sigset_t *set );
+
    + +

    +Description: The sigsuspend() function replaces the signal mask +with the set of signals pointed to by the argument set and then suspends +the task until delivery of a signal to the task. +

    +If the effect of the set argument is to unblock a pending signal, then +no wait is performed. +

    +The original signal mask is restored when sigsuspend() returns. +

    +Waiting for an empty signal set stops a task without freeing any +resources (a very bad idea). +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the POSIX specification include: +

    + +

    2.7.10 sigwaitinfo

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int sigwaitinfo(const sigset_t *set, struct siginfo *info);
+
    + +

    +Description: This function is equivalent to sigtimedwait() +with a NULL timeout parameter. (see below). +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.7.11 sigtimedwait

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int sigtimedwait( const sigset_t *set, struct siginfo *info,
+                      const struct timespec *timeout );
+
    + +

    +Description: This function selects the pending signal set +specified by the argument set. If multiple signals are pending in set, +it will remove and return the lowest numbered one. If no signals in set +are pending at the time of the call, the calling task will be suspended +until one of the signals in set becomes pending OR until the task +interrupted by an unblocked signal OR until the time interval specified by +timeout (if any), has expired. If timeout is NULL, then the timeout interval +is forever. +

    +If the info argument is non-NULL, the selected signal number is +stored in the si_signo member and the cause of the signal is store +in the si_code member. The content of si_value is only meaningful +if the signal was generated by sigqueue(). The following values +for si_code are defined in signal.h: +

    + +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the POSIX interface include: +

    + +

    2.7.12 sigqueue

    + +

    +Function Prototype: +

    +    #include <signal.h>
+    int sigqueue (int tid, int signo, const union sigval value);
+
    + +

    +Description: This function sends the signal specified by +signo with the signal parameter value to the task specified +by tid. +

    +If the receiving task has the signal blocked via its sigprocmask, +the signal will pend until it is unmasked. Only one pending signal +(for a given signo) is retained by the system. This is consistent with +POSIX which states: "If a subsequent occurrence of a pending signal +is generated, it is implementation defined as to whether the signal +is delivered more than once." +

    +Input Parameters: +

    + +

    +Returned Values: +

    + +

    +Assumptions/Limitations: +

    + POSIX Compatibility: Comparable to the POSIX +interface of the same name. +Differences from the POSIX interface include: +

    + +

    2.8 Pthread Interfaces

    +

    +

    2.8.1 pthread_attr_init

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_attr_init(pthread_attr_t *attr);
+
    +

    +Description: +Initializes a thread attributes object (attr) with default values +for all of the individual attributes used by the implementation. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. +

    +

    2.8.2 pthread_attr_destroy

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_attr_destroy(pthread_attr_t *attr);
+
    +

    +Description: +An attributes object can be deleted when it is no longer needed. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. +

    +

    2.8.3 pthread_attr_setschedpolicy

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.4 pthread_attr_getschedpolicy

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_attr_getschedpolicy(pthread_attr_t *attr, int *policy);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.5 pthread_attr_setschedparam

    +

    +Function Prototype: +

    +

    +   #include <pthread.h>
+    int pthread_attr_setschedparam(pthread_attr_t *attr,
+				      const struct sched_param *param);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.6 pthread_attr_getschedparam

    +

    +Function Prototype: +

    +

    +   #include <pthread.h>
+     int pthread_attr_getschedparam(pthread_attr_t *attr,
+				      struct sched_param *param);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.7 pthread_attr_setinheritsched

    +

    +Function Prototype: +

    +

    +   #include <pthread.h>
+    int pthread_attr_setinheritsched(pthread_attr_t *attr,
+					int inheritsched);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. +

    +

    2.8.8 pthread_attr_getinheritsched

    +

    +Function Prototype: +

    +

    +   #include <pthread.h>
+     int pthread_attr_getinheritsched(const pthread_attr_t *attr,
+					int *inheritsched);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.9 pthread_attr_setstacksize

    +

    +Function Prototype: +

    +

    +   #include <pthread.h>
+    int pthread_attr_setstacksize(pthread_attr_t *attr, long stacksize);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.10 pthread_attr_getstacksize

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+   int pthread_attr_getstacksize(pthread_attr_t *attr, long *stackaddr);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.11 pthread_create

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_create(pthread_t *thread, pthread_attr_t *attr,
+			  pthread_startroutine_t startRoutine,
+			  pthread_addr_t arg);
+
    +

    +Description: +To create a thread object and runnable thread, a routine +must be specified as the new thread's start routine. An +argument may be passed to this routine, as an untyped +address; an untyped address may also be returned as the +routine's value. An attributes object may be used to +specify details about the kind of thread being created. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.12 pthread_detach

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_detach(pthread_t thread);
+
    +

    +Description: +A thread object may be "detached" to specify that the +return value and completion status will not be requested. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.13 pthread_exit

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    void pthread_exit(pthread_addr_t pvValue);
+
    +

    +Description: +A thread may terminate it's own execution. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.14 pthread_cancel

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_cancel(pthread_t thread);
+
    +

    +Description: + +

    The pthread_cancel() function shall request that thread +be canceled. The target thread's cancelability state determines +when the cancellation takes effect. When the +cancellation is acted on, thread shall 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: +

    +

    +

    +Returned Values: +

    +If successful, the ptnread_cancel() function will return zero (OK). +Otherwise, an error number will be returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. Except:

    + + +

    2.8.15 pthread_setcancelstate

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_setcancelstate(int state, int *oldstate);
+
    +

    +Description: +

    The pthread_setcancelstate() function atomically +sets both the calling thread's 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 cancelation may occur at the time that the +cancelation state is set to PTHREAD_CANCEL_ENABLE.

    + +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the pthread_setcancelstate() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.16 pthread_setcancelstate

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_setcancelstate(int state, int *oldstate);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.17 pthread_join

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_join(pthread_t thread, pthread_addr_t *ppvValue);
+
    +

    +Description: +A thread can await termination of another thread and retrieve +the return value of the thread. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.18 pthread_yield

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    void pthread_yield(void);
+
    +

    +Description: +A thread may tell the scheduler that its processor can be +made available. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.19 pthread_self

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    pthread_t pthread_self(void);
+
    +

    +Description: +A thread may obtain a copy of its own thread handle. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.20 pthread_getschedparam

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_getschedparam(pthread_t thread, int *policy,
+				 struct sched_param *param);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.21 pthread_setschedparam

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_setschedparam(pthread_t thread, int policy,
+				 const struct sched_param *param);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.22 pthread_key_create

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_key_create( pthread_key_t *key, void (*destructor)(void*) )
+
    +

    +Description: +

    +This function creates a thread-specific data key visible +to all threads in the system. Although the same key value +may be used by different threads, the values bound to +the key by pthread_setspecific() are maintained on a +per-thread basis and persist for the life of the calling +thread. +

    +Upon key creation, the value NULL will be associated with +the the new key in all active threads. Upon thread +creation, the value NULL will be associated with all +defined keys in the new thread. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the pthread_key_create() function will +store the newly created key value at *key and return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. +

    + +

    2.8.23 pthread_setspecific

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_setspecific( pthread_key_t key, void *value )
+
    +

    +Description: +

    +The pthread_setspecific() function associates a thread- +specific value with a key obtained via a previous call +to pthread_key_create(). Different threads may bind +different values to the same key. These values are +typically pointers to blocks of dynamically allocated +memory that have been reserved for use by the calling +thread. +

    +The effect of calling pthread_setspecific() with a key value +not obtained from pthread_key_create() or after a key has been +deleted with pthread_key_delete() is undefined. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, pthread_setspecific() will return zero (OK). +Otherwise, an error number will be returned: +

    +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. +

    + +

    2.8.24 pthread_getspecific

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    void *pthread_getspecific( pthread_key_t key )
+
    +

    +Description: +

    +The pthread_getspecific() function returns the value +currently bound to the specified key on behalf of the +calling thread. +

    +The effect of calling pthread_getspecific() with a key value +not obtained from pthread_key_create() or after a key has been +deleted with pthread_key_delete() is undefined. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +The function pthread_getspecific() returns the thread- +specific data associated with the given key. If no +thread specific data is associated with the key, then +the value NULL is returned. +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. +

    + +

    2.8.25 pthread_key_delete

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_key_delete( pthread_key_t key )
+
    +

    +Description: +

    +This POSIX function should delete a thread-specific data +key previously returned by pthread_key_create(). However, +this function does nothing in the present implementation. +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.26 pthread_mutexattr_init

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_mutexattr_init(pthread_mutexattr_t *attr);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.27 pthread_mutexattr_destroy

    +

    +Function Protoype: +

    +

    +    #include <pthread.h>
+    int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.28 pthread_mutexattr_getpshared

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_mutexattr_getpshared(pthread_mutexattr_t *attr,
+					int *pshared);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.29 pthread_mutexattr_setpshared

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+   int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
+					int pshared);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.30 pthread_mutex_init

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_mutex_init(pthread_mutex_t *mutex,
+			      pthread_mutexattr_t *attr);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.31 pthread_mutex_destroy

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_mutex_destroy(pthread_mutex_t *mutex);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.32 pthread_mutex_lock

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_mutex_lock(pthread_mutex_t *mutex);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.33 pthread_mutex_trylock

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_mutex_trylock(pthread_mutex_t *mutex);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.34 pthread_mutex_unlock

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_mutex_unlock(pthread_mutex_t *mutex);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.35 pthread_condattr_init

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_condattr_init(pthread_condattr_t *attr);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.36 pthread_condattr_destroy

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_condattr_destroy(pthread_condattr_t *attr);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.37 pthread_cond_init

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_cond_init(pthread_cond_t *cond, pthread_condattr_t *attr);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.38 pthread_cond_destroy

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_cond_destroy(pthread_cond_t *cond);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.39 pthread_cond_broadcast

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_cond_broadcast(pthread_cond_t *cond);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.40 pthread_cond_signal

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_cond_signal(pthread_cond_t *dond);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.41 pthread_cond_wait

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    2.8.42 pthread_cond_timedwait

    +

    +Function Prototype: +

    +

    +    #include <pthread.h>
+    int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex,
+				  const struct timespec *abstime);
+
    +

    +Description: +

    +Input Parameters: +

    +

    +

    +Returned Values: +

    +If successful, the xxx() function will return +zero (OK). Otherwise, an error number will be +returned to indicate the error: +

    +

    +Assumptions/Limitations: +

    +POSIX Compatibility: Comparable to the POSIX +interface of the same name. + +

    +

    +

    3.0 OS Data Structures

    +

    3.1 Scalar types

    +

    +Many of the types used to communicate with Nuttx are simple +scalar types. These types are used to provide architecture independence +of the OS from the application. The scalar types used at the Nuttx +interface include: +

    + +

    3.2 Hidden Interface Structures

    +

    +Several of the types used to interface with Nuttx are +structures that are intended to be hidden from the application. +From the standpoint of the application, these structures (and +structure pointers) should be treated as simple handles to reference +OS resources. These hidden structures include: +

    +

    +In order to maintain portability, applications should not reference +specific elements within these hidden structures. These hidden +structures will not be described further in this user's manual. +

    + +

    3.3. Access to the errno Variable

    +

    +A pointer to the thread-specific errno. value is available through a +function call: +

    +Function Prototype: +

    +

        int *get_errno_ptr( void )
    +

    +Description: osGetErrnorPtr() returns a pointer to +the thread-specific errno value. +

    +This differs somewhat from the use for errno in a multi-threaded process environment: +Each pthread will have its own private copy of errno and the errno will not be shared +between pthreads. +

    +Input Parameters: None +

    +Returned Values: +

    +

    +

    + +

    3.4 User Interface Structures

    +

    +

    3.4.1 main_t

    +

    +main_t defines the type of a task entry point. main_t is declared +in sys/types.h as: +

    +    typedef int (*main_t)(int argc, char *argv[]);
+
    + +

    3.4.2 struct sched_param

    + +

    +This structure is used to pass scheduling priorities to and from +Nuttx; +

    +    struct sched_param
+    {
+      int sched_priority;
+    };
+
    + +

    3.4.3 struct timespec

    + +

    +This structure is used to pass timing information between the +Nuttx and a user application: +

    +    struct timespec
+    {
+      time_t tv_sec;  /* Seconds */
+      long   tv_nsec; /* Nanoseconds */
+    };
+
    + +

    3.4.4 struct mq_attr

    + +

    +This structure is used to communicate message queue attributes +between Nuttx and a MoBY application: +

    +    struct mq_attr {
+      size_t       mq_maxmsg;   /* Max number of messages in queue */
+      size_t       mq_msgsize;  /* Max message size */
+      unsigned     mq_flags;    /* Queue flags */
+      size_t       mq_curmsgs;  /* Number of messages currently in queue */
+    };
+
    + +

    3.4.5 struct sigaction

    + +

    +The following structure defines the action to take for given signal: +

    +    struct sigaction {
+      union {
+        saHandType      *_sa_handler;
+        saVxHandType    *_sa_sigaction;
+      } sa_u;
+      sigset_t           sa_mask;
+      int                sa_flags;
+    };
+    #define sa_handler   sa_u._sa_handler
+    #define sa_sigaction sa_u._sa_sigaction
+
    + +

    +where: +

    +    typedef void saHandType( int signo );
+    typedef void saVxHandType( int signo, siginfo_t *info, void *context );
+
    + +

    3.4.6 struct siginfo/siginfo_t

    + +

    +The following types is used to pass parameters to/from signal +handlers: +

    +    typedef struct siginfo
+    {
+      int          si_signo;
+      int          si_code;
+      union sigval si_value;
+   } siginfo_t;
+
    + +

    3.4.7 union sigval

    + +

    +This defines the type of the struct siginfo si_value field and +is used to pass parameters with signals. +

    +    union sigval
+    {
+      int   sival_int;
+      void *sival_ptr;
+    };
+
    + +

    3.4.8 struct sigevent

    + +

    +The following is used to attach a signal to a message queue to +notify a task when a message is available on a queue. +

    +    struct sigevent
+    {
+      int          sigev_signo;
+      union sigval sigev_value;
+      int          sigev_notify;
+    };
+
    +
    + +

    4.0 Known Problems

    + +

    +This section documents know problems with Nuttx at the time +of this writing. +

    +

    +Problem: +There is a problem with the unblock logic in os_signal.c when message queue +becomes not-empty -- sig_mqnotempty() calls sig_received(). +sig_received() relies on task_state == TSTATE_WAIT_SIG and will ignore +tasks that are waiting on a message queue to become non-empty. +

    +Priority: LOW. If a task is blocked a waiting for a message +queue to become non-empty, it will be re-started anyway. +

    + +Problem: task_restart won't restart a running task +

    +Priority: LOW. + + +