--- /root/projects/doc/article.sgml	Mon Jun 18 08:35:59 2007
+++ /tmp/article.sgml	Mon Jun 18 08:45:42 2007
@@ -29,7 +29,7 @@
 
     <abstract>
       <para>This masters thesis deals with updating the &linux; emulation layer
-	(so called &linux;ulator).  The task was to update the layer to match
+	(so called linuxulator).  The task was to update the layer to match
 	the functionality of &linux; 2.6. As a reference implementation, the
 	&linux; 2.6.16 kernel was chosen.  The concept is loosely based on
 	the NetBSD implementation.  Most of the work was done in the summer
@@ -65,7 +65,7 @@
 
 <para>
 During the Summer of 2006 Google Inc. sponsored a project which focused on extending 
-the &linux; emulation layer (so called &linux;ulator) in &os; to include &linux; 2.6 facilities. 
+the &linux; emulation layer (so called linuxulator) in &os; to include &linux; 2.6 facilities. 
 This thesis is written about part of this project. </para>
 
 <para>
@@ -294,7 +294,7 @@
 &os; is traditional &unix; in the sense of dividing the run of a process into two halves.
 Kernel space and user space run. There are two types of process entry to the kernel: a syscall
 and a trap. There.s only one way to return. In the subsequent sections we will describe the 3
-gates to/from the kernel. All the description applies to i386 architecture as the &linux;ulator
+gates to/from the kernel. All the description applies to i386 architecture as the linuxulator
 exists only there but it.s similar for other archs. The information was taken from [1] and
 source codes.
 </para>
@@ -464,22 +464,22 @@
 
 <orderedlist>
 <listitem><para>
-parameter .> %ebx
+parameter -> %ebx
 </para></listitem>
 <listitem><para>
-parameter .> %ecx
+parameter -> %ecx
 </para></listitem>
 <listitem><para>
-parameter .> %edx
+parameter -> %edx
 </para></listitem>
 <listitem><para>
-parameter .> %esi
+parameter -> %esi
 </para></listitem>
 <listitem><para>
-parameter .> %edi
+parameter -> %edi
 </para></listitem>
 <listitem><para>
-parameter .> %ebp
+parameter -> %ebp
 </para></listitem>
 </orderedlist>
 
@@ -532,55 +532,55 @@
 
 <itemizedlist>
 <listitem><para>
-CLONE VM - processes share their memory space
+CLONE_VM - processes share their memory space
 </para></listitem>
 <listitem><para>
-CLONE FS - share umask, cwd and namespace
+CLONE_FS - share umask, cwd and namespace
 </para></listitem>
 <listitem><para>
-CLONE FILES - share open files
+CLONE_FILES - share open files
 </para></listitem>
 <listitem><para>
-CLONE SIGHAND - share signal handlers and blocked signals
+CLONE_SIGHAND - share signal handlers and blocked signals
 </para></listitem>
 <listitem><para>
-CLONE PARENT - share parent
+CLONE_PARENT - share parent
 </para></listitem>
 <listitem><para>
-CLONE THREAD - be thread (further explanation below)
+CLONE_THREAD - be thread (further explanation below)
 </para></listitem>
 <listitem><para>
-CLONE NEWNS - new namespace
+CLONE_NEWNS - new namespace
 </para></listitem>
 <listitem><para>
-CLONE SYSVSEM - share SysV undo structures
+CLONE_SYSVSEM - share SysV undo structures
 </para></listitem>
 <listitem><para>
-CLONE SETTLS - setup TLS at supplied address
+CLONE_SETTLS - setup TLS at supplied address
 </para></listitem>
 <listitem><para>
-CLONE PARENT SETTID - set TID in the parent
+CLONE_PARENT_SETTID - set TID in the parent
 </para></listitem>
 <listitem><para>
-CLONE CHILD CLEARTID - clear TID in the child
+CLONE_CHILD_CLEARTID - clear TID in the child
 </para></listitem>
 <listitem><para>
-CLONE CHILD SETTID - set TID in the child 
+CLONE_CHILD_SETTID - set TID in the child 
 </para></listitem>
 </itemizedlist>
 
 <para>
-CLONE PARENT sets the real parent to the parent of the caller. This is useful for 
+CLONE_PARENT sets the real parent to the parent of the caller. This is useful for 
 threads because if thread A creates thread B we want thread B to be parented to the 
