This project is based on code from freertos.rs and some additions to simplify the usage of FreeRTOS in embedded applications written in Rust

Overview

FreeRTOS-rust

This project is based on code from freertos.rs and some additions to simplify the usage of FreeRTOS in embedded applications written in Rust.

In contrast to freertos.rs this crate differs in these points:

  • The application main() entry point is written in Rust.
  • The FreeRTOS scheduler can be started from Rust.
  • The FreeRTOS heap MemMang/heap/heap_x.cis used as global memory allocator for Rust
  • No need for a Clang skeleton project

How it works

The freertos-cargo-build build-dependency compiles the FreeRTOS code from its original "C" sources files into an archive to be linked against your Rust app. Internally it uses the cc crate and some meta info provided by your apps build.rs:

  1. A path to the FreeRTOS Sources
  2. A path to the app specific FreeRTOSConfig.h
  3. A relative path to the FreeRTOS port to be used, e.g. for ARM Cortex-M3 cores.
  4. Optional: Additional C code to be compiled

The freertos-rust dependency provides an interface to access all FreeRTOS functionality from your (embedded) Rust app.

Usage

  1. Checkout FreeRTOS: https://github.com/FreeRTOS/FreeRTOS-Kernel

  2. Add dependencies to your Rust apps Cargo.toml

    [dependencies]
    freertos-rust = "*"
    
    [build-dependencies]
    freertos-cargo-build = "*"
    
  3. Add this snippet to your apps build.rs:

    fn main() {
        let mut b = freertos_cargo_build::Builder::new();
    
        // Path to FreeRTOS kernel or set ENV "FREERTOS_SRC" instead
        b.freertos("path/to/FreeRTOS-Kernel");
        b.freertos_config("src");       // Location of `FreeRTOSConfig.h` 
        b.freertos_port("GCC/ARM_CM3"); // Port dir relativ to 'FreeRTOS-Kernel/portable' 
        b.heap("heap4.c");              // Set the heap_?.c allocator to use from 
                                        // 'FreeRTOS-Kernel/portable/MemMang' (Default: heap_4.c)       
    
        // b.get_cc().file("More.c");   // Optional additional C-Code to be compiled
    
        b.compile().unwrap_or_else(|e| { panic!(e.to_string()) });
    }
    

Used C compiler

freertos-cargo-build depends on the cc crate. So the C compiler used can be set by using the CC enviroment variable or otherwise defined by internal defaults. For the ARM architecture this is the arm-none-eabi-gcc which can be found here.

Examples

To get started there are examples in freertos-rust-examples for:

  • Cortex M33 (nRF9160)
  • Cortex M3 (STM32L151CBU6A)
  • Cortex M4 (STM32F411CEU6)
  • Windows
  • ...more to come...

Project Crates

License

This repository is using the MIT License. Some parts might state different licenses that need to be respected when used.

