Added manual pages - Not release quality yet.

docs/man/man7/capability.7

@@ -0,0 +1,59 @@
+.TH CAPABILITY 7 2009-11-07 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "Capability" " - Overview of Capabilities in Codezero"
+
+.SH DESCRIPTION
+A capability is a unique representation of security qualifiers on a particular resource.
+Each thread, address space and container is associated with its own capability list represented by the below structure.
+
+.nf
+.TP
+.BI "struct" " capability " "{"
+.in 16
+.BI "struct link " "list" ";"
+.BI ""
+/* Capability identifiers */
+.BI "l4id_t " "capid" ";         /* Unique capability ID */"
+.BI "l4id_t "  "owner" ";         /* Capability owner ID */"
+.BI "l4id_t " "resid" ";         /* Targeted resource ID */"
+.BI "unsigned int " "type" ";    /* Capability and target resource type */"
+.BI ""
+/* Capability permissions */
+.BI "u32 " "access" ";           /* Permitted operations */"
+.BI ""
+/* Other Limits/Attributes of the resource */
+.BI "unsigned long " "start" ";  /* Resource start value */"
+.BI "unsigned long " "end" ";    /* Resource end value */"
+.BI "unsigned long " "size" ";   /* Resource size */"
+.BI ""
+.BI "unsigned long " "used" ";   /* Resource used size */"
+.BI "unsigned int " "attr" ";   /* User-defined attribute. (Device index and type on devices) */"
+.BI "l4id_t " "irq" ";   /* Device irq (Devices Only) */"
+.in 6
+.B };
+
+.TP
+.fi
+.I capid
+denotes the unique capability ID.
+.TP
+.fi
+.I resid
+denotes the unique ID of targeted resource. The smallest resource targetable by a capability is a thread. There are also collections of targetable resources such as an address space or a container. An address space target resource implies all threads inside that address space, and a container target resource implies all threads inside that container. Quantitative capabilities such as typed memory pools do not possess a target, and therefore have an invalid resource ID.
+.TP
+.fi
+.I owner
+denotes the unique ID of the one and only capability owner. This is always a thread ID. The ownership of a capability determines who has the right to practise the capability modification privileges available over the capability, such as sharing, granting, spliting, reducing or destruction of the capability.
+.TP
+.fi
+.I type
+field contains the capability type or targeted resource type. The capability type determines the generic operations that the capability describes. For example a capability describing a system call would likely have a type name that resembles the name of that system call. See below for the list of valid capability types. The resource type denotes the type of targeted resources. In case this is a thread or a collection of threads, the type may be one of thread, address space, or container. Quantitative resources also have different types, describing the resource. Since quantitative resources such as memory pools, or memory regions are not associated with a target id, the types have no meaning for the resid field for these capabilities. See below for the full list of valid resource types.
+.TP
+.fi
+.I access
+field denotes the fine-grain operations available on a particular resource. The meaning of each bitfield differs according to the type of the capability. For example, for a capability type thread_control, the bitfields may mean suspend, resume, create, delete etc. See below for the full list of capability bits.
+
+
+.SH SEE ALSO
+.BR "l4_capability_control"(7)

docs/man/man7/l4_capability_control.7

@@ -0,0 +1,104 @@
+.TH L4_CAPABILITY_CONTROL 7 2009-11-07 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "l4_capability_control" "- Set/Get Various capabilities of thread"
+
+.SH SYNOPSIS
+.nf
+.B #include <l4lib/arch/syscalls.h>
+.B #include <l4lib/arch/syslib.h>
+
+.BI "int l4_capability_control (unsigned int " "req" ", unsigned int " "flags",
+.BI "                           l4id_t " "capid" ", l4id_t " "tid" ", void " "*buf" ");"
+.SH DESCRIPTION
+.BR l4_capability_control() " -"
+Sets various capabilities of a thread, capabilities are read/modified always with respect to current task/thread, current address space or current container. The thread calling this system call must posses a capability to do capability. It returns
+.B ENOCAP
+if the capabilities specified by 
+.I req
+and
+.I flags
+are not valid capabilities for current thread. 
+
+.I req
+is type of requtest and can take one of these values
+.TP
+.BR CAP_CONTROL_NCAPS               
+Get capability count, sum of private capabilities, address space capabilities and container capabilities.
+.TP
+.BR CAP_CONTROL_READ
+Returns a 
+.BI "struct " "capability"
+via 
+.I buf.
+.TP
+.BR CAP_CONTROL_SHARE               
+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 
+.B CAP_SHARE_ALL
+is specified in
+.IR "flag",
+all capabiliteis are moved from container's capability list to address sapce capability list.
+.TP
+.BR CAP_CONTROL_GRANT
+Grant the capabilities in the buffer
+.IR "buf",
+if 
+.I flag 
+has 
+.BR "CAP_GRANT_SINGLE",
+if 
+.B CAP_GRANT_ALL
+is provided with flag all capabilities are granted, if
+.B CAP_GRANT_IMMUTABLE
+is specified in flags then all(or one) capabilities are made immutable.
+.TP
+.BR CAP_CONTROL_REPLICATE
+Replicates an existing capability. This is for expanding capabilities to managed children.
+.TP
+.B CAP_CONTROL_SPLIT
+Capabilities are split by diff'ing resources possessed between capabilities.
+.I flags 
+may be one of
+.B CAP_SPLIT_SIZE     
+or
+.B CAP_SPLIT_ACCESS   
+or
+.B CAP_SPLIT_RANGE.
+
+.TP
+.BR CAP_CONTROL_DEDUCE              
+Deduction can be by access permissions, start, end, size fields, or the target resource type. Inter-container deduction is not allowed. Target resource deduction denotes reducing the applicable space of the target, e.g. from a container to a space in that container.
+.TP
+.BR CAP_CONTROL_DESTROY
+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
+
+.SH ERRORS
+.TP 
+.B EINVAL
+when a capability struct is passed, but it has some invalid fields.
+.TP
+.B ENOCAP
+when capabilities doesn't match or doesn't exists.
+
+.SH SEE ALSO
+.BR "capability"(7)

docs/man/man7/l4_exchange_registers.7

@@ -0,0 +1,89 @@
+.TH L4_EXCHANGE_REGISTERS 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "l4_exchange_registers" "- Modifies the context of a suspended thread."
+
+.SH SYNOPSIS
+.nf
+.B #include <l4lib/arch/syscalls.h>
+.B #include <l4lib/arch/syslib.h>
+
+.BI "int l4_exchange_registers(void " "*exregs_struct" ", l4id_t " "tid" ");"
+.SH DESCRIPTION
+.BR l4_exchange_registers()  " Modifies the context of a suspended thread."
+
+Pagers can modify any register, the pager id or utcb virtual address of a thread using this call.
+
+An architecture specific 
+.BI "struct " exregs_data
+is passed to the kernel for modifying the context of a thread.
+
+Each bit in the 
+.B valid_vect 
+field determines which register offsets are to be modified.
+
+.B flags
+field determines whether to set the 
+.BR pagerid " and " utcb_address
+fields of the thread.
+
+.nf
+.in 8
+/* Values for the flags fields */
+#define EXREGS_SET_PAGER	1
+#define EXREGS_SET_UTCB	2
+#define EXREGS_READ	4
+.nf
+.in 8
+
+/* Generic structure passed by userspace pagers 
+ * for exchanging registers  
+ */
+.B struct exregs_data {
+.in 16
+.BI "exregs_context_t " "context" ";"
+.BI "u32 " "valid_vect" ";"
+.BI	"u32 " "flags" ";"
+.BI "l4id_t " "pagerid" ";"
+.BI "unsigned long " "utcb_address" ";"
+.ti 8
+.B };
+
+.in 8
+/* Exchange registers context structure for ARM */
+.B typedef struct arm_exregs_context {
+.in 16
+.BI	"u32 " "r0" ";		/* 0x4 */"
+.BI	"u32 " "r1" ";		/* 0x8 */"
+.BI	"u32 " "r2" ";		/* 0xC */"
+.BI	"u32 " "r3" ";		/* 0x10 */"
+.BI	"u32 " "r4" ";		/* 0x14 */"
+.BI	"u32 " "r5" ";		/* 0x18 */"
+.BI	"u32 " "r6" "; 		/* 0x1C */"
+.BI	"u32 " "r7" ";		/* 0x20 */"
+.BI	"u32 " "r8" ";		/* 0x24 */"
+.BI	"u32 " "r9" ";		/* 0x28 */"
+.BI	"u32 " "r10" ";		/* 0x2C */"
+.BI	"u32 " "r11" ";		/* 0x30 */"
+.BI	"u32 " "r12" ";		/* 0x34 */"
+.BI	"u32 " "sp" ";		/* 0x38 */"
+.BI	"u32 " "lr" ";		/* 0x3C */"
+.BI	"u32 " "pc" ";		/* 0x40 */"
+.ti 8
+.B } __attribute__((__packed__)) exregs_context_t;
+
+
+.in 8
+.SH L4 Userspace Library Functions
+
+.nf
+/*
+ * Exchange register library calls to modify program counter,
+ * stack, pager id, utcb address and any hardware register.
+ */
+
+.BI "void exregs_set_stack(struct exregs_data " "*s" ", unsigned long " sp);
+.BI "void exregs_set_mr(struct exregs_data " "*s" ", int " "offset" ", unsigned long " "val" ");"
+.BI "void exregs_set_pc(struct exregs_data " "*s" ", unsigned long " "pc" ");"
+.BI "void exregs_set_pager(struct exregs_data " "*s" ", l4id_t " "pagerid" ");"
+.BI "void exregs_set_utcb(struct exregs_data  "*s" ", unsigned long " "virt" ");"

