System call implementations documentation improvements

doc/syscalls/README.md

@@ -56,8 +56,13 @@ JINUE_ENOSYS (in `arg1`).
 ### System Call Registers
 
 During a system call, information is passed back and forth between user space
-and the microkernel through four pointer-sized logical registers named `arg0` to
-`arg3`.
+and the microkernel through four pointer-sized logical registers named `arg0`
+to `arg3`.
+
+The mapping of these four system call registers to actual CPU registers is
+architecture dependent. However, the system call specification given in terms
+arguments and return values set in the system call registers is independent of
+the architecture.
 
 ### System Call Implementations
 

doc/syscalls/implementations.md

@@ -1,45 +1,52 @@
 # System Call Implementations
 
-The microkernel supports the following implementations to invoke system calls.
-Not all implementations are available on all CPUs. On initialization, before
-invoking any system call, an application should look at the value of auxiliary
-vector number 8 (called `JINUE_AT_HOWSYSCALL`) to determine the best supported
-system call implementation:
+## Overview and Register Mapping
+
+On 32-bit x86 there are three system call implementations: one interrupt-based
+implementation and two that use different fast system call instructions.
+
+All three implementations use the same system call register mappings:
+
+* `arg0` maps to CPU register `eax`.
+* `arg1` maps to CPU register `ebx`.
+* `arg2` maps to CPU register `esi`.
+* `arg3` maps to CPU register `edi`.
+
+The microkernel uses auxiliary vector number 8 (called `JINUE_AT_HOWSYSCALL`)
+to inform the user space loader and initial process of the implementation it
+should use. (See the [Initial Process Execution
+Environment](../init-process.md) for detail.)
+
+The value of this auxiliary vector will be set to one of the following:
 
 * 0 for the interrupt-based implementation
 * 1 for the SYSCALL/SYSRET (fast AMD) implementation
 * 2 for the SYSENTER/SYSEXIT (fast Intel) implementation
 
 ## Interrupt-Based Implementation
 
-A system call can be invoked by generating a software interrupt to interrupt
-vector 128 (80h). The argument registers are mapped as follow:
+A system call is invoked by setting the correct arguments in the system call
+registers and then generating a software interrupt to interrupt vector 128
+(80h).
 
-* `arg0` maps to CPU register `eax`.
-* `arg1` maps to CPU register `ebx`.
-* `arg2` maps to CPU register `esi`.
-* `arg3` maps to CPU register `edi`.
+On return, the return values are set in the system call registers.
 
 ## SYSCALL/SYSRET (Fast AMD) Implementation
 
-A system call can be invoked by executing the `SYSCALL` CPU instruction.
+A system call is invoked by setting the correct arguments in the system call
+registers and then executing the `SYSCALL` CPU instruction.
 
-* `arg0` maps to CPU register `eax`.
-* `arg1` maps to CPU register `ebx`.
-* `arg2` maps to CPU register `esi`.
-* `arg3` maps to CPU register `edi`.
+On return, the return values are set in the system call registers.
 
-This system call is not supported by all CPUs.
+This implementation is not supported by all CPUs. Only use this system call
+implementation if the `JINUE_AT_HOWSYSCALL` auxiliary vector is set to 1.
 
 ## SYSENTER/SYSEXIT (Fast Intel) Implementation
 
-A system call can be invoked by executing the `SYSENTER` CPU instruction.
+A system call is invoked by setting the correct arguments in the system call
+registers and then executing the `SYSENTER` CPU instruction.
 
-* `arg0` maps to CPU register `eax`.
-* `arg1` maps to CPU register `ebx`.
-* `arg2` maps to CPU register `esi`.
-* `arg3` maps to CPU register `edi`.
-* The return address must be set in the `ecx` CPU register.
-* The user stack pointer must be set in the `ebp` CPU register.
+On return, the return values are set in the system call registers.
 
-This system call is not supported by all CPUs.
+This implementation is not supported by all CPUs. Only use this system call
+implementation if the `JINUE_AT_HOWSYSCALL` auxiliary vector is set to 2.