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
This commit is contained in:
Thomas Dickson 2024-10-01 11:08:25 +13:00 committed by Tate, Hongliang Tian
parent 5af0fd6010
commit 1632ce36d7
12 changed files with 37 additions and 28 deletions

View File

@ -2,12 +2,12 @@
## Overview ## 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. is designed to simplify the development of Rust operating systems.
It aims to streamline the process It aims to streamline the process
by leveraging [the framekernel architecture](../../kernel/the-framekernel-architecture.md). 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 which facilitates project management
for those developed on the framekernel architecture. for those developed on the framekernel architecture.
`cargo-osdk` can be used as a subcommand of Cargo. `cargo-osdk` can be used as a subcommand of Cargo.
@ -18,7 +18,7 @@ and testing projects conveniently.
## Install OSDK ## Install OSDK
### Requirements ### 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. We will add support for more operating systems in the future.
To run a kernel developed by OSDK with QEMU, To run a kernel developed by OSDK with QEMU,
@ -50,14 +50,14 @@ cargo install cargo-binutils
### Install ### Install
`cargo-osdk` is published on [crates.io](https://crates.io/), `cargo-osdk` is published on [crates.io](https://crates.io/),
and can be installed by and can be installed by running
```bash ```bash
cargo install cargo-osdk cargo install cargo-osdk
``` ```
### Upgrade ### Upgrade
If `cargo-osdk` is already installed, If `cargo-osdk` is already installed,
the tool can be upgraded by the tool can be upgraded by running
```bash ```bash
cargo install --force cargo-osdk cargo install --force cargo-osdk
``` ```

View File

@ -1,6 +1,6 @@
# Creating an OS Project # 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. or a new library project.
A kernel project defines the entry point of the kernel A kernel project defines the entry point of the kernel
and can be run with QEMU. and can be run with QEMU.
@ -112,4 +112,4 @@ The default manifest of a kernel project:
### `rust-toolchain.toml` ### `rust-toolchain.toml`
The Rust toolchain for the kernel. 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.

View File

@ -1,6 +1,6 @@
# Running an OS in Intel TDX env # 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. Intel TDX can provide a more secure environment for your OS.
## Prepare the Intel TDX Environment ## 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, As Intel TDX has extra requirements or restrictions for VMs,
it demands adjusting the OSDK configurations accordingly. 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 which provides a convenient way to override the default OSDK configurations
for a specific environment. for a specific environment.

View File

@ -1,6 +1,6 @@
# Running or Testing an OS Project # 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. and testing of an OS project.
The following example shows the typical workflow. The following example shows the typical workflow.
@ -76,12 +76,12 @@ cargo osdk test foo
## Options ## 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 to control their behavior, such as how to compile and
launch the kernel. launch the kernel.
The following documentations provide details on The following documentations provide details on
all the available options: all the available options:
- [build options](../reference/commands/build.md) - [`build` options](../reference/commands/build.md)
- [run options](../reference/commands/run.md) - [`run` options](../reference/commands/run.md)
- [test options](../reference/commands/test.md) - [`test` options](../reference/commands/test.md)

View File

@ -9,7 +9,7 @@ This is important to Asterinas
as we believe that the project's success as we believe that the project's success
is intricately tied to the productivity and happiness is intricately tied to the productivity and happiness
of its developers. 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. To be honest, writing OS kernels is hard.
Even when you're using Rust, 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. It's just you and the no_std world of Rust.
You have to implement these basic programming primitives You have to implement these basic programming primitives
by getting your hands dirty with the most low-level, 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 It's a journey of learning, doing, and
a whole lot of finger-crossing a whole lot of finger-crossing
to make sure everything clicks into place. to make sure everything clicks into place.
@ -35,7 +35,7 @@ reuse OS-related libraries/crates across projects.
Think about it: Think about it:
most applications share a common groundwork, most applications share a common groundwork,
like libc, Rust's std library, or an SDK. 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, they lack this shared starting point,
forcing each one to craft its own set of tools forcing each one to craft its own set of tools
from the ground up. 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/) Despite having [a whole book](https://doc.rust-lang.org/nomicon/)
to document "the Dark Arts of Unsafe Rust", to document "the Dark Arts of Unsafe Rust",
unsafe Rust is still tricky to use correctly, unsafe Rust is still tricky to use correctly,
even among reasoned Rust developers. even among seasoned Rust developers.

View File

@ -2,7 +2,7 @@
Typically, an operating system may consist of multiple crates, Typically, an operating system may consist of multiple crates,
and these crates may be organized in a workspace. 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 Below is an example that demonstrates
how to create, build, run, and test projects in a workspace. how to create, build, run, and test projects in a workspace.
@ -47,11 +47,11 @@ myworkspace/
└── lib.rs └── 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. within a workspace.
In addition to the two projects, 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. at the root of the workspace.
Next, add the following function to `mylib/src/lib.rs`. Next, add the following function to `mylib/src/lib.rs`.

View File

@ -1,6 +1,6 @@
# OSDK User Reference # 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. as a subcommand of Cargo.
The common usage of OSDK is: The common usage of OSDK is:
@ -15,7 +15,7 @@ you can use `cargo osdk help <COMMAND>`.
## Manifest ## Manifest
OSDK utilizes a manifest named `OSDK.toml` The OSDK utilizes a manifest named `OSDK.toml`
to define its precise behavior regarding to define its precise behavior regarding
how to run a kernel with QEMU. how to run a kernel with QEMU.
The `OSDK.toml` file should be placed The `OSDK.toml` file should be placed

View File

@ -3,7 +3,7 @@
## Overview ## Overview
The profile command is used to collect stack traces when running the target 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 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 used to directly generate a flame graph, or be stored for later analysis using
[the original flame graph tool](https://github.com/brendangregg/FlameGraph). [the original flame graph tool](https://github.com/brendangregg/FlameGraph).

View File

@ -33,6 +33,9 @@ Launch a debug server via QEMU with an unix socket stub, e.g. `.debug`:
```bash ```bash
cargo osdk run --gdb-server addr=.debug 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`: 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 ```bash
cargo osdk run --gdb-server wait-client,vscode,addr=:1234 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
```

View File

@ -5,12 +5,12 @@ execute kernel mode unit test by starting QEMU.
The usage is as follows: The usage is as follows:
```bash ```bash
cargo osdk test [OPTIONS] [TESTNAME] cargo osdk test [TESTNAME] [OPTIONS]
``` ```
## Arguments ## Arguments
[TESTNAME]: `TESTNAME`:
Only run tests containing this string in their names Only run tests containing this string in their names
## Options ## Options

View File

@ -2,7 +2,7 @@
## Overview ## 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` Typically, the configuration file is named `OSDK.toml`
and is placed in the root directory of the workspace and is placed in the root directory of the workspace
(the same directory as the workspace's `Cargo.toml`). (the same directory as the workspace's `Cargo.toml`).

View File

@ -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. Asterinas adheres to the API style guidelines of the Rust community.
The recommended API documentation style can be found at 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 ## Lint Guidelines