docs/man/man7/l4_getid.7

@@ -0,0 +1,44 @@
+.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."
+
+.SH SYNOPSIS
+.nf
+.B #include <l4lib/arch/syscalls.h>
+.B #include <l4lib/arch/syslib.h>
+
+.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.
+
+.nf
+.in 16
+.B "struct task_ids {"
+.BI "int " "tid" "; /* Thread ID */"
+.BI "int " "spid" "; /* Space ID */"
+.BI "int " "tgid" "; /* Thread Group ID */"
+.B "};"
+
+.SH L4 Userspace Library Functions
+
+.nf
+/*
+ * Returns Thread ID of current thread
+ */
+
+.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_ipc.7

@@ -0,0 +1,52 @@
+.TH L4_IPC 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "l4_ipc" "- Provides inter-process communication between threads."
+
+.SH SYNOPSIS
+.nf
+.B #include <l4lib/arch/syscalls.h>
+.B #include <l4lib/arch/syslib.h>
+
+.BI "int l4_ipc(l4id_t " "to, " "l4id_t " "from, " "unsigned int " "flags" ")"
+.SH DESCRIPTION
+.BR l4_ipc()  " Provides inter-process communication between threads."
+
+IPC calls transfer messages between threads that are stored in each thread's unique UTCB area accessible in the thread's address space.
+
+UTCB is a system-defined memory block that provides thread-local storage. See UTCB for more details.
+
+There are 3 types of IPC defined as shown below
+
+.B Short IPC
+.ti 16
+Transfers only the  
+.I "Primary Message Registers"
+
+.B Full IPC
+.ti 16
+Transfers the complete UTCB of the thread. 
+
+.B Extended IPC
+.ti 16
+Transfers a message buffer of up to 2 Kilobytes in size, using any address located in the address space.
+
+
+.SH L4 Userspace Library Functions
+
+.nf
+/* Short IPC Calls */
+.BI "static inline int l4_send(l4id_t " "to" ", unsigned int " "tag" ");"
+.BI "static inline int l4_receive(l4id_t " "from" ");"
+.BI "static inline int l4_sendrecv(l4id_t " "to" ", l4id_t " "from" ", unsigned int " "tag" ");"
+
+.nf
+/* Full IPC Calls */
+.BI "static inline int l4_send_full(l4id_t " "to" ", unsigned int " "tag" ");"
+.BI "static inline int l4_receive_full(l4id_t " "from" ");"
+.BI "static inline int l4_sendrecv_full(l4id_t " "to" ", l4id_t " "from" ", unsigned int " "tag" ");"
+
+.nf 
+/* Extended IPC Calls */
+.BI "static inline int l4_send_extended(l4id_t " "to" ", unsigned int " "tag" ", unsigned int " "size" ", void " "*buf" ");"
+.BI "static inline int l4_receive_extended(l4id_t " "from" ", unsigned int " "size" ", void " "*buf" ");"

