diff --git a/freertos-build/README.md b/freertos-build/README.md index 461a5dc..c9a28ef 100644 --- a/freertos-build/README.md +++ b/freertos-build/README.md @@ -1,19 +1,23 @@ # freertos-build +[![CI](https://github.com/mcu-rust/freertos/workflows/CI/badge.svg)](https://github.com/mcu-rust/freertos/actions) [![Crates.io](https://img.shields.io/crates/v/freertos-build.svg)](https://crates.io/crates/freertos-build) +[![Docs.rs](https://docs.rs/freertos-build/badge.svg)](https://docs.rs/freertos-build) +[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](./LICENSE) +[![Downloads](https://img.shields.io/crates/d/freertos-build.svg)](https://crates.io/crates/freertos-build) - -Helper crate for [freertos-next](https://crates.io/crates/freertos-next) by building FreeRTOS applications with Cargo and Rust using a `build.rs`. +As part of the [freertos-next](https://crates.io/crates/freertos-next) ecosystem, `freertos-build` provides a simple and reliable way to build FreeRTOS applications using Cargo. +It integrates FreeRTOS into your Rust project through a `build.rs`, automatically compiling the kernel sources and applying your custom `FreeRTOSConfig.h`. See also [freertos README](https://github.com/mcu-rust/FreeRTOS/tree/main/freertos). -## Usage +## 馃摝 Usage -```shel +```sh cargo add --build freertos-build ``` -Add this snippet to your apps `build.rs`: +Add the following snippet to your application's `build.rs`: ```rust fn main() { let mut b = freertos_build::Builder::new(); diff --git a/freertos/README.md b/freertos/README.md index 8636ad2..015b9f9 100644 --- a/freertos/README.md +++ b/freertos/README.md @@ -1,60 +1,69 @@ # FreeRTOS - +[![CI](https://github.com/mcu-rust/freertos/workflows/CI/badge.svg)](https://github.com/mcu-rust/freertos/actions) [![Crates.io](https://img.shields.io/crates/v/freertos-next.svg)](https://crates.io/crates/freertos-next) +[![Docs.rs](https://docs.rs/freertos-next/badge.svg)](https://docs.rs/freertos-next) +[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](./LICENSE) +[![Downloads](https://img.shields.io/crates/d/freertos-next.svg)](https://crates.io/crates/freertos-next) + +`freertos-next` is a Rust wrapper for the FreeRTOS API. -Wrapper library to use FreeRTOS API in Rust. +- It bundles the official [FreeRTOS-Kernel](https://github.com/FreeRTOS/FreeRTOS-Kernel) sources (currently `V11.2.0`). + If you need a customized setup, you can prepare your own kernel source files and call `b.freertos("path/to/your/kernel");` in your `build.rs`. +- It implements several traits to ensure smooth integration with embedded projects: + - [`os-trait`](https://crates.io/crates/os-trait) + - [`critical-section`](https://crates.io/crates/critical-section) + - [`mutex-traits`](https://crates.io/crates/mutex-traits) -- It includes the source code of [FreeRTOS-Kernel](https://github.com/FreeRTOS/FreeRTOS-Kernel). Current version is `V11.2.0`. - - If you have any specific requirements, please prepare your source code and call `b.freertos("path/to/your/kernel");` in your `build.rs` file. -- It implements some useful traits: - - [os-trait](https://crates.io/crates/os-trait) - - [critical-section](https://crates.io/crates/critical-section). - - [mutex-traits](https://crates.io/crates/mutex-traits). +The crate is published as **freertos-next** on crates.io because the more obvious names (`freertos`, `freertos-rust`) are already taken. -It's named **freertos-next** on crates.io right now, because we can't choose a shorter name. +## 馃摝 Usage -## Usage +1. Add the dependencies to your application: -1. Add dependencies to your Rust APP -```shell +```sh cargo add freertos-next cargo add --build freertos-build ``` - -2. Add this snippet to your APP's `build.rs`: +2. Add the following snippet to your application's `build.rs`: ```rust fn main() { let mut b = freertos_build::Builder::new(); - b.freertos_config("src_c"); // Location of `FreeRTOSConfig.h` + b.freertos_config("src_c"); // Path to your FreeRTOSConfig.h b.compile().unwrap(); } ``` -3. Optional: +3. Optional configuration: ```rust -// If you want to use you own source code. +// Use your own FreeRTOS-Kernel source tree b.freertos("path/to/FreeRTOS-Kernel"); -// Path relative to 'FreeRTOS-Kernel/portable'. -// If the default path is not what you want. + +// Override the default port (relative to FreeRTOS-Kernel/portable) b.freertos_port("GCC/ARM_CM3"); -// Set the heap_?.c allocator to use from 'FreeRTOS-Kernel/portable/MemMang' -// (Default: heap_4.c) + +// Select the heap allocator from FreeRTOS-Kernel/portable/MemMang +// Default: heap_4.c b.heap("heap_4.c"); ``` +[freertos-next](https://github.com/mcu-rust/FreeRTOS/tree/main/freertos) works together with [freertos-build](https://crates.io/crates/freertos-build). A complete example using [freertos-next](https://github.com/mcu-rust/FreeRTOS/tree/main/freertos) with [stm32f1-hal](https://crates.io/crates/stm32f1-hal) is available here: [stm32f1-FreeRTOS-example](https://github.com/mcu-rust/stm32f1-FreeRTOS-example) + +## 馃摌 C Compiler +`freertos-build` uses the [`cc`](https://docs.rs/crate/cc) crate to compile the FreeRTOS kernel. +The C compiler can be configured via the `CC` environment variable, or it will fall back to the defaults provided by `cc`. -It needs [freertos-build](https://crates.io/crates/freertos-build) to work with. [stm32f1-FreeRTOS-example](https://github.com/mcu-rust/stm32f1-FreeRTOS-example) shows how to use this crate with [stm32f1-hal](https://crates.io/crates/stm32f1-hal) together. +For ARM targets, the expected compiler is `arm-none-eabi-gcc`, which can be obtained from the [ARM GNU toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads). -### Used C compiler -`freertos-build` depends on the [cc crate](https://docs.rs/crate/cc). 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](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads). +### Install -Install: -```shell -# on Ubuntu +```sh +# Ubuntu sudo apt-get install -y gcc-arm-none-eabi -# on Windows + +# Windows (Scoop) scoop install gcc-arm-none-eabi ``` +For more details, see the main [repository](https://github.com/mcu-rust/FreeRTOS). + +## 馃敄 Keywords -See also [repository](https://github.com/mcu-rust/FreeRTOS). +freertos 路 rtos 路 rust 路 embedded 路 embedded-hal 路 no-std 路 arm 路 cortex-m 路 scheduler 路 multitasking 路 bindings 路 wrapper