1<!--
2     Copyright 2016, Data61
3     Commonwealth Scientific and Industrial Research Organisation (CSIRO)
4     ABN 41 687 119 230.
5
6     This software may be distributed and modified according to the terms of
7     the BSD 2-Clause license. Note that NO WARRANTY is provided.
8     See "LICENSE_BSD2.txt" for details.
9
10     @TAG(D61_BSD)
11  -->
12
13RefOS Repository
14================
15
16This is the git repository for RefOS.
17This repository is meant to be used as part of a Google repo setup. Instead of cloning it directly,
18please go to the following repository and follow the instructions there:
19
20    https://github.com/seL4/refos-manifest
21
22RefOS is currently supported on iMX3.1 KZM, iMX6 Sabre Lite and ia32 hardware platforms and
23on qemu-ARM kzm and qemu-i386 ia32.
24
25Overview
26--------
27
28The repository is organised as follows.
29
30 * [`impl/apps`](impl/apps/): RefOS system and userland applications
31    * [`selfloader`](impl/apps/selfloader/): Bootstrap application, which is responsible for starting
32      user processes.
33    * [`process_server`](impl/apps/process_server/): The process server, which runs as the root
34      task and provides process and thread abstraction and initialises the entire system.
35    * [`file_server`](impl/apps/file_server/): The cpio file server, which stores files and
36      executables in a cpio archive and exposes them via a dataspace interface.
37    * [`console_server`](impl/apps/console_server/): The console server, a system process which acts
38      as the console device driver and manages serial input and output and EGA text mode output.
39    * [`timer_server`](impl/apps/timer_server/): The timer server, a userland driver process which
40      manages the timer device and provides timer get time and sleep functionality.
41    * [`terminal`](impl/apps/terminal/): The interactive terminal application.
42    * [`test_os`](impl/apps/test_os/): RefOS operating system level test suite, which tests the
43      operating system environment.
44    * [`test_user`](impl/apps/test_os/): RefOS user-level test application, which is responsible for
45      testing the operating system user environment.
46    * [`snake`](impl/apps/snake/): Example snake game.
47    * [`tetris`](impl/apps/tetris/): Example tetris game.
48    * [`nethack`](impl/apps/nethack/): Port of Nethack 3.4.3 roguelike game.
49 * [`impl/libs`](impl/libs/): RefOS system and userland applications
50    * [`libdatastruct`](impl/libs/libdatastruct/): RefOS library that provides simple C data structures such as
51      vectors, hash tables and allocation tables.
52    * [`librefos`](impl/libs/librefos/): RefOS user and server shared definitions, RPC specifications and
53      generated stubs and low level helper libraries.
54    * [`librefossys`](impl/libs/librefossys/): RefOS library that implements some POSIX system calls using low-level
55      RefOS and thus allows the C library to work. This directory is intended to simplify RefOS 
56      userland applications and facilitate porting.
57 * [`impl/docs`](impl/docs/): RefOS doxygen code documentation.
58 * [`design`](design/): RefOS protocol design document.
59
60Suggested Future Work
61---------------------
62
63The following is suggested future work that interested open-source developers could implement:
64
65 * Future Work 1: modify how the process server creates and starts processes and threads (see 'Future Work 1' in code)
66 * Future Work 2: fix issue where calls to assert_fail() result in infinite recursion on x86 architecture (see 'Future Work 2' in code)
67 * Future Work 3: modify how the selfloader bootstraps user processes (see 'Future Work 3' in code)
68 * Future Work 4: remove explicit reference to system call table in processes that the process server creates (see 'Future Work 4' in code)
69 * Future Work 5: set up muslc's errno in RefOS (see 'Future Work 5' in code)
70 * Future Work 6: get ia32_screen_debug_defconfig and ia32_screen_release_defconfig default configurations running with new seL4 API
71 * Future Work 7: get Nethack running with new seL4 API
72
73License
74-------
75
76The files in this repository are released under standard open source
77licenses. RefOS code is released under the BSD license where possible and GPL for some
78external software. Please see the individual file headers and
79[`LICENSE_BSD2.txt`](LICENSE_BSD2.txt) for details.
80
81Please note that RefOS is intended to be sample code and is not high assurance software.
82We are not reponsible for any consequences if you choose to deploy this software in
83production.
84