NetBurner 3.5.7
PDF Version
NBRTOS Real Time Operating System

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_ELOSFifoPend (OS_FIFO *pFifo, uint16_t timeout)
 Wait for an element to be posted to the FIFO.
 
OS_FIFO_ELOSFifoPendNoWait (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.
 

Detailed Description

#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).

Macro Definition Documentation

◆ OSSimpleTaskCreateLambda

#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().

Parameters
pPriority for the new task (1 = highest, OS_MAX_PRIOS = lowest).
nName string for the task.
fCode block to execute as the task body (enclosed in braces).
See also
OSTaskCreatewName(), OSSimpleTaskCreatewName()

Expand for Example Usage

Examples

Create a Lambda Task
OSSimpleTaskCreateLambda(MAIN_PRIO - 1, "MyLambdaTask", {
while (1)
{
iprintf("Hello from lambda task\r\n");
}
});
#define TICKS_PER_SECOND
System clock ticks per second.
Definition constants.h:49
#define MAIN_PRIO
Recommend UserMain priority.
Definition constants.h:130
#define OSSimpleTaskCreateLambda(p, n, f)
Create a task from inline code using a lambda expression.
Definition nbrtos.h:2143
void OSTimeDly(uint32_t to_count)
Delay the calling task for the specified number of system ticks.
Definition nbrtos.h:2202

◆ OSSimpleTaskCreatewName

#define OSSimpleTaskCreatewName ( x,
p,
n )

#include <nbrtos.h>

Value:
[&]() { \
static uint32_t func_##x##_Stk[USER_TASK_STK_SIZE] __attribute__((aligned(4))); \
return OSTaskCreatewName(x, NULL, (void *)&func_##x##_Stk[USER_TASK_STK_SIZE], (void *)func_##x##_Stk, p, n); \
}()
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.

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():

int OSGetNextPrio(OSNextPrio where=OSNextPrio::Below, int startingPrio=-1)
Find the next available (unused) task priority for creating a new task.
#define OSSimpleTaskCreatewName(x, p, n)
Create a new task with an automatically allocated stack.
Definition nbrtos.h:2081
@ Below
Highest priority that is lower than the current task, OSTaskID()->OS_LO_PRIO.
Parameters
xThe task function (must have the signature void func(void *)).
pPriority for the new task (1 = highest, OS_MAX_PRIOS = lowest). See <nburn_install>/nbrtos/include/constants.h for reserved priorities.
nName string for the task.
See also
OSTaskCreatewName(), OSTaskDelete(), OSChangePrio(), OSGetNextPrio(), OSNextPrio

Expand for Example Usage

Examples

Create a Simple Task
void TaskSimple(void *pd)
{
while (1)
{
// task code
}
}
// In UserMain()....
returnCode = OSSimpleTaskCreatewName(TaskSimple, MAIN_PRIO - 2, "TaskSimple");
if (returnCode == OS_NO_ERR)
printf("Task creation successful\r\n");
else
printf("*** Error: status = %d\r\n", returnCode);
#define OS_NO_ERR
No error.
Definition nbrtos.h:67

◆ OSSimpleTaskCreatewNameSRAM

#define OSSimpleTaskCreatewNameSRAM ( x,
p,
n )

#include <nbrtos.h>

