diff --git a/ChangeLog b/ChangeLog index f98e28187a8..cbaa96917be 100644 --- a/ChangeLog +++ b/ChangeLog @@ -64,6 +64,7 @@ POSIX compliance. * Eliminate compilation warnings that that crept into recent check-ins + * Add kill() * Some Documentation updates * Added support for the Neuros OSD / DM320 diff --git a/Documentation/NuttxUserGuide.html b/Documentation/NuttxUserGuide.html index 4efacd9fd76..d20f05c179b 100644 --- a/Documentation/NuttxUserGuide.html +++ b/Documentation/NuttxUserGuide.html @@ -27,7 +27,7 @@ Gregory Nutt

1.0 Introduction

-This user's manual is divided into three sections: +This user's manual is divided into three sections plus a index:

2.0 OS Interfaces

@@ -89,47 +90,58 @@ paragraphs.

2.1 Task Control Interfaces

-Tasks. -NuttX is a flat address OS. As such it does not support "processes" -in the way that, say, Linux does. -NuttX only supports simple threads running within the same address space. -However, the programming model makes a distinction between "tasks" -and pthreads: + Tasks. + 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. + 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. + 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. +

+

+ The following task control interfaces are provided by Nuttx: +

+ -

2.1.1 task_create

+

2.1.1 task_create

Function Prototype: 

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

@@ -196,19 +208,15 @@ were started from the same parent thread. 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);
+   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: + The NuttX task_create() differs from VxWorks' taskSpawn() in the + following ways: +

-

2.1.2 task_init

+

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,
-          const char *argv[]);
+   STATUS task_init(_TCB *tcb, char *name, int priority, uint32 *stack, uint32 stack_size,
+                    maint_t entry, const char *argv[]);

@@ -278,21 +280,15 @@ mechanism to initialize and start a new task. POSIX Compatibility: This is a NON-POSIX interface. VxWorks provides the following similar interface: 

-   STATUS taskInit(
-      WIND_TCB *pTcb,
-      char *name,
-      int priority,
-      int options,
-      uint32 *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);
+   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: + The NuttX task_init() differs from VxWorks' taskInit() in the + following ways: +

-

2.1.3 task_activate

+

2.1.3 task_activate

Function Prototype: @@ -341,15 +337,16 @@ VxWorks provides the following similar interface:

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

-

2.1.4 task_delete

+

2.1.4 task_delete

Function Prototype: @@ -390,15 +387,16 @@ VxWorks provides the following similar interface:

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

-

2.1.5 exit

+

2.1.5 exit

Function Prototype: @@ -438,13 +436,13 @@ And the unix interface:

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

-

2.1.6 task_restart

+

2.1.6 task_restart

Function Prototype: @@ -487,15 +485,15 @@ VxWorks provides the following similar interface:

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

-

2.1.7 getpid

+

2.1.7 getpid

Function Prototype: @@ -524,19 +522,35 @@ 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. +

+ By default, NuttX performs strict priority scheduling: Tasks of higher + priority have exclusive access to the CPU until they become blocked. + At that time, the CPU is available to tasks of lower priority. + Tasks of equal priority are scheduled FIFO. +

+

+ Optionally, a Nuttx task or thread can be configured with round-robin + scheduler. This is similar to priority scheduling except that + tasks with equal priority and share CPU time via time-slicing. + The time-slice interval is a constant determined by the configuration + setting CONFIG_RR_INTERVAL. +

+

+ The OS interfaces described in the following paragraphs provide + a POSIX- compliant interface to the NuttX scheduler: +

+ -

2.2.1 sched_setparam

+

2.2.1 sched_setparam

Function Prototype: @@ -583,7 +597,7 @@ Differences from the full POSIX implementation include:

  • The range of priority values for the POSIX call is 0 to 255 -

    2.2.2 sched_getparam

    +

    2.2.2 sched_getparam

    Function Prototype: @@ -617,7 +631,7 @@ element of this structure. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.2.3 sched_setscheduler

    +

    2.2.3 sched_setscheduler

    Function Prototype: 

    @@ -660,7 +674,7 @@ interface of the same name.
   POSIX  Compatibility: Comparable to the POSIX
 interface of the same name.
 
-
    2.2.4 sched_getscheduler
    
+
    2.2.4 sched_getscheduler
    
 
    
 Function Prototype: 
 
    @@ -670,7 +684,7 @@ interface of the same name.
 
    
   Description:
   sched_getscheduler() returns the scheduling policy
