1/*! @file */
2
3/*! @page design Design Overview
4
5@section Dataspace
6
7The overall design of RefOS revolves around the abstraction of a dataspace and the interfaces needed to manage them.
8
9A dataspace is a memory space and is represented by a stream of bytes. Dataspaces may represent entities such as:
10<ul>
11    <li> A physical file on disk (e.g. unix /bin/sh) </li>
12    <li> A hardware device (e.g. unix /dev/hda1) </li>
13    <li> A bit of anonymous memory (e.g. physical RAM) </li>
14    <li> A stream of bytes (e.g. unix /dev/urandom) </li>
15</ul>
16
17@image html dataspace_example.png "Figure 1 - Example Dataspace Setup"
18
19Dataspace servers (dataservers) implement the dataspace protocol interface and provide a dataspace abstraction service to clients. For example, in Figure 1, a portion of dataspace A is mapped into a client's memory window (client's virtual memory). When the client reads this memory, the client effectively reads the content in dataspace A. Another aspect of this figure is that dataspace A could initialise dataspace B with dataspace A's contents.
20
21@section Interfaces
22
23The two main interfaces in RefOS are the process server and the data server. In addition to these two interfaces, there are a number of less major (but still important) interfaces, such as the name server interface, that provide additional functionality.
24
25<h3>Process Server Interface</h3>
26
27The process server interface creates process abstractions. The process server interface provides methods for:
28<ul>
29    <li> Starting, ending and managing processes and threads </li>
30    <li> Creating, deleting and managing memory windows </li>
31    <li> Handling and delegating kernel page faults </li>
32</ul>
33
34<h3>Data Server Interface</h3>
35
36The main goal of the data server interface is to provide dataspace abstraction. The data server interface provides methods for:
37<ul>
38    <li> Creating, deleting and managing dataspaces </li>
39    <li> Mapping dataspaces to memory windows and thus allowing access to the contents of dataspaces </li>
40    <li> Initialising dataspaces with the contents of other dataspaces </li>
41    <li> Establishing pager services to map memory frames for memory windows mapped to dataspaces </li>
42</ul>
43
44@section Startup
45@image html startup.png "Figure 2 - RefOS Boot Protocol"
46
47In the RefOS boot protocol, the process server is started and initialises itself. Once the process server is running, the process server uses its interal ELF loader to start the console server, the file server and then the selfloader.
48
49@image html elfload.png "Figure 3 - ELF Loading"
50
51The selfloader is a process that the process server spawns, and it is used for starting user processes. The selfloader runs in the same address space as the process it is starting. The selfloader establishes a connection to the file server, reads the ELF executable headers and then creates memory windows mapped to the bytes of the file content served by the file server. The selfloader also sets up a memory window for the stack pointer. After performing these tasks, the selfloader jumps to the entry point of the executable which causes a page fault on the first instruction read.
52
53@section page_faults Page Faults
54@image html fault.png "Figure 4 - Page Fault Handling"
55
56When a page fault occurs in a client program, the process server receives a page fault notification from the kernel. Since the selfloader initialised the memory windows for the client, the window that the client faulted in is data mapped to one of the process server's own dataspaces (representing anonymous memory).
57
58The process server then notifies the file server that a page fault occurred. Having received the notifiction, the file server registers the fault event, handles the fault event and replies via interprocess communication. The file server provides any data that the process server asked for in its notification such as the window capability, the window offset and the memory page address.
59
60The process server then copies the contents of the memory page to its own RAM dataspace and replies to the faulting message with the contents of the memory page, which causes the client to resume execution.
61
62@section Dispatcher
63
64RefOS's servers use a dispatcher algorithm to handle messages that they receive.
65
66@image html dispatcher.png "Figure 5 - Dispatcher Design Overview"
67
68The best way to illustrate the RefOS dispatcher algorithm is through an example. Say a server receives a message. The message is analysed by dispatcher 1. If dispatcher 1 determines that the message is the type of message that it handles, dispatcher 1 handles the message. Otherwise, dispatcher 1 passes the message onto dispatcher 2. If dispatcher 1 passes the message onto dispatcher 2, dispatcher 2 also analyses the message and determines whether the message is the type of message that it handles. Just like dispatcher 1, dispatcher 2 either handles the message or passes the message onto dispatcher 3. This algorithm is repeated until the final dispatcher if necessary. If a dispatcher determines that a message is the correct message type for it to handle, the dispatcher handles the message by calling the appropriate handler function depending on the message contents. Of course, if a dispatcher handles a message, the message is now processed and is not passed onto the next dispatcher. If the final dispatcher determines that the message is not the correct message type for it to handle, the server produces an error message.
69
70Note that in implementation each server does not necessarily have exactly four dispactchers.
71*/
72