diff --git a/docs/src/framework/an-100-line-example.md b/docs/src/framework/an-100-line-example.md index e27a3f64a..71ca5cd48 100644 --- a/docs/src/framework/an-100-line-example.md +++ b/docs/src/framework/an-100-line-example.md @@ -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] diff --git a/docs/src/introduction.md b/docs/src/introduction.md index c5c15448e..0759ba698 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -4,7 +4,9 @@ asterinas-logo

-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. diff --git a/docs/src/kernel/README.md b/docs/src/kernel/README.md index 91a4e08e8..77533f626 100644 --- a/docs/src/kernel/README.md +++ b/docs/src/kernel/README.md @@ -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. diff --git a/docs/src/kernel/linux-compatibility.md b/docs/src/kernel/linux-compatibility.md index b1cab1dfb..d314f0e7c 100644 --- a/docs/src/kernel/linux-compatibility.md +++ b/docs/src/kernel/linux-compatibility.md @@ -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 | | ------- | ---------------- | --------------- | diff --git a/docs/src/kernel/roadmap.md b/docs/src/kernel/roadmap.md index 470332d14..e6fb32d77 100644 --- a/docs/src/kernel/roadmap.md +++ b/docs/src/kernel/roadmap.md @@ -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. diff --git a/docs/src/kernel/the-framekernel-architecture.md b/docs/src/kernel/the-framekernel-architecture.md index 8914f39dd..151605d8c 100644 --- a/docs/src/kernel/the-framekernel-architecture.md +++ b/docs/src/kernel/the-framekernel-architecture.md @@ -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.