-  currently applied to the process identified by pid. If
+  currently applied to the task identified by pid. If
   pid equals zero, the policy of the calling process will
   be retrieved.
  *
@@ -710,7 +724,7 @@ Differences from the full POSIX implementation include:
 
  • Does not report errors via errno.
 
 
-
    2.2.5 sched_yield
    
+
    2.2.5 sched_yield
    
 
 
    
 Function Prototype: 
@@ -736,7 +750,7 @@ up the CPU (only to other tasks at the same priority).
   POSIX  Compatibility: Comparable to the POSIX
 interface of the same name.
 
-
    2.2.6 sched_get_priority_max
    
+
    2.2.6 sched_get_priority_max
    
 
 
    
 Function Prototype: 
@@ -766,7 +780,7 @@ possible task priority for a specified scheduling policy.
   POSIX  Compatibility: Comparable to the POSIX
 interface of the same name.
 
-
    2.2.7 sched_get_priority_min
    
+
    2.2.7 sched_get_priority_min
    
 
 
    
 Function Prototype: 
@@ -796,7 +810,7 @@ possible task priority for a specified scheduling policy.
   POSIX  Compatibility: Comparable to the POSIX
 interface of the same name.
 
-
    2.2.8 sched_get_rr_interval
    
+
    2.2.8 sched_get_rr_interval
    
 
 
    
 Function Prototype: 
@@ -844,7 +858,13 @@ priority of the calling task is returned.
 
 
    2.3 Task Switching Interfaces
    
 
-
    2.3.1 sched_lock
    
+
+
+
    2.3.1 sched_lock
    
 
 
    
 Function Prototype: 
@@ -876,7 +896,7 @@ VxWorks provides the comparable interface:
     STATUS taskLock( void );
 
    • 
 
-
    2.3.2 sched_unlock
    
+
    2.3.2 sched_unlock
    
 
 
    
 Function Prototype: 
