User's Manual @@ -30,9 +30,9 @@ Gregory Nutt This user's manual is divided into three sections:
-This section describes each C-callable interface to the Nuttx +This section describes each C-callable interface to the NuttX Operating System. The description of each interface is presented in the following format:
@@ -77,10 +77,10 @@ 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 +NuttX interface and its corresponding POSIX interface will be noted here.
-NOTE: In order to achieve an independent name space for the Nuttx +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. @@ -90,9 +90,9 @@ paragraphs.
Tasks. -Nuttx is a flat address OS. As such it does not support "processes" +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. +NuttX only supports simple threads running within the same address space. However, the programming model makes a distinction between "tasks" and pthreads:
@@ -144,17 +144,28 @@ were started from the same parent thread. 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
+ Note that an arbitrary number of arguments may be passed to the
+ spawned functions. The maximum umber of arguments is an OS
+ configuration parameter (CONFIG_MAX_TASK_ARGS).
+
+ 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 characteristcs 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:
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 Values: @@ -192,14 +207,13 @@ VxWorks provides the following similar interface:
-The Nuttx task_create() differs from VxWorks' taskSpawn() in the +The NuttX task_create() differs from VxWorks' taskSpawn() in the following ways:
#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);
+ _TCB *tcb,
+ char *name,
+ int priority,
+ uint32 *stack,
+ uint32 stack_size,
+ maint_t entry,
+ const char *argv[]);
Description:
This function initializes a Task Control Block (TCB)
- in preparation for starting a new thread.
+ 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. @@ -237,7 +252,11 @@ ten).
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.
@@ -272,13 +291,13 @@ VxWorks provides the following similar interface:
-The Nuttx task_init() differs from VxWorks' taskInit() in the +The NuttX task_init() differs from VxWorks' taskInit() in the following ways:
-The Nuttx task_activate() differs from VxWorks' taskActivate() in the +The NuttX task_activate() differs from VxWorks' taskActivate() in the following ways:
-The Nuttx task_delete() differs from VxWorks' taskDelete() in +The NuttX task_delete() differs from VxWorks' taskDelete() in the following ways:
-The Nuttx exit() differs from ANSI exit() in +The NuttX exit() differs from ANSI exit() in the following ways:
-The Nuttx task_restart() differs from VxWorks' taskRestart() in +The NuttX task_restart() differs from VxWorks' taskRestart() in the following ways:
-Nuttx performs strict priority scheduling: Tasks of higher +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 +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 +than those provided by the NuttX scheduler. As a result, many of these POSIX interfaces are little more than stubs.
-The Nuttx supports POSIX named message queues for intertask communication. +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. @@ -1305,7 +1324,7 @@ interface of the same name.
Semaphores. Semaphores are the basis for -synchronization and mutual exclusion in Nuttx. Nuttx supports +synchronization and mutual exclusion in NuttX. NuttX supports POSIX semaphores.
Semaphores are the preferred mechanism for gaining exclusive access to a @@ -1336,7 +1355,7 @@ 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 +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: @@ -1757,13 +1776,13 @@ interface of the same name.
-The Nuttx provides a general watchdog timer facility. This -facility allows the Nuttx user to specify a watchdog timer function +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 +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. +may use mq_send(), and sigqueue() to communicate with NuttX tasks.
-The Nuttx provides signal interfaces for tasks. Signals are +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 @@ -3913,9 +3932,9 @@ interface of the same name.
-Many of the types used to communicate with Nuttx are simple +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 +of the OS from the application. The scalar types used at the NuttX interface include:
-Several of the types used to interface with Nuttx are +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 @@ -3984,7 +4003,7 @@ in sys/types.h as:
This structure is used to pass scheduling priorities to and from -Nuttx; +NuttX;
struct sched_param
{
@@ -3996,7 +4015,7 @@ Nuttx;
This structure is used to pass timing information between the
-Nuttx and a user application:
+NuttX and a user application:
struct timespec
{
@@ -4009,7 +4028,7 @@ Nuttx and a user application:
This structure is used to communicate message queue attributes
-between Nuttx and a MoBY application:
+between NuttX and a MoBY application:
struct mq_attr {
size_t mq_maxmsg; /* Max number of messages in queue */