osal_rs/freertos/
types.rs

1/***************************************************************************
2 *
3 * osal-rs
4 * Copyright (C) 2026 Antonio Salsi <passy.linux@zresa.it>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, see <https://www.gnu.org/licenses/>.
18 *
19 ***************************************************************************/
20
21//! FreeRTOS type definitions and handle wrappers.
22//!
23//! This module provides type aliases and handle types that interface with FreeRTOS.
24//! Types are generated at build time from the FreeRTOS configuration.
25//!
26//! # Generated Types
27//!
28//! The following types are generated from `FreeRTOSConfig.h` at build time:
29//!
30//! - `TickType` - System tick counter type (typically `u32` or `u64`)
31//! - `BaseType` - Basic signed integer type for return values
32//! - `UBaseType` - Basic unsigned integer type
33//! - `StackType` - Type used for stack allocation
34//!
35//! # Handle Types
36//!
37//! FreeRTOS uses opaque pointers (handles) to reference OS objects:
38//!
39//! - `ThreadHandle` - References a FreeRTOS task
40//! - `QueueHandle` - References a message queue
41//! - `SemaphoreHandle` - References a semaphore
42//! - `MutexHandle` - References a mutex
43//! - `EventGroupHandle` - References an event group
44//! - `TimerHandle` - References a software timer
45//!
46//! # Examples
47//!
48//! ```ignore
49//! use osal_rs::os::types::*;
50//!
51//! // Using tick types for timing
52//! let delay_ticks: TickType = 1000;
53//!
54//! // Using handles (typically obtained from create functions)
55//! let handle: ThreadHandle = std::ptr::null_mut();
56//! ```
57
58// Include build-time generated types from FreeRTOS configuration
59// This file is generated by the build script and contains:
60// - TickType: System tick counter type
61// - BaseType: Basic signed integer type
62// - UBaseType: Basic unsigned integer type
63// - StackType: Stack allocation type
64include!(concat!(env!("OUT_DIR"), "/types_generated.rs"));    
65
66use core::ffi::c_void;
67
68/// FreeRTOS opaque handle types for OS primitives.
69///
70/// These handles are opaque pointers used to reference FreeRTOS objects.
71/// They should not be dereferenced directly; instead, use the safe wrappers
72/// provided by this crate (e.g., `Thread`, `Queue`, `Semaphore`, etc.).
73///
74/// # Handle Types
75///
76/// - **`ThreadHandle`**: Handle to a FreeRTOS task/thread
77/// - **`QueueHandle`**: Handle to a message queue for inter-thread communication
78/// - **`SemaphoreHandle`**: Handle to a counting or binary semaphore
79/// - **`MutexHandle`**: Handle to a recursive mutex with priority inheritance
80/// - **`EventGroupHandle`**: Handle to an event group for multi-bit synchronization
81/// - **`TimerHandle`**: Handle to a software timer
82///
83/// # Safety
84///
85/// These are raw pointers to FreeRTOS internal structures. Always use the
86/// safe Rust wrappers instead of manipulating handles directly.
87///
88/// # Examples
89///
90/// ```ignore
91/// use osal_rs::os::{Thread, types::ThreadHandle};
92///
93/// // Typically you get handles from wrapper constructors
94/// let thread = Thread::new("worker", 2048, 5).unwrap();
95/// // The handle is managed internally by the Thread wrapper
96/// ```
97pub type ThreadHandle = *const c_void;
98pub type QueueHandle = *const c_void;
99pub type SemaphoreHandle = *const c_void;
100pub type EventGroupHandle = *const c_void;
101pub type TimerHandle = *const c_void;
102pub type MutexHandle = *const c_void;
103
104/// Type alias for event group bits.
105///
106/// Represents a set of event flags where each bit can be set or cleared independently.
107/// The underlying type is `TickType`, which is typically `u32` or `u64` depending on
108/// the FreeRTOS configuration.
109///
110/// # Bit Usage
111///
112/// - **Usable bits**: For `u32`, 24 bits (0-23) are usable; top 8 bits are reserved
113///   by FreeRTOS for internal use. For `u64`, 56 bits are usable.
114/// - **Maximum mask**: Use `EventGroup::MAX_MASK` for the maximum safe mask value.
115///
116/// # Examples
117///
118/// ```ignore
119/// use osal_rs::os::types::EventBits;
120/// use osal_rs::os::{EventGroup, EventGroupFn};
121///
122/// const EVENT_A: EventBits = 1 << 0;  // Bit 0
123/// const EVENT_B: EventBits = 1 << 1;  // Bit 1
124/// const EVENT_C: EventBits = 1 << 2;  // Bit 2
125///
126/// let event_group = EventGroup::new().unwrap();
127///
128/// // Set multiple bits
129/// event_group.set(EVENT_A | EVENT_B);
130///
131/// // Wait for any bit
132/// let result = event_group.wait(EVENT_A | EVENT_C, 1000);
133///
134/// // Check specific bits
135/// if result & EVENT_A != 0 {
136///     println!("Event A occurred");
137/// }
138/// ```
139pub type EventBits = TickType;
140
osal_rs/freertos/types.rs

osal_rs/freertos/
types.rs
