Comment updates

git-svn-id: https://nuttx.svn.sourceforge.net/svnroot/nuttx/trunk@754 7fd9a85b-ad96-42d3-883c-3090e2eb8679

5 files changed, 142 insertions, 40 deletions

diff --git a/nuttx/Documentation/NuttxUserGuide.html b/nuttx/Documentation/NuttxUserGuide.html
index 554915b772..c424662d0d 100644
--- a/nuttx/Documentation/NuttxUserGuide.html
+++ b/nuttx/Documentation/NuttxUserGuide.html
@@ -4697,7 +4697,10 @@ returned to indicate the error:
       A thread attempting to unlock an unlocked mutex will return with an error.</li>
     <li><code>PTHREAD_MUTEX_DEFAULT</code>.  The default mutex type (PTHREAD_MUTEX_NORMAL).</li>
   </ul>
-  In NuttX, PTHREAD_MUTEX_NORMAL is not implemented.  PTHREAD_MUTEX_ERRORCHECK is the <i>normal</i> behavior.</li>
+  <p>
+    In NuttX, <code>PTHREAD_MUTEX_NORMAL</code> is not implemented.  Rather, the behavior described
+    for <code>PTHREAD_MUTEX_ERRORCHECK</code> is the <i>normal</i> behavior.
+  </p>
 </ul>
 <p>
 <b>Returned Values:</b>
@@ -4786,22 +4789,57 @@ interface of the same name.
 </pre>
 <p>
 <b>Description:</b>
+   The mutex object referenced by mutex is locked by calling <code>pthread_mutex_lock()</code>.
+   If the mutex is already locked, the calling thread blocks until the mutex
+   becomes available. This operation returns with the mutex object referenced
+   by mutex in the locked state with the calling thread as its owner.
+</p>
+<p>
+   If the mutex type is <code>PTHREAD_MUTEX_NORMAL</code>, deadlock detection is not provided.
+   Attempting to relock the mutex causes deadlock. If a thread attempts to unlock
+   a mutex that it has not locked or a mutex which is unlocked, undefined behavior
+   results.
+</p>
+<p>
+   In NuttX, <code>PTHREAD_MUTEX_NORMAL</code> is not implemented.  Rather, the behavior described
+   for <code>PTHREAD_MUTEX_ERRORCHECK</code> is the <i>normal</i> behavior.
+</p>
+<p>
+   If the mutex type is <code>PTHREAD_MUTEX_ERRORCHECK</code>, then error checking is provided.
+   If a thread attempts to relock a mutex that it has already locked, an error
+   will be returned. If a thread attempts to unlock a mutex that it has not
+   locked or a mutex which is unlocked, an error will be returned.
+</p>
+<p>
+   If the mutex type is <code>PTHREAD_MUTEX_RECURSIVE</code>, then the mutex maintains the concept
+   of a lock count. When a thread successfully acquires a mutex for the first time,
+   the lock count is set to one. Every time a thread relocks this mutex, the lock count
+   is incremented by one. Each time the thread unlocks the mutex, the lock count is
+   decremented by one. When the lock count reaches zero, the mutex becomes available
+   for other threads to acquire. If a thread attempts to unlock a mutex that it has
+   not locked or a mutex which is unlocked, an error will be returned.
+</p>
+<p>
+   If a signal is delivered to a thread waiting for a mutex, upon return from
+   the signal handler the thread resumes waiting for the mutex as if it was
+   not interrupted.
+</p>
 <p>
 <b>Input Parameters:</b>
 <p>
 <ul>
-  <li><code>To be provided</code>.</li>
+  <li><code>mutex</code>.  A reference to the mutex to be locked.</li>
 </ul>
 <p>
 <b>Returned Values:</b>
 <p>
-If successful, the <I>pthread_mutex_lock()</I> function will return
-zero (<I>OK</I>).  Otherwise, an error number will be
-returned to indicate the error:
+If successful, the <I>pthread_mutex_lock()</I> function will return zero (<I>OK</I>).
+Otherwise, an error number will be returned to indicate the error:
 <p>
 <ul>
   <li><code>To be provided</code>. </li>
 </ul>
+<p>Note that this function will never return the error EINTR.</p>
 <b>Assumptions/Limitations:</b>
 <p>
 <b>POSIX Compatibility:</b> Comparable to the POSIX
@@ -4817,22 +4855,31 @@ interface of the same name.
 </pre>
 <p>
 <b>Description:</b>
+   The function pthread_mutex_trylock() is identical to <a href="#pthreadmutexlock"><code>pthread_mutex_lock()</code></a>
+   except that if the mutex object referenced by mutex is currently locked
+   (by any thread, including the current thread), the call returns immediately
+   with the errno <code>EBUSY</code>.
+<p>
+   If a signal is delivered to a thread waiting for a mutex, upon return from
+   the signal handler the thread resumes waiting for the mutex as if it was
+   not interrupted.
+</p>
 <p>
 <b>Input Parameters:</b>
 <p>
 <ul>
