From 98f603444440748b051d821e0a461ab9b5613010 Mon Sep 17 00:00:00 2001
From: patacongo <patacongo@42af7a65-404d-4744-a932-0658087f49c3>
Date: Fri, 23 Mar 2012 20:14:21 +0000
Subject: [PATCH] Updated comments; starting to implement priority protection
 but backed everything out but some changes to comments

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@4510 42af7a65-404d-4744-a932-0658087f49c3
---
 Documentation/NuttxPortingGuide.html |  2 +-
 Documentation/NuttxUserGuide.html    |  4 ++--
 configs/README.txt                   |  2 ++
 include/semaphore.h                  | 14 ++++++++------
 lib/semaphore/sem_init.c             | 21 +++++++++++++++------
 sched/os_internal.h                  |  2 +-
 sched/sched_reprioritize.c           |  4 ++--
 sched/sem_initialize.c               |  4 ++--
 sched/sem_internal.h                 | 10 ++++++++--
 sched/sem_post.c                     |  4 ++--
 sched/sem_wait.c                     |  4 ++--
 sched/task_restart.c                 |  9 ++++++---
 sched/task_setup.c                   |  4 ++--
 13 files changed, 53 insertions(+), 31 deletions(-)

diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html
index 8b44766143..64bf3568a2 100644
--- a/Documentation/NuttxPortingGuide.html
+++ b/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>
diff --git a/Documentation/NuttxUserGuide.html b/Documentation/NuttxUserGuide.html
index 262f237a95..dec4fca028 100644
--- a/Documentation/NuttxUserGuide.html
+++ b/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>
diff --git a/configs/README.txt b/configs/README.txt
index 955b35d732..78f6a97335 100644
--- a/configs/README.txt
+++ b/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
diff --git a/include/semaphore.h b/include/semaphore.h
index dd1754d694..85214b9c20 100644
--- a/include/semaphore.h
+++ b/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 */
diff --git a/lib/semaphore/sem_init.c b/lib/semaphore/sem_init.c
index f90cc54700..ea1c6e84ea 100644
--- a/lib/semaphore/sem_init.c
+++ b/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;
     }
 }
diff --git a/sched/os_internal.h b/sched/os_internal.h
index 16eb176e19..b7376eb1ec 100644
--- a/sched/os_internal.h
+++ b/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
diff --git a/sched/sched_reprioritize.c b/sched/sched_reprioritize.c
index 9c40e5e3d4..3fa1c4da0d 100644
--- a/sched/sched_reprioritize.c
+++ b/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
diff --git a/sched/sem_initialize.c b/sched/sem_initialize.c
index a355571fde..e9ebfb737f 100644
--- a/sched/sem_initialize.c
+++ b/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
diff --git a/sched/sem_internal.h b/sched/sem_internal.h
index b67e506bfb..4688e0cae2 100644
--- a/sched/sem_internal.h
+++ b/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);
diff --git a/sched/sem_post.c b/sched/sem_post.c
index b29cdfb157..183ca362a0 100644
--- a/sched/sem_post.c
+++ b/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
diff --git a/sched/sem_wait.c b/sched/sem_wait.c
index e36de438d5..98097c991e 100644
--- a/sched/sem_wait.c
+++ b/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
diff --git a/sched/task_restart.c b/sched/task_restart.c
index 1cd575a4e1..c70a2e9451 100644
--- a/sched/task_restart.c
+++ b/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
diff --git a/sched/task_setup.c b/sched/task_setup.c
index 9fdbf3d253..2cbd6daba7 100644
--- a/sched/task_setup.c
+++ b/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