From 1632ce36d7cf29b38b6e06cc5dd3d9fb70247129 Mon Sep 17 00:00:00 2001 From: Thomas Dickson Date: Tue, 1 Oct 2024 11:08:25 +1300 Subject: [PATCH] doc: improve grammar, spelling, and fix some links doc: resolve rebasing osdk docs doc: improve grammar and spelling, fix links for the contributing section fix: resolve rebasing for run.rs fix: resolve rebasing for osdk, again --- docs/src/osdk/guide/README.md | 10 +++++----- docs/src/osdk/guide/create-project.md | 4 ++-- docs/src/osdk/guide/intel-tdx.md | 4 ++-- docs/src/osdk/guide/run-project.md | 10 +++++----- docs/src/osdk/guide/why.md | 8 ++++---- docs/src/osdk/guide/work-in-workspace.md | 6 +++--- docs/src/osdk/reference/README.md | 4 ++-- docs/src/osdk/reference/commands/profile.md | 2 +- docs/src/osdk/reference/commands/run.md | 9 +++++++++ docs/src/osdk/reference/commands/test.md | 4 ++-- docs/src/osdk/reference/manifest.md | 2 +- .../to-contribute/style-guidelines/rust-guidelines.md | 2 +- 12 files changed, 37 insertions(+), 28 deletions(-) diff --git a/docs/src/osdk/guide/README.md b/docs/src/osdk/guide/README.md index a7cddfd98..d71d21b59 100644 --- a/docs/src/osdk/guide/README.md +++ b/docs/src/osdk/guide/README.md @@ -2,12 +2,12 @@ ## Overview -OSDK (short for Operating System Development Kit) +The Asterinas OSDK (short for Operating System Development Kit) is designed to simplify the development of Rust operating systems. It aims to streamline the process by leveraging [the framekernel architecture](../../kernel/the-framekernel-architecture.md). -OSDK provides a command-line tool `cargo-osdk`, +The OSDK provides a command-line tool `cargo-osdk`, which facilitates project management for those developed on the framekernel architecture. `cargo-osdk` can be used as a subcommand of Cargo. @@ -18,7 +18,7 @@ and testing projects conveniently. ## Install OSDK ### Requirements -Currently, OSDK only works on x86_64 ubuntu system. +Currently, OSDK is only supported on x86_64 Ubuntu systems. We will add support for more operating systems in the future. To run a kernel developed by OSDK with QEMU, @@ -50,14 +50,14 @@ cargo install cargo-binutils ### Install `cargo-osdk` is published on [crates.io](https://crates.io/), -and can be installed by +and can be installed by running ```bash cargo install cargo-osdk ``` ### Upgrade If `cargo-osdk` is already installed, -the tool can be upgraded by +the tool can be upgraded by running ```bash cargo install --force cargo-osdk ``` diff --git a/docs/src/osdk/guide/create-project.md b/docs/src/osdk/guide/create-project.md index 7c8f3732a..1790a21a3 100644 --- a/docs/src/osdk/guide/create-project.md +++ b/docs/src/osdk/guide/create-project.md @@ -1,6 +1,6 @@ # Creating an OS Project -OSDK can be used to create a new kernel project +The OSDK can be used to create a new kernel project or a new library project. A kernel project defines the entry point of the kernel and can be run with QEMU. @@ -112,4 +112,4 @@ The default manifest of a kernel project: ### `rust-toolchain.toml` The Rust toolchain for the kernel. -It aligns with the toolchain of the Asterinas OSTD. +It is the same as the toolchain of the Asterinas OSTD. diff --git a/docs/src/osdk/guide/intel-tdx.md b/docs/src/osdk/guide/intel-tdx.md index 98a770e46..bb387d159 100644 --- a/docs/src/osdk/guide/intel-tdx.md +++ b/docs/src/osdk/guide/intel-tdx.md @@ -1,6 +1,6 @@ # Running an OS in Intel TDX env -OSDK supports running your OS in an [Intel TDX](https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/overview.html) environment conveniently. +The OSDK supports running your OS in an [Intel TDX](https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/overview.html) environment conveniently. Intel TDX can provide a more secure environment for your OS. ## Prepare the Intel TDX Environment @@ -39,7 +39,7 @@ docker run -it --privileged --network=host --device=/dev/kvm asterinas/osdk-tdx: As Intel TDX has extra requirements or restrictions for VMs, it demands adjusting the OSDK configurations accordingly. -This can be easily achieved with the `scheme` feature of OSDK, +This can be easily achieved with the `scheme` feature of the OSDK, which provides a convenient way to override the default OSDK configurations for a specific environment. diff --git a/docs/src/osdk/guide/run-project.md b/docs/src/osdk/guide/run-project.md index 7c44bc0bd..cfe3b4926 100644 --- a/docs/src/osdk/guide/run-project.md +++ b/docs/src/osdk/guide/run-project.md @@ -1,6 +1,6 @@ # Running or Testing an OS Project -OSDK allows for convenient building, running, +The OSDK allows for convenient building, running, and testing of an OS project. The following example shows the typical workflow. @@ -76,12 +76,12 @@ cargo osdk test foo ## Options -Both `build`, `run`, and `test` commands accept options +All of the `build`, `run`, and `test` commands accept options to control their behavior, such as how to compile and launch the kernel. The following documentations provide details on all the available options: -- [build options](../reference/commands/build.md) -- [run options](../reference/commands/run.md) -- [test options](../reference/commands/test.md) +- [`build` options](../reference/commands/build.md) +- [`run` options](../reference/commands/run.md) +- [`test` options](../reference/commands/test.md) diff --git a/docs/src/osdk/guide/why.md b/docs/src/osdk/guide/why.md index f6f789982..79ffb97cd 100644 --- a/docs/src/osdk/guide/why.md +++ b/docs/src/osdk/guide/why.md @@ -9,7 +9,7 @@ This is important to Asterinas as we believe that the project's success is intricately tied to the productivity and happiness of its developers. -So OSDK is here to upgrade your dev experience. +So the OSDK is here to upgrade your dev experience. To be honest, writing OS kernels is hard. Even when you're using Rust, @@ -24,7 +24,7 @@ no stack, no heap, no threads, not even the standard I/O. It's just you and the no_std world of Rust. You have to implement these basic programming primitives by getting your hands dirty with the most low-level, -error-prone, nitty-gritty of computer architecture. +error-prone, and nitty-gritty details of computer architecture. It's a journey of learning, doing, and a whole lot of finger-crossing to make sure everything clicks into place. @@ -35,7 +35,7 @@ reuse OS-related libraries/crates across projects. Think about it: most applications share a common groundwork, like libc, Rust's std library, or an SDK. -This isn't the case with kernels -- +This isn't the case with kernels - they lack this shared starting point, forcing each one to craft its own set of tools from the ground up. @@ -83,4 +83,4 @@ as reported by [RustSec Advisory Database](https://rustsec.org). Despite having [a whole book](https://doc.rust-lang.org/nomicon/) to document "the Dark Arts of Unsafe Rust", unsafe Rust is still tricky to use correctly, -even among reasoned Rust developers. +even among seasoned Rust developers. diff --git a/docs/src/osdk/guide/work-in-workspace.md b/docs/src/osdk/guide/work-in-workspace.md index d0055f494..e72d1cda1 100644 --- a/docs/src/osdk/guide/work-in-workspace.md +++ b/docs/src/osdk/guide/work-in-workspace.md @@ -2,7 +2,7 @@ Typically, an operating system may consist of multiple crates, and these crates may be organized in a workspace. -OSDK also supports managing projects in a workspace. +The OSDK also supports managing projects in a workspace. Below is an example that demonstrates how to create, build, run, and test projects in a workspace. @@ -47,11 +47,11 @@ myworkspace/ └── lib.rs ``` -At present, OSDK mandates that there must be only one kernel project +At present, the OSDK mandates that there must be only one kernel project within a workspace. In addition to the two projects, -OSDK will also generate `OSDK.toml` and `rust-toolchain.toml` +the OSDK will also generate `OSDK.toml` and `rust-toolchain.toml` at the root of the workspace. Next, add the following function to `mylib/src/lib.rs`. diff --git a/docs/src/osdk/reference/README.md b/docs/src/osdk/reference/README.md index 2379e7765..919eb40a8 100644 --- a/docs/src/osdk/reference/README.md +++ b/docs/src/osdk/reference/README.md @@ -1,6 +1,6 @@ # OSDK User Reference -OSDK is a command line tool that can be used +The Asterinas OSDK is a command line tool that can be used as a subcommand of Cargo. The common usage of OSDK is: @@ -15,7 +15,7 @@ you can use `cargo osdk help `. ## Manifest -OSDK utilizes a manifest named `OSDK.toml` +The OSDK utilizes a manifest named `OSDK.toml` to define its precise behavior regarding how to run a kernel with QEMU. The `OSDK.toml` file should be placed diff --git a/docs/src/osdk/reference/commands/profile.md b/docs/src/osdk/reference/commands/profile.md index c2ec6afbc..b20483a37 100644 --- a/docs/src/osdk/reference/commands/profile.md +++ b/docs/src/osdk/reference/commands/profile.md @@ -3,7 +3,7 @@ ## Overview The profile command is used to collect stack traces when running the target -kernel in QEMU. It attaches to the GDB server initiated with the run subcommand +kernel in QEMU. It attaches to the GDB server, initiated with the run subcommand, and collects the stack trace periodically. The collected information can be used to directly generate a flame graph, or be stored for later analysis using [the original flame graph tool](https://github.com/brendangregg/FlameGraph). diff --git a/docs/src/osdk/reference/commands/run.md b/docs/src/osdk/reference/commands/run.md index 7729adb3d..aed2acca8 100644 --- a/docs/src/osdk/reference/commands/run.md +++ b/docs/src/osdk/reference/commands/run.md @@ -33,6 +33,9 @@ Launch a debug server via QEMU with an unix socket stub, e.g. `.debug`: ```bash cargo osdk run --gdb-server addr=.debug + +```bash +cargo osdk run --gdb-server --gdb-server-addr .debug ``` Launch a debug server via QEMU with a TCP stub, e.g., `localhost:1234`: @@ -46,3 +49,9 @@ Launch a debug server via QEMU and use VSCode to interact with: ```bash cargo osdk run --gdb-server wait-client,vscode,addr=:1234 ``` + +Launch a debug server via QEMU and use VSCode to interact with: + +```bash +cargo osdk run --gdb-server --gdb-vsc --gdb-server-addr :1234 +``` diff --git a/docs/src/osdk/reference/commands/test.md b/docs/src/osdk/reference/commands/test.md index 612267aee..a39e4f30f 100644 --- a/docs/src/osdk/reference/commands/test.md +++ b/docs/src/osdk/reference/commands/test.md @@ -5,12 +5,12 @@ execute kernel mode unit test by starting QEMU. The usage is as follows: ```bash -cargo osdk test [OPTIONS] [TESTNAME] +cargo osdk test [TESTNAME] [OPTIONS] ``` ## Arguments -[TESTNAME]: +`TESTNAME`: Only run tests containing this string in their names ## Options diff --git a/docs/src/osdk/reference/manifest.md b/docs/src/osdk/reference/manifest.md index aeceb262e..0fb5b56c3 100644 --- a/docs/src/osdk/reference/manifest.md +++ b/docs/src/osdk/reference/manifest.md @@ -2,7 +2,7 @@ ## Overview -OSDK utilizes a manifest to define its precise behavior. +The OSDK tool utilizes a manifest to define its precise behavior. Typically, the configuration file is named `OSDK.toml` and is placed in the root directory of the workspace (the same directory as the workspace's `Cargo.toml`). diff --git a/docs/src/to-contribute/style-guidelines/rust-guidelines.md b/docs/src/to-contribute/style-guidelines/rust-guidelines.md index 28c0bf7c3..1d0c92c4d 100644 --- a/docs/src/to-contribute/style-guidelines/rust-guidelines.md +++ b/docs/src/to-contribute/style-guidelines/rust-guidelines.md @@ -11,7 +11,7 @@ The use of the `#[warn(missing_docs)]` lint enforces this rule. Asterinas adheres to the API style guidelines of the Rust community. The recommended API documentation style can be found at -[how-to-write-documentation](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html). +[How to write documentation - The rustdoc book](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html). ## Lint Guidelines