9a0bbbd2fb
The approach here turns the usb-device crate "inside out". The working hypothesis for the unreliability of the previous implementation is that we try to do all the IRQ-handling in userspace, where the operation can be pre-empted. Unfortunately, this doesn't set well with the corigine USB hardware driver, as it assumes that it has the full CPU attention while its state is being manipulated (and some things must be responded to in basically real time otherwise you get protocol inconsistencies). In this implementation, we use the Xous subsystem to do the API-level exchanges of information to a USB handler that, for the most part, runs directly inside an IRQ context. There's some trickiness in terms of sharing the hardware state across the boundary between IRQ and userland, but most of it got handled I think fairly cleanly in this implemnetation by using the xous-native server queuing mechanism to shuttle data in between the two domains. The main spot where I think panics can creep in is in data transmission, where the Tx data is shoved into a RefCell and then the IRQ is invoked to pull the data from a RefCell. As long as we don't invoke the IRQ to pull data from the RefCell while it's borrowed mutably, we should be OK. Wrapping the structure in a Mutex actually doesn't help here because the IRQ context can't do a "wait" to get a lock - it would never get it, because it's in an uninterruptable context. Thus we skip the complexity of a Mutex and let Rust panic if we mesesd up the data hand-off. |
||
|---|---|---|
| .cargo | ||
| .github/workflows | ||
| .vscode | ||
| api | ||
| apps | ||
| devkey | ||
| docs | ||
| emulation | ||
| imports | ||
| kernel | ||
| libs | ||
| LICENSES | ||
| loader | ||
| locales | ||
| planning | ||
| precursors | ||
| services | ||
| svd2repl | ||
| svd2utra | ||
| tools | ||
| utralib | ||
| xous-ipc | ||
| xous-rs | ||
| xtask | ||
| .gitattributes | ||
| .gitignore | ||
| analyze-bloat.sh | ||
| API.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| ct_eq.txt | ||
| FORMATTING.md | ||
| LICENSE | ||
| publish.py | ||
| README.md | ||
| RELEASE-v0.8.md | ||
| RELEASE-v0.9.md | ||
| rustfmt.toml | ||
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 runcargo xtaskfrom 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, ifrustccontinues to behave like it can't find thexoustarget even after it is installed. - If you plan on doing USB firmware updates, you'll need
progressbar2(updates) andpyusb(updates). Note thatpyusbhas name space conflicts with similarly named packages, so if updates aren't working you may need to create avenvor 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-devor similar - If you receive an error about
feature resolver is required, try installing a newer version ofrustcandcargovia rustup
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
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.
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 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 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.
The UTRA 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:
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; 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 and 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.
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.
 |
 |