Update README for Xous; stab at improving the documentation.

This commit is contained in:
bunnie 2025-10-08 01:16:45 +08:00
parent b41dd9b7ac
commit 00717b01df
No known key found for this signature in database
3 changed files with 100 additions and 144 deletions

View file

@ -1,12 +1,49 @@
# "Baochip" / "bao1x" Series API Organization & Glossary
# Getting Started with Baochip Targets
Baochip-based boards use the `bao1x` SoC. There are two boards supported out-of-the-box:
- `dabao` is a minimal SoM-style breakout board. Basically just the chip on a board.
- `baosec` is a hardware security token. It features a camera, display, external memory, buttons, and a supplemental hardware TRNG.
Regardless of the board, the `bao1x` chip comes from the factory programmed with `boot0` and `boot1` stages. The code for these can be found in `bao1x-boot/`.
- `boot0` is a permanent root of trust burned onto the chip. Its sole purpose is to validate `boot1`. See [security model](./README-baochip.md#security-model) for details on the trust chain
- `boot1` contains a USB driver, serial-over-USB driver, and serial driver capable of accepting code updates in the form of .u2f files or serial commands. It also contains a small command terminal for managing configurations, keys, and device lifecycle state.
Three application targets are supported by Xous:
- `baremetal` is an unsecured, bare-iron environment. It is `no-std`, but comes with `alloc` pre-initialized and a USB serial console.
- `dabao` is a Xous environment. It boots a full kernel, supports `std`, and features "detached-apps", i.e., users can develop stand-alone applications that run on the OS without having to touch the kernel image.
- `baosec` is a Xous environment. It is like `dabao`, but supports swap memory. As a result it can run much larger, more complicated applications. The on-chip RRAM is reserved for the kernel, while the off-chip swap contains user applications.
Code is delivered via `boot1`. `boot1` is entered by holding down a button while power the device on. The device will show up as a USB mass storage device, at which point a .uf2 file containing the application image is copied to the device, and the update is applied.
## Security Model
The default `bao1x` chips come from the factory with four public keys burned into them:
- Two code deployment signing keys
- One beta signing key
- One developer key (anyone can use the [private key](./devkey/README.md) to sign a developer image)
In addition to these public keys, a collection of initial identifiers and secrets are generated on-device which serve as the security root. Each boot stage has a copy of these public keys; thus the key set can be updated/changed for downstream artifacts. boot0/boot1 should be rarely, if ever, updated; meanwhile detached application images running within the OS environment may have more permissive signing policies since memory protection is enforced by the OS.
By default, the `bao1x` will accept and run developer images; however upon encountering a developer image anywhere in the boot chain, all the initial secrets are erased, and a one-way counter is incremented to indicate the device is a developer device. From this point developers can generate new keys, but any device attestation or on-chip secrets programmed into the device are lost.
The developer key can be revoked by running `lockdown` at the `boot1` stage. `baosec` boards have this done at the factory prior to shipment, to prevent tampering in the supply chain.
## API Organization
The Baochip platform has the following API structure. Note that
`bao1x` is the original code name for the target chip, which after
two years of extensive code development migrated to the `baochip`
brand name. At the moment the misnaming stands, due to the amount
of code that carries the legacy name.
The Baochip platform has the following API structure.
`apps-dabao`: Applications for the dabao platform
`apps-baosec`: Applications for the baosec platform
`bao1x-boot`: Secure bootloader chain for the Baochip platform. The
bootloader code has settings for three targets, `dabao`, `baosec`,
and `oem`. The `oem` setting is intended for developers who want
to do their own custom board.
`libs/bao1x-api`: contains hardware-abstracted API code to the hardware
layers (traits, some constants, enums, etc.). For example, "here is
@ -47,10 +84,12 @@ you may encounter in this project.
`daric`: Internal code name for the SoC while in development.
`crossbar`: The parent company that shouldered the cost of taping out the SoC.
Most of the OSS SoC code has its copyright assigned to this organization;
so, this is probably the most relevant legal entity even though its
name doesn't appear in marketing materials.
`crossbar`: Baochip made it's SoC by "hitchiking" on Crossbar's tape-out. Crossbar
thus shouldered the cost of taping out the SoC, while Baochip made light-fingered
changes that made the chip amenable to running Xous. Most of the OSS SoC code
has its copyright assigned to this organization; so, this is probably the
most relevant third-party legal entity, even though its name doesn't appear
in marketing materials.
`baochip`: The name of a new company formed to market an OSS- and Xous-focused
variant of the `daric` chip. This is the relevant legal organization in terms

0
README-precursor.md Normal file
View file

185
README.md
View file

@ -2,157 +2,74 @@
Core files for the Xous microkernel operating system.
You might find this [wiki](https://github.com/betrusted-io/betrusted-wiki/wiki) handy, as well as the [Xous Book](https://betrusted.io/xous-book/).
The [Xous Book](https://betrusted.io/xous-book/) covers the architecture and structure of the kernel.
Users targeting Baochip platforms should also familiarize with the [Boachip API structure and glossary](./README-baochip.md) as the platform has several targets and gone through numerous name changes.
The [wiki](https://github.com/betrusted-io/betrusted-wiki/wiki) is a community resource that answers many FAQ.
This repository contains everything necessary to build the Xous kernel
from source. It consists of the following projects:
The [Boachip README](./README-baochip.md) is the starting point for Baochip users.
* **kernel**: core memory manager, irq manager, and syscallhandler
* **loader**: initial loader used to start the kernel
* **tools**: programs used to construct a final boot image
* **docs**: documentation on various aspects of Xous
The [Precursor README](./README-precursor.md) is the starting point for Precursor users.
Xous is a mono-repo project. It contains the kernel, libraries, applications, and tools necessary to build full device images. Here is a brief description of the more important directories:
* **api**: "Secular" API libraries - minimal-dependency, common-core APIs used by core Xous services
* **apps**: Precursor applications
* **apps-dabao**: Dabao applications
* **apps-baosec**: Baosec applications
* **bao1x-boot**: Bao1x secure boot chain
* **baremetal**: Baremetal target - runs after the boot chain, for developers that don't want Xous but can still use Xous' `no-std` features
* **emulation**: Renode scripts used to emulate Xous
* **xous-rs**: userspace library
* **imports**: Vendored-in libraries that had to be forked for Xous compatibility
* **kernel**: core memory manager, irq manager, and syscall implementations.
* **libs**: Device driver libraries. The common thread is that none of these code bases contain a `main.rs`, just a `lib.rs`.
* **loader**: Sets up virtual memory space and boots the kernel
* **locales**: Tools for handling internationalization
* **signing**: Scripts for generating signed images
* **services**: Xous programs that support Xous apps. Middleware, if you will.
* **svd2utra**: A program for converting SVD chip descriptions in XML to the UTRA "header file" format
* **tools**: Programs used to construct a final boot image. Also the home of various diagnostic and test utilities.
* **utralib**: The [Unambigous Thin Register Abtraction](./utralib/README.md). The core hardware interface for Xous.
* **xous-ipc**: Inter-process communication convenience APIs for Xous
* **xous-rs**: API files for the kernel. Where the syscall interfaces live.
* **xtask**: The build system manager for Xous.
## Dependencies
- Xous requires its own Rust target, `riscv32imac-unknown-xous-elf`. If you run `cargo xtask` from the command line, you should be prompted to install the target automatically if it does not already exist.
- You may need to remove the `target/` directory before building, if `rustc` continues to behave like it can't find the `xous` target even after it is installed.
- If you plan on doing USB firmware updates, you'll need `progressbar2` (updates) and `pyusb` (updates). Note that `pyusb` has name space conflicts with similarly named packages, so if updates aren't working you may need to create a `venv` or uninstall conflicting packages.
- If you are doing development on the digital signatures with the Python helper scripts, you will need: `pycryptodome` (signing - PEM read), `cryptography` (signing - x509 read), `pynacl` (signing - ed25519 signatures) (most users won't need this).
- Some system packages are needed, which can be installed with `sudo apt install libssl-dev libxkbcommon-dev` or similar
- If you receive an error about `feature resolver is required`, try installing a newer version of `rustc` and `cargo` via [rustup](https://rustup.rs)
Install the latest [Rust](https://rust-lang.org/tools/install/) or run `rustup update` to update your Rust installation prior to building. Xous development assumes a recent version of Rust.
## Build Commands
- Precursor: `cargo xtask app-image`
- Dabao: `cargo xtask dabao`
- Baosec: `cargo xtask baosec`
- Baochip baremetal: `cargo xtask baremetal-bao1x`
Additional apps to be bundled into images can be specified as extra arguments on the command line, e.g. `cargo xtask dabao helloworld` will generate a Dabao image that includes `helloworld` in the detached-app section. Features, app-features, loader-features, and so forth can also be passed as command line arguments; run `cargo xtask` on its own for more help.
## Emulation
- `cargo xtask run` will bring up an emulated Precursor
- `cargo xtask baosec-emu` will bring up an emulated Baosec
- `cargo xtask renode-image` will build an image suitable for [Renode](https://renode.io/#downloads) emulation of a Precursor target. Start renode by running `renode emulation/xous-release.resc`
## Building Documentation
A flag of `--feature doc-deps` must be passed when running `cargo doc`, like this:
`cargo doc --no-deps --feature doc-deps`
This flag is required because Xous requires a target board to be specified in
all build configurations. `doc-deps` specifies a set of dummy dependencies
that satisfy board requirements for the purpose of building documentation.
`doc-deps` is a dummy hardware target that satisfies the requirement of
a "board" when building documentation.
## Local-vs-crates.io Verification
By default the `xtask` resolver runs a check to confirm that your local files
match the ones referenced in `crates.io`. For a handful of core crates, the
build preferentially runs from what is on `crates.io`, so local changes have
no effect until they are pushed as an update to an existing crate. If you see
an error complaining about local source files not being published, make sure
you have the correct patches in place in your top level `Cargo.toml` file,
and bypass the check with `--no-verify`.
## Quickstart using Hosted Mode
`xtask` does a check every build to ensure that any `crates.io` dependencies
are synchronized with the contents of the monorepo. It protects against the
scenario where you edited a crate that exists in the Xous repo, but the
build system ignores the local edits because it's fetching an old version from
`crates.io`.
You can try out Xous in a "hosted mode" wherein programs are compiled
for your native platform and are run locally as processes within your
current operating system. System calls are replaced with network calls
to a kernel that simply shuffles messages around.
Xous uses the [xtask](https://github.com/matklad/cargo-xtask/) convention,
where various complex build commands are stored under `cargo xtask`.
This allows for us to create arbitrarily complex build sequences
without resorting to `make` (which is platform-dependent),
`sh` (which requires a lot of external tooling), or another build
system.
To build a set of sample programs and run them all using the
kernel for communication, clone this repository and run:
```sh
cargo xtask run
```
This will build several servers and a "shell" program to control them
all. Most notably, a `graphics-server` will appear and kernel messages
will begin scrolling in your terminal.
### Hosted Mode UI navigation
| Precursor | Host |
| ------------------- | ----------- |
| D-pad middle button | Home |
| D-pad up | up arrow |
| D-pad down | down arrow |
| D-pad left | left arrow |
| D-pad right | right arrow |
## Quickstart using an emulator
Xous uses [Renode](https://renode.io/) as the preferred emulator, because
it is easy to extend the hardware peripherals without recompiling the
entire emulator.
Due to a breaking change in Renode, this codebase is only compatible with Renode equal to or later than `1.15.2.7965 (e6e79aad-202408180425)`
[Download Renode](https://renode.io/#downloads) and ensure it is in your path.
For now, you need to [download the nightly build](https://dl.antmicro.com/projects/renode/builds/),
until `DecodedOperation` is included in the release.
Then, build Xous:
```sh
cargo xtask renode-image
```
This will compile everything in `release` mode for RISC-V, compile the tools
require to package it all up, then create an image file.
Finally, run Renode and specify the `xous-release.resc` REnode SCript:
```sh
renode emulation/xous-release.resc
```
Renode will start emulation automatically, and will run the same set of programs
as in "Hosted mode".
## Generating a hardware image
To build for real hardware, you must specify an `.svd` file. This
file is generated by the SoC build process and describes a single
Betrusted core. These addresses will change as hardware is modified,
so if you distribute a modified Betrusted core, you should be sure
to distribute the `.svd` file.
The [UTRA](./utralib/README.md) abstracts the details of the register
locations, by wrapping them in logical names that don't change.
For Precursor, the SVD files are tracked inside `utralib/precursor/soc-<gitref>.svd`.
Since each soc.svd can potentially change with a git reference, a gitref
is coded into the filename by convention.
Generally, one can create an image for hardware using the following command:
```sh
cargo xtask app-image-xip
```
And it will pull from the default soc.svd configuration.
The currently selected config is set by the constant `PRECURSOR_SOC_VERSION`
in [xtask/src/main.rs](./xtask/src/main.rs); it is one of the first constants
near the top.
If you have built your own custom soc.svd file, the most convenient way to update
to this is to simply replace the file referenced in the default with yours,
and then run `cargo build` inside the `utralib` directory (not in the Xous
root -- the `build` command must happen inside the directory to force a
regeneration of the generated UTRA bindings). This will likely result
in a complaint when you run `xtask` that your local tree does not match what
is checked into `git`; if you are building from your own configuration,
that is correct, and thus you should add `--no-verify` to your `xtask` command
to suppress the check.
Note that adding a full extra custom gitrev is more involved, it involves
editing the [utralib/Cargo.toml](./utralib/Cargo.toml) and [utralib/build.rs](./utralib/build.rs)
to reference your new artifact as a brand new feature flag.
The resulting images are in your target directory (typically `target/riscv32imac-unknown-xous-elf/release/`)
with the names `xous.img` (for the kernel) and `loader.bin` (for its bootloader). The corresponding
gateware is in `precursors/soc_csr-<gitref>.bin`. These can be written to your
device by following the [update guide](https://github.com/betrusted-io/betrusted-wiki/wiki/Updating-Your-Device).
Developers working on published crates should patch them in the root `Cargo.toml`
file and bypass the check with `--no-verify`.
## Acknowledgement
This project is funded through the NGI0 PET Fund, a fund established by NLnet