zCore/docs

# zCore

An OS kernel based on zircon, provides Linux compatible mode.

• 中文自述文档

• legacy README

  you may want to check the legacy for setting up docker, running graphical applications, etc. But many of these scripts are deprecated

Launch zCore

cargo qemu --arch riscv64

This command will launch zCore using qemu-system-riscv64。

The default file system will contain a busybox application and a musl-libc linker. They are compiled by automatic downloaded musl-libc RISC-V cross-compilation tool chain.

Table of contents

• Launch zCore
• Build the project
  • Commands
  • Commands reference
• Platform support
  • Qemu/virt
  • Allwinner/nezha
  • starfivetech/visionfive

Build the project

The project will be built with xtask. The common operations are provided as cargo commands.

An extra Makefile provides make calls for compatibility with some legacy scripts.

Currently tested development environments include Ubuntu 20.04, Ubuntu 22.04 and Debian 11. The libc tests for x86_64 cannot compile on Ubuntu22.04. If you do not need to flash to physical hardware, using WSL2 or other virtual machines does not operate any differently from the real machine.

Commands

The basic format of the command is cargo <command> [--rags [value]], which is actually cargo run --package xtask --release -- <command> [--args [value]]. command is passed to the xtask application to parse and execute.

The effects of many commands are affected by the repo environment and will also affect the repo environment. For convenience, if one command depends on the result of another command, they are designed to recursion. The recursive relationship diagram of the commands is as follows. The detailed explanation of them is in the next section:

---

NOTICE It is recommended to use equivalent fonts

---

┌────────────┐ ┌─────────────┐ ┌─────────────┐
| update-all | | check-style | | zircon-init |
└────────────┘ └─────────────┘ └─────────────┘
┌─────┐ ┌──────┐  ┌─────┐  ┌─────────────┐ ┌─────────────────┐
| asm | | qemu |─→| bin |  | linux-libos | | libos-libc-test |
└─────┘ └──────┘  └─────┘  └─────────────┘ └─────────────────┘
                     |            └───┐┌─────┘   ┌───────────┐
                     ↓                ↓↓      ┌──| libc-test |
                 ┌───────┐        ┌────────┐←─┘  └───────────┘
                 | image |───────→| rootfs |←─┐ ┌────────────┐
                 └───────┘        └────────┘  └─| other-test |
                 ┌────────┐           ↑         └────────────┘
                 | opencv |────→┌───────────┐
                 └────────┘  ┌─→| musl-libc |
                 ┌────────┐  |  └───────────┘
                 | ffmpeg |──┘
                 └────────┘
-------------------------------------------------------------------
Example：`A` recursively executing `B` (`A` depends on the results of `B`, and `B` is executed before `A` automatically)
┌───┐  ┌───┐
| A |─→| B |
└───┘  └───┘

Commands reference

If the following command description does not match its behavior, or if you suspect that this documentation is not up to date, you can check the inline documentation as well. If you find error: no such subcommand: ..., check command alias to see which commands have aliases set for them.

---

NOTICE inline documentation is also bilingual

---

update-all

Updates toolchain、dependencies and submodules.

cargo update-all

check-style

Checks code without running. Try to compile the project with various different features.

cargo check-style

zircon-init

Download zircon binaries.

cargo zircon-init

asm

Dumps the asm of kernel for specific architecture. The default output is target/zcore.asm.

cargo asm --arch riscv64 --output riscv64.asm

bin

Strips kernel binary for specific architecture. The default output is target/{arch}/release/zcore.bin.

cargo bin --arch riscv64 --output zcore.bin

qemu

Runs zCore in qemu.

cargo qemu --arch riscv64 --smp 4

Connects qemu to gdb：

cargo qemu --arch riscv64 --smp 4 --gdb 1234

rootfs

Rebuilds the linux rootfs. This command will remove the existing rootfs directory for this architecture, and rebuild a minimum rootfs.

cargo rootfs --arch riscv64

musl-libs

Copies musl so files to rootfs directory.

cargo musl-libs --arch riscv64

ffmpeg

Copies ffmpeg so files to rootfs directory.

cargo ffmpeg --arch riscv64

opencv

Copies opencv so files to rootfs directory. If ffmpeg is already there, this opencv will build with ffmpeg support.

cargo opencv --arch riscv64

libc-test

Copies libc test files to rootfs directory.

cargo libc-test --arch riscv64

other-test

Copies other test files to rootfs directory.

cargo other-test --arch riscv64

image

Builds the linux rootfs image file.

cargo image --arch riscv64

linux-libos

Runs zCore in linux libos mode and runs an executable at the specified path.

NOTICE zCore can only run a single executable in libos mode, and it will exit after finishing.

cargo linux-libos --args /bin/busybox

Platform support

Qemu/virt

Launch with command directly, see launch zCore.

Allwinner/nezha

Build kernel binary with the following command:

cargo bin --arch riscv64 --features "linux board-d1" --output z.bin

Then deploy the binary to Flash or DRAM with rustsbi-d1.

Starfivetech/visionfive

Build kernel binary with the following command:

cargo bin --arch riscv64 --features "linux board-visionfive" --output z.bin

Then, see this document for detailed description, launching the system through u-boot network.