-parent of the whole thread group. CLONE THREAD does exactly the same thing as 
-CLONE PARENT, CLONE VM and CLONE SIGHAND, rewrites PID to be the same as 
-PID of the caller, sets exit signal to be none and enters the thread group. CLONE SETTLS 
-sets up GDT entries for TLS handling. CLONE * *TID this set of flags sets/clear user
+parent of the whole thread group. CLONE_THREAD does exactly the same thing as 
+CLONE_PARENT, CLONE_VM and CLONE_SIGHAND, rewrites PID to be the same as 
+PID of the caller, sets exit signal to be none and enters the thread group. CLONE_SETTLS 
+sets up GDT entries for TLS handling. CLONE_*_*TID this set of flags sets/clear user
 supplied address to TID or 0.
 </para>
 
 <para>
-As you can see the CLONE THREAD does most of the work and doesn.t seem to fit the 
+As you can see the CLONE_THREAD does most of the work and doesn.t seem to fit the 
 scheme very well. The original intention is unclear (even for authors, according to comments 
 in the code) but I think originally there was one threading flag which was then parcelled 
 among many other flags but this separation was never fully finished. Its also unclear what 
@@ -614,7 +614,7 @@
 </para>
 
 <para>
-The CLONE SIGNAL is defined like 
+The CLONE_SIGNAL is defined like 
 
 #define CLONE_SIGNAL (CLONE_SIGHAND | CLONE_THREAD) 
 
@@ -831,13 +831,13 @@
 
 <itemizedlist>
 <listitem><para>
-1. 0. spinning
+1. spinning
 </para></listitem>
 <listitem><para>
-2. 1. blocking
+2. blocking
 </para></listitem>
 <listitem><para>
-3. 2. sleeping
+3. sleeping
 </para></listitem>
 </itemizedlist>
  
@@ -1077,7 +1077,7 @@
 path for a given (locked) vnode. This process is unreliable but works just fine for the most 
 common cases. The unreliability is because it relies on VFS cache (it doesn.t traverse the 
 on medium structures), it doesn.t work with hardlinks etc. This routine is used in several 
-places in the &linux;ulator.
+places in the linuxulator.
 </para>
 
 	</sect4>
@@ -1096,19 +1096,19 @@
 vn unlock - unlocks a vnode
 </para></listitem>
 <listitem><para>
-VOP READDIR - reads a directory referenced by a vnode
+VOP_READDIR - reads a directory referenced by a vnode
 </para></listitem>
 <listitem><para>
-VOP GETATTR - gets attributes of a file or a directory referenced by a vnode
+VOP_GETATTR - gets attributes of a file or a directory referenced by a vnode
 </para></listitem>
 <listitem><para>
-VOP LOOKUP - looks up a path to a given directory
+VOP_LOOKUP - looks up a path to a given directory
 </para></listitem>
 <listitem><para>
-VOP OPEN - opens a file referenced by a vnode
+VOP_OPEN - opens a file referenced by a vnode
 </para></listitem>
 <listitem><para>
-VOP CLOSE - closes a file referenced by a vnode
+VOP_CLOSE - closes a file referenced by a vnode
 </para></listitem>
 <listitem><para>
 vput - decrement the use count for a vnode and unlock it
@@ -1152,7 +1152,7 @@
 system. It first describes the machine dependant part talking about how and where interaction between userland and kernelland is implemented. It talks about syscalls, signals, 
 ptrace, traps, stack fixup. This part covers only i386 but is written generally so no other 
 architecture should differ much. The next part is the machine independant part of the 
-&linux;ulator. This part covers i386 and ELF handling only. A.out is obsolete and untested. 
+linuxulator. This part covers i386 and ELF handling only. A.out is obsolete and untested. 
 </para>
 
     <sect2>
@@ -1182,7 +1182,7 @@
 	<title>Syscall writing</title>
 
 <para>
-Every syscall implemented in the &linux;ulator must have its prototype with various flags in 
+Every syscall implemented in the linuxulator must have its prototype with various flags in 
 the syscalls.master file. The form of the file is: 
 </para>
 
@@ -1239,7 +1239,7 @@
 </para>
 
 <para>
-As you can see linux fork is implemented in &linux;ulator itself so the definition is of 
+As you can see linux fork is implemented in linuxulator itself so the definition is of 
 STD type and has no argument which is exhibited by the dummy argument structure. On 
 the other hand close is just an alias for real &os; close so it has no linux arguments 
 structure associated and in the system entry table it.s not prefixed with linux as it calls the 
