C interface for controlling priority inheritance mutexes. More...

Collaboration diagram for Priority Inheritance Mutex C API:

Functions
l4_msgtag_t	l4_pi_mutex_lock (l4_cap_idx_t mutex, l4_timeout_t timeout) L4_NOTHROW
	Lock contended priority inheritance mutex on slow path.
l4_msgtag_t	l4_pi_mutex_unlock (l4_cap_idx_t mutex) L4_NOTHROW
	Unlock contended priority inheritance mutex from fast path or slow path.

Detailed Description

C interface for controlling priority inheritance mutexes.

A priority inheritance mutex (PI mutex) object provides the slow path for a priority-inheritance-aware mutex.

User-space implements the fast-path using a compare-and-swap atomic operation, with acquire/release semantics, on a status machine-word in kernel-user memory.

[63/31 .. L4_CAP_SHIFT]	...	0
thread cap slot		waiter flag

When a thread wants to acquire a PI mutex, it first tries to do so via the fast path: cas(&status, 0, self_thread_cap()) If the mutex is uncontended the cas succeeds and the thread becomes the owner of mutex. Otherwise, the thread needs to enter the slow path via l4_pi_mutex_lock() and the kernel takes over.

When a thread wants to release a PI mutex, it first tries to do so via the fast path: cas(&status, self_thread_cap(), 0) If the mutex is uncontended, i.e. the waiter flag is not set, the cas succeeds. Otherwise, the thread needs to enter the slow path via l4_pi_mutex_unlock() and the kernel takes over.

Include File: #include <l4/sys/pi_mutex.h>

pi_mutex.h
Priority Inheritance Mutex object.

Function Documentation

◆ l4_pi_mutex_lock()

l4_msgtag_t l4_pi_mutex_lock	(	l4_cap_idx_t	mutex,
		l4_timeout_t	timeout )

inline

Lock contended priority inheritance mutex on slow path.

Parameters

mutex	Priority inheritance mutex object.
timeout	Timeout for blocking the mutex lock operation. Note: The receive timeout of this timeout-pair is significant for blocking, the send part is usually non-blocking.

Returns: Syscall return tag. Use l4_error() to check for errors.

Return values

0	Success.
-L4_EAGAIN	Lock operation in kernel failed, can happen under certain circumstances, try again.
-L4_EDEADLK	Deadlock condition was detected or the calling thread already owns the mutex.
-L4_EINVAL	Invalid parameter or ku_status in invalid state.
L4_IPC_RETIMEOUT	Timeout expired before mutex could be locked.
L4_IPC_RECANCELED	Thread was cancelled while waiting on the mutex.

Definition at line 145 of file pi_mutex.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

◆ l4_pi_mutex_unlock()

l4_msgtag_t l4_pi_mutex_unlock ( l4_cap_idx_t mutex )

inline

Unlock contended priority inheritance mutex from fast path or slow path.