Value:
[&]() { \
static uint32_t func_##x##_Stk[USER_TASK_STK_SIZE] __attribute__((aligned(4))) FAST_USER_STK; \
return OSTaskCreatewName(x, NULL, (void *)&func_##x##_Stk[USER_TASK_STK_SIZE], (void *)func_##x##_Stk, p, n); \
}()

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.

Parameters
xThe task function to execute.
pPriority for the new task (1 = highest, OS_MAX_PRIOS = lowest).
nName string for the task.
See also
OSSimpleTaskCreatewName(), OSTaskCreatewName(), OSGetNextPrio(), OSNextPrio

Typedef Documentation

◆ OS_FIFO_EL

typedef struct os_fifo_el OS_FIFO_EL

#include <nbrtos.h>

Element header for OS_FIFO linked-list entries.

Every structure passed through an OS_FIFO must begin with this type (or a layout-compatible union) so the FIFO can maintain its internal linked list.

Enumeration Type Documentation

◆ OSNextPrio

enum class OSNextPrio
strong

#include <nbrtos.h>

Search direction for OSGetNextPrio() when finding an available task priority.

See also
OSGetNextPrio()
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.

Function Documentation

◆ Is2ndTickEarlier()

bool Is2ndTickEarlier ( uint32_t t1,
uint32_t t2 )
inline

#include <nbrtos.h>

Compare two tick values and check whether t2 is strictly earlier than t1.

Parameters
t1First tick value.
t2Second tick value.
Return values
truet2 is earlier than t1.
falset2 is equal to or later than t1.
See also
Is2ndTickNowOrEarlier(), IsTickLater()

◆ Is2ndTickNowOrEarlier()

bool Is2ndTickNowOrEarlier ( uint32_t t1,
uint32_t t2 )
inline

#include <nbrtos.h>

Compare two tick values and check whether t2 is equal to or earlier than t1.

Parameters
t1First tick value.
t2Second tick value.
Return values
truet2 is equal to or earlier than t1.
falset2 is later than t1.
See also
Is2ndTickEarlier(), IsTickNowOrEarlier()

◆ IsTickLater()

bool IsTickLater ( uint32_t test_time)
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.

Parameters
test_timeThe tick value to test.
Return values
truetest_time is in the future relative to TimeTick.
falsetest_time is now or in the past.
See also
IsTickNowOrEarlier(), Is2ndTickEarlier()

◆ IsTickNowOrEarlier()

bool IsTickNowOrEarlier ( uint32_t test_time)
inline

#include <nbrtos.h>

Check whether a tick value is equal to or earlier than the current TimeTick.

Parameters
test_timeThe tick value to test.
Return values
truetest_time is now or in the past.
falsetest_time is in the future.
See also
IsTickLater(), Is2ndTickNowOrEarlier()

◆ OSChangePrio()

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.

Parameters
newpThe new priority for the calling task.
Return values
OS_NO_ERRIf the priority was changed successfully.
OS_PRIO_EXISTIf another task already occupies the requested priority.
See also
NBRTOS Error Codes, OSTaskCreatewName(), OSTaskID()

◆ OSChangeTaskDly()

void OSChangeTaskDly ( uint16_t task_prio,
uint32_t to_count )
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.

Warning
Use of this function is discouraged. Modifying another task's delay can lead to difficult-to-debug timing issues.
Parameters
task_prioThe priority of the task whose delay should be changed.
to_countThe new number of system ticks to delay from now.
See also
OSTimeDly(), OSTimeWaitUntil()

◆ OSCritEnter()

uint8_t OSCritEnter ( OS_CRIT * pCrit,
uint16_t timeout )
inline

#include <nbrtos.h>

Wait to claim the critical section with a timeout.

Parameters
pCritPointer to the OS_CRIT object.
timeoutNumber of time ticks to wait. A value of 0 waits forever.
Return values
OS_NO_ERRIf the section was claimed or is already owned by the calling task.
OS_TIMEOUTIf the section could not be claimed before the timeout.
See also
NBRTOS Error Codes
Deprecated
Use OS_CRIT::Enter() instead.

◆ OSCritEnterNoWait()

uint8_t OSCritEnterNoWait ( OS_CRIT * pCrit)
inline

#include <nbrtos.h>

Attempt to claim the critical section without waiting.

Parameters
pCritPointer to the OS_CRIT object.
Return values
OS_NO_ERRIf the section was claimed or is already owned by the calling task.
OS_TIMEOUTIf the section is owned by another task.
See also
NBRTOS Error Codes
Deprecated
Use OS_CRIT::EnterNoWait() instead.

◆ OSCritInit()

uint8_t OSCritInit ( OS_CRIT * pCrit)
inline

#include <nbrtos.h>

Initialize a critical section object.

Parameters
pCritPointer to the OS_CRIT object to initialize.
Return values
OS_NO_ERRIf successful.
See also
NBRTOS Error Codes
Deprecated
Use OS_CRIT::Init() or the OS_CRIT constructor instead.

◆ OSCritLeave()

uint8_t OSCritLeave ( OS_CRIT * pCrit)
inline

#include <nbrtos.h>

Release the critical section.

Parameters
pCritPointer to the OS_CRIT object to release.
Return values
OS_NO_ERRIf the critical section was successfully released.
OS_CRIT_ERRIf the calling task does not own the critical section.
See also
NBRTOS Error Codes
Deprecated
Use OS_CRIT::Leave() instead.

◆ OSCritLeaveAndUnlock()

uint8_t OSCritLeaveAndUnlock ( OS_CRIT * pCrit)
inline

#include <nbrtos.h>

Leave the critical section and unlock the OS.

Parameters
pCritPointer to the OS_CRIT object.
Return values
OS_NO_ERRIf successful.
OS_CRIT_ERRIf the calling task does not own the critical section.
Deprecated
Use OS_CRIT::LeaveAndUnlock() instead.

◆ OSCritLockAndEnter()

uint8_t OSCritLockAndEnter ( OS_CRIT * pCrit,
uint16_t timeout )
inline

#include <nbrtos.h>

Lock the OS and enter the critical section.

Parameters
pCritPointer to the OS_CRIT object.
timeoutNumber of time ticks to wait. A value of 0 waits forever.
Return values
OS_NO_ERRIf the critical section was successfully claimed.
OS_TIMEOUTIf the section could not be claimed before the timeout.
Deprecated
Use OS_CRIT::LockAndEnter() instead.

◆ OSDumpStack()

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.

◆ OSDumpTasks()

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.

Note
Only available when NBRTOS_STACKCHECK is defined in predef.h.
See also
OSDumpTCBStacks(), ShowTaskList()

◆ OSDumpTCBStacks()

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.

Note
Only available when NBRTOS_STACKCHECK is defined in predef.h.
See also
OSDumpTasks(), ShowTaskList()

◆ OSFifoInit()

uint8_t OSFifoInit ( OS_FIFO * pFifo)
inline

#include <nbrtos.h>

Initialize a FIFO object for passing structures between tasks.

Parameters
pFifoPointer to the OS_FIFO object to initialize.
Return values
OS_NO_ERRIf successful.
OS_CRIT_ERRIf pFifo is NULL.
See also
NBRTOS Error Codes
Deprecated
Use OS_FIFO::Init() or the OS_FIFO constructor instead.

◆ OSFifoPend()

OS_FIFO_EL * OSFifoPend ( OS_FIFO * pFifo,
uint16_t timeout )
inline

#include <nbrtos.h>

Wait for an element to be posted to the FIFO.

Parameters
pFifoPointer to the OS_FIFO object.
timeoutNumber of system ticks to wait. A value of 0 waits forever.
Returns
Pointer to the retrieved OS_FIFO_EL if successful, or NULL on timeout.
Deprecated
Use OS_FIFO::Pend() instead.

◆ OSFifoPendNoWait()

OS_FIFO_EL * OSFifoPendNoWait ( OS_FIFO * pFifo)
inline

#include <nbrtos.h>

Attempt to retrieve an element from the FIFO without waiting.

Parameters
pFifoPointer to the OS_FIFO object.
Returns
Pointer to the retrieved OS_FIFO_EL if an element was available, or NULL otherwise.
Deprecated
Use OS_FIFO::PendNoWait() instead.

◆ OSFifoPost()

uint8_t OSFifoPost ( OS_FIFO * pFifo,
OS_FIFO_EL * pToPost )
inline

#include <nbrtos.h>

Post an element to the tail of the FIFO.

Parameters
pFifoPointer to the OS_FIFO object.
pToPostPointer to the element (cast as OS_FIFO_EL) to post.
Return values
OS_NO_ERRIf successful.
See also
NBRTOS Error Codes
Deprecated
Use OS_FIFO::Post() instead.

◆ OSFifoPostFirst()

uint8_t OSFifoPostFirst ( OS_FIFO * pFifo,
OS_FIFO_EL * pToPost )
inline

#include <nbrtos.h>

Post an element to the head of the FIFO.

Parameters
pFifoPointer to the OS_FIFO object.
pToPostPointer to the element (cast as OS_FIFO_EL) to post at the head.
Return values
OS_NO_ERRIf successful.
See also
NBRTOS Error Codes
Deprecated
Use OS_FIFO::PostFirst() instead.

◆ OSFlagClear()

void OSFlagClear ( OS_FLAGS * flags,
uint32_t bits_to_clr )
inline

#include <nbrtos.h>

Clear the specified flag bits in an OS_FLAGS object.

Parameters
flagsPointer to the OS_FLAGS object.
bits_to_clrBitmask of flag bits to clear.
Deprecated
Use OS_FLAGS::Clear() instead.

◆ OSFlagCreate()

void OSFlagCreate ( OS_FLAGS * pf)
inline

#include <nbrtos.h>

Initialize an OS_FLAGS object.

Parameters
pfPointer to the OS_FLAGS object to initialize.
Deprecated
Use OS_FLAGS::Init() or the OS_FLAGS constructor instead.

◆ OSFlagPendAll()

uint8_t OSFlagPendAll ( OS_FLAGS * flags,
uint32_t bit_mask,
uint16_t timeout )
inline

#include <nbrtos.h>

Wait for all of the specified flag bits to be set.

Parameters
flagsPointer to the OS_FLAGS object.
bit_maskBitmask of flags that must all be set.
timeoutNumber of time ticks to wait. A value of 0 waits forever.
Return values
OS_NO_ERRAll specified flag bits were set before the timeout.
OS_TIMEOUTThe timeout expired before all flags were set.
Deprecated
Use OS_FLAGS::PendAll() instead.

◆ OSFlagPendAllNoWait()

uint8_t OSFlagPendAllNoWait ( OS_FLAGS * flags,
uint32_t bit_mask )
inline

#include <nbrtos.h>

Check if all of the specified flag bits are set without waiting.

Parameters
flagsPointer to the OS_FLAGS object.
bit_maskBitmask of flags that must all be set.
Return values
OS_NO_ERRAll specified flag bits are currently set.
OS_TIMEOUTNot all specified flag bits are set.
Deprecated
Use OS_FLAGS::PendAllNoWait() instead.

◆ OSFlagPendAny()

uint8_t OSFlagPendAny ( OS_FLAGS * flags,
uint32_t bit_mask,
uint16_t timeout )
inline

#include <nbrtos.h>

Wait for any of the specified flag bits to be set.

Parameters
flagsPointer to the OS_FLAGS object.
bit_maskBitmask of flags to wait on.
timeoutNumber of time ticks to wait. A value of 0 waits forever.
Return values
OS_NO_ERRAt least one specified flag bit was set before the timeout.
OS_TIMEOUTNo specified flag bits were set before the timeout.
Deprecated
Use OS_FLAGS::PendAny() instead.

◆ OSFlagPendAnyNoWait()

uint8_t OSFlagPendAnyNoWait ( OS_FLAGS * flags,
uint32_t bit_mask )
inline

#include <nbrtos.h>

Check if any of the specified flag bits are set without waiting.

Parameters
flagsPointer to the OS_FLAGS object.
bit_maskBitmask of flags to check.
Return values
OS_NO_ERRAt least one specified flag bit is set.
OS_TIMEOUTNone of the specified flag bits are set.
Deprecated
Use OS_FLAGS::PendAnyNoWait() instead.

◆ OSFlagSet()

void OSFlagSet ( OS_FLAGS * flags,
uint32_t bits_to_set )
inline

#include <nbrtos.h>

Set the specified flag bits in an OS_FLAGS object.

Parameters
flagsPointer to the OS_FLAGS object.
bits_to_setBitmask of flag bits to set.
Deprecated
Use OS_FLAGS::Set() instead.

◆ OSFlagState()

uint32_t OSFlagState ( OS_FLAGS * flags)
inline

#include <nbrtos.h>

Get the current flag bit values from an OS_FLAGS object.

Parameters
flagsPointer to the OS_FLAGS object.
Returns
The current 32-bit flag state.
Deprecated
Use OS_FLAGS::State() instead.

◆ OSGetNextPrio()

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.

Parameters
whereThe search direction relative to the starting priority.
startingPrioThe priority to search from. If negative (the default), the calling task's current priority is used.
Returns
The next available priority, or a negative value if no priority is available in the requested direction.
See also
OSNextPrio, OSTaskCreatewName(), OSSimpleTaskCreatewName()

◆ OSGetTaskBlock()

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.

Parameters
task_prioThe priority of the task whose OS_TCB is requested.
Returns
Pointer to the OS_TCB for the specified priority, or NULL if no task exists at that priority.
See also
OSTaskCreatewName(), OSTaskID()

◆ OSLock()

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().

Warning
Do not hold the lock for extended periods or perform blocking I/O while locked. The network subsystem will degrade and eventually lose packets. For RAII-style usage, prefer the OSLockObj wrapper class.
See also
OSUnlock(), OSLockObj

◆ OSMboxInit()

uint8_t OSMboxInit ( OS_MBOX * pmbox,
void * msg )
inline

#include <nbrtos.h>

Initialize a mailbox object.

Parameters
pmboxPointer to the OS_MBOX object to initialize.
msgInitial message to store, or NULL for an empty mailbox.
Return values
OS_NO_ERRIf successful.
OS_CRIT_ERRIf pmbox is NULL.
See also
NBRTOS Error Codes
Deprecated
Use OS_MBOX::Init() or the OS_MBOX constructor instead.

◆ OSMboxPend()

void * OSMboxPend ( OS_MBOX * pmbox,
uint16_t timeout,
uint8_t * err )
inline

#include <nbrtos.h>

Wait for a message to be posted to the mailbox.

Parameters
pmboxPointer to the OS_MBOX object.
timeoutNumber of system ticks to wait. A value of 0 waits forever.
[out]errReceives OS_NO_ERR on success or OS_TIMEOUT on timeout.
Returns
The message pointer, or NULL on timeout.
Deprecated
Use OS_MBOX::Pend() instead.

◆ OSMboxPendNoWait()

void * OSMboxPendNoWait ( OS_MBOX * pmbox,
uint8_t * err )
inline

#include <nbrtos.h>

Attempt to retrieve a message from the mailbox without waiting.

Parameters
pmboxPointer to the OS_MBOX object.
errPointer to receive OS_NO_ERR on success or OS_TIMEOUT if empty.
Returns
The message pointer, or NULL if the mailbox was empty.
Deprecated
Use OS_MBOX::PendNoWait() instead.

◆ OSMboxPost()

uint8_t OSMboxPost ( OS_MBOX * pmbox,
void * msg )
inline

#include <nbrtos.h>

Post a message to a mailbox.

Parameters
pmboxPointer to the OS_MBOX object.
msgThe message pointer to post.
Return values
OS_NO_ERRIf successful.
OS_MBOX_FULLIf the mailbox already contains a message.
See also
NBRTOS Error Codes
Deprecated
Use OS_MBOX::Post() instead.

◆ OSQInit()

uint8_t OSQInit ( OS_Q * pq,
void ** start,
uint8_t size )
inline

#include <nbrtos.h>

Initialize a message queue object.

Parameters
pqPointer to the OS_Q object to initialize.
startPointer to an array of void pointers that serves as the queue storage.
sizeNumber of entries in the storage array.
Return values
OS_NO_ERRIf successful.
OS_CRIT_ERRIf pq or start is NULL.
See also
NBRTOS Error Codes
Deprecated
Use OS_Q::Init() or the OS_Q constructor instead.

◆ OSQPend()

void * OSQPend ( OS_Q * pq,
uint16_t timeout,
uint8_t * err )
inline

#include <nbrtos.h>

Wait for a message to be posted to the queue.

Parameters
pqPointer to the OS_Q object.
timeoutNumber of system ticks to wait. A value of 0 waits forever.
[out]errReceives OS_NO_ERR on success or OS_TIMEOUT on timeout.
Returns
The retrieved message pointer, or NULL on timeout.
Deprecated
Use OS_Q::Pend() instead.

◆ OSQPendNoWait()

void * OSQPendNoWait ( OS_Q * pq,
uint8_t * err )
inline

#include <nbrtos.h>

Attempt to retrieve a message from the queue without waiting.

Parameters
pqPointer to the OS_Q object.
[out]errReceives OS_NO_ERR on success or OS_TIMEOUT if the queue is empty.
Returns
The retrieved message pointer, or NULL if the queue was empty.
Deprecated
Use OS_Q::PendNoWait() instead.

◆ OSQPost()

uint8_t OSQPost ( OS_Q * pq,
void * msg )
inline

#include <nbrtos.h>

Post a message to the tail of the queue.

Parameters
pqPointer to the OS_Q object.
msgThe message pointer to post.
Return values
OS_NO_ERRIf successful.
OS_Q_FULLIf the queue is full.
See also
NBRTOS Error Codes
Deprecated
Use OS_Q::Post() instead.

◆ OSQPostFirst()

uint8_t OSQPostFirst ( OS_Q * pq,
void * msg )
inline

#include <nbrtos.h>

Post a message to the head of the queue (priority insertion).

Parameters
pqPointer to the OS_Q object.
msgThe message pointer to post at the head.
Return values
OS_NO_ERRIf successful.
OS_Q_FULLIf the queue is full.
See also
NBRTOS Error Codes
Deprecated
Use OS_Q::PostFirst() instead.

◆ OSQPostUnique()

uint8_t OSQPostUnique ( OS_Q * pq,
void * msg )
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.

Parameters
pqPointer to the OS_Q object.
msgThe message pointer to post.
Return values
OS_NO_ERRIf the message was successfully posted.
OS_Q_FULLIf the queue is full.
OS_Q_EXISTSIf the message already exists in the queue.
See also
NBRTOS Error Codes
Deprecated
Use OS_Q::PostUnique() instead.

◆ OSQPostUniqueFirst()

uint8_t OSQPostUniqueFirst ( OS_Q * pq,
void * msg )
inline

#include <nbrtos.h>

Post a message to the head of the queue only if it is not already present.

Parameters
pqPointer to the OS_Q object.
msgThe message pointer to post.
Return values
OS_NO_ERRIf the message was successfully posted.
OS_Q_FULLIf the queue is full.
OS_Q_EXISTSIf the message already exists in the queue.
See also
NBRTOS Error Codes
Deprecated
Use OS_Q::PostUniqueFirst() instead.

◆ OSSemInit()

uint8_t OSSemInit ( OS_SEM * psem,
long value )
inline

#include <nbrtos.h>

Initialize a semaphore object.

Parameters
psemPointer to the OS_SEM object to initialize.
valueThe initial count value for the semaphore.
Return values
OS_NO_ERRIf successful.
OS_SEM_ERRIf the initial value is negative.
OS_CRIT_ERRIf psem is NULL.
See also
NBRTOS Error Codes
Deprecated
Use OS_SEM::Init() or the OS_SEM constructor instead.

◆ OSSemPend()

uint8_t OSSemPend ( OS_SEM * psem,
uint16_t timeout )
inline

#include <nbrtos.h>

Wait for the semaphore count to become non-zero, then decrement it.

Parameters
psemPointer to the OS_SEM object.
timeoutNumber of system ticks to wait. A value of 0 waits forever.
Return values
OS_NO_ERRIf the semaphore was successfully acquired.
OS_TIMEOUTIf the timeout expired before the semaphore became available.
See also
NBRTOS Error Codes
Deprecated
Use OS_SEM::Pend() instead.

◆ OSSemPendNoWait()

uint8_t OSSemPendNoWait ( OS_SEM * psem)
inline

#include <nbrtos.h>

Attempt to decrement the semaphore without waiting.

Parameters
psemPointer to the OS_SEM object.
Return values
OS_NO_ERRIf the semaphore count was non-zero and was decremented.
OS_TIMEOUTIf the semaphore count was zero.
See also
NBRTOS Error Codes
Deprecated
Use OS_SEM::PendNoWait() instead.

◆ OSSemPost()

uint8_t OSSemPost ( OS_SEM * psem)
inline

#include <nbrtos.h>

Increment the semaphore count by one, releasing any waiting higher-priority tasks.

Parameters
psemPointer to the OS_SEM object.
Return values
OS_NO_ERRIf successful.
OS_SEM_OVFIf the semaphore count would overflow.
See also
NBRTOS Error Codes
Deprecated
Use OS_SEM::Post() instead.

◆ OSSetName()

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).

