/********************************************************************************************************* * ------------------------------------------------------------------------------------------------------ * file description * ------------------------------------------------------------------------------------------------------ * \file coroutine_hook.h * \unit coroutine * \brief Predefined idleHook and wakeupHook implementations for Bare-Metal, RTOS and OS platforms * \author Lamdonn * \version v0.2.0 * \license GPL-2.0 * \copyright Copyright (C) 2025 Lamdonn. ********************************************************************************************************/ #ifndef __coroutine_hook_H #define __coroutine_hook_H #include "coroutine.h" #include #include #ifdef __cplusplus extern "C" { #endif /* ======================================================================================================= * 1. Bare-metal / Embedded MCU Hooks (ARM Cortex-M, RISC-V, Xtensa, C-SKY, MSP430, etc.) * ======================================================================================================= */ /** * \brief: Bare-metal low power idle hook using hardware sleep instruction (wfi / waiti / sleep / LPM) * \param schedulerId: Target scheduler ID * \param idleUs: Estimated idle time in microseconds * \note: Puts the CPU core into low-power sleep mode until an interrupt occurs. */ void CoHook_Baremetal_Idle(uint32_t schedulerId, uint32_t idleUs); /** * \brief: Bare-metal wakeup hook * \param schedulerId: Target scheduler ID * \note: On single-core MCU, hardware interrupts automatically wake the CPU from WFI. * In multi-core/AMP setups, triggers SEV (Send Event) or an Inter-Processor Interrupt (IPI). */ void CoHook_Baremetal_Wakeup(uint32_t schedulerId); /* ======================================================================================================= * 2. FreeRTOS Hooks (Task Notification based, Zero-RAM overhead) * ======================================================================================================= */ /** * \brief: Initialize FreeRTOS hooks for a scheduler, binding it to the target FreeRTOS task * \param schedulerId: Target scheduler ID * \param taskHandle: FreeRTOS TaskHandle_t running this scheduler (or NULL to use xTaskGetCurrentTaskHandle()) * \return: 0 on success, or negative error code */ int CoHook_FreeRTOS_Init(uint32_t schedulerId, void *taskHandle); /** * \brief: FreeRTOS idle hook (calls ulTaskNotifyTake with timeout) * \param schedulerId: Target scheduler ID * \param idleUs: Sleep timeout in microseconds */ void CoHook_FreeRTOS_Idle(uint32_t schedulerId, uint32_t idleUs); /** * \brief: FreeRTOS wakeup hook (calls xTaskNotifyGive / vTaskNotifyGiveFromISR) * \param schedulerId: Target scheduler ID to wake up */ void CoHook_FreeRTOS_Wakeup(uint32_t schedulerId); /** * \brief: Deinitialize FreeRTOS hooks for a scheduler * \param schedulerId: Target scheduler ID */ void CoHook_FreeRTOS_Deinit(uint32_t schedulerId); /* ======================================================================================================= * 3. RT-Thread Hooks (rt_sem semaphore based) * ======================================================================================================= */ /** * \brief: Initialize RT-Thread semaphore-based hooks for a scheduler * \param schedulerId: Target scheduler ID * \return: 0 on success, or negative error code */ int CoHook_RTThread_Init(uint32_t schedulerId); /** * \brief: RT-Thread idle hook (calls rt_sem_take with timeout) * \param schedulerId: Target scheduler ID * \param idleUs: Sleep timeout in microseconds */ void CoHook_RTThread_Idle(uint32_t schedulerId, uint32_t idleUs); /** * \brief: RT-Thread wakeup hook (calls rt_sem_release) * \param schedulerId: Target scheduler ID to wake up */ void CoHook_RTThread_Wakeup(uint32_t schedulerId); /** * \brief: Deinitialize RT-Thread hooks for a scheduler * \param schedulerId: Target scheduler ID */ void CoHook_RTThread_Deinit(uint32_t schedulerId); /* ======================================================================================================= * 4. CMSIS-RTOS2 Hooks (ARM Standard - Keil RTX5, FreeRTOS-CMSIS wrapper, etc.) * ======================================================================================================= */ /** * \brief: Initialize CMSIS-RTOS2 hooks for a scheduler * \param schedulerId: Target scheduler ID * \param threadId: osThreadId_t running this scheduler (or NULL to use osThreadGetId()) * \return: 0 on success, or negative error code */ int CoHook_CMSIS_Init(uint32_t schedulerId, void *threadId); /** * \brief: CMSIS-RTOS2 idle hook (calls osThreadFlagsWait with timeout) * \param schedulerId: Target scheduler ID * \param idleUs: Sleep timeout in microseconds */ void CoHook_CMSIS_Idle(uint32_t schedulerId, uint32_t idleUs); /** * \brief: CMSIS-RTOS2 wakeup hook (calls osThreadFlagsSet) * \param schedulerId: Target scheduler ID to wake up */ void CoHook_CMSIS_Wakeup(uint32_t schedulerId); /** * \brief: Deinitialize CMSIS-RTOS2 hooks for a scheduler * \param schedulerId: Target scheduler ID */ void CoHook_CMSIS_Deinit(uint32_t schedulerId); /* ======================================================================================================= * 5. uC/OS-III Hooks (Task Semaphore based) * ======================================================================================================= */ /** * \brief: Initialize uC/OS-III hooks for a scheduler * \param schedulerId: Target scheduler ID * \param pTcb: Target OS_TCB pointer (or NULL to use OSTCBCurPtr) * \return: 0 on success, or negative error code */ int CoHook_UCOS_Init(uint32_t schedulerId, void *pTcb); /** * \brief: uC/OS-III idle hook (calls OSTaskSemPend with timeout) * \param schedulerId: Target scheduler ID * \param idleUs: Sleep timeout in microseconds */ void CoHook_UCOS_Idle(uint32_t schedulerId, uint32_t idleUs); /** * \brief: uC/OS-III wakeup hook (calls OSTaskSemPost) * \param schedulerId: Target scheduler ID to wake up */ void CoHook_UCOS_Wakeup(uint32_t schedulerId); /** * \brief: Deinitialize uC/OS-III hooks for a scheduler * \param schedulerId: Target scheduler ID */ void CoHook_UCOS_Deinit(uint32_t schedulerId); /* ======================================================================================================= * 6. POSIX / Linux / Android / macOS / iOS / QNX / VxWorks / NuttX Multi-Threaded Hooks * ======================================================================================================= */ /** * \brief: Initialize POSIX condition-variable based hooks for a scheduler * \param schedulerId: Target scheduler ID * \return: 0 on success, or negative error code */ int CoHook_Posix_Init(uint32_t schedulerId); /** * \brief: POSIX idle hook with timeout * \param schedulerId: Target scheduler ID * \param idleUs: Sleep timeout in microseconds */ void CoHook_Posix_Idle(uint32_t schedulerId, uint32_t idleUs); /** * \brief: POSIX wakeup hook (signals condition variable to wake up scheduler immediately) * \param schedulerId: Target scheduler ID to wake up */ void CoHook_Posix_Wakeup(uint32_t schedulerId); /** * \brief: Destroy POSIX synchronization primitives for a scheduler * \param schedulerId: Target scheduler ID */ void CoHook_Posix_Deinit(uint32_t schedulerId); /* ======================================================================================================= * 7. Windows Multi-Threaded Hooks (Win32 Event) * ======================================================================================================= */ /** * \brief: Initialize Windows event-based hooks for a scheduler * \param schedulerId: Target scheduler ID * \return: 0 on success, or negative error code */ int CoHook_Win32_Init(uint32_t schedulerId); /** * \brief: Windows idle hook with timeout * \param schedulerId: Target scheduler ID * \param idleUs: Sleep timeout in microseconds */ void CoHook_Win32_Idle(uint32_t schedulerId, uint32_t idleUs); /** * \brief: Windows wakeup hook (SetEvent to unblock scheduler immediately) * \param schedulerId: Target scheduler ID to wake up */ void CoHook_Win32_Wakeup(uint32_t schedulerId); /** * \brief: Destroy Windows synchronization primitives for a scheduler * \param schedulerId: Target scheduler ID */ void CoHook_Win32_Deinit(uint32_t schedulerId); /* ======================================================================================================= * 8. Unified / Auto-Detect Platform Hooks (Ready-to-Use Out-of-the-Box) * ======================================================================================================= */ /** * \brief: Automatically attach platform-appropriate idleHook and wakeupHook to the scheduler * \param schedulerId: Target scheduler ID * \return: 0 on success, or negative error code * \note: Automatically detects FreeRTOS, RT-Thread, CMSIS-RTOS2, uC/OS, Windows, POSIX/Linux, or Bare-metal. * \example: * CoScheduler_Init(0, GetTimerUsec, 1000); * CoScheduler_BindDefaultHooks(0); */ int CoScheduler_BindDefaultHooks(uint32_t schedulerId); /** * \brief: Release default platform hooks attached to the scheduler * \param schedulerId: Target scheduler ID */ int CoScheduler_UnbindDefaultHooks(uint32_t schedulerId); #ifdef __cplusplus } #endif #endif /* !__coroutine_hook_H */