-  <li><code>To be provided</code>.</li>
+  <li><code>mutex</code>.  A reference to the mutex to be locked.</li>
 </ul>
 <p>
 <b>Returned Values:</b>
 <p>
-If successful, the <I>pthread_mutex_trylock()</I> function will return
-zero (<I>OK</I>).  Otherwise, an error number will be
-returned to indicate the error:
+If successful, the <I>pthread_mutex_trylock()</I> function will return zero (<I>OK</I>).
+Otherwise, an error number will be returned to indicate the error:
 <p>
 <ul>
   <li><code>To be provided</code>. </li>
 </ul>
+<p>Note that this function will never return the error EINTR.</p>
 <b>Assumptions/Limitations:</b>
 <p>
 <b>POSIX Compatibility:</b> Comparable to the POSIX
@@ -4849,6 +4896,20 @@ interface of the same name.
 <p>
 <b>Description:</b>
 <p>
+   The <code>pthread_mutex_unlock()</code> function releases the mutex object referenced
+   by mutex. The manner in which a mutex is released is dependent upon the
+   mutex's type attribute. If there are threads blocked on the mutex object
+   referenced by mutex when <code>pthread_mutex_unlock()</code> is called, resulting in
+   the mutex becoming available, the scheduling policy is used to determine
+   which thread shall acquire the mutex. (In the case of <code>PTHREAD_MUTEX_RECURSIVE</code>
+   mutexes, the mutex becomes available when the count reaches zero and the
+   calling thread no longer has any locks on this mutex).
+</p>
+<p>
+   If a signal is delivered to a thread waiting for a mutex, upon return from
+   the signal handler the thread resumes waiting for the mutex as if it was
+   not interrupted.
+</p>
 <b>Input Parameters:</b>
 <p>
 <ul>
@@ -4864,6 +4925,7 @@ returned to indicate the error:
 <ul>
   <li><code>To be provided</code>. </li>
 </ul>
+<p>Note that this function will never return the error EINTR.</p>
 <b>Assumptions/Limitations:</b>
 <p>
 <b>POSIX Compatibility:</b> Comparable to the POSIX
diff --git a/nuttx/sched/pthread_initialize.c b/nuttx/sched/pthread_initialize.c
index 599d63ebff..3cd715d8fa 100644
--- a/nuttx/sched/pthread_initialize.c
+++ b/nuttx/sched/pthread_initialize.c
@@ -1,7 +1,7 @@
-/************************************************************
+/****************************************************************************
  * pthread_initialize.c
  *
- *   Copyright (C) 2007 Gregory Nutt. All rights reserved.
+ *   Copyright (C) 2007, 2008 Gregory Nutt. All rights reserved.
  *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
  *
  * Redistribution and use in source and binary forms, with or without
@@ -14,7 +14,7 @@
  *    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
+ * 3. Neither the name NuttX nor the names of its contributors may be
  *    used to endorse or promote products derived from this software
  *    without specific prior written permission.
  *
@@ -31,28 +31,28 @@
  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  *
- ************************************************************/
+ ****************************************************************************/
 
-/************************************************************
+/****************************************************************************
  * Included Files
- ************************************************************/
+ ****************************************************************************/
 
 #include <sys/types.h>
 #include <semaphore.h>
 #include <errno.h>
 #include "pthread_internal.h"
 
-/************************************************************
+/****************************************************************************
  * Definitions
- ************************************************************/
+ ****************************************************************************/
 
-/************************************************************
+/****************************************************************************
  * Private Type Declarations
- ************************************************************/
+ ****************************************************************************/
 
-/************************************************************
+/****************************************************************************
  * Global Variables
- ************************************************************/
+ ****************************************************************************/
 
 /* This is the head of a private singly linked list.  It
  * is used to retain information about the spawned threads.
@@ -73,19 +73,19 @@ sem_t g_join_semaphore;
 
 ubyte g_pthread_num_keys;
 
-/************************************************************
+/****************************************************************************
  * Private Variables
- ************************************************************/
+ ****************************************************************************/
 
-/************************************************************
+/****************************************************************************
  * Private Functions
- ************************************************************/
+ ****************************************************************************/
 
-/************************************************************
+/****************************************************************************
  * Public Functions
- ************************************************************/
+ ****************************************************************************/
 
-/************************************************************
+/****************************************************************************
  * Function:  pthread_initialize
  *
  * Description:
@@ -100,7 +100,7 @@ ubyte g_pthread_num_keys;
  *
  * Assumptions:
  *
- ************************************************************/
+ ****************************************************************************/
 
 void pthread_initialize(void)
 {
@@ -117,7 +117,7 @@ void pthread_initialize(void)
   (void)sem_init(&g_join_semaphore, 0, 1);
 }
 
