Kernel mutex
EVL kernel mutexes are useful for serializing EVL threads from kernel space, typically some EVL driver code would use them. User and kernel EVL threads can be serialized by EVL kernel mutexes indifferently. An EVL kernel mutex applies a priority inheritance protocol upon contention.
Kernel mutex services
This call initializes a kernel mutex which can be used to serialize EVL threads running on the out-of-band context.
A mutex descriptor is constructed by evl_init_kmutex(), which contains ancillary information other
calls will need. mutex is a pointer to such descriptor of type
struct evl_kmutex.
This call destroys an existing EVL kernel mutex. Any thread which might blocked waiting on the mutex is woken up by this call, receiving a ‘resource removed’ status (-EIDRM).
The descriptor of the kernel mutex to be destroyed.
evl_trylock_kmutex() attempts to lock a kernel mutex, returning immediately on success or failure without blocking the caller.
The descriptor of the kernel mutex to lock.
This call returns zero if the kernel mutex was acquired and locked successfully by the caller. Otherwise, a negated error code is returned:
-
-EBUSY is returned if the mutex is currently locked by another thread.
-
-EDEADLOCK is returned if a deadlock condition was detected while attempting to lock the mutex.
evl_lock_kmutex() locks a kernel mutex. If the lock is owned by another thread on entry, the caller is blocked until the access is granted. If multiple threads wait for acquiring the lock, the one with the highest scheduling priority which has been waiting for the longest time is served first.
The descriptor of the kernel mutex to lock.
This call returns zero if the kernel mutex was acquired and locked successfully by the caller. Otherwise, a negated error code is returned:
-
-EIDRM indicates that the mutex was deleted while the caller was sleeping on it. When this status is returned, the mutex must be considered stale and should not be accessed anymore.
-
-EDEADLOCK is returned if a deadlock condition was detected while attempting to lock the mutex.
-
-EOWNERDEAD is returned if the mutex was locked on entry, but the current owner disappeared from the system, leading to an inconsistent state. This error cannot be fixed, the resource protected by this mutex may be in some undefined state. In other words, such error is definitely bad news.
Acquiring an EVL kernel mutex must be done from the out-of-band context exclusively. In addition, as long as the caller holds an EVL mutex, switching to in-band mode is wrong since this would introduce a priority inversion. Unlike from the user-space context, there is no guard preventing from doing so in kernel space though.
evl_unlock_kmutex() unlocks a kernel mutex previously acquired by a call to evl_lock_kmutex(). The thread leading the wait queue for the mutex is transferred ownership of the released mutex atomically if any.
The descriptor of the kernel mutex to unlock.
Only the thread which acquired an EVL kernel mutex may release it.
A macro which expands as a static initializer you can use in a C statement creating an EVL kernel mutex.
The C variable name to which the initializer should be assigned.
struct evl_kmutex foo = EVL_KMUTEX_INITIALIZER(foo);
A macro which expands as a C statement defining an initialized EVL kernel mutex.
The C variable name of the kernel mutex to define.
/*
* The following expands as:
* static struct evl_kmutex bar = EVL_KMUTEX_INITIALIZER(bar);
*/
static DEFINE_EVL_KMUTEX(bar);