@@ -1336,7 +1336,7 @@
 </para>
 
 <para>
-Ptrace implementation in &linux;ulator has some known weaknesses. There have been 
+Ptrace implementation in linuxulator has some known weaknesses. There have been 
 panics seen when using strace (which is a ptrace consumer) in the linuxulator environment. 
 Also PT SYSCALL is not implemented. 
 </para>
@@ -1382,7 +1382,7 @@
 <para>
 The RTLD run-time link-editor expects so called AUX tags on stack during an execve so 
 a fixup must be done to ensure this. Of course every RTLD system is different so the 
-emulation layer must provide its own stack fixup routine to do this. So does &linux;ulator. 
+emulation layer must provide its own stack fixup routine to do this. So does linuxulator. 
 The elf linux fixup() simply copies out AUX tags to the stack and adjusts the stack of the 
 user space process to point right after those tags. So RTLD happily works. 
 </para>
@@ -1410,7 +1410,7 @@
     <title>&linux; emulation layer -MI part</title>
 
 <para>
-This chapter talks about machine independent part of the &linux;ulator. It
+This chapter talks about machine independent part of the linuxulator. It
 covers the emulation infrastructure needed for &linux; 2.6 emulation, the
 thread local storage (TLS) implementation (on i386) and futexes. Then we
 talk briefly about some syscalls.
@@ -1441,7 +1441,7 @@
 </para>
 
 <para>
-The &os; &linux;ulator implementation approaches the NPTL in three main areas. 
+The &os; linuxulator implementation approaches the NPTL in three main areas. 
 The TLS, futexes and PID mangling which is meant to simulate the &linux; threads. Further 
 sections describe each of these areas. 
 </para>
@@ -1566,7 +1566,7 @@
 Because of the described different view know what a process ID and thread ID is between 
 &os; and &linux; we have to translate the view somehow. We do it by PID mangling. 
 This means that we fake what a PID (=TGID) and TID (=PID) is between kernel and 
-userland. The rule of thumb is that in kernel (in &linux;ulator) PID = PID and TGID 
+userland. The rule of thumb is that in kernel (in linuxulator) PID = PID and TGID 
 = shared->group pid and to userland we present PID = shared-.group pid and TID = 
 proc->p pid. The PID member of linux emuldata structure is a &os; PID. 
 </para>
@@ -1852,27 +1852,27 @@
 
 <itemizedlist>
 <listitem><para>
-FUTEX WAIT
+FUTEX_WAIT
 </para></listitem>
 <listitem><para>
-FUTEX WAKE
+FUTEX_WAKE
 </para></listitem>
 <listitem><para>
-FUTEX FD
+FUTEX_FD
 </para></listitem>
 <listitem><para>
-FUTEX REQUEUE
+FUTEX_REQUEUE
 </para></listitem>
 <listitem><para>
-FUTEX CMP REQUEUE
+FUTEX_CMP_REQUEUE
 </para></listitem>
 <listitem><para>
-FUTEX WAKE OP
+FUTEX_WAKE_OP
 </para></listitem>
 </itemizedlist> 
 
 	<sect4>
-	  <title>FUTEX WAIT</title>
+	  <title>FUTEX_WAIT</title>
 
 <para>
 This operation verifies that on address uaddr the value val is written. If not EWOULDBLOCK is returned, otherwise the thread is queued on the futex and it is suspended. If the 
@@ -1883,7 +1883,7 @@
 	</sect4>
 
 	<sect4>
-	  <title>FUTEX WAKE</title>
+	  <title>FUTEX_WAKE</title>
 
 <para>
 This operation takes a futex at uaddr and wakes up val first futexes queued on this futex. 
@@ -1892,7 +1892,7 @@
 	</sect4>
 
 	<sect4>
-	  <title>FUTEX FD</title>
+	  <title>FUTEX_FD</title>
 
 <para>
 This operations associates a file descriptor with a given futex.
@@ -1901,7 +1901,7 @@
 	</sect4>
 
 	<sect4>
-	  <title>FUTEX REQUEUE</title>
+	  <title>FUTEX_REQUEUE</title>
 
 <para>
 This operation takes val threads queued on futex at uaddr and wakes them up, and takes 
@@ -1911,17 +1911,17 @@
 	</sect4>
 
 	<sect4>
-	  <title>FUTEX CMP REQUEUE</title>
+	  <title>FUTEX_CMP_REQUEUE</title>
 
 <para>
