xous-core/README.md

# Xous Core

Xous is a microkernel operating system written in pure Rust, built for high-assurance applications.

Key features:
- Hardware memory protection
  - Virtual memory via MMU
  - Each process has an isolated address space
- `std` support in stable Rust (tier-3 Rust target)
- Asynchronous message passing
- Minimal code base
  - [Microkernel](./kernel) architecture
  - System [services](./services) live in userland
- Targeted at high-assurance embedded applications

The [Xous Book](https://betrusted.io/xous-book/) covers the architecture and structure of the kernel.

The [wiki](https://github.com/betrusted-io/betrusted-wiki/wiki) is a community resource that answers many FAQ.

The [Baochip README](./README-baochip.md) is the starting point for Baochip users. `vscode` users may wish to install the `baochip` extension to help manage build & test cycles.

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
* **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

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`

`doc-deps` is a dummy hardware target that satisfies the requirement of
a "board" when building documentation.

## Local-vs-crates.io Verification

`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`.

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
with financial support from the European Commission's Next Generation Internet
programme, under the aegis of DG Communications Networks, Content and Technology
under grant agreement No 825310.

<table>
    <tr>
        <td align="center" width="50%"><img src="https://nlnet.nl/logo/banner.svg" alt="NLnet foundation logo" style="width:90%"></td>
        <td align="center"><img src="https://nlnet.nl/image/logos/NGI0_tag.svg" alt="NGI0 logo" style="width:90%"></td>
    </tr>
</table>