mirror of
https://github.com/saymrwulf/xous-core.git
synced 2026-11-16 08:38:26 +00:00
Merge pull request #696 from betrusted-io/docs
Update README for Xous; stab at improving the documentation.
This commit is contained in:
commit
f66e3d0241
3 changed files with 100 additions and 144 deletions
|
|
@ -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
0
README-precursor.md
Normal file
185
README.md
185
README.md
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue