saymrwulf/xous-core
1
0
Fork 0
mirror of https://github.com/saymrwulf/xous-core.git synced 2026-11-04 04:27:34 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
Xous SDK (pinned for betrusted transpilation)
4179 commits 1 branch 0 tags 404 MiB
Rust 93.7%
Python 3%
C# 2.2%
C 0.6%
Assembly 0.2%
Other 0.1%
Find a file
bunnie 4e40ae6c5d move from target selectors to feature selectors for back-ends 
This will allow for e.g. xous on riscv32-imac but not a precursor
target, for example: by using feature selectors we get to have
a bigger range of targets that we support, such as for implementations
that haven't been upstreamed or have official target-triples.

The downsides are:

- patch override libraries don't absorb feature flags. so, for
example, the AES crate that is used to patch other crates won't
be aware of the target features without modifying the referencing
crates.

- features are normally meant to be additive, but target features
are mutually exclusive. The mutex is enforced by a check in
utralib that throws a panic on build if two targets are accidentally
selected at the same time.
2022-10-02 02:56:44 +08:00
.cargo fixups to fix linux builds 2022-08-21 16:30:37 +08:00
.github/workflows bump minimum toolchain requirement 2022-08-05 16:28:42 +08:00
.vscode don't hide the loader! 2022-09-27 01:14:06 +08:00
api/log-server bump version so we can update xous-ipc dependency 2022-09-26 17:15:54 +08:00
apps move from target selectors to feature selectors for back-ends 2022-10-02 02:56:44 +08:00
devkey beginnings of image signing 2021-07-06 17:31:09 +08:00
docs Update flash.md 2022-07-09 15:37:50 +08:00
emulation fix renode paths 2022-09-27 18:32:30 +08:00
imports prep a fork of riscv package 2022-09-27 17:23:25 +08:00
kernel also move utralib change into kernel, update cargo.lock 2022-10-02 02:21:27 +08:00
LICENSES creating LICENSES directory 2021-01-25 14:52:31 +01:00
loader refactor utra target line to use explicit feature targets 2022-10-02 02:20:03 +08:00
locales fix #174 2022-06-10 21:36:53 +08:00
precursors move precursors to the utralib 2022-09-26 16:49:49 +08:00
services move from target selectors to feature selectors for back-ends 2022-10-02 02:56:44 +08:00
svd2repl this file wasn't saved for some reason 2022-09-29 22:38:12 +08:00
svd2utra bump rev to remove clap 2022-09-29 22:15:22 +08:00
tools missed a file 2022-10-02 02:21:06 +08:00
utralib absorb svd2utra rev 2022-09-29 22:16:24 +08:00
xous-ipc update xous-ipc and xous versions 2022-09-26 16:07:35 +08:00
xous-rs move from target selectors to feature selectors for back-ends 2022-10-02 02:56:44 +08:00
xtask initial cut at a refactored build process. 2022-10-02 02:21:48 +08:00
.gitattributes gitattributes: add txt as lf 2021-03-10 17:36:41 +08:00
.gitignore omit the page table file 2022-09-16 01:53:46 +08:00
analyze-bloat.sh fix argument to backup copy 2022-06-14 02:05:31 +08:00
API.md xous: remove xous::xous_main macro 2022-05-31 13:41:48 +08:00
Cargo.lock also move utralib change into kernel, update cargo.lock 2022-10-02 02:21:27 +08:00
Cargo.toml fixup other refs 2022-09-27 03:09:41 +08:00
CODE_OF_CONDUCT.md
CONTRIBUTING.md CONTRIBUTRING: Update license link 2022-04-24 21:48:43 +08:00
README.md Update README.md 2022-04-03 13:10:56 +08:00
RELEASE-v0.8.md clean up release notes 2021-09-05 20:46:23 +08:00
RELEASE-v0.9.md note gdbstub removal 2022-09-27 18:43:27 +08:00
rustfmt.toml finalize formatting run 2021-08-20 00:26:16 +08:00

README.md

Xous Core

Core files for the Xous microkernel operating system.

You might find this wiki handy, as well as the Xous Book.

This repository contains everything necessary to build the Xous kernel from source. It consists of the following projects:

  • 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
  • emulation: Renode scripts used to emulate Xous
  • xous-rs: userspace library

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

Quickstart using Hosted Mode

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

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.

Quickstart using an emulator

Xous uses Renode as the preferred emulator, because it is easy to extend the hardware peripherals without recompiling the entire emulator.

Download Renode and ensure it is in your path. For now, you need to download the nightly build, until DecodedOperation is included in the release.

Then, build Xous:

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:

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.

We have included a reference version of the gateware and its SVD file in the precursors directory, so you can compile a gateware for the reference image using this command:

cargo xtask hw-image precursors/soc.svd

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.