lilos: A minimal async RTOS

• Intro guide
• API Docs
• crates.io

This is a wee operating system written to support the async style of programming in Rust on microcontrollers. It fits in about 2 kiB of Flash and uses about 40 bytes of RAM (before your tasks are added). In that space, you get a full async runtime with multiple tasks, support for complex concurrency via join and select, and a lot of convenient but simple APIs. (If you want to see what a lilos program looks like, look in the examples directory, or read the intro guide.)

lilos has been deployed in real embedded systems since 2019, running continuously. I've built about a dozen systems around it of varying complexity, on half a dozen varieties of microcontroller. It works pretty okay! Perhaps you will find it useful too.

Repo layout

This repo contains crates in subdirectories, and the subdirectories use .cargo/config.toml files to change settings that Cargo has so far declined to allow in Cargo.toml, such as the target triple. This means you will need to cd into subdirectories to build things, rather than using cargo build --all. Here is a map:

• os contains the operating system crate.
• testsuite contains a test suite for the operating system, which can run on a Cortex-M0 or better. See its README for instructions.
• examples contains example programs for various microcontrollers.
• extra contains a few "non-core" crates providing features that don't need to be in the OS proper:
  • handoff provides a synchronous rendezvous for transferring data from one task to another with minimal copies.
  • semaphore provides a counting semaphore implementation.
  • rwlock provides a read-write lock implementation.

Building

These instructions are mostly for building the examples or working on the operating system itself. If you're trying to use lilos in a program, the usual way is to just cargo add lilos to your application.

To build in the repo, you will need a Rust toolchain installed through rustup, because we use a rustup-style rust-toolchain.toml file to pin the toolchain version to ensure that you get the right results. rustup will automatically ensure you've got the appropriate toolchain version available, including support for the right target architecture for whatever program you're building.

1. Enter the directory you're interested in, for example, cd os.
2. Build: cargo build (or, for smaller binaries, cargo build --release).
3. To try an example on a microcontroller eval board, see the README in the individual example. (In most cases cargo run in the directory will suffice.)

To build everything in the repo, run ./build-all.sh.

Contact and License

If you have questions, or you use it for something, I'd love to find out! Send me an email.

All the code in this repo is MPL-2 licensed.