Parameters
cpPointer to the new null-terminated task name string.
See also
OSTaskName(), OSTaskCreatewName()

◆ OSStartTaskDumper()

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.

Parameters
prioPriority for the dumper task.
reportIntervalNumber of system ticks between each dump.
Note
Only available when NBRTOS_STACKCHECK is defined in predef.h.
See also
OSDumpTasks(), OSDumpTCBStacks()

◆ OSTaskCreatewName()

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.

Note
Always check the return value to confirm the task was created successfully.
Parameters
taskPointer to the task function (signature: void func(void *)).
dataArgument passed to the task function, or NULL if unused.
pstktopPointer to the top (highest address) of the stack buffer.
pstkbotPointer to the bottom (lowest address) of the stack buffer.
prioPriority for the new task (1 = highest, OS_MAX_PRIOS = lowest).
nameNull-terminated name string for the task.
pRetHandleOptional pointer to receive the OS_TCB handle of the new task.
Return values
OS_NO_ERRIf the task was created successfully.
OS_PRIO_EXISTIf a task already exists at the requested priority.
See also
OSSimpleTaskCreatewName(), OSTaskDelete(), OSChangePrio(), OSGetNextPrio(), OSNextPrio, NBRTOS Error Codes

Expand for Example Usage

Examples

Create a Task with Explicit Stack
void TaskAllParams(void *pd)
{
while (1)
{
// task code
}
}
// In UserMain()....
uint32_t TaskAllParamsStack[USER_TASK_STK_SIZE];
returnCode = OSTaskCreatewName(TaskAllParams, // Task function
(void *)delayTime, // Parameter
&TaskAllParamsStack[USER_TASK_STK_SIZE], // Stack top
TaskAllParamsStack, // Stack bottom
MAIN_PRIO - 1, // Priority
"TaskAllParams"); // Name
if (returnCode == OS_NO_ERR)
printf("Task creation successful\r\n");
else
printf("*** Error: status = %d\r\n", returnCode);
Dynamic Priority Allocation
uint32_t MyTaskStack[USER_TASK_STK_SIZE];
OSTaskCreatewName(MyTask, NULL,
&MyTaskStack[USER_TASK_STK_SIZE], MyTaskStack,
OSGetNextPrio(OSNextPrio::Below), "MyTask_BelowPrio");

