Modules | |
NBRTOS Error Codes | |
NBRTOS Task Status | |
Classes | |
class | TickTimeout |
TickTimeouts are used to facilitate sequential function calls with timeout parameters that need to index from an initial start time and be proof against TimeTick rollover. More... | |
class | OS_SEM |
Semaphores are used to control access to shared resource critical section, or to communicate between tasks. More... | |
class | OS_MBOX |
Mailboxes are used to communicate between tasks. More... | |
class | OS_Q |
A queue functions as a fixed size FIFO for communication between tasks. More... | |
class | OS_FIFO |
A FIFO is used to pass structures from one task to another. Note: Structures to be passed must have an unused (void *) pointer as its first element. This precludes passing C++ objects with virtual member functions. More... | |
class | OS_CRIT |
An OS_CRIT object is used to establish critical sections of code that can only be run by one task at a time. Tasks that try to claim a critical section which is currently claimed by another task will stop and wait for that task to leave the critical section before continuing execution. More... | |
class | OS_FLAGS |
An OS_FLAGS object is used to set, clear, and pend on a set of flags that is held and maintained by the object. More... | |
class | OSLockObj |
A simple wrapper class that helps use OS locks effectively. More... | |
class | OSCriticalSectionObj |
A simple wrapper class that helps utilize OS_CRIT objects more effectively. More... | |
class | OSLockAndCritObj |
A simple wrapper class that helps utilize OS_CRIT objects to lock tasks and enter critical sections more effectively. More... | |
class | OSSpinCrit |
A simple wrapper class that uses an OS_CRIT object to try and claim a critical section, and will continue the attempt until it is able to do so. More... | |
Macros | |
#define | WAIT_FOREVER 0 |
#define | OSSimpleTaskCreatewName(x, p, n) |
Functions | |
void | OSFlagSet (OS_FLAGS *flags, uint32_t bits_to_set) |
This function sets the corresponding bits asserted in bits_to_set of an OS_FLAGS object pointed to by *flags . More... | |
void | OSFlagClear (OS_FLAGS *flags, uint32_t bits_to_clr) |
This function clears the bits asserted in bits_to_clr of an OS_FLAGS object pointed to by *flags.. More... | |
uint8_t | OSFlagPendAny (OS_FLAGS *flags, uint32_t bit_mask, uint16_t timeout) |
This function waits a number of time ticks specified by timeout until any of the flags indicated by bit_mask are set. More... | |
uint8_t | OSFlagPendAnyNoWait (OS_FLAGS *flags, uint32_t bit_mask) |
This function immediately checks to see if any of the flag bits indicated by bit_mask are set; it does not wait. More... | |
uint8_t | OSFlagPendAll (OS_FLAGS *flags, uint32_t bit_mask, uint16_t timeout) |
This function waits a number of time ticks specified by timeout until all the flags indicated by bit_mask are set. More... | |
uint8_t | OSFlagPendAllNoWait (OS_FLAGS *flags, uint32_t bit_mask) |
This function immediately checks to see if all the flag bits indicated by bit_mask are set; it does not wait. More... | |
uint32_t | OSFlagState (OS_FLAGS *flags) |
This function returns the current values of the flags stored in the OS_FLAGS object structure. More... | |
uint8_t | OSTaskCreatewName (void(*task)(void *dptr), void *data, void *pstktop, void *pstkbot, uint8_t prio, const char *name) |
void | OSTimeDly (uint32_t to_count) |
Delay the task until the specified value of the system timer ticks. The number of system ticks per second is defined by the constant: TICKS_PER_SECOND in <nburn_install>/nbrtos/include/constants.h . The default value is 20 ticks per second. More... | |
void | OSTaskDelete (void) |
This function deletes the current calling task, but we do not recommend the use of this function because it can cause memory leaks. More... | |
uint8_t | OSChangePrio (uint32_t newp) |
This function changes the priority of the calling task. More... | |
void | OSLock (void) |
Calling the OSLock function will prevent the OS from changing tasks. More... | |
void | OSUnlock (void) |
This function unlocks the OS. More... | |
uint8_t | OSSemInit (OS_SEM *psem, long value) |
Initializes a semaphore. More... | |
uint8_t | OSSemPost (OS_SEM *psem) |
Increases the value of the semaphore by one. Note: If any higher priority tasks were waiting on the semaphore - it releases them. More... | |
uint8_t | OSSemPend (OS_SEM *psem, uint16_t timeout) |
Wait timeout ticks for the value of the semaphore to be non zero. Note: A timeout value of 0 (zero) waits forever. More... | |
uint8_t | OSSemPendNoWait (OS_SEM *psem) |
OSSemPendNoWait() is identical to OSSemPend(), but it does not wait. More... | |
uint8_t | OSMboxInit (OS_MBOX *pmbox, void *msg) |
This function is used to initialize an OS_MBOX structure. More... | |
uint8_t | OSMboxPost (OS_MBOX *pmbox, void *msg) |
This function posts a message to a Mail box. More... | |
void * | OSMboxPend (OS_MBOX *pmbox, uint16_t timeout, uint8_t *err) |
Wait timeout ticks for some other task to post to the Mailbox. More... | |
void * | OSMboxPendNoWait (OS_MBOX *pmbox, uint8_t *err) |
OSMboxPendNoWait() is identical to OSMboxPend(), but it does not wait. More... | |
uint8_t | OSQInit (OS_Q *pq, void **start, uint8_t size) |
A queue functions as a fixed size FIFO for communication between tasks. This function initializes an OS_Q structure. More... | |
uint8_t | OSQPost (OS_Q *pq, void *msg) |
This function posts a message to a Queue. More... | |
uint8_t | OSQPostFirst (OS_Q *pq, void *msg) |
This function posts a message like OSQPost , but posts the message at the head of the queue. More... | |
uint8_t | OSQPostUnique (OS_Q *pq, void *msg) |
This function posts a message like OSQPost , but only if the message isn't already in the queue The function performs a brute force check to see if the message is already in the queue. More... | |
uint8_t | OSQPostUniqueFirst (OS_Q *pq, void *msg) |
This function posts a message like OSQPostFirst , but only if the message isn't already in the queue The function performs a brute force check to see if the message is already in the queue. More... | |
void * | OSQPend (OS_Q *pq, uint16_t timeout, uint8_t *err) |
Wait timeout ticks for another task to post to the queue. More... | |
void * | OSQPendNoWait (OS_Q *pq, uint8_t *err) |
OSQPendNoWait() is identical to the OSQPend() function but it does not wait. More... | |
uint8_t | OSFifoInit (OS_FIFO *pFifo) |
Initialize a FIFO, which is used to pass structures from one task to another. More... | |
uint8_t | OSFifoPost (OS_FIFO *pFifo, OS_FIFO_EL *pToPost) |
This function posts to a FIFO. More... | |
uint8_t | OSFifoPostFirst (OS_FIFO *pFifo, OS_FIFO_EL *pToPost) |
This function is identical to OSFifoPost(), but the element posted is put at the beginning of the FIFO list. More... | |
OS_FIFO_EL * | OSFifoPend (OS_FIFO *pFifo, uint16_t timeout) |
This function pends on a FIFO. More... | |
OS_FIFO_EL * | OSFifoPendNoWait (OS_FIFO *pFifo) |
This function is identical to the OSFifoPen() function, but it does not wait. More... | |
uint8_t | OSCritInit (OS_CRIT *pCrit) |
This function initializes the critical section. More... | |
uint8_t | OSCritEnter (OS_CRIT *pCrit, uint16_t timeout) |
This function tries to enter or claim the critical section. More... | |
uint8_t | OSCritEnterNoWait (OS_CRIT *pCrit) |
This function tries to enter or claim the critical section. More... | |
uint8_t | OSCritLeave (OS_CRIT *pCrit) |
This function releases the critical section. More... | |
void | OSChangeTaskDly (uint16_t task_prio, uint32_t to_count) |
This function allows the User to modify the timeout delay for a task that is waiting. More... | |
void | OSDumpTCBStacks (void) |
This function dumps information about the UCOS stacks and tasks to stdout. This function is useful for debugging. Note: This function is only valid when NBRTOS_STACKCHECK is defined. More... | |
void | OSDumpTasks (void) |
This function dumps the state and call stack for every task to stdout. This function is useful for debugging. Note: This function is only valid when NBRTOS_STACKCHECK is defined. More... | |
void | ShowTaskList (void) |
This functions dumps the current RTOS task states to stdio. More... | |
The NetBurner Real-Time OS Group
#define OSSimpleTaskCreatewName | ( | x, | |
p, | |||
n | |||
) |
This macro functions the same as OSTaskCreatewName().
x | The address of the function where this task will start executing. |
p | The priority for this new task (OS_MAX_PRIOS is lowest priority and 1 is highest). Look in <nburn_install>/nbrtos/include/constants.h to see which priorities are used by the OS. |
n | The optional name of the task. |
#define WAIT_FOREVER 0 |
Can be used for parameters that have a 0 value
uint8_t OSChangePrio | ( | uint32_t | newp | ) |
This function changes the priority of the calling task.
Note: The uC/OS can only have one task at each priority level. Task priorities can range from 1 to OS_MAX_PRIOS, where OS_MAX_PRIOS is the lowest priority level and 1 is highest priority level. Priorities 1-4 and the NetBurner system priority levels are reserved as described below. The recommended user priority levels for your application are in the range of 46 to OS_MAX_PRIOS-1. This avoids any conflicts with network communications.
System priorities are defined in <nburn_install>/nbrtos/include/constants.h
for all platforms.
newp | The new priority of the calling task |
OS_NO_ERR | If successful |
OS_PRIO_EXIST | If the requested priority already exists |
|
inline |
This function allows the User to modify the timeout delay for a task that is waiting.
Warning: Use of this function is discouraged.
task_prio | The task's priority |
to_count | The new number of ticks to delay |
|
inline |
This function tries to enter or claim the critical section.
pCrit | A pointer to the critical section. |
timeout | How many time ticks do we want to wait for this critical section? Note: A timeout of 0 (zero) waits forever. |
|
inline |
This function tries to enter or claim the critical section.
pCrit | A pointer to the critical section. |
|
inline |
This function initializes the critical section.
pCrit | A pointer to the critical section. |
|
inline |
This function releases the critical section.
pCrit | A pointer to the critical section we want to leave/release. |
void OSDumpTasks | ( | void | ) |
This function dumps the state and call stack for every task to stdout. This function is useful for debugging. Note: This function is only valid when NBRTOS_STACKCHECK
is defined.
void OSDumpTCBStacks | ( | void | ) |
This function dumps information about the UCOS stacks and tasks to stdout. This function is useful for debugging. Note: This function is only valid when NBRTOS_STACKCHECK
is defined.
|
inline |
Initialize a FIFO, which is used to pass structures from one task to another.
pFifo | A pointer to an OS_FIFO structure. |
|
inline |
This function pends on a FIFO.
pFifo | A pointer to an OS_FIFO structure. |
timeout | The number of ticks to wait on the FIFO. |
|
inline |
This function is identical to the OSFifoPen() function, but it does not wait.
pFifo | A pointer to an OS_FIFO structure. |
|
inline |
This function posts to a FIFO.
pFifo | A pointer to an OS_FIFO structure. |
pToPost | A pointer to the user's structure cast as an OS_FIFO_EL to be posted to the FIFO. |
|
inline |
This function is identical to OSFifoPost(), but the element posted is put at the beginning of the FIFO list.
pFifo | A pointer to an OS_FIFO structure. |
pToPost | A pointer to the user's structure cast as an OS_FIFO_EL to be posted to the FIFO. |
|
inline |
This function clears the bits asserted in bits_to_clr
of an OS_FLAGS object pointed to by *flags..
flags | A pointer to the OS_FLAGS object to be configured. |
bits_to_clr | A bit or set of bits to be cleared. |
|
inline |
This function waits a number of time ticks specified by timeout
until all the flags indicated by bit_mask
are set.
flags | A pointer to the OS_FLAGS object with the desired flag bits. |
bit_mask | A bit or set of bits to wait on. |
timeout | Number of time ticks to wait for all specified flag bits to be set. |
OS_NO_ERR | If the flags condition is satisfied |
OS_TIMEOUT | If the timeout expired |
|
inline |
This function immediately checks to see if all the flag bits indicated by bit_mask
are set; it does not wait.
flags | A pointer to the OS_FLAGS object with the desired flag bits. |
bit_mask | A bit or set of bits to wait on. |
OS_NO_ERR | All flags indicated by bit_mask are set. |
OS_TIMEOUT | Not all of the flags indicated by bit_mask are set. |
|
inline |
This function waits a number of time ticks specified by timeout
until any of the flags indicated by bit_mask
are set.
flags | A pointer to the OS_FLAGS object with the desired flag bits. |
bit_mask | A bit or set of bits to wait on. |
timeout | Number of time ticks to wait for all specified flag bits to be set. |
OS_NO_ERR | At least one of the flag bits are set before timeout expires. |
OS_TIMEOUT | None of the flag bits are set before timeout expires. |
|
inline |
This function immediately checks to see if any of the flag bits indicated by bit_mask
are set; it does not wait.
flags | A pointer to the OS_FLAGS object with the desired flag bits. |
bit_mask | A bit or set of bits to wait on. |
OS_NO_ERR | At least one of the flags indicated by bit_mask are set. |
OS_TIMEOUT | None of the flags indicated by bit_mask are set. |
|
inline |
This function sets the corresponding bits asserted in bits_to_set
of an OS_FLAGS object pointed to by *flags
.
flags | A pointer to the OS_FLAGS object to be configured. |
bits_to_set | A bit or set of bits to be set. |
|
inline |
This function returns the current values of the flags stored in the OS_FLAGS object structure.
flags | A pointer to the OS_FLAGS object whose flag states are to be returned. |
void OSLock | ( | void | ) |
Calling the OSLock function will prevent the OS from changing tasks.
This is used to protect critical variables that must be accessed one task at a time. Use the OSUnlock function to release your lock. Important: You must call OSUnlock() once for each call to OSLock.
Warning: Do not keep a task locked for a long period of time, or the performance of the network subsystem will degrade, and eventually loose packets.
|
inline |
This function is used to initialize an OS_MBOX
structure.
pmbox | A pointer to the OS_MBOX structure to initialize. |
msg | The initial mail box message (NULL ) for none. |
|
inline |
Wait timeout ticks for some other task to post to the Mailbox.
pmbox | A pointer to the OS_MBOX structure. | |
timeout | The number of time ticks to wait. | |
[out] | err | A variable to receive the result code (OS_NO_ERR if successful or OS_TIMEOUT if it fails). |
NULL
if timed out.
|
inline |
OSMboxPendNoWait() is identical to OSMboxPend(), but it does not wait.
pmbox | A pointer to the OS_MBOX structure. | |
[out] | err | A variable to receive the result code (OS_NO_ERR if successful or OS_TIMEOUT if it fails). |
NULL
if it fails.
|
inline |
This function posts a message to a Mail box.
pmbox | A pointer to the OS_MBOX structure. |
msg | The message to post. |
|
inline |
A queue functions as a fixed size FIFO for communication between tasks. This function initializes an OS_Q
structure.
pq | A pointer to the OS_Q structure. |
start | A pointer to an array of (void *) pointers to hold queue messages. |
siz | The number of pointers in the Q data storage area. |
|
inline |
Wait timeout ticks for another task to post to the queue.
pq | A pointer to the OS_Q structure. | |
timeout | The number of ticks to wait. | |
[out] | err | A variable to receive the result code, either OS_NO_ERR on receiving a posted message, or OS_TIMEOUT on a timeout. |
NULL
if the function failed
|
inline |
OSQPendNoWait() is identical to the OSQPend() function but it does not wait.
pq | A pointer to the OS_Q structure. | |
[out] | err | A variable to receive the result code, either OS_NO_ERR on receiving a posted message, or OS_TIMEOUT on a timeout. |
NULL
if the function failed
|
inline |
This function posts a message to a Queue.
pq | A pointer to the OS_Q structure. |
msg | The message to be posted to the queue. |
|
inline |
This function posts a message like OSQPost
, but posts the message at the head of the queue.
pq | A pointer to the OS_Q structure. |
msg | The message to post at the head of the queue. |
|
inline |
This function posts a message like OSQPost
, but only if the message isn't already in the queue The function performs a brute force check to see if the message is already in the queue.
pq | A pointer to the OS_Q structure. |
msg | The message to post at the head of the queue. |
|
inline |
This function posts a message like OSQPostFirst
, but only if the message isn't already in the queue The function performs a brute force check to see if the message is already in the queue.
pq | A pointer to the OS_Q structure. |
msg | The message to post at the head of the queue. |
|
inline |
Initializes a semaphore.
psem | A pointer to the OS_SEM structure to initialize. |
value | The initial count value for the semaphore. |
|
inline |
Wait timeout ticks for the value of the semaphore to be non zero. Note: A timeout value of 0 (zero) waits forever.
psem | A pointer to the OS_SEM structure. |
timeout | The number of time ticks to wait |
|
inline |
OSSemPendNoWait() is identical to OSSemPend(), but it does not wait.
psem | A pointer to the OS_SEM structure |
|
inline |
Increases the value of the semaphore by one. Note: If any higher priority tasks were waiting on the semaphore - it releases them.
psem | A pointer to the OS_SEM structure. |
uint8_t OSTaskCreatewName | ( | void(*)(void *dptr) | task, |
void * | data, | ||
void * | pstktop, | ||
void * | pstkbot, | ||
uint8_t | prio, | ||
const char * | name | ||
) |
This function creates a new task.
You must allocate storage for the stack that this new task will use and it must be 4 byte aligned. Task priorities can range from 1 to OS_MAX_PRIOS
, where OS_MAX_PRIOS
is the lowest priority level and 1 is highest priority level. The recommended user priority levels for your application are in the range of 46 to OS_MAX_PRIOS-1. This avoids any conflicts with network communications. The maximum number of tasks your application can run is defined by OS_MAX_TASKS
. Both OS_MAX_PRIOS
and OS_MAX_TASKS
are defined in <nburn_install>/nbrtos/include/constants.h
.
Important:The uC/OS can only have one task at each priority.
dptr | The address of the function where this task will start executing. |
data | The data to pass to the task function. |
pstktop | The highest address of the stack space. |
pstkbot | The lowest address of the stack space. |
prio | The priority for this new task (OS_MAX_PRIOS is lowest priority and 1 is highest). Look in <nburn_install>/nbrtos/include/constants.h to see which priorities are used by the OS. |
name | The name of the task |
OS_NO_ERR | If successful |
OS_PRIO_EXIST | If the requested priority already exists |
void OSTaskDelete | ( | void | ) |
This function deletes the current calling task, but we do not recommend the use of this function because it can cause memory leaks.
The preferred method for terminating a task is to set a flag or semaphore that the task is listening for. The flag can then be set by an outside task, which enables the task to be deleted to free any resources and terminate gracefully by simply returning.
|
inline |
Delay the task until the specified value of the system timer ticks. The number of system ticks per second is defined by the constant: TICKS_PER_SECOND
in <nburn_install>/nbrtos/include/constants.h
. The default value is 20 ticks per second.
to_count | The number of system ticks to delay. |
void OSUnlock | ( | void | ) |
This function unlocks the OS.
Important: You must call OSUnlock() once for each call to OSLock().
void ShowTaskList | ( | void | ) |
This functions dumps the current RTOS task states to stdio.
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.