Protocols of the LwIP Stack

• IPv4 and IPv6 (Internet Protocol v4 and v6)
• TCP (Transmission Control Protocol)
• UDP (User Datagram Protocol)
• DNS (Domain Name Server)
• SNMP (Simple Network Management Protocol)
• DHCP (Dynamic Host Configuration Protocol)
• PPP (Point to Point Protocol)
• ARP (Address Resolution Protocol)
• ICMP (Internet Control Message Protocol)
• IGMP (Internet Group Management Protocol)

Protocol Files of LwIP Stack

• Application Layer: dhcp.c, dns.c
• Transport Layer: udp.c, tcp.c
• Internet Layer: ip.c
• Network Interface Layer: netif.c

Ethernet Controller Interface

1. The official LwIP core stack is hardware-independent and does not include MCU-specific Ethernet MAC/PHY drivers. Hardware-specific drivers are normally provided by the MCU vendor, SDK, BSP, or application.
2. For MCU integrations, such as STM32 projects generated by STM32CubeMX, a file named ethernetif.c provides the interface between the LwIP network stack and the underlying Ethernet hardware driver.
3. The ethernetif.c is essentially a hardware-abstraction/adaptation layer. It must be implemented or customized for the target MCU, Ethernet MAC, PHY, DMA configuration, and operating environment.
4. The main responsibility of ethernetif.c is to transfer Ethernet frames between LwIP and the low-level Ethernet driver:
   • Transmit: LwIP pbuf → ethernetif.c → Ethernet MAC/DMA driver → Ethernet hardware
   • Receive: Ethernet hardware → Ethernet MAC/DMA driver → ethernetif.c → LwIP pbuf
5. Typical functions implemented in ethernetif.c include:
   • low_level_init(): initializes the Ethernet interface and related hardware
   • low_level_output(): sends an Ethernet frame
   • low_level_input(): receives an Ethernet frame
   • ethernetif_input(): passes received packets to the LwIP stack
   • ethernetif_init(): initializes and registers the network interface

Buffer Management

1. A pbuf (packet buffer) is a core LwIP data structure used to store and manage network packet data.
2. A pbuf can either contain dynamically allocated packet data or reference packet data stored elsewhere, including RAM or ROM, depending on the pbuf type and allocation method.
3. A single packet may be divided across multiple pbuf structures linked together through the next pointer. This is called a pbuf chain.
4. Multiple packets can also be linked using the same next pointer mechanism, forming a packet queue. LwIP distinguishes packet boundaries using fields such as len and tot_len.
5. Important fields in struct pbuf include:
   • next: pointer to next pbuf in a pbuf chain
   • payload: pointer to packet data
   • len: number of data bytes stored in the current pbuf
   • tot_len: total number of bytes from the current pbuf to the end of the current packet
   • ref (on 4 bits): reference count that indicates the number of pointers that reference the pbuf. A pbuf can be released from memory only when its reference count is zero

Types of pbufs

PBUF_POOL
1. With PBUF_POOL, pbufs are allocated from a statically configured memory pool containing a fixed number of fixed-size buffers.
2. Each allocated pbuf contains both the pbuf structure and a payload buffer.
3. If the packet is larger than the payload capacity of a single pool buffer, LwIP allocates multiple pbufs and links them together to form a pbuf chain.
4. PBUF_POOL is commonly used for receiving Ethernet packets, where fast and predictable allocation is important.

PBUF_RAM
1. With PBUF_RAM, memory is dynamically allocated from LwIP’s heap.
2. The pbuf structure and its payload are normally allocated as one contiguous block of memory.
3. Unlike PBUF_POOL, a PBUF_RAM allocation normally creates a single pbuf large enough to hold the requested packet, rather than chaining multiple fixed-size pool buffers.
4. PBUF_RAM is commonly used when constructing or transmitting packets whose size is known at allocation time.

APIs for Managing pbufs

1. pbuf_alloc(): Allocates a new pbuf of the specified type and size. For PBUF_POOL, the result may be a chain of multiple pbufs.
2. pbuf_realloc(): Shrinks a pbuf or pbuf chain to a specified length. Despite its name, it cannot enlarge a pbuf. Any unused pbufs at the end of the chain are freed.
3. pbuf_ref(): Increments the reference count (ref) of a pbuf, indicating that another reference to the pbuf exists.
4. pbuf_free(): Decrements the reference count of a pbuf. If the reference count reaches 0, the pbuf is deallocated. For a chain, this process continues until a pbuf with a remaining nonzero reference count is encountered.
5. pbuf_clen(): Returns the number of individual pbufs in a pbuf chain.
6. pbuf_cat(): Concatenates two pbufs or pbuf chains. It does not increment the reference count of the tail chain; ownership of the caller’s tail reference is transferred to the resulting chain.
7. pbuf_chain(): Chains two pbufs or pbuf chains together and increments the reference count of the first pbuf in the tail chain, allowing the caller to retain its own reference to the tail.
8. pbuf_dechain(): Detaches the first pbuf from the remainder of a pbuf chain. The first pbuf becomes a standalone pbuf, and the function returns the remaining chain if it is still allocated.
9. pbuf_copy_partial(): Copies a specified number of bytes from a pbuf or pbuf chain, starting at a specified offset, into an application-provided buffer.
10. pbuf_take(): Copies application-provided data into an existing pbuf or pbuf chain. The destination pbuf must have sufficient capacity.
11. pbuf_coalesce(): Converts a chained pbuf into a single contiguous pbuf. If allocation fails, the original pbuf is returned unchanged.

Reference

[1] Light Weight Internet Protocol
[2] Embedded Ethernet Firmware Development Learning Path

Zephyr is an open-source, scalable, and secure real-time operating system (RTOS) designed for modern embedded and connected devices. It supports a wide range of hardware platforms, from small resource-constrained microcontrollers to more capable edge-computing systems.

• Kernel: It manages threads, scheduling, interrupts, synchronization, timing, and other system resources.
• Multithreading: Allows multiple threads to execute concurrently, enabling applications to handle several operations while maintaining responsiveness and real-time behavior.
• Memory Management: Provides mechanisms for efficient and predictable use of limited memory, including dynamic allocation, memory pools, stacks, and memory protection.

Zephyr Workspace

zephyr-sdk-<version>/

zephyr_workspace/
|--.venv/
|--.west/
     |--config
|--bootloader/
|--modules/
     |--hal/
         |--cmsis/ - CMSIS core headers    
         |--stm32/ - STM32 HAL and LL layers               
     |--lib/
         |--cmsis-dsp/
         |--cmsis-nn/
     |--fs/
         |--fatfs/
         |--littlefs/        
|--tools/
|--apps/
|--zephyr/
     |--arch/
     |--boards/
     |--cmake/
     |--drivers/
     |--include/
     |--kernel/
     |--samples/
     |--scripts/
     |--soc/
     |--subsys/
     |--tests/
     |--west.yml

arch/     - CPU architecture support  
boards/   - Board definitions, DeviceTree, Kconfig, and default settings
cmake/    - CMake build-system modules
drivers/  - Hardware drivers: GPIO, I2C, SPI, UART, ADC, sensors, etc
include/  - Public Zephyr API headers   
kernel/   - Kernel: scheduler, threads, synchronization, timers
samples/  - Example and reference applications
scripts/  - Build, configuration, flashing, testing, and helper tools  
soc/      - Vendor- and SoC-specific support
subsys/   - System services: logging, shell, networking, settings, etc
tests/    - Kernel, driver, subsystem, and API tests

zephyr-sdk-<version>/

zephyr_workspace/
|--.venv/
|--.west/
     |--config
|--bootloader/
|--modules/
     |--hal/
         |--cmsis/ - CMSIS core headers    
         |--stm32/ - STM32 HAL and LL layers               
     |--lib/
         |--cmsis-dsp/
         |--cmsis-nn/
     |--fs/
         |--fatfs/
         |--littlefs/        
|--tools/
|--apps/
|--zephyr/
     |--arch/
     |--boards/
     |--cmake/
     |--drivers/
     |--include/
     |--kernel/
     |--samples/
     |--scripts/
     |--soc/
     |--subsys/
     |--tests/
     |--west.yml

arch/     - CPU architecture support  
boards/   - Board definitions, DeviceTree, Kconfig, and default settings
cmake/    - CMake build-system modules
drivers/  - Hardware drivers: GPIO, I2C, SPI, UART, ADC, sensors, etc
include/  - Public Zephyr API headers   
kernel/   - Kernel: scheduler, threads, synchronization, timers
samples/  - Example and reference applications
scripts/  - Build, configuration, flashing, testing, and helper tools  
soc/      - Vendor- and SoC-specific support
subsys/   - System services: logging, shell, networking, settings, etc
tests/    - Kernel, driver, subsystem, and API tests

Reference

[1] Zephyr Project Documentation
[2] Zephyr API Reference
[3] Samples and Demos
[4] Supported Boards and Shields

FreeRTOS Heap Implementation Compared

Memory Fragmentation Process

heap_1.c

heap_1.c is the simplest FreeRTOS heap implementation and provides dynamic memory allocation through pvPortMalloc(). It manages a statically allocated heap defined by configTOTAL_HEAP_SIZE and allocates memory sequentially from the beginning of this heap. Once memory is allocated, it cannot be returned to the heap because heap_1.c does not support vPortFree(). This makes the implementation very small, fast, and deterministic, with no risk of heap fragmentation. It is most suitable for embedded applications in which all dynamic memory is allocated during system initialization and never released, such as systems that create all tasks, queues, semaphores, and other RTOS objects before starting normal operation.