◆ OSTaskDelete()

void OSTaskDelete ( void )

#include <nbrtos.h>

Terminate the calling task immediately.

Warning
This function can cause memory leaks because it does not give the task an opportunity to free allocated resources. The preferred approach is to signal the task (e.g. via a semaphore or flag) so it can release its resources and terminate gracefully by returning from its task function.
See also
OSTaskCreatewName(), OSChangePrio(), OSTaskJoin()

◆ OSTaskID()

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.

Returns
The priority (ID) of the calling task.
See also
OSChangePrio(), OSTaskName()

◆ OSTaskJoin()

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()).

Parameters
pTaskPointer to the OS_TCB of the task to wait for.
timeoutDlyMaximum number of system ticks to wait. A value of 0 waits forever.
Return values
OS_NO_ERRThe target task completed.
OS_TIMEOUTThe timeout expired before the target task completed.
OS_PRIO_EXISTThe target task is the calling task (cannot join self).
OS_PRIO_INVALIDThe provided OS_TCB pointer is not valid.
See also
OSTaskCreatewName(), OSTaskDelete(), NBRTOS Error Codes

◆ OSTaskName()

const char * OSTaskName ( )

#include <nbrtos.h>

Get the name of the calling task.

Returns
Pointer to the null-terminated name string assigned at task creation.
See also
OSSetName(), OSTaskCreatewName()

