diff --git a/README-baochip.md b/README-baochip.md index 1da01a648..0f1688647 100644 --- a/README-baochip.md +++ b/README-baochip.md @@ -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 diff --git a/README-precursor.md b/README-precursor.md new file mode 100644 index 000000000..e69de29bb diff --git a/README.md b/README.md index fc534e510..f6aa5e4a4 100644 --- a/README.md +++ b/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-.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-.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