heap_2.c

heap_2.c provides dynamic memory allocation through pvPortMalloc() and supports releasing memory with vPortFree(). It manages a statically allocated heap and reuses previously freed blocks when possible. However, adjacent free blocks are not combined, so repeated allocations and deallocations of different sizes can cause memory fragmentation over time. It is mainly suitable for applications that allocate and free blocks of the same or similar sizes, although heap_4.c is generally preferred for most applications that require memory to be freed.

heap_3.c

heap_3.c implements the FreeRTOS memory allocation interface by wrapping the standard C library functions malloc() and free(). Unlike the other FreeRTOS heap implementations, it does not use the memory region defined by configTOTAL_HEAP_SIZE; instead, memory management is handled by the C runtime library. This implementation is useful when an application already relies on the standard library heap, but its determinism, thread safety, fragmentation behavior, and memory usage depend on the specific C library and system configuration.

heap_4.c

heap_4.c is a commonly used FreeRTOS heap implementation that supports both dynamic allocation with pvPortMalloc() and deallocation with vPortFree(). It manages a statically allocated heap and automatically combines adjacent free memory blocks, which significantly reduces memory fragmentation compared with heap_2.c. It provides a good balance between simplicity, efficiency, and flexibility, making it well suited for applications that dynamically create and delete tasks, queues, semaphores, and other RTOS objects during runtime.

// ---------------------- Example ----------------------

uint8_t *buffer = NULL;
buffer = pvPortMalloc(32);
printf("Allocated memory at address: %p\r\n", (void *)buffer);

printf("Freeing memory at address: %p\r\n", (void *)buffer);
vPortFree(buffer);
buffer = NULL;

size_t freeMem;
freeMem = xPortGetFreeHeapSize();
printf("Free heap memory: %u bytes\r\n", (uint16_t)freeMem);

// ---------------------- Example ----------------------

uint8_t *buffer = NULL;
buffer = pvPortMalloc(32);
printf("Allocated memory at address: %p\r\n", (void *)buffer);

printf("Freeing memory at address: %p\r\n", (void *)buffer);
vPortFree(buffer);
buffer = NULL;

size_t freeMem;
freeMem = xPortGetFreeHeapSize();
printf("Free heap memory: %u bytes\r\n", (uint16_t)freeMem);

heap_5.c

heap_5.c provides the same allocation and deallocation behavior as heap_4.c, including the ability to merge adjacent free blocks, but it can manage multiple separate memory regions instead of a single contiguous heap. The available regions are defined by the application using vPortDefineHeapRegions(), allowing FreeRTOS to use memory located in different RAM banks or address ranges. It is particularly useful on microcontrollers with multiple RAM regions, such as internal SRAM, CCM RAM, or external memory, where the application needs to combine several non-contiguous areas into a single FreeRTOS heap.

typedef struct HeapRegion {
    uint8_t *pucStartAddress;  // Start address of the memory block
    size_t xSizeInBytes;       // Size of the memory region
} HeapRegion_t;

HeapRegion_t xHeapRegions[] = {
    { ( uint8_t * ) 0X10000000UL, 0x10000 },   // CCM memory, start address 0X10000000, size 64 KB
    { ( uint8_t * ) 0X20000000UL, 0x20000 },   // Internal SRAM, start address 0X20000000, size 128 KB
    { ( uint8_t * ) 0X68000000UL, 0x100000 },  // External SRAM, start address 0X68000000, size 1 MB
    { NULL, 0 }                                // End of the array
};

// Initialize the heap memory
vPortDefineHeapRegions((const HeapRegion_t *)xHeapRegions);

typedef struct HeapRegion {
    uint8_t *pucStartAddress;  // Start address of the memory block
    size_t xSizeInBytes;       // Size of the memory region
} HeapRegion_t;

HeapRegion_t xHeapRegions[] = {
    { ( uint8_t * ) 0X10000000UL, 0x10000 },   // CCM memory, start address 0X10000000, size 64 KB
    { ( uint8_t * ) 0X20000000UL, 0x20000 },   // Internal SRAM, start address 0X20000000, size 128 KB
    { ( uint8_t * ) 0X68000000UL, 0x100000 },  // External SRAM, start address 0X68000000, size 1 MB
    { NULL, 0 }                                // End of the array
};

// Initialize the heap memory
vPortDefineHeapRegions((const HeapRegion_t *)xHeapRegions);

vApplicationIdleHook()

The idle task hook is a user-defined callback function that FreeRTOS executes repeatedly whenever no other task is ready to run. It is implemented as vApplicationIdleHook() and enabled by setting configUSE_IDLE_HOOK to 1 in FreeRTOSConfig.h. The hook can be used for low-priority background operations, such as entering a low-power mode, collecting system statistics, or performing simple maintenance tasks. It must never block, call functions that may block, or perform lengthy processing, because doing so prevents the idle task from running normally and may delay the cleanup of deleted tasks.

void vApplicationIdleHook(void)

// ---------------------- Example ----------------------

#define configUSE_TICKLESS_IDLE    0  
#define configUSE_IDLE_HOOK        1
#define configIDLE_SHOULD_YIELD    1 

void BeforeEnterSleep(void)
{
    __HAL_RCC_GPIOB_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOC_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOD_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOE_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOF_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOG_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOH_CLK_SLEEP_DISABLE();
}

void AfterExitSleep(void)
{
    __HAL_RCC_GPIOB_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOC_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOD_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOE_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOF_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOG_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOH_CLK_SLEEP_ENABLE();
}

void vApplicationIdleHook(void)
{
    BeforeEnterSleep();
    __DSB();  
    __WFI();  
    __ISB();  
    AfterExitSleep();
}

void vApplicationIdleHook(void)

// ---------------------- Example ----------------------

#define configUSE_TICKLESS_IDLE    0  
#define configUSE_IDLE_HOOK        1
#define configIDLE_SHOULD_YIELD    1 

void BeforeEnterSleep(void)
{
    __HAL_RCC_GPIOB_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOC_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOD_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOE_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOF_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOG_CLK_SLEEP_DISABLE();
    __HAL_RCC_GPIOH_CLK_SLEEP_DISABLE();
}

void AfterExitSleep(void)
{
    __HAL_RCC_GPIOB_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOC_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOD_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOE_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOF_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOG_CLK_SLEEP_ENABLE();
    __HAL_RCC_GPIOH_CLK_SLEEP_ENABLE();
}

void vApplicationIdleHook(void)
{
    BeforeEnterSleep();
    __DSB();  
    __WFI();  
    __ISB();  
    AfterExitSleep();
}

vApplicationTickHook()

vApplicationTickHook() is a user-defined FreeRTOS hook function that is called from the RTOS tick interrupt each time the system tick occurs. To enable it, set configUSE_TICK_HOOK to 1 in FreeRTOSConfig.h. It is typically used for short, periodic operations such as incrementing counters, updating software timing variables, or triggering lightweight monitoring functions. Because it executes in interrupt context, the hook must run quickly, must not block, and may only call FreeRTOS API functions that are safe to use from an ISR.

void vApplicationTickHook(void)

// ---------------------- Example ----------------------

#define configUSE_TICK_HOOK    1

volatile uint32_t ulTickHookCounter = 0;
volatile BaseType_t xOneSecondElapsed = pdFALSE;

void vApplicationTickHook(void) {
    ulTickHookCounter++;

    // Set a flag approximately once every second
    if (ulTickHookCounter >= configTICK_RATE_HZ)
    {
        ulTickHookCounter = 0;
        xOneSecondElapsed = pdTRUE;
    }
}

void vApplicationTickHook(void)

// ---------------------- Example ----------------------

#define configUSE_TICK_HOOK    1

volatile uint32_t ulTickHookCounter = 0;
volatile BaseType_t xOneSecondElapsed = pdFALSE;

void vApplicationTickHook(void) {
    ulTickHookCounter++;

    // Set a flag approximately once every second
    if (ulTickHookCounter >= configTICK_RATE_HZ)
    {
        ulTickHookCounter = 0;
        xOneSecondElapsed = pdTRUE;
    }
}

vApplicationMallocFailedHook()

vApplicationMallocFailedHook() is a user-defined FreeRTOS hook function that is called whenever a dynamic memory allocation request fails, such as when pvPortMalloc(), xTaskCreate(), or another kernel object creation function cannot obtain enough heap memory. To enable it, set configUSE_MALLOC_FAILED_HOOK to 1 in FreeRTOSConfig.h. The hook is commonly used to record diagnostic information, trigger an assertion, illuminate an error indicator, or halt execution for debugging. Because the system may have very little memory remaining, the hook should avoid performing additional dynamic memory allocations.

void vApplicationMallocFailedHook(void)

// ---------------------- Example ----------------------

#define configUSE_MALLOC_FAILED_HOOK    1

void vApplicationMallocFailedHook(void) 
{
    taskDISABLE_INTERRUPTS();
    for (;;) {}
}

void vApplicationMallocFailedHook(void)

// ---------------------- Example ----------------------

#define configUSE_MALLOC_FAILED_HOOK    1

void vApplicationMallocFailedHook(void) 
{
    taskDISABLE_INTERRUPTS();
    for (;;) {}
}

vApplicationStackOverflowHook()