◆ OSTimeDly()

void OSTimeDly ( uint32_t to_count)
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).

Note
Use the TICKS_PER_SECOND macro to express delays in human-readable units, e.g. OSTimeDly(5 * TICKS_PER_SECOND) for a 5-second delay.
A value of 0 does not block indefinitely. It sets the wake-up time to the current TimeTick, causing the task to yield the CPU and return almost immediately once the scheduler runs. This is different from the 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."
Parameters
to_countNumber of system ticks to delay.
See also
OSTimeWaitUntil(), OSChangeTaskDly()

◆ OSTimeWaitUntil()

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).

Parameters
systemTickValueThe absolute system TimeTick value to wait for.
See also
OSTimeDly(), OSChangeTaskDly()

Expand for Example Usage

Examples

Periodic 60-Second Task
uint32_t Now = TimeTick;
while (1)
{
Now += 60 * TICKS_PER_SECOND;
// Runs every 60 seconds with consistent spacing
}
volatile tick_t TimeTick
Number of system timer ticks elapsed since system start.
void OSTimeWaitUntil(uint32_t systemTickValue)
Delay the calling task until the system TimeTick reaches the specified value.

◆ OSUnlock()

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.

See also
OSLock(), OSLockObj

◆ OwnedByCurTask()

bool OS_CRIT::OwnedByCurTask ( )
inline

#include <nbrtos.h>

Check whether the calling task currently owns this critical section.

Return values
trueThe calling task owns this section.
falseThe calling task does not own this section.
trueThe calling task owns this critical section
falseThe calling task does not own this critical section

◆ ShowTaskList()

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.

Note
Only available when 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.

See also
OSDumpTasks(), OSDumpTCBStacks()