docs/man/man7/l4_map.7

@@ -0,0 +1,26 @@
+.TH L4_MAP 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "l4_map" "- Sets up 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 virtual to physical address mappings."
+
+.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" "."
+
+
+.SH L4 Userspace Library Functions
+
+.nf
+/*
+ * 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" ");"

docs/man/man7/l4_mutex_control.7

@@ -0,0 +1,56 @@
+.TH L4_MUTEX_CONTROL 7 2009-11-07 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "l4_mutex_control" "- Userspace locking and synchronization for shared memory"
+
+.SH SYNOPSIS
+.nf
+.B #include <l4lib/arch/syscalls.h>
+.B #include <l4lib/arch/syslib.h>
+
+.BI "int l4_mutex_control(void " "*mutex_word" ", int " "op" ");"
+.SH DESCRIPTION
+.BR l4_mutex_control() " - Userspace locking and synchronization for shared memory."
+
+.B op 
+argument defines whether the operation is a 
+.B lock 
+or 
+.B unlock 
+operation.
+
+.B mutex_word
+argument specifies the userspace virtual address for the lock.
+
+.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.
+
+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.
+
+.nf
+.in 16
+#define L4_MUTEX_LOCK	0
+#define L4_MUTEX_UNLOCK	1
+.nf
+.in 16
+.B struct l4_mutex {
+.BI	"unsigned int " "lock" ";"
+.B } __attribute__((aligned(sizeof(int))));
+
+
+.SH L4 Userspace Library Functions
+
+.nf
+
+.BI "void l4_mutex_init(struct l4_mutex " "*m" ");"
+.BI "int l4_mutex_lock(struct l4_mutex " "*m" ");"
+.BI "int l4_mutex_unlock(struct l4_mutex " "*m" ");"
+
+
+

docs/man/man7/l4_thread_control.7

@@ -0,0 +1,65 @@
+.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."
+
+.SH SYNOPSIS
+.nf
+.B #include <l4lib/arch/syscalls.h>
+.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.
+.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.
+
+.TP
+.B THREAD_CREATE
+Creates a new thread in a new or existing space depending on the spid argument
+.TP
+.B THREAD_DESTROY 
+Destroys a thread, and its address space if it is the only thread left
+.TP
+.B THREAD_SUSPEND 
+Suspends execution of a thread 
+.TP
+.B THREAD_RUN 
+Run/Resumes execution of a thread 
+.TP
+.B THREAD_RECYCLE
+Reuses threads UTCB/Address space
+.TP
+.B THREAD_WAIT
+Wait for thread to complete
+
+.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
+};
+
+.SH L4 Userspace Library Functions
+.nf
+N/A
+ 
+ 

docs/man/man7/l4_thread_switch.7

@@ -0,0 +1,18 @@
+.TH L4_THREAD_SWITCH 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "l4_thread_switch" " - Yields the CPU"
+
+.SH SYNOPSIS
+.nf
+.B #include <l4lib/arch/syscalls.h>
+.B #include <l4lib/arch/syslib.h>
+
+.BI "int l4_thread_switch(u32 " "dest" ");"
+.SH DESCRIPTION
+.BR l4_thread_switch()  " - Yields the CPU."
+
+Current thread yields the CPU donating its left timeslice to thread with ID specified in the 
+.B dest 
+argument.
+

docs/man/man7/l4_time.7

@@ -0,0 +1,27 @@
+.TH L4_TIME 7 2009-11-07 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "l4_time" "- Sets or returns 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" ");"
+.SH DESCRIPTION
+.BR l4_time() " - Sets or returns system time."
+
+System time is read in the 
+.B timeval 
+argument field.
+
+If 
+.B set
+argument is a non-zero value, system time is set using the values in 
+.B timeval
+
+Currently setting the time feature is disabled
+
+Currently the system time is returned since the system has started rather than a set date.
+

docs/man/man7/l4_unmap.7

@@ -0,0 +1,27 @@
+.TH L4_UNMAP 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "l4_unmap" "- Removes virtual to physical address mappings."
+
+.SH SYNOPSIS
+.nf
+.B #include <l4lib/arch/syscalls.h>
+.B #include <l4lib/arch/syslib.h>
+
+.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"
+
+.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 Functions
+
+.nf
+/*
+ * Unmaps the given virtual address from current address space
+ * 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" ");"

docs/man/man7/l4_utcb.7

@@ -0,0 +1,47 @@
+.TH L4_UTCB 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "UTCB" "- User visible thread control block"
+
+.SH SYNOPSIS
+.nf
+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 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 
+.BR L4_IPC ()
+system call reference page.
+UTCB address pool is predefined by the microkernel, but each individual address is allocated by the pagers. 
+.fi
+UTCB may contain thread-local information. Currently on the ARM architecture, the only fields on the UTCB that are not message registers are the 
+.I saved_tag
+and 
+.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.
+.fi
+The UTCB structure is subject to change. New fields may be reserved on the UTCB as needed.
+
+
+.ti 10
+.BI "struct " "utcb " 
+{
+.ti 18
+.BI  "u32 "  "mr[MR_TOTAL]" ";       /* MRs that are mapped to real registers */"
+.ti 18
+.BI  "u32 "  "saved_tag" ";          /* Saved tag field for stacked ipcs */"
+.ti 18
+.BI  "u32 "  "saved_sender" ";       /* Saved sender field for stacked ipcs */"
+.ti 18
+.BI  "u32 "  "mr_rest[MR_REST]" ";   /* Complete the utcb for up to 64 words */"
+.ti 10
+};
+
+.in 8
+.SH L4 Userspace Library Functions
+.nf
+
+/* 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" ")"

docs/man/man7/thread_control.7

@@ -0,0 +1,28 @@
+.\"
+.\" Man page for the Codezero Project
+.\"
+.\" L4 Thread Control system call
+.\"
+
+.TH L4_THREAD_CONTROL 7 2009-10-21 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+l4_thread_control \- Create a new thread in the system
+.SH SYNOPSIS
+.B #include <l4lib/arch/syscalls.h>
+.br
+.B #include <l4lib/arch/syslib.h>
+.sp
+.BI "int l4_thread_control(unsigned int " "action, " "struct task_ids * " "ids) "
+.sp
+.SH DESCRIPTION
+.B l4_thread_control()
+manipulates threads in the system.
+.I action
+field is the main action specifier where one of
+.BR THREAD_CREATE,
+.BR THREAD_RUN,
+.BR THREAD_SUSPEND,
+.BR THREAD_RESUME,
+.BR THREAD_DESTROY,
+.BR THREAD_RECYCLE,
+may be supplied as valid actions.

docs/man/man7/utcb.7

@@ -0,0 +1,55 @@
+.TH L4_UTCB 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "UTCB" "- User visible 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 
+.BR l4_ipc ()
+system call reference page.
+
+.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 " 
+{
+.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 */"
+.ti 12
+.BI  "u32 "  "saved_sender" ";       /* Saved sender field for stacked ipcs */"
+.ti 12
+.BI  "u32 "  "mr_rest[MR_REST]" ";   /* Complete the utcb for up to 64 words */"
+.ti 8
+};
+
+.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 
+.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.
+
+.in 8
+.SH L4 Userspace Library Functions
+.nf
+
+/* 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" ")"