Crate freertos_next

Expand description

§FreeRTOS

freertos-next is a Rust wrapper for the FreeRTOS API.

It bundles the official 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:

The crate is published as freertos-next on crates.io because the more obvious names (freertos, freertos-rust) are already taken.

§📦 Usage

freertos-next works together with freertos-build.

Add the dependencies to your application:

cargo add freertos-next
cargo add --build freertos-build

Add the following snippet to your application’s build.rs:

use freertos_build::prelude::*;

fn main() {
    let mut b = freertos_build::Builder::new();
    b.cpu_clock(72.MHz());
    b.heap_size(10 * 1024);
    b.minimal_stack_size(80);
    b.interrupt_priority_bits(4, 5, 15);
    b.compile().unwrap();
}

For more Optional configuration, see freertos-build

A complete example using freertos-next with stm32f1-hal is available here: stm32f1-FreeRTOS-example

§📘 C Compiler

freertos-build uses the 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.

For ARM targets, the expected compiler is arm-none-eabi-gcc, which can be obtained from the ARM GNU toolchain.

§Install

# Ubuntu
sudo apt-get install -y gcc-arm-none-eabi

# Windows (Scoop)
scoop install gcc-arm-none-eabi

Re-exports§

pub use os_trait;

Modules§

patterns
prelude

Macros§

os_type_alias: Use this macro to alias the OS-specific types for greater convenience, or manually alias only the ones you need.

Structs§

CriticalRegion
CurrentTask: Helper methods to be performed on the task that is currently executing.
DurationImpl: Time unit used by FreeRTOS, passed to the scheduler as ticks.
EventGroup: An event group
ExclusiveData: Data protected with a critical region. Lightweight version of a mutex, intended for simple data structures.
ExclusiveDataGuard: Holds the mutex until we are dropped
ExclusiveDataGuardIsr
FreeRtosAllocator: Use with:
FreeRtosRawMutex: mutex-traits implementation
FreeRtosSystemState
FreeRtosTaskStatus
FreeRtosTaskStatusFfi
FreeRtosTimeUnitsShimmed
FreeRtosUtils
InterruptContext: Keep track of whether we need to yield the execution to a different task at the end of the interrupt.
MutexGuard: Holds the mutex until we are dropped
MutexImpl: Mutual exclusion access to a contained value. Can be recursive - the current owner of a lock can re-lock it.
MutexNormal
MutexRecursive
Queue: A queue with a finite size.
Semaphore: A counting or binary semaphore
SemaphoreGuard: Holds the lock to the semaphore until we are dropped
SendError
SuspendScheduler: Data protected with a critical region, implemented by suspending the FreeRTOS scheduler.
SuspendSchedulerGuard
Task: Handle for a FreeRTOS task
TaskBuilder: Helper for spawning a new task. Instantiate with Task::new().
TaskDelayPeriodic: Periodic delay timer.
TaskPriority: Task’s execution priority. Low priority numbers denote low priority tasks.
Timer: A FreeRTOS software timer.
TimerBuilder: Helper builder for a new software timer.

Enums§

FreeRtosError: Basic error type for the library.
FreeRtosSchedulerState
FreeRtosTaskState
TaskNotification: Notification to be sent to a task.

Traits§

DurationTicks
FreeRtosTimeUnits
MutexInnerImpl

Functions§

assert_callback
freertos_rs_create_binary_semaphore^⚠
freertos_rs_create_counting_semaphore^⚠
freertos_rs_create_mutex^⚠
freertos_rs_create_recursive_mutex^⚠
freertos_rs_delete_semaphore^⚠
freertos_rs_delete_task^⚠
freertos_rs_enter_critical^⚠
freertos_rs_enter_critical_from_isr^⚠
freertos_rs_event_group_clear_bits^⚠
freertos_rs_event_group_create^⚠
freertos_rs_event_group_delete^⚠
freertos_rs_event_group_get_bits^⚠
freertos_rs_event_group_set_bits^⚠
freertos_rs_event_group_sync^⚠
freertos_rs_event_group_wait_bits^⚠
freertos_rs_exit_critical^⚠
freertos_rs_exit_critical_from_isr^⚠
freertos_rs_get_current_task^⚠
freertos_rs_get_free_heap_size^⚠
freertos_rs_get_minimum_free_heap_size^⚠
freertos_rs_get_number_of_tasks^⚠
freertos_rs_get_portTICK_PERIOD_MS^⚠
freertos_rs_get_stack_high_water_mark^⚠
freertos_rs_get_system_state^⚠
freertos_rs_give_recursive_semaphore^⚠
freertos_rs_give_semaphore^⚠
freertos_rs_give_semaphore_isr^⚠
freertos_rs_invoke_configASSERT^⚠
freertos_rs_is_in_isr^⚠
freertos_rs_isr_yield^⚠
freertos_rs_max_wait^⚠
freertos_rs_pvPortMalloc^⚠
freertos_rs_queue_create^⚠
freertos_rs_queue_delete^⚠
freertos_rs_queue_messages_waiting^⚠
freertos_rs_queue_receive^⚠
freertos_rs_queue_send^⚠
freertos_rs_queue_send_isr^⚠
freertos_rs_reset_minimum_free_heap_size^⚠
freertos_rs_sizeof^⚠
freertos_rs_spawn_task^⚠
freertos_rs_suspend_task^⚠
freertos_rs_take_recursive_semaphore^⚠
freertos_rs_take_semaphore^⚠
freertos_rs_take_semaphore_isr^⚠
freertos_rs_task_get_name^⚠
freertos_rs_task_notify^⚠
freertos_rs_task_notify_isr^⚠
freertos_rs_task_notify_take^⚠
freertos_rs_task_notify_wait^⚠
freertos_rs_task_yield^⚠
freertos_rs_timer_change_period^⚠
freertos_rs_timer_create^⚠
freertos_rs_timer_delete^⚠
freertos_rs_timer_get_id^⚠
freertos_rs_timer_start^⚠
freertos_rs_timer_start_from_isr^⚠
freertos_rs_timer_stop^⚠
freertos_rs_uxTaskGetTaskNumber^⚠
freertos_rs_vPortFree^⚠
freertos_rs_vTaskDelay^⚠
freertos_rs_vTaskDelayUntil^⚠
freertos_rs_vTaskSetTaskNumber^⚠
freertos_rs_vTaskStartScheduler^⚠
freertos_rs_vTaskSuspendAll^⚠
freertos_rs_xTaskGetTickCount^⚠
freertos_rs_xTaskGetTickCountFromISR^⚠
freertos_rs_xTaskResumeAll^⚠
freertos_rt_xTaskGetSchedulerState^⚠
is_in_isr
shim_sanity_check: Perform checks whether the C FreeRTOS shim and Rust agree on the sizes of used types.
str_from_c_string^⚠: Safety