https://github.com/cbiffle/lilos

A wee async RTOS for Cortex-M
https://github.com/cbiffle/lilos

Last synced: 4 days ago
JSON representation

A wee async RTOS for Cortex-M

• Host: GitHub
• URL: https://github.com/cbiffle/lilos
• Owner: cbiffle
• License: mpl-2.0
• Created: 2011-04-03T03:38:27.000Z (over 13 years ago)
• Default Branch: main
• Last Pushed: 2024-10-22T16:19:36.000Z (20 days ago)
• Last Synced: 2024-10-31T11:47:53.429Z (11 days ago)
• Language: Rust
• Homepage:
• Size: 618 KB
• Stars: 694
• Watchers: 16
• Forks: 34
• Open Issues: 5
• Metadata Files:
  • Readme: README.mkdn
  • License: LICENSE

Awesome Lists containing this project

README

        
# `lilos`: A minimal async RTOS

![crates.io published version badge](https://img.shields.io/crates/v/lilos.svg)

![docs.rs badge link](https://img.shields.io/docsrs/lilos.svg)

![CI status badge](https://github.com/cbiffle/lilos/actions/workflows/ci.yml/badge.svg)

- [Intro guide](doc/intro.adoc)

- [API Docs](https://docs.rs/lilos)

- [crates.io](https://crates.io/crates/lilos)

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](https://github.com/cbiffle/lilos/blob/main/testsuite/README.mkdn) 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.