vApplicationStackOverflowHook() is a user-defined FreeRTOS hook function that is called when the kernel detects that a task has exceeded its allocated stack space. To enable stack-overflow checking, set configCHECK_FOR_STACK_OVERFLOW to 1 or 2 in FreeRTOSConfig.h, with 2 providing more thorough checking. The hook receives the handle and name of the affected task, allowing the application to record diagnostic information, trigger an assertion, illuminate an error LED, or halt execution for debugging. Because stack corruption may already have occurred, the hook should avoid complex operations and should normally stop the system so the cause can be investigated.

void vApplicationStackOverflowHook(TaskHandle_t xTask, 
                                   char *pcTaskName)

// ---------------------- Example ----------------------

#define INCLUDE_uxTaskGetStackHighWaterMark    1
#define configCHECK_FOR_STACK_OVERFLOW			   2    

volatile const char *g_overflow_task_name = NULL;
volatile TaskHandle_t g_overflow_task_handle = NULL;

void vApplicationStackOverflowHook(TaskHandle_t xTask, 
                                   char *pcTaskName) 
{
    g_overflow_task_handle = xTask;
    g_overflow_task_name = pcTaskName; // points to the task name string

    taskDISABLE_INTERRUPTS();
    for (;;) {
        __NOP(); // set breakpoint here and inspect g_overflow_task_name
                 // LED may also be turned on or toggled here
    }
}

TaskHandle_t taskHandler;
UBaseType_t uxRemainingWords;
uxRemainingWords = uxTaskGetStackHighWaterMark(taskHandler);
printf("Unused stack: %lu words (%lu bytes)\r\n",
       (unsigned long)uxRemainingWords,
       (unsigned long)uxRemainingWords * sizeof(StackType_t));

void vApplicationStackOverflowHook(TaskHandle_t xTask, 
                                   char *pcTaskName)

// ---------------------- Example ----------------------

#define INCLUDE_uxTaskGetStackHighWaterMark    1
#define configCHECK_FOR_STACK_OVERFLOW			   2    

volatile const char *g_overflow_task_name = NULL;
volatile TaskHandle_t g_overflow_task_handle = NULL;

void vApplicationStackOverflowHook(TaskHandle_t xTask, 
                                   char *pcTaskName) 
{
    g_overflow_task_handle = xTask;
    g_overflow_task_name = pcTaskName; // points to the task name string

    taskDISABLE_INTERRUPTS();
    for (;;) {
        __NOP(); // set breakpoint here and inspect g_overflow_task_name
                 // LED may also be turned on or toggled here
    }
}

TaskHandle_t taskHandler;
UBaseType_t uxRemainingWords;
uxRemainingWords = uxTaskGetStackHighWaterMark(taskHandler);
printf("Unused stack: %lu words (%lu bytes)\r\n",
       (unsigned long)uxRemainingWords,
       (unsigned long)uxRemainingWords * sizeof(StackType_t));

vApplicationDaemonTaskStartupHook()

vApplicationDaemonTaskStartupHook() is a user-defined FreeRTOS hook function that is called once when the daemon task, also known as the timer service task, begins running after the scheduler starts. To enable it, set configUSE_DAEMON_TASK_STARTUP_HOOK to 1 in FreeRTOSConfig.h. It is typically used to perform application initialization that must occur after the scheduler is active, such as creating synchronization objects, starting software timers, or initializing components that depend on FreeRTOS services. Because the hook executes in the context of the daemon task, lengthy or blocking operations should be avoided so that software timers and deferred callback processing are not delayed.

void vApplicationDaemonTaskStartupHook(void)

// ---------------------- Example ----------------------

#define configUSE_DAEMON_TASK_STARTUP_HOOK    1
#define configUSE_TIMERS				              1

TimerHandle_t OneShotTimer_Handle;

OneShotTimer_Handle = 
  xTimerCreate((const char*			       ) "OneShotTimer",
			         (TickType_t			       ) 3000,
							 (UBaseType_t			       ) pdFALSE,
							 (void*				           ) 1,
							 (TimerCallbackFunction_t) OneShotTimerCallback);

void vApplicationDaemonTaskStartupHook(void) {
    BaseType_t xResult;
    xResult = xTimerStart(OneShotTimer_Handle, 0);
    configASSERT(xResult == pdPASS);
}

void OneShotTimerCallback(TimerHandle_t xTimer) {
	static TickType_t xTimeNow;
	xTimeNow = xTaskGetTickCount();
	printf("One-shot timer callback executing: %d\r\n", (int)xTimeNow);
}

void vApplicationDaemonTaskStartupHook(void)

// ---------------------- Example ----------------------

#define configUSE_DAEMON_TASK_STARTUP_HOOK    1
#define configUSE_TIMERS				              1

TimerHandle_t OneShotTimer_Handle;

OneShotTimer_Handle = 
  xTimerCreate((const char*			       ) "OneShotTimer",
			         (TickType_t			       ) 3000,
							 (UBaseType_t			       ) pdFALSE,
							 (void*				           ) 1,
							 (TimerCallbackFunction_t) OneShotTimerCallback);

void vApplicationDaemonTaskStartupHook(void) {
    BaseType_t xResult;
    xResult = xTimerStart(OneShotTimer_Handle, 0);
    configASSERT(xResult == pdPASS);
}

void OneShotTimerCallback(TimerHandle_t xTimer) {
	static TickType_t xTimeNow;
	xTimeNow = xTaskGetTickCount();
	printf("One-shot timer callback executing: %d\r\n", (int)xTimeNow);
}

configUSE_TICKLESS_IDLE

configUSE_TICKLESS_IDLE enables FreeRTOS tickless idle mode, which reduces power consumption when no application task is ready to run. Normally, the periodic RTOS tick interrupt continues waking the processor even while the Idle task is running. When tickless idle is enabled, FreeRTOS temporarily stops the tick interrupt, places the processor into a low-power state, and sleeps until an interrupt occurs or a blocked task is due to wake. After waking, the kernel adjusts its tick count to account for the elapsed time. Set it to 0 to disable tickless idle, 1 to use the port’s built-in implementation when supported, or 2 to provide a custom portSUPPRESS_TICKS_AND_SLEEP() implementation.

#define configUSE_TICKLESS_IDLE    1                       

// FreeRTOSConfig.h
extern void PreSleepProcessing(uint32_t ulExpectedIdleTime);
extern void PostSleepProcessing(uint32_t ulExpectedIdleTime);
#define configPRE_SLEEP_PROCESSING  PreSleepProcessing	 
#define configPOST_SLEEP_PROCESSING  PostSleepProcessing	 

// main.c
void PreSleepProcessing(uint32_t ulExpectedIdleTime)
{
    (void)ulExpectedIdleTime;

    // Disable GPIO clocks that are not needed during sleep
    __HAL_RCC_GPIOB_CLK_DISABLE();
    __HAL_RCC_GPIOC_CLK_DISABLE();
    __HAL_RCC_GPIOD_CLK_DISABLE();
    __HAL_RCC_GPIOE_CLK_DISABLE();
    __HAL_RCC_GPIOF_CLK_DISABLE();
    __HAL_RCC_GPIOG_CLK_DISABLE();
    __HAL_RCC_GPIOH_CLK_DISABLE();
}

void PostSleepProcessing(uint32_t ulExpectedIdleTime)
{
    (void)ulExpectedIdleTime;

    // Re-enable GPIO clocks after waking up
    __HAL_RCC_GPIOB_CLK_ENABLE();
    __HAL_RCC_GPIOC_CLK_ENABLE();
    __HAL_RCC_GPIOD_CLK_ENABLE();
    __HAL_RCC_GPIOE_CLK_ENABLE();
    __HAL_RCC_GPIOF_CLK_ENABLE();
    __HAL_RCC_GPIOG_CLK_ENABLE();
    __HAL_RCC_GPIOH_CLK_ENABLE();
}

#define configUSE_TICKLESS_IDLE    1                       

// FreeRTOSConfig.h
extern void PreSleepProcessing(uint32_t ulExpectedIdleTime);
extern void PostSleepProcessing(uint32_t ulExpectedIdleTime);
#define configPRE_SLEEP_PROCESSING  PreSleepProcessing	 
#define configPOST_SLEEP_PROCESSING  PostSleepProcessing	 

// main.c
void PreSleepProcessing(uint32_t ulExpectedIdleTime)
{
    (void)ulExpectedIdleTime;

    // Disable GPIO clocks that are not needed during sleep
    __HAL_RCC_GPIOB_CLK_DISABLE();
    __HAL_RCC_GPIOC_CLK_DISABLE();
    __HAL_RCC_GPIOD_CLK_DISABLE();
    __HAL_RCC_GPIOE_CLK_DISABLE();
    __HAL_RCC_GPIOF_CLK_DISABLE();
    __HAL_RCC_GPIOG_CLK_DISABLE();
    __HAL_RCC_GPIOH_CLK_DISABLE();
}

void PostSleepProcessing(uint32_t ulExpectedIdleTime)
{
    (void)ulExpectedIdleTime;

    // Re-enable GPIO clocks after waking up
    __HAL_RCC_GPIOB_CLK_ENABLE();
    __HAL_RCC_GPIOC_CLK_ENABLE();
    __HAL_RCC_GPIOD_CLK_ENABLE();
    __HAL_RCC_GPIOE_CLK_ENABLE();
    __HAL_RCC_GPIOF_CLK_ENABLE();
    __HAL_RCC_GPIOG_CLK_ENABLE();
    __HAL_RCC_GPIOH_CLK_ENABLE();
}