-This operation does the same as FUTEX REQUEUE but it checks that val3 equals to val 
+This operation does the same as FUTEX_REQUEUE but it checks that val3 equals to val 
 first.
 </para> 
 
 	</sect4>
 
 	<sect4>
-	  <title>FUTEX WAKE OP</title>
+	  <title>FUTEX_WAKE_OP</title>
 
 <para>
 This operation performs an atomic operation on val3 (which contains coded some other 
@@ -1930,31 +1930,31 @@
 </para>
 
 <para>
-The operations implemented in the FUTEX WAKE OP:
+The operations implemented in the FUTEX_WAKE_OP:
 </para>
 
 <itemizedlist>
 <listitem><para>
-FUTEX OP SET
+FUTEX_OP_SET
 </para></listitem>
 <listitem><para>
-FUTEX OP ADD
+FUTEX_OP_ADD
 </para></listitem>
 <listitem><para>
-FUTEX OP OR
+FUTEX_OP_OR
 </para></listitem>
 <listitem><para>
-FUTEX OP ANDN
+FUTEX_OP_ANDN
 </para></listitem>
 <listitem><para>
-FUTEX OP XOR
+FUTEX_OP_XOR
 </para></listitem>
 </itemizedlist>
 
 <para>
 Note that there is no val2 parameter in the futex prototype. The val2 is taken from the 
-struct timespec *timeout parameter for operations FUTEX REQUEUE, FUTEX CMP REQUEUE 
-and FUTEX WAKE OP.
+struct timespec *timeout parameter for operations FUTEX_REQUEUE, FUTEX_CMP_REQUEUE 
+and FUTEX_WAKE_OP.
 </para>
 
 	</sect4>
@@ -1991,7 +1991,7 @@
 </para>
 
 	<sect4>
-	  <title>futex get/put</title>
+	  <title>futex_get/put</title>
 
 <para>
 A futex is obtained using the futex get function that searches a linear list of futexes and 
@@ -2003,7 +2003,7 @@
 	</sect4>
 
 	<sect4>
-	  <title>futex sleep</title>
+	  <title>futex_sleep</title>
 
 <para>
 When a futex queues a thread for sleeping it creates a working proc structure and puts this 
@@ -2018,7 +2018,7 @@
 	</sect4>
 
 	<sect4>
-	  <title>futex wake</title>
+	  <title>futex_wake</title>
 
 <para>
 Waking up a thread sleeping on a futex is performed in the futex wake function. In this 
@@ -2033,7 +2033,7 @@
 	</sect4>
 
 	<sect4>
-	  <title>futex wake op</title>
+	  <title>futex_wake_op</title>
 
 <para>
 The WAKE OP operation is quite complicated. First we obtain two futexes at addresses 
@@ -2075,17 +2075,6 @@
 </para>
 
 	</sect4>
-
-	<sect4>
-	  <title>Futex problems</title>
-
-<para>
-Currently the futex implementation in &os; suffers some problems. First it is locked 
-by Giant and second we don.t pass futex testing program. It looks like the locking under 
-contention is wrong. Work is ongoing to fix this.
-</para>
-
-	</sect4>
       </sect3>
     </sect2>
 
@@ -2108,7 +2097,7 @@
 is to be performed, is. When filename parameter is absolute the dirfd is ignored but when 
 the path to the file is relative, the dirfd comes to play. The dirfd is a directory relative to 
 which the relative pathname is checked. The dirfd is a file descriptor of some directory or 
-AT FDCWD. So for example the openat() syscall can be like this:
+AT_FDCWD. So for example the openat() syscall can be like this:
 </para>
 
 <para>
@@ -2143,7 +2132,7 @@
 
 <para>
 The implementation is done by altering the namei routine (described above) to take additional parameter dirfd in its nameidata structure which specifies the starting point of the 
-pathname lookup instead of using CWD every time. The dirfd resolution from file descriptor number to a vnode is done in native *at syscalls. When dirfd is AT FDCWD the dvp 
+pathname lookup instead of using CWD every time. The dirfd resolution from file descriptor number to a vnode is done in native *at syscalls. When dirfd is AT_FDCWD the dvp 
 entry in nameidata structure is null but when dirfd is a different number we obtain a file 
 for this file descriptor, check whether this file is valid and if there.s vnode attached to it 
 then we get a vnode. Then we check this vnode for being a directory. In the actual namei 
