Update to manual pages.

Introduced an ENOMAP error code for l4_unmap.

docs/man/man7/l4_getid.7

@@ -1,7 +1,7 @@
 .TH L4_GETID 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
 .SH NAME
 .nf
-.BR "l4_getid" "- Returns thread id, thread group id and space id of a thread."
+.BR "l4_getid" " - returns thread id, thread group id and space id of a thread."
 
 .SH SYNOPSIS
 .nf
@@ -10,35 +10,39 @@
 
 .BI "int l4_getid(struct task_ids " "*ids" ");"
 .SH DESCRIPTION
-.BR l4_getid()  " Returns thread id, thread group id and space id of a thread."
-
-.SH Operational Model
-Thread ID, Thread Group ID, and Space ID are received via the 
-.B ids
-structure.
-.nf
-Every thread in the system has a globally unique Thread ID.
-An address space may have one or more threads. Therefore threads may share their Space IDs.
-A Thread Group Leader has a Thread ID same as its Thread Group ID.
-A newly created thread may join an existing thread group or create a new group. This behaviour is defined by the thread's pager.
+.BR "l4_getid() " "returns thread id, thread group id and space id of a thread in a " "struct task_ids " "structure, as shown below."
 
 .nf
-.in 16
-.B "struct task_ids {"
-.BI "int " "tid" "; /* Thread ID */"
-.BI "int " "spid" "; /* Space ID */"
-.BI "int " "tgid" "; /* Thread Group ID */"
-.B "};"
+.TP
+.BI "struct" " task_ids { "
+.in 15
+.BI "int " "tid" ";   /* Fully qualified thread id */"
+.BI "int " "spid" ";  /* Address space id (local to container) */"
+.BI "int " "tgid" ";  /* Thread group id (local, defined by userspace protocol) */"
+.ti 7
+};
+
+.fi
+
+.in 7
+Every thread in the system has a thread id, space id and a thread group id associated with it. Each thread and space id is globally unique across the system. Thread group ids are available for grouping threads in arbitrary groups, via a user-defined protocol. A newly created thread may join an existing thread group or create a new group. This behaviour is defined by the thread's pager. Such a user-defined thread group allocation protocol may be useful for implementing groups of threads by higher level OS services.
+
+Even though both thread and space ids are globally unique across the system, there is an addressability difference between them. Each thread id is a fully qualified id, carrying its container id information with it. Upon a system call that targets a thread id, the system allows addressing threads in other containers. In contrast, space ids are not fully qualified. They are local to a container, and any system call addressing a space id cannot target a space in another container.
+
+.SH FUTURE
+.BR "l4_getid() " "call is currently not subject to capability checking, as every thread has a natural right to discover their ids. In the future, it is possible that this system call is used for naming discovery for other addressable entities. If such a role is given to this call, it may also become subject to capability checking, as access control would prove beneficial over naming discovery services."
+
 
 .SH L4 USERSPACE LIBRARY
 
 .nf
+.B #include <l4lib/arch/syslib.h>
+
 /*
  * Returns Thread ID of current thread
  */
+.BI "static inline l4id_t self_tid(" "void" ")"
+
+.SH RETURN VALUE
+.BR "l4_getid()" " always succeeds with a return value of 0."
 
-.BI "static inline l4id_t self_tid(" "void" "){"
-.BI "struct task_ids " "ids" ";"
-.BI "l4_getid(" "&ids" ");"
-.BI "return " "ids.tid" ";"
-.B }

docs/man/man7/l4_thread_control.7

@@ -76,10 +76,8 @@ Waits on a thread to exit, with exit status.
 
 On a system setup where a pager is responsible for creating threads in separate address spaces and communicating with them via IPC, the children may send an exit IPC message to their pager. This way, a pager may synchronously receive exit status of a child in the form of IPC, and take action to destroy it as part of handling the IPC. However, on systems where the application is a multi-threaded, single address space application, a thread wait call provides a simple synchronous channel for the parent to wait on its child's exit status, without requiring any extra set up for IPC handling.
 
-.ti 8
-
-.I ids
-field specifies the thread, address space, and thread group ids of the targeted thread. Below is the declaration for this structure:
+.ti 7
+.IR "ids " "field specifies the thread, address space, and thread group ids of the targeted thread. Below is the declaration for this structure:"
 
 .nf
 .TP
@@ -115,6 +113,9 @@ flags
 .I tgid
 field is provided as an extra id slot for the thread. The pager of the thread may designate a group of threads to be in the same thread group, defining the group by a userspace protocol. This field has no meaning from the kernel's perspective, and may be removed in future releases.
 
+.in 7
+.RB "See " "l4_getid" "(7) for more details on resource ids in Codezero."
+
 .SH THREAD RELATIONSHIPS
 Codezero aims to provide fine-grain privilege levels to threads in the system in the form of capabilities. Capabilities enable privileges of threads over each other to become highly configurable, resulting in the hierarchical relationship between them to become blurry. However, even though such a relationship is not enforced by the architecture, often it comes natural that threads are created by other threads. As a result, even though a thread hierarchy is not enforced by the capability design, it is implicitly catered for by a
 .I pagerid
@@ -152,4 +153,4 @@ argument would cause a page fault.
 returned when a given thread id has not been found in the container.
 
 .SH SEE ALSO
-.BR "capability"(7), " l4_exchange_registers"(7)
+.BR "capability"(7), " l4_exchange_registers" "(7), " "l4_getid" "(7)"

docs/man/man7/l4_thread_switch.7

@@ -10,9 +10,10 @@
 
 .BI "int l4_thread_switch(u32 " "dest" ");"
 .SH DESCRIPTION
-.BR l4_thread_switch()  " - Yields the CPU."
+.BR l4_thread_switch()  " - yields the CPU. Current thread yields the CPU donating its left timeslice to thread with id specified in the
+.I dest
+field.
 
-Current thread yields the CPU donating its left timeslice to thread with ID specified in the 
-.B dest 
-argument.
+.SH RETURN VALUE
+Always succeeds with a return value of 0.
 

docs/man/man7/l4_time.7

@@ -1,27 +1,44 @@
 .TH L4_TIME 7 2009-11-07 "Codezero" "Codezero Programmer's Manual"
 .SH NAME
 .nf
-.BR "l4_time" "- Sets or returns system time."
+.BR "l4_time" " - sets or reads system time."
 
 .SH SYNOPSIS
 .nf
 .B #include <l4lib/arch/syscalls.h>
 .B #include <l4lib/arch/syslib.h>
 
-.BI "int l4_time(void " "*timeval" ", int " "set" ");"
+.BI "int l4_time(struct timeval *" "timeval" ", int " "set" ");"
+
 .SH DESCRIPTION
-.BR l4_time() " - Sets or returns system time."
+.BR "l4_time() " "sets or reads system time. "
 
-System time is read in the 
-.B timeval 
-argument field.
+.IR "timeval " "field is the representation of time since the system has started running. See below for details."
 
-If 
-.B set
-argument is a non-zero value, system time is set using the values in 
-.B timeval
+.IR "set " " field instructs whether the time is to be read or set to the values specified in the " "timeval " "field supplied."
 
-Currently setting the time feature is disabled
+.nf
+.B struct timeval {
+.BI "      int " "tv_sec;"  "    /* Time value in seconds */ "
+.BI "      int " "tv_usec;" "   /* Time value in microseconds */ "
+.B };
+.fi
 
-Currently the system time is returned since the system has started rather than a set date.
+.SH LIMITATIONS
+- Currently setting the time feature is disabled.
+
+- Currently the system time is returned since the system has started rather than a set date.
+
+- Currently this system call is not subject to capabilities.
+
+.SH ERRORS
+.TP
+.B -EFAULT
+.IR "timeval " "field would cause an unhandled page fault."
+.TP
+.B -EBUSY
+Timer structures in the system are currently being used.
+.TP
+.B -ENOSYS
+Operation of given type is not supported.
 

docs/man/man7/l4_unmap.7

@@ -1,7 +1,7 @@
 .TH L4_UNMAP 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
 .SH NAME
 .nf
-.BR "l4_unmap" "- Removes virtual to physical address mappings."
+.BR "l4_unmap" " - removes virtual to physical address mappings."
 
 .SH SYNOPSIS
 .nf
@@ -10,9 +10,9 @@
 
 .BI "int l4_unmap(void " "*virtual" ", unsigned long " "npages" ", l4id_t " "tid" ")"
 .SH DESCRIPTION
-.BR l4_unmap()  " Removes virtual to physical address mappings from a thread's address space"
+.B l4_unmap()
+.RI "removes a virtual to physical mapping from the address space of the thread identified by " "tid " "starting from virtual address " "virtual" ", and spanning " "npages" " number of pages."
 
-.RB "Removes a virtual to physical mapping for the thread identified by " "tid" ", startingfrom virtual address " "virtual" ", spanning " "npages" " number of pages."
 
 
 .SH L4 USERSPACE LIBRARY
@@ -23,5 +23,24 @@
  * spanning npages number of pages. Returns negative value
  * if the address was already unmapped.
  */
-
 .BI "static inline void *l4_unmap_helper(void " "*virt" ", int " "npages" ");"
+
+.fi
+.SH RETURN VALUE
+.BR "l4_unmap"()
+returns 0 on success, and negative value on failure. See below for error codes.
+
+.SH ERRORS
+
+.B -ESRCH
+The thread to remove the mapping could not be found on the system.
+
+.B -ENOCAP
+Capabilities required don't exist or caller do not have sufficient privileges.
+
+.B -1
+There is already an unmapped area in one of the pages that were unmapped. This may or may not be an error, depending on what state the caller expects the unmapped area to be in.
+
+.SH SEE ALSO
+.BR "l4_map"(7)
+