-/************************************************************
+/****************************************************************************
  * Function:  pthread_takesemaphore and pthread_givesemaphore
  *
  * Description:
@@ -127,11 +127,12 @@ void pthread_initialize(void)
  *   None
  *
  * Return Value:
- *   None
+ *   0 on success or an ERROR on failure with errno value set to EINVAL.
+ *   Note that the errno EINTR is never returned by this function.
  *
  * Assumptions:
  *
- ************************************************************/
+ ****************************************************************************/
 
 int pthread_takesemaphore(sem_t *sem)
 {
@@ -173,8 +174,9 @@ int pthread_givesemaphore(sem_t *sem)
       /* Give the semaphore */
 
       if (sem_post(sem) == OK)
-        return OK;
-
+        {
+          return OK;
+        }
       else
         {
           /* sem_post() reported an error */
diff --git a/nuttx/sched/pthread_mutexlock.c b/nuttx/sched/pthread_mutexlock.c
index 753aa2c6b1..d5156e4618 100644
--- a/nuttx/sched/pthread_mutexlock.c
+++ b/nuttx/sched/pthread_mutexlock.c
@@ -73,13 +73,39 @@
  * Function:  pthread_mutex_lock
  *
  * Description:
- *   Lock a mutex.
+ *   The mutex object referenced by mutex is locked by calling pthread_mutex_lock().
+ *   If the mutex is already locked, the calling thread blocks until the mutex
+ *   becomes available. This operation returns with the mutex object referenced
+ *   by mutex in the locked state with the calling thread as its owner.
+ *
+ *   If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided.
+ *   Attempting to relock the mutex causes deadlock. If a thread attempts to unlock
+ *   a mutex that it has not locked or a mutex which is unlocked, undefined behavior
+ *   results.
+ *
+ *   If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided.
+ *   If a thread attempts to relock a mutex that it has already locked, an error
+ *   will be returned. If a thread attempts to unlock a mutex that it has not
+ *   locked or a mutex which is unlocked, an error will be returned.
+ *
+ *   If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept
+ *   of a lock count. When a thread successfully acquires a mutex for the first time,
+ *   the lock count is set to one. Every time a thread relocks this mutex, the lock count
+ *   is incremented by one. Each time the thread unlocks the mutex, the lock count is
+ *   decremented by one. When the lock count reaches zero, the mutex becomes available
+ *   for other threads to acquire. If a thread attempts to unlock a mutex that it has
+ *   not locked or a mutex which is unlocked, an error will be returned.
+ *
+ *   If a signal is delivered to a thread waiting for a mutex, upon return from
+ *   the signal handler the thread resumes waiting for the mutex as if it was
+ *   not interrupted.
  *
  * Parameters:
- *   None
+ *   mutex - A reference to the mutex to be locked.
  *
  * Return Value:
- *   None
+ *   0 on success or an errno value on failure.  Note that the errno EINTR
+ *   is never returned by pthread_mutex_lock().
  *
  * Assumptions:
  *
diff --git a/nuttx/sched/pthread_mutextrylock.c b/nuttx/sched/pthread_mutextrylock.c
index 21c76bd65c..b62a524968 100644
--- a/nuttx/sched/pthread_mutextrylock.c
+++ b/nuttx/sched/pthread_mutextrylock.c
@@ -74,13 +74,21 @@
  * Function:  pthread_mutex_trylock
  *
  * Description:
- *   Attempt to lock a mutex
+ *   The function pthread_mutex_trylock() is identical to pthread_mutex_lock()
+ *   except that if the mutex object referenced by mutex is currently locked
+ *   (by any thread, including the current thread), the call returns immediately
+ *   with the errno EBUSY.
+ *
+ *   If a signal is delivered to a thread waiting for a mutex, upon return from
+ *   the signal handler the thread resumes waiting for the mutex as if it was
+ *   not interrupted.
  *
  * Parameters:
- *   None
+ *   mutex - A reference to the mutex to be locked.
  *
  * Return Value:
- *   None
+ *   0 on success or an errno value on failure.  Note that the errno EINTR
+ *   is never returned by pthread_mutex_lock().
  *
  * Assumptions:
  *
diff --git a/nuttx/sched/pthread_mutexunlock.c b/nuttx/sched/pthread_mutexunlock.c
index f01f7761eb..4551c729fc 100644
--- a/nuttx/sched/pthread_mutexunlock.c
+++ b/nuttx/sched/pthread_mutexunlock.c
@@ -75,6 +75,10 @@
  * Description:
  *   Unlock a mutex.
  *
+ *   If a signal is delivered to a thread waiting for a mutex, upon return from
+ *   the signal handler the thread resumes waiting for the mutex as if it was
+ *   not interrupted.
+ *
  * Parameters:
  *   None
  *