add architecture description

doc/kernel.txt

@@ -0,0 +1,151 @@
+This file describes the kernel architecture.  It does no go into detail on all
+the fields of structs; for that, refer to the source code.
+
+# Overview
+
+Iris is an operating system.  The kernel should be called "the Iris kernel",
+but sometimes it is simply called "Iris".  If there can be confusion, the terms
+"kernel" and "userspace" are used to clarify.
+
+Iris uses a capability based microkernel.  Being a microkernel means that most
+parts that would be part of a monolithic kernel are not part of the Iris
+kernel, but of the Iris userspace.  Being capability based means that there is
+no public dictionary of running processes; in order to communicate with another
+process, the caller must have received a capability to them.
+
+
+# First class objects
+
+First class objects are implemented by the kernel.  They can be used through
+capabilities.
+
+- Cap: a single capability.  Can be invoked and passed to others.
+- Caps: storage container for a fixed number of Cap objects.  Every Thread has
+  at least one of these so it can communicate with the kernel, its parent, and
+  other processes.
+- Receiver: an object that allows to create Cap objects.  When those are
+  invoked, the Receiver's listener receives the message.
+- Thread: an execution context.  On creation, a number of slots is specified
+  and space is reserved for that many Caps pointers.  Only Cap objects in those
+  Caps can be invoked from the thread.
+- Page: a single page of memory, always 4kB.  A Page can be mapped in a Memory
+  and then accessed by a Thread.
+- Memory: Everything[*] needs a Memory object to be stored in.  In addition to
+  storing first class objects, a Memory can own Page objects and map them.  A
+  mapped page is accessible for running Threads that stored in the Memory.
+- List: Helper for implementing a list of Cap objects, which are stored by the
+  caller.  A List allows servers to keep a list of clients without paying for
+  its storage.  This prevents a denial of service attack.  Each item is stored
+  with a code that is set and only accessible by the List owner.
+- ListItem: an item in a List object.
+
+[*] There is of course one exception to the rule that everything is stored in a
+    Memory.  Everything is a tree, with Memory objects as nodes and all other
+    objects as leaves.  The root of the tree is not stored in anything.  This
+    node is called the "top Memory".
+
+Example: A new process consists of a Memory with one or more mapped Page
+	objects that hold the code and data, a Receiver, a Thread, and a Caps
+	that contains a Cap for each of those objects, plus one for its parent
+	process.  That Caps is stored in slot 0.
+
+Note that the kernel provides system calls through capabilities.  If a thread
+doesn't hold the capability, it cannot make the system call.  The parent Cap is
+used to request access to other processes, or devices.  The Thread has no way
+to know if it is talking to the thing it requested, or something that simulates
+it.  That is intentional; Threads should not be able to detect that they are
+being debugged.
+
+
+# Capability invocations
+
+When a Cap is invoked, a message is sent to the Receiver that created it (or,
+if it was created by the kernel, to the kernel).  This message contains three
+64 bit numbers (which are usually treated as two 32 bit numbers each) and two
+Cap objects.  Two of the numbers, named d0 and d1, are passed with the
+invocation, the third one is named protected_data and is defined when the Cap
+is created.  The owner of the Cap cannot see or change protected_data; it is
+the target's way of recognizing who's sending the message.
+
+The Cap objects in the message are called arg and reply.  By convention, a call
+that requires a reply passes a Cap for it, which will be invoked with the
+reply.  However, this is only a convention; if a program wants, it can use both
+arg and reply as regular arguments if no reply is required.  Normally a Caps is
+passed in arg if more than one Cap should be sent though.
+
+Cap objects can be passed around.  The target of the invocation cannot see if
+the original recipient is calling, or some other process that was given access.
+The Receiver does allow to revoke a Cap; after this, any invocation no longer
+sends a message to the Receiver.  When sending a Cap, a flag specifies whether
+it is mapped (the default), or copied.  A mapped Cap is revoked when its source
+is revoked; a copy is not.  To give a Cap to another process and then drop it,
+it must be copied.  Otherwise the new Cap is immediately revoked.
+
+
+# Interrupts
+
+Interrupts are handled by one or a few interrupt handlers.  In a microkernel,
+it would be ideal to let userspace handle them, but that is not reasonable
+given the hardware architecture.  However, it is possible for the kernel to
+find out who should handle it, and then pass it to userspace.  In Linux-terms:
+the top half is in kernel space, but the bottom half is not.  (Note that those
+two halves are highly asymmetrical; the top half is very small, the bottom half
+can be very large.)  So this is what Iris does.  A process can register as an
+interrupt handler, the kernel masks the interrupt when it arrives, so it isn't
+immediately triggered again, enables all interrupts and sends a message to the
+registered process.  It will normally clear the interrupt condition and
+reregister itself as the interrupt handler.  The reregistration is required to
+avoid queueing of interrupts; if they are not reregistered, they are no longer
+handled.
+
+
+# Userspace
+
+When the system boots, the kernel is started with its first process.  This
+process sets up userspace.  Unlike Linux init systems, the first process does
+not continue running; it is hard to change (because the filesystem is not yet
+accessible) and so it must be as simple as possible.
+
+As part of the startup, drivers for built in devices are started.  These are
+regular userspace programs, most of them handle interrupts and all of them have
+access to memory mapped I/O.  Note that this means they are just as critical as
+the kernel; in a monolithical system, only the kernel needs to be ultimately
+trusted (if it is compromised, all is lost).  With a microkernel, it's both the
+kernel and some parts of userspace.  The total amount of trusted code is likely
+smaller in a microkernel design, because it is easier to split parts that don't
+need to be critical into their own process.
+
+A user session is a process which can start other processes and switch between
+them.  For this, it contains the following components:
+
+- A bag of device Cap objects, which can be mapped to the active process (and
+  revoked when they are deactivated).  What's in the bag can change.  For
+  example, if the user wants sound to continue playing while switching to
+  another user, the sound Cap must not be in the bag.
+- An interface for task switching: when the user makes a system request (which
+  is some dedicated hardware, such as a button), the active process is
+  deactivated and the session itself (or a designated helper) is activated.  It
+  allows switching to a different process, or starting a new one, or stopping
+  or ending running processes.  The session can also allow communication
+  between certain processes.  (The processes need to cooperate to actually make
+  the link; they ask the session for a link of a certain type (for example, a
+  file system) and the session responds with the Cap or an error.
+- There is a list of things that can be started; an important one is a shell,
+  which allows control over the session.  In other words, the shell is able to
+  start and end other processes, make and break communication links, and define
+  which programs can be started.
+
+
+# Multi user support
+
+For multi user support, a login manager is required which can start user
+sessions and switch between them.  This is very similar to what a user session
+does, and so the same process is used for it.  Just a few changes are required,
+and those can be implemented by choosing different helper programs.
+
+The login manager lets the user select an identity to log in.  The login
+program itself is run by the user session, so that users can change the way
+they log in without asking the administrator to set it up for them.  For
+example, one user may set up to only allow logging in with a physical crypto
+device, while a guest login may be set up that doesn't require credentials at
+all.