Samuka007/asterinas
1
0
Fork 0
mirror of https://github.com/asterinas/asterinas.git synced 2025-06-20 04:56:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rename jinux to asterinas in documentation and code

Browse Source
This commit is contained in:
Jianfeng Jiang
2023-12-25 07:27:41 +00:00
committed by Tate, Hongliang Tian
parent 2b248dc326
commit 99f6765ced
43 changed files with 143 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/docker_build.yml vendored
View File

@ -26,7 +26,7 @@ jobs:
- name: Fetch versions in the repo - name: Fetch versions in the repo
id: fetch-versions id: fetch-versions
run: | run: |
echo "jinux_version=$( cat VERSION )" >> "$GITHUB_OUTPUT" echo "aster_version=$( cat VERSION )" >> "$GITHUB_OUTPUT"
echo "rust_version=$( grep -m1 -o 'nightly-[0-9]\+-[0-9]\+-[0-9]\+' rust-toolchain.toml )" >> "$GITHUB_OUTPUT" echo "rust_version=$( grep -m1 -o 'nightly-[0-9]\+-[0-9]\+-[0-9]\+' rust-toolchain.toml )" >> "$GITHUB_OUTPUT"
- name: Build and push - name: Build and push
@ -36,6 +36,6 @@ jobs:
file: ./tools/docker/Dockerfile.ubuntu22.04 file: ./tools/docker/Dockerfile.ubuntu22.04
platforms: linux/amd64 platforms: linux/amd64
push: true push: true
tags: jinuxdev/jinux:${{ steps.fetch-versions.outputs.jinux_version }} tags: jinuxdev/jinux:${{ steps.fetch-versions.outputs.aster_version }}
build-args: | build-args: |
"JINUX_RUST_VERSION=${{ steps.fetch-versions.outputs.rust_version }}" "JINUX_RUST_VERSION=${{ steps.fetch-versions.outputs.rust_version }}"

8
COPYRIGHT
View File

@ -1,9 +1,9 @@
The Jinux project licensed under the GNU General Public License version 2. The Asterinas project licensed under the GNU General Public License version 2.
Copyrights in the Jinux project are retained by their contributors. No Copyrights in the Asterinas project are retained by their contributors. No
copyright assignment is required to contribute to the Jinux project. copyright assignment is required to contribute to the Asterinas project.
For full authorship information, see the version control history. For full authorship information, see the version control history.
Please note that certain files or directories within the Jinux project may Please note that certain files or directories within the Asterinas project may
contain explicit copyright notices and/or license notices differ contain explicit copyright notices and/or license notices differ
from the project's general license terms. from the project's general license terms.

66
README.md
View File

