Kernel updates since December 2009

docs/architecture.txt

@@ -0,0 +1,14 @@
+
++-+ + + + + + + +	+ + + + + + + + +
+|T| | | | | | | |	| | | | | | | | |
+|H| | | | | | | |	| | | | | | | | |
+|R| | | | | | | |	| | | | | | | | |
+|E| | | | | | | |	| | | | | | | | |
+|A| | | | | | | |	| | | | | | | | |
+|D| | | | | | | |	| | | | | | | | |
++-------+-------+	+-------+-------+
+| Space | Space |	| Space | Space |
++---------------+	+---------------+
+|   Container	|	|   Container	|
++---------------+	+---------------+
+

docs/man/man7/capability.7

@@ -15,29 +15,26 @@ Each thread, address space and container is associated with its own capability l
 
 The capability structure is defined as follows:
 .nf
-.TP
-.BI "struct" " capability " "{"
-.in 16
-.BI "struct link " "list" ";"
+.B struct capability {
+.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 */"
+ 	   /* 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 */"
+	   /* 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 */"
+	   /* 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
+.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) */"
 .B };
 
 .TP

docs/man/man7/kip.7

@@ -13,41 +13,38 @@ The kernel interface page acts as a read-only identification structure for syste
 
 KIP also provides the address of the thread-local UTCB address, and the value of this field dynamically changes as each thread becomes runnable. The KIP structure is defined as follows:
 .nf
-.TP
-.BI "struct" " kip " "{"
-.in 16
-/* System descriptions */
-.BI "u32 " "magic" ";"
-.BI "u16 " "version_rsrv" ";"
-.BI "u8  " "api_subversion" ";"
-.BI "u8  " "api_version" ";"
-.BI "u32 " "api_flags" ";"
+.B struct kip {
+	   /* System descriptions */
+.BI "	   u32 " "magic" ";"
+.BI "	   u16 " "version_rsrv" ";"
+.BI "	   u8  " "api_subversion" ";"
+.BI "	   u8  " "api_version" ";"
+.BI "	   u32 " "api_flags" ";"
 .BI ""
-/* Addresses of various avaiable System calls */
-.BI "u32 " "container_control" ";"
-.BI "u32 " "time" ";"
-.BI "u32 " "irq_control" ";"
-.BI "u32 " "thread_control" ";"
-.BI "u32 " "ipc_control" ";"
-.BI "u32 " "map" ";"
-.BI "u32 " "ipc" ";"
-.BI "u32 " "capability_control" ";"
-.BI "u32 " "unmap" ";"
-.BI "u32 " "exchange_registers" ";"
-.BI "u32 " "thread_switch" ";"
-.BI "u32 " "schedule" ";"
-.BI "u32 " "getid" ";"
-.BI "u32 " "mutex_control" ";"
-.BI "u32 " "arch_syscall0" ";"
-.BI "u32 " "arch_syscall1" ";"
-.BI "u32 " "arch_syscall2" ";"
+	   /* Addresses of various avaiable System calls */
+.BI "	   u32 " "container_control" ";"
+.BI "	   u32 " "time" ";"
+.BI "	   u32 " "irq_control" ";"
+.BI "	   u32 " "thread_control" ";"
+.BI "	   u32 " "ipc_control" ";"
+.BI "	   u32 " "map" ";"
+.BI "	   u32 " "ipc" ";"
+.BI "	   u32 " "capability_control" ";"
+.BI "	   u32 " "unmap" ";"
+.BI "	   u32 " "exchange_registers" ";"
+.BI "	   u32 " "thread_switch" ";"
+.BI "	   u32 " "schedule" ";"
+.BI "	   u32 " "getid" ";"
+.BI "	   u32 " "mutex_control" ";"
+.BI "	   u32 " "arch_syscall0" ";"
+.BI "	   u32 " "arch_syscall1" ";"
+.BI "	   u32 " "arch_syscall2" ";"
 .BI ""
-/* UTCB address field */
-.BI "u32 " "utcb" ";"
+	   /* UTCB address field */
+.BI "	   u32 " "utcb" ";"
 .BI ""
-/* Brief Description of Kernel */
-.BI "struct " "kernel_descriptor kdesc" ";"
-.in 6
+	   /* Brief Description of Kernel */
+.BI "	   struct " "kernel_descriptor kdesc" ";"
 .B };
 
 .TP

