mirror of
https://github.com/asterinas/asterinas.git
synced 2025-06-10 05:46:48 +00:00
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:
parent
5af0fd6010
commit
1632ce36d7
@ -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
|
||||||
```
|
```
|
||||||
|
@ -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.
|
||||||
|
@ -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.
|
||||||
|
|
||||||
|
@ -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)
|
||||||
|
@ -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.
|
||||||
|
@ -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`.
|
||||||
|
@ -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
|
||||||
|
@ -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).
|
||||||
|
@ -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
|
||||||
|
```
|
||||||
|
@ -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
|
||||||
|
@ -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`).
|
||||||
|
@ -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
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user