From: lottaviano <lottaviano@38d2e660-2303-0410-9eaa-f027e97ec537>
Date: Tue, 17 May 2011 14:08:05 +0000 (+0000)
Subject: Add high level documentation to priority inheritance algorithms.
X-Git-Tag: 2.7.0~57
X-Git-Url: https://codewiz.org/gitweb?a=commitdiff_plain;h=c0bf24abc6e74b7de8237af5fe843d19d31b3b87;p=bertos.git

Add high level documentation to priority inheritance algorithms.

git-svn-id: https://src.develer.com/svnoss/bertos/trunk@4909 38d2e660-2303-0410-9eaa-f027e97ec537
---

diff --git a/bertos/kern/sem.c b/bertos/kern/sem.c
index 6f460746..dc19f4ab 100644
--- a/bertos/kern/sem.c
+++ b/bertos/kern/sem.c
@@ -58,6 +58,19 @@ INLINE void sem_verify(struct Semaphore *s)
 #define proc_updatePri(proc) (proc_setPri(proc, (proc)->orig_pri))
 
 
+/**
+ * Priority inheritance update algorithm.
+ *
+ * The algorithm checks and boosts the priority of the semaphore's
+ * current owner and also processes in that block the owner, which
+ * form a chain of blocking processes.
+ *
+ * Note that the priority of a process in the chain of blocked
+ * processes is always greater or equal than the priority of a process
+ * before in the chain. See the diagram below:
+ * P1  --. S1 ---> P2 --. S2 ---> P3
+ * prio_proc(P2) >= prio_proc(P1) always.
+ */
 INLINE void pri_inheritBlock(Semaphore *s)
 {
 	Process *owner = s->owner;
@@ -99,6 +112,15 @@ INLINE void pri_inheritBlock(Semaphore *s)
 }
 
 
+/**
+ * Priority inheritance unblock algorithm.
+ *
+ * Pass the priority inheritance list from the current owner to the
+ * process that will take ownership of the semaphore next, potentially
+ * boosting its priority.
+ *
+ * \param proc The process that will take ownership of the semaphore.
+ */
 INLINE void pri_inheritUnblock(Semaphore *s, Process *proc)
 {
 	Process *owner = s->owner;