docs/man/man7/l4_cache_control.7

@@ -0,0 +1,80 @@
+.TH L4_CACHE_CONTROL 7 2009-11-07 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "l4_cache_control" " - Cache/TLB manipulation"
+
+.SH SYNOPSIS
+.nf
+.B #include <l4lib/arch/syscalls.h>
+.B #include <l4lib/arch/syslib.h>
+
+.BI "int l4_cache_control (unsigned int " "start" ", unsigned int " "end" ", unsigned int " "flags");
+.SH DESCRIPTION
+.B l4_cache_control()
+enables a thread to invalidate and clean the cache memory.
+.TP
+.fi
+.I start
+denotes the start address(virtual memory address) of memory region to be invalidated/cleaned. This is not used in case of armv5.
+
+.TP
+.fi
+.I end
+denotes the end address(virtual memory address) of memory region to be invalidated/cleaned. This is not used in case of armv5.
+
+.TP
+.fi
+.I flags
+denotes the operation to be performed.
+
+.TP
+.BR L4_INVALIDATE_CACHE
+Invalidate/flush both I and D caches.
+
+.TP
+.BR L4_INVALIDATE_ICACHE
+Invalidate/flush I cache.
+
+.TP
+.BR L4_INVALIDATE_DCACHE
+Invalidate/flush D cache.
+
+.TP
+.BR L4_CLEAN_DCACHE
+Clean D cache.
+
+.TP
+.BR L4_CLEAN_INVALIDATE_DCACHE
+Clean and Invalidate D cache.
+
+.TP
+.BR L4_CLEAN_INVALIDATE_CACHE
+Invalidate/flush both I and D cache and Clean D cache.
+
+.TP
+.BR L4_DRAIN_WRITEBUFFER
+Drain Write Buffer.
+
+.TP
+.BR L4_INVALIDATE_TLB
+Invalidate/flush TLB.
+
+.TP
+.BR L4_INVALIDATE_ITLB
+Invalidate/flush I TLB.
+
+.TP
+.BR L4_INVALIDATE_DTLB
+Invalidate/flush D TLB.
+
+.SH RETURN VALUE
+.IR "l4_cache_control"()
+Returns 0 on success, and negative value on failure. See below for error codes.
+
+.SH ERRORS
+.TP
+.B -EINVAL
+when a
+.IR "flag"
+is passed with invalid fields.
+

docs/man/man7/l4_capability_control.7

@@ -16,20 +16,21 @@ enables a thread to read and manipulate the list of capabilities that it possess
 .fi
 .I req
 denotes the type of request. See below for a full list.
+
 .TP
 .fi
 .I flags
 denotes additional flags for the given request. See below for a list of flags.
+
 .TP
 .fi
-
 .I buf
 almost always contains a capability structure that describes the request with regard to given
 .IR "req"
 and
 .IR "flags."
-.TP
 
+.TP
 .BR CAP_CONTROL_NCAPS
 Get capability count. This is the sum of thread-private capabilities, address space capabilities and container capabilities.
 .TP

docs/man/man7/l4_exchange_registers.7

@@ -17,44 +17,37 @@ By this call, pagers can read and modify any register or other crucial informati
 is passed to the kernel for modifying the targeted thread's context. See below for a detailed description of this structure and the default context structure for the ARM architecture.
 
 .nf
-.in 8
 /* Exchange registers context structure for the ARM architecture */
 .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
+.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 */"
 .B } __attribute__((__packed__)) exregs_context_t;
 
 .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
+.BI "	   exregs_context_t " "context" ";"
+.BI "	   u32 " "valid_vect" ";"
+.BI "	   u32 " "flags" ";"
+.BI "	   l4id_t " "pagerid" ";"
+.BI "	   unsigned long " "utcb_address" ";"
 .B };
 
 .fi

docs/man/man7/l4_getid.7

@@ -13,13 +13,10 @@
 .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
-.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
+.B struct task_ids {
+.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) */"
 };
 
 .fi
@@ -27,7 +24,11 @@
 .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.
+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 that reside 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. For thread ids,
+.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, i.e. there is one such raw id per thread across the system.
 
 .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."

docs/man/man7/l4_irq_control.7

@@ -0,0 +1,67 @@
+.TH L4_IRQ_CONTROL 7 2009-11-07 "Codezero" "Codezero Programmer's Manual"
+.SH NAME
+.nf
+.BR "l4_irq_control" " -  Register/unregister device irqs.
+
+.SH SYNOPSIS
+.nf
+.B #include <l4lib/arch/syscalls.h>
+.B #include <l4lib/arch/syslib.h>
+
+.BI "int l4_irq_control (unsigned int " "req" ", unsigned int " "flags" ", l4id_t " "id");
+.SH DESCRIPTION
+.B l4_irq_control()
+enables a thread to register/unregister device irqs. Caller of this sytem call has an option to choose between synchronous or asynchronous irq handling.
+.TP
+.fi
+.I req
+denotes the type of operation to be performed.
+
+.TP
+.BR IRQ_CONTROL_REGISTER
+Register the caller thread as irq handler for the irq index
+.BR "id".
+
+.TP
+.BR IRQ_CONTROL_RELEASE
+Unregister the caller thread, earlier registered as irq handler for the irq index
+.BR "id".
+
+.TP
+.BR IRQ_CONTROL_WAIT
+Wait for irq to happen. This flag is used by the irq handler to block and wait for irq to happen.
+
+.TP
+.fi
+.I flags
+denotes the slot number representing the irq handler, this is the identifier which distinguishes various handlers registered for the same device.
+
+.TP
+.fi
+.I id
+denotes the platform specific irq index of the concerned device.
+
+.SH RETURN VALUE
+.IR "l4_irq_control"()
+Returns 0 on success, and negative value on failure. See below for error codes.
+
+.SH ERRORS
+.TP
+.B -EINVAL
+when the
+.IR "flags"
+passed is not having valid information.
+
+.TP
+.B -ENOUTCB
+in case the thread making the system call does not have a valid utcb.
+
+.TP
+.B -EFAULT
+in case utcb of caller thread is not mapped.
+
+.TP
+.B -ENOIRQ
+in case the device represented by irq index
+.BR "id"
+is invalid or kernel does not allow user space tasks to avail this device.

docs/man/man7/l4_mutex_control.7

@@ -42,12 +42,8 @@ argument specifies the userspace virtual address for the lock. See below for a u
 .SH L4 USERSPACE LIBRARY
 
 .nf
-.br
-.in 7
 .B struct l4_mutex {
-.in 15
-.BI	"unsigned int " "lock" ";"
-.in 7
+.BI "	   unsigned int " "lock" ";"
 .B } __attribute__((aligned(sizeof(int))));
 
 .BI "void l4_mutex_init(struct l4_mutex " "*m" ");"

docs/man/man7/l4_thread_control.7

@@ -18,26 +18,54 @@ system call manipulates threads in the system. Pagers may create, destroy, recyc
 subsection below for a detailed explanation of the matter.
 .fi
 
+.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
+.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 may have different meanings for different thread control actions. For an existing thread, this argument specifies the thread on which the action is to be performed. On a thread creation request, this argument would specify the thread whose context is to be copied from for creating the new thread. See
+.I actions
+below for a more detailed explanation.
+
+.TP
+.fi
+.I spid
+field has meaning only on a
+.B THREAD_CREATE
+request, in conjunction with one of
+.B TC_SHARE_SPACE,
+.B TC_NEW_SPACE
+or
+.B TC_COPY_SPACE
+flags
+.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.
+
 .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. 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.
+Creates a new thread in a new or existing space depending on the provided space flags.
+.RI "A thread create request requires valid " "tid" " and " "spid" " fields in order to specify which thread context and address space to copy from or use."
 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.
 
@@ -47,12 +75,14 @@ Sets the new thread's thread group id as the id specified by
 
 .B TC_SHARE_SPACE
 Places the new thread into the address space specified by
-.I spid
+.IR "spid" ", and copies the thread context from thread specified by " "tid" " field. The thread represented by the " "tid " "argument is said to represent a "
+.BR "parent " " relationship to the newly created thread."
 
 .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
+to the new thread's newly created address space.
+.RI "Also copies the thread context from thread specified by the " "tid " "field, who is said to represent a " "parent" " relationship to the newly created thread. This flag is particularly useful for implementing the"
 .B POSIX fork()
 system call.
 
@@ -77,41 +107,6 @@ 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 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
-.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, in conjunction with one of
-.B TC_SHARE_SPACE,
-.B TC_NEW_SPACE
-or
-.B TC_COPY_SPACE
-flags
-.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.
 
 .in 7
 .RB "See " "l4_getid" "(7) for more details on resource ids in Codezero."

docs/man/man7/utcb.7

@@ -22,18 +22,12 @@ system call reference page.
 .RI "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, " "saved_tag " "and " "saved_sender " "fields serve the purpose of saving the unfinished IPC information. For a full description of each field please refer to below. "
 .fi
 
-.ti 8
-.BI "struct " "utcb "
-{
-.ti 16
-.BI  "u32 "  "mr[MR_TOTAL]" ";       /* MRs that are mapped to real registers */"
-.ti 16
-.BI  "u32 "  "saved_tag" ";          /* Saved tag field for stacked ipc */"
-.ti 16
-.BI  "u32 "  "saved_sender" ";       /* Saved sender field for stacked ipc */"
-.ti 16
-.BI  "u32 "  "mr_rest[MR_REST]" ";   /* Complete the utcb to 64 words */"
-.ti 8
+.nf
+.B struct utcb {
+.BI "	   u32 "  "mr[MR_TOTAL]" ";       /* MRs that are mapped to real registers */"
+.BI "	   u32 "  "saved_tag" ";          /* Saved tag field for stacked ipc */"
+.BI "	   u32 "  "saved_sender" ";       /* Saved sender field for stacked ipc */"
+.BI "	   u32 "  "mr_rest[MR_REST]" ";   /* Complete the utcb to 64 words */"
 };
 
 .TP

docs/tls.txt

@@ -6,12 +6,12 @@ registers and write the IPC payload. This necessitates a convenient method
 of accessing the thread-specific utcb structure. Here are some of the
 possible methods of accessing a thread local storage in general:
 
-1.) Keep a global pointer to it. The scheduler updates the pointer to TLS
-upon every context switch.
-
-2.) Map the private physical TLS page to thread address space at same virtual
+1.) Map the private physical TLS page to thread address space at same virtual
 offset, everytime there is a context switch.
 
+2.) Keep a global pointer to it. The scheduler updates the pointer to TLS
+upon every context switch.
+
 3.) Manage everything by the run-time library in the application. This includes
 the following:
 
@@ -42,9 +42,9 @@ as new threads come to life, and map this when they run, without managing utcb
 table size. The downside is that a page is wasted per-thread.
 
 The solution Codezero uses includes a mixture of both (1) and (2). Upon a
-context switch, a private page is allocated and mapped by the pager, but also
+context switch, a page private to each context is mapped by the pager, but also
 the UTCB pointer is updated to point at an offset in this page. As an example,
 if a UTCB is sized 1/4th of a page, a single page is used by 4 UTCBs. This way,
 the pager needs to manage 4 entries per-private page, utcbs utilise page memory
-fully, and there is no need for a fixed table of utcbs per address space.
-
+fully, and there is no need for a fixed table of utcbs per address space. Of
+course, utcb pages are only shared by threads in the same address space.