sambuc/codezero
1
0
Fork 0
mirror of https://github.com/drasko/codezero.git synced 2026-01-12 02:43:15 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

Updates to l4_map and l4_mutex_control man pages.

Browse Source
This commit is contained in:
Bahadir Balban
2009-12-03 16:27:47 +02:00
parent 72be4e9fae
commit 72b5f1d1b1
2 changed files with 49 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/man/man7/l4_map.7
View File

@@ -16,7 +16,7 @@
A thread who calls this function must possess capabilities associated with the physical and virtual memory ranges to be mapped. In particular, the range and access permissions for one or more physical and one or more virtual memory capabilities must match the request.
Due to the hierarchical nature of page table organization on some cpu architectures, an
.BR "l4_map() " "request may result in a middle-level page-table expenditure. The caller is also expected to have enough capability resources, namely " "mappool " "capabilities, to cover these cases. All formerly mentioned capability parameters may be adjusted at kernel configuration time. For more information see
.BR "l4_map() " "request may result in a middle-level page-table expenditure. The caller is also expected to have enough capability resources, namely " "mappool " "capabilities, to cover these cases. All formerly mentioned capability parameters may be configured at kernel configuration time. For more information see
.BR "capability" "(7)."
.IR "flags " " field determines different mapping permissions and caching behaviour as defined below:"
@@ -38,20 +38,21 @@ Map with read/write permissions for userspace as non-cacheable/non-bufferable.
.TP
.B MAP_USR_DEFAULT_FLAGS
An alias for MAP_USR_RW_FLAGS. This is the default for userspace
An alias for MAP_USR_RW_FLAGS (See above). This is the default for userspace
.TP
.B MAP_IO_DEFAULT_FLAGS
An alias for MAP_USR_IO_FLAGS (See above) This is the default for userspace device mappings
An alias for MAP_USR_IO_FLAGS (See above). This is the default for userspace device mappings
.SH L4 Userspace Library Functions
.nf
/*
* Map given physical address to a virtual address
* in the current task spanning npages in size.
*/
/*
* Helper that maps given physical address to a virtual address
* in the current task spanning npages in size.
* Returns mapped virtual address on success, negative value on error.
*/
.BI "static inline void *l4_map_helper(void " "*phys" ", int " "npages" ");"
.SH RETURN VALUE

62
docs/man/man7/l4_mutex_control.7
View File

@@ -10,39 +10,43 @@
.BI "int l4_mutex_control(void " "*mutex_word" ", int " "op" ");"
.SH DESCRIPTION
.BR l4_mutex_control() " - Userspace locking and synchronization for shared memory."
.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.
.B op
argument defines whether the operation is a
.B lock
or
.B unlock
operation.
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.
.B mutex_word
argument specifies the userspace virtual address for 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."
.ti 16
Typically the lock is placed on a shared memory segment.
.ti 16
The virtual address can be different on different address spaces referring to the same lock.
.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.
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
"binary semaphore" implementation.
.in 7
.I mutex_word
argument specifies the userspace virtual address for the lock. See below for a userspace representation of the mutex structure:
.nf
#define L4_MUTEX_LOCK 0
.br
#define L4_MUTEX_UNLOCK 1
.br
.in 7
.B struct l4_mutex {
.in 12
.in 15
.BI "unsigned int " "lock" ";"
.in 7
.B } __attribute__((aligned(sizeof(int))));
.SH L4 Userspace Library Functions
.SH L4 USERSPACE LIBRARY
.nf
@@ -52,3 +56,19 @@ Mutexes are locked and unlocked with no system call assistance if there is no lo
.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)"