@ -1,33 +1,33 @@
# Jinux # Asterinas
Jinux is a _secure_, _fast_, and _general-purpose_ OS kernel, written in Rust and providing Linux-compatible ABI. Asterinas is a _secure_, _fast_, and _general-purpose_ OS kernel, written in Rust and providing Linux-compatible ABI.
Jinux is designed and implemented with an emphasis on security, rendering it highly attractive for usage scenarios where Linux ABI is indispensable, but Linux itself is deemed insecure given its sheer size of TCB and its nature of being memory unsafe. An instance of such usage is employing Jinux as the guest OS for VM TEEs (e.g., [AMD SEV](https://www.amd.com/en/developer/sev.html) and [Intel TDX](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-trust-domain-extensions.html)). Asterinas is designed and implemented with an emphasis on security, rendering it highly attractive for usage scenarios where Linux ABI is indispensable, but Linux itself is deemed insecure given its sheer size of TCB and its nature of being memory unsafe. An instance of such usage is employing Asterinas as the guest OS for VM TEEs (e.g., [AMD SEV](https://www.amd.com/en/developer/sev.html) and [Intel TDX](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-trust-domain-extensions.html)).
## What's unique about Jinux ## What's unique about Asterinas
Jinux is a _zero-cost_, _least-privilege_ OS kernel. A least-privilege OS is one that adheres to the principle of least privileges, which mandates that every unit (e.g., a subsystem, a module, a function, or even an object) of the OS has the minimum authority and permissions required to perform its tasks. This approach reduces the security risk associated with any single element's bugs or flaws. By "zero-cost", we means the same as in Rust's philosophy of zero-cost abstractions, which emphasizes that high-level abstractions (like those that enable least privilege principles) should be available to developers to use, but not come at the cost of performance. Thus, a zero-cost, least-privilege OS enhances its security without compromising its performance. Asterinas is a _zero-cost_, _least-privilege_ OS kernel. A least-privilege OS is one that adheres to the principle of least privileges, which mandates that every unit (e.g., a subsystem, a module, a function, or even an object) of the OS has the minimum authority and permissions required to perform its tasks. This approach reduces the security risk associated with any single element's bugs or flaws. By "zero-cost", we means the same as in Rust's philosophy of zero-cost abstractions, which emphasizes that high-level abstractions (like those that enable least privilege principles) should be available to developers to use, but not come at the cost of performance. Thus, a zero-cost, least-privilege OS enhances its security without compromising its performance.
Some prior OSes do abide by the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege), but come with considerable performance costs. Take [seL4](https://sel4.systems/) as an example. A [seL4-based multi-server OS](https://docs.sel4.systems/projects/camkes/) minimizes the scope of the OS running in the privileged CPU mode to the seL4 microkernel. The bulk of OS functionalities are implemented by process-based servers, which are separated by process boundary and only allowed to communicate with each other through well-defined interfaces, usually based on RPC. Each service can only access kernel resources represented by [seL4 capabilities](), each of which is restricted with respect to its scope and permissions. All these security measures contribute to the enhanced security of the OS, but result in a considerable runtime costs due to context switching, message passing, and runtime checks. Some prior OSes do abide by the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege), but come with considerable performance costs. Take [seL4](https://sel4.systems/) as an example. A [seL4-based multi-server OS](https://docs.sel4.systems/projects/camkes/) minimizes the scope of the OS running in the privileged CPU mode to the seL4 microkernel. The bulk of OS functionalities are implemented by process-based servers, which are separated by process boundary and only allowed to communicate with each other through well-defined interfaces, usually based on RPC. Each service can only access kernel resources represented by [seL4 capabilities](), each of which is restricted with respect to its scope and permissions. All these security measures contribute to the enhanced security of the OS, but result in a considerable runtime costs due to context switching, message passing, and runtime checks.
Jinux is unique in practicing the principle of least privilege without sacrificing the performance. This is achieved by realizing the full potential of Rust, which, compared to the traditional system programming language like C/C++, offers unique features like an expressive type system, memory safety with unsafe extensions, powerful macros, and a customizable toolchain. By leveraging these unique features, Jinux is able to construct zero-cost abstractions that enable least privileges at the following three levels. Asterinas is unique in practicing the principle of least privilege without sacrificing the performance. This is achieved by realizing the full potential of Rust, which, compared to the traditional system programming language like C/C++, offers unique features like an expressive type system, memory safety with unsafe extensions, powerful macros, and a customizable toolchain. By leveraging these unique features, Asterinas is able to construct zero-cost abstractions that enable least privileges at the following three levels.
1. The architectural level. Jinux is architected as a _framekernel_, where the entire OS resides in a single address space and unsafe Rust code is restricted to a tiny portion of the OS called Jinux Framework. The Framework exposes safe APIs to the rest of Jinux, which implements the most of OS functionalities in safe Rust code completely. Thanks to the framekernel architecture, Jinux's TCB for memory safety is minimized. 1. The architectural level. Asterinas is architected as a _framekernel_, where the entire OS resides in a single address space and unsafe Rust code is restricted to a tiny portion of the OS called Asterinas Framework. The Framework exposes safe APIs to the rest of Asterinas, which implements the most of OS functionalities in safe Rust code completely. Thanks to the framekernel architecture, Asterinas's TCB for memory safety is minimized.
![Architecture](docs/src/images/arch_comparison.png) ![Architecture](docs/src/images/arch_comparison.png)
2. The component level. Upon Jinux Framework is a set of OS components, each of which is responsible for a particular OS functionality, feature, or device. These OS components are Rust crates with two traits: (1) containing safe Rust code, as demanded by the framekernel architecture, and (2) being governed by Jinux Component System, which can enforce a fine-grained access control to their public APIs. The access control policy is specified in a configuration file and enforced at compile time, using a static analysis tool. 2. The component level. Upon Asterinas Framework is a set of OS components, each of which is responsible for a particular OS functionality, feature, or device. These OS components are Rust crates with two traits: (1) containing safe Rust code, as demanded by the framekernel architecture, and (2) being governed by Asterinas Component System, which can enforce a fine-grained access control to their public APIs. The access control policy is specified in a configuration file and enforced at compile time, using a static analysis tool.
3. The object level. Jinux promotes the philosophy of _everything-is-a-capability_, which means all kernel resources, from files to threads, from virtual memory to physical pages, should be accessed through [capabilities](https://en.wikipedia.org/wiki/Capability-based_security). In Jinux, capabilities are implemented as Rust objects that are constrained in their creation, acquisition, and usage. One common form of capabilities is those with access rights. Wherever possible, access rights are encoded in types (rather than values) so that they can be checked at compile time, eliminating any runtime costs. 3. The object level. Asterinas promotes the philosophy of _everything-is-a-capability_, which means all kernel resources, from files to threads, from virtual memory to physical pages, should be accessed through [capabilities](https://en.wikipedia.org/wiki/Capability-based_security). In Asterinas, capabilities are implemented as Rust objects that are constrained in their creation, acquisition, and usage. One common form of capabilities is those with access rights. Wherever possible, access rights are encoded in types (rather than values) so that they can be checked at compile time, eliminating any runtime costs.
As a zero-cost, least-privilege OS, Jinux provides the best of both worlds: the performance of a monolithic kernel and the security of a microkernel. Like a monolithic kernel, the different parts of Jinux can communicate with the most efficient means, e.g., function calls and memory sharing. In the same spirit as a microkernel, the fundamental security properties of the OS depend on a minimum amount of code (i.e., Jinux Framework). As a zero-cost, least-privilege OS, Asterinas provides the best of both worlds: the performance of a monolithic kernel and the security of a microkernel. Like a monolithic kernel, the different parts of Asterinas can communicate with the most efficient means, e.g., function calls and memory sharing. In the same spirit as a microkernel, the fundamental security properties of the OS depend on a minimum amount of code (i.e., Asterinas Framework).
## Build, test and debug Jinux ## Build, test and debug Asterinas
While most of the code is written in Rust, the project-scope build process is governed by Makefile. The development environment is managed with Docker. Please ensure Docker is installed and can be run without sudo privilege. While most of the code is written in Rust, the project-scope build process is governed by Makefile. The development environment is managed with Docker. Please ensure Docker is installed and can be run without sudo privilege.
### Preparation ### Preparation
1. Download the latest source code of jinux. 1. Download the latest source code of asterinas.
```bash ```bash
git clone [repository url] git clone [repository url]
``` ```
@ -39,7 +39,7 @@ docker pull jinuxdev/jinux:0.2.2
3. Start the development container. 3. Start the development container.
```bash ```bash
docker run -it --privileged --network=host --device=/dev/kvm -v `pwd`:/root/jinux jinuxdev/jinux:0.2.2 docker run -it --privileged --network=host --device=/dev/kvm -v `pwd`:/root/asterinas jinuxdev/jinux:0.2.2
``` ```
**All build and test commands should be run inside the development container.** **All build and test commands should be run inside the development container.**
@ -96,33 +96,33 @@ cargo component-check
#### Regression Test #### Regression Test
This command will automatically run Jinux with the test binaries in `regression/apps` directory. This command will automatically run Asterinas with the test binaries in `regression/apps` directory.
```bash ```bash
make run AUTO_TEST=regression make run AUTO_TEST=regression
``` ```
#### Syscall Test #### Syscall Test
This command will build the syscall test binary and automatically run Jinux with the tests using QEMU. This command will build the syscall test binary and automatically run Asterinas with the tests using QEMU.
```bash ```bash
make run AUTO_TEST=syscall make run AUTO_TEST=syscall
``` ```
Alternatively, if you wish to test it interactively inside a shell in Jinux. Alternatively, if you wish to test it interactively inside a shell in Asterinas.
```bash ```bash
make run BUILD_SYSCALL_TEST=1 make run BUILD_SYSCALL_TEST=1
``` ```
Then, we can run the following script using the Jinux shell to run all syscall test cases. Then, we can run the following script using the Asterinas shell to run all syscall test cases.
```bash ```bash
/opt/syscall_test/run_syscall_test.sh /opt/syscall_test/run_syscall_test.sh
``` ```
### Debug ### Debug
To debug Jinux using [QEMU GDB remote debugging](https://qemu-project.gitlab.io/qemu/system/gdb.html), you could compile Jinux in debug mode, start a Jinux instance and run the GDB interactive shell in another terminal. To debug Asterinas using [QEMU GDB remote debugging](https://qemu-project.gitlab.io/qemu/system/gdb.html), you could compile Asterinas in debug mode, start a Asterinas instance and run the GDB interactive shell in another terminal.
To start a QEMU Jinux VM and wait for debugging connection: To start a QEMU Asterinas VM and wait for debugging connection:
```bash ```bash
make run GDB_SERVER=1 ENABLE_KVM=0 make run GDB_SERVER=1 ENABLE_KVM=0
``` ```
@ -132,33 +132,33 @@ To get the GDB interactive shell:
make run GDB_CLIENT=1 make run GDB_CLIENT=1
``` ```
Currently, the Jinux runner's debugging interface is exposed by unix socket. Thus there shouldn't be multiple debugging instances in the same container. To add debug symbols for the underlying infrastructures such as UEFI firmware or bootloader, please check the runner's source code for details. Currently, the Asterinas runner's debugging interface is exposed by unix socket. Thus there shouldn't be multiple debugging instances in the same container. To add debug symbols for the underlying infrastructures such as UEFI firmware or bootloader, please check the runner's source code for details.
## Code organization ## Code organization
The codebase of Jinux is organized as below. The codebase of Asterinas is organized as below.
* `runner/`: creating a bootable Jinux kernel image along with an initramfs image. It also supports `cargo run` since it is the only package with `main()`. * `runner/`: creating a bootable Asterinas kernel image along with an initramfs image. It also supports `cargo run` since it is the only package with `main()`.
* `kernel/`: defining the entry point of the Jinux kernel. * `kernel/`: defining the entry point of the Asterinas kernel.
* `framework/`: the privileged half of Jinux (allowed to use `unsafe` keyword) * `framework/`: the privileged half of Asterinas (allowed to use `unsafe` keyword)
* `aster-frame`: providing the safe Rust abstractions for low-level resources like CPU, memory, interrupts, etc; * `aster-frame`: providing the safe Rust abstractions for low-level resources like CPU, memory, interrupts, etc;
* `libs`: Privileged libraries. * `libs`: Privileged libraries.
* `services/`: the unprivileged half of Jinux (not allowed to use `unsafe` directly), implementing most of the OS functionalities. * `services/`: the unprivileged half of Asterinas (not allowed to use `unsafe` directly), implementing most of the OS functionalities.
* `comps/`: Jinux OS components; * `comps/`: Asterinas OS components;
* `libs/`: Jinux OS libraries; * `libs/`: Asterinas OS libraries;
* `aster-std`: this is where system calls are implemented. Currently, this crate is too big. It will eventually be decomposed into smaller crates. * `aster-std`: this is where system calls are implemented. Currently, this crate is too big. It will eventually be decomposed into smaller crates.
* `tests/`: providing integration tests written in Rust. * `tests/`: providing integration tests written in Rust.
* `regression/`: providing user-space tests written in C. * `regression/`: providing user-space tests written in C.
* `docs/`: The Jinux book (needs a major update). * `docs/`: The Asterinas book (needs a major update).
## Development status ## Development status
Jinux is under active development. The list below summarizes the progress of important planned features. Asterinas is under active development. The list below summarizes the progress of important planned features.
* Technical novelty * Technical novelty
- [X] Jinux Framework - [X] Asterinas Framework
- [X] Jinux Component System - [X] Asterinas Component System
- [X] Jinux Capabilities - [X] Asterinas Capabilities
* High-level stuff * High-level stuff
* Process management * Process management
- [X] Essential system calls (fork, execve, etc.) - [X] Essential system calls (fork, execve, etc.)
@ -231,6 +231,6 @@ Jinux is under active development. The list below summarizes the progress of imp
## License ## License
The Jinux project is proudly released as a free software The Asterinas project is proudly released as a free software
under the license of [GNU General Public License version 2](LICENSE-GPL). under the license of [GNU General Public License version 2](LICENSE-GPL).
See [COPYRIGHT](COPYRIGHT) for details. See [COPYRIGHT](COPYRIGHT) for details.

2
docs/README.md
View File

@ -1,4 +1,4 @@
# Jinux Documentation # Asterinas Documentation
The documentation is rendered as a book with [mdBook](https://rust-lang.github.io/mdBook/), The documentation is rendered as a book with [mdBook](https://rust-lang.github.io/mdBook/),
which can be installed with `cargo`. which can be installed with `cargo`.

2
docs/book.toml
View File

@ -3,7 +3,7 @@ authors = ["Tate, Hongliang Tian"]
language = "en" language = "en"
multilingual = false multilingual = false
src = "src" src = "src"
title = "Jinux: A Secure, Fast, and Modern OS in Rust" title = "Asterinas: A Secure, Fast, and Modern OS in Rust"
[rust] [rust]
edition = "2021" edition = "2021"

16
docs/src/README.md
View File

@ -14,7 +14,7 @@
# Introduction # Introduction
This document describes Jinux, a secure, fast, and modern OS written in Rust. This document describes Asterinas, a secure, fast, and modern OS written in Rust.
As the project is a work in progress, this document is by no means complete. As the project is a work in progress, this document is by no means complete.
Despite the incompleteness, this evolving document serves several important purposes: Despite the incompleteness, this evolving document serves several important purposes:
@ -50,7 +50,7 @@ OSes, e.g., [Kerla](https://github.com/nuta/kerla),
and [zCore](https://github.com/rcore-os/zCore). Despite their varying degrees of and [zCore](https://github.com/rcore-os/zCore). Despite their varying degrees of
success, none of them are general-purpose, industrial-strength OSes that are or success, none of them are general-purpose, industrial-strength OSes that are or
will ever be competitive with Linux. Eventually, a winner will emerge out of this will ever be competitive with Linux. Eventually, a winner will emerge out of this
market of Rust OSes, and Jinux is our bet for this competition. market of Rust OSes, and Asterinas is our bet for this competition.
Second, Rust OSes are a perfect fit for Second, Rust OSes are a perfect fit for
[Trusted Execution Environments (TEEs)](https://en.wikipedia.org/wiki/Trusted_execution_environment). [Trusted Execution Environments (TEEs)](https://en.wikipedia.org/wiki/Trusted_execution_environment).
@ -79,24 +79,24 @@ relational databases:
[Oracle and IBM are losing ground as Chinese vendors catch up with their US counterparts](https://www.theregister.com/2022/07/06/international_database_vendors_are_losing/). [Oracle and IBM are losing ground as Chinese vendors catch up with their US counterparts](https://www.theregister.com/2022/07/06/international_database_vendors_are_losing/).
Can such success stories be repeated in the field of OSes? I think so. Can such success stories be repeated in the field of OSes? I think so.
There are some China's home-grown OSes like [openKylin](https://www.openkylin.top/index.php?lang=en), but all of them are based on Linux and lack a self-developed There are some China's home-grown OSes like [openKylin](https://www.openkylin.top/index.php?lang=en), but all of them are based on Linux and lack a self-developed
OS _kernel_. The long-term goal of Jinux is to fill this key missing core of the home-grown OSes. OS _kernel_. The long-term goal of Asterinas is to fill this key missing core of the home-grown OSes.
## Architecture Overview ## Architecture Overview
Here is an overview of the architecture of Jinux. Here is an overview of the architecture of Asterinas.
![architecture overview](images/arch_overview.png) ![architecture overview](images/arch_overview.png)
## Features ## Features
**1. Security by design.** Security is our top priority in the design of Jinux. As such, we adopt the widely acknowledged security best practice of [least privilege principle](https://en.wikipedia.org/wiki/Principle_of_least_privilege) and enforce it in a fashion that leverages the full strengths of Rust. To do so, we partition Jinux into two halves: a _privileged_ OS core and _unprivileged_ OS components. All OS components are written entirely in _safe_ Rust and only the privileged OS core **1. Security by design.** Security is our top priority in the design of Asterinas. As such, we adopt the widely acknowledged security best practice of [least privilege principle](https://en.wikipedia.org/wiki/Principle_of_least_privilege) and enforce it in a fashion that leverages the full strengths of Rust. To do so, we partition Asterinas into two halves: a _privileged_ OS core and _unprivileged_ OS components. All OS components are written entirely in _safe_ Rust and only the privileged OS core
is allowed to have _unsafe_ Rust code. Furthermore, we propose the idea of _everything-is-a-capability_, which elevates the status of [capabilities](https://en.wikipedia.org/wiki/Capability-based_security) to the level of a ubiquitous security primitive used throughout the OS. We make novel use of Rust's advanced features (e.g., [type-level programming](https://willcrichton.net/notes/type-level-programming/)) to make capabilities more accessible and efficient. The net result is improved security and uncompromised performance. is allowed to have _unsafe_ Rust code. Furthermore, we propose the idea of _everything-is-a-capability_, which elevates the status of [capabilities](https://en.wikipedia.org/wiki/Capability-based_security) to the level of a ubiquitous security primitive used throughout the OS. We make novel use of Rust's advanced features (e.g., [type-level programming](https://willcrichton.net/notes/type-level-programming/)) to make capabilities more accessible and efficient. The net result is improved security and uncompromised performance.
**2. Trustworthy OS-level virtualization.** OS-level virtualization mechanisms (like Linux's cgroups and namespaces) enable containers, a more lightweight and arguably more popular alternative to virtual machines (VMs). But there is one problem with containers: they are not as secure as VMs (see [StackExchange](https://security.stackexchange.com/questions/169642/what-makes-docker-more-secure-than-vms-or-bare-metal), [LWN](https://lwn.net/Articles/796700/), and [AWS](https://docs.aws.amazon.com/AmazonECS/latest/bestpracticesguide/security-tasks-containers.html)). There is a real risk that malicious containers may exploit privilege escalation bugs in the OS kernel to attack the host. [A study](https://dl.acm.org/doi/10.1145/3274694.3274720) found that 11 out of 88 kernel exploits are effective in breaking the container sandbox. The seemingly inherent insecurity of OS kernels leads to a new breed of container implementations (e.g., [Kata](https://katacontainers.io/) and [gVisor](https://gvisor.dev/)) that are based on VMs, instead of kernels, for isolation and sandboxing. We argue that this unfortunate retreat from OS-level virtualization to VM-based one is unwarranted---if the OS kernels are secure enough. And this is exactly what we plan to achieve with Jinux. We aim to provide a trustworthy OS-level virtualization mechanism on Jinux. **2. Trustworthy OS-level virtualization.** OS-level virtualization mechanisms (like Linux's cgroups and namespaces) enable containers, a more lightweight and arguably more popular alternative to virtual machines (VMs). But there is one problem with containers: they are not as secure as VMs (see [StackExchange](https://security.stackexchange.com/questions/169642/what-makes-docker-more-secure-than-vms-or-bare-metal), [LWN](https://lwn.net/Articles/796700/), and [AWS](https://docs.aws.amazon.com/AmazonECS/latest/bestpracticesguide/security-tasks-containers.html)). There is a real risk that malicious containers may exploit privilege escalation bugs in the OS kernel to attack the host. [A study](https://dl.acm.org/doi/10.1145/3274694.3274720) found that 11 out of 88 kernel exploits are effective in breaking the container sandbox. The seemingly inherent insecurity of OS kernels leads to a new breed of container implementations (e.g., [Kata](https://katacontainers.io/) and [gVisor](https://gvisor.dev/)) that are based on VMs, instead of kernels, for isolation and sandboxing. We argue that this unfortunate retreat from OS-level virtualization to VM-based one is unwarranted---if the OS kernels are secure enough. And this is exactly what we plan to achieve with Asterinas. We aim to provide a trustworthy OS-level virtualization mechanism on Asterinas.
**3. Fast user-mode development.** Traditional OS kernels like Linux are hard to develop, test, and debug. Kernel development involves countless rounds of programming, failing, and rebooting on bare-metal or virtual machines. This way of life is unproductive and painful. Such a pain point is also recognized and partially addressed by [research work](https://www.usenix.org/conference/fast21/presentation/miller), but we think we can do more. In this spirit, we design the OS core to provide high-level APIs that are largely independent of the underlying hardware and implement it with two targets: one target is as part of a regular OS in kernel space and the other is as a library OS in user space. This way, all the OS components of Jinux, which are stacked above the OS core, can be developed, tested, and debugged in user space, which is more friendly to developers than kernel space. **3. Fast user-mode development.** Traditional OS kernels like Linux are hard to develop, test, and debug. Kernel development involves countless rounds of programming, failing, and rebooting on bare-metal or virtual machines. This way of life is unproductive and painful. Such a pain point is also recognized and partially addressed by [research work](https://www.usenix.org/conference/fast21/presentation/miller), but we think we can do more. In this spirit, we design the OS core to provide high-level APIs that are largely independent of the underlying hardware and implement it with two targets: one target is as part of a regular OS in kernel space and the other is as a library OS in user space. This way, all the OS components of Asterinas, which are stacked above the OS core, can be developed, tested, and debugged in user space, which is more friendly to developers than kernel space.
**4. High-fidelity Linux ABI.** An OS without usable applications is useless. So we believe it is important for Jinux to fit in an established and thriving ecosystem of software, such as the one around Linux. This is why we conclude that Jinux should aim at implementing high-fidelity Linux ABI, including the system calls, the proc file system, etc. **4. High-fidelity Linux ABI.** An OS without usable applications is useless. So we believe it is important for Asterinas to fit in an established and thriving ecosystem of software, such as the one around Linux. This is why we conclude that Asterinas should aim at implementing high-fidelity Linux ABI, including the system calls, the proc file system, etc.
**5. TEEs as top-tier targets.** (Todo) **5. TEEs as top-tier targets.** (Todo)

4
docs/src/capabilities/README.md
View File

@ -20,12 +20,12 @@ capabilities in a limited fashion, mostly as a means to limit the access from
external users (e.g., via syscall), rather than a mechanism to enforce advanced external users (e.g., via syscall), rather than a mechanism to enforce advanced
security policies internally (e.g., module-level isolation). security policies internally (e.g., module-level isolation).
So we ask this question: is it possible to use capabilities as a _ubitiquous_ security primitive throughout Jinux to enhance the security and robustness of the So we ask this question: is it possible to use capabilities as a _ubitiquous_ security primitive throughout Asterinas to enhance the security and robustness of the
OS? Specifically, we propose a new principle called "_everything is a capability_". OS? Specifically, we propose a new principle called "_everything is a capability_".
Here, "everything" refers to any type of OS resource, internal or external alike. Here, "everything" refers to any type of OS resource, internal or external alike.
In traditional OSes, treating everything as a capability is unrewarding In traditional OSes, treating everything as a capability is unrewarding
because (1) capabilities themselves are unreliable due to memory safety problems because (1) capabilities themselves are unreliable due to memory safety problems
, and (2) capabilities are no free lunch as they incur memory and CPU overheads. But these arguments may no longer stand in a well-designed Rust OS like Jinux. , and (2) capabilities are no free lunch as they incur memory and CPU overheads. But these arguments may no longer stand in a well-designed Rust OS like Asterinas.
Because the odds of memory safety bugs are minimized and Because the odds of memory safety bugs are minimized and
advanced Rust features like type-level programming allow us to implement advanced Rust features like type-level programming allow us to implement
capabilities as a zero-cost abstraction. capabilities as a zero-cost abstraction.

2
docs/src/capabilities/zero_cost_capabilities.md
View File

@ -1,6 +1,6 @@
# Zero-Cost Capabilities # Zero-Cost Capabilities
To strengthen the security of Jinux, we aim to implement all kinds of OS resources To strengthen the security of Asterinas, we aim to implement all kinds of OS resources
as capabilities. As the capabilities are going to be used throughout the OS, as capabilities. As the capabilities are going to be used throughout the OS,
it is highly desirable to minimize their costs. For this purpose, it is highly desirable to minimize their costs. For this purpose,
we want to implement capabilities as a _zero-cost abstraction_. we want to implement capabilities as a _zero-cost abstraction_.

6
docs/src/privilege_separation/README.md
View File

@ -1,15 +1,15 @@
# Privilege Separation # Privilege Separation
One fundamental design goal of Jinux is to support _privilege separation_, i.e., the separation between the privileged OS core and the unprivileged OS components. The privileged portion is allowed to use `unsafe` keyword to carry out dangerous tasks like accessing CPU registers, manipulating stack frames, and doing MMIO or PIO. In contrast, the unprivileged portion, which forms the majority of the OS, must be free from `unsafe` code. With privilege separation, the memory safety of Jinux can be boiled down to the correctness of the privileged OS core, regardless of the correctness of the unprivileged OS components, thus reducing the size of TCB significantly. One fundamental design goal of Asterinas is to support _privilege separation_, i.e., the separation between the privileged OS core and the unprivileged OS components. The privileged portion is allowed to use `unsafe` keyword to carry out dangerous tasks like accessing CPU registers, manipulating stack frames, and doing MMIO or PIO. In contrast, the unprivileged portion, which forms the majority of the OS, must be free from `unsafe` code. With privilege separation, the memory safety of Asterinas can be boiled down to the correctness of the privileged OS core, regardless of the correctness of the unprivileged OS components, thus reducing the size of TCB significantly.
To put privilege separation into perspective, let's compare the architectures To put privilege separation into perspective, let's compare the architectures
of the monolithic kernels, microkernels, and Jinux. of the monolithic kernels, microkernels, and Asterinas.
![Arch comparison](../images/arch_comparison.png) ![Arch comparison](../images/arch_comparison.png)
The diagram above highlights the characteristics of different OS architectures The diagram above highlights the characteristics of different OS architectures
in terms of communication overheads and the TCB for memory safety. in terms of communication overheads and the TCB for memory safety.
Thanks to privilege separation, Jinux promises the benefit of being _as safe as a microkernel and as fast as a monolithic kernel_. Thanks to privilege separation, Asterinas promises the benefit of being _as safe as a microkernel and as fast as a monolithic kernel_.
Privilege separation is an interesting research problem, prompting us to Privilege separation is an interesting research problem, prompting us to
answer a series of technical questions. answer a series of technical questions.

6
docs/src/privilege_separation/pci_virtio_drivers.md
View File

@ -22,7 +22,7 @@ Here are some of the elements in PCI-based Virtio devices that may involve `unsa
### Privileged part ### Privileged part
```rust ```rust
// file: jinux-core-libs/pci-io-port/lib.rs // file: aster-core-libs/pci-io-port/lib.rs
use x86::IoPort; use x86::IoPort;
/// The I/O port to write an address in the PCI /// The I/O port to write an address in the PCI
@ -49,7 +49,7 @@ pub const PCI_DATA_PORT: IoPort<u32> = {
### Unprivileged part ### Unprivileged part
```rust ```rust
// file: jinux-comps/pci/lib.rs // file: aster-comps/pci/lib.rs
use pci_io_port::{PCI_ADDR_PORT, PCI_DATA_PORT}; use pci_io_port::{PCI_ADDR_PORT, PCI_DATA_PORT};
/// The PCI configuration space, which enables the discovery, /// The PCI configuration space, which enables the discovery,
@ -128,7 +128,7 @@ pub struct PciCapabilities {
Most code of Virtio drivers can be unprivileged thanks to the abstractions of `VmPager` and `VmCell` provided by the OS core. Most code of Virtio drivers can be unprivileged thanks to the abstractions of `VmPager` and `VmCell` provided by the OS core.
```rust ```rust
// file: jinux-comp-libs/virtio/transport.rs // file: aster-comp-libs/virtio/transport.rs
/// The transport layer for configuring a Virtio device. /// The transport layer for configuring a Virtio device.
pub struct VirtioTransport { pub struct VirtioTransport {

36
docs/src/privilege_separation/syscall_workflow.md
View File

@ -138,7 +138,7 @@ impl<T, P: Write> UserPtr<T, P> {
} }
``` ```
The examples reveal two important considerations in designing Jinux: The examples reveal two important considerations in designing Asterinas:
1. Exposing _truly_ safe APIs. The privileged OS core must expose _truly safe_ APIs: however buggy or silly the unprivileged OS components may be written, they must _not_ cause undefined behaviors. 1. Exposing _truly_ safe APIs. The privileged OS core must expose _truly safe_ APIs: however buggy or silly the unprivileged OS components may be written, they must _not_ cause undefined behaviors.
2. Handling _arbitrary_ pointers safely. The safe API of the OS core must provide a safe way to deal with arbitrary pointers. 2. Handling _arbitrary_ pointers safely. The safe API of the OS core must provide a safe way to deal with arbitrary pointers.
@ -146,15 +146,15 @@ With the two points in mind, let's get back to our main goal of privilege separa
## Code organization with privilege separation ## Code organization with privilege separation
Our first step is to separate privileged and unprivileged code in the codebase of Jinux. For our purpose of demonstrating a syscall handling framework, a minimal codebase may look like the following. Our first step is to separate privileged and unprivileged code in the codebase of Asterinas. For our purpose of demonstrating a syscall handling framework, a minimal codebase may look like the following.
```text ```text
. .
├── jinux ├── asterinas
│   ├── src │   ├── src
│ │   └── main.rs │ │   └── main.rs
│   └── Cargo.toml │   └── Cargo.toml
├── jinux-core ├── aster-core
│   ├── src │   ├── src
│ │   ├── lib.rs │ │   ├── lib.rs
│ │   ├── syscall_handler.rs │ │   ├── syscall_handler.rs
@ -162,7 +162,7 @@ Our first step is to separate privileged and unprivileged code in the codebase o
│ │ ├── vmo.rs │ │ ├── vmo.rs
│ │ └── vmar.rs │ │ └── vmar.rs
│   └── Cargo.toml │   └── Cargo.toml
├── jinux-core-libs ├── aster-core-libs
│ ├── linux-abi-types │ ├── linux-abi-types
│ │   ├── src │ │   ├── src
│ │   │ └── lib.rs │ │   │ └── lib.rs
@ -171,34 +171,34 @@ Our first step is to separate privileged and unprivileged code in the codebase o
│ ├── src │ ├── src
│   │ └── lib.rs │   │ └── lib.rs
│  └── Cargo.toml │  └── Cargo.toml
├── jinux-comps ├── aster-comps
│   └── linux-syscall │   └── linux-syscall
│ ├── src │ ├── src
│   │ └── lib.rs │   │ └── lib.rs
│   └── Cargo.toml │   └── Cargo.toml
└── jinux-comp-libs └── aster-comp-libs
   └── linux-abi    └── linux-abi
├── src ├── src
  │ └── lib.rs   │ └── lib.rs
   └── Cargo.toml    └── Cargo.toml
``` ```
The ultimate build target of the codebase is the `jinux` crate, which is an OS kernel that consists of a privileged OS core (crate `jinux-core`) and multiple OS components (the crates under `jinux-comps/`). The ultimate build target of the codebase is the `asterinas` crate, which is an OS kernel that consists of a privileged OS core (crate `aster-core`) and multiple OS components (the crates under `aster-comps/`).
For the sake of privilege separation, only crate `jinux` and `jinux-core` along with the crates under `jinux-core-libs` are allowed to use the `unsafe` keyword. To the contrary, the crates under `jinux-comps/` along with their dependent crates under `jinux-comp-libs/` are not allowed to use `unsafe` directly; they may only borrow the superpower of `unsafe` by using the safe API exposed by `jinux-core` or the crates under `jinux-core-libs`. To summarize, the memory safety of the OS only relies on a small and well-defined TCB that constitutes the `jinux` and `jinux-core` crate plus the crates under `jinux-core-libs/`. For the sake of privilege separation, only crate `asterinas` and `aster-core` along with the crates under `aster-core-libs` are allowed to use the `unsafe` keyword. To the contrary, the crates under `aster-comps/` along with their dependent crates under `aster-comp-libs/` are not allowed to use `unsafe` directly; they may only borrow the superpower of `unsafe` by using the safe API exposed by `aster-core` or the crates under `aster-core-libs`. To summarize, the memory safety of the OS only relies on a small and well-defined TCB that constitutes the `asterinas` and `aster-core` crate plus the crates under `aster-core-libs/`.
Under this setting, all implementation of system calls goes to the `linux-syscall` crate. We are about to show that the _safe_ API provided by `jinux-core` is powerful enough to enable the _safe_ implementation of `linux-syscall`. Under this setting, all implementation of system calls goes to the `linux-syscall` crate. We are about to show that the _safe_ API provided by `aster-core` is powerful enough to enable the _safe_ implementation of `linux-syscall`.
## Crate `jinux-core` ## Crate `aster-core`
For our purposes here, the two most relevant APIs provided by `jinux-core` is the abstraction for syscall handlers and virtual memory (VM). For our purposes here, the two most relevant APIs provided by `aster-core` is the abstraction for syscall handlers and virtual memory (VM).
### Syscall handlers ### Syscall handlers
The `SyscallHandler` abstraction enables the OS core to hide the low-level, architectural-dependent aspects of syscall handling workflow (e.g., user-kernel switching and CPU register manipulation) and allow the unprivileged OS components to implement system calls. The `SyscallHandler` abstraction enables the OS core to hide the low-level, architectural-dependent aspects of syscall handling workflow (e.g., user-kernel switching and CPU register manipulation) and allow the unprivileged OS components to implement system calls.
```rust ```rust
// file: jinux-core/src/syscall_handler.rs // file: aster-core/src/syscall_handler.rs
pub trait SyscallHandler { pub trait SyscallHandler {
fn handle_syscall(&self, ctx: &mut SyscallContext); fn handle_syscall(&self, ctx: &mut SyscallContext);
@ -243,8 +243,8 @@ an important concept that we will elaborate on later. Basically, they are capabi
Here we demonstrate how to leverage the APIs of `ksos-core` to implement system calls with safe Rust code in crate `linux-syscall`. Here we demonstrate how to leverage the APIs of `ksos-core` to implement system calls with safe Rust code in crate `linux-syscall`.
```rust ```rust
// file: jinux-comps/linux-syscall/src/lib.rs // file: aster-comps/linux-syscall/src/lib.rs
use jinux_core::{SyscallContext, SyscallHandler, Vmar}; use aster_core::{SyscallContext, SyscallHandler, Vmar};
use linux_abi::{SyscallNum::*, UserPtr, RawFd, RawTimeVal, RawTimeZone}; use linux_abi::{SyscallNum::*, UserPtr, RawFd, RawTimeVal, RawTimeZone};
pub struct SampleHandler; pub struct SampleHandler;
@ -315,7 +315,7 @@ impl SampleHandler {
This crate defines a marker trait `Pod`, which represents plain-old data. This crate defines a marker trait `Pod`, which represents plain-old data.
```rust ```rust
/// file: jinux-core-libs/pod/src/lib.rs /// file: aster-core-libs/pod/src/lib.rs
/// A marker trait for plain old data (POD). /// A marker trait for plain old data (POD).
/// ///
@ -388,7 +388,7 @@ unsafe impl<T: Pod, const N> [T; N] for Pod {}
## Crate `linux-abi-type` ## Crate `linux-abi-type`
```rust ```rust
// file: jinux-core-libs/linux-abi-types // file: aster-core-libs/linux-abi-types
use pod::Pod; use pod::Pod;
pub type RawFd = i32; pub type RawFd = i32;
@ -404,7 +404,7 @@ unsafe impl Pod for RawTimeVal {}
## Crate `linux-abi` ## Crate `linux-abi`
```rust ```rust
// file: jinux-comp-libs/linux-abi // file: aster-comp-libs/linux-abi
pub use linux_abi_types::*; pub use linux_abi_types::*;
pub enum SyscallNum { pub enum SyscallNum {

16
framework/README.md
View File

@ -1,20 +1,20 @@
# Jinux Framework # Asterinas Framework
Jinux Framework is a Rust OS framework that facilitates the development of and innovation in OS kernels written in Rust. Asterinas Framework is a Rust OS framework that facilitates the development of and innovation in OS kernels written in Rust.
## An overview ## An overview
Jinux Framework provides a solid foundation for Rust developers to build their own OS kernels. While Jinux Framework origins from Jinux, the first ever framekernel, Jinux Framework is well suited for building OS kernels of any architecture, be it a framekernel, a monolithic kernel, or a microkernel. Asterinas Framework provides a solid foundation for Rust developers to build their own OS kernels. While Asterinas Framework origins from Asterinas, the first ever framekernel, Asterinas Framework is well suited for building OS kernels of any architecture, be it a framekernel, a monolithic kernel, or a microkernel.
Jinux Framework offers the following key values. Asterinas Framework offers the following key values.
1. **Lowering the entry bar for OS innovation.** Building an OS from scratch is not easy. Not to mention a novel one. Before adding any novel or interesting feature, an OS developer must first have something runnable, which must include basic functionalities for managing CPU, memory, and interrupts. Jinux Framework has laid this groundwork so that OS developers do not have to deal with the most low-level, error-prone, architecture-specific aspects of OS development themselves. 1. **Lowering the entry bar for OS innovation.** Building an OS from scratch is not easy. Not to mention a novel one. Before adding any novel or interesting feature, an OS developer must first have something runnable, which must include basic functionalities for managing CPU, memory, and interrupts. Asterinas Framework has laid this groundwork so that OS developers do not have to deal with the most low-level, error-prone, architecture-specific aspects of OS development themselves.
2. **Enhancing the memory safety of Rust OSes.** Jinux Framework encapsulates low-level, machine-oriented unsafe Rust code into high-level, machine-agnostic safe APIs. These APIs are carefully designed and implemented to be sound and minimal, ensuring the memory safety of any safe Rust callers. Our experience in building Jinux has shown that Jinux Framework is powerful enough to allow a feature-rich, Linux-compatible kernel to be completely written in safe Rust, including its device drivers. 2. **Enhancing the memory safety of Rust OSes.** Asterinas Framework encapsulates low-level, machine-oriented unsafe Rust code into high-level, machine-agnostic safe APIs. These APIs are carefully designed and implemented to be sound and minimal, ensuring the memory safety of any safe Rust callers. Our experience in building Asterinas has shown that Asterinas Framework is powerful enough to allow a feature-rich, Linux-compatible kernel to be completely written in safe Rust, including its device drivers.
3. **Promoting code reuse across Rust OS projects.** Shipped as crates, Rust code can be reused across projects---except when they are OSes. A crate that implements a feature or driver for OS A can hardly be reused by OS B because the crate must be [`no_std`](https://docs.rust-embedded.org/book/intro/no-std.html#summary) and depend on the infrastructure APIs provided by OS A, which are obviously different from that provided by OS B. This incompatibility problem can be resolved by Jinux Framework as it can serve as a common ground across different Rust OS projects, as long as they are built upon Jinux Framework. 3. **Promoting code reuse across Rust OS projects.** Shipped as crates, Rust code can be reused across projects---except when they are OSes. A crate that implements a feature or driver for OS A can hardly be reused by OS B because the crate must be [`no_std`](https://docs.rust-embedded.org/book/intro/no-std.html#summary) and depend on the infrastructure APIs provided by OS A, which are obviously different from that provided by OS B. This incompatibility problem can be resolved by Asterinas Framework as it can serve as a common ground across different Rust OS projects, as long as they are built upon Asterinas Framework.
4. **Boost productivity with user-mode development.** Traditionally, developing a kernel feature involves countless rounds of coding, failing, and rebooting on bare-metal or virtual machines, which is a painfully slow process. Jinux Framework accelerates the process by allowing high-level OS features like file systems and network stacks to be quickly tested in user mode, making the experience of OS development as smooth as that of application development. To support user-mode development, Jinux Framework is implemented for the Linux platform, in addition to bare-mental or virtual machine environments. 4. **Boost productivity with user-mode development.** Traditionally, developing a kernel feature involves countless rounds of coding, failing, and rebooting on bare-metal or virtual machines, which is a painfully slow process. Asterinas Framework accelerates the process by allowing high-level OS features like file systems and network stacks to be quickly tested in user mode, making the experience of OS development as smooth as that of application development. To support user-mode development, Asterinas Framework is implemented for the Linux platform, in addition to bare-mental or virtual machine environments.
## Framework APIs ## Framework APIs

2
framework/aster-frame/src/arch/x86/boot/linux_boot/boot_params.rs
View File

@ -3,7 +3,7 @@
//! The bootloader will deliver the address of the `BootParams` struct //! The bootloader will deliver the address of the `BootParams` struct
//! as the argument of the kernel entrypoint. So we must define a Linux //! as the argument of the kernel entrypoint. So we must define a Linux
//! ABI compatible struct in Rust, despite that most of the fields are //! ABI compatible struct in Rust, despite that most of the fields are
//! currently not needed by Jinux. //! currently not needed by Asterinas.
//! //!
#[derive(Copy, Clone, Debug)] #[derive(Copy, Clone, Debug)]

2
framework/aster-frame/src/arch/x86/boot/linux_boot/mod.rs
View File

@ -152,5 +152,5 @@ unsafe extern "sysv64" fn __linux64_boot(params_ptr: *const boot_params::BootPar
init_framebuffer_info, init_framebuffer_info,
init_memory_regions, init_memory_regions,
); );
crate::boot::call_jinux_main(); crate::boot::call_aster_main();
} }

4
framework/aster-frame/src/arch/x86/boot/linux_boot/setup/src/header.S
View File

@ -9,8 +9,8 @@
// Some of the fields filled with a 0xab* values should be filled // Some of the fields filled with a 0xab* values should be filled
// by the runner, which is the only tool after building and can // by the runner, which is the only tool after building and can
// access the info of the payload. // access the info of the payload.
// Jinux will use only a few of these fields, and some of them // Asterinas will use only a few of these fields, and some of them
// are filled by the loader and will be read by Jinux. // are filled by the loader and will be read by Asterinas.
CODE32_START = 0x100000 CODE32_START = 0x100000

2
framework/aster-frame/src/arch/x86/boot/linux_boot/setup/src/loader.rs
View File

@ -24,6 +24,6 @@ pub fn load_elf(file: &[u8]) -> u32 {
} }
} }
// Return the Linux 32-bit Boot Protocol entry point defined by Jinux. // Return the Linux 32-bit Boot Protocol entry point defined by Asterinas.
0x8001000 0x8001000
} }

4
framework/aster-frame/src/arch/x86/boot/linux_boot/setup/src/main.rs
View File

@ -9,7 +9,7 @@ use core::arch::{asm, global_asm};
global_asm!(include_str!("header.S")); global_asm!(include_str!("header.S"));
unsafe fn call_jinux_entrypoint(entrypoint: u32, boot_params_ptr: u32) -> ! { unsafe fn call_aster_entrypoint(entrypoint: u32, boot_params_ptr: u32) -> ! {
asm!("mov esi, {}", in(reg) boot_params_ptr); asm!("mov esi, {}", in(reg) boot_params_ptr);
asm!("mov eax, {}", in(reg) entrypoint); asm!("mov eax, {}", in(reg) entrypoint);
asm!("jmp eax"); asm!("jmp eax");
@ -34,7 +34,7 @@ pub extern "cdecl" fn _rust_setup_entry(boot_params_ptr: u32) -> ! {
println!("[setup] entrypoint: {:#x}", entrypoint); println!("[setup] entrypoint: {:#x}", entrypoint);
// Safety: the entrypoint and the ptr is valid. // Safety: the entrypoint and the ptr is valid.
unsafe { call_jinux_entrypoint(entrypoint, boot_params_ptr) }; unsafe { call_aster_entrypoint(entrypoint, boot_params_ptr) };
} }
#[panic_handler] #[panic_handler]

4
framework/aster-frame/src/arch/x86/boot/mod.rs
View File

@ -1,4 +1,4 @@
//! The x86 boot module defines the entrypoints of Jinux and //! The x86 boot module defines the entrypoints of Asterinas and
//! the corresponding headers for different x86 boot protocols. //! the corresponding headers for different x86 boot protocols.
//! //!
//! We directly support //! We directly support
@ -9,7 +9,7 @@
//! //!
//! without any additional configurations. //! without any additional configurations.
//! //!
//! Jinux diffrentiates the boot protocol by the entry point //! Asterinas diffrentiates the boot protocol by the entry point
//! chosen by the boot loader. In each entry point function, //! chosen by the boot loader. In each entry point function,
//! the universal callback registeration method from //! the universal callback registeration method from
//! `crate::boot` will be called. Thus the initialization of //! `crate::boot` will be called. Thus the initialization of

2
framework/aster-frame/src/arch/x86/boot/multiboot/mod.rs
View File

@ -339,5 +339,5 @@ unsafe extern "sysv64" fn __multiboot_entry(boot_magic: u32, boot_params: u64) -
init_framebuffer_info, init_framebuffer_info,
init_memory_regions, init_memory_regions,
); );
crate::boot::call_jinux_main(); crate::boot::call_aster_main();
} }

2
framework/aster-frame/src/arch/x86/boot/multiboot2/mod.rs
View File

@ -172,5 +172,5 @@ unsafe extern "sysv64" fn __multiboot2_entry(boot_magic: u32, boot_params: u64)
init_framebuffer_info, init_framebuffer_info,
init_memory_regions, init_memory_regions,
); );
crate::boot::call_jinux_main(); crate::boot::call_aster_main();
} }

2
framework/aster-frame/src/boot/kcmdline.rs
View File

@ -1,6 +1,6 @@
//! The module to parse kernel command-line arguments. //! The module to parse kernel command-line arguments.
//! //!
//! The format of the Jinux command line string conforms //! The format of the Asterinas command line string conforms
//! to the Linux kernel command line rules: //! to the Linux kernel command line rules:
//! //!
//! https://www.kernel.org/doc/html/v6.4/admin-guide/kernel-parameters.html //! https://www.kernel.org/doc/html/v6.4/admin-guide/kernel-parameters.html

10
framework/aster-frame/src/boot/mod.rs
View File

@ -60,7 +60,7 @@ macro_rules! define_global_static_boot_arguments {
/// ///
/// For the introduction of a new boot protocol, the entry point could be a novel /// For the introduction of a new boot protocol, the entry point could be a novel
/// one. The entry point function should register all the boot initialization /// one. The entry point function should register all the boot initialization
/// methods before `jinux_main` is called. A boot initialization method takes a /// methods before `aster_main` is called. A boot initialization method takes a
/// reference of the global static boot information variable and initialize it, /// reference of the global static boot information variable and initialize it,
/// so that the boot information it represents could be accessed in the kernel /// so that the boot information it represents could be accessed in the kernel
/// anywhere. /// anywhere.
@ -104,16 +104,16 @@ pub fn init() {
/// Call the framework-user defined entrypoint of the actual kernel. /// Call the framework-user defined entrypoint of the actual kernel.
/// ///
/// Any kernel that uses the aster-frame crate should define a function named /// Any kernel that uses the aster-frame crate should define a function named
/// `jinux_main` as the entrypoint. /// `aster_main` as the entrypoint.
pub fn call_jinux_main() -> ! { pub fn call_aster_main() -> ! {
#[cfg(not(ktest))] #[cfg(not(ktest))]
unsafe { unsafe {
// The entry point of kernel code, which should be defined by the package that // The entry point of kernel code, which should be defined by the package that
// uses aster-frame. // uses aster-frame.
extern "Rust" { extern "Rust" {
fn jinux_main() -> !; fn aster_main() -> !;
} }
jinux_main(); aster_main();
} }
#[cfg(ktest)] #[cfg(ktest)]
{ {

2
framework/aster-frame/src/lib.rs
View File

@ -1,4 +1,4 @@
//! The framework part of Jinux. //! The framework part of Asterinas.
#![feature(alloc_error_handler)] #![feature(alloc_error_handler)]
#![feature(const_maybe_uninit_zeroed)] #![feature(const_maybe_uninit_zeroed)]
#![feature(const_mut_refs)] #![feature(const_mut_refs)]

4
framework/libs/ktest/src/lib.rs
View File

@ -1,9 +1,9 @@
//! # The kernel mode testing framework of Jinux. //! # The kernel mode testing framework of Asterinas.
//! //!
//! `ktest` stands for kernel-mode testing framework. Its goal is to provide a //! `ktest` stands for kernel-mode testing framework. Its goal is to provide a
//! `cargo test`-like experience for any `#![no_std]` bare metal crates. //! `cargo test`-like experience for any `#![no_std]` bare metal crates.
//! //!
//! In Jinux, all the tests written in the source tree of the crates will be run //! In Asterinas, all the tests written in the source tree of the crates will be run
//! immediately after the initialization of aster-frame. Thus you can use any //! immediately after the initialization of aster-frame. Thus you can use any
//! feature provided by the frame including the heap allocator, etc. //! feature provided by the frame including the heap allocator, etc.
//! //!

4
kernel/main.rs
View File

@ -1,13 +1,13 @@
#![no_std] #![no_std]
#![no_main] #![no_main]
// The `export_name` attribute for the `jinux_main` entrypoint requires the removal of safety check. // The `export_name` attribute for the `aster_main` entrypoint requires the removal of safety check.
// Please be aware that the kernel is not allowed to introduce any other unsafe operations. // Please be aware that the kernel is not allowed to introduce any other unsafe operations.
// #![forbid(unsafe_code)] // #![forbid(unsafe_code)]
extern crate aster_frame; extern crate aster_frame;
use aster_frame::early_println; use aster_frame::early_println;
#[export_name = "jinux_main"] #[export_name = "aster_main"]
pub fn main() -> ! { pub fn main() -> ! {
aster_frame::init(); aster_frame::init();
early_println!("[kernel] finish init aster_frame"); early_println!("[kernel] finish init aster_frame");

2
regression/apps/scripts/shell_cmd.sh
View File

@ -31,7 +31,7 @@ find . -name "*shell_cmd*"
mkdir foo mkdir foo
rmdir foo rmdir foo
echo "Hello world from jinux" > hello.txt echo "Hello world from asterinas" > hello.txt
rm hello.txt rm hello.txt
cd .. cd ..

2
regression/apps/signal_c/signal_test.c
View File

@ -184,7 +184,7 @@ int test_handle_sigfpe() {
c = div_maybe_zero(a, b); c = div_maybe_zero(a, b);
fxsave(y); fxsave(y);
// jinux does not save and restore fpregs now, so we emit this check. // Asterinas does not save and restore fpregs now, so we emit this check.
// if (memcmp(x, y, 512) != 0) { // if (memcmp(x, y, 512) != 0) {
// THROW_ERROR("floating point registers are modified"); // THROW_ERROR("floating point registers are modified");
// } // }

2
services/comps/block/src/lib.rs
View File

@ -1,4 +1,4 @@
//! The block devices of jinux //! The block devices of Asterinas.
#![no_std] #![no_std]
#![forbid(unsafe_code)] #![forbid(unsafe_code)]
#![feature(fn_traits)] #![feature(fn_traits)]

2
services/comps/console/src/lib.rs
View File

@ -1,4 +1,4 @@
//! The console device of jinux //! The console device of Asterinas.
#![no_std] #![no_std]
#![forbid(unsafe_code)] #![forbid(unsafe_code)]
#![feature(fn_traits)] #![feature(fn_traits)]

2
services/comps/framebuffer/src/lib.rs
View File

@ -1,4 +1,4 @@
//! The framebuffer of jinux //! The framebuffer of Asterinas.
#![no_std] #![no_std]
#![forbid(unsafe_code)] #![forbid(unsafe_code)]
#![feature(strict_provenance)] #![feature(strict_provenance)]

2
services/comps/input/src/lib.rs
View File

@ -1,4 +1,4 @@
//! The input devices of jinux //! The input devices of Asterinas.
#![no_std] #![no_std]
#![forbid(unsafe_code)] #![forbid(unsafe_code)]
#![feature(fn_traits)] #![feature(fn_traits)]

2
services/comps/time/src/lib.rs
View File

@ -1,4 +1,4 @@
//! The system time of jinux //! The system time of Asterinas.
#![no_std] #![no_std]
#![forbid(unsafe_code)] #![forbid(unsafe_code)]

2
services/comps/virtio/src/lib.rs
View File

@ -1,4 +1,4 @@
//! The virtio of jinux //! The virtio of Asterinas.
#![no_std] #![no_std]
#![forbid(unsafe_code)] #![forbid(unsafe_code)]
#![allow(dead_code)] #![allow(dead_code)]

2
services/libs/aster-rights-proc/src/lib.rs
View File

@ -1,4 +1,4 @@
//！This crate defines the require procedural macros to implement capability for jinux. //！This crate defines the require procedural macros to implement capability for Asterinas.
//! When use this crate, typeflags and typeflags-util should also be added as dependency. //! When use this crate, typeflags and typeflags-util should also be added as dependency.
//! //!
//! The require macro are used to ensure that an object has the enough capability to call the function. //! The require macro are used to ensure that an object has the enough capability to call the function.

2
services/libs/aster-std/src/lib.rs
View File

@ -1,4 +1,4 @@
//! The std library of jinux //! The std library of Asterinas.
#![no_std] #![no_std]
#![forbid(unsafe_code)] #![forbid(unsafe_code)]
#![allow(dead_code)] #![allow(dead_code)]

4
services/libs/aster-std/src/vm/mod.rs
View File

@ -10,8 +10,8 @@
//! [Zircon](https://fuchsia.dev/fuchsia-src/reference/kernel_objects/vm_object). //! [Zircon](https://fuchsia.dev/fuchsia-src/reference/kernel_objects/vm_object).
//! As capabilities, the two abstractions are aligned with our goal //! As capabilities, the two abstractions are aligned with our goal
//! of everything-is-a-capability, although their specifications and //! of everything-is-a-capability, although their specifications and
//! implementations in C/C++ cannot apply directly to Jinux. //! implementations in C/C++ cannot apply directly to Asterinas.
//! In Jinux, VMARs and VMOs, as well as other capabilities, are implemented //! In Asterinas, VMARs and VMOs, as well as other capabilities, are implemented
//! as zero-cost capabilities. //! as zero-cost capabilities.
pub mod page_fault_handler; pub mod page_fault_handler;

2
services/libs/aster-util/src/lib.rs
View File

@ -1,4 +1,4 @@
//! The util of jinux //! The util of Asterinas.
#![no_std] #![no_std]
#![forbid(unsafe_code)] #![forbid(unsafe_code)]

6
services/libs/comp-sys/cargo-component/README.md
View File

@ -1,15 +1,15 @@
## Overview ## Overview
The crate contains cargo-component, a cargo subcommand to enable component-level access control in Jinux. For more info about Jinux component system, see the [RFC](https://github.com/jinzhao-dev/jinux/issues/58). The implementation mainly follows [rust clippy](https://github.com/rust-lang/rust-clippy). Internally, this tool will call `cargo check` to compile the whole project and bases the analysis on MIR. The crate contains cargo-component, a cargo subcommand to enable component-level access control in Asterinas. For more info about Asterinas component system, see the [RFC](https://github.com/jinzhao-dev/Asterinas/issues/58). The implementation mainly follows [rust clippy](https://github.com/rust-lang/rust-clippy). Internally, this tool will call `cargo check` to compile the whole project and bases the analysis on MIR.
## install ## install
After running `make setup` for jinux, this crate can be created with cargo. After running `make setup` for Asterinas, this crate can be created with cargo.
```shell ```shell
cargo install --path . cargo install --path .
``` ```
This will install two binaries `cargo-component` and `component-driver` at `$HOME/.cargo/bin`(by default, it depends on the cargo config). This will install two binaries `cargo-component` and `component-driver` at `$HOME/.cargo/bin`(by default, it depends on the cargo config).
## Usage ## Usage
Use `cargo component` or `cargo component check` or `cargo component audit`. The three commands are the same now. For jinux, we shoud use another alias command `cargo component-check`, which was defined in `src/.cargo/config.toml`. Use `cargo component` or `cargo component check` or `cargo component audit`. The three commands are the same now. For Asterinas, we shoud use another alias command `cargo component-check`, which was defined in `src/.cargo/config.toml`.
### Two notes: ### Two notes:
- The directory **where you run the command** should contains a `Components.toml` config file, where defines all components and whitelist. - The directory **where you run the command** should contains a `Components.toml` config file, where defines all components and whitelist.

2
services/libs/typeflags-util/src/lib.rs
View File

@ -1,7 +1,7 @@
//! The content of this crate is from another project CapComp. //! The content of this crate is from another project CapComp.
//! This crate defines common type level operations, like SameAsOp, and Bool type operations. //! This crate defines common type level operations, like SameAsOp, and Bool type operations.
//! Besides, this crate defines operations to deal with type sets, like SetContain and SetInclude. //! Besides, this crate defines operations to deal with type sets, like SetContain and SetInclude.
//! When use jinux-typeflags or aster-rights-poc, this crate should also be added as a dependency. //! When use typeflags or aster-rights-poc, this crate should also be added as a dependency.
#![no_std] #![no_std]
pub mod assert; pub mod assert;
pub mod bool; pub mod bool;

2
services/libs/typeflags/src/lib.rs
View File

@ -1,4 +1,4 @@
//！This crate defines the procedural macro typeflags to implement capability for jinux. //！This crate defines the procedural macro typeflags to implement capability for Asterinas.
//! When using this crate, typeflags-util should also be added as dependency. //! When using this crate, typeflags-util should also be added as dependency.
//! This is due to typeflgas is a proc-macro crate, which is only allowed to export proc-macro interfaces. //! This is due to typeflgas is a proc-macro crate, which is only allowed to export proc-macro interfaces.
//! So we leave the common type-level operations and structures defined in typeflags-util. //! So we leave the common type-level operations and structures defined in typeflags-util.

16
tools/bump_version.sh
View File

@ -1,6 +1,6 @@
#!/bin/bash #!/bin/bash
# This script is used to update Jinux version numbers in all relevant files in the repository. # This script is used to update Asterinas version numbers in all relevant files in the repository.
# Usage: ./tools/bump_version.sh <new_version> # Usage: ./tools/bump_version.sh <new_version>
# Update Cargo style versions (`version = "{version}"`) in file $1 # Update Cargo style versions (`version = "{version}"`) in file $1
@ -16,9 +16,9 @@ update_image_versions() {
} }
SCRIPT_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd ) SCRIPT_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
JINUX_SRC_DIR=${SCRIPT_DIR}/.. ASTER_SRC_DIR=${SCRIPT_DIR}/..
CARGO_TOML_PATH=${JINUX_SRC_DIR}/Cargo.toml CARGO_TOML_PATH=${ASTER_SRC_DIR}/Cargo.toml
VERSION_PATH=${JINUX_SRC_DIR}/VERSION VERSION_PATH=${ASTER_SRC_DIR}/VERSION
# Get and check the new version number # Get and check the new version number
if [[ $1 =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then if [[ $1 =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
@ -32,14 +32,14 @@ fi
update_cargo_versions ${CARGO_TOML_PATH} update_cargo_versions ${CARGO_TOML_PATH}
# Automatically bump Cargo.lock file # Automatically bump Cargo.lock file
cargo update -p jinux --precise $new_version cargo update -p asterinas --precise $new_version
# Update Docker image versions in README files # Update Docker image versions in README files
update_image_versions ${JINUX_SRC_DIR}/README.md update_image_versions ${ASTER_SRC_DIR}/README.md
update_image_versions ${SCRIPT_DIR}/docker/README.md update_image_versions ${SCRIPT_DIR}/docker/README.md
# Update Docker image versions in workflows # Update Docker image versions in workflows
WORKFLOWS=$(find "${JINUX_SRC_DIR}/.github/workflows/" -type f -name "*.yml") WORKFLOWS=$(find "${ASTER_SRC_DIR}/.github/workflows/" -type f -name "*.yml")
for workflow in $WORKFLOWS; do for workflow in $WORKFLOWS; do
update_image_versions $workflow update_image_versions $workflow
done done
@ -47,4 +47,4 @@ done
# Create or update VERSION # Create or update VERSION
echo "${new_version}" > ${VERSION_PATH} echo "${new_version}" > ${VERSION_PATH}
echo "Bumped Jinux version to $new_version" echo "Bumped Asterinas version to $new_version"

16
tools/docker/README.md
View File

@ -1,35 +1,35 @@
# Jinux Development Docker Images # Asterinas Development Docker Images
Jinux development Docker images are provided to facilitate developing and testing Jinux project. These images can be found in the [jinuxdev/jinux](https://hub.docker.com/r/jinuxdev/jinux/) repository on DockerHub. Asterinas development Docker images are provided to facilitate developing and testing Asterinas project. These images can be found in the [jinuxdev/jinux](https://hub.docker.com/r/jinuxdev/jinux/) repository on DockerHub.
## Building Docker Images ## Building Docker Images
To build a Docker image for Jinux and test it on your local machine, navigate to the root directory of the Jinux source code tree and execute the following command: To build a Docker image for Asterinas and test it on your local machine, navigate to the root directory of the Asterinas source code tree and execute the following command:
```bash ```bash
docker buildx build \ docker buildx build \
-f tools/docker/Dockerfile.ubuntu22.04 \ -f tools/docker/Dockerfile.ubuntu22.04 \
--build-arg JINUX_RUST_VERSION=$RUST_VERSION \ --build-arg JINUX_RUST_VERSION=$RUST_VERSION \
-t jinuxdev/jinux:$JINUX_VERSION \ -t jinuxdev/jinux:$ASTER_VERSION \
. .
``` ```
The meanings of the two environment variables in the command are as follows: The meanings of the two environment variables in the command are as follows:
- `$JINUX_VERSION`: Represents the version number of Jinux. You can find this in the `VERSION` file. - `$ASTER_VERSION`: Represents the version number of Asterinas. You can find this in the `VERSION` file.
- `$RUST_VERSION`: Denotes the required Rust toolchain version, as specified in the `rust-toolchain` file. - `$RUST_VERSION`: Denotes the required Rust toolchain version, as specified in the `rust-toolchain` file.
## Tagging Docker Images ## Tagging Docker Images
It's essential for each Jinux Docker image to have a distinct tag. By convention, the tag is assigned with the version number of the Jinux project itself. This methodology ensures clear correspondence between a commit of the source code and its respective Docker image. It's essential for each Asterinas Docker image to have a distinct tag. By convention, the tag is assigned with the version number of the Asterinas project itself. This methodology ensures clear correspondence between a commit of the source code and its respective Docker image.
If a commit needs to create a new Docker image, it should If a commit needs to create a new Docker image, it should
1. Update the Dockerfile as well as other materials relevant to the Docker image, and 1. Update the Dockerfile as well as other materials relevant to the Docker image, and
2. Run [`tools/bump_version.sh`](../bump_version.sh) tool to update the Jinux project's version number. 2. Run [`tools/bump_version.sh`](../bump_version.sh) tool to update the Asterinas project's version number.
For bug fixes or small changes, increment the last number of a [SemVer](https://semver.org/) by one. For major features or releases, increment the second number. All changes made in the two steps should be included in the commit. For bug fixes or small changes, increment the last number of a [SemVer](https://semver.org/) by one. For major features or releases, increment the second number. All changes made in the two steps should be included in the commit.
## Uploading Docker Images ## Uploading Docker Images
New versions of Jinux's Docker images are automatically uploaded to DockerHub through Github Actions. Simply submit your PR that updates Jinux's Docker image for review. After getting the project maintainers' approval, the [Docker image building workflow](../../.github/workflows/docker_build.yml) will be started, building the new Docker image and pushing it to DockerHub. New versions of Asterinas's Docker images are automatically uploaded to DockerHub through Github Actions. Simply submit your PR that updates Asterinas's Docker image for review. After getting the project maintainers' approval, the [Docker image building workflow](../../.github/workflows/docker_build.yml) will be started, building the new Docker image and pushing it to DockerHub.

6
tools/docker/run_dev_container.sh
View File

@ -3,9 +3,9 @@
set -e set -e
SCRIPT_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd ) SCRIPT_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
JINUX_SRC_DIR=${SCRIPT_DIR}/../.. ASTER_SRC_DIR=${SCRIPT_DIR}/../..
CARGO_TOML_PATH=${SCRIPT_DIR}/../../Cargo.toml CARGO_TOML_PATH=${SCRIPT_DIR}/../../Cargo.toml
VERSION=$( cat ${JINUX_SRC_DIR}/VERSION ) VERSION=$( cat ${ASTER_SRC_DIR}/VERSION )
IMAGE_NAME=jinuxdev/jinux:${VERSION} IMAGE_NAME=jinuxdev/jinux:${VERSION}
docker run -it --privileged --network=host --device=/dev/kvm -v ${JINUX_SRC_DIR}:/root/jinux ${IMAGE_NAME} docker run -it --privileged --network=host --device=/dev/kvm -v ${ASTER_SRC_DIR}:/root/asterinas ${IMAGE_NAME}