mirror of
https://github.com/drasko/codezero.git
synced 2026-01-12 19:03:15 +01:00
71 lines
2.7 KiB
Groff
Executable File
71 lines
2.7 KiB
Groff
Executable File
.TH L4_MUTEX_CONTROL 7 2009-11-07 "Codezero" "Codezero Programmer's Manual"
|
|
.SH NAME
|
|
.nf
|
|
.BR "l4_mutex_control" "- Userspace locking and synchronization for shared memory"
|
|
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <l4lib/arch/syscalls.h>
|
|
.B #include <l4lib/arch/syslib.h>
|
|
|
|
.BI "int l4_mutex_control(void " "*mutex_word" ", int " "op" ");"
|
|
.SH DESCRIPTION
|
|
.BR "l4_mutex_control()" " - provides userspace locking and synchronization for shared memory."
|
|
.RI "The " "mutex_word " "argument contains the virtual address for the lock, and is typically placed on a shared memory segment."
|
|
It would still be valid if the lock virtual address is different on different address spaces, as the kernel uses the actual physical address for uniquely identifying the lock.
|
|
|
|
Any virtual address on an address space may be used as a mutex lock, and mutexes are locked and unlocked with no system call assistance if there is no lock contention. If a lock contention occurs, lock holder and lock contender synchronize by the assistance of this system call. In its current state, this system call represents a
|
|
.B "binary semaphore"
|
|
implementation. Note that the userspace threads involved with locking must cooperate, as a non-cooperative thread may cause one or more of the threads to block indefinitely on the lock.
|
|
|
|
.RB "As with all other system calls, the success of this call is subject to the caller having sufficient capabilities. See " "capability" "(7) for more information."
|
|
.RB "On the matter of capabilities, mutex allocation inside the kernel by this call is subject to the caller having the " "mutexpool " "typed memory pool capability. The individual mutex instances however, are not first class objects as capability tracking of each mutex would put too much memory burden on the system."
|
|
|
|
.I op
|
|
argument defines whether the operation is a
|
|
.BR "lock" ","
|
|
or an
|
|
.B unlock
|
|
operation:
|
|
.TP
|
|
.B L4_MUTEX_LOCK
|
|
Locks a contended mutex.
|
|
.TP
|
|
.B L4_MUTEX_UNLOCK
|
|
Unlocks a contended mutex.
|
|
|
|
.in 7
|
|
.I mutex_word
|
|
argument specifies the userspace virtual address for the lock. See below for a userspace representation of the mutex structure.
|
|
|
|
|
|
.SH L4 USERSPACE LIBRARY
|
|
|
|
.nf
|
|
.B struct l4_mutex {
|
|
.BI " unsigned int " "lock" ";"
|
|
.B } __attribute__((aligned(sizeof(int))));
|
|
|
|
.BI "void l4_mutex_init(struct l4_mutex " "*m" ");"
|
|
.BI "int l4_mutex_lock(struct l4_mutex " "*m" ");"
|
|
.BI "int l4_mutex_unlock(struct l4_mutex " "*m" ");"
|
|
|
|
|
|
|
|
.SH RETURN VALUE
|
|
.BR "l4_mutex_control()" " returns 0 on success, and negative value on failure. See below for error codes."
|
|
|
|
.SH ERRORS
|
|
.TP
|
|
.B -ENOMEM
|
|
The caller has no sufficient capability to allocate a mutex structure in the kernel.
|
|
.TP
|
|
.B -EINVAL
|
|
.RI "Invalid value in the " "op " "field. "
|
|
.TP
|
|
.B -ENOCAP
|
|
Caller has no capability to make this system call.
|
|
|
|
.SH SEE ALSO
|
|
.BR "capability" "(7)"
|