From c0bf24abc6e74b7de8237af5fe843d19d31b3b87 Mon Sep 17 00:00:00 2001
From: lottaviano <lottaviano@38d2e660-2303-0410-9eaa-f027e97ec537>
Date: Tue, 17 May 2011 14:08:05 +0000
Subject: [PATCH] Add high level documentation to priority inheritance
 algorithms.

git-svn-id: https://src.develer.com/svnoss/bertos/trunk@4909 38d2e660-2303-0410-9eaa-f027e97ec537
---
 bertos/kern/sem.c | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

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;
-- 
2.25.1