Task notifications enable direct communication between tasks without requiring separate kernel objects such as queues, semaphores, or event groups.

• Pending: When a task receives a notification, its notification state is set to pending.
• Not pending: When the task processes the notification, its notification state is cleared to not pending.

Advantages: Faster than using queues, semaphore and event groups to perform an equivalent operation. Requires significantly less RAM than using a queue, semaphore or an event group.

Limitations: Unlike queues, semaphores and event groups, task notifications cannot be used to send events or data from a task to an ISR, although they can be used to send events or data from an ISR to a task. Unlike queues, semaphores and event groups, task notifications cannot be sent to multiple tasks.

// FreeRTOSConfig.h
#define configUSE_TASK_NOTIFICATIONS   1 

// FreeRTOSConfig.h
#define configUSE_TASK_NOTIFICATIONS   1 

xTaskNotify()

xTaskNotify() sends a task notification to another task and updates the receiving task’s notification value according to the selected eNotifyAction. It can set specific bits, increment the value, overwrite the existing value, update it only when no unread notification is pending, or generate a notification event without modifying the value. If the receiving task is blocked waiting for the notification, it is moved to the Ready state. The function normally returns pdPASS; however, when eSetValueWithoutOverwrite is used, it returns pdFAIL if a previous notification is still pending.

BaseType_t xTaskNotify(TaskHandle_t xTaskToNotify,
                       uint32_t ulValue,
                       eNotifyAction eAction)
                       
// ---------------------- Example ---------------------- 

TaskHandle_t ReceiverTask_Handler;
uint8_t keyState;
BaseType_t err;
err = xTaskNotify((TaskHandle_t	) ReceiverTask_Handler,
							    (uint32_t		  ) keyState,
							    (eNotifyAction) eSetValueWithOverwrite);

BaseType_t xTaskNotify(TaskHandle_t xTaskToNotify,
                       uint32_t ulValue,
                       eNotifyAction eAction)
                       
// ---------------------- Example ---------------------- 

TaskHandle_t ReceiverTask_Handler;
uint8_t keyState;
BaseType_t err;
err = xTaskNotify((TaskHandle_t	) ReceiverTask_Handler,
							    (uint32_t		  ) keyState,
							    (eNotifyAction) eSetValueWithOverwrite);

xTaskNotifyFromISR()

xTaskNotifyFromISR() is the interrupt-safe version of xTaskNotify(). It supports the same notification actions and includes the pxHigherPriorityTaskWoken parameter, which is set to pdTRUE if the notification unblocks a task with a higher priority than the currently running task. This variable must be initialized to pdFALSE before the function is called. If it is set to pdTRUE, portYIELD_FROM_ISR() should be called before exiting the ISR to request an immediate context switch.

BaseType_t xTaskNotifyFromISR(TaskHandle_t xTaskToNotify, 
                              uint32_t ulValue, 
                              eNotifyAction eAction, 
                              BaseType_t * pxHigherPriorityTaskWoken)

TaskHandle_t EventGroupTask_Handler;
#define EVENTBIT_0	 (1 << 0)

BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xTaskNotifyFromISR((TaskHandle_t ) EventGroupTask_Handler,
						       (uint32_t	   ) EVENTBIT_0,
						       (eNotifyAction) eSetBits,
						       (BaseType_t*	 ) &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

BaseType_t xTaskNotifyFromISR(TaskHandle_t xTaskToNotify, 
                              uint32_t ulValue, 
                              eNotifyAction eAction, 
                              BaseType_t * pxHigherPriorityTaskWoken)

TaskHandle_t EventGroupTask_Handler;
#define EVENTBIT_0	 (1 << 0)

BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xTaskNotifyFromISR((TaskHandle_t ) EventGroupTask_Handler,
						       (uint32_t	   ) EVENTBIT_0,
						       (eNotifyAction) eSetBits,
						       (BaseType_t*	 ) &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

xTaskNotifyGive()

xTaskNotifyGive() increments the target task’s notification value by one and marks the notification as pending. It is equivalent to calling xTaskNotify() with the eIncrement action and is typically paired with ulTaskNotifyTake(). Together, these functions provide a lightweight alternative to a binary or counting semaphore when an event needs to be delivered to a single specific task. xTaskNotifyGive() must be called from task context; use vTaskNotifyGiveFromISR() when sending the notification from an ISR.

BaseType_t xTaskNotifyGive(TaskHandle_t xTaskToNotify)

// ---------------------- Example ---------------------- 

TaskHandle_t SemapGiveTask_Handler;
xTaskNotifyGive(SemapTakeTask_Handler);
printf("TaskNotifyGive!\r\n");

BaseType_t xTaskNotifyGive(TaskHandle_t xTaskToNotify)

// ---------------------- Example ---------------------- 

TaskHandle_t SemapGiveTask_Handler;
xTaskNotifyGive(SemapTakeTask_Handler);
printf("TaskNotifyGive!\r\n");

vTaskNotifyGiveFromISR()

vTaskNotifyGiveFromISR() safely increments a task’s notification value from an interrupt service routine and marks the notification as pending. It is commonly used to unblock a task responsible for deferred interrupt processing, such as handling received data or processing a completed DMA transfer. The pxHigherPriorityTaskWoken parameter indicates whether the notification unblocked a task with a higher priority than the interrupted task. If it is set to pdTRUE, portYIELD_FROM_ISR() should be called before exiting the ISR to request an immediate context switch.

void vTaskNotifyGiveFromISR(TaskHandle_t xTaskHandle, 
                            BaseType_t * pxHigherPriorityTaskWoken)
                            
// ---------------------- Example ----------------------

TaskHandle_t DataProcess_Handler;
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
vTaskNotifyGiveFromISR(DataProcess_Handler, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

void vTaskNotifyGiveFromISR(TaskHandle_t xTaskHandle, 
                            BaseType_t * pxHigherPriorityTaskWoken)
                            
// ---------------------- Example ----------------------

TaskHandle_t DataProcess_Handler;
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
vTaskNotifyGiveFromISR(DataProcess_Handler, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

xTaskNotifyAndQuery()

xTaskNotifyAndQuery() performs the same notification and value-update operation as xTaskNotify(), while also returning the target task’s previous notification value through pulPreviousNotifyValue. The previous value is captured atomically before the selected eNotifyAction modifies it. This is useful when the sending task needs to inspect and update the notification value in a single operation, such as checking previously set event bits or reading a counter before incrementing or overwriting it. The function must be called from task context.

BaseType_t xTaskNotifyAndQuery(TaskHandle_t xTaskToNotify,
                               uint32_t ulValue,
                               eNotifyAction eAction,
                               uint32_t * pulPreviousNotificationValue)

BaseType_t xTaskNotifyAndQuery(TaskHandle_t xTaskToNotify,
                               uint32_t ulValue,
                               eNotifyAction eAction,
                               uint32_t * pulPreviousNotificationValue)

xTaskNotifyAndQueryFromISR()

xTaskNotifyAndQueryFromISR() is the interrupt-safe version of xTaskNotifyAndQuery(). It sends a notification to the target task, updates its notification value according to the selected eNotifyAction, and returns the value that existed before the update through pulPreviousNotifyValue. The pxHigherPriorityTaskWoken parameter indicates whether the notification unblocked a higher-priority task, allowing the ISR to request an immediate context switch with portYIELD_FROM_ISR(). The function normally returns pdPASS; however, when eSetValueWithoutOverwrite is used, it returns pdFAIL if an unread notification is already pending.

BaseType_t xTaskNotifyAndQueryFromISR(
    TaskHandle_t xTaskToNotify, 
    uint32_t ulValue, 
    eNotifyAction eAction, 
    uint32_t * pulPreviousNotificationValue
    BaseType_t * pxHigherPriorityTaskWoken)

BaseType_t xTaskNotifyAndQueryFromISR(
    TaskHandle_t xTaskToNotify, 
    uint32_t ulValue, 
    eNotifyAction eAction, 
    uint32_t * pulPreviousNotificationValue
    BaseType_t * pxHigherPriorityTaskWoken)

ulTaskNotifyTake()

ulTaskNotifyTake() allows the calling task to block until its notification value becomes nonzero or the specified timeout expires. When a notification is received, setting xClearCountOnExit to pdTRUE clears the notification value to zero, providing binary-semaphore behavior. Setting it to pdFALSE decrements the value by one, providing counting-semaphore behavior. The function returns the notification value before it is cleared or decremented, or 0 if the wait period expires without a notification.

uint32_t ulTaskNotifyTake(BaseType_t xClearCountOnExit, 
                          TickType_t xTicksToWait)
                          
// ---------------------- Example ----------------------

uint32_t NotifyValue;
NotifyValue = ulTaskNotifyTake(pdTRUE, portMAX_DELAY);

uint32_t ulTaskNotifyTake(BaseType_t xClearCountOnExit, 
                          TickType_t xTicksToWait)
                          
// ---------------------- Example ----------------------

uint32_t NotifyValue;
NotifyValue = ulTaskNotifyTake(pdTRUE, portMAX_DELAY);

xTaskNotifyWait()

xTaskNotifyWait() blocks the calling task until a notification becomes pending or the specified timeout expires. It can clear selected bits in the task’s notification value before waiting and clear additional bits after the received value has been copied to pulNotificationValue. This makes it well suited for receiving event flags or a 32-bit mailbox value sent through xTaskNotify(). The function returns pdTRUE when a notification is received and pdFALSE if the wait period expires without one.

BaseType_t xTaskNotifyWait(uint32_t ulBitsToClearOnEntry,
                           uint32_t ulBitsToClearOnExit, 
                           uint32_t * pulNotificationValue, 
                           TickType_t xTicksToWait)
                           
// ---------------------- Example ----------------------

uint32_t NotifyValue;
BaseType_t err;
err = xTaskNotifyWait((uint32_t	 ) 0x00,		       // Clear no bits before waiting
							        (uint32_t	 ) ULONG_MAX,	     // Clear all bits after receiving
							        (uint32_t* ) &NotifyValue,   // Store the received notification value  
							        (TickType_t) portMAX_DELAY); // Wait indefinitely                           

BaseType_t xTaskNotifyWait(uint32_t ulBitsToClearOnEntry,
                           uint32_t ulBitsToClearOnExit, 
                           uint32_t * pulNotificationValue, 
                           TickType_t xTicksToWait)
                           
// ---------------------- Example ----------------------

uint32_t NotifyValue;
BaseType_t err;
err = xTaskNotifyWait((uint32_t	 ) 0x00,		       // Clear no bits before waiting
							        (uint32_t	 ) ULONG_MAX,	     // Clear all bits after receiving
							        (uint32_t* ) &NotifyValue,   // Store the received notification value  
							        (TickType_t) portMAX_DELAY); // Wait indefinitely                           

FreeRTOS (Scheduler): FreeRTOS provides core RTOS primitives, tasks, semaphores, queues, and software timers. It leaves driver implementation, networking, and hardware configuration up to you or your target MCU’s vendor HAL.

Zephyr (Platform): Zephyr takes a batteries-included approach. It includes unified driver models, a shell interface, power management, filesystems, and security modules built directly into the tree.

Configuration & Developer Workflow

FreeRTOS: Configuration is managed through a single FreeRTOSConfig.h file. You can easily integrate it into almost any vendor IDE (Keil, IAR, STM32CubeIDE) or custom Makefile/CMake environment.

Zephyr: Mimics the Linux kernel build process. Hardware is described using Devicetree (.dts), while software components are toggled using Kconfig (prj.conf). The meta-tool west manages repositories and builds, offering high cross-platform portability at the cost of a steeper initial learning curve.

Memory Protection & Performance

FreeRTOS: Has lower context-switching and interrupt overhead because of its lean execution model. Tasks generally execute in a single shared memory space.

Zephyr: Emphasizes safety and isolation. On supported hardware, it separates kernel mode from user mode and enforces hardware stack protection and memory partitions using the Memory Protection Unit (MPU).

FreeRTOS API vs. Zephyr API

Event Groups

Event groups allow a task to wait in the blocked state for a combination of one of more events to occur. Event groups unblock all the tasks that were waiting for the same event, or combination of events, when the event occurs. Event groups reduce RAM usage by allowing us to replace multiple binary semaphores with a single event group.

• Synchronizing tasks
• Broadcasting events to multiple tasks

Event Bits

When configUSE_16_BIT_TICKS is set to 0, TickType_t is a 32-bit data type, so EventBits_t is also a 32-bit data type. A variable of type EventBits_t can store 24 event bits, while the upper 8 bits are reserved for internal use. Event bit 0 is stored in bit 0 of the variable, event bit 1 is stored in bit 1, and so on. For STM32 devices, an event group can therefore contain up to 24 usable event bits.

• An event group is a set of event flags
• An event flag is a boolean value (1 or 0) used to indicate whether an event has occurred or not
• An event flag is stored in a single bit and the state of all event flags can be stored in a single variable

xEventGroupCreate()

xEventGroupCreate() dynamically allocates the required memory and creates a new event group. It returns an EventGroupHandle_t for use with other event-group functions, or NULL if memory allocation fails. This function is available only when configSUPPORT_DYNAMIC_ALLOCATION is enabled. When the event group is no longer needed, call vEventGroupDelete() to free the allocated memory.

EventGroupHandle_t xEventGroupCreate(void)

// ---------------------- Example ----------------------

EventGroupHandle_t xEventGroupHandler;
xEventGroupHandler = xEventGroupCreate();

EventGroupHandle_t xEventGroupCreate(void)

// ---------------------- Example ----------------------

EventGroupHandle_t xEventGroupHandler;
xEventGroupHandler = xEventGroupCreate();

xEventGroupCreateStatic()

xEventGroupCreateStatic() creates an event group using memory supplied by the application rather than allocating memory from the FreeRTOS heap. The application must provide a StaticEventGroup_t variable that remains valid for the entire lifetime of the event group. This function is useful in systems that require deterministic memory usage or do not permit dynamic allocation, and it is available only when configSUPPORT_STATIC_ALLOCATION is enabled.

EventGroupHandle_t xEventGroupCreateStatic(StaticEventGroup_t *pxEventGroupBuffer)

EventGroupHandle_t xEventGroupCreateStatic(StaticEventGroup_t *pxEventGroupBuffer)

xEventGroupClearBits()

xEventGroupClearBits() clears one or more specified bits in an event group from task context. The bits are selected using a bit mask: each bit set to 1 in the mask is cleared, while all other bits remain unchanged. The function returns the event-group value before the bits were cleared, allowing the task to inspect the previous event state. It must not be called from an interrupt service routine.

EventBits_t xEventGroupClearBits(EventGroupHandle_t xEventGroup, 
                                 const EventBits_t uxBitsToClear)

EventBits_t xEventGroupClearBits(EventGroupHandle_t xEventGroup, 
                                 const EventBits_t uxBitsToClear)

xEventGroupClearBitsFromISR()

xEventGroupClearBitsFromISR() requests that one or more specified event bits be cleared from interrupt context. Because clearing event bits may unblock multiple waiting tasks, the operation is deferred to the FreeRTOS timer daemon task rather than performed directly within the ISR. The function returns pdPASS if the request is successfully posted to the timer command queue, or pdFAIL if the queue is full.

BaseType_t xEventGroupClearBitsFromISR(EventGroupHandle_t xEventGroup, 
                                       const EventBits_t uxBitsToSet)

BaseType_t xEventGroupClearBitsFromISR(EventGroupHandle_t xEventGroup, 
                                       const EventBits_t uxBitsToSet)

xEventGroupSetBits()

xEventGroupSetBits() sets one or more specified bits in an event group from task context. Tasks waiting for those bits are then evaluated and may be moved from the Blocked state to the Ready state. Multiple bits can be set simultaneously by combining them with the bitwise OR operator. The function returns the event-group value after the bits have been set and any automatically cleared bits have been processed.

EventBits_t xEventGroupSetBits(EventGroupHandle_t xEventGroup, 
                               const EventBits_t uxBitsToSet)

// ---------------------- Example ---------------------- 

#define EVENTBIT_0	 (1 << 0)
#define EVENTBIT_1	 (1 << 1)
#define EVENTBIT_2	 (1 << 2)
#define EVENTBIT_ALL (EVENTBIT_0 | EVENTBIT_1 | EVENTBIT_2)
                              
xEventGroupSetBits(xEventGroupHandler, EVENTBIT_1);
xEventGroupSetBits(xEventGroupHandler, EVENTBIT_2);                               

EventBits_t xEventGroupSetBits(EventGroupHandle_t xEventGroup, 
                               const EventBits_t uxBitsToSet)

// ---------------------- Example ---------------------- 

#define EVENTBIT_0	 (1 << 0)
#define EVENTBIT_1	 (1 << 1)
#define EVENTBIT_2	 (1 << 2)
#define EVENTBIT_ALL (EVENTBIT_0 | EVENTBIT_1 | EVENTBIT_2)
                              
xEventGroupSetBits(xEventGroupHandler, EVENTBIT_1);
xEventGroupSetBits(xEventGroupHandler, EVENTBIT_2);                               

xEventGroupSetBitsFromISR()

xEventGroupSetBitsFromISR() requests that one or more event bits be set from an interrupt service routine. Because setting event bits may unblock multiple tasks and is not a constant-time operation, the request is deferred to the FreeRTOS timer daemon task. The xHigherPriorityTaskWoken parameter indicates whether processing the request may make a higher-priority task ready to run. The function returns pdPASS if the request is successfully posted to the timer command queue, or pdFAIL if the queue is full.

BaseType_t xEventGroupSetBitsFromISR(EventGroupHandle_t xEventGroup, 
                                     const EventBits_t uxBitsToSet, 
                                     BaseType_t * pxHigherPriorityTaskWoken)
                                     
// ---------------------- Example ----------------------

BaseType_t YieldRequired = pdFALSE;
BaseType_t xHigherPriorityTaskWoken;

YieldRequired = xEventGroupSetBitsFromISR(xEventGroupHandler,
    											                EVENTBIT_0,
												                  &xHigherPriorityTaskWoken);	
												                  
if(YieldRequired != pdFAIL) {
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}                                      

BaseType_t xEventGroupSetBitsFromISR(EventGroupHandle_t xEventGroup, 
                                     const EventBits_t uxBitsToSet, 
                                     BaseType_t * pxHigherPriorityTaskWoken)
                                     
// ---------------------- Example ----------------------

BaseType_t YieldRequired = pdFALSE;
BaseType_t xHigherPriorityTaskWoken;

YieldRequired = xEventGroupSetBitsFromISR(xEventGroupHandler,
    											                EVENTBIT_0,
												                  &xHigherPriorityTaskWoken);	
												                  
if(YieldRequired != pdFAIL) {
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}                                      

xEventGroupGetBits()

xEventGroupGetBits() reads and returns the current value of an event group from task context without modifying any bits. The returned EventBits_t value can be tested with bit masks to determine which events are currently set. Because another task or interrupt may change the event group immediately afterward, the returned value should be treated as a snapshot of its state at the time of the call.

EventBits_t xEventGroupGetBits(EventGroupHandle_t xEventGroup)

// ---------------------- Example ----------------------

EventBits_t newValue;
newValue = xEventGroupGetBits(xEventGroupHandler);

EventBits_t xEventGroupGetBits(EventGroupHandle_t xEventGroup)

// ---------------------- Example ----------------------

EventBits_t newValue;
newValue = xEventGroupGetBits(xEventGroupHandler);

xEventGroupGetBitsFromISR()

xEventGroupGetBitsFromISR() reads and returns the current value of an event group from interrupt context without modifying any bits. It provides an ISR-safe way to check which event conditions are currently set. Like xEventGroupGetBits(), the returned value is only a snapshot of the event group at the time of the call and may change immediately afterward.

EventBits_t xEventGroupGetBitsFromISR(EventGroupHandle_t xEventGroup)

EventBits_t xEventGroupGetBitsFromISR(EventGroupHandle_t xEventGroup)

xEventGroupWaitBits()

xEventGroupWaitBits() allows a task to wait for one or more specified event bits. The task can be configured to unblock when either any requested bit is set or all requested bits are set. It can also automatically clear the matched bits before returning and wait indefinitely or for a specified timeout. The function returns the event-group value that caused the task to unblock, or the value present when the timeout expired.

EventBits_t xEventGroupWaitBits(EventGroupHandle_t xEventGroup,
                                const EventBits_t uxBitsToWaitFor,
                                const BaseType_t xClearOnExit,
                                const BaseType_t xWaitForAllBits,
                                const TickType_t xTicksToWait)
                                
// ---------------------- Example ----------------------

EventBits_t EventValue;

// This code blocks the current FreeRTOS task until all event bits
// specified by EVENTBIT_ALL are set
EventValue = xEventGroupWaitBits((EventGroupHandle_t) xEventGroupHandler,
						     				         (EventBits_t		    ) EVENTBIT_ALL,
										             (BaseType_t		    ) pdTRUE,
										             (BaseType_t		    ) pdTRUE,
								                 (TickType_t		    ) portMAX_DELAY);   

// This call blocks the current task until any bit defined in EVENTBIT_ALL becomes set, 
// then clears the matched event bits and stores the previous event-group value in EventValue
EventValue = xEventGroupWaitBits((EventGroupHandle_t) xEventGroupHandler, // Event group to monitor
						     				         (EventBits_t		    ) EVENTBIT_ALL,       // Bit mask to wait for
										             (BaseType_t		    ) pdTRUE,             // Clear matched bits before returning
										             (BaseType_t		    ) pdFALSE,            // Wait for ANY bit, not all bits
								                 (TickType_t		    ) portMAX_DELAY);     // Wait indefinitely     								                                              

EventBits_t xEventGroupWaitBits(EventGroupHandle_t xEventGroup,
                                const EventBits_t uxBitsToWaitFor,
                                const BaseType_t xClearOnExit,
                                const BaseType_t xWaitForAllBits,
                                const TickType_t xTicksToWait)
                                
// ---------------------- Example ----------------------

EventBits_t EventValue;

// This code blocks the current FreeRTOS task until all event bits
// specified by EVENTBIT_ALL are set
EventValue = xEventGroupWaitBits((EventGroupHandle_t) xEventGroupHandler,
						     				         (EventBits_t		    ) EVENTBIT_ALL,
										             (BaseType_t		    ) pdTRUE,
										             (BaseType_t		    ) pdTRUE,
								                 (TickType_t		    ) portMAX_DELAY);   

// This call blocks the current task until any bit defined in EVENTBIT_ALL becomes set, 
// then clears the matched event bits and stores the previous event-group value in EventValue
EventValue = xEventGroupWaitBits((EventGroupHandle_t) xEventGroupHandler, // Event group to monitor
						     				         (EventBits_t		    ) EVENTBIT_ALL,       // Bit mask to wait for
										             (BaseType_t		    ) pdTRUE,             // Clear matched bits before returning
										             (BaseType_t		    ) pdFALSE,            // Wait for ANY bit, not all bits
								                 (TickType_t		    ) portMAX_DELAY);     // Wait indefinitely     								                                              

xEventGroupSync()

xEventGroupSync() synchronizes multiple tasks at a common execution point. It atomically sets the event bits specified by uxBitsToSet, then blocks the calling task until all bits in uxBitsToWaitFor are set or the timeout expires. The function returns the event-group value that caused the task to unblock, allowing the task to determine whether synchronization was completed successfully.

EventBits_t xEventGroupSync(EventGroupHandle_t xEventGroup, 
                            const EventBits_t uxBitsToSet, 
                            const EventBits_t uxBitsToWaitFor, 
                            TickType_t xTicksToWait)
                            
// ---------------------- Example ----------------------

#define TASK1_BIT (1UL << 0UL)
#define TASK2_BIT (1UL << 1UL)
#define TASK3_BIT (1UL << 2UL)

EventGroupHandle_t xEventGroup;
EventBits_t uxAllSyncBits = (TASK1_BIT | TASK2_BIT | TASK3_BIT);

xEventGroup = xEventGroupCreate();

void vTask1Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK1_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
		}
	}
}

void vTask2Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK2_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
		}
	}
}

