1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
/***************************************************************************
*
* osal-rs
* Copyright (C) 2026 Antonio Salsi <passy.linux@zresa.it>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, see <https://www.gnu.org/licenses/>.
*
***************************************************************************/
//! FreeRTOS implementation of OSAL-RS traits.
//!
//! This module provides concrete implementations of all OSAL-RS traits for
//! the FreeRTOS real-time operating system, enabling portable real-time
//! applications across different RTOS implementations.
//!
//! # Overview
//!
//! FreeRTOS is a popular open-source RTOS for embedded systems, providing:
//! - Preemptive multitasking with priority-based scheduling
//! - Multiple synchronization primitives (mutexes, semaphores, queues)
//! - Software timers
//! - Memory management
//! - Low memory footprint
//!
//! This module wraps the FreeRTOS C API with safe Rust abstractions that
//! implement the OSAL-RS trait interfaces.
//!
//! # Modules
//!
//! - [`allocator`] - Memory allocation using FreeRTOS heap
//! - [`config`] - FreeRTOS configuration constants
//! - [`duration`] - Duration type conversions for FreeRTOS ticks
//! - [`event_group`] - Event group synchronization primitives
//! - [`mutex`] - Mutex implementations with priority inheritance
//! - [`queue`] - Message queues for inter-task communication
//! - [`semaphore`] - Binary and counting semaphores
//! - [`system`] - System-level RTOS control and timing
//! - [`thread`] - Task/thread creation and management
//! - [`timer`] - Software timers for delayed/periodic callbacks
//! - [`types`] - FreeRTOS-specific type definitions
//!
//! # Requirements
//!
//! - FreeRTOS kernel source code (linked at build time)
//! - Proper FreeRTOSConfig.h configuration for your platform
//! - C compiler for building FreeRTOS kernel
//!
//! # Configuration
//!
//! FreeRTOS behavior is configured at compile time via `FreeRTOSConfig.h`.
//! Key settings include:
//! - `configTICK_RATE_HZ` - System tick frequency (typically 100-1000 Hz)
//! - `configMAX_PRIORITIES` - Number of priority levels
//! - `configTOTAL_HEAP_SIZE` - Heap size for dynamic allocation
//! - `configUSE_PREEMPTION` - Enable preemptive scheduling
//! - `configUSE_MUTEXES` - Enable mutex support
//! - `configUSE_TIMERS` - Enable software timer support
//!
//! # Usage
//!
//! Types from this module implement the traits defined in [`crate::traits`],
//! allowing you to write portable code that works across different RTOS
//! implementations.
//!
//! ## Example: Creating a Thread
//!
//! ```ignore
//! use osal_rs::freertos::thread::Thread;
//! use osal_rs::freertos::system::System;
//! use osal_rs::traits::Thread as ThreadTrait;
//! use osal_rs::traits::System as SystemTrait;
//!
//! let mut thread = Thread::new("worker", 1024, 5);
//! thread.spawn_simple(|| {
//! loop {
//! println!("Working...");
//! System::delay(1000);
//! }
//! }).unwrap();
//!
//! System::start(); // Start FreeRTOS scheduler
//! ```
//!
//! ## Example: Using a Queue
//!
//! ```ignore
//! use osal_rs::freertos::queue::Queue;
//! use osal_rs::traits::Queue as QueueTrait;
//!
//! let queue = Queue::new(10, 16).unwrap();
//!
//! // Producer
//! let data = [1, 2, 3, 4];
//! queue.post(&data, 100).unwrap();
//!
//! // Consumer
//! let mut buffer = [0u8; 16];
//! queue.fetch(&mut buffer, 100).unwrap();
//! ```
//!
//! # Platform Support
//!
//! FreeRTOS supports many architectures including:
//! - ARM Cortex-M (M0, M0+, M3, M4, M7, M33, M55)
//! - ARM Cortex-A
//! - RISC-V
//! - x86
//! - And many others
//!
//! Each platform requires a port-specific configuration and startup code.
//!
//! # Safety
//!
//! This module uses FFI to call FreeRTOS C functions. The Rust wrappers
//! ensure memory safety through:
//! - Proper lifetime management
//! - Type safety
//! - Resource cleanup (RAII)
//! - Checked conversions
//!
//! # Performance
//!
//! FreeRTOS is designed for resource-constrained embedded systems with:
//! - Fast context switches (typically < 1µs on modern MCUs)
//! - Small memory footprint (< 10KB with typical configuration)
//! - Low interrupt latency
//! - Efficient priority-based scheduler
/// Memory allocator using FreeRTOS heap.
/// FreeRTOS FFI (Foreign Function Interface) bindings.
///
/// This module is private and contains unsafe C bindings to the FreeRTOS kernel.
/// FreeRTOS configuration constants and utilities.
/// Duration type implementations for FreeRTOS tick conversion.
/// Event group synchronization primitives.
/// Mutex implementations with optional priority inheritance.
/// Message queue implementations for inter-task communication.
/// Binary and counting semaphore implementations.
/// System-level RTOS control, timing, and scheduler management.
/// Task/thread creation, management, and notifications.
/// Software timer implementations for delayed and periodic callbacks.
/// FreeRTOS-specific type definitions and aliases.