From: Ingo Molnar Add rt-mutex documentation. Signed-off-by: Ingo Molnar Signed-off-by: Thomas Gleixner Signed-off-by: Arjan van de Ven Signed-off-by: Andrew Morton --- Documentation/rtmutex.txt | 60 ++++++++++++++++++++++++++++++++++++ 1 files changed, 60 insertions(+) diff -puN /dev/null Documentation/rtmutex.txt --- /dev/null 2003-09-15 06:40:47.000000000 -0700 +++ devel-akpm/Documentation/rtmutex.txt 2006-03-25 19:05:05.000000000 -0800 @@ -0,0 +1,60 @@ +RT Mutex Subsystem with PI support + +RT Mutexes with priority inheritance are used to support pthread_mutexes +with priority inheritance attributes. + +The basic technology was developed in the preempt-rt tree and +streamlined for the pthread_mutex support. + +RT Mutexes extend the semantics of Mutexes by the priority inheritance +protocol. Sharing code and data structures with the Mutex code is not +feasible due to the extended requirements of RT Mutexes. + +Basic operation principle: + +A low priority owner of a rt_mutex inherits the priority of a higher +priority waiter until the mutex is released. Is the temporary priority +boosted owner blocked on a rt_mutex itself it propagates the priority +boosting to the owner of the rt_mutex it is blocked on. The priority +boosting is immidiately removed once the rt_mutex has been unlocked. +This technology allows to shorten the blocking on mutexes which +protect shared resources. Priority inheritance is not a magic bullet +for poorly designed applications, but allows optimizations in cases +where the protection of shared resources might affect critical parts +of an high priority thread. + +The enqueueing of the waiters into the rtmutex waiter list is done in +priority order. In case of the same priority FIFO order is chosen. Per +rtmutex only the top priority waiter is enqueued into the owners +priority waiters list. Also this list enqueues in priority +order. Whenever the top priority waiter of a task is changed the +priority of the task is readjusted. The priority enqueueing is handled +by plists, see also include/linux/plist.h for further explanation. + +RT Mutexes are optimized for fastpath operations and have no runtime +overhead in case of locking an uncontended mutex or unlocking a mutex +without waiters. The optimized fathpath operations require cmpxchg +support. + +The state of the rtmutex is tracked via the owner field of the +rt_mutex structure: + +rt_mutex->owner holds the task_struct pointer of the owner. Bit 0 and +1 are used to keep track of the "owner is pending" and "rtmutex has +waiters" state. + +owner bit1 bit0 +NULL 0 0 mutex is free (fast acquire possible) +NULL 0 1 invalid state +NULL 1 0 invalid state +NULL 1 1 invalid state +taskpointer 0 0 mutex is held (fast release possible) +taskpointer 0 1 task is pending owner +taskpointer 1 0 mutex is held and has waiters +taskpointer 1 1 task is pending owner and mutex has more waiters + +Pending ownership is assigned to the first (highest priority) waiter +of the mutex, when the mutex is released. The thread is woken up and +can now acquire the mutex. Until the mutex is taken (bit 0 cleared) a +competing higher priority thread can steal the mutex which puts the +woken up thread back on the waiters list. _