void vTask3Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK3_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
			printf("All tasks set \r\n");
			vTaskDelay(_200ms);
		}
	}
}                            

EventBits_t xEventGroupSync(EventGroupHandle_t xEventGroup, 
                            const EventBits_t uxBitsToSet, 
                            const EventBits_t uxBitsToWaitFor, 
                            TickType_t xTicksToWait)
                            
// ---------------------- Example ----------------------

#define TASK1_BIT (1UL << 0UL)
#define TASK2_BIT (1UL << 1UL)
#define TASK3_BIT (1UL << 2UL)

EventGroupHandle_t xEventGroup;
EventBits_t uxAllSyncBits = (TASK1_BIT | TASK2_BIT | TASK3_BIT);

xEventGroup = xEventGroupCreate();

void vTask1Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK1_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
		}
	}
}

void vTask2Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK2_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
		}
	}
}

void vTask3Task(void *pvParameters) {
	EventBits_t uxReturn;
	while(1) {
		uxReturn = xEventGroupSync(xEventGroup, TASK3_BIT, uxAllSyncBits, portMAX_DELAY);
		if( uxAllSyncBits == (uxReturn & uxAllSyncBits) ) {
			// Do something
			printf("All tasks set \r\n");
			vTaskDelay(_200ms);
		}
	}
}                            

One-shot timer: once started, it will execute its callback function once only. It can be restarted manually, but will not restart itself

Auto-reload timer: once started, it will re-start itself each time it expires, resulting in periodic execution of its callback function

#define configUSE_TIMERS              1 
#define configTIMER_TASK_PRIORITY     (configMAX_PRIORITIES-1) 
#define configTIMER_QUEUE_LENGTH      5
#define configTIMER_TASK_STACK_DEPTH  (configMINIMAL_STACK_SIZE*2)

#define configUSE_TIMERS              1 
#define configTIMER_TASK_PRIORITY     (configMAX_PRIORITIES-1) 
#define configTIMER_QUEUE_LENGTH      5
#define configTIMER_TASK_STACK_DEPTH  (configMINIMAL_STACK_SIZE*2)

xTimerCreate()

Creates a FreeRTOS software timer using dynamically allocated memory from the FreeRTOS heap. It defines the timer name, period, one-shot or auto-reload mode, timer ID, and callback function. The newly created timer remains dormant until it is started.

TimerHandle_t xTimerCreate(const char * const pcTimerName,
                           TickType_t xTimerPeriodInTicks,
                           UBaseType_t uxAutoReload,
                           void * pvTimerID,
                           TimerCallbackFunction_t pxCallbackFunction)
                           
// ---------------------- Example ----------------------

TimerHandle_t OneShotTimer_Handle;
TimerHandle_t AutoReloadTimer_Handle;

void OneShotTimerCallback(TimerHandle_t xTimer);    
void AutoReloadTimerCallback(TimerHandle_t xTimer); 

OneShotTimer_Handle = xTimerCreate("OneShotTimer",
			                     	       mainONE_SHOT_TIMER_PERIOD,
								                   pdFALSE,
								                   0,
								                   OneShotTimerCallback);
								                   
AutoReloadTimer_Handle = xTimerCreate("AutoReloadTimer",
									                    mainAUTO_RELOAD_TIMER_PERIOD,
									                    pdTRUE,
									                    0,
									                    AutoReloadTimerCallback);

TimerHandle_t xTimerCreate(const char * const pcTimerName,
                           TickType_t xTimerPeriodInTicks,
                           UBaseType_t uxAutoReload,
                           void * pvTimerID,
                           TimerCallbackFunction_t pxCallbackFunction)
                           
// ---------------------- Example ----------------------