Comments
  • linux port: configCPU_CLOCK_HZ not defined

    linux port: configCPU_CLOCK_HZ not defined

    cargo:warning=/home/void/FreeRTOS-rust/freertos-rust/src/freertos/shim.c: In function 'freertos_rs_get_configCPU_CLOCK_HZ': cargo:warning=/home/void/FreeRTOS-rust/freertos-rust/src/freertos/shim.c:117:10: error: 'configCPU_CLOCK_HZ' undeclared (first use in this function) cargo:warning= 117 | return configCPU_CLOCK_HZ; cargo:warning= | ^~~~~~~~~~~~~~~~~~

    I realize this probably needs be defined in the examples / FreeRTOSConfig.h . Not sure what value to put there though...

    opened by johnathancn 8
  • Possible incorrect timing for `CurrentTask::delay;` on stm32f411

    Possible incorrect timing for `CurrentTask::delay;` on stm32f411

    First of all, thanks for your hard work on this project.

    I took the stm32f411 black pill example and promoted it to a free-standing repo. I was very happy to see it works nicely with defmt and newer versions of the stm32f4xx-hal. However, I did observe that the blinking frequency is way higher than 1Hz.

    https://github.com/barafael/really-fast-buttons/blob/a2081814e0dbff1d8ebc5d2aaa62761cebbb0252/freertos-tasks/src/main.rs#L70

    More like 6Hz estimated. This was also the case before I upgraded the hal dependencies and set

            let clocks = rcc.cfgr.use_hse(25.MHz()).sysclk(48.MHz()).freeze();
    

    I'm not sure if this issue is even in the right place, perhaps I shouldn't touch the timer configuration when FreeRTOS already does it?

    opened by barafael 5
  • `Semaphore::create_binary` can't be used

    `Semaphore::create_binary` can't be used

    Quoting the docs:

    [...] binary semaphores created using xSemaphoreCreateBinary() are created in a state such that the the semaphore must first be 'given' before it can be 'taken'
    

    The Semaphore API only allows locking, and then dropping the guard, which means there is no way to "give" a binary semaphore. This API also makes using Semaphores as synchronization tools unwieldy.

    opened by bugadani 4
  • FreeRTOS submodule doesn't have Linux port

    FreeRTOS submodule doesn't have Linux port

    thread 'main' panicked at 'Directory freertos_port_dir does not exist: FreeRTOS-Kernel/portable/GCC/Linux', freertos-rust-examples/build.rs:61:38

    Looks like this is recent regression following change from in-tree copy of Kernel to submodule. I checked upstream and can't find trace of that Linux folder ever being there, maybe it was added to the local copy in this repo

    opened by johnathancn 3
  • Removes FreeRTOS 9.0.0 and adds submodule to official FreeRTOS-Kernel…

    Removes FreeRTOS 9.0.0 and adds submodule to official FreeRTOS-Kernel…

    It looks like there is an edit to a critical function, here:

    https://github.com/lobaro/FreeRTOS-rust/blob/master/freertos-rust-examples/FreeRTOS/Source/tasks.c#L3041

    While bringing this up on a Cortex M4, I was getting hardfaults in the PendSVHandler after vTaskSwitchContext was called.

    This commit changes back to the base FreeRTOS source without the above edit. The source is removed from this repo, and is changed to a submodule.

    opened by apullin 3
  • Tasks are now given a handle to themselves.

    Tasks are now given a handle to themselves.

    It wasn't possible for a task to get its own handle, making features like wait_for_notification unusable without the aid of some dangerous juggling of global variables.

    Tasks are now handed their handle as an argument, making it so they can safely make use of such features.

    I also cleaned up some warnings that have cropped up with updates to Rust and ran cargo fmt on the project.

    opened by IamTheCarl 3
  • Working Cortex-M4 example

    Working Cortex-M4 example

    opened by tstellanova 3
  • Add CI script

    Add CI script

    Add basic CI script to check incoming pull requests and help maintain stability of master branch. Currently it only checks things that are working, but I left lines in place (commented out) for things that we plan to improve.

    Currently checks:

    • Build succeeds for the main library (warnings allowed)
      • freertos-rust
      • freertos-cargo-build
    • Examples build (for the one that already works)
      • stm32-cortex-m4-blackpill

    Not yet checked:

    • fmt
    • test
    • clippy
    • Build is clean (deny warnings)
    • All examples build
    • Examples build clean (deny warnings)

    Some of the current issues under discussion should allow us to check builds for linux and win examples soon.

    Toolchains are only set to nightly since the allocator_api still needs that.

    Also related to recent discussions, it's not clear if running this on ubuntu-latest means that we might miss some build issues on windows (where build succeeds on linux but not on windows). For future investigation outside of this PR.

    opened by schteve 2
  • Fix port base for non-linux targets

    Fix port base for non-linux targets

    Previous changes in #36 broke the non-Linux examples since the port base path by default was not set correctly. This PR changes the mechanism to use the user-supplied value if available, otherwise fall back on the portable directory inside the FreeRTOS kernel root.

    I confirmed that these examples work for me (with adding #define configCPU_CLOCK_HZ to avoid #35). The other have previously-existing build failures, at least on my machine.

    • linux
    • stm32-cortex-m4-blackpill (build only)
    • win

    @johnathancn please double check that this change still works for your use case.

    We've had a bunch of accidental build breakages in the examples recently (understandably so, since users often don't have more than one platform available to test with) so I'm going to make it a priority to get a CI script running for PR's.

    opened by schteve 2
  • bound `P: AsRef<Path>` for heap in freertos-cargo-build cannot infer type for string argument

    bound `P: AsRef` for heap in freertos-cargo-build cannot infer type for string argument

    I am trying to build this package with the latest nightly, and I am getting the following error:

    error[E0282]: type annotations needed
     --> build.rs:8:7
      |
    8 |     b.heap("heap_4.c".to_string());              // Set the heap_?.c allocator to use from
      |       ^^^^ cannot infer type for type parameter `P` declared on the associated function `heap`
    
    error: aborting due to previous error
    

    Notably, in my build.rs, I made the modification of explicit String conversion, otherwise I get a cargo error about mismatched types: b.heap("heap_4.c".to_string() );

    Relaxing the signature to: pub fn heap(&mut self, file_name: String) appears to resolve the build issue, although that is just a guess, and other regressions may be introduced.

    opened by apullin 2
  • Add Cargo features for functionality

    Add Cargo features for functionality

    Woudl it be possible to add Cargo features for the various bits of functionality? For example, I only want the allocator; otherwise I'm working with a no_std + alloc crate.

    opened by Manishearth 2
  • Blackpill example blink rate is wrong

    Blackpill example blink rate is wrong

    It seems the blackpill example blinks at the incorrect rate. It should blink with one toggle per second (0.5 Hz blink rate) with the given task timings but is going too fast. This is likely due to configCPU_CLOCK_HZ being set incorrectly.

    See #44

    opened by schteve 0
  • Proposal: re-organize examples to contain their own target and dependencies

    Proposal: re-organize examples to contain their own target and dependencies

    Currently, the dependencies are tied to the target-triple in freertos-rust-examples/Cargo.toml, and the build.rs ties example paths directly to targets.

    After some tinkering with cargo, it seems there might not be a way to improve on this.

    However, if each "example" is reorganized into its own cargo binary project, then:

    • the target triple can be put into .cargo/config.toml for each
    • dependencies for each can be made unique
    • build.rs does not need to link targets to example paths

    proposed reorg here: https://github.com/apullin/FreeRTOS-rust/tree/examples_reorg/freertos-rust-examples/examples/stm32f407-segger-trace

    This might be moot, since the "examples" should just be templates, and any new project would have a project-specific build.rs and config.toml anyway.

    However, this way, each refactored example would be a template to copy & adapt directly (just paths, I think?) for new projects.

    opened by apullin 5
  • Looking for Maintainer

    Looking for Maintainer

    The project was created in the urge of using Rust for our embedded development and was a first proof of concept. Unfortunately the real world makes it much harder to migrate to rust than I would like. That's the reason why we do not use the library in production yet.

    On the other side I see a lot of interest in moving the code forward and welcome this a lot. I just feel too inactive on GitHub to maintain the project alone with the Quality it deserves.

    If there is someone who like to help maintaining the library I'm open for suggestions.

    @schteve I just merged a lot of PR from you. If you have long term interest to use and develop the library, just let me know. @reitermarkus same holds for you.

    opened by niondir 8
  • Add delay provider

    Add delay provider

    This and other projects may require a delay provider (for example: https://github.com/stm32-rs/stm32f4xx-hal/blob/master/src/delay.rs) that provides delayms and delayus functions. lt should be possible to provide this functionality as part of this package. I am new to rust (I thought it could be a better option than c), but I use pdMS_TO_TICKS in C.

    opened by xoviat 2
Releases(0.1.0)
Owner
Lobaro
German (🇩🇪) startup specialized on full-stack industrial IoT development 📡📻
Lobaro
Experimental kernel for embedded devices written in Rust

bkernel is an experimental kernel for embedded devices written in Rust. I'm mostly trying out Rust now to see how it applies to kernel development. Pr

Alexey Shmalko 84 Dec 13, 2022
Learn to write an embedded OS in Rust

Operating System development tutorials in Rust on the Raspberry Pi

Rust Embedded 9.9k Jan 6, 2023
A Real Time Operating System in Rust for Cortex M3 embedded systems

A Real Time Operating System in Rust for Cortex M3 embedded systems

Manuel Forcén Muñoz 5 Jun 1, 2022
A secure embedded operating system for microcontrollers

Tock is an embedded operating system designed for running multiple concurrent, mutually distrustful applications on Cortex-M and RISC-V based embedded

Tock Embedded OS 4.1k Jan 5, 2023
A secure embedded operating system for microcontrollers

Tock is an embedded operating system designed for running multiple concurrent, mutually distrustful applications on Cortex-M and RISC-V based embedded

Tock Embedded OS 4k Jan 2, 2023
Hubris is a microcontroller operating environment designed for deeply-embedded systems

A lightweight, memory-protected, message-passing kernel for deeply embedded systems.

Oxide Computer Company 2.1k Jan 6, 2023
Real Time For the Masses (RTFM), a framework for building concurrent applications, for MSP430 MCUs

msp430-rtfm Real Time For the Masses (RTFM), a framework for building concurrent applications, for MSP430 MCUs License Licensed under either of Apache

Jorge Aparicio 9 Sep 10, 2022
GZTime's GGOS for OS course project.

GZTime's GG OS OS course project. The basic development of this course operating system has been completed. Using JetBrainsMono as console font. Usage

GZTime 15 Dec 30, 2022
RiiR project to find available slots for SOS Médecins Oise

SOS Médecins Oise available slots Update 2022-12-28 I've found that all slots for the day are dumped at 6am, 9am and 11am This is a small RiiR project

Pierre Tondereau 3 Jan 10, 2023
suidsnoop is a tool based on eBPF LSM programs that logs whenever a suid binary is executed and implements custom allow/deny lists.

suidsnoop Log suid binaries and enforce per-uid suid policy. suidsnoop is a tool for logging whenever a suid binary is executed on your system and opt

William Findlay 11 Dec 22, 2022
A language-based OS to run Rust on bare metal

RustOS A simple, language-based OS. Current features: Simple VGA for seeing output Some Rust libraries (core, alloc, collections) already in Working (

null 402 Dec 8, 2022
A language-based OS to run Rust on bare metal

RustOS A simple, language-based OS. Current features: Simple VGA for seeing output Some Rust libraries (core, alloc, collections) already in Working (

null 79 Dec 3, 2022
A lightweight microkernel/IPC based operating system built with Rust which is not a clone of any existing operating system

Noble Operating System Noble is a lightweight microkernel and IPC based operating system built with Rust which is not a clone of any existing operatin

Revolution Xenon 3 Jan 10, 2022
A Rust-based userland which also adds compile-time assurances to seL4 development.

ferros Overview A Rust library to add extra assurances to seL4 development. ferros provides smart type-safe wrappers around seL4 features with an emph

Auxon Corporation 68 Dec 25, 2022
Aero is a new modern, unix based operating system. It is being developed for educational purposes.

Areo Aero is a new modern, unix based operating system written in Rust and is being developed for educational purposes. Aero follows the monolithic ke

Anhad Singh 623 Dec 24, 2022
A fresh FRAME-based Substrate node, ready for hacking

Substrate Node Template A fresh FRAME-based Substrate node, ready for hacking ?? Getting Started Follow the steps below to get started with the Node T

Worlddev5007 13 Aug 26, 2022
🍒 Small, simple, and fast kernel written in Rust. 🌸

?? Small, simple, and fast kernel written in Rust. ??

Cherry Developers 5 May 20, 2022
An UEFI application that unlocks a SED and starts an OS from it. Written in Rust

opal-uefi-greeter This is an UEFI application written in Rust that unlocks a SED and then launches another UEFI application from the unlocked drive -

Anton Bulakh 26 Jan 4, 2023
A comparison of operating systems written in Rust

Rust OS comparison A comparison of operating systems written in Rust. There are several open source operating systems written in Rust. Most of them ar

Markus Kohlhase 492 Jan 8, 2023