From 320a9ab70b3433ee073d8a9f9dae9a6b590521e0 Mon Sep 17 00:00:00 2001 From: "Tate, Hongliang Tian" Date: Mon, 8 Aug 2022 13:33:34 -0700 Subject: [PATCH] Add README for src/ --- src/README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 src/README.md diff --git a/src/README.md b/src/README.md new file mode 100644 index 000000000..56438e95f --- /dev/null +++ b/src/README.md @@ -0,0 +1,34 @@ +# KxOS Source Code + +## Code organization + +The codebase is organized as a number of Rust crates. + +* The `kxos` crate assembles all other crates into a runnable OS kernel image. +This is the only binary crate; all other crates are libraries. +* The `kxos-frame` crate constitutes the main part of the KxOS framework, +providing a minimal set of _safe_ abstractions that encapsulates _unsafe_ Rust +code to deal with hardware resources like CPU, memory, and interrupts. +* The `kxos-frame-*` crates complement `kxos-frame` by providing more _safe_ +types, APIs, or abstractions that are useful to specific aspects of the KxOS. +* The `kxos-std` crate is KxOS's equivalent of Rust's std crate, although +their APIs are quite different. This crate offers an extensive set of +high-level safe APIs that are widely used throughout the OS code above the +framework (i.e., the crates described below). +* The rest of `kxos-*` crates implement most of the functionalities of KxOS, e.g., +Linux syscall dispatching, process management, file systems, network stacks, +and device drivers. + +## Privilege separation + +KxOS is a _framekernel_, separating the entire OS into two halves: +the _privileged_ half (so-called "frame") and the _unprivileged_ half. +Only the privileged half is allowed to include any _unsafe_ Rust code. And +it is the privileged half's responsibility to encapsulate the _unsafe_ Rust +code in _safe_ API so that most of the OS functionalities can be implemented +with safe Rust in the unprivileged half. + +This philosophy of privilege separationn is also reflected in the code organization. + +* The privileged half consists of `kxos`, `kxos-frame`, and `kxos-frame-*` crates. +* The unprivileged half consists of `kxos-std` and the rest `kxos-*` crates.