TimerHandle_t OneShotTimer_Handle;
TimerHandle_t AutoReloadTimer_Handle;

void OneShotTimerCallback(TimerHandle_t xTimer);    
void AutoReloadTimerCallback(TimerHandle_t xTimer); 

OneShotTimer_Handle = xTimerCreate("OneShotTimer",
			                     	       mainONE_SHOT_TIMER_PERIOD,
								                   pdFALSE,
								                   0,
								                   OneShotTimerCallback);
								                   
AutoReloadTimer_Handle = xTimerCreate("AutoReloadTimer",
									                    mainAUTO_RELOAD_TIMER_PERIOD,
									                    pdTRUE,
									                    0,
									                    AutoReloadTimerCallback);

xTimerCreateStatic()

Creates a software timer using a StaticTimer_t memory buffer supplied by the application. Unlike xTimerCreate(), it does not allocate memory from the FreeRTOS heap, making memory usage predictable and suitable for systems that avoid dynamic allocation.

TimerHandle_t xTimerCreateStatic(const char * const pcTimerName,
                                 TickType_t xTimerPeriodInTicks,
                                 UBaseType_t uxAutoReload,
                                 void * pvTimerID,
                                 TimerCallbackFunction_t pxCallbackFunction,
                                 StaticTimer_t * pxTimerBuffer)

TimerHandle_t xTimerCreateStatic(const char * const pcTimerName,
                                 TickType_t xTimerPeriodInTicks,
                                 UBaseType_t uxAutoReload,
                                 void * pvTimerID,
                                 TimerCallbackFunction_t pxCallbackFunction,
                                 StaticTimer_t * pxTimerBuffer)

xTimerStart()

Starts a previously created software timer from normal task context. After the specified timer period expires, the timer’s callback function executes. For an auto-reload timer, this repeats periodically; for a one-shot timer, it occurs only once.

BaseType_t xTimerStart(TimerHandle_t xTimer, 
                       TickType_t xTicksToWait)
                       
// ---------------------- Example ----------------------

TimerHandle_t OneShotTimer_Handle;
TimerHandle_t AutoReloadTimer_Handle;

xTimerStart(OneShotTimer_Handle, 0);
xTimerStart(AutoReloadTimer_Handle, 0);

BaseType_t xTimerStart(TimerHandle_t xTimer, 
                       TickType_t xTicksToWait)
                       
// ---------------------- Example ----------------------

TimerHandle_t OneShotTimer_Handle;
TimerHandle_t AutoReloadTimer_Handle;

xTimerStart(OneShotTimer_Handle, 0);
xTimerStart(AutoReloadTimer_Handle, 0);

xTimerStartFromISR()

Starts or restarts a software timer from an interrupt service routine. It sends a start command to the timer command queue and uses pxHigherPriorityTaskWoken to indicate whether a context switch should occur when the ISR exits.

BaseType_t xTimerStartFromISR(TimerHandle_t xTimer,
                              BaseType_t * pxHigherPriorityTaskWoken)

BaseType_t xTimerStartFromISR(TimerHandle_t xTimer,
                              BaseType_t * pxHigherPriorityTaskWoken)

xTimerStop()

Stops an active software timer from normal task context. Once stopped, the timer will not expire or execute its callback function, but the timer object remains valid and can be started again later.

BaseType_t xTimerStop(TimerHandle_t xTimer, 
                      TickType_t xTicksToWait)

// ---------------------- Example ----------------------

TimerHandle_t AutoReloadTimer_Handle;
xTimerStop(AutoReloadTimer_Handle, 0);

BaseType_t xTimerStop(TimerHandle_t xTimer, 
                      TickType_t xTicksToWait)

// ---------------------- Example ----------------------

TimerHandle_t AutoReloadTimer_Handle;
xTimerStop(AutoReloadTimer_Handle, 0);

xTimerStopFromISR()

Stops an active software timer from an interrupt service routine. It is the interrupt-safe version of xTimerStop() and can request a context switch through the pxHigherPriorityTaskWoken parameter.

BaseType_t xTimerStopFromISR(TimerHandle_t xTimer,
                             BaseType_t * pxHigherPriorityTaskWoken)

BaseType_t xTimerStopFromISR(TimerHandle_t xTimer,
                             BaseType_t * pxHigherPriorityTaskWoken)

xTimerReset()

Resets a timer’s expiration time from normal task context. If the timer is active, it restarts the full timer period from the moment the reset is requested; if it is dormant, the reset operation also starts it.

BaseType_t xTimerReset(TimerHandle_t xTimer, 
                       TickType_t xTicksToWait)

BaseType_t xTimerReset(TimerHandle_t xTimer, 
                       TickType_t xTicksToWait)

xTimerResetFromISR()

Resets or starts a software timer from an interrupt service routine. It recalculates the expiration time from the moment it is called and uses pxHigherPriorityTaskWoken to indicate whether an ISR-level context switch is required.

BaseType_t xTimerResetFromISR(TimerHandle_t xTimer,
                              BaseType_t * pxHigherPriorityTaskWoken)

BaseType_t xTimerResetFromISR(TimerHandle_t xTimer,
                              BaseType_t * pxHigherPriorityTaskWoken)

External Memory Interface (EMIF)

This EMIF memory controller is compliant with the JESD21-C SDR SDRAM memories utilizing a 32-bit/16-bit data bus. The purpose of this EMIF is to provide a means for the CPU to connect to a variety of external devices including:

• Single data rate (SDR) SDRAM
• Asynchronous devices including NOR Flash and SRAM

A common use for the EMIF is to interface with both a flash device and an SDRAM device simultaneously.

Interfacing to SDRAM

The EMIF supports a glueless interface to SDRAM devices with the following characteristics:

• Pre-charge bit is A[10]
• The number of column address bits is 8, 9, 10, or 11
• The number of row address bits is 13, 14, 15, or 16
• The number of internal banks is 1, 2, or 4

Interfacing to Asynchronous Memory

The EMIF easily interfaces to a variety of asynchronous devices including NOR Flash and SRAM. It can be operated in two major modes

• Normal Mode
• Select Strobe Mode

EMIF Performance

Reference

[1] TMS320F2837xD Microcontroller Workshop

(1) The task calls xSemaphoreTake() to acquire the semaphore. Since the semaphore is unavailable, Task is placed into the Blocked state until the semaphore becomes available.

(2) An interrupt occurs, and the interrupt service routine (ISR) calls xSemaphoreGiveFromISR() to give the semaphore. As a result, the semaphore becomes available.

(3) Because the semaphore is now available, Task successfully acquires it using xSemaphoreTake(). The task transitions from the Blocked state to the Running (or Ready, depending on the scheduler) state and begins executing the associated processing.

(4) Since a task function typically runs in an infinite loop, after completing the required processing it calls xSemaphoreTake() again to wait for the semaphore. Because the semaphore became unavailable after Step 3, the task enters the Blocked state once again, just as it did in Step 1. It remains blocked until another interrupt occurs and the interrupt service routine (ISR) calls xSemaphoreGiveFromISR() to give the semaphore.

xSemaphoreCreateBinary()

Creates a binary semaphore using memory dynamically allocated from the FreeRTOS heap. A binary semaphore has only two states: available and unavailable, internally represented by a count of 1 or 0. The semaphore is created in the unavailable/empty state, so xSemaphoreGive() must normally be called before the first successful xSemaphoreTake(). It is commonly used for task-to-task or interrupt-to-task synchronization. The function returns a semaphore handle on success or NULL if memory allocation fails.

SemaphoreHandle_t xSemaphoreCreateBinary(void)

// ---------------------- Example ----------------------

SemaphoreHandle_t xBinarySemaphore;
xBinarySemaphore = xSemaphoreCreateBinary();
xSemaphoreGive(xBinarySemaphore);

xSemaphoreTake(xBinarySemaphore, portMAX_DELAY);
xSemaphoreGive(xBinarySemaphore);

SemaphoreHandle_t xSemaphoreCreateBinary(void)

// ---------------------- Example ----------------------

SemaphoreHandle_t xBinarySemaphore;
xBinarySemaphore = xSemaphoreCreateBinary();
xSemaphoreGive(xBinarySemaphore);

xSemaphoreTake(xBinarySemaphore, portMAX_DELAY);
xSemaphoreGive(xBinarySemaphore);

xSemaphoreCreateBinaryStatic()

Creates a binary semaphore without using the FreeRTOS heap. The application provides a StaticSemaphore_t object that stores the semaphore’s internal control information. This buffer must remain valid for the entire lifetime of the semaphore, so it should normally be global or declared with static. Like the dynamically created version, the semaphore starts empty and must be given before it can be taken. Static creation is useful in safety-critical or memory-constrained systems where dynamic allocation is undesirable.

SemaphoreHandle_t xSemaphoreCreateBinaryStatic(StaticSemaphore_t *pxSemaphoreBuffer)

SemaphoreHandle_t xSemaphoreCreateBinaryStatic(StaticSemaphore_t *pxSemaphoreBuffer)

xSemaphoreCreateCounting()

Creates a dynamically allocated counting semaphore. uxMaxCount specifies the largest value the semaphore count can reach, while uxInitialCount specifies its starting value and must not exceed the maximum. Every successful xSemaphoreGive() increases the count, and every successful xSemaphoreTake() decreases it. Counting semaphores are commonly used either to count pending events or to manage a pool of identical resources. The function returns a valid handle on success or NULL if allocation fails.

