Microcosm

(Microcosm is not yet implemented, so this description may change)

Microcosm is an OS (of sorts) designed to run on top of any other OS. It has its own system call layer, providing a single target ABI for binaries. That system call layer is implemented in terms of lower level (host-specific) system calls, and so must to a certain degree be reimplemented per OS.

At its core, Microcosm has only three intrinsic functions: It can load (and run) ELF binaries, manage multiple threads, and handle syscalls. The only syscalls provided by the core are:
 * -1: Register syscall
 * -2: Get syscall
 * -3: Deregister syscall
 * -8: Expand thread structure
 * -9: Get current thread structure
 * -16: Spawn thread
 * -17: Initialize thread
 * -18: Kill thread
 * -19: Join thread (wait)
These system calls are clearly divided into three groups.

==Syscall registration==
The core syscalls -1, -2 and -3 control the registration of system calls. Microcosm allows syscalls to be added at runtime, and these three builtin syscalls allow that:

===Register syscall===
{{syscall(-1, callnumber, functionptr, 0, 0)}}
Syscall -1 registers a system call. The system call 'callnumber' is associated with the function 'functionptr'. The previous value is returned, or NULL if the system call was unassigned. This system call cannot fail non-catastrophically.

===Get syscall===
{{syscall(-2, callnumber, 0, 0, 0)}}
Syscall -2 gets the current association of a system call. The function pointer is returned, or NULL if the system call is unassigned.

===Deregister syscall===
{{syscall(-2, callnumber, 0, 0, 0)}}
Syscall -3 deregisters the given system call. The return value is always 0, and this system call cannot fail non-catastrophically.

==Other core system calls==
(To be documented later)

==Modules==
When Microcosm is started, before loading a binary, it loads the ELF file microcosm-modules.so . That ELF shared object file should depend on a number of other modules, which will all be loaded. The initialization code for the modules will generally register system calls, expand the thread data structure, and do any other initialization steps potentially necessary.

Usually, these modules will be implemented with an 'in-microcosm' component depending on an 'out-of-microcosm' component. Microcosm's ELF loader allows dependencies on external shared libraries (or DLLs on Windows) by registering dependencies in the guest .so named (e.g.) libhost_libc.so.6 (for libc.so.6 on the host).

==FOO==
More documentation to come!