Samuka007/asterinas
1
0
Fork 0
mirror of https://github.com/asterinas/asterinas.git synced 2025-06-21 08:26:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Reformat the book in semantic line breaks

Browse Source
This commit is contained in:
Tate, Hongliang Tian
2024-01-26 09:44:06 +08:00
parent a3b6af458c
commit 844b673821
6 changed files with 187 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/src/framework/an-100-line-example.md
View File

@ -1,6 +1,8 @@
# Example: Writing a Kernel in About 100 Lines of Safe Rust
To give you a sense of how Asterinas Framework enables writing kernels in safe Rust, we will show a new kernel in about 100 lines of safe Rust.
To give you a sense of
how Asterinas Framework enables writing kernels in safe Rust,
we will show a new kernel in about 100 lines of safe Rust.
Our new kernel will be able to run the following Hello World program.
@ -29,7 +31,9 @@ The user program above requires our kernel to support three main features:
3. Handling the write system call;
4. Handling the exit system call.
A sample implementation of the kernel in safe Rust is given below. Comments are added to highlight how the APIs of Asterinas Framework enable safe kernel development.
A sample implementation of the kernel in safe Rust is given below.
Comments are added
to highlight how the APIs of Asterinas Framework enable safe kernel development.
```rust
#![no_std]

57
docs/src/introduction.md
View File

@ -4,7 +4,9 @@
<img src="images/logo_en.svg" alt="asterinas-logo" width="620"><br>
</p>
Welcome to the documentation for Asterinas, an innovative open-source project and community focused on developing cutting-edge Rust OS kernels.
Welcome to the documentation for Asterinas,
an open-source project and community
focused on developing cutting-edge Rust OS kernels.
## Book Structure
@ -12,32 +14,67 @@ This book is divided into five distinct parts:
#### [Part 1: Asterinas Kernel](kernel/)
Explore the modern OS kernel at the heart of Asterinas. Designed to leverage the full potential of Rust, Asterinas Kernel provides a high-fidelity Linux ABI compatibility. This means it can seamlessly replace Linux, offering enhanced safety and security.
Explore the modern OS kernel at the heart of Asterinas.
Designed to realize the full potential of Rust,
Asterinas Kernel implements Linux ABI in a safe and efficient way.
This means it can seamlessly replace Linux,
offering enhanced safety and security.
#### [Part 2: Asterinas Framework](framework/)
The Framework lays down a robust, minimalistic foundation essential for OS development. It's akin to Rust's `std` crate but crafted for the demands of _safe_ Rust OS development. Asterinas Kernel is built on this very Framework.
The Framework lays down a minimalistic, powerful, and solid foundation
for OS development.
It's akin to Rust's `std` crate
but crafted for the demands of _safe_ Rust OS development.
Asterinas Kernel is built on this very Framework.
#### [Part 3: Asterinas OSDK](osdk/guide/)
The OSDK is a command-line tool, streamlining the workflow to create, build, test, and run Rust OS projects that are built upon Asterinas Framework. Developed specifically for OS developers, it extends Rust's Cargo tool to better suite their specific needs. OSDK is instrumental in the development of Asterinas Kernel.
The OSDK is a command-line tool
that streamlines the workflow to
create, build, test, and run Rust OS projects
that are built upon Asterinas Framework.
Developed specifically for OS developers,
it extends Rust's Cargo tool to better suite their specific needs.
OSDK is instrumental in the development of Asterinas Kernel.
#### [Part 4: Contributing to Asterinas](to-contribute/)
Asterinas is in its nascent stage and welcomes your contributions! This part provides guidance on how you can become an integral part of the Asterinas project.
Asterinas is in its early stage
and welcomes your contributions!
This part provides guidance
on how you can become an integral part of the Asterinas project.
#### [Part 5: Requests for Comments (RFCs)](rfcs/)
Significant decisions in Asterinas are made through a transparent RFC process. This part documents the rationale behind these decisions and how you can participate in this process.
Significant decisions in Asterinas are made through a transparent RFC process.
This part describes the RFC process
and archives all approvaed RFCs.
## Licensing
Asterinas's source code and documentation primarily use the [Mozilla Public License (MPL), Version 2.0](https://github.com/asterinas/asterinas/blob/main/LICENSE-MPL). Select components are under more permissive licenses, detailed [here](https://github.com/asterinas/asterinas/blob/main/.licenserc.yaml).
Asterinas's source code and documentation primarily use the
[Mozilla Public License (MPL), Version 2.0](https://github.com/asterinas/asterinas/blob/main/LICENSE-MPL).
Select components are under more permissive licenses,
detailed [here](https://github.com/asterinas/asterinas/blob/main/.licenserc.yaml).
Our choice of the [weak-copyleft](https://www.tldrlegal.com/license/mozilla-public-license-2-0-mpl-2) MPL license reflects a strategic balance:
1. **Commitment to open-source freedom**: We believe that OS kernels are a communal asset that should benefit humanity. The MPL ensures that any alterations to MPL-covered files remain open source, aligning with our vision. Additionally, we do not require contributors to sign a Contributor License Agreement (CLA), [preserving their rights and preventing the possibility of their contributions being made closed source](https://drewdevault.com/2018/10/05/Dont-sign-a-CLA.html).
1. **Commitment to open-source freedom**:
We believe that OS kernels are a communal asset that should benefit humanity.
The MPL ensures that any alterations to MPL-covered files remain open source,
aligning with our vision.
Additionally, we do not require contributors
to sign a Contributor License Agreement (CLA),
[preserving their rights and preventing the possibility of their contributions being made closed source](https://drewdevault.com/2018/10/05/Dont-sign-a-CLA.html).
2. **Accommodating proprietary modules**: Recognizing the evolving landscape where large corporations also contribute significantly to open-source, we accommodate the business need for proprietary kernel modules. Unlike GPL, the MPL permits the combination and linking of MPL-covered files with proprietary code.
2. **Accommodating proprietary modules**:
Recognizing the evolving landscape
where large corporations also contribute significantly to open-source,
we accommodate the business need for proprietary kernel modules.
Unlike GPL,
the MPL permits the linking of MPL-covered files with proprietary code.
In conclusion, we believe the MPL is the best choice to foster a vibrant, robust, and inclusive open-source community around Asterinas.
In conclusion, we believe that
MPL is the best choice
to foster a vibrant, robust, and inclusive open-source community around Asterinas.

31
docs/src/kernel/README.md
View File

@ -2,17 +2,38 @@
## Overview
Asterinas is a _safe_, _fast_, and _general-purpose_ OS kernel that provides _Linux-compatible_ ABI. It can serve as a seamless replacement for Linux while enhancing _memory safety_ and _developer friendliness_.
Asterinas is a _safe_, _fast_, and _general-purpose_ OS kernel
that provides _Linux-compatible_ ABI.
It can serve as a seamless replacement for Linux
while enhancing _memory safety_ and _developer friendliness_.
* Asterinas prioritizes memory safety by employing Rust as its sole programming language and limiting the use of _unsafe Rust_ to a clearly defined and minimal Trusted Computing Base (TCB). This innovative approach, known as [the framekernel architecture](), establishes Asterinas as a more secure and dependable kernel option.
* Asterinas prioritizes memory safety
by employing Rust as its sole programming language
and limiting the use of _unsafe Rust_
to a clearly defined and minimal Trusted Computing Base (TCB).
This innovative approach,
known as [the framekernel architecture](),
establishes Asterinas as a more secure and dependable kernel option.
* Asterinas surpasses Linux in terms of developer friendliness. It empowers kernel developers to (1) utilize the more productive Rust programming language, (2) leverage a purpose-built toolkit called [OSDK]() to streamline their workflows, and (3) choose between releasing their kernel modules as open source or keeping them proprietary, thanks to the flexibility offered by [MPL]().
* Asterinas surpasses Linux in terms of developer friendliness.
It empowers kernel developers to
(1) utilize the more productive Rust programming language,
(2) leverage a purpose-built toolkit called [OSDK]() to streamline their workflows,
and (3) choose between releasing their kernel modules as open source
or keeping them proprietary,
thanks to the flexibility offered by [MPL]().
While the journey towards a production-grade OS kernel can be challenging, we are steadfastly progressing towards our goal. Currently, Asterinas only supports x86-64 VMs. However, [our aim for 2024]() is to make Asterinas production-ready on x86-64 for both bare-metal and VM environments.
While the journey towards a production-grade OS kernel can be challenging,
we are steadfastly progressing towards our goal.
Currently, Asterinas only supports x86-64 VMs.
However, [our aim for 2024]() is
to make Asterinas production-ready on x86-64
for both bare-metal and VM environments.
## Getting Started
Get yourself an x86-64 Linux machine with Docker installed. Follow the three simple steps below to get Asterinas up and running.
Get yourself an x86-64 Linux machine with Docker installed.
Follow the three simple steps below to get Asterinas up and running.
1. Download the latest source code.

12
docs/src/kernel/linux-compatibility.md
View File

@ -4,11 +4,19 @@
>
> --- Linus Torvalds
Asterinas is dedicated to maintaining compatibility with the Linux ABI, ensuring that applications and administrative tools designed for Linux can seamlessly operate within Asterinas. While we prioritize compatibility, it is important to note that Asterinas does not, nor will it in the future, support the loading of Linux kernel modules.
Asterinas is dedicated to maintaining compatibility with the Linux ABI,
ensuring that applications and administrative tools
designed for Linux can seamlessly operate within Asterinas.
While we prioritize compatibility,
it is important to note that Asterinas does not,
nor will it in the future,
support the loading of Linux kernel modules.
## System Calls
At the time of writing, Asterinas implements 120 out of the 310+ system calls provided by Linux on x86-64 architecture.
At the time of writing,
Asterinas implements 120 out of the 310+ system calls
provided by Linux on x86-64 architecture.
| Numbers | Names | Is Implemented |
| ------- | ---------------- | --------------- |

47
docs/src/kernel/roadmap.md
View File

@ -1,18 +1,53 @@
# Roadmap
Asterinas is a general-purpose OS kernel designed to support multiple CPU architectures and a variety of use cases. Currently, it only supports x86-64 VMs. Our roadmap includes the following plans:
Asterinas is a general-purpose OS kernel
designed to support multiple CPU architectures and a variety of use cases.
Currently, it only supports x86-64 VMs.
Our roadmap includes the following plans:
* By 2024, we aim to achieve production-ready status for VM environments on x86-64.
* In 2025 and beyond, we will expand our support for CPU architectures and hardware devices.
## Target Early Use Cases
One of the biggest challenges for a new OS kernel is driver support. Linux has been widely accepted due to its wide range of hardware support. As a newcomer, Asterinas faces the challenge of implementing drivers for all devices on a target platform, which would take a significant amount of time.
One of the biggest challenges for a new OS kernel is driver support.
Linux has been widely accepted due to its wide range of hardware support.
As a newcomer, Asterinas faces the challenge of implementing drivers
for all devices on a target platform,
which would take a significant amount of time.
To address this obstacle, we have decided to enter the cloud market first. In an IaaS cloud, workloads of different tenants are run in VMs or [VM-style bare-metal servers](https://dl.acm.org/doi/10.1145/3373376.3378507) for maximum isolation and elasticity. The main device driver requirement for the VM environment is virtio, which is already supported by Asterinas. Therefore, using Asterinas as the guest OS of a VM or the host OS of a VM-style bare-metal server in production looks feasible in the near future.
To address this obstacle,
we have decided to enter the cloud market first.
In an IaaS cloud, workloads of different tenants are run in VMs
or [VM-style bare-metal servers](https://dl.acm.org/doi/10.1145/3373376.3378507)
for maximum isolation and elasticity.
The main device driver requirement for the VM environment is virtio,
which is already supported by Asterinas.
Therefore, using Asterinas as the guest OS of a VM
or the host OS of a VM-style bare-metal server in production
looks quite feasible in the near future.
Asterinas provides high assurance of memory safety thanks to [the framekernel architecture](). Thus, in the cloud setting, Asterinas is attractive for usage scenarios where Linux ABI is necessary but Linux itself is considered insecure due to its large Trusted Computing Base (TCB) and memory unsafety. Specifically, we are focusing on two use cases:
Asterinas provides high assurance of memory safety
thanks to [the framekernel architecture]().
Thus, in the cloud setting,
Asterinas is attractive for usage scenarios
where Linux ABI is necessary but Linux itself is considered insecure
due to its large Trusted Computing Base (TCB) and memory unsafety.
Specifically, we are focusing on two use cases:
1. VM-based TEEs: All major CPU architectures have introduced VM-based Trusted Execution Environment (TEE) technology, such as ARM CCA, AMD SEV, and Intel TDX. Applications running inside TEEs often handle private or sensitive data. By running on a lightweight and memory-safe OS kernel like Asterinas, they can greatly enhance security and privacy.
1. VM-based TEEs:
All major CPU architectures have introduced
VM-based Trusted Execution Environment (TEE) technology,
such as ARM CCA, AMD SEV, and Intel TDX.
Applications running inside TEEs often handle private or sensitive data.
By running on a lightweight and memory-safe OS kernel like Asterinas,
they can greatly enhance security and privacy.
2. Secure containers: In the cloud-native era, applications are commonly deployed in containers. The popular container runtimes like runc and Docker rely on the OS-level isolation enforced by Linux. However, [Linux containers are prone to privilege escalation bugs](https://dl.acm.org/doi/10.1145/3274694.3274720). With its safety and security prioritized architecture, Asterinas can offer more reliable OS-level isolation, making it ideal for secure containers.
2. Secure containers:
In the cloud-native era, applications are commonly deployed in containers.
The popular container runtimes like runc and Docker rely on
the OS-level isolation enforced by Linux.
However, [Linux containers are prone to privilege escalation bugs](https://dl.acm.org/doi/10.1145/3274694.3274720).
With its safety and security prioritized architecture,
Asterinas can offer more reliable OS-level isolation,
making it ideal for secure containers.

66
docs/src/kernel/the-framekernel-architecture.md
View File

@ -4,31 +4,79 @@
> The security of a microkernel, the speed of a monolithic kernel.
Asterinas introduces a novel OS architecture called _framekernel_, which unleashes the full power of Rust to bring the best of both monolithic kernels and microkernels.
Asterinas introduces a novel OS architecture called _framekernel_,
which unleashes the full power of Rust
to bring the best of both monolithic kernels and microkernels.
Within the framekernel architecture, the entire OS resides in the same address space (like a monolithic kernel) and is required to be written in Rust. However, there's a twist---the kernel is partitioned in two halves: the OS Framework (akin to a microkernel) and the OS Services. Only the OS Framework is allowed to use _unsafe Rust_, while the OS Services must be written exclusively in _safe Rust_.
Within the framekernel architecture,
the entire OS resides in the same address space (like a monolithic kernel)
and is required to be written in Rust.
However, there's a twist---the kernel is partitioned in two halves:
the OS Framework (akin to a microkernel)
and the OS Services.
Only the OS Framework is allowed to use _unsafe Rust_,
while the OS Services must be written exclusively in _safe Rust_.
| | Unsafe Rust | Responsibilities | Code Sizes |
|--------------|-------------|--------------------------------------------------------------------------------|------------|
| OS Framework | Allowed | Encapsulate low-level unsafe code within high-level safe APIs | Small |
| OS Services | Not allowed | Implement OS functionalities, e.g., system calls, file systems, device drivers | Large |
As a result, the memory safety of the kernel can be reduced to that of the OS Framework, thus minimizing the Trusted Computing Base (TCB) associated with the kernel's memory safety. On the other hand, the single address space allows different parts of the kernel to communicate in the most efficient means, e.g., function calls and shared memory. Thanks to the framekernel architecture, Asterinas can offer both exceptional performance and enhanced safety.
As a result,
the memory safety of the kernel can be reduced to that of the OS Framework,
thus minimizing the Trusted Computing Base (TCB)
associated with the kernel's memory safety.
On the other hand,
the single address space allows different parts of the kernel
to communicate in the most efficient means,
e.g., function calls and shared memory.
Thanks to the framekernel architecture,
Asterinas can offer both exceptional performance and enhanced safety.
![A comparison between different OS architectures](../images/a_comparison_between_os_archs.svg)
## Requirements for the OS Framework
While the concept of framekernel is straightforward, the design and implementation of the required OS framework present challenges. It must concurrently fulfill four criteria.
While the concept of framekernel is straightforward,
the design and implementation of the required OS framework present challenges.
It must concurrently fulfill four criteria.
![The four requirements for the OS framework](../images/four_requirements_for_os_framework.svg)
* **Soundness.** The safe APIs of the framework are considered sound if no [undefined behaviors](https://doc.rust-lang.org/reference/behavior-considered-undefined.html#behavior-considered-undefined) shall be triggered by whatever safe Rust code that a programmer may write using the APIs---as long as the code is verified by the Rust toolchain. Soundness ensures that the OS framework, in conjunction with the Rust toolchain, bears the full responsibility for the kernel's memory safety.
* **Soundness.**
The safe APIs of the framework are considered sound
if no [undefined behaviors](https://doc.rust-lang.org/reference/behavior-considered-undefined.html#behavior-considered-undefined) shall be triggered
by whatever safe Rust code that a programmer may write using the APIs
---as long as the code is verified by the Rust toolchain.
Soundness ensures that the OS framework,
in conjunction with the Rust toolchain,
bears the full responsibility for the kernel's memory safety.
* **Expressiveness.** The framework should empower developers to implement a substantial range of OS functionalities in safe Rust using the APIs. It is especially important that the framework enables writing device drivers in safe Rust, considering that device drivers comprise the bulk of the code in a fully-fleged OS kernel (like Linux).
* **Expressiveness.**
The framework should empower developers
to implement a substantial range of OS functionalities
in safe Rust using the APIs.
It is especially important that
the framework enables writing device drivers in safe Rust,
considering that device drivers comprise the bulk of the code
in a fully-fleged OS kernel (like Linux).
* **Minimalism.** As the TCB for memory safety, the framework should be kept as small as possible. No functionality should be implemented inside the framework if doing it outside is possible.
* **Minimalism.**
As the TCB for memory safety,
the framework should be kept as small as possible.
No functionality should be implemented inside the framework
if doing it outside is possible.
* **Efficiency.** The safe API provided by the framework is only allowed to introduce minimal overheads. Ideally, these APIs should be realized as [zero-cost abstractions](https://monomorph.is/posts/zero-cost-abstractions/).
* **Efficiency.**
The safe API provided by the framework is only allowed
to introduce minimal overheads.
Ideally, these APIs should be realized
as [zero-cost abstractions](https://monomorph.is/posts/zero-cost-abstractions/).
Fortunatelly, our efforts to design and implement an OS framework meeting these standards have borne fruit in the form of the [Asterinas Framework](). Using this framework as a foundation, we have developed the Asterinas Kernel; this framework also enables others to create their own framekernels, with different goals and tradeoffs.
Fortunatelly, our efforts
to design and implement an OS framework meeting these standards
have borne fruit in the form of the [Asterinas Framework]().
Using this framework as a foundation,
we have developed the Asterinas Kernel;
this framework also enables others to create their own framekernels,
with different goals and tradeoffs.