diff --git a/docs/src/README.md b/docs/src/README.md index c5613d00..86ce7068 100644 --- a/docs/src/README.md +++ b/docs/src/README.md @@ -16,17 +16,17 @@ This book is divided into five distinct parts: 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. +Asterinas Kernel implements the Linux ABI in a safe and efficient way. This means it can seamlessly replace Linux, offering enhanced safety and security. #### [Part 2: Asterinas OSTD](ostd/) -Asterinas OSTD lays down a minimalistic, powerful, and solid foundation +The Asterinas OSTD 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 OSTD. +The Asterinas Kernel is built on this very OSTD. #### [Part 3: Asterinas OSDK](osdk/guide/) diff --git a/docs/src/kernel/README.md b/docs/src/kernel/README.md index d2b1b9bb..8d6e9c37 100644 --- a/docs/src/kernel/README.md +++ b/docs/src/kernel/README.md @@ -3,7 +3,7 @@ ## Overview Asterinas is a _secure_, _fast_, and _general-purpose_ OS kernel -that provides _Linux-compatible_ ABI. +that provides an _Linux-compatible_ ABI. It can serve as a seamless replacement for Linux while enhancing _memory safety_ and _developer friendliness_. @@ -44,7 +44,11 @@ git clone https://github.com/asterinas/asterinas 2. Run a Docker container as the development environment. ```bash -docker run -it --privileged --network=host --device=/dev/kvm -v $(pwd)/asterinas:/root/asterinas asterinas/asterinas:0.9.0 +docker run -it --privileged \ + --network=host \ + --device=/dev/kvm \ + -v $(pwd)/asterinas:/root/asterinas \ + asterinas/asterinas:0.9.0 ``` 3. Inside the container, go to the project folder to build and run Asterinas. diff --git a/docs/src/kernel/advanced-instructions.md b/docs/src/kernel/advanced-instructions.md index d209cc3e..e2e2822b 100644 --- a/docs/src/kernel/advanced-instructions.md +++ b/docs/src/kernel/advanced-instructions.md @@ -64,8 +64,8 @@ Then, in the interactive shell, run the following script to start the syscall te ### Using GDB to Debug -To debug Asterinas by [QEMU GDB support](https://qemu-project.gitlab.io/qemu/system/gdb.html), -one could compile Asterinas in the debug profile, +To debug Asterinas via [QEMU GDB support](https://qemu-project.gitlab.io/qemu/system/gdb.html), +you can compile Asterinas in the debug profile, start an Asterinas instance and run the GDB interactive shell in another terminal. Start a GDB-enabled VM of Asterinas with OSDK and wait for debugging connection: diff --git a/docs/src/kernel/roadmap.md b/docs/src/kernel/roadmap.md index e6fb32d7..07a38b2c 100644 --- a/docs/src/kernel/roadmap.md +++ b/docs/src/kernel/roadmap.md @@ -18,7 +18,7 @@ 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 +In an IaaS (Infrastructure-as-a-Service) 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, @@ -28,7 +28,7 @@ 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](). +thanks to [the framekernel architecture](the-framekernel-architecture.md). Thus, in the cloud setting, Asterinas is attractive for usage scenarios where Linux ABI is necessary but Linux itself is considered insecure diff --git a/docs/src/kernel/the-framekernel-architecture.md b/docs/src/kernel/the-framekernel-architecture.md index e8e2c4af..5ea31631 100644 --- a/docs/src/kernel/the-framekernel-architecture.md +++ b/docs/src/kernel/the-framekernel-architecture.md @@ -47,7 +47,7 @@ It must concurrently fulfill four criteria. 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. +- 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. diff --git a/docs/src/ostd/README.md b/docs/src/ostd/README.md index 9912a4ba..ca347d99 100644 --- a/docs/src/ostd/README.md +++ b/docs/src/ostd/README.md @@ -7,10 +7,10 @@ > 子曰: > "从心所欲,不逾矩。" -With Asterinas OSTD, +With the Asterinas OSTD (Operating System Standard Library), you don't have to learn the dark art of unsafe Rust programming and risk shooting yourself in the foot. -You will be doing whatever your heart desired +You will be doing whatever your heart desires, and be confident that your kernel will never crash or be hacked due to undefined behaviors, even if today marks your Day 1 as a Rust programmer. @@ -58,28 +58,27 @@ by leveraging OSTD. Adopting a minimalist philosophy, OSTD has a small codebase. At its core lies the `ostd` crate, -currently encompassing about 10K lines of code ----a figure that is even smaller than those of many microkernels. +currently encompassing about 10K lines of code - a figure +that is even smaller than those of many microkernels. As OSTD evolves, its codebase will expand, albeit at a relatively slow rate in comparison to the OS services layered atop it. -OSTD's efficiency is measurable +The OSTD's efficiency is measurable through the performance metrics of its APIs and the system calls of Asterinas Kernel. No intrinsic limitations have been identified within Rust or the framekernel architecture that could hinder kernel performance. -Soundness, -unlike the other three requirements, +Soundness, unlike the other three requirements, is not as easily quantified or proved. While formal verification stands as the gold standard, it requires considerable resources and time and is not an immediate priority. As a more pragmatic approach, we will explain why the high-level design is sound -in the [soundness analysis]() -and rely on the many eyes of the community -to catch any potential flaws in the implementation. +in the soundness analysis and rely on the many +eyes of the community to catch any potential flaws +in the implementation.