qiurui
/
asterinas
mirror of https://github.com/asterinas/asterinas.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update the README to describe code organization

This commit is contained in:
Tate, Hongliang Tian 2023-04-17 13:11:47 +08:00
parent 53b8acf6f6
commit 7e1584fca9
2 changed files with 105 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
README.md
View File

@ -4,7 +4,7 @@ Jinux is a _secure_, _fast_, and _general-purpose_ OS kernel, written in Rust an
Jinux is designed and implemented with an emphasis on security, rendering it highly attractive for usage scenarios where Linux ABI is indispensable, but Linux itself is deemed insecure given its sheer size of TCB and its nature of being memory unsafe. An instance of such usage is employing Jinux as the guest OS for VM TEEs (e.g., [AMD SEV](https://www.amd.com/en/developer/sev.html) and [Intel TDX](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-trust-domain-extensions.html)).
## What's unique about Jinux?
## What's unique about Jinux
Jinux is a _zero-cost_, _least-privilege_ OS kernel. A least-privilege OS is one that adheres to the principle of least privileges, which mandates that every unit (e.g., a subsystem, a module, a function, or even an object) of the OS has the minimum authority and permissions required to perform its tasks. This approach reduces the security risk associated with any single element's bugs or flaws. By "zero-cost", we means the same as in Rust's philosophy of zero-cost abstractions, which emphasizes that high-level abstractions (like those that enable least privilege principles) should be available to developers to use, but not come at the cost of performance. Thus, a zero-cost, least-privilege OS enhances its security without compromising its performance.
@ -14,18 +14,20 @@ Jinux is unique in practicing the principle of least privilege without sacrifici
1. The architectural level. Jinux is architected as a _framekernel_, where the entire OS resides in a single address space and unsafe Rust code is restricted to a tiny portion of the OS called Jinux Framework. The Framework exposes safe APIs to the rest of Jinux, which implements the most of OS functionalities in safe Rust code completely. Thanks to the framekernel architecture, Jinux's TCB for memory safety is minimized.
![Architecture](docs/src/images/arch_comparison.png)
2. The component level. Upon Jinux Framework is a set of OS components, each of which is responsible for a particular OS functionality, feature, or device. These OS components are Rust crates with two traits: (1) containing safe Rust code, as demanded by the framekernel architecture, and (2) being governed by Jinux Component System, which can enforce a fine-grained access control to their public APIs. The access control policy is specified in a configuration file and enforced at compile time, using a static analysis tool.
3. The object level. Jinux promotes the philosophy of _everything-is-a-capability_, which means all kernel resources, from files to threads, from virtual memory to physical pages, should be accessed through [capabilities](https://en.wikipedia.org/wiki/Capability-based_security). In Jinux, capabilities are implemented as Rust objects that are constrained in their creation, acquisition, and usage. One common form of capabilities is those with access rights. Wherever possible, access rights are encoded in types (rather than values) so that they can be checked at compile time, eliminating any runtime costs.
As a zero-cost, least-privilege OS, Jinux provides the best of both worlds: the performance of a monolithic kernel and the security of a microkernel. Like a monolithic kernel, the different parts of Jinux can communicate with the most efficient means, e.g., function calls and memory sharing. In the same spirit as a microkernel, the fundamental security properties of the OS depend on a minimum amount of code (i.e., Jinux Framework).
## How to build and test
## Build and test
While most code is written in Rust, the project-scope build process is governed
by Makefile. The following commands are intended for use on an Ubuntu server that has installed qemu-system-x86_64.
While most of the code is written in Rust, the project-scope build process is governed by Makefile. The following commands are intended for use on an Ubuntu server that has installed qemu-system-x86_64.
### Preparation
Before downloading source code, install and init Git LFS since the project manages binaries with Git LFS.
```bash
# 1. install git-lfs
@ -46,7 +48,8 @@ all developmennt tools are installed.
make setup
```
### build
### Build
Then, we can build the project.
```bash
make build
@ -58,6 +61,7 @@ make run
```
### Test
We can run unit tests and integration tests if building succeeds.
```bash
make test
@ -72,3 +76,99 @@ Then we can use the tool to check access control policy.
```bash
cargo component-check
```
## Code organization
The codebase of Jinux is organized as below.
* `boot/`: creating a bootable Jinux kernel image along with an initramfs image.
* `kernel/`: defining the entry point of the Jinux kernel.
* `framework/`: the privileged half of Jinux (allowed to use `unsafe` keyword)
* `jinux-frame`: providing the safe Rust abstractions for low-level resources like CPU, memory, interrupts, etc;
* `libs`: Privileged libraries.
* `services/`: the unprivileged half of Jinux (not allowed to use `unsafe` directly), implementing most of the OS functionalities.
* `comps/`: Jinux OS components;
* `libs/`: Jinux OS libraries;
* `jinux-std`: this is where system calls are implemented. Currently, this crate is too big. It will eventually be decomposed into smaller crates.
* `tests/`: providing integration tests written in Rust.
* `regression/`: providing user-space tests written in C.
* `docs/`: The Jinux book (needs a major update).
## Development status
Jinux is under active development. The list below summarizes the progress of important planned features.
* Technical novelty
- [X] Jinux Framework
- [X] Jinux Component System
- [X] Jinux Capabilities
* High-level stuff
* Process management
- [X] Essential system calls (fork, execve, etc.)
* Supported file formats:
- [X] ELF
- [X] Scripts (Shebang)
- [X] Process group
- [ ] Process credentials
* Thread management
- [X] Essential system calls (clone, futex, etc.)
* Scheduling
- [X] Essential system calls (yield, nanosleep, etc.)
* Sleeping
* Schedulers
- [ ] Scheduler framework
- [X] Round-robin scheduler
- [ ] Preemption
* Memory management
- [X] Essential system calls (mmap, munmap, etc.)
* Mapping types
- [X] Anonymous
- [X] File-backed
* Optimizations
- [X] On-demand paging
- [X] Copy-on-write
* File system
* Essential system calls
- [X] File I/O (read, write, etc.)
- [X] FS operations (create, unlink, etc.)
* VFS
- [X] The VFS framework
- [X] Dentry cache
- [X] Page cache
* File systems
- [X] Ramfs
- [X] Initramfs
- [X] Procfs
- [ ] Ext2/3/4
* Inter-process communication
* POSIX signals
- [X] Essential system calls (sigaction, sigreturn, kill, etc.)
- [ ] Pipe
* Network I/O
* I/O multiplexing
- [ ] poll
- [ ] select
- [ ] epoll
* Socket types
- [ ] TCP sockets
- [ ] Unix sockets
- [ ] UDP sockets
* Time and clocks
* Low-level stuff
* Devices
- [X] PCI
- [X] System time
- [X] Tty
- [X] Virtio-blk
- [ ] Virtio-net
- [ ] Device abstraction layer
* CPU archs
- [X] x86-64
- [ ] AMD SEV
- [ ] Intel TDX
- [ ] Arm
- [ ] RISC-V
* Misc
- [ ] Multi-core support
- [ ] User-mode development

34
kernel/README.md
View File

@ -1,34 +0,0 @@
# Jinux Source Code
## Code organization
The codebase is organized as a number of Rust crates.
* The `jinux` crate assembles all other crates into a runnable OS kernel image.
This is the only binary crate; all other crates are libraries.
* The `jinux-frame` crate constitutes the main part of the jinux framework,
providing a minimal set of _safe_ abstractions that encapsulates _unsafe_ Rust
code to deal with hardware resources like CPU, memory, and interrupts.
* The `jinux-frame-*` crates complement `jinux-frame` by providing more _safe_
types, APIs, or abstractions that are useful to specific aspects of the Jinux.
* The `jinux-std` crate is Jinux'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 `jinux-*` crates implement most of the functionalities of Jinux, e.g.,
Linux syscall dispatching, process management, file systems, network stacks,
and device drivers.
## Privilege separation
Jinux 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 `jinux`, `jinux-frame`, and `jinux-frame-*` crates.
* The unprivileged half consists of `jinux-std` and the rest `jinux-*` crates.