SemaphoreHandle_t xSemaphoreCreateCounting(UBaseType_t uxMaxCount, 
                                           UBaseType_t uxInitialCount)
                                           
// ---------------------- Example ----------------------

SemaphoreHandle_t xCountSemaphore; 
xCountSemaphore = xSemaphoreCreateCounting(255, 0);

SemaphoreHandle_t xSemaphoreCreateCounting(UBaseType_t uxMaxCount, 
                                           UBaseType_t uxInitialCount)
                                           
// ---------------------- Example ----------------------

SemaphoreHandle_t xCountSemaphore; 
xCountSemaphore = xSemaphoreCreateCounting(255, 0);

xSemaphoreCreateCountingStatic()

Creates a counting semaphore using memory supplied by the application. It behaves like xSemaphoreCreateCounting(), but no FreeRTOS heap allocation is performed. The caller provides a persistent StaticSemaphore_t buffer that stores the semaphore’s control structure. The initial count must be less than or equal to the maximum count. This version is useful when all RTOS objects must have deterministic, statically allocated memory.

SemaphoreHandle_t xSemaphoreCreateCountingStatic(UBaseType_t uxMaxCount, 
                                                 UBaseType_t uxInitialCount, 
                                                 StaticSemaphore_t * pxSemaphoreBuffer)

SemaphoreHandle_t xSemaphoreCreateCountingStatic(UBaseType_t uxMaxCount, 
                                                 UBaseType_t uxInitialCount, 
                                                 StaticSemaphore_t * pxSemaphoreBuffer)

xSemaphoreCreateMutex()

Creates a dynamically allocated mutex for protecting a shared resource, such as a UART, SPI peripheral, file system, or shared data structure. Unlike a newly created binary semaphore, a newly created mutex starts in the available state and can immediately be taken. A mutex records which task owns it and provides priority inheritance to reduce priority-inversion problems. The task that successfully takes the mutex must be the task that gives it back. Mutexes must not be used from interrupt service routines.

SemaphoreHandle_t xSemaphoreCreateMutex(void)

// ---------------------- Example ----------------------

SemaphoreHandle_t xMutexSemaphore;
xMutexSemaphore = xSemaphoreCreateMutex();

SemaphoreHandle_t xSemaphoreCreateMutex(void)

// ---------------------- Example ----------------------

SemaphoreHandle_t xMutexSemaphore;
xMutexSemaphore = xSemaphoreCreateMutex();

xSemaphoreCreateMutexStatic()

Creates a mutex using a user-provided StaticSemaphore_t buffer instead of dynamically allocating memory. It provides the same ownership tracking, mutual-exclusion behavior, and priority inheritance as xSemaphoreCreateMutex(). The buffer must remain allocated for as long as the mutex exists. The mutex is initially available, so no initial xSemaphoreGive() is required. This function is suitable for applications that prohibit heap allocation after startup.

SemaphoreHandle_t xSemaphoreCreateMutexStatic(StaticSemaphore_t *pxMutexBuffer)

SemaphoreHandle_t xSemaphoreCreateMutexStatic(StaticSemaphore_t *pxMutexBuffer)

xSemaphoreGive()

Releases a semaphore from task context. For a binary semaphore, it changes the state from unavailable to available. For a counting semaphore, it increases the current count by one, provided the maximum count has not already been reached. For a mutex, it releases ownership so another waiting task can acquire the protected resource. The function returns pdTRUE when successful and pdFALSE when the semaphore is already full or cannot be released. It must not be called from an interrupt; use xSemaphoreGiveFromISR() instead.

BaseType_t xSemaphoreGive(xSemaphore)

// ---------------------- Example ----------------------

xSemaphoreGive(xBinarySemaphore);

BaseType_t xSemaphoreGive(xSemaphore)

// ---------------------- Example ----------------------

xSemaphoreGive(xBinarySemaphore);

xSemaphoreGiveFromISR()

Releases a binary or counting semaphore from an interrupt service routine. If giving the semaphore unblocks a task whose priority is higher than that of the currently running task, *pxHigherPriorityTaskWoken is set to pdTRUE. The ISR should then request a context switch with the port-specific macro, commonly portYIELD_FROM_ISR(). The variable should normally be initialized to pdFALSE before the call. This function cannot be used with mutexes because mutex ownership and priority inheritance require task context.

BaseType_t xSemaphoreGiveFromISR(SemaphoreHandle_t xSemaphore,
                                 BaseType_t * pxHigherPriorityTaskWoken)
                                 
// ---------------------- Example ----------------------

SemaphoreHandle_t xBinarySemaphore;
xBinarySemaphore = xSemaphoreCreateBinary();

BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xSemaphoreGiveFromISR(BinarySemaphore, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

BaseType_t xSemaphoreGiveFromISR(SemaphoreHandle_t xSemaphore,
                                 BaseType_t * pxHigherPriorityTaskWoken)
                                 
// ---------------------- Example ----------------------

SemaphoreHandle_t xBinarySemaphore;
xBinarySemaphore = xSemaphoreCreateBinary();

BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xSemaphoreGiveFromISR(BinarySemaphore, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

xSemaphoreTake()

Attempts to obtain a binary semaphore, counting semaphore, or standard mutex from task context. If the object is available, the operation succeeds immediately and its count is decreased. If it is unavailable, the calling task can enter the Blocked state for up to xTicksToWait ticks. A value of 0 performs a nonblocking check, while portMAX_DELAY can be used for an indefinite wait when the relevant FreeRTOS configuration permits it. The function returns pdTRUE when the semaphore is obtained and pdFALSE if the waiting time expires.

BaseType_t xSemaphoreTake(SemaphoreHandle_t xSemaphore,
                          TickType_t xBlockTime)

// ---------------------- Example ----------------------

xSemaphoreTake(xBinarySemaphore, portMAX_DELAY);

BaseType_t xSemaphoreTake(SemaphoreHandle_t xSemaphore,
                          TickType_t xBlockTime)

// ---------------------- Example ----------------------

xSemaphoreTake(xBinarySemaphore, portMAX_DELAY);

xSemaphoreTakeFromISR()

Attempts to obtain a binary or counting semaphore from an interrupt service routine. It cannot wait or block, so it succeeds only if the semaphore count is already greater than zero. A successful operation decreases the semaphore count and returns pdTRUE; otherwise, it returns pdFALSE. It must not be used with mutexes or recursive mutexes. In most interrupt-to-task synchronization designs, the ISR gives the semaphore and the task takes it, so this function is used less frequently than xSemaphoreGiveFromISR().

BaseType_t xSemaphoreTakeFromISR(SemaphoreHandle_t xSemaphore,
                                 BaseType_t * pxHigherPriorityTaskWoken)                         

BaseType_t xSemaphoreTakeFromISR(SemaphoreHandle_t xSemaphore,
                                 BaseType_t * pxHigherPriorityTaskWoken)                         

xSemaphoreCreateRecursiveMutex()

Creates a dynamically allocated recursive mutex. A recursive mutex allows its owning task to take the same mutex multiple times without blocking itself. FreeRTOS maintains an internal recursion count that records how many times the owner has successfully taken it. The task must give the mutex exactly the same number of times before another task can acquire it. Recursive mutexes are useful when a protected function calls another function that needs the same lock. They must be used with xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive(), not the standard take and give functions.

SemaphoreHandle_t xSemaphoreCreateRecursiveMutex(void)

SemaphoreHandle_t xSemaphoreCreateRecursiveMutex(void)

xSemaphoreCreateRecursiveMutexStatic()

Creates a recursive mutex using application-provided static memory. Its behavior is identical to the dynamically created recursive mutex, including ownership tracking, priority inheritance, and recursive nesting count. The supplied StaticSemaphore_t buffer must remain valid throughout the mutex’s lifetime. This function avoids heap allocation while still allowing the same task to lock a resource repeatedly. Recursive mutex support must be enabled in FreeRTOSConfig.h.

SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic(StaticSemaphore_t *pxMutexBuffer)

SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic(StaticSemaphore_t *pxMutexBuffer)

xSemaphoreTakeRecursive()

Obtains a mutex created specifically as a recursive mutex. The first successful call assigns ownership to the calling task. Additional calls from the same task succeed immediately and increase the recursive nesting count. Calls from other tasks block for up to xTicksToWait while the mutex remains owned. The function returns pdTRUE when the mutex is obtained and pdFALSE if the waiting time expires. It must not be used with a standard mutex created by xSemaphoreCreateMutex().

#define xSemaphoreTakeRecursive(xMutex, xBlockTime)
  xQueueTakeMutexRecursive(xMutex, xBlockTime)

#define xSemaphoreTakeRecursive(xMutex, xBlockTime)
  xQueueTakeMutexRecursive(xMutex, xBlockTime)

xSemaphoreGiveRecursive()

Releases one level of ownership of a recursive mutex. Each call decreases the mutex’s recursive nesting count by one. The mutex becomes available to other tasks only when the count reaches zero. Therefore, every successful call to xSemaphoreTakeRecursive() must eventually have a matching call to xSemaphoreGiveRecursive(). Only the task that owns the recursive mutex may give it, and the function must not be called from an ISR.

#define xSemaphoreGiveRecursive(xMutex)
  xQueueGiveMutexRecursive(xMutex)

#define xSemaphoreGiveRecursive(xMutex)
  xQueueGiveMutexRecursive(xMutex)