@@ -909,7 +929,7 @@ VxWorks provides the comparable interface:
     STATUS taskUnlock( void );
    -

    2.3.3 sched_lockcount

    +

    2.3.3 sched_lockcount

    Function Prototype: @@ -939,12 +959,23 @@ on this thread of execution.

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

    + 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

    +

    2.4.1 mq_open

    Function Prototype: @@ -1013,7 +1044,7 @@ may be sent or received. In the present implementation, this maximum message size is limited at 22 bytes. -

    2.4.2 mq_close

    +

    2.4.2 mq_close

    Function Prototype: @@ -1058,7 +1089,7 @@ return from mq_close() is undefined. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.4.3 mq_unlink

    +

    2.4.3 mq_unlink

    Function Prototype: @@ -1087,7 +1118,7 @@ closed. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.4.4 mq_send

    +

    2.4.4 mq_send

    Function Prototype: @@ -1136,7 +1167,7 @@ Differences from the full POSIX implementation include:

  • Control is not returned if a signal is received. -

    2.4.5 mq_receive

    +

    2.4.5 mq_receive

    Function Prototype: @@ -1186,7 +1217,7 @@ Differences from the full POSIX implementation include:

  • Control is not returned if a signal is received. -

    2.4.6 mq_notify

    +

    2.4.6 mq_notify

    Function Prototype: @@ -1242,7 +1273,7 @@ appropriate mq_receive() ... The resulting behavior is as if the message queue remains empty, and no notification shall be sent." -

    2.4.7 mq_setattr

    +

    2.4.7 mq_setattr

    Function Prototype: @@ -1281,7 +1312,7 @@ would have been returned by mq_getattr()). POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.4.8 mq_getattr

    +

    2.4.8 mq_getattr

    Function Prototype: @@ -1322,53 +1353,71 @@ 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: +

    + 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. +
    2. Task C is suspended to allow some high-priority task,
      3. + Task A, to execute. +
    3. Task A attempts to acquire the semaphore held by Task C and + gets blocked until Task C relinquishes the semaphore.
      4. +
    4. Task C is allowed to execute again, but gets suspended by some + medium-priority Task B.
      5. +
    +

    + At this point, the high-priority Task A cannot execute until + Task B (and possibly other medium-priority tasks) completes and until + Task C relinquishes the semaphore. In effect, the high-priority task, + Task A behaves as though it were lower in priority than the + low-priority task, Task C! This phenomenon is called priority + inversion. +

    +

    + Some operating systems avoid priority inversion by automatically + increasing the priority of the low-priority Task C (the operable + buzz-word for this behavior is priority inheritance). NuttX 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: +

    -

    +

    + POSIX semaphore interfaces: +

    + -

    2.5.1 sem_init

    +

    2.5.1 sem_init

    Function Prototype: @@ -1411,7 +1460,7 @@ Differences from the full POSIX implementation include:

  • pshared is not used. -

    2.5.2 sem_destroy

    +

    2.5.2 sem_destroy

    Function Prototype: @@ -1448,7 +1497,7 @@ blocked is undefined. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.5.3 sem_open

    +

    2.5.3 sem_open

    Function Prototype: @@ -1514,7 +1563,7 @@ Differences from the full POSIX implementation include: just a counting semaphore. -

    2.5.4 sem_close

    +

    2.5.4 sem_close

    Function Prototype: @@ -1559,7 +1608,7 @@ has already locked. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.5.5 sem_unlink

    +

    2.5.5 sem_unlink

    Function Prototype: @@ -1605,7 +1654,7 @@ refer to the same semaphore; POSIX specifies that a new semaphore with the same name should be created after sem_unlink() is called. -

    2.5.6 sem_wait

    +

    2.5.6 sem_wait

    Function Prototype: @@ -1648,7 +1697,7 @@ received by this task. In this case, the semaphore has not be acquired. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.5.7 sem_trywait

    +

    2.5.7 sem_trywait

    Function Prototype: @@ -1690,7 +1739,7 @@ not valid. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.5.8 sem_post

    +

    2.5.8 sem_post

    Function Prototype: @@ -1733,7 +1782,7 @@ 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

    +

    2.5.9 sem_getvalue

    Function Prototype: @@ -1777,15 +1826,21 @@ 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. + 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. +

    + -

    2.6.1 wd_create

    +

    2.6.1 wd_create

    Function Prototype: @@ -1823,7 +1878,7 @@ Differences from the VxWorks interface include: initialization time). -

    2.6.2 wd_delete

    +

    2.6.2 wd_delete

    Function Prototype: @@ -1867,7 +1922,7 @@ Differences from the VxWorks interface include: before de-allocating it (i.e., never returns ERROR). -

    2.6.3 wd_start

    +

    2.6.3 wd_start

    Function Prototype: @@ -1927,7 +1982,7 @@ to wdentry; VxWorks supports only a single parameter. The maximum number of parameters is determined by -

    2.6.4 wd_cancel

    +

    2.6.4 wd_cancel

    Function Prototype: @@ -1965,27 +2020,46 @@ VxWorks provides the following comparable interface:

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

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

    +

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

    +

    + The following signal handling interfaces are provided by NuttX: +

    + -

    2.7.1 sigemptyset

    +

    2.7.1 sigemptyset

    Function Prototype: @@ -2015,7 +2089,7 @@ by set such that all signals are excluded. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.7.2 sigfillset

    +

    2.7.2 sigfillset

    Function Prototype: @@ -2045,7 +2119,7 @@ by set such that all signals are included. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.7.3 sigaddset

    +

    2.7.3 sigaddset

    Function Prototype: @@ -2076,7 +2150,7 @@ signo to the signal set specified by set. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.7.4 sigdelset

    +

    2.7.4 sigdelset

    Function Prototype: @@ -2107,7 +2181,7 @@ by signo from the signal set specified by set. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.7.5 sigismember

    +

    2.7.5 sigismember

    Function Prototype: @@ -2140,7 +2214,7 @@ by signo is a member of the set specified by set. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.7.6 sigaction

    +

    2.7.6 sigaction

    Function Prototype: @@ -2213,7 +2287,7 @@ not handled (SIG_DFL, SIG_IGN). (all treated like SA_SIGINFO). -

    2.7.7 sigprocmask

    +

    2.7.7 sigprocmask

    Function Prototype: @@ -2263,7 +2337,7 @@ pointed to by the set input parameter. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.7.8 sigpending

    +

    2.7.8 sigpending

    Function Prototype: @@ -2301,7 +2375,7 @@ is delivered more than once." POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.7.9 sigsuspend

    +

    2.7.9 sigsuspend

    Function Prototype: @@ -2349,7 +2423,7 @@ function or to terminate the task." Only delivery of the signal is required in the present implementation (even if the signal is ignored). -

    2.7.10 sigwaitinfo

    +

    2.7.10 sigwaitinfo

    Function Prototype: @@ -2381,7 +2455,7 @@ with a NULL timeout parameter. (see below). POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.7.11 sigtimedwait

    +

    2.7.11 sigtimedwait

    Function Prototype: @@ -2447,7 +2521,7 @@ that the unblocked signal be caught; the task will be resumed even if the unblocked signal is ignored. -

    2.7.12 sigqueue

    +

    2.7.12 sigqueue

    Function Prototype: @@ -2470,7 +2544,7 @@ is delivered more than once."

    Input Parameters:

    @@ -2478,7 +2552,15 @@ is delivered more than once."

    Returned Values:

    @@ -2490,17 +2572,114 @@ Differences from the POSIX interface include:

    -

    2.8 Pthread Interfaces

    +

    2.7.13 kill

    +

    -

    2.8.1 pthread_attr_init

    +Function Prototype: +
    +   #include <sys/types.h>
