|
NetBurner 3.5.7
PDF Version |
Topics | |
| NBRTOS Error Codes | |
| NBRTOS Task Flags | |
| NBRTOS Task Status | |
Classes | |
| class | TickTimeout |
| Timeout helper that converts a relative tick duration into an absolute expiration point. More... | |
| struct | OS_SEM |
| Counting semaphore for task synchronization and resource management. More... | |
| struct | OS_MBOX |
| Single-message mailbox for passing one void-pointer value between tasks. More... | |
| class | TEMPL_MBOX< T > |
| Type-safe template wrapper around OS_MBOX for passing typed pointer messages. More... | |
| struct | OS_Q |
| Fixed-size FIFO message queue for passing void-pointer messages between tasks. More... | |
| struct | TEMPL_Q< T > |
| Type-safe template wrapper around OS_Q for passing typed pointer messages. More... | |
| struct | os_fifo_el |
| Element header for OS_FIFO linked-list entries. More... | |
| struct | OS_FIFO |
| A linked-list FIFO for passing pointers to user-defined structures between tasks. More... | |
| struct | TEMPL_FIFO< T > |
| Type-safe wrapper around OS_FIFO for passing typed structure pointers. More... | |
| struct | OS_CRIT |
| Mutual-exclusion critical section for protecting shared resources between tasks. More... | |
| struct | OS_FLAGS |
| A 32-bit event flag group that allows tasks to pend on multiple events. More... | |
| class | OSLockObj |
| RAII wrapper for OSLock()/OSUnlock() that prevents task switching within a scope. More... | |
| class | OSCriticalSectionObj |
| RAII wrapper for OS_CRIT that automatically enters and leaves a critical section. More... | |
| class | OSLockAndCritObj |
| RAII wrapper that combines an OS task lock with an OS_CRIT critical section. More... | |
| class | OSSpinCrit |
| RAII wrapper that spin-waits to claim a critical section. More... | |
| class | USERCritObj |
| RAII wrapper for hardware-level user critical sections (interrupt masking). More... | |
| class | NBRtosInitObj |
| Base class for objects that require RTOS initialization before use. More... | |
Macros | |
| #define | OS_LO_PRIO (OS_MAX_PRIOS-1) |
| Lowest task priority level (reserved for the system idle task). | |
| #define | WAIT_FOREVER 0 |
| Pass as a timeout parameter to wait indefinitely (no timeout) | |
| #define | OSSimpleTaskCreatewName(x, p, n) |
| Create a new task with an automatically allocated stack. | |
| #define | OSSimpleTaskCreatewNameSRAM(x, p, n) |
| Create a task with its stack allocated in on-chip SRAM. | |
| #define | OSSimpleTaskCreateLambda(p, n, f) LambdaTask2(p,n,[]( void * pv)f,__COUNTER__) |
| Create a task from inline code using a lambda expression. | |
Typedefs | |
| typedef volatile uint32_t | tick_t |
| Unsigned 32-bit type representing a system timer tick count. | |
| typedef struct os_fifo_el | OS_FIFO_EL |
| Element header for OS_FIFO linked-list entries. | |
Enumerations | |
| enum class | OSNextPrio { OSNextPrio::Maximum = -2 , OSNextPrio::Above = -1 , OSNextPrio::Below = 0 , OSNextPrio::Next = Below , OSNextPrio::Minimum = 1 } |
| Search direction for OSGetNextPrio() when finding an available task priority. More... | |
Functions | |
| bool | IsTickLater (uint32_t test_time) |
| Check whether a tick value is strictly later than the current TimeTick. | |
| bool | IsTickNowOrEarlier (uint32_t test_time) |
| Check whether a tick value is equal to or earlier than the current TimeTick. | |
| bool | Is2ndTickEarlier (uint32_t t1, uint32_t t2) |
| Compare two tick values and check whether t2 is strictly earlier than t1. | |
| bool | Is2ndTickNowOrEarlier (uint32_t t1, uint32_t t2) |
| Compare two tick values and check whether t2 is equal to or earlier than t1. | |
| void | OSFlagCreate (OS_FLAGS *pf) |
| Initialize an OS_FLAGS object. | |
| void | OSFlagSet (OS_FLAGS *flags, uint32_t bits_to_set) |
| Set the specified flag bits in an OS_FLAGS object. | |
| void | OSFlagClear (OS_FLAGS *flags, uint32_t bits_to_clr) |
| Clear the specified flag bits in an OS_FLAGS object. | |
| uint8_t | OSFlagPendAny (OS_FLAGS *flags, uint32_t bit_mask, uint16_t timeout) |
| Wait for any of the specified flag bits to be set. | |
| uint8_t | OSFlagPendAnyNoWait (OS_FLAGS *flags, uint32_t bit_mask) |
| Check if any of the specified flag bits are set without waiting. | |
| uint8_t | OSFlagPendAll (OS_FLAGS *flags, uint32_t bit_mask, uint16_t timeout) |
| Wait for all of the specified flag bits to be set. | |
| uint8_t | OSFlagPendAllNoWait (OS_FLAGS *flags, uint32_t bit_mask) |
| Check if all of the specified flag bits are set without waiting. | |
| uint32_t | OSFlagState (OS_FLAGS *flags) |
| Get the current flag bit values from an OS_FLAGS object. | |
| uint8_t | OSTaskCreatewName (void(*task)(void *dptr), void *data, void *pstktop, void *pstkbot, uint8_t prio, const char *name, OS_TCB **pRetHandle=NULL) |
| Create a new RTOS task with full control over stack allocation and priority. | |
| void | OSTimeWaitUntil (uint32_t systemTickValue) |
| Delay the calling task until the system TimeTick reaches the specified value. | |
| void | OSTimeDly (uint32_t to_count) |
| Delay the calling task for the specified number of system ticks. | |
| void | OSTaskDelete (void) |
| Terminate the calling task immediately. | |
| uint8_t | OSChangePrio (uint32_t newp) |
| Change the priority of the calling task. | |
| void | OSSetName (const char *cp) |
| Set the name of the calling task. | |
| void | OSLock (void) |
| Prevent the RTOS scheduler from switching tasks. | |
| void | OSUnlock (void) |
| Re-enable task switching after a previous call to OSLock(). | |
| uint8_t | OSSemInit (OS_SEM *psem, long value) |
| Initialize a semaphore object. | |
| uint8_t | OSSemPost (OS_SEM *psem) |
| Increment the semaphore count by one, releasing any waiting higher-priority tasks. | |
| uint8_t | OSSemPend (OS_SEM *psem, uint16_t timeout) |
| Wait for the semaphore count to become non-zero, then decrement it. | |
| uint8_t | OSSemPendNoWait (OS_SEM *psem) |
| Attempt to decrement the semaphore without waiting. | |
| uint8_t | OSMboxInit (OS_MBOX *pmbox, void *msg) |
| Initialize a mailbox object. | |
| uint8_t | OSMboxPost (OS_MBOX *pmbox, void *msg) |
| Post a message to a mailbox. | |
| void * | OSMboxPend (OS_MBOX *pmbox, uint16_t timeout, uint8_t *err) |
| Wait for a message to be posted to the mailbox. | |
| void * | OSMboxPendNoWait (OS_MBOX *pmbox, uint8_t *err) |
| Attempt to retrieve a message from the mailbox without waiting. | |
| uint8_t | OSQInit (OS_Q *pq, void **start, uint8_t size) |
| Initialize a message queue object. | |
| uint8_t | OSQPost (OS_Q *pq, void *msg) |
| Post a message to the tail of the queue. | |
| uint8_t | OSQPostFirst (OS_Q *pq, void *msg) |
| Post a message to the head of the queue (priority insertion). | |
| uint8_t | OSQPostUnique (OS_Q *pq, void *msg) |
| Post a message to the queue only if it is not already present. | |
| uint8_t | OSQPostUniqueFirst (OS_Q *pq, void *msg) |
| Post a message to the head of the queue only if it is not already present. | |
| void * | OSQPend (OS_Q *pq, uint16_t timeout, uint8_t *err) |
| Wait for a message to be posted to the queue. | |
| void * | OSQPendNoWait (OS_Q *pq, uint8_t *err) |
| Attempt to retrieve a message from the queue without waiting. | |
| uint8_t | OSFifoInit (OS_FIFO *pFifo) |
| Initialize a FIFO object for passing structures between tasks. | |
| uint8_t | OSFifoPost (OS_FIFO *pFifo, OS_FIFO_EL *pToPost) |
| Post an element to the tail of the FIFO. | |
| uint8_t | OSFifoPostFirst (OS_FIFO *pFifo, OS_FIFO_EL *pToPost) |
| Post an element to the head of the FIFO. | |
| OS_FIFO_EL * | OSFifoPend (OS_FIFO *pFifo, uint16_t timeout) |
| Wait for an element to be posted to the FIFO. | |
| OS_FIFO_EL * | OSFifoPendNoWait (OS_FIFO *pFifo) |
| Attempt to retrieve an element from the FIFO without waiting. | |
| uint8_t | OSCritInit (OS_CRIT *pCrit) |
| Initialize a critical section object. | |
| uint8_t | OSCritLockAndEnter (OS_CRIT *pCrit, uint16_t timeout) |
| Lock the OS and enter the critical section. | |
| uint8_t | OSCritEnter (OS_CRIT *pCrit, uint16_t timeout) |
| Wait to claim the critical section with a timeout. | |
| uint8_t | OSCritEnterNoWait (OS_CRIT *pCrit) |
| Attempt to claim the critical section without waiting. | |
| uint8_t | OSCritLeave (OS_CRIT *pCrit) |
| Release the critical section. | |
| uint8_t | OSCritLeaveAndUnlock (OS_CRIT *pCrit) |
| Leave the critical section and unlock the OS. | |
| uint8_t | OSTaskID (void) |
| Get the priority number of the calling task. | |
| int | OSGetNextPrio (OSNextPrio where=OSNextPrio::Below, int startingPrio=-1) |
| Find the next available (unused) task priority for creating a new task. | |
| const char * | OSTaskName () |
| Get the name of the calling task. | |
| void | OSChangeTaskDly (uint16_t task_prio, uint32_t to_count) |
| Modify the remaining delay for a waiting task. | |
| OS_TCB * | OSGetTaskBlock (uint16_t task_prio) |
| Get a pointer to the task control block (OS_TCB) for a given task priority. | |
| uint8_t | OSTaskJoin (OS_TCB *pTask, uint32_t timeoutDly=0) |
| Block the calling task until the specified task has finished executing. | |
| void | OSDumpStack (void) |
| Print the current task's call stack to stdout. | |
| void | OSDumpTCBStacks (void) |
| Print stack usage information for all task control blocks to stdout. | |
| void | OSDumpTasks (void) |
| Print the state and call stack of every task to stdout. | |
| void | OSStartTaskDumper (uint8_t prio, uint32_t reportInterval) |
| Create a background task that periodically calls OSDumpTasks(). | |
| void | ShowTaskList (void) |
| Print the current state of all RTOS tasks to stdout. | |
| bool | OS_CRIT::OwnedByCurTask () |
| Check whether the calling task currently owns this critical section. | |
Variables | |
| vuint32_t | Secs |
| Number of seconds elapsed since system start (updated once per second). | |
| volatile tick_t | TimeTick |
| Number of system timer ticks elapsed since system start. | |
#include< nbrtos.h>
The NetBurner Real-Time Operating System provides preemptive priority-based multitasking with a rich set of inter-task communication and synchronization primitives including semaphores (OS_SEM), mailboxes (OS_MBOX), queues (OS_Q), FIFOs (OS_FIFO), critical sections (OS_CRIT), and event flags (OS_FLAGS).
| #define OSSimpleTaskCreateLambda | ( | p, | |
| n, | |||
| f ) LambdaTask2(p,n,[]( void * pv)f,__COUNTER__) |
#include <nbrtos.h>
Create a task from inline code using a lambda expression.
Wraps the provided code block in a lambda and creates a task with an automatically allocated stack, similar to OSSimpleTaskCreatewName().
| p | Priority for the new task (1 = highest, OS_MAX_PRIOS = lowest). |
| n | Name string for the task. |
| f | Code block to execute as the task body (enclosed in braces). |
Expand for Example Usage
| #define OSSimpleTaskCreatewName | ( | x, | |
| p, | |||
| n ) |
#include <nbrtos.h>
Create a new task with an automatically allocated stack.
This is the preferred and simplest way to create a task. The macro automatically allocates a stack of USER_TASK_STK_SIZE words (4-byte aligned) and calls OSTaskCreatewName() internally.
Task priorities can be assigned dynamically with OSGetNextPrio():
| x | The task function (must have the signature void func(void *)). |
| p | Priority for the new task (1 = highest, OS_MAX_PRIOS = lowest). See <nburn_install>/nbrtos/include/constants.h for reserved priorities. |
| n | Name string for the task. |
Expand for Example Usage
| #define OSSimpleTaskCreatewNameSRAM | ( | x, | |
| p, | |||
| n ) |
#include <nbrtos.h>
Create a task with its stack allocated in on-chip SRAM.
Identical to OSSimpleTaskCreatewName() except the automatically allocated task stack is placed in fast on-chip SRAM instead of external memory. This can improve task switching performance on platforms with SRAM support.
| x | The task function to execute. |
| p | Priority for the new task (1 = highest, OS_MAX_PRIOS = lowest). |
| n | Name string for the task. |
| typedef struct os_fifo_el OS_FIFO_EL |
|
strong |
#include <nbrtos.h>
Search direction for OSGetNextPrio() when finding an available task priority.
| Enumerator | |
|---|---|
| Maximum | Highest priority currently unused, 0->OS_LO_PRIO. |
| Above | Lowest priority that is higher than the current task, OSTaskID()->0. |
| Below | Highest priority that is lower than the current task, OSTaskID()->OS_LO_PRIO. |
| Next | Highest priority that is lower than the current task, OSTaskID()->OS_LO_PRIO. |
| Minimum | Lowest priority currently unused, OS_LO_PRIO->0. |
|
inline |
#include <nbrtos.h>
Compare two tick values and check whether t2 is strictly earlier than t1.
| t1 | First tick value. |
| t2 | Second tick value. |
| true | t2 is earlier than t1. |
| false | t2 is equal to or later than t1. |
|
inline |
#include <nbrtos.h>
Compare two tick values and check whether t2 is equal to or earlier than t1.
| t1 | First tick value. |
| t2 | Second tick value. |
| true | t2 is equal to or earlier than t1. |
| false | t2 is later than t1. |
|
inline |
#include <nbrtos.h>
Check whether a tick value is strictly later than the current TimeTick.
Uses signed arithmetic to handle 32-bit rollover correctly.
| test_time | The tick value to test. |
| true | test_time is in the future relative to TimeTick. |
| false | test_time is now or in the past. |
|
inline |
#include <nbrtos.h>
Check whether a tick value is equal to or earlier than the current TimeTick.
| test_time | The tick value to test. |
| true | test_time is now or in the past. |
| false | test_time is in the future. |
| uint8_t OSChangePrio | ( | uint32_t | newp | ) |
#include <nbrtos.h>
Change the priority of the calling task.
Priorities range from 1 (highest) to OS_MAX_PRIOS (lowest). Each priority level can be occupied by only one task. The recommended user range is 46 to OS_MAX_PRIOS - 1 to avoid conflicts with system and network tasks.
System priorities are defined in <nburn_install>/nbrtos/include/constants.h.
| newp | The new priority for the calling task. |
| OS_NO_ERR | If the priority was changed successfully. |
| OS_PRIO_EXIST | If another task already occupies the requested priority. |
|
inline |
#include <nbrtos.h>
Modify the remaining delay for a waiting task.
Replaces the current delay of the task at the specified priority with a new delay of to_count ticks from now.
| task_prio | The priority of the task whose delay should be changed. |
| to_count | The new number of system ticks to delay from now. |
|
inline |
#include <nbrtos.h>
Wait to claim the critical section with a timeout.
| pCrit | Pointer to the OS_CRIT object. |
| timeout | Number of time ticks to wait. A value of 0 waits forever. |
| OS_NO_ERR | If the section was claimed or is already owned by the calling task. |
| OS_TIMEOUT | If the section could not be claimed before the timeout. |
|
inline |
#include <nbrtos.h>
Attempt to claim the critical section without waiting.
| pCrit | Pointer to the OS_CRIT object. |
| OS_NO_ERR | If the section was claimed or is already owned by the calling task. |
| OS_TIMEOUT | If the section is owned by another task. |
|
inline |
#include <nbrtos.h>
Initialize a critical section object.
| pCrit | Pointer to the OS_CRIT object to initialize. |
| OS_NO_ERR | If successful. |
|
inline |
#include <nbrtos.h>
Release the critical section.
| pCrit | Pointer to the OS_CRIT object to release. |
| OS_NO_ERR | If the critical section was successfully released. |
| OS_CRIT_ERR | If the calling task does not own the critical section. |
|
inline |
#include <nbrtos.h>
Leave the critical section and unlock the OS.
| pCrit | Pointer to the OS_CRIT object. |
| OS_NO_ERR | If successful. |
| OS_CRIT_ERR | If the calling task does not own the critical section. |
|
inline |
#include <nbrtos.h>
Lock the OS and enter the critical section.
| pCrit | Pointer to the OS_CRIT object. |
| timeout | Number of time ticks to wait. A value of 0 waits forever. |
| OS_NO_ERR | If the critical section was successfully claimed. |
| OS_TIMEOUT | If the section could not be claimed before the timeout. |
| void OSDumpStack | ( | void | ) |
#include <nbrtos.h>
Print the current task's call stack to stdout.
Useful for debugging to inspect where the calling task is currently executing.
| void OSDumpTasks | ( | void | ) |
#include <nbrtos.h>
Print the state and call stack of every task to stdout.
Displays detailed per-task information including current status, priority, and a symbolic call stack trace. Useful for diagnosing deadlocks, hangs, or unexpected task behavior during development.
NBRTOS_STACKCHECK is defined in predef.h.| void OSDumpTCBStacks | ( | void | ) |
#include <nbrtos.h>
Print stack usage information for all task control blocks to stdout.
Reports the allocated and used stack space for each task, which is useful for tuning stack sizes and detecting near-overflow conditions during development.
NBRTOS_STACKCHECK is defined in predef.h.
|
inline |
#include <nbrtos.h>
Initialize a FIFO object for passing structures between tasks.
| pFifo | Pointer to the OS_FIFO object to initialize. |
| OS_NO_ERR | If successful. |
| OS_CRIT_ERR | If pFifo is NULL. |
|
inline |
#include <nbrtos.h>
Wait for an element to be posted to the FIFO.
| pFifo | Pointer to the OS_FIFO object. |
| timeout | Number of system ticks to wait. A value of 0 waits forever. |
|
inline |
#include <nbrtos.h>
Attempt to retrieve an element from the FIFO without waiting.
| pFifo | Pointer to the OS_FIFO object. |
|
inline |
#include <nbrtos.h>
Post an element to the tail of the FIFO.
| pFifo | Pointer to the OS_FIFO object. |
| pToPost | Pointer to the element (cast as OS_FIFO_EL) to post. |
| OS_NO_ERR | If successful. |
|
inline |
#include <nbrtos.h>
Post an element to the head of the FIFO.
| pFifo | Pointer to the OS_FIFO object. |
| pToPost | Pointer to the element (cast as OS_FIFO_EL) to post at the head. |
| OS_NO_ERR | If successful. |
|
inline |
#include <nbrtos.h>
Clear the specified flag bits in an OS_FLAGS object.
| flags | Pointer to the OS_FLAGS object. |
| bits_to_clr | Bitmask of flag bits to clear. |
|
inline |
#include <nbrtos.h>
Initialize an OS_FLAGS object.
| pf | Pointer to the OS_FLAGS object to initialize. |
|
inline |
#include <nbrtos.h>
Wait for all of the specified flag bits to be set.
| flags | Pointer to the OS_FLAGS object. |
| bit_mask | Bitmask of flags that must all be set. |
| timeout | Number of time ticks to wait. A value of 0 waits forever. |
| OS_NO_ERR | All specified flag bits were set before the timeout. |
| OS_TIMEOUT | The timeout expired before all flags were set. |
|
inline |
#include <nbrtos.h>
Check if all of the specified flag bits are set without waiting.
| flags | Pointer to the OS_FLAGS object. |
| bit_mask | Bitmask of flags that must all be set. |
| OS_NO_ERR | All specified flag bits are currently set. |
| OS_TIMEOUT | Not all specified flag bits are set. |
|
inline |
#include <nbrtos.h>
Wait for any of the specified flag bits to be set.
| flags | Pointer to the OS_FLAGS object. |
| bit_mask | Bitmask of flags to wait on. |
| timeout | Number of time ticks to wait. A value of 0 waits forever. |
| OS_NO_ERR | At least one specified flag bit was set before the timeout. |
| OS_TIMEOUT | No specified flag bits were set before the timeout. |
|
inline |
#include <nbrtos.h>
Check if any of the specified flag bits are set without waiting.
| flags | Pointer to the OS_FLAGS object. |
| bit_mask | Bitmask of flags to check. |
| OS_NO_ERR | At least one specified flag bit is set. |
| OS_TIMEOUT | None of the specified flag bits are set. |
|
inline |
#include <nbrtos.h>
Set the specified flag bits in an OS_FLAGS object.
| flags | Pointer to the OS_FLAGS object. |
| bits_to_set | Bitmask of flag bits to set. |
|
inline |
#include <nbrtos.h>
Get the current flag bit values from an OS_FLAGS object.
| flags | Pointer to the OS_FLAGS object. |
| int OSGetNextPrio | ( | OSNextPrio | where = OSNextPrio::Below, |
| int | startingPrio = -1 ) |
#include <nbrtos.h>
Find the next available (unused) task priority for creating a new task.
Searches for an unused priority relative to a starting priority. The search direction and range are controlled by the where parameter.
| where | The search direction relative to the starting priority. |
| startingPrio | The priority to search from. If negative (the default), the calling task's current priority is used. |
| OS_TCB * OSGetTaskBlock | ( | uint16_t | task_prio | ) |
#include <nbrtos.h>
Get a pointer to the task control block (OS_TCB) for a given task priority.
| task_prio | The priority of the task whose OS_TCB is requested. |
| void OSLock | ( | void | ) |
#include <nbrtos.h>
Prevent the RTOS scheduler from switching tasks.
Increments the lock nesting counter so the calling task cannot be preempted. Calls to OSLock() may be nested; you must call OSUnlock() once for each OSLock().
|
inline |
#include <nbrtos.h>
Initialize a mailbox object.
| pmbox | Pointer to the OS_MBOX object to initialize. |
| msg | Initial message to store, or NULL for an empty mailbox. |
| OS_NO_ERR | If successful. |
| OS_CRIT_ERR | If pmbox is NULL. |
|
inline |
#include <nbrtos.h>
Wait for a message to be posted to the mailbox.
| pmbox | Pointer to the OS_MBOX object. | |
| timeout | Number of system ticks to wait. A value of 0 waits forever. | |
| [out] | err | Receives OS_NO_ERR on success or OS_TIMEOUT on timeout. |
|
inline |
#include <nbrtos.h>
Attempt to retrieve a message from the mailbox without waiting.
| pmbox | Pointer to the OS_MBOX object. |
| err | Pointer to receive OS_NO_ERR on success or OS_TIMEOUT if empty. |
|
inline |
#include <nbrtos.h>
Post a message to a mailbox.
| pmbox | Pointer to the OS_MBOX object. |
| msg | The message pointer to post. |
| OS_NO_ERR | If successful. |
| OS_MBOX_FULL | If the mailbox already contains a message. |
|
inline |
#include <nbrtos.h>
Initialize a message queue object.
| pq | Pointer to the OS_Q object to initialize. |
| start | Pointer to an array of void pointers that serves as the queue storage. |
| size | Number of entries in the storage array. |
| OS_NO_ERR | If successful. |
| OS_CRIT_ERR | If pq or start is NULL. |
|
inline |
#include <nbrtos.h>
Wait for a message to be posted to the queue.
| pq | Pointer to the OS_Q object. | |
| timeout | Number of system ticks to wait. A value of 0 waits forever. | |
| [out] | err | Receives OS_NO_ERR on success or OS_TIMEOUT on timeout. |
|
inline |
#include <nbrtos.h>
Attempt to retrieve a message from the queue without waiting.
| pq | Pointer to the OS_Q object. | |
| [out] | err | Receives OS_NO_ERR on success or OS_TIMEOUT if the queue is empty. |
|
inline |
#include <nbrtos.h>
Post a message to the tail of the queue.
| pq | Pointer to the OS_Q object. |
| msg | The message pointer to post. |
| OS_NO_ERR | If successful. |
| OS_Q_FULL | If the queue is full. |
|
inline |
#include <nbrtos.h>
Post a message to the head of the queue (priority insertion).
| pq | Pointer to the OS_Q object. |
| msg | The message pointer to post at the head. |
| OS_NO_ERR | If successful. |
| OS_Q_FULL | If the queue is full. |
|
inline |
#include <nbrtos.h>
Post a message to the queue only if it is not already present.
Performs a linear scan to verify the message is unique before posting.
| pq | Pointer to the OS_Q object. |
| msg | The message pointer to post. |
| OS_NO_ERR | If the message was successfully posted. |
| OS_Q_FULL | If the queue is full. |
| OS_Q_EXISTS | If the message already exists in the queue. |
|
inline |
#include <nbrtos.h>
Post a message to the head of the queue only if it is not already present.
| pq | Pointer to the OS_Q object. |
| msg | The message pointer to post. |
| OS_NO_ERR | If the message was successfully posted. |
| OS_Q_FULL | If the queue is full. |
| OS_Q_EXISTS | If the message already exists in the queue. |
|
inline |
#include <nbrtos.h>
Initialize a semaphore object.
| psem | Pointer to the OS_SEM object to initialize. |
| value | The initial count value for the semaphore. |
| OS_NO_ERR | If successful. |
| OS_SEM_ERR | If the initial value is negative. |
| OS_CRIT_ERR | If psem is NULL. |
|
inline |
#include <nbrtos.h>
Wait for the semaphore count to become non-zero, then decrement it.
| psem | Pointer to the OS_SEM object. |
| timeout | Number of system ticks to wait. A value of 0 waits forever. |
| OS_NO_ERR | If the semaphore was successfully acquired. |
| OS_TIMEOUT | If the timeout expired before the semaphore became available. |
|
inline |
#include <nbrtos.h>
Attempt to decrement the semaphore without waiting.
| psem | Pointer to the OS_SEM object. |
| OS_NO_ERR | If the semaphore count was non-zero and was decremented. |
| OS_TIMEOUT | If the semaphore count was zero. |
|
inline |
#include <nbrtos.h>
Increment the semaphore count by one, releasing any waiting higher-priority tasks.
| psem | Pointer to the OS_SEM object. |
| OS_NO_ERR | If successful. |
| OS_SEM_OVF | If the semaphore count would overflow. |
| void OSSetName | ( | const char * | cp | ) |
#include <nbrtos.h>
Set the name of the calling task.
The pointer must remain valid for the lifetime of the task (use a string literal or statically allocated buffer).
| cp | Pointer to the new null-terminated task name string. |
| void OSStartTaskDumper | ( | uint8_t | prio, |
| uint32_t | reportInterval ) |
#include <nbrtos.h>
Create a background task that periodically calls OSDumpTasks().
The created task runs at the specified priority and invokes OSDumpTasks() at every reportInterval system tick interval. Intended for continuous monitoring of task states during development.
| prio | Priority for the dumper task. |
| reportInterval | Number of system ticks between each dump. |
NBRTOS_STACKCHECK is defined in predef.h.| uint8_t OSTaskCreatewName | ( | void(* | task )(void *dptr), |
| void * | data, | ||
| void * | pstktop, | ||
| void * | pstkbot, | ||
| uint8_t | prio, | ||
| const char * | name, | ||
| OS_TCB ** | pRetHandle = NULL ) |
#include <nbrtos.h>
Create a new RTOS task with full control over stack allocation and priority.
You must provide a 4-byte-aligned stack buffer for the new task. For most use cases, OSSimpleTaskCreatewName() is simpler because it allocates the stack automatically.
Task priorities range from 1 (highest) to OS_MAX_PRIOS (lowest). Only one task may exist at each priority level. The recommended range for user tasks is 46 to OS_MAX_PRIOS - 1 to avoid conflicts with system and network tasks. Both OS_MAX_PRIOS and OS_MAX_TASKS are defined in <nburn_install>/nbrtos/include/constants.h.
| task | Pointer to the task function (signature: void func(void *)). |
| data | Argument passed to the task function, or NULL if unused. |
| pstktop | Pointer to the top (highest address) of the stack buffer. |
| pstkbot | Pointer to the bottom (lowest address) of the stack buffer. |
| prio | Priority for the new task (1 = highest, OS_MAX_PRIOS = lowest). |
| name | Null-terminated name string for the task. |
| pRetHandle | Optional pointer to receive the OS_TCB handle of the new task. |
| OS_NO_ERR | If the task was created successfully. |
| OS_PRIO_EXIST | If a task already exists at the requested priority. |
Expand for Example Usage
| void OSTaskDelete | ( | void | ) |
#include <nbrtos.h>
Terminate the calling task immediately.
| uint8_t OSTaskID | ( | void | ) |
#include <nbrtos.h>
Get the priority number of the calling task.
Since each task has a unique priority, this value also serves as the task identifier.
| uint8_t OSTaskJoin | ( | OS_TCB * | pTask, |
| uint32_t | timeoutDly = 0 ) |
#include <nbrtos.h>
Block the calling task until the specified task has finished executing.
Similar to POSIX pthread_join(), this function suspends the caller until the target task terminates (returns from its task function or calls OSTaskDelete()).
| pTask | Pointer to the OS_TCB of the task to wait for. |
| timeoutDly | Maximum number of system ticks to wait. A value of 0 waits forever. |
| OS_NO_ERR | The target task completed. |
| OS_TIMEOUT | The timeout expired before the target task completed. |
| OS_PRIO_EXIST | The target task is the calling task (cannot join self). |
| OS_PRIO_INVALID | The provided OS_TCB pointer is not valid. |
| const char * OSTaskName | ( | ) |
#include <nbrtos.h>
Get the name of the calling task.
|
inline |
#include <nbrtos.h>
Delay the calling task for the specified number of system ticks.
The number of ticks per second is defined by TICKS_PER_SECOND in <nburn_install>/nbrtos/include/constants.h (default: 20 ticks/second).
TICKS_PER_SECOND macro to express delays in human-readable units, e.g. OSTimeDly(5 * TICKS_PER_SECOND) for a 5-second delay.WAIT_FOREVER (0) convention used by timeout parameters in functions such as OS_SEM::Pend() and OS_FLAGS::PendAny(), which explicitly interpret 0 as "wait indefinitely."| to_count | Number of system ticks to delay. |
| void OSTimeWaitUntil | ( | uint32_t | systemTickValue | ) |
#include <nbrtos.h>
Delay the calling task until the system TimeTick reaches the specified value.
Unlike OSTimeDly(), which delays for a relative duration, this function waits for an absolute TimeTick value. This is ideal for creating periodic tasks with consistent intervals that do not drift regardless of how long the task body takes to execute.
The number of ticks per second is defined by TICKS_PER_SECOND in <nburn_install>/nbrtos/include/constants.h (default: 20 ticks/second).
| systemTickValue | The absolute system TimeTick value to wait for. |
Expand for Example Usage
| void OSUnlock | ( | void | ) |
#include <nbrtos.h>
Re-enable task switching after a previous call to OSLock().
You must call OSUnlock() once for every call to OSLock(). When the nesting count reaches zero, the scheduler is re-enabled and any pending context switch occurs immediately.
|
inline |
#include <nbrtos.h>
Check whether the calling task currently owns this critical section.
| true | The calling task owns this section. |
| false | The calling task does not own this section. |
| true | The calling task owns this critical section |
| false | The calling task does not own this critical section |
| void ShowTaskList | ( | void | ) |
#include <nbrtos.h>
Print the current state of all RTOS tasks to stdout.
Displays a formatted table of every registered task including its priority, name, status, and stack usage.
NBRTOS_TASKLIST is defined in predef.h.
The output takes on multiple lines of the following format for each logged state:
at t= [T] [Message]
Followed by a tally of the number of task states logged since system start:
Total messages: [N]
[T] represents the number of ticks in hexadecimal since system start; [N] represents the number of task state messages in decimal logged since system start; [Message] represents one of the output messages listed in the below table.
| Message | Description |
|---|---|
Wait for Semaphore | Task is asleep and pending for semaphore |
Wake from Semaphore | Task gets a semaphore and wakes up |
Task locked | Task becomes locked |
Task lock++ | Task gets an added nested lock |
Task lock– | Task get a nested lock unlocked |
Task unlocked | Task becomes completely unlocked |
Task priority changed | The task's priority level is changed |
Unknown flag [F] | The flag value defining the task's state is undefined |
Switched to Task [P] | Task priority [P] (in decimal) gets control |
Switched to Task [P] PC=[X] | Task priority [P] gets control with the program counter containing the address [X] (in hexadecimal) of the instruction being executed |
Note: Usage of this function is valid only when defining NBRTOS_TASKLIST in debug mode. In order to enable this macro definition, it must be uncommented in \Nburn\include\predef.h, followed by rebuilding the system files to incorporate the modification. Attempting to load a compiled non-debug application image with the macro defined will cause a trap error.