Home - betrusted-io/betrusted-wiki GitHub Wiki
Get Started
For help, you can open a github issue in the appropriate repo, or join the Matrix chat.
First - Update Your Precursor Device
- Update your device using the Precursor Updater. Out-of-box Precursors have an ancient version of Xous.
- For those with a limited edition Precursor: How to Assemble a Limited Edition (Video)
Next - Set up Security
- Inspect your mainboard
- Set up passwords on "factory new" devices, by selecting the item from the main menu, or following the prompts at boot
- (Optional) Burn Battery-Backed RAM keys, aka your "backup key".
- (Optional) Backup your data. Recommended if you use BBRAM keys, since they are volatile.
After these steps, your basic Precursor is be ready to be used.
Installing Additional Apps
- Out of the box, the basic firmware image for Precursor comes with
shellchat
andvault
apps. - Apps are statically loaded programs, linked into the firmware image.
- To add additional apps, build a custom firmware image and load it onto your Precursor.
Apps include:
Currently Available- Shellchat - the default app when you power on.
- Vault - a physical password vault. Make, store, and autotype passwords; generate TOTP codes; and perform FIDO2/U2F authentication. Perhaps the only hardware FIDO token with secure backups.
- Matrix client - a simple Matrix chat application.
- Mtxchat - next-gen matrix client, currently WIP.
- Transientdisk - present a 1.44MiB RAM drive to a host over USB. Contents are cleared when the app is closed, or the device is put to sleep. Useful for transferring secret keys over short distances.
Reminder: Backup your Precursor.
- Backups - the thing you think you'll never need. Until you do. Highly recommended.
Writing code for Xous (and Precursor)
Running the emulator
- Run
cargo xtask run
, and it will pop up a "host-mode" emulated version of Precursor. - To add additional apps other than the default, add them after
run
, likecargo xtask run hello ball
(will build and add both thehello
andball
apps)- check
cargo xtask --help
for the full list of commands and options. - Hosted emulator uses
Home
(Fn+⬅
on Mac) for the center key on the Precursor device, use this button when navigating within the emulator.
- check
Build troubleshooting
- If you have updated
rust
or have tinkered withstd
on your system, you can re-install thexous
target withcargo xtask install-toolkit --force
, and then runrm -r target
to force remove stale build files. - You may also need to install some additional libraries, such as
libxkbdcommon-dev
. - Xous has generally been tracking the latest stable Rust toolchain, so if your build isn't working, try updating to the latest stable Rust, or if there was just a release, try one version before the latest version. Alternatively, you can check the CI logs for the version used in the last stable build, by searching for
rustc --version
in the log.- To set the toolchain version, run
rustup override set 1.64
(or which ever version you're trying to target). - Arch Linux users: Hoverbear has written a guide for setting up Xous on Arch Linux!
- To set the toolchain version, run
Making your own app
Reference Apps
repl
app demo is the starting point for users who want to interact with their device by typing commands. This demo leverages more of the Xous UX built-in frameworks.ball
app demo is the starting point for users who prefer to run close to the bare iron, getting only key events and a framebuffer for crafting games and bespoke apps.
Ready to add your own app?
- Please refer to the manifest.json documentation for integration notes.
- :warning: hosted mode is literally Xous running on your local host, which means it supports more features than Xous on native hardware:
- We do not have
tokio
support planned anytime soon. - We do not have
File
support in Xous; instead, we have thepddb
. Net
support in actively in development and we hope to have fairly robust support forlibstd
Net
but, note thatsocket2
crate (which is not part of Rustlibstd
) does not recognize Xous as a supported host.
- We do not have
- It is recommended to try compiling your configuration for a real hardware target or Renode early on to confirm compatibility, before doing extensive development in hosted mode.
- Currently, the only hardware implementation of the project referenced in this repo is the Precursor device. If you port Xous to a new platform, please reference the target right here in this wiki!
Getting past Hello World
- Xous Book Xous API docs, structure, etc.
- Jargon: Confused by terms like SoC and EC? You're not alone.
- Tips and tricks stuck on a bug? Look here.
- Build the SoC from Scratch
In Depth
Organized, roughly, from top of the stack and drilling into the hardware.
Xous: Applications
- App manifest and adding apps
- GDB is available with a custom-built kernel using the argument
--gdb-stub
. GDB is mainly tested for the Renode target; it should work for "real" hardware as well but it is not as well tested.
Xous: OS Services
- Xous API documentation and examples
- Messaging Idoms is the starting point for common idioms on talking to Xous services.
- Modals API is the starting point for interactive UX elements.
- Xous Book is gradually coming together
- Services describes the various servers that compose the services provided by the Xous microkernel.
- Push Events
- Graphical Abstraction Manager (GAM) architecture; applications guide
- xous-names Name resolution for server IDs
- Localization
- PDDB Plausibly Deniable DataBase for deniable data storage of secrets. Also see this blog post for an overview.
- PDDB path conventions for
libstd
integration. - Boot flow specification
Xous: Microkernel Core
- Quickstart is on the main page
- Memory layout
- FLASH layout
- Processes
- Syscalls
- Startup Sequence
- Boot arguments
- Loader Stage 1 loader for the kernel
- Suspend/resume
Pre-Boot & Security
- What happens before boot? fills in the details of everything that happens before the first instruction gets run.
- "Secure Boot" and key ROM layout
- eFuse/BBRAM FPGA key FAQ
Between the Software and Hardware: Hardware Abstractions
- UTRA Hardware register access abstraction for Xous
- Peripheral access conventions Goals for hardware register abstractions
- COM Protocol between the embedded controller (EC) and the main SoC
Hardware Documentation
- SoC register set / generated from SoC Litex Design Source
- SoC block diagram is embedded in the README for the SoC
- EC register set / generated from EC Litex Design Source
- Hardware design files PDFs of schematics are in the "mainboard-*" directories
TRNG Chronicles
- Physics and electrical design of the external Avalanche generator
- Notes on Characterization and debugging of raw sources
- On-line health monitoring
- Post-Generation Conditioning with ChaCha
Audit Trail
- crate-scraper is the beginning of a tool that helps with audit trails. It saves all the source code derived from
crates.io
to build Xous, and collates all thebuild.rs
files into a single mega-file for faster manual inspection.
Meta-Issues
- imports How imported repositories that are not yet stand-alone crates are managed
- Emulation
- Tools Helper tools to build bootable images
- Converting Wiki Pages from ODT to Markdown
- Release checklist
- Updating Crates order of crates to update to crates.io when making changes
External Talks and Papers
- RISC-V International Seattle RISC-V Group Betrusted Progress Call
- 36c3 Introducing the core principles that motivate the hardware architecture
- LCA20 Evolution and planning of the overall project, including software layers
- FOSSNORTH20 Precursor overview talk
- Precursor SoC Tour
- Precursor Mainboard tour
- Other Precursor posts hardware security evaluation, braille keyboard, hackability, mechanical and PCB design aspects.
- Precursor + Renode, Multi-device emulation
- Boot to root in one hour
Other Documents of Interest
- Spartan 7 JTAG notes on the eFuse structure (for self-provisioning of security keys)
- HCI target rationale.
- Hardware systems architecture analysis for details on the analysis that lead us to our current architectural constraints.
- Betrusted development plan a now largely historical document that outlined schedule and overall development plan.
Acknowledgments
This project is funded in part 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.