Updated comments; starting to implement priority protection but backed everything out but some changes to comments

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

nuttx/Documentation/NuttxPortingGuide.html

@@ -12,7 +12,7 @@
       <h1><big><font color="#3c34ec">
         <i>NuttX RTOS Porting Guide</i>
       </font></big></h1>
-      <p>Last Updated: March 11, 2011</p>
+      <p>Last Updated: March 23, 2011</p>
     </td>
   </tr>
 </table>

nuttx/Documentation/NuttxUserGuide.html

@@ -13,7 +13,7 @@
       <h1><big><font color="#3c34ec"><i>NuttX Operating System<p>User's Manual</i></font></big></h1>
       <p><small>by</small></p>
       <p>Gregory Nutt<p>
-      <p>Last Updated: February 18, 2011</p>
+      <p>Last Updated: March 23, 2012</p>
     </td>
   </tr>
 </table>
@@ -1838,7 +1838,7 @@ interface of the same name.
   </li>
 </ul>
 <p>
-  POSIX semaphore interfaces:
+  <b>POSIX semaphore interfaces:</b>
 </p>
 <ul>
   <li><a href="#seminit">2.5.1 sem_init</a></li>

nuttx/configs/README.txt

@@ -314,6 +314,8 @@ defconfig -- This is a configuration file similar to the Linux
       errorcheck mutexes.  Enables pthread_mutexattr_settype().
     CONFIG_PRIORITY_INHERITANCE - Set to enable support for
       priority inheritance on mutexes and semaphores.
+      Priority inheritance is a strategy for addressing priority
+      inversion.
     CONFIG_SEM_PREALLOCHOLDERS: This setting is only used if priority
       inheritance is enabled.  It defines the maximum number of
       different threads (minus one) that can take counts on a

nuttx/include/semaphore.h

@@ -1,8 +1,8 @@
 /****************************************************************************
  * include/semaphore.h
  *
- *   Copyright (C) 2007-2009 Gregory Nutt. All rights reserved.
- *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *   Copyright (C) 2007-2009, 2012 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -33,8 +33,8 @@
  *
  ****************************************************************************/
 
-#ifndef __SEMAPHORE_H
-#define __SEMAPHORE_H
+#ifndef __INCLUDE_SEMAPHORE_H
+#define __INCLUDE_SEMAPHORE_H
 
 /****************************************************************************
  * Included Files
@@ -83,7 +83,7 @@ struct semholder_s
 
 struct sem_s
 {
-  int16_t semcount;              /* >0 -> Num counts available */
+  int16_t semcount;             /* >0 -> Num counts available */
                                 /* <0 -> Num tasks waiting for semaphore */
 #ifdef CONFIG_PRIORITY_INHERITANCE
   struct semholder_s hlist;     /* List of holders of semaphore counts */
@@ -91,6 +91,8 @@ struct sem_s
 };
 typedef struct sem_s sem_t;
 
+/* Initializers */
+
 #ifdef CONFIG_PRIORITY_INHERITANCE
 #  define SEM_INITIALIZER(c) {(c), SEMHOLDER_INITIALIZER}
 #else
@@ -127,4 +129,4 @@ EXTERN int        sem_getvalue(FAR sem_t *sem, FAR int *sval);
 }
 #endif
 
-#endif /* __SEMAPHORE_H */
+#endif /* __INCLUDE_SEMAPHORE_H */

nuttx/lib/semaphore/sem_init.c

@@ -1,8 +1,8 @@
 /****************************************************************************
  * lib/sem/sem_init.c
  *
- *   Copyright (C) 2007-2009, 2011 Gregory Nutt. All rights reserved.
- *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *   Copyright (C) 2007-2009, 2011-2012 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -93,15 +93,24 @@
  *
  ****************************************************************************/
 
-int sem_init (FAR sem_t *sem, int pshared, unsigned int value)
+int sem_init(FAR sem_t *sem, int pshared, unsigned int value)
 {
+  /* Verify that a semaphore was provided and the count is within the valid
+   * range.
+   */
+
   if (sem && value <= SEM_VALUE_MAX)
     {
+      /* Initialize the seamphore count */
+
       sem->semcount     = (int16_t)value;
+
+      /* Initialize to support priority inheritance */
+
 #ifdef CONFIG_PRIORITY_INHERITANCE
-#if CONFIG_SEM_PREALLOCHOLDERS > 0
+#  if CONFIG_SEM_PREALLOCHOLDERS > 0
       sem->hlist.flink  = NULL;
-#endif
+#  endif
       sem->hlist.holder = NULL;
       sem->hlist.counts = 0;
 #endif
@@ -110,6 +119,6 @@ int sem_init (FAR sem_t *sem, int pshared, unsigned int value)
   else
     {
       set_errno(EINVAL);
-	  return ERROR;
+      return ERROR;
     }
 }

nuttx/sched/os_internal.h

@@ -1,7 +1,7 @@
 /****************************************************************************
  * sched/os_internal.h
  *
- *   Copyright (C) 2007-2011 Gregory Nutt. All rights reserved.
+ *   Copyright (C) 2007-2012 Gregory Nutt. All rights reserved.
  *   Author: Gregory Nutt <gnutt@nuttx.org>
  *
  * Redistribution and use in source and binary forms, with or without

nuttx/sched/sched_reprioritize.c

@@ -1,8 +1,8 @@
 /****************************************************************************
  * sched/sched_reprioritize.c
  *
- *   Copyright (C) 2009 Gregory Nutt. All rights reserved.
- *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *   Copyright (C) 2009, 2012 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions

nuttx/sched/sem_initialize.c

@@ -1,8 +1,8 @@
 /****************************************************************************
  * schec/sem_initialize.c
  *
- *   Copyright (C) 2007, 2009 Gregory Nutt. All rights reserved.
- *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *   Copyright (C) 2007, 2009, 2012 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions

nuttx/sched/sem_internal.h

@@ -1,8 +1,8 @@
 /****************************************************************************
  * sched/sem_internal.h
  *
- *   Copyright (C) 2007, 2009-2011 Gregory Nutt. All rights reserved.
- *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *   Copyright (C) 2007, 2009-2012 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -89,10 +89,16 @@ extern "C" {
 #define EXTERN extern
 #endif
 
+/* Common semaphore logic */
+
 EXTERN void weak_function sem_initialize(void);
 EXTERN void               sem_waitirq(FAR _TCB *wtcb, int errcode);
 EXTERN FAR nsem_t        *sem_findnamed(const char *name);
 
+/* Special logic needed only by priority inheritance to manage collections of
+ * holders of semaphores.
+ */
+
 #ifdef CONFIG_PRIORITY_INHERITANCE
 EXTERN void sem_initholders(void);
 EXTERN void sem_destroyholder(FAR sem_t *sem);

nuttx/sched/sem_post.c

@@ -1,8 +1,8 @@
 /****************************************************************************
  * sched/sem_post.c
  *
- *   Copyright (C) 2007-2009 Gregory Nutt. All rights reserved.
- *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *   Copyright (C) 2007-2009, 2012 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions

nuttx/sched/sem_wait.c

@@ -1,8 +1,8 @@
 /****************************************************************************
  * sched/sem_wait.c
  *
- *   Copyright (C) 2007-2011 Gregory Nutt. All rights reserved.
- *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *   Copyright (C) 2007-2012 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions

nuttx/sched/task_restart.c

@@ -1,8 +1,8 @@
 /****************************************************************************
  * sched/task_restart.c
  *
- *   Copyright (C) 2007, 2009 Gregory Nutt. All rights reserved.
- *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *   Copyright (C) 2007, 2009, 2012 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -146,9 +146,12 @@ int task_restart(pid_t pid)
 
        sig_cleanup(tcb); /* Deallocate Signal lists */
 
-       /* Reset the task priority  */
+       /* Reset the current task priority  */
 
        tcb->sched_priority = tcb->init_priority;
+
+       /* Reset the base task priority and the number of pending reprioritizations */
+
 #ifdef CONFIG_PRIORITY_INHERITANCE
        tcb->base_priority  = tcb->init_priority;
 #  if CONFIG_SEM_NNESTPRIO > 0

nuttx/sched/task_setup.c

@@ -1,8 +1,8 @@
 /****************************************************************************
  * sched/task_setup.c
  *
- *   Copyright (C) 2007-2011 Gregory Nutt. All rights reserved.
- *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *   Copyright (C) 2007-2012 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions