Updates to man pages

docs/man/man7/l4_capability_control.7

@@ -30,25 +30,43 @@ almost always contains a capability structure that describes the request with re
 and
 .IR "flags."
 .TP
+.TP
+.I capid
+Currently unused
+.TP
+.I tid
+Unused
+.TP
+
 .BR CAP_CONTROL_NCAPS
-Get capability count, sum of private capabilities, address space capabilities and container capabilities.
+Get capability count. This is the sum of thread-private capabilities, address space capabilities and container capabilities.
 .TP
 .BR CAP_CONTROL_READ
-Returns a
+Returns an array of
 .BI "struct " "capability"
-via
+structures in
 .I buf.
+The number of capabilities in the array should be first obtained by the
+.B CAP_CONTROL_NCAPS
+request.
 .TP
 .BR CAP_CONTROL_SHARE
-If
+Shares a single capability or list of capabilities with a collection entity such as an address space or a container. If
 .B CAP_SHARE_SINGLE
 is specified in
 .IR "flag",
-only the capability is moved from container capability list to address space capablity list, if
+only the given capability is shared with that entity, and if
 .B CAP_SHARE_ALL
 is specified in
 .IR "flag",
-all capabiliteis are moved from container's capability list to address sapce capability list.
+all capabilities in the given list are shared with that entity.
+
+The sharing must be made with a collection entity that contains the original entity. For example, a capability possessed by a thread may be shared with the thread's address space, or the thread's container. However it is not possible to share a capability in one container with another container. See
+.B CAP_CONTROL_REPLICATE
+and
+.B CAP_CONTROL_GRANT
+on other methods of transferring a possessed capability to another entity.
+
 .TP
 .BR CAP_CONTROL_GRANT
 Grant the capabilities in the buffer
@@ -84,29 +102,19 @@ Deduction can be by access permissions, start, end, size fields, or the target r
 Destroys a capability specified in
 .IR "flag".
 
-.TP
-.I capid
-Currently not used, for Future
-.TP
-.I tid
-Currently not used, for Future
-.TP
-.I buf
-pointer to buffer, which holds more information depending on
-.IR "req".
 
 .SH RETURN VALUE
 .IR "l4_capability_control"()
-Returns 0 on success, and negetive error value on failure. See below for errors
+Returns 0 on success, and negative value on failure. See below for error codes.
 
 .SH ERRORS
 .TP
-.B EINVAL
+.B -EINVAL
 when a capability struct is passed in
 .IR "buf"
-but has some invalid fields.
+but with invalid fields.
 .TP
-.B ENOCAP
+.B -ENOCAP
 when capabilities required don't exist or do not have sufficient privileges.
 
 .SH SEE ALSO

docs/man/man7/l4_thread_control.7

@@ -1,7 +1,7 @@
 .TH L4_THREAD_CONTROL 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
 .SH NAME
 .nf
-.BR "l4_thread_control" "- create, destroy, suspend and resume threads."
+.BR "l4_thread_control" " - create, destroy, suspend, resume, recycle and wait on threads."
 
 .SH SYNOPSIS
 .nf
@@ -9,57 +9,142 @@
 .B #include <l4lib/arch/syslib.h>
 
 .BI "int l4_thread_control(unsigned int " "action" ", struct task_ids *" "ids" ")"
+
+
 .SH DESCRIPTION
-.BR l4_thread_control()  
-manipulates threads in the system.
+.BR l4_thread_control()
+system call manipulates threads in the system. Pagers may create, destroy, recycle, suspend and resume threads via this call. While Codezero Microkernel aims to provide dynamic privilege and resource management in the form of capabilities, this system call inherently assumes a hierarchical parent-child relationship between the caller and the target thread, such that the caller should be the pager of the targeted thread. See the Subsection
+.B THREAD RELATIONSHIPS
+below for a detailed explanation of the matter.
 .fi
-This is a privileged call that can be used by pagers only.
 
-
-The  
-.I action  
-field is the main action specifier where one of the following may be supplied as valid actions.
+.I action
+field is the main action specifier where one of the following may be supplied as valid actions:
+.TP
 
 .TP
 .B THREAD_CREATE
-Creates a new thread in a new or existing space depending on the spid argument
+Creates a new thread in a new or existing space depending on the spid argument. If spid argument denotes an existing space, new thread is added to that space. If spid argument has the value
+.B THREAD_ID_INVALID
+this is taken as a new address space creation request, and the new thread is placed into a newly allocated address space.
+Following are the action flags that are associated with a
+.B THREAD_CREATE
+request:
+
+.in 14
+.B TC_AS_PAGER
+Sets the creator of the thread as the pager of the new thread.
+
+.B TC_SHARE_PAGER
+Sets the creator's pagerid as the pager of the new thread.
+
+.B TC_SHARE_UTCB
+Sets the new thread's utcb as the creator's utcb. Threads may validly share UTCBs by making sure that they don't initiate IPC at the same time, or ensure synchronized access to UTCB fields.
+
+.B TC_SHARE_GROUP
+Sets the new thread's thread group id as the id specified by
+.I tgid field.
+
+.B TC_SHARE_SPACE
+Places the new thread into the address space specified by
+.I spid
+
+.B TC_COPY_SPACE
+Copies all page tables of the address space specified by
+.I spid
+to the new thread's newly created address space. This flag is particularly useful for implementing the
+.B POSIX fork()
+system call.
+
+.B TC_NEW_SPACE
+Creates the new thread in a brand new address space.
 .TP
-.B THREAD_DESTROY 
-Destroys a thread, and its address space if it is the only thread left
+.B THREAD_DESTROY
+Destroys a thread, and its address space if the thread destroyed is the only thread left in that address space.
 .TP
-.B THREAD_SUSPEND 
-Suspends execution of a thread 
+.B THREAD_SUSPEND
+Suspends execution of a thread. The thread goes into a dormant state.
 .TP
-.B THREAD_RUN 
-Run/Resumes execution of a thread 
+.B THREAD_RUN
+Runs or resumes execution of a thread.
 .TP
 .B THREAD_RECYCLE
-Reuses threads UTCB/Address space
+Clears all existing state of a thread, but does not deallocate the thread, leaving it dormant. The only information retained is the existing thread ids of the original thread. This is particularly useful for implementing the execve() POSIX system call.
 .TP
 .B THREAD_WAIT
-Wait for thread to complete
+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
-The 
-.IR "ids.tid" " and " "ids.spid" 
-arguments specify the thread and address space that is going to be manipulated with the specified 
-.I "action" 
-argument.
 
-.ti 10
-.BI "struct" " task_ids " 
-{
-.ti 18
-.BI "int" " tid" ";"
-.ti 18
-.BI "int" " spid" ";"
-.ti 18
-.BI "int" " tgid" ";"
-.ti 10
+.I ids
+field specifies the thread, address space, and thread group ids of the targeted thread. Below is the declaration for this structure:
+
+.nf
+.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
 };
+.ti 7
+.TP
+.fi
+.I tid
+argument specifies the targeted thread id for the request. This is a fully qualified thread id that uniquely identifies the thread in the system. The benefit of a fully qualified id is that it may be used to address threads that exist in other containers in the system.
+.BI "__cid("tid ")"
+macro extracts the Container ID information from the fully qualified thread id, whereas the
+.BI " __raw_tid("tid ")"
+macro provides the raw Thread ID, which omits the container ID information from the thread id. Such a raw ID still uniquely identifies the thread across containers.
+.TP
+.fi
+.I spid
+field has meaning only on a
+.B THREAD_CREATE
+request. It either identifies the targeted address space, or by providing an invalid id, signals to the system that a new address space needs to be created.
+.TP
+.fi
+.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.
+
+.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 very 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
+field inside the kernel, to denote the relationship that a thread has create or destroy rights on another thread. The relationship is only a one-level relationship, and it may be manipulated upon thread creation by
+.B TC_AS_PAGER
+or
+.B TC_SHARE_PAGER
+fields.
+
 
 .SH L4 Userspace Library Functions
 .nf
 N/A
- 
- 
+
+.SH RETURN VALUE
+.IR "l4_thread_control"()
+Returns 0 on success, and negative value on failure. See below for error codes.
+
+.SH ERRORS
+
+.B -EINVAL
+returned when
+.IR "req"
+field has an invalid value.
+
+.B -ENOCAP
+returned when capabilities required don't exist or do not have sufficient privileges.
+
+.B -EFAULT
+returned when
+.I ids
+argument would cause a page fault.
+
+.B -ESRCH
+returned when a given thread id has not been found in the container.
+
+.SH SEE ALSO
+.BR "capability"(7), " l4_exchange_registers"(7)

docs/man/man7/utcb.7

@@ -1,50 +1,86 @@
-.TH L4_UTCB 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
+.TH UTCB 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
 .SH NAME
 .nf
-.BR "UTCB" "- User visible thread control block"
+.BR "UTCB" " - Userspace Thread Control Block"
 
 .SH SYNOPSIS
 
 .B #include <l4lib/arch/utcb.h>
 
-UTCB is a memory block designated as thread local storage that also serves as storage space for per-thread message registers transferred during an IPC between two threads.
 
 .fi
 .SH DESCRIPTION
 
-UTCB address is a virtual address that is unique for each thread available on the system and is discovered at run-time by reading the 
-.BR "Kernel Interface Page" "."
-It also stores message registers that are transferred between threads during an IPC. Depending on whether the IPC is a send or a receive, the message register fields are either transferred to other threads, or overwritten by message registers of other threads. For details please refer to the 
+UTCB is a per-thread data structure designated as thread local storage for IPC message registers and private data. The UTCB area in a thread's address space is a virtual address region that is unique for each thread available on the system. It is discovered at run-time by reading the
+.BR "Kernel Interface Page"
+utcb field.
+
+The UTCB stores message registers that are transferred between threads during an IPC. Depending on whether the IPC is a send or a receive, the message register fields are either transferred to other threads, or overwritten by message registers of other threads. For details on IPC behaviour please refer to the
 .BR l4_ipc ()
 system call reference page.
 
+UTCB may also be used for any thread-local information that is private to each thread in an address space. For example on stacked IPCs where a new IPC is initiated before the current IPC has been completed,
+.I saved_tag
+and
+.I saved_sender
+fields serve the purpose of saving the unfinished IPC information.
+.I notify
+field provides asynchronous notification slots for asynchronous messages. For a full description of each field please refer to below.
 .fi
-UTCB address pool is predefined by the microkernel, but each individual address is allocated by the pagers. 
-
-.fi
-The UTCB structure is subject to change. New fields may be reserved on the UTCB as needed.
-
 
 .ti 8
-.BI "struct " "utcb " 
+.BI "struct " "utcb "
 {
 .ti 12
 .BI  "u32 "  "mr[MR_TOTAL]" ";       /* MRs that are mapped to real registers */"
 .ti 12
-.BI  "u32 "  "saved_tag" ";          /* Saved tag field for stacked ipcs */"
+.BI  "u32 "  "saved_tag" ";          /* Saved tag field for stacked ipc */"
 .ti 12
-.BI  "u32 "  "saved_sender" ";       /* Saved sender field for stacked ipcs */"
+.BI  "u32 "  "saved_sender" ";       /* Saved sender field for stacked ipc */"
 .ti 12
-.BI  "u32 "  "mr_rest[MR_REST]" ";   /* Complete the utcb for up to 64 words */"
+.BI  "u8 "   " notify[8]" ";          /* Asynchronous notification slots. One slot per byte. */"
+.ti 12
+.BI  "u32 "  "mr_rest[MR_REST]" ";   /* Complete the utcb to 64 words */"
 .ti 8
 };
 
+.TP
 .fi
-UTCB may contain thread-local information; on the ARM architecture, the only fields on the UTCB that are not message registers are the 
 .I saved_tag
-and 
+Saved IPC tag field on a stacked IPC.
+.TP
+.fi
 .I saved_sender
-fields, which are used for saving the context of an earlier IPC if a new IPC is going to be made before finishing the first one in a stacked fashion.
+Saved sender id on a stacked IPC.
+.TP
+.fi
+.I notify
+This field consists of eight single-byte slots that are used for asynchronous messaging. Each thread subscribes to one or more slots, and may sleep on these slots if needed. Any asynchronous message sent to the thread updates these slots with new values. IRQs are often handled in userspace with the help of these slots. See
+.B l4_irq_control()
+for detailed information.
+
+.SH UTCB ALLOCATION
+UTCB address and memory allocation is not maintained by Codezero Microkernel. Both UTCB allocation and maintainence is expected to be handled in userspace.
+As an example, a pager for a group of threads may use the UTCB management functions to allocate and manage multiple UTCBs. This would be a more complicated but well-addressed approach, since this library would maintain multiple utcb areas across different address spaces, and differentiate between address spaces upon allocation. Otherwise a single address space multi-threaded application may simply use a pool of memory and virtual addresses to manage per-thread UTCB areas.
+
+UTCB addresses may be any virtual address, however there is a restriction that the utcb address region must lie in a disjoint virtual memory region. This is required because when an IPC is established, the kernel does a direct copy between UTCB regions, without the need for page-table manipulation.
+
+The simplest solution to create a UTCB is to simply declare a UTCB size aligned array of utcb structures statically by the below macro:
+
+.BI "#define DECLARE_UTCB(" name ")
+.B struct utcb name ALIGN(sizeof(struct utcb))
+
+.B DECLARE_UTCB(utcb);
+
+While this works, it requires the statically allocated structure to lie in a virtual address area that is disjoint from any other virtual address in the system.
+
+Pagers may set a thread's utcb by the
+.I l4_exchange_registers()
+system call. See this call on how to set up a new utcb.
+
+.fi
+The UTCB structure may be of variable size, and has been set to a total of 256 bytes on an ARM system. The UTCB structure is subject to change. New fields may be reserved on the UTCB as needed.
+
 
 .in 8
 .SH L4 Userspace Library Functions
@@ -53,3 +89,6 @@ fields, which are used for saving the context of an earlier IPC if a new IPC is
 /* Functions to read/write utcb registers */
 .BI "static inline unsigned int read_mr(int " "offset");
 .BI "static inline void write_mr(unsigned int " "offset" ", unsigned int " "val" ")"
+
+.SH SEE ALSO
+.BR "l4_irq_control"(7), " l4_exchange_registers"(7)