Subversion Repositories c0or1k

.TH L4_MAP 7 2009-11-18 "Codezero" "Codezero Programmer's Manual"
.SH NAME
.nf
.BR "l4_map" " - Set up a range of virtual to physical address mappings. "

.SH SYNOPSIS
.nf
.B #include <l4lib/arch/syscalls.h>
.B #include <l4lib/arch/syslib.h>

.BI "int l4_map(void " "*p" ", void " "*v" ", u32 " "npages" ", u32 " "flags" ", l4id_t " "tid" ")"
.SH DESCRIPTION
.BR "l4_map() " " sets up a virtual to physical mapping for the thread identified by "
.IR "tid" ", from virtual address " "v" " to physical address " "p" ", spanning for the number of pages defined in " "npages" ", and using the map flags provided in " "flags" "."

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 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:"
.TP
.B MAP_USR_RW_FLAGS
Map with read/write permissions for userspace as cacheable/bufferable

.TP
.B MAP_USR_RO_FLAGS
Map with read-only permissions for userspace as cacheable/bufferable

.TP
.B MAP_SVC_RW_FLAGS
Map with read/write permissions for supervisor mode-only as cacheable/bufferable.

.TP
.B MAP_USR_IO_FLAGS
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 (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

.SH L4 USERSPACE LIBRARY

.nf

/*
 * 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
.BR "l4_map"()
returns 0 on success, and negative value on failure. See below for error codes.

.SH ERRORS

.B -ESRCH
The thread to make the mapping could not be found on the system.

.B -ENOCAP
Capabilities required don't exist or do not have sufficient privileges.

.SH SEE ALSO
.BR "capability"(7)