From 72be4e9faea6e7f1845f8ddb8333cc278909aadc Mon Sep 17 00:00:00 2001
From: Bahadir Balban <bbalban@b-labs.co.uk>
Date: Thu, 3 Dec 2009 14:44:50 +0200
Subject: [PATCH] Updated l4_map man page.

---
 docs/man/man7/l4_map.7 | 55 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 50 insertions(+), 5 deletions(-)

diff --git a/docs/man/man7/l4_map.7 b/docs/man/man7/l4_map.7
index 5a834fe..6a775f3 100644
--- a/docs/man/man7/l4_map.7
+++ b/docs/man/man7/l4_map.7
@@ -1,7 +1,7 @@
-.TH L4_MAP 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
+.TH L4_MAP 7 2009-11-18 "Codezero" "Codezero Programmer's Manual"
 .SH NAME
 .nf
-.BR "l4_map" "- Sets up virtual to physical address mappings."
+.BR "l4_map" " - Set up a range of virtual to physical address mappings. "
 
 .SH SYNOPSIS
 .nf
@@ -10,17 +10,62 @@
 
 .BI "int l4_map(void " "*p" ", void " "*v" ", u32 " "npages" ", u32 " "flags" ", l4id_t " "tid" ")"
 .SH DESCRIPTION
-.BR l4_map()  " Sets up virtual to physical address mappings."
+.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" "."
 
-.RB "Sets up a virtual to physical mapping for the thread identified by " "tid" ", from virtual address " "v" " to physical address " "p" ", spanning " "npages" " number of pages, using the given " "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 adjusted 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. 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 Functions
 
 .nf
 /*
- * Map given physical address to a virtual address 
+ * Map given physical address to a virtual address
  * in the current task spanning npages in size.
  */
 
 .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)
+