+   #include <signal.h>
+   int kill(pid_t pid, int sig);
+
    + +

    +Description: + The kill() system call can be used to send any signal to + any task. +

    +

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

    +

    +Input Parameters: +

    + +

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

    @@ -2533,7 +2712,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name.

    -

    2.8.2 pthread_attr_destroy

    +

    2.8.2 pthread_attr_destroy

    Function Prototype:

    @@ -2565,7 +2744,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name.

    -

    2.8.3 pthread_attr_setschedpolicy

    +

    2.8.3 pthread_attr_setschedpolicy

    Function Prototype:

    @@ -2596,7 +2775,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.4 pthread_attr_getschedpolicy

    +

    2.8.4 pthread_attr_getschedpolicy

    Function Prototype:

    @@ -2627,7 +2806,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.5 pthread_attr_setschedparam

    +

    2.8.5 pthread_attr_setschedparam

    Function Prototype:

    @@ -2659,7 +2838,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.6 pthread_attr_getschedparam

    +

    2.8.6 pthread_attr_getschedparam

    Function Prototype:

    @@ -2691,7 +2870,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.7 pthread_attr_setinheritsched

    +

    2.8.7 pthread_attr_setinheritsched

    Function Prototype:

    @@ -2723,7 +2902,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name.

    -

    2.8.8 pthread_attr_getinheritsched

    +

    2.8.8 pthread_attr_getinheritsched

    Function Prototype:

    @@ -2755,7 +2934,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.9 pthread_attr_setstacksize

    +

    2.8.9 pthread_attr_setstacksize

    Function Prototype:

    @@ -2786,7 +2965,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.10 pthread_attr_getstacksize

    +

    2.8.10 pthread_attr_getstacksize

    Function Prototype:

    @@ -2817,7 +2996,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.11 pthread_create

    +

    2.8.11 pthread_create

    Function Prototype:

    @@ -2856,7 +3035,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.12 pthread_detach

    +

    2.8.12 pthread_detach

    Function Prototype:

    @@ -2889,7 +3068,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.13 pthread_exit

    +

    2.8.13 pthread_exit

    Function Prototype:

    @@ -2921,7 +3100,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.14 pthread_cancel

    +

    2.8.14 pthread_cancel

    Function Prototype:

    @@ -2977,7 +3156,7 @@ the time when cancelation is re-enabled.

  • Thread cancellation at cancellation points is not supported.
    • -

    2.8.15 pthread_setcancelstate

    +

    2.8.15 pthread_setcancelstate

    Function Prototype:

    @@ -3019,17 +3198,17 @@ 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. -

    2.8.16 pthread_setcancelstate

    +

    2.8.16 pthread_testcancelstate

    Function Prototype: 

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

    Description: -

    +

    NOT SUPPORTED Input Parameters:

    -

    2.8.23 pthread_setspecific

    +

    2.8.23 pthread_setspecific

    Function Prototype:

    @@ -3317,7 +3496,7 @@ interface of the same name. destructor function. -

    2.8.24 pthread_getspecific

    +

    2.8.24 pthread_getspecific

    Function Prototype:

    @@ -3358,7 +3537,7 @@ interface of the same name. destructor function. -

    2.8.25 pthread_key_delete

    +

    2.8.25 pthread_key_delete

    Function Prototype:

    @@ -3390,7 +3569,7 @@ this function does nothing in the present implementation. POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.26 pthread_mutexattr_init

    +

    2.8.26 pthread_mutexattr_init

    Function Prototype:

    @@ -3421,7 +3600,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.27 pthread_mutexattr_destroy

    +

    2.8.27 pthread_mutexattr_destroy

    Function Protoype:

    @@ -3452,7 +3631,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.28 pthread_mutexattr_getpshared

    +

    2.8.28 pthread_mutexattr_getpshared

    Function Prototype:

    @@ -3484,7 +3663,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.29 pthread_mutexattr_setpshared

    +

    2.8.29 pthread_mutexattr_setpshared

    Function Prototype:

    @@ -3516,7 +3695,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.30 pthread_mutex_init

    +

    2.8.30 pthread_mutex_init

    Function Prototype:

    @@ -3548,7 +3727,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.31 pthread_mutex_destroy

    +

    2.8.31 pthread_mutex_destroy

    Function Prototype:

    @@ -3579,7 +3758,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.32 pthread_mutex_lock

    +

    2.8.32 pthread_mutex_lock

    Function Prototype:

    @@ -3610,7 +3789,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.33 pthread_mutex_trylock

    +

    2.8.33 pthread_mutex_trylock

    Function Prototype:

    @@ -3641,7 +3820,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.34 pthread_mutex_unlock

    +

    2.8.34 pthread_mutex_unlock

    Function Prototype:

    @@ -3672,7 +3851,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.35 pthread_condattr_init

    +

    2.8.35 pthread_condattr_init

    Function Prototype:

    @@ -3703,7 +3882,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.36 pthread_condattr_destroy

    +

    2.8.36 pthread_condattr_destroy

    Function Prototype:

    @@ -3734,7 +3913,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.37 pthread_cond_init

    +

    2.8.37 pthread_cond_init

    Function Prototype:

    @@ -3765,7 +3944,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.38 pthread_cond_destroy

    +

    2.8.38 pthread_cond_destroy

    Function Prototype:

    @@ -3796,7 +3975,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.39 pthread_cond_broadcast

    +

    2.8.39 pthread_cond_broadcast

    Function Prototype:

    @@ -3827,7 +4006,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.40 pthread_cond_signal

    +

    2.8.40 pthread_cond_signal

    Function Prototype:

    @@ -3858,7 +4037,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.41 pthread_cond_wait

    +

    2.8.41 pthread_cond_wait

    Function Prototype:

    @@ -3889,7 +4068,7 @@ returned to indicate the error: POSIX Compatibility: Comparable to the POSIX interface of the same name. -

    2.8.42 pthread_cond_timedwait

    +

    2.8.42 pthread_cond_timedwait

    Function Prototype:

    @@ -4124,5 +4303,115 @@ notify a task when a message is available on a queue. have to do some redesign.

    +

    Index

    + + diff --git a/include/signal.h b/include/signal.h index 8e25f8c0020..72c6e3fa7c5 100644 --- a/include/signal.h +++ b/include/signal.h @@ -83,10 +83,6 @@ * with 3 args instead of 1 * (always assumed) */ -/* Dummy value for the sigev_notify field of struct sigevent */ - -#define SIGEV_SIGNAL 0 - /* These are the possible values of the signfo si_code field */ #define SI_USER 0 /* Signal sent from kill, raise, or abort */ @@ -96,7 +92,7 @@ #define SI_MESGQ 4 /* Signal generated by arrival of a message on an */ /* empty message queue */ -/* sigevent definitions */ +/* Values for the sigev_notify field of struct sigevent */ #define SIGEV_NONE 0 /* No notification desired */ #define SIGEV_SIGNAL 1 /* Notify via signal */ diff --git a/sched/Makefile b/sched/Makefile index 7708f5d4672..de803739018 100644 --- a/sched/Makefile +++ b/sched/Makefile @@ -61,7 +61,7 @@ CLOCK_SRCS = clock_initialize.c mktime.c gmtime_r.c clock_settime.c \ clock_gettime.c clock_getres.c SIGNAL_SRCS = sig_initialize.c \ sig_action.c sig_procmask.c sig_pending.c sig_suspend.c \ - sig_queue.c sig_waitinfo.c sig_timedwait.c \ + sig_kill.c sig_queue.c sig_waitinfo.c sig_timedwait.c \ sig_emptyset.c sig_fillset.c sig_addset.c sig_delset.c \ sig_ismember.c sig_findaction.c \ sig_allocatependingsigaction.c sig_releasependingsigaction.c \ diff --git a/sched/sig_kill.c b/sched/sig_kill.c new file mode 100644 index 00000000000..db9a73ba262 --- /dev/null +++ b/sched/sig_kill.c @@ -0,0 +1,134 @@ +/************************************************************ + * sig_kill.c + * + * Copyright (C) 2007 Gregory Nutt. All rights reserved. + * Author: Gregory Nutt + * + * 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 Gregory Nutt 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 + ************************************************************/ + +#include +#include +#include +#include +#include "os_internal.h" +#include "sig_internal.h" + +/************************************************************ + * Global Functions + ************************************************************/ + +/************************************************************ + * Function: kill + * + * Description: + * The kill() system call can be used to send any signal to + * any task. + * + * Limitation: Sending of signals to 'process groups' is + * not supported in NuttX + * + * 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. + * signo - The signal number to send. + * + * Return Value: + * On success (at least one signal was sent), zero is + * returned. On error, -1 is returned, and errno is set + * appropriately. + * + * EINVAL An invalid signal was specified. + * EPERM The process does not have permission to send the + * signal to any of the target processes. + * ESRCH The pid or process group does not exist. + * ENOSYS Do not support sending signals to process groups. + * + * Assumptions: + * + ************************************************************/ + +int kill(pid_t pid, int signo) +{ + FAR _TCB *stcb; + siginfo_t info; + int ret = ERROR; + + /* We do not support sending signals to process groups */ + + if (pid <= 0) + { + *get_errno_ptr() = ENOSYS; + return ERROR; + } + + /* Make sure that the signal is valid */ + + if (!GOOD_SIGNO(signo)) + { + *get_errno_ptr() = EINVAL; + return ERROR; + } + + /* Keep things stationary through the following */ + + sched_lock(); + + /* Get the TCB of the receiving task */ + + stcb = sched_gettcb(pid); + dbg("TCB=0x%08x signo=%d\n", stcb, signo); + if (!stcb) + { + *get_errno_ptr() = ESRCH; + sched_unlock(); + return ERROR; + } + + /* Create the siginfo structure */ + + info.si_signo = signo; + info.si_code = SI_USER; + info.si_value.sival_ptr = NULL; + + /* Send the signal */ + + ret = sig_received(stcb, &info); + sched_unlock(); + return ret; +} + + diff --git a/sched/sig_queue.c b/sched/sig_queue.c index dcae4e0a5b7..835f2d2ddf4 100644 --- a/sched/sig_queue.c +++ b/sched/sig_queue.c @@ -43,6 +43,7 @@ #include #include #include +#include #include "os_internal.h" #include "sig_internal.h" @@ -92,7 +93,15 @@ * value - Value to pass to task with signal * * Return Value: - * None + * On success (at least one signal was sent), zero is + * returned. On error, -1 is returned, and errno is set + * appropriately. + * + * EGAIN The limit of signals which may be queued has been reached. + * EINVAL sig was invalid. + * EPERM The process does not have permission to send the + * signal to the receiving process. + * ESRCH No process has a PID matching pid. * * Assumptions: * @@ -108,6 +117,14 @@ int sigqueue(int pid, int signo, void *sival_ptr) siginfo_t info; int ret = ERROR; + /* sanity checks */ + + if (!GOOD_SIGNO(signo)) + { + *get_errno_ptr() = EINVAL; + return ERROR; + } + sched_lock(); /* Get the TCB of the receiving task */ @@ -118,6 +135,12 @@ int sigqueue(int pid, int signo, void *sival_ptr) #else dbg("TCB=0x%08x signo=%d value=%p\n", stcb, signo, sival_ptr); #endif + if (pid == 0 || !stcb) + { + *get_errno_ptr() = ESRCH; + sched_unlock(); + return ERROR; + } /* Create the siginfo structure */ @@ -129,15 +152,9 @@ int sigqueue(int pid, int signo, void *sival_ptr) info.si_value.sival_ptr = sival_ptr; #endif - /* Verify that we can perform the signalling operation */ - - if (stcb && GOOD_SIGNO(signo)) - { - /* Process the receipt of the signal */ - - ret = sig_received(stcb, &info); - } + /* Send the signal */ + ret = sig_received(stcb, &info); sched_unlock(); return ret; }