/***************************************************************************
 *
 * 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 type definitions and handle wrappers.
//!
//! This module provides type aliases and handle types that interface with FreeRTOS.
//! Types are generated at build time from the FreeRTOS configuration.
//!
//! # Generated Types
//!
//! The following types are generated from `FreeRTOSConfig.h` at build time:
//!
//! - `TickType` - System tick counter type (typically `u32` or `u64`)
//! - `BaseType` - Basic signed integer type for return values
//! - `UBaseType` - Basic unsigned integer type
//! - `StackType` - Type used for stack allocation
//!
//! # Handle Types
//!
//! FreeRTOS uses opaque pointers (handles) to reference OS objects:
//!
//! - `ThreadHandle` - References a FreeRTOS task
//! - `QueueHandle` - References a message queue
//! - `SemaphoreHandle` - References a semaphore
//! - `MutexHandle` - References a mutex
//! - `EventGroupHandle` - References an event group
//! - `TimerHandle` - References a software timer
//!
//! # Examples
//!
//! ```ignore
//! use osal_rs::os::types::*;
//!
//! // Using tick types for timing
//! let delay_ticks: TickType = 1000;
//!
//! // Using handles (typically obtained from create functions)
//! let handle: ThreadHandle = std::ptr::null_mut();
//! ```

// Include build-time generated types from FreeRTOS configuration
// This file is generated by the build script and contains:
// - TickType: System tick counter type
// - BaseType: Basic signed integer type
// - UBaseType: Basic unsigned integer type
// - StackType: Stack allocation type
include!(concat!(env!("OUT_DIR"), "/types_generated.rs"));    

/// FreeRTOS opaque handle types for OS primitives.
///
/// These handles are opaque pointers used to reference FreeRTOS objects.
/// They should not be dereferenced directly; instead, use the safe wrappers
/// provided by this crate (e.g., `Thread`, `Queue`, `Semaphore`, etc.).
///
/// # Handle Types
///
/// - **`ThreadHandle`**: Handle to a FreeRTOS task/thread
/// - **`QueueHandle`**: Handle to a message queue for inter-thread communication
/// - **`SemaphoreHandle`**: Handle to a counting or binary semaphore
/// - **`MutexHandle`**: Handle to a recursive mutex with priority inheritance
/// - **`EventGroupHandle`**: Handle to an event group for multi-bit synchronization
/// - **`TimerHandle`**: Handle to a software timer
///
/// # Safety
///
/// These are raw pointers to FreeRTOS internal structures. Always use the
/// safe Rust wrappers instead of manipulating handles directly.
///
/// # Examples
///
/// ```ignore
/// use osal_rs::os::{Thread, types::ThreadHandle};
///
/// // Typically you get handles from wrapper constructors
/// let thread = Thread::new("worker", 2048, 5).unwrap();
/// // The handle is managed internally by the Thread wrapper
/// ```
pub use super::ffi::{ThreadHandle, QueueHandle, SemaphoreHandle, EventGroupHandle, TimerHandle, MutexHandle};

/// Type alias for event group bits.
///
/// Represents a set of event flags where each bit can be set or cleared independently.
/// The underlying type is `TickType`, which is typically `u32` or `u64` depending on
/// the FreeRTOS configuration.
///
/// # Bit Usage
///
/// - **Usable bits**: For `u32`, 24 bits (0-23) are usable; top 8 bits are reserved
///   by FreeRTOS for internal use. For `u64`, 56 bits are usable.
/// - **Maximum mask**: Use `EventGroup::MAX_MASK` for the maximum safe mask value.
///
/// # Examples
///
/// ```ignore
/// use osal_rs::os::types::EventBits;
/// use osal_rs::os::{EventGroup, EventGroupFn};
///
/// const EVENT_A: EventBits = 1 << 0;  // Bit 0
/// const EVENT_B: EventBits = 1 << 1;  // Bit 1
/// const EVENT_C: EventBits = 1 << 2;  // Bit 2
///
/// let event_group = EventGroup::new().unwrap();
///
/// // Set multiple bits
/// event_group.set(EVENT_A | EVENT_B);
///
/// // Wait for any bit
/// let result = event_group.wait(EVENT_A | EVENT_C, 1000);
///
/// // Check specific bits
/// if result & EVENT_A != 0 {
///     println!("Event A occurred");
/// }
/// ```
pub type EventBits = TickType;

