µC/OS-II - Acierta IT Solutions CON TODO/DCRABBIT_9.21...µC/OS-II Module 020-0059 Rev. A 2...
Transcript of µC/OS-II - Acierta IT Solutions CON TODO/DCRABBIT_9.21...µC/OS-II Module 020-0059 Rev. A 2...
µC/OS-IIµC/OS-II is a simple, clean, efficient, easy-to-use real-time operating system that runs on the Rab-bit microprocessor and is fully supported by the Dynamic C development environment.
µC/OS-II is capable of intertask communication and synchronization via the use of semaphores,mailboxes, and queues. User-definable system hooks are supplied for added system and configura-tion control during task creation, task deletion, context switches, and time ticks.
For more information on µC/OS-II, please refer to Jean J. Labrosse’s book, MicroC/OS-II, TheReal-Time Kernel (ISBN: 0-87930-543-6). The data structures (e.g. Event Control Block) refer-enced in the Dynamic C µC/OS-II function descriptions are fully explained in Labrosse’s book. Itcan be purchased at the Z-World store, www.zworld.com/store/home.html, or at http://www.ucos-ii.com/.
The Rabbit version of µC/OS-II has the new features and API changes available in version 2.51 ofµC/OS-II. The documentation for these changes will be in the /Samples/UCos-II directoryafter you copy and paste the “Lib” and “Samples” folders from the µC/OS-II module into yourworking Dynamic C directory. The file Newv251.pdf contains all of the features added sinceversion 2.00 and Relv251.pdf contains release notes for version 2.51.
The remainder of this document discusses the following:
• Dynamic C enhancements to µC/OS-II
• Tasking aware ISRs
• Dynamic C library reentrancy
• How to get a µC/OS-II application running
• TCP/IP compatibility
• API function descriptions
• Debugging tips
µC/OS-II Module 020-0059 Rev. A 1
1.0 Changes to µC/OS-IITo take full advantage of services provided by Dynamic C, minor changes have been made toµC/OS-II.
1.1 Ticks per SecondIn most implementations of µC/OS-II, OS_TICKS_PER_SEC informs the operating system ofthe rate at which OSTimeTick is called; this macro is used as a constant to match the rate of theperiodic interrupt. In µC/OS-II for the Rabbit, however, changing this macro will change the tickrate of the operating system set up during OSInit. Usually, a real-time operating system has atick rate of 10 Hz to 100 Hz, or 10–100 ticks per second. Since the periodic interrupt on the Rabbitoccurs at a rate of 2 kHz, it is recommended that the tick rate be a power of 2 (e.g., 16, 32, or 64).Keep in mind that the higher the tick rate, the more overhead the system will incur.
In the Rabbit version of µC/OS-II, the number of ticks per second defaults to 64. The actual num-ber of ticks per second may be slightly different than the desired ticks per second ifTicksPerSec does not evenly divide 2048.
Changing the default tick rate is done by simply defining OS_TICKS_PER_SEC to the desiredtick rate before calling OSInit(). E.g. to change the tick rate to 32 ticks per second:
#define OS_TICKS_PER_SEC 32...OSInit();...OSStart();
1.2 Task CreationIn a µC/OS-II application, stacks are declared as static arrays, and the address of either the top orbottom (depending on the CPU) of the stack is passed to OSTaskCreate. In a Rabbit-basedsystem, the Dynamic C development environment provides a superior stack allocation mechanismthat µC/OS-II incorporates. Rather than declaring stacks as static arrays, the number of stacks ofparticular sizes are declared, and when a task is created using either OSTaskCreate orOSTaskCreateExt, only the size of the stack is passed, not the memory address. This mecha-nism allows a large number of stacks to be defined without using up root RAM.
There are five macros located in ucos2.lib that define the number of stacks needed of five dif-ferent sizes. In order to have three 256 byte stacks, one 512 byte stack, two 1024 byte stacks, one2048 byte stack, and no 4096 byte stacks, the following macro definitions would be used:
#define STACK_CNT_256 3 // number of 256 byte stacks#define STACK_CNT_512 1 // number of 512 byte stacks#define STACK_CNT_1K 2 // number of 1K stacks#define STACK_CNT_2K 1 // number of 2K stacks#define STACK_CNT_4K 0 // number of 4K stacks
µC/OS-II Module 020-0059 Rev. A 2
These macros can be placed into each µC/OS-II application so that the number of each size stackcan be customized based on the needs of the application. Suppose that an application needs 5tasks, and each task has a consecutively larger stack. The macros and calls to OSTaskCreatewould look as follows
#define STACK_CNT_256 2 // number of 256 byte stacks#define STACK_CNT_512 2 // number of 512 byte stacks#define STACK_CNT_1K 1 // number of 1K stacks#define STACK_CNT_2K 1 // number of 2K stacks#define STACK_CNT_4K 1 // number of 4K stacks
OSTaskCreate(task1, NULL, 256, 0);OSTaskCreate(task2, NULL, 512, 1);OSTaskCreate(task3, NULL, 1024, 2);OSTaskCreate(task4, NULL, 2048, 3);OSTaskCreate(task5, NULL, 4096, 4);
Note that STACK_CNT_256 is set to 2 instead of 1. µC/OS-II always creates an idle task whichruns when no other tasks are in the ready state. Note also that there are two 512 byte stacks insteadof one. This is because the program is given a 512 byte stack. If the application utilizes theµC/OS-II statistics task, then the number of 512 byte stacks would have to be set to 3. (Statistictask creation can be enabled and disabled via the macro OS_TASK_STAT_EN which is located inucos2.lib). If only 6 stacks were declared, one of the calls to OSTaskCreate would fail.
If an application uses OSTaskCreateExt, which enables stack checking and allows an exten-sion of the Task Control Block, fewer parameters are needed in the Rabbit version of µC/OS-II.Using the macros in the example above, the tasks would be created as follows:
OSTaskCreateExt(task1, NULL, 0, 0, 256, NULL, OS_TASK_OPT_STK_CHK |OS_TASK_OPT_STK_CLR);
OSTaskCreateExt(task2, NULL, 1, 1, 512, NULL, OS_TASK_OPT_STK_CHK |OS_TASK_OPT_STK_CLR);
OSTaskCreateExt(task3, NULL, 2, 2, 1024, NULL, OS_TASK_OPT_STK_CHK |OS_TASK_OPT_STK_CLR);
OSTaskCreateExt(task4, NULL, 3, 3, 2048, NULL, OS_TASK_OPT_STK_CHK |OS_TASK_OPT_STK_CLR);
OSTaskCreateExt(task5, NULL, 4, 4, 4096, NULL, OS_TASK_OPT_STK_CHK |OS_TASK_OPT_STK_CLR);
1.3 RestrictionsAt the time of this writing, µC/OS-II for Dynamic C is not compatible with the use of slice state-ments. Also, see the function description for OSTimeTickHook() for important informationabout preserving registers if that stub function is replaced by a user-defined function.
Due to Dynamic C's stack allocation scheme, special care should be used when posting messagesto either a mailbox or a queue. A message is simply a void pointer, allowing the application todetermine its meaning. Since tasks can have their stacks in different segments, auto pointersdeclared on the stack of the task posting the message should not be used since the pointer may beinvalid in another task with a different stack segment.
µC/OS-II Module 020-0059 Rev. A 3
2.0 Tasking Aware Interrupt Service Routines (TA-ISR)Special care must be taken when writing an interrupt service routine (ISR) that will be used in con-junction with µC/OS-II so that µC/OS-II scheduling will be performed at the proper time.
2.1 Interrupt Priority LevelsµC/OS-II for the Rabbit reserves interrupt priority levels 2 and 3 for interrupts outside of the ker-nel. Since the kernel is unaware of interrupts above priority level 1, interrupt service routines forinterrupts that occur at interrupt priority levels 2 and 3 should not be written to be tasking aware.Also, a µC/OS-II application should only disable interrupts by setting the interrupt priority level to1, and should never raise the interrupt priority level above 1.
2.2 Possible ISR ScenariosThere are several different scenarios that must be considered when writing an ISR for use withµC/OS-II. Depending on the use of the ISR, it may or may not have to be written so that it is task-ing aware. Consider the scenario in the Figure below. In this situation, the ISR for Interrupt X doesnot have to be tasking aware since it does not re-enable interrupts before completion and it doesnot post to a semaphore, mailbox, or queue.
Figure 1. Type 1 ISR
If, however, an ISR needs to signal a task to the ready state, then the ISR must be tasking aware. Inthe example in the Figure below, the TA-ISR increments the interrupt nesting counter, does thework necessary for the ISR, readies a higher priority task, decrements the nesting count, andreturns to the higher priority task.
Task 1
Task 1
Interrupt X
Interrupt X ISR
ipres
µC/OS-II Module 020-0059 Rev. A 4
Figure 2. Type 2 ISR
It may seem as though the ISR in this Figure does not have to increment and decrement the nestingcount. This is, however, very important. If the ISR for Interrupt X is called during an ISR that re-enables interrupts before completion, scheduling should not be performed when Interrupt X com-pletes; scheduling should instead be deferred until the least nested ISR completes. The next Figureshows an example of this situation.
Figure 3. Type 2 ISR Nested Inside Type 3 ISR
Task 2
Task 1
Interrupt X
Interrupt X TA-ISR
Nesting = 1Task 1 is readiedNesting = 0ipres
Task 2
Task 1
Interrupt Z TA-ISR
Nesting = 2Task 1 is readiedNesting = 1ipres
Interrupt X TA-ISR
Nesting = 1Do critical codeipresInterrupt X
Finish ISRNesting = 0
Interrupt Z
µC/OS-II Module 020-0059 Rev. A 5
As can be seen here, although the ISR for interrupt Z does not signal any tasks by posting to asemaphore, mailbox, or queue, it must increment and decrement the interrupt nesting count since itre-enables interrupts (ipres) prior to finishing all of its work.
2.3 General Layout of a TA-ISRA TA-ISR is just like a standard ISR except that it does some extra checking and house-keeping.The following table summarizes when to use a TA-ISR.
The following Figure shows the logical flow of a TA-ISR.
Table 18-1. Use of TA-ISR
µC/OS-II Application
Type 11
1. Type 1—Leaves interrupts disabled and does not signal task to ready state
Type 22
2. Type 2—Leaves interrupts disabled and signals task to ready state
Type 33
3. Type 3—Reenables interrupts before completion
TA-ISR Required? No Yes Yes
µC/OS-II Module 020-0059 Rev. A 6
Figure 4. Logical Flow of a TA-ISR
Save registers used by TA-ISR
Reenable interrupts (optional)
Do work necessary for interrupt
Decrement Nesting Count
Call OSIntExit
Clear interrupt source
Increment nesting count
Is Nesting == 0 ?
Restore Registers used by TA-ISR
Return from interrupt
Is switch pending ?
Switch to new task
Yes
Yes
No
No
µC/OS-II Module 020-0059 Rev. A 7
2.3.1 Sample Code for a TA-ISRFortunately, the Rabbit BIOS and libraries provide all of the necessary flags to make TA-ISRswork. With the code found in Listing 1, minimal work is needed to make a TA-ISR functioncorrectly with µC/OS-II. TA-ISRs allow µC/OS-II the ability to have ISRs that communicate withtasks as well as the ability to let ISRs nest, thereby reducing interrupt latency.
Just like a standard ISR, the first thing a TA-ISR does is to save the registers that it is going to use(1). Once the registers are saved, the interrupt source is cleared (2) and the nesting counter isincremented (3). Note that bios_intnesting is a global interrupt nesting counter provided inthe Dynamic C libraries specifically for tracking the interrupt nesting level. If an ipres instruc-tion is executed (4) other interrupts can occur before this ISR is completed, making it necessaryfor this ISR to be a TA-ISR. If it is possible for the ISR to execute before µC/OS-II has been fullyinitialized and started multi-tasking, a check should be made (5) to insure that µC/OS-II is in aknown state, especially if the TA-ISR signals a task to the ready state (6). After the TA-ISR hasdone its necessary work (which may include making a higher priority task than is currently run-ning ready to run), OSIntExit must be called (7). This µC/OS-II function determines the high-est priority task ready to run, sets it as the currently running task, and sets the global flagbios_swpend if a context switch needs to take place. Interrupts are disabled since a contextswitch is treated as a critical section (8). If the TA-ISR decrements the nesting counter and thecount does not go to zero, then the nesting level is saved in bios_intnesting (9), the regis-ters used by the TA-ISR are restored, interrupts are re-enabled (if not already done in (4)), and theTA-ISR returns (12). However, if decrementing the nesting counter in (9) causes the counter tobecome zero, then bios_swpend must be checked to see if a context switch needs to occur (10).If a context switch is not pending, then the nesting level is set (9) and the TA-ISR exits (12). If acontext switch is pending, then the remaining context of the previous task is saved and a long call,which insures that the xpc is saved and restored properly, is made to bios_intexit (11).bios_intexit is responsible for switching to the stack of the task that is now ready to run andexecuting a long call to switch to the new task. The remainder of (11) is executed when a previ-ously preempted task is allowed to run again.
Listing 1
#asmtaskaware_isr::
push af ;push regs needed by isr (1)push hl ;clear interrupt source (2)ld hl,bios_intnesting ;increase the nesting count (3)inc (hl); ipres (optional) (4); do processing necessary for interruptld a,(OSRunning) ;MCOS multitasking yet? (5)or ajr z,taisr_decnesting
; possibly signal task to become ready (6)call OSIntExit ;sets bios_swpend if higher
; prio ready (7)
µC/OS-II Module 020-0059 Rev. A 8
taisr_decnesting:push ip (8)ipset 1
ld hl,bios_intnesting ; nesting counter == 1?dec (hl) (9)jr nz,taisr_noswitch
ld a,(bios_swpend) ; switch pending? (10)or ajr z,taisr_noswitch
push de (11)push bcex af,af’push afexxpush hlpush depush bcpush iy
lcall bios_intexit
pop iypop bcpop depop hlexxpop afex af,af’pop bcpop de
taisr_noswitch:pop ip
taisr_done:pop hl (12)pop afipresret
#endasm
µC/OS-II Module 020-0059 Rev. A 9
3.0 Library ReentrancyWhen writing a µC/OS-II application, it is important to know which Dynamic C library functionsare non-reentrant. If a function is non-reentrant, then only one task may access the function at atime, and access to the function should be controlled with a µC/OS-II semaphore. The following isa list of Dynamic C functions that are non-reentrant.
The Dynamic C serial port functions (RS232.LIB functions) should be used in a restricted man-ner with µC/OS-II. Two tasks can use the same port as long as both are not reading, or both are notwriting; i.e., one task can read from serial port X and another task can write to serial port X at thesame time without conflict.
Library Non-reentrant Functions
MATH.LIB randg, randb, rand
RS232.LIB All
RTCLOCK.LIB write_rtc, tm_wr
STDIO.LIB kbhit, getchar, gets, getswf, selectkey
STRING.LIB atof1, atoi1, strtok
1. reentrant but sets the global _xtoxErr flag
SYS.LIBclockDoublerOn, clockDoublerOff, useMainOsc,useClockDivider, use32kHzOsc
VDRIVER.LIB VdGetFreeWd, VdReleaseWd
XMEM.LIB WriteFlash
JRIO.LIB digOut, digOn, digOff, jrioInit, anaIn, anaOut, cof_anaIn
JR485.LIB All
µC/OS-II Module 020-0059 Rev. A 10
4.0 How to Get a µC/OS-II Application RunningµC/OS-II is a highly configureable, real-time operating system. It can be customized using asmany or as few of the operating system’s features as needed. This section outlines:
• The configuration constants used in µC/OS-II
• How to override the default configuration supplied in UCOS2.LIB
• The necessary steps to get an application running
It is assumed that the reader has a familiarity with µC/OS-II or has a µC/OS-II reference(MicroC/OS-II, The Real-Time Kernel by Jean J. Labrosse is highly recommended).
4.1 Default ConfigurationµC/OS-II usually relies on the include file os_cfg.h to get values for the configuration con-stants. In the Dynamic C implementation of µC/OS-II, these constants, along with their defaultvalues, are in os_cfg.lib. A default stack configuration is also supplied in os_cfg.lib.µC/OS-II for the Rabbit uses a more intelligent stack allocation scheme than other µC/OS-IIimplementations to take better advantage of unused memory.
The default configuration allows up to 10 normally created application tasks running at 64 ticksper second. Each task has a 512-byte stack. There are 2 queues specified, and 10 events. An eventis a queue, mailbox or semaphore. You can define any combination of these three for a total of 10.If you want more than 2 queues, however, you must change the default value of OS_MAX_QS.
Some of the default configuration constants are:
OS_MAX_EVENTS Max number of events (semaphores, queues, mail-boxes)Default is 10
OS_MAX_TASKS Maximum number of tasks (less stat and idle tasks)Default is 10
OS_MAX_QS Max number of queues in systemDefault is 2
OS_MAX_MEM_PART Max number of memory partitionsDefault is 1
OS_TASK_CREATE_EN Enable normal task creationDefault is 1
OS_TASK_CREATE_EXT_EN Disable extended task creationDefault is 0
OS_TASK_DEL_EN Disable task deletionDefault is 0
OS_TASK_STAT_EN Disable statistics task creationDefault is 0
OS_Q_EN Enable queue usageDefault is 1
µC/OS-II Module 020-0059 Rev. A 11
OS_MEM_EN Disable memory managerDefault is 0
OS_MBOX_EN Enable mailboxesDefault is 1
OS_SEM_EN Enable semaphoresDefault is 1
OS_TICKS_PER_SEC Number of ticks in one secondDefault is 64
STACK_CNT_256 Number of 256 byte stacks (idle task stack)Default is 1
STACK_CNT_512 Number of 512-byte stacks(task stacks + initial program stack)Default is OS_MAX_TASKS+1 (11)
If a particular portion of µC/OS-II is disabled, the code for that portion will not be compiled, mak-ing the overall size of the operating system smaller. Take advantage of this feature by customizingµC/OS-II based on the needs of each application.
4.2 Custom ConfigurationIn order to customize µC/OS-II by enabling and disabling components of the operating system,simply redefine the configuration constants as necessary for the application.
#define OS_MAX_EVENTS 2#define OS_MAX_TASKS 20#define OS_MAX_QS 1#define OS_MAX_MEM_PART 15#define OS_TASK_STAT_EN 1#define OS_Q_EN 0#define OS_MEM_EN 1#define OS_MBOX_EN 0#define OS_TICKS_PER_SEC 64
If a custom stack configuration is needed also, define the necessary macros for the counts of thedifferent stack sizes needed by the application.
#define STACK_CNT_256 1 // idle task stack#define STACK_CNT_512 2 // initial program + stat task stack#define STACK_CNT_1K 10 // task stacks#define STACK_CNT_2K 10 // number of 2K stacks
In the application code, follow the µC/OS-II and stack configuration constants with a #use“ucos2.lib” statement. This ensures that the definitions supplied outside of the library areused, rather than the defaults in the library.
This configuration uses 20 tasks, two semaphores, up to 15 memory partitions that the memorymanager will control, and makes use of the statistics task. Note that the configuration constants fortask creation, task deletion, and semaphores are not defined, as the library defaults will suffice.
µC/OS-II Module 020-0059 Rev. A 12
Also note that 10 of the application tasks will each have a 1024 byte stack, 10 will each have a2048 byte stack, and an extra stack is declared for the statistics task.
4.3 ExamplesThe following sample programs demonstrate the use of the default configuration supplied inUCOS2.LIB and a custom configuration which overrides the defaults.
Example 1In this application, 10 tasks are created and one semaphore is created. Each task pends on thesemaphore, gets a random number, posts to the semaphore, displays its random number, andfinally delays itself for 3 seconds.
Looking at the code for this short application, there are several things to note. First, since µC/OS-II and slice statements are mutually exclusive (both rely on the periodic interrupt for a “heart-beat”), #use “ucos2.lib” must be included in every µC/OS-II application (1). In order foreach of the tasks to have access to the random number generator semaphore, it is declared as a glo-bal variable (2). In most cases, all mailboxes, queues, and semaphores will be declared with globalscope. Next, OSInit() must be called before any other µC/OS-II function to ensure that theoperating system is properly initialized (3). Before µC/OS-II can begin running, at least one appli-cation task must be created. In this application, all tasks are created before the operating systembegins running (4). It is perfectly acceptable for tasks to create other tasks. Next, the semaphoreeach task uses is created (5). Once all of the initialization is done, OSStart() is called to startµC/OS-II running (6). In the code that each of the tasks run, it is important to note the variabledeclarations. Each task runs as an infinite loop and once this application is started, µC/OS-II willrun indefinitely.
µC/OS-II Module 020-0059 Rev. A 13
// 1. Explicitly use µC/OS-II library#use "ucos2.lib"
void RandomNumberTask(void *pdata);
// 2. Declare semaphore global so all tasks have accessOS_EVENT* RandomSem;
void main(){int i;
// 3. Initialize OS internalsOSInit();
for(i = 0; i < OS_MAX_TASKS; i++)
// 4. Create each of the system tasksOSTaskCreate(RandomNumberTask, NULL, 512, i);
// 5. semaphore to control access to random number generatorRandomSem = OSSemCreate(1);
// 6. Begin multitaskingOSStart();
}
void RandomNumberTask(void *pdata){
OS_TCB data;INT8U err;INT16U RNum;
OSTaskQuery(OS_PRIO_SELF, &data);while(1){
// Rand is not reentrant, so access must be controlled via a semaphore.OSSemPend(RandomSem, 0, &err);RNum = (int)(rand() * 100);OSSemPost(RandomSem);printf("Task%d's random #: %d\n",data.OSTCBPrio,RNum);
// Wait 3 seconds in order to view output from each task.OSTimeDlySec(3);
}}
µC/OS-II Module 020-0059 Rev. A 14
Example 2This application runs exactly the same code as Example 1, except that each of the tasks are createdwith 1024 byte stacks. The main difference between the two is the configuration of µC/OS-II.
First, each configuration constant that differs from the library default is defined. The configurationin this example differs from the default in that it allows only two events (the minimum neededwhen using only one semaphore), 20 tasks, no queues, no mailboxes, and the system tick rate is setto 32 ticks per second (1). Next, since this application uses tasks with 1024 byte stacks, it is neces-sary to define the configuration constants differently than the library default (2). Notice that one512 byte stack is declared. Every Dynamic C program starts with an initial stack, and definingSTACK_CNT_512 is crucial to ensure that the application has a stack to use during initializationand before multi-tasking begins. Finally ucos2.lib is explicitly used (3). This ensures that thedefinitions in (1 and 2) are used rather than the library defaults. The last step in initialization is toset the number of ticks per second via OSSetTicksPerSec (4).
The rest of this application is identical to example 1 and is explained in the previous section.
// 1. Define necessary configuration constants for uC/OS-II#define OS_MAX_EVENTS 2#define OS_MAX_TASKS 20#define OS_MAX_QS 0#define OS_Q_EN 0#define OS_MBOX_EN 0#define OS_TICKS_PER_SEC 32
// 2. Define necessary stack configuration constants#define STACK_CNT_512 1 // initial program stack#define STACK_CNT_1K OS_MAX_TASKS // task stacks
// 3. This ensures that the above definitions are used#use "ucos2.lib"
void RandomNumberTask(void *pdata);
// Declare semaphore global so all tasks have accessOS_EVENT* RandomSem;
void main(){int i;
// Initialize OS internalsOSInit();
for(i = 0; i < OS_MAX_TASKS; i++){
// Create each of the system tasksOSTaskCreate(RandomNumberTask, NULL, 1024, i);
}// semaphore to control access to random number generatorRandomSem = OSSemCreate(1);
// 4. Set number of system ticks per secondOSSetTicksPerSec(OS_TICKS_PER_SEC);
// Begin multi-taskingOSStart();
}
µC/OS-II Module 020-0059 Rev. A 15
void RandomNumberTask(void *pdata){
// Declare as auto to ensure reentrancy.auto OS_TCB data;auto INT8U err;auto INT16U RNum;
OSTaskQuery(OS_PRIO_SELF, &data);while(1){
// Rand is not reentrant, so access must be controlled via a semaphore.OSSemPend(RandomSem, 0, &err);RNum = (int)(rand() * 100);OSSemPost(RandomSem);
printf("Task%02d's random #: %d\n",data.OSTCBPrio,RNum);
// Wait 3 seconds in order to view output from each task.OSTimeDlySec(3);
}}
5.0 Compatibility with TCP/IPThe TCP/IP stack is reentrant and may be used with the µC/OS real-time kernel. The line
#use ucos2.lib
must appear before the line
#use dcrtcp.lib
A call to OSInit() must be made before calling sock_init().
5.1 Socket LocksEach socket used in a µC/OS-II application program has an associated socket lock. Each socketlock uses one semaphore of type OS_EVENT. Therefore, the macro MAX_OS_EVENTS must takeinto account each of the socket locks, plus any events that the application program may be using(semaphores, queues, mailboxes, event flags, or mutexes).
Determining OS_MAX_EVENTS may get a little tricky, but it isn't too bad if you know what yourprogram is doing. Since MAX_SOCKET_LOCKS is defined as:
#define MAX_SOCKET_LOCKS (MAX_TCP_SOCKET_BUFFERS +MAX_UDP_SOCKET_BUFFERS)
µC/OS-II Module 020-0059 Rev. A 16
OS_MAX_EVENTS may be defined as:
#define OS_MAX_EVENTS MAX_TCP_SOCKET_BUFFERS +MAX_UDP_SOCKET_BUFFERS + 2 + z
The constant “2” is included for the two global locks used by TCP/IP, and “z” is the number ofOS_EVENTS (semaphores, queues, mailboxes, event flags, or mutexes) required by the program.
If either MAX_TCP_SOCKET_BUFFERS or MAX_UDP_SOCKET_BUFFERS is not defined bythe application program prior to the #use statements for ucos.lib and dcrtcp.lib defaultvalues will be assigned.
If MAX_TCP_SOCKET_BUFFERS is not defined in the application program, it will be definedas MAX_SOCKETS. If, however, MAX_SOCKETS is not defined in the application program,MAX_TCP_SOCKET_BUFFERS will be 4.
If MAX_UDP_SOCKET_BUFFERS is not defined in the application program, it will be defined as1 if USE_DHCP is defined, or 0 otherwise.
For more information regarding TCP/IP, please see the Dynamic C TCP/IP User’s Manual, avail-able online at zworld.com or rabbitsemiconductor.com.
6.0 Debugging TipsSingle stepping may be limited to the currently running task by using <F8> (Step over). If the taskis suspended, single stepping will also be suspended. When the task is put back in a running state,single stepping will continue at the statement following the statement that suspended execution ofthe task.
Pressing <F7> (Trace into) at a statement that suspends execution of the current task will cause theprogram to step into the next active task that has debug information. It may be useful to put awatch on the global variable OSPrioCur to see which task is currently running.
For example, if the current task is going to call OSSemPend() on a semaphore that is not in thesignaled state, the task will be suspended and other tasks will run. If <F8> is pressed at the state-ment that calls OSSemPend(), the debugger will not single step in the other running tasks thathave debug information; single stepping will continue at the statement following the call toOSSemPend(). If <F7> is pressed at the statement that calls OSSemPend() instead of <F8>,the debugger will single step in the next task with debug information that is put into the runningstate.
µC/OS-II Module 020-0059 Rev. A 17
7.0 API FunctionsThe rest of this document describes the API functions available with the µC/OS-II module.
OS_ENTER_CRITICAL
void OS_ENTER_CRITICAL();
DESCRIPTION
Enter a critical section. Interrupts will be disabled until OS_EXIT_CRITICAL() iscalled. Task switching is disabled. This function must be used with great care, sincemisuse can greatly increase the latency of your application. Note that nestingOS_ENTER_CRITICAL() calls will work correctly.
LIBRARY
UCOS2.LIB
OS_EXIT_CRITICAL
void OS_EXIT_CRITICAL();
DESCRIPTION
Exit a critical section. If the corresponding previous OS_ENTER_CRITICAL() calldisabled interrupts (that is, interrupts were not already disabled), then interrupts will beenabled. Otherwise, interrupts will remain disabled. Hence, nesting calls toOS_ENTER_CRITICAL() will work correctly.
LIBRARY
UCOS2.LIB
µC/OS-II Module 020-0059 Rev. A 18
OSFlagAccept
OS_FLAGS OSFlagAccept (OS_FLAG_GRP *pgrp, OS_FLAGS flags, INT8Uwait_type, INT8U *err);
DESCRIPTION
This function is called to check the status of a combination of bits to be set or clearedin an event flag group. Your application can check for ANY bit to be set/cleared or ALLbits to be set/cleared.
This call does not block if the desired flags are not present.
PARAMETERS
pgrp Pointer to the desired event flag group.
flags Bit pattern indicating which bit(s) (i.e. flags) you wish to check.E.g. if your application wants to wait for bits 0 and 1 then flagsshould be 0x03.
wait_type Specifies whether you are checking for ALL bits to be set/clearedor ANY of the bits to be set/cleared. You can specify the followingargument:
• OS_FLAG_WAIT_CLR_ALL - You will check ALL bits inflags to be clear (0)
• OS_FLAG_WAIT_CLR_ANY - You will check ANY bit inflags to be clear (0)
• OS_FLAG_WAIT_SET_ALL - You will check ALL bits inflags to be set (1)
• OS_FLAG_WAIT_SET_ANY - You will check ANY bit inflags to be set (1)
Note: Add OS_FLAG_CONSUME if you want the event flagto be consumed by the call. Example, to wait for any flag in agroup AND then clear the flags that are present, set thewait_type parameter to:
OS_FLAG_WAIT_SET_ANY + OS_FLAG_CONSUME
µC/OS-II Module 020-0059 Rev. A 19
OSFlagAccept (continued)
err Pointer to an error code. Possible values are:
• OS_NO_ERR - No error• OS_ERR_EVENT_TYPE - Not pointing to an event flag
group• OS_FLAG_ERR_WAIT_TYPE - Proper wait_type ar-
gument not specified.• OS_FLAG_INVALID_PGRP - NULL pointer passed in-
stead of the event flag group handle.• OS_FLAG_ERR_NOT_RDY - Flags not available.
RETURN VALUE
The state of the flags in the event flag group.
LIBRARY
OS_FLAG.C
OSFlagCreate
OS_FLAG_GRP *OSFlagCreate (OS_FLAGS flags, INT8U *err);
DESCRIPTION
This function is called to create an event flag group.
PARAMETERS
flags Contains the initial value to store in the event flag group.
err Pointer to an error code that will be returned to your application:
• OS_NO_ERR - The call was successful.• OS_ERR_CREATE_ISR - Attempt made to create an
Event Flag from an ISR.• OS_FLAG_GRP_DEPLETED - There are no more event
flag groups
RETURN VALUE
A pointer to an event flag group or a NULL pointer if no more groups are available.
LIBRARY
OS_FLAG.C
µC/OS-II Module 020-0059 Rev. A 20
OSFlagDel
OS_FLAG_GRP *OSFlagDel (OS_FLAG_GRP *pgrp, INT8U opt, INT8U*err);
DESCRIPTION
This function deletes an event flag group and readies all tasks pending on the event flaggroup. Note that:
• This function must be used with care. Tasks that would normally expect thepresence of the event flag group must check the return code ofOSFlagAccept() and OSFlagPend().
• This call can potentially disable interrupts for a long time. The interrupt disabletime is directly proportional to the number of tasks waiting on the event flaggroup.
PARAMETERS
pgrp Pointer to the desired event flag group.
opt May be one of the following delete options:
• OS_DEL_NO_PEND - Deletes the event flag group only ifno task pending
• OS_DEL_ALWAYS - Deletes the event flag group even iftasks are waiting. In this case, all the tasks pending will bereadied..
err Pointer to an error code. May be one of the following values:
• OS_NO_ERR - Success, the event flag group was deleted• OS_ERR_DEL_ISR - If you attempted to delete the event
flag group from an ISR• OS_FLAG_INVALID_PGRP - If pgrp is a NULL pointer.• OS_ERR_EVENT_TYPE - You are not pointing to an event
flag group• OS_ERR_EVENT_TYPE - If you didn't pass a pointer to an
event flag group• OS_ERR_INVALID_OPT - Invalid option was specified• OS_ERR_TASK_WAITING - One or more tasks were wait-
ing on the event flag group.
RETURN VALUE
pevent Error.
(OS_EVENT *)0 Semaphore was successfully deleted.
LIBRARY
OS_FLAG.C
µC/OS-II Module 020-0059 Rev. A 21
OSFlagPend
OS_FLAGS OSFlagPend (OS_FLAG_GRP *pgrp, OS_FLAGS flags, INT8Uwait_type, INT16U timeout, INT8U *err);
DESCRIPTION
This function is called to wait for a combination of bits to be set in an event flag group.Your application can wait for ANY bit to be set or ALL bits to be set.
PARAMETERS
pgrp Pointer to the desired event flag group.
flags Bit pattern indicating which bit(s) (i.e. flags) you wish to wait for.E.g. if your application wants to wait for bits 0 and 1 then flagsshould be 0x03.
wait_type Specifies whether you want ALL bits to be set or ANY of the bitsto be set. You can specify the following argument:
• OS_FLAG_WAIT_CLR_ALL - You will wait for ALL bitsin mask to be clear (0)
• OS_FLAG_WAIT_SET_ALL - You will wait for ALL bitsin mask to be set (1)
• OS_FLAG_WAIT_CLR_ANY - You will wait for ANY bitin mask to be clear (0)
• OS_FLAG_WAIT_SET_ANY - You will wait for ANY bitin mask to be set (1)
Note: Add OS_FLAG_CONSUME if you want the eventflag to be consumed by the call. E.g., to wait for any flag in agroup AND then clear the flags that are present, set thewait_type parameter to:
OS_FLAG_WAIT_SET_ANY + OS_FLAG_CONSUME
timeout An optional timeout (in clock ticks) that your task will wait for thedesired bit combination. If you specify 0, however, your task willwait forever at the specified event flag group or, until a messagearrives.
µC/OS-II Module 020-0059 Rev. A 22
OSFlagPend (continued)
err Pointer to an error code. Possible values are:
OS_NO_ERR - The desired bits have been set within the specifiedtime-out.
OS_ERR_PEND_ISR - If you tried to PEND from an ISR.
OS_FLAG_INVALID_PGRP - If pgrp is a NULL pointer.
OS_ERR_EVENT_TYPE - You are not pointing to an event flaggroup
OS_TIMEOUT - The bit(s) have not been set in the specified time-out.
OS_FLAG_ERR_WAIT_TYPE - You didn't specify a properwait_type argument.
RETURN VALUE
The new state of the flags in the event flag group when the task is resumed or, 0 if atimeout or an error occurred.
LIBRARY
OS_FLAG.C
µC/OS-II Module 020-0059 Rev. A 23
OSFlagPost
OS_FLAGS OSFlagPost (OS_FLAG_GRP *pgrp, OS_FLAGS flags, INT8Uopt, INT8U *err);
DESCRIPTION
This function is called to set or clear some bits in an event flag group. The bits to set orclear are specified by a bitmask. Warnings:
• The execution time of this function depends on the number of tasks waiting onthe event flag group.
• The amount of time interrupts are DISABLED depends on the number of taskswaiting on the event flag group.
PARAMETERS
pgrp Pointer to the desired event flag group.
flags If opt (see below) is OS_FLAG_SET, each bit that is set inflags will set the corresponding bit in the event flag group. E.g.,to set bits 0, 4 and 5 you would set flags to:
0x31 (note, bit 0 is least significant bit)
If opt (see below) is OS_FLAG_CLR, each bit that is set in flagswill CLEAR the corresponding bit in the event flag group. E.g., toclear bits 0, 4 and 5 you would specify flags as:
0x31 (note, bit 0 is least significant bit)
opt Indicates whether the flags will be:
set (OS_FLAG_SET), or cleared (OS_FLAG_CLR)
err Pointer to an error code. Valid values are:
• OS_NO_ERR - The call was successful.• OS_FLAG_INVALID_PGRP - NULL pointer passed.• OS_ERR_EVENT_TYPE - Not pointing to an event flag
group• OS_FLAG_INVALID_OPT - Invalid option specified.
RETURN VALUE
The new value of the event flags bits that are still set.
LIBRARY
OS_FLAG.C
µC/OS-II Module 020-0059 Rev. A 24
OSFlagQuery
OS_FLAGS OSFlagQuery (OS_FLAG_GRP *pgrp, INT8U *err);
DESCRIPTION
This function is used to check the value of the event flag group.
PARAMETERS
pgrp Pointer to the desired event flag group.
err Pointer to an error code returned to the called:
• OS_NO_ERR - The call was successful• OS_FLAG_INVALID_PGRP - NULL pointer passed.• OS_ERR_EVENT_TYPE - Not pointing to an event flag
group
RETURN VALUE
The current value of the event flag group.
LIBRARY
OS_FLAG.C
OSInit
void OSInit(void);
DESCRIPTION
Initializes µC/OS-II data; must be called before any other µC/OS-II functions arecalled.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTaskCreate, OSTaskCreateExt, OSStart
µC/OS-II Module 020-0059 Rev. A 25
OSMboxAccept
void *OSMboxAccept (OS_EVENT *pevent);
DESCRIPTION
Checks the mailbox to see if a message is available. Unlike OSMboxPend(),OSMboxAccept() does not suspend the calling task if a message is not available.
PARAMETERS
pevent Pointer to the mailbox’s event control block.
RETURN VALUE
!= (void *)0 This is the message in the mailbox if one is available. Themailbox is cleared so the next time OSMboxAccept() iscalled, the mailbox will be empty.
== (void *)0 The mailbox is empty, or pevent is a NULL pointer, oryou didn't pass the proper event pointer.
LIBRARY
OS_MBOX.C
SEE ALSO
OSMboxCreate, OSMboxPend, OSMboxPost, OSMboxQuery
µC/OS-II Module 020-0059 Rev. A 26
OSMboxCreate
OS_EVENT *OSMboxCreate (void *msg);
DESCRIPTION
Creates a message mailbox if event control blocks are available.
PARAMETERS
msg Pointer to a message to put in the mailbox. If this value is set to theNULL pointer (i.e., (void *)0) then the mailbox will be consid-ered empty.
RETURN VALUE
!= (void *)0 A pointer to the event control clock (OS_EVENT) associat-ed with the created mailbox.
== (void *)0 No event control blocks were available.
LIBRARY
OS_MBOX.C
SEE ALSO
OSMboxAccept, OSMboxPend, OSMboxPost, OSMboxQuery
µC/OS-II Module 020-0059 Rev. A 27
OSMboxDel
OS_EVENT *OSMboxDel (OS_EVENT *pevent, INT8U opt, INT8U *err);
DESCRIPTION
This function deletes a mailbox and readies all tasks pending on the mailbox. Note that:
• This function must be used with care. Tasks that would normally expect thepresence of the mailbox MUST check the return code of OSMboxPend().
• OSMboxAccept() callers will not know that the intended mailbox has beendeleted unless they check pevent to see that it's a NULL pointer.
• This call can potentially disable interrupts for a long time. The interrupt disabletime is directly proportional to the number of tasks waiting on the mailbox.
• Because ALL tasks pending on the mailbox will be readied, you MUST becareful in applications where the mailbox is used for mutual exclusion becausethe resource(s) will no longer be guarded by the mailbox.
PARAMETERS
pevent Pointer to the event control block associated with the desired mail-box.
opt May be one of the following delete options:
• OS_DEL_NO_PEND - Delete mailbox only if no task pend-ing
• OS_DEL_ALWAYS - Deletes the mailbox even if tasks arewaiting. In this case, all the tasks pending will be readied.
err Pointer to an error code that can contain one of the following val-ues:
• OS_NO_ERR - Call was successful; mailbox was deleted• OS_ERR_DEL_ISR - Attempt to delete mailbox from ISR• OS_ERR_INVALID_OPT - Invalid option was specified• OS_ERR_TASK_WAITING - One or more tasks were wait-
ing on the mailbox• OS_ERR_EVENT_TYPE - No pointer passed to a mailbox• OS_ERR_PEVENT_NULL - If pevent is a NULL pointer.
RETURN VALUE
!= (void *)0 Is a pointer to the event control clock (OS_EVENT) asso-ciated with the created mailbox
== (void *)0 If no event control blocks were available
LIBRARY
OS_MBOX.C
µC/OS-II Module 020-0059 Rev. A 28
OSMboxPend
void *OSMboxPend(OS_EVENT *pevent, INT16U timeout, INT8U *err);
DESCRIPTION
Waits for a message to be sent to a mailbox.
PARAMETERS
pevent Pointer to mailbox’s event control block.
timeout Allows task to resume execution if a message was not received bythe number of clock ticks specified. Specifying 0 means the task iswilling to wait forever.
err Pointer to a variable for holding an error code. Possible error mes-sages are:
• OS_NO_ERR: The call was successful and the task receiveda message.
• OS_TIMEOUT: A message was not received within thespecified timeout
• OS_ERR_EVENT_TYPE: Invalid event type• OS_ERR_PEND_ISR If this function was called from an
ISR and the result would lead to a suspension.• OS_ERR_PEVENT_NULL: If pevent is a NULL pointer
RETURN VALUE
!= (void *)0 A pointer to the message received
== (void *)0 No message was received, or pevent is a NULL pointer,or the proper pointer to the event control block was notpassed.
LIBRARY
OS_MBOX.C
SEE ALSO
OSMboxAccept, OSMboxCreate, OSMboxPost, OSMboxQuery
µC/OS-II Module 020-0059 Rev. A 29
OSMboxPost
INT8U OSMboxPost (OS_EVENT *pevent, void *msg);
DESCRIPTION
Sends a message to the specified mailbox
PARAMETERS
pevent Pointer to mailbox’s event control block.
msg Pointer to message to be posted. A NULL pointer must not be sent.
RETURN VALUE
OS_NO_ERR The call was successful and the message was sent.
OS_MBOX_FULL The mailbox already contains a message. Only one mes-sage at a time can be sent and thus, the message MUSTbe consumed before another can be sent.
OS_ERR_EVENT_TYPE Attempting to post to a non-mailbox.
OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
OS_ERR_POST_NULL_PTR If you are attempting to post a NULL pointer
LIBRARY
OS_MBOX.C
SEE ALSO
OSMboxAccept, OSMboxCreate, OSMboxPend, OSMboxQuery
µC/OS-II Module 020-0059 Rev. A 30
OSMboxPostOpt
INT8U OSMboxPostOpt (OS_EVENT *pevent, void *msg, INT8U opt);
DESCRIPTION
This function sends a message to a mailbox.
Note: Interrupts can be disabled for a long time if you do a “broadcast.” Theinterrupt disable time is proportional to the number of tasks waiting on themailbox.
PARAMETERS
pevent Pointer to mailbox’s event control block.
msg Pointer to the message to send. A NULL pointer must not be sent.
opt Determines the type of POST performed:
• OS_POST_OPT_NONE - POST to a single waiting task(Identical to OS_MboxPost())
• OS_POST_OPT_BROADCAST - POST to ALL tasks thatare waiting on the mailbox
RETURN VALUE
OS_NO_ERR The call was successful and the message was sent.
OS_MBOX_FULL The mailbox already contains a message. Only one mes-sage at a time can be sent and thus, the message MUSTbe consumed before another can be sent.
OS_ERR_EVENT_TYPE Attempting to post to a non-mailbox.
OS_ERR_PEVENT_NULL If pevent is a NULL pointer
OS_ERR_POST_NULL_PTR If you are attempting to post a NULL pointer
LIBRARY
OS_MBOX.C
µC/OS-II Module 020-0059 Rev. A 31
OSMboxQuery
INT8U OSMboxQuery (OS_EVENT *pevent, OS_MBOX_DATA *pdata);
DESCRIPTION
Obtains information about a message mailbox.
PARAMETERS
pevent Pointer to message mailbox’s event control block.
pdata Pointer to a data structure for information about the message mail-box
RETURN VALUE
OS_NO_ERR The call was successful and the message was sent.
OS_ERR_EVENT_TYPE Attempting to obtain data from a non mailbox.
LIBRARY
UCOS2.LIB
SEE ALSO
OSMboxAccept, OSMboxCreate, OSMboxPend, OSMboxPost
µC/OS-II Module 020-0059 Rev. A 32
OSMemCreate
OS_MEM *OSMemCreate (void *addr, INT32U nblks, INT32U blksize,INT8U *err);
DESCRIPTION
Creates a fixed-sized memory partition that will be managed by µC/OS-II.
PARAMETERS
addr Pointer to starting address of the partition.
nblks Number of memory blocks to create in the partition.
blksize The size (in bytes) of the memory blocks.
err Pointer to variable containing an error message.
RETURN VALUE
Pointer to the created memory partition control block if one is available, NULL pointerotherwise.
LIBRARY
UCOS2.LIB
SEE ALSO
OSMemGet, OSMemPut, OSMemQuery
µC/OS-II Module 020-0059 Rev. A 33
OSMemGet
void *OSMemGet (OS_MEM *pmem, INT8U *err);
DESCRIPTION
Gets a memory block from the specified partition.
PARAMETERS
pmem Pointer to partition’s memory control block
err Pointer to variable containing an error message
RETURN VALUE
Pointer to a memory block or a NULL pointer if an error condition is detected.
LIBRARY
UCOS2.LIB
SEE ALSO
OSMemCreate, OSMemPut, OSMemQuery
µC/OS-II Module 020-0059 Rev. A 34
OSMemPut
INT8U OSMemPut(OS_MEM *pmem, void *pblk);
DESCRIPTION
Returns a memory block to a partition.
PARAMETERS
pmem Pointer to the partition’s memory control block.
pblk Pointer to the memory block being released.
RETURN VALUE
OS_NO_ERR The memory block was inserted into the partition.
OS_MEM_FULL If returning a memory block to an already FULL memory parti-tion. (More blocks were freed than allocated!)
LIBRARY
UCOS2.LIB
SEE ALSO
OSMemCreate, OSMemGet, OSMemQuery
µC/OS-II Module 020-0059 Rev. A 35
OSMemQuery
INT8U OSMemQuery (OS_MEM *pmem, OS_MEM_DATA *pdata);
DESCRIPTION
Determines the number of both free and used memory blocks in a memory partition.
PARAMETERS
pmem Pointer to partition’s memory control block.
pdata Pointer to structure for holding information about the partition.
RETURN VALUE
OS_NO_ERR This function always returns no error.
LIBRARY
UCOS2.LIB
SEE ALSO
OSMemCreate, OSMemGet, OSMemPut
µC/OS-II Module 020-0059 Rev. A 36
OSMutexAccept
INT8U OSMutexAccept (OS_EVENT *pevent, INT8U *err);
DESCRIPTION
This function checks the mutual exclusion semaphore to see if a resource is available.Unlike OSMutexPend(), OSMutexAccept() does not suspend the calling task ifthe resource is not available or the event did not occur. This function cannot be calledfrom an ISR because mutual exclusion semaphores are intended to be used by tasksonly.
PARAMETERS
pevent Pointer to the event control block.
err Pointer to an error code that will be returned to your application:
• OS_NO_ERR - if the call was successful.• OS_ERR_EVENT_TYPE - if pevent is not a pointer to a
mutex• OS_ERR_PEVENT_NULL - pevent is a NULL pointer• OS_ERR_PEND_ISR - if you called this function from an
ISR
RETURN VALUE
1: Success, the resource is available and the mutual exclusion semaphore is acquired.
0: Error, either the resource is not available, or you didn't pass a pointer to a mutual ex-clusion semaphore, or you called this function from an ISR.
LIBRARY
OS_MUTEX.C
µC/OS-II Module 020-0059 Rev. A 37
OSMutexCreate
OS_EVENT *OSMutexCreate (INT8U prio, INT8U *err);
DESCRIPTION
This function creates a mutual exclusion semaphore. Note that:
• The LEAST significant 8 bits of the OSEventCnt field of the mutex’s eventcontrol block are used to hold the priority number of the task owning the mutexor 0xFF if no task owns the mutex.
• The MOST significant 8 bits of the OSEventCnt field of the mutex’s eventcontrol block are used to hold the priority number to use to reduce priorityinversion.
PARAMETERS
prio The priority to use when accessing the mutual exclusion sema-phore. In other words, when the semaphore is acquired and a high-er priority task attempts to obtain the semaphore then the priorityof the task owning the semaphore is raised to this priority. It is as-sumed that you will specify a priority that is LOWER in value thanANY of the tasks competing for the mutex.
err Pointer to error code that will be returned to your application:
• OS_NO_ERR - if the call was successful.• OS_ERR_CREATE_ISR - you attempted to create a mutex
from an ISR• OS_PRIO_EXIST - a task at the priority inheritance prior-
ity already exist.• OS_ERR_PEVENT_NULL - no more event control blocks
available.• OS_PRIO_INVALID - if the priority you specify is higher
that the maximum allowed (i.e. > OS_LOWEST_PRIO)
RETURN VALUE
!= (void *)0 Pointer to the event control clock (OS_EVENT) associat-ed with the created mutex.
== (void *)0 Error detected.
LIBRARY
OS_MUTEX.C
µC/OS-II Module 020-0059 Rev. A 38
OSMutexDel
OS_EVENT *OSMutexDel (OS_EVENT *pevent, INT8U opt, INT8U *err);
DESCRIPTION
This function deletes a mutual exclusion semaphore and readies all tasks pending on it.Note that:
• This function must be used with care. Tasks that would normally expect thepresence of the mutex MUST check the return code of OSMutexPend().
• This call can potentially disable interrupts for a long time. The interrupt disabletime is directly proportional to the number of tasks waiting on the mutex.
• Because ALL tasks pending on the mutex will be readied, you MUST be carefulbecause the resource(s) will no longer be guarded by the mutex.
PARAMETERS
pevent Pointer to mutex’s event control block.
opt May be one of the following delete options:
• OS_DEL_NO_PEND - Delete mutex only if no task pending• OS_DEL_ALWAYS - Deletes the mutex even if tasks are
waiting. In this case, all pending tasks will be readied.
err Pointer to an error code that can contain one of the following val-ues:
• OS_NO_ERR - The call was successful and the mutex wasdeleted
• OS_ERR_DEL_ISR - Attempted to delete the mutex froman ISR
• OS_ERR_INVALID_OPT - An invalid option was speci-fied
• OS_ERR_TASK_WAITING - One or more tasks were wait-ing on the mutex
• OS_ERR_EVENT_TYPE - If you didn't pass a pointer to amutex pointer.
RETURN VALUE
pevent On error.
(OS_EVENT *)0 Mutex was deleted.
LIBRARY
OS_MUTEX.C
µC/OS-II Module 020-0059 Rev. A 39
OSMutexPend
void OSMutexPend (OS_EVENT *pevent, INT16U timeout, INT8U*err);
DESCRIPTION
This function waits for a mutual exclusion semaphore. Note that:
• The task that owns the Mutex MUST NOT pend on any other event while it ownsthe mutex.
• You MUST NOT change the priority of the task that owns the mutex.
PARAMETERS
pevent Pointer to mutex’s event control block.
timeout Optional timeout period (in clock ticks). If non-zero, your task willwait for the resource up to the amount of time specified by this ar-gument. If you specify 0, however, your task will wait forever atthe specified mutex or, until the resource becomes available.
err Pointer to where an error message will be deposited. Possible errormessages are:
OS_NO_ERR - The call was successful and your task owns themutex
OS_TIMEOUT - The mutex was not available within the specifiedtime.
OS_ERR_EVENT_TYPE - If you didn't pass a pointer to a mutex
OS_ERR_PEVENT_NULL - pevent is a NULL pointer
OS_ERR_PEND_ISR - If you called this function from an ISRand the result would lead to a suspension.
LIBRARY
OS_MUTEX.C
µC/OS-II Module 020-0059 Rev. A 40
OSMutexPost
INT8U OSMutexPost (OS_EVENT *pevent);
DESCRIPTION
This function signals a mutual exclusion semaphore.
PARAMETERS
pevent Pointer to mutex’s event control block.
RETURN VALUE
OS_NO_ERR The call was successful and the mutex was signaled.
OS_ERR_EVENT_TYPE If you didn't pass a pointer to a mutex
OS_ERR_PEVENT_NULL pevent is a NULL pointer
OS_ERR_POST_ISR Attempted to post from an ISR (invalid for mutexes)
OS_ERR_NOT_MUTEX_OWNER The task that did the post is NOT the owner of theMUTEX.
LIBRARY
OS_MUTEX.C
µC/OS-II Module 020-0059 Rev. A 41
OSMutexQuery
INT8U OSMutexQuery (OS_EVENT *pevent, OS_MUTEX_DATA *pdata);
DESCRIPTION
This function obtains information about a mutex.
PARAMETERS
pevent Pointer to the event control block associated with the desired mu-tex.
pdata Pointer to a structure that will contain information about the mu-tex.
RETURN VALUE
OS_NO_ERR The call was successful and the message was sent
OS_ERR_QUERY_ISR Function was called from an ISR
OS_ERR_PEVENT_NULL pevent is a NULL pointer
OS_ERR_EVENT_TYPE Attempting to obtain data from a non mutex.
LIBRARY
OS_MUTEX.C
µC/OS-II Module 020-0059 Rev. A 42
OSQAccept
void *OSQAccept (OS_EVENT *pevent);
DESCRIPTION
Checks the queue to see if a message is available. Unlike OSQPend(), withOSQAccept() the calling task is not suspended if a message is unavailable.
PARAMETERS
pevent Pointer to the message queue’s event control block.
RETURN VALUE
Pointer to message in the queue if one is available, NULL pointer otherwise.
LIBRARY
OS_Q.C
SEE ALSO
OSQCreate, OSQFlush, OSQPend, OSQPost, OSQPostFront, OSQQuery
µC/OS-II Module 020-0059 Rev. A 43
OSQCreate
OS_EVENT *OSQCreate (void **start, INT16U qsize);
DESCRIPTION
Creates a message queue if event control blocks are available.
PARAMETERS
start Pointer to the base address of the message queue storage area. Thestorage area MUST be declared an array of pointers to void:void*MessageStorage[qsize].
qsize Number of elements in the storage area.
RETURN VALUE
Pointer to message queue’s event control block or NULL pointer if no event controlblocks were available.
LIBRARY
OS_Q.C
SEE ALSO
OSQAccept, OSQFlush, OSQPend, OSQPost, OSQPostFront, OSQQuery
µC/OS-II Module 020-0059 Rev. A 44
OSQDel
OS_EVENT *OSQDel (OS_EVENT *pevent, INT8U opt, INT8U *err);
DESCRIPTION
Deletes a message queue and readies all tasks pending on the queue. Note that:
• This function must be used with care. Tasks that would normally expect thepresence of the queue MUST check the return code of OSQPend().
• OSQAccept() callers will not know that the intended queue has been deletedunless they check pevent to see that it's a NULL pointer.
• This call can potentially disable interrupts for a long time. The interrupt disabletime is directly proportional to the number of tasks waiting on the queue.
• Because all tasks pending on the queue will be readied, you must be careful inapplications where the queue is used for mutual exclusion because the resource(s)will no longer be guarded by the queue.
• If the storage for the message queue was allocated dynamically (i.e. using amalloc() type call) then your application must release the memory storage bycall the counterpart call of the dynamic allocation scheme used. If the queuestorage was created statically then, the storage can be reused.
PARAMETERS
pevent Pointer to the queue’s event control block.
opt May be one of the following delete options:
• OS_DEL_NO_PEND - Delete queue only if no task pending• OS_DEL_ALWAYS - Deletes the queue even if tasks are
waiting. In this case, all the tasks pending will be readied.
err Pointer to an error code that can contain one of the following :
OS_NO_ERR - The call was successful and thequeue was deleted
OS_ERR_DEL_ISR - You tried to delete the queuefrom an ISR
OS_ERR_INVALID_OPT - An invalid option was specified
OS_ERR_TASK_WAITING - One or more tasks were waiting onthe queue
OS_ERR_EVENT_TYPE - If you didn't pass a pointer to a queue
OS_ERR_PEVENT_NULL - If pevent is a NULL pointer.
RETURN VALUE
pevent Error
(OS_EVENT *)0 The queue was successfully deleted.
LIBRARY
OS_Q.C
µC/OS-II Module 020-0059 Rev. A 45
OSQFlush
INT8U OSQFlush (OS_EVENT *pevent);
DESCRIPTION
Flushes the contents of the message queue.
PARAMETERS
pevent Pointer to message queue’s event control block.
RETURN VALUE
OS_NO_ERR Success.
OS_ERR_EVENT_TYPE A pointer to a queue was not passed.
OS_ERR_PEVENT_NULL If pevent is a NULL pointer.
LIBRARY
OS_Q.C
SEE ALSO
OSQAccept, OSQCreate, OSQPend, OSQPost, OSQPostFront, OSQQuery
µC/OS-II Module 020-0059 Rev. A 46
OSQPend
void *OSQPend (OS_EVENT *pevent, INT16U timeout, INT8U *err);
DESCRIPTION
Waits for a message to be sent to a queue.
PARAMETERS
pevent Pointer to message queue’s event control block.
timeout Allow task to resume execution if a message was not received bythe number of clock ticks specified. Specifying 0 means the task iswilling to wait forever.
err Pointer to a variable for holding an error code.
RETURN VALUE
Pointer to a message or, if a timeout occurs, a NULL pointer.
LIBRARY
OS_Q.C
SEE ALSO
OSQAccept, OSQCreate, OSQFlush, OSQPost, OSQPostFront,OSQQuery
µC/OS-II Module 020-0059 Rev. A 47
OSQPost
INT8U OSQPost (OS_EVENT *pevent, void *msg);
DESCRIPTION
Sends a message to the specified queue.
PARAMETERS
pevent Pointer to message queue’s event control block.
msg Pointer to the message to send. NULL pointer must not be sent.
RETURN VALUE
OS_NO_ERR The call was successful and the message was sent.
OS_Q_FULL The queue cannot accept any more messages becauseit is full.
OS_ERR_EVENT_TYPE If a pointer to a queue not passed.
OS_ERR_PEVENT_NULL If pevent is a NULL pointer.
OS_ERR_POST_NULL_PTR If attempting to post to a NULL pointer.
LIBRARY
OS_Q.C
SEE ALSO
OSQAccept, OSQCreate, OSQFlush, OSQPend, OSQPostFront,OSQQuery
µC/OS-II Module 020-0059 Rev. A 48
OSQPostFront
INT8U OSQPostFront (OS_EVENT *pevent, void *msg);
DESCRIPTION
Sends a message to the specified queue, but unlike OSQPost(), the message is postedat the front instead of the end of the queue. Using OSQPostFront() allows 'priority'messages to be sent.
PARAMETERS
pevent Pointer to message queue’s event control block.
msg Pointer to the message to send. NULL pointer must not be sent.
RETURN VALUE
OS_NO_ERR The call was successful and the message was sent.
OS_Q_FULL The queue cannot accept any more messages because it isfull.
OS_ERR_EVENT_TYPE A pointer to a queue was not passed.
OS_ERR_PEVENT_NULL If pevent is a NULL pointer.
OS_ERR_POST_NULL_PTR Attempting to post to a non mailbox.
LIBRARY
OS_Q.C
SEE ALSO
OSQAccept, OSQCreate, OSQFlush, OSQPend, OSQPost, OSQQuery
µC/OS-II Module 020-0059 Rev. A 49
OSQPostOpt
INT8U OSQPostOpt (OS_EVENT *pevent, void *msg, INT8U opt);
DESCRIPTION
This function sends a message to a queue. This call has been added to reduce code sizesince it can replace both OSQPost() and OSQPostFront(). Also, this functionadds the capability to broadcast a message to all tasks waiting on the message queue.
Note: Interrupts can be disabled for a long time if you do a “broadcast.” In fact,the interrupt disable time is proportional to the number of tasks waiting on thequeue.
PARAMETERS
pevent Pointer to message queue’s event control block.
msg Pointer to the message to send. NULL pointer must not be sent.
opt Determines the type of POST performed:
• OS_POST_OPT_NONE - POST to a single waiting task(Identical to OSQPost())
• OS_POST_OPT_BROADCAST - POST to ALL tasks thatare waiting on the queue
• OS_POST_OPT_FRONT - POST as LIFO (SimulatesOSQPostFront())
The last 2 flags may be combined:
• OS_POST_OPT_FRONT +OS_POST_OPT_BROADCAST - is identical toOSQPostFront() except that it will broadcast msg to allwaiting tasks.
RETURN VALUE
OS_NO_ERR The call was successful and the message was sent.
OS_Q_FULL The queue is full, cannot accept any more messages.
OS_ERR_EVENT_TYPE A pointer to a queue was not passed.
OS_ERR_PEVENT_NULL If pevent is a NULL pointer.
OS_ERR_POST_NULL_PTR Attempting to post a NULL pointer.
LIBRARY
OS_Q.C
µC/OS-II Module 020-0059 Rev. A 50
OSQQuery
INT8U OSQQuery (OS_EVENT *pevent, OS_Q_DATA *pdata);
DESCRIPTION
Obtains information about a message queue.
PARAMETERS
pevent Pointer to message queue’s event control block.
pdata Pointer to a data structure for message queue information.
RETURN VALUE
OS_NO_ERR The call was successful and the message was sent
OS_ERR_EVENT_TYPE Attempting to obtain data from a non queue.
OS_ERR_PEVENT_NULL If pevent is a NULL pointer.
LIBRARY
OS_Q.C
SEE ALSO
OSQAccept, OSQCreate, OSQFlush, OSQPend, OSQPost, OSQPostFront
µC/OS-II Module 020-0059 Rev. A 51
OSSchedLock
void OSSchedLock(void);
DESCRIPTION
Prevents task rescheduling. This allows an application to prevent context switches untilit is ready for them. There must be a matched call to OSSchedUnlock() for everycall to OSSchedLock().
LIBRARY
UCOS2.LIB
SEE ALSO
OSSchedUnlock
OSSchedUnlock
void OSSchedUnlock(void);
DESCRIPTION
Allow task rescheduling. There must be a matched call to OSSchedUnlock() forevery call to OSSchedLock().
LIBRARY
UCOS2.LIB
SEE ALSO
OSSchedLock
µC/OS-II Module 020-0059 Rev. A 52
OSSemAccept
INT16U OSSemAccept (OS_EVENT *pevent);
DESCRIPTION
This function checks the semaphore to see if a resource is available or if an event oc-curred. Unlike OSSemPend(), OSSemAccept() does not suspend the calling taskif the resource is not available or the event did not occur.
PARAMETERS
pevent Pointer to the desired semaphore’s event control block
RETURN VALUE
Semaphore value:If >0, semaphore value is decremented; value is returned before the decrement.If 0, then either resource is unavailable, event did not occur, or NULL or invalid pointerwas passed to the function.
LIBRARY
UCOS2.LIB
SEE ALSO
OSSemCreate, OSSemPend, OSSemPost, OSSemQuery
µC/OS-II Module 020-0059 Rev. A 53
OSSemCreate
OS_EVENT *OSSemCreate (INT16U cnt);
DESCRIPTION
Creates a semaphore.
PARAMETERS
cnt The initial value of the semaphore.
RETURN VALUE
Pointer to the event control block (OS_EVENT) associated with the created semaphore,or NULL if no event control block is available.
LIBRARY
UCOS2.LIB
SEE ALSO
OSSemAccept, OSSemPend, OSSemPost, OSSemQuery
OSSemPend
void OSSemPend (OS_EVENT *pevent, INT16U timeout, INT8U *err);
DESCRIPTION
Waits on a semaphore.
PARAMETERS
pevent Pointer to the desired semaphore’s event control block
timeout Time in clock ticks to wait for the resource. If 0, the task will waituntil the resource becomes available or the event occurs.
err Pointer to error message.
LIBRARY
UCOS2.LIB
SEE ALSO
OSSemAccept, OSSemCreate, OSSemPost, OSSemQuery
µC/OS-II Module 020-0059 Rev. A 54
OSSemPost
INT8U OSSemPost (OS_EVENT *pevent);
DESCRIPTION
This function signals a semaphore.
PARAMETERS
pevent Pointer to the desired semaphore’s event control block
RETURN VALUE
OS_NO_ERR The call was successful and the semaphore was signaled.
OS_SEM_OVF If the semaphore count exceeded its limit. In other words,you have signalled the semaphore more often than youwaited on it with either OSSemAccept() orOSSemPend().
OS_ERR_EVENT_TYPE If a pointer to a semaphore not passed.
OS_ERR_PEVENT_NULL If pevent is a NULL pointer.
LIBRARY
UCOS2.LIB
SEE ALSO
OSSemAccept, OSSemCreate, OSSemPend, OSSemQuery
µC/OS-II Module 020-0059 Rev. A 55
OSSemQuery
INT8U OSSemQuery (OS_EVENT *pevent, OS_SEM_DATA *pdata);
DESCRIPTION
Obtains information about a semaphore.
PARAMETERS
pevent Pointer to the desired semaphore’s event control block
pdata Pointer to a data structure that will hold information about thesemaphore.
RETURN VALUE
OS_NO_ERR The call was successful and the message was sent.
OS_ERR_EVENT_TYPE Attempting to obtain data from a non semaphore.
OS_ERR_PEVENT_NULL If the pevent parameter is a NULL pointer.
LIBRARY
UCOS2.LIB
SEE ALSO
OSSemAccept, OSSemCreate, OSSemPend, OSSemPost
µC/OS-II Module 020-0059 Rev. A 56
OSSetTickPerSec
INT16U OSSetTickPerSec(INT16U TicksPerSec);
DESCRIPTION
Sets the amount of ticks per second (from 1 - 2048). Ticks per second defaults to 64. Ifthis function is used, the #define OS_TICKS_PER_SEC needs to be changed sothat the time delay functions work correctly. Since this function uses integer division,the actual ticks per second may be slightly different that the desired ticks per second.
PARAMETERS
TicksPerSec Unsigned 16-bit integer.
RETURN VALUE
The actual ticks per second set, as an unsigned 16-bit integer.
LIBRARY
UCOS2.LIB
SEE ALSO
OSStart
OSStart
void OSStart(void);
DESCRIPTION
Starts the multitasking process, allowing µC/OS-II to manage the tasks that have beencreated. Before OSStart() is called, OSInit() MUST have been called and atleast one task MUST have been created. This function calls OSStartHighRdywhich calls OSTaskSwHook and sets OSRunning to TRUE.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTaskCreate, OSTaskCreateExt
µC/OS-II Module 020-0059 Rev. A 57
OSStatInit
void OSStatInit(void);
DESCRIPTION
Determines CPU usage.
LIBRARY
UCOS2.LIB
OSTaskChangePrio
INT8U OSTaskChangePrio (INT8U oldprio, INT8U newprio);
DESCRIPTION
Allows a task's priority to be changed dynamically. Note that the new priority MUSTbe available.
PARAMETERS
oldprio The priority level to change from.
newprio The priority level to change to.
RETURN VALUE
OS_NO_ERR The call was successful.
OS_PRIO_INVALID The priority specified is higher that the maximum allowed(i.e. ≥ OS_LOWEST_PRIO).
OS_PRIO_EXIST The new priority already exist
OS_PRIO_ERR There is no task with the specified OLD priority (i.e. theOLD task does not exist).
LIBRARY
UCOS2.LIB
µC/OS-II Module 020-0059 Rev. A 58
OSTaskCreate
INT8U OSTaskCreate(void (*task)(), void *pdata, INT16Ustk_size, INT8U prio);
DESCRIPTION
Creates a task to be managed by µC/OS-II. Tasks can either be created prior to the startof multitasking or by a running task. A task cannot be created by an ISR.
PARAMETERS
task Pointer to the task’s starting address.
pdata Pointer to a task’s initial parameters.
stk_size Number of bytes of the stack.
prior The task’s unique priority number.
RETURN VALUE
OS_NO_ERR The call was successful.
OS_PRIO_EXIT Task priority already exists (each task MUST have a uniquepriority).
OS_PRIO_INVALID The priority specified is higher than the maximum allowed(i.e. ≥ OS_LOWEST_PRIO).
LIBRARY
UCOS2.LIB
SEE ALSO
OSTaskCreateExt
µC/OS-II Module 020-0059 Rev. A 59
OSTaskCreateExt
INT8U OSTaskCreateExt (void (*task)(), void *pdata, INT8Uprio, INT16U id, INT16U stk_size, void *pext, INT16U opt);
DESCRIPTION
Creates a task to be managed by µC/OS-II. Tasks can either be created prior to the startof multitasking or by a running task. A task cannot be created by an ISR. This functionis similar to OSTaskCreate() except that it allows additional information about atask to be specified.
PARAMETERS
task Pointer to task’s code.
pdata Pointer to optional data area; used to pass parameters to the task atstart of execution.
prio The task’s unique priority number; the lower the number the high-er the priority.
id The task’s identification number (0...65535).
stk_size Size of the stack in number of elements. If OS_STK is set toINT8U, stk_size corresponds to the number of bytes avail-able. If OS_STK is set to INT16U, stk_size contains the num-ber of 16-bit entries available. Finally, if OS_STK is set toINT32U, stk_size contains the number of 32-bit entries avail-able on the stack.
pext Pointer to a user-supplied Task Control Block (TCB) extension.
opt The lower 8 bits are reserved by µC/OS-II. The upper 8 bits con-trol application-specific options. Select an option by setting thecorresponding bit(s).
RETURN VALUE
OS_NO_ERR The call was successful.
OS_PRIO_EXIT Task priority already exists (each task MUST have a uniquepriority).
OS_PRIO_INVALID The priority specified is higher than the maximum allowed(i.e. ≥OS_LOWEST_PRIO).
Library
UCOS2.LIB
SEE ALSO
OSTaskCreate
µC/OS-II Module 020-0059 Rev. A 60
OSTaskCreateHook
void OSTaskCreateHook(OS_TCB *ptcb);
DESCRIPTION
Called by µC/OS-II whenever a task is created. This call-back function resides inUCOS2.LIB and extends functionality during task creation by allowing additional in-formation to be passed to the kernel, anything associated with a task. This function canalso be used to trigger other hardware, such as an oscilloscope. Interrupts are disabledduring this call, therefore, it is recommended that code be kept to a minimum.
PARAMETERS
ptcb Pointer to the TCB of the task being created.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTaskDelHook
µC/OS-II Module 020-0059 Rev. A 61
OSTaskDel
INT8U OSTaskDel (INT8U prio);
DESCRIPTION
Deletes a task. The calling task can delete itself by passing either its own priority num-ber or OS_PRIO_SELF if it doesn’t know its priority number. The deleted task is re-turned to the dormant state and can be re-activated by creating the deleted task again.
PARAMETERS
prio Task’s priority number.
RETURN VALUE
OS_NO_ERR The call was successful.
OS_TASK_DEL_IDLE Attempting to delete µC/OS-II's idle task.
OS_PRIO_INVALID The priority specified is higher than the maximum allowed(i.e. ≥ OS_LOWEST_PRIO) or, OS_PRIO_SELF notspecified.
OS_TASK_DEL_ERR The task to delete does not exist.
OS_TASK_DEL_ISR Attempting to delete a task from an ISR.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTaskDelReq
µC/OS-II Module 020-0059 Rev. A 62
OSTaskDelHook
void OSTaskDelHook(OS_TCB *ptcb);
DESCRIPTION
Called by µC/OS-II whenever a task is deleted. This call-back function resides inUCOS2.LIB. Interrupts are disabled during this call, therefore, it is recommendedthat code be kept to a minimum.
PARAMETERS
ptcb Pointer to TCB of task being deleted.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTaskCreateHook
µC/OS-II Module 020-0059 Rev. A 63
OSTaskDelReq
INT8U OSTaskDelReq (INT8U prio);
DESCRIPTION
Notifies a task to delete itself. A well-behaved task is deleted when it regains control ofthe CPU by calling OSTaskDelReq (OSTaskDelReq) and monitoring the re-turn value.
PARAMETERS
prio The priority of the task that is being asked to delete itself.OS_PRIO_SELF is used when asking whether another taskwants the current task to be deleted.
RETURN VALUE
OS_NO_ERR The task exists and the request has been registered.
OS_TASK_NOT_EXIST The task has been deleted. This allows the caller to knowwhether the request has been executed.
OS_TASK_DEL_IDLE If requesting to delete uC/OS-II's idle task.
OS_PRIO_INVALID The priority specified is higher than the maximum allowed(i.e. ≥ OS_LOWEST_PRIO) or, OS_PRIO_SELF is notspecified.
OS_TASK_DEL_REQ A task (possibly another task) requested that the runningtask be deleted.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTaskDel
µC/OS-II Module 020-0059 Rev. A 64
OSTaskIdleHook
void OSTaskIdleHook (void);
DESCRIPTION
This function is called by the idle task. This hook has been added to allow you to dosuch things as STOP the CPU to conserve power. Interrupts are enabled during this call.
LIBRARY
UCOS2.LIB
OSTaskQuery
INT8U OSTaskQuery (INT8U prio, OS_TCB *pdata);
DESCRIPTION
Obtains a copy of the requested task's task control block (TCB).
PARAMETERS
prio Priority number of the task.
pdata Pointer to task’s TCB.
RETURN VALUE
OS_NO_ERR The requested task is suspended.
OS_PRIO_INVALID The priority you specify is higher than the maximum al-lowed (i.e. ≥ OS_LOWEST_PRIO) or, OS_PRIO_SELFis not specified.
OS_PRIO_ERR The desired task has not been created.
LIBRARY
UCOS2.LIB
µC/OS-II Module 020-0059 Rev. A 65
OSTaskResume
INT8U OSTaskResume (INT8U prio);
DESCRIPTION
Resumes a suspended task. This is the only call that will remove an explicit task sus-pension.
PARAMETERS
prio The priority of the task to resume.
RETURN VALUE
OS_NO_ERR The requested task is resumed.
OS_PRIO_INVALID The priority specified is higher than the maximum allowed(i.e. ≥ OS_LOWEST_PRIO).
OS_TASK_NOT_SUSPENDED The task to resume has not been suspended.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTaskSuspend
OSTaskStatHook
void OSTaskStatHook();
DESCRIPTION
Called every second by µC/OS-II's statistics task. This function resides inUCOS2.LIB and allows an application to add functionality to the statistics task.
LIBRARY
UCOS2.LIB
µC/OS-II Module 020-0059 Rev. A 66
OSTaskStkChk
INT8U OSTaskStkChk (INT8U prio, OS_STK_DATA *pdata);
DESCRIPTION
Check the amount of free memory on the stack of the specified task.
PARAMETERS
prio The task’s priority.
pdata Pointer to a data structure of type OS_STK_DATA.
RETURN VALUE
OS_NO_ERR The call was successful.
OS_PRIO_INVALID The priority you specify is higher than the maximum al-lowed (i.e. > OS_LOWEST_PRIO) or, OS_PRIO_SELFnot specified.
OS_TASK_NOT_EXIST The desired task has not been created.
OS_TASK_OPT_ERR If OS_TASK_OPT_STK_CHK was NOT specified whenthe task was created.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTaskCreateExt
µC/OS-II Module 020-0059 Rev. A 67
OSTaskSuspend
INT8U OSTaskSuspend (INT8U prio);
DESCRIPTION
Suspends a task. The task can be the calling task if the priority passed toOSTaskSuspend() is the priority of the calling task or OS_PRIO_SELF. Thisfunction should be used with great care. If a task is suspended that is waiting for anevent (i.e. a message, a semaphore, a queue ...) the task will be prevented from runningwhen the event arrives.
PARAMETERS
prio The priority of the task to suspend.
RETURN VALUE
OS_NO_ERR The requested task is suspended.
OS_TASK_SUS_IDLE Attempting to suspend the idle task (not allowed).
OS_PRIO_INVALID The priority specified is higher than the maximum allowed(i.e. ≥ OS_LOWEST_PRIO) or, OS_PRIO_SELF is notspecified .
OS_TASK_SUS_PRIO The task to suspend does not exist.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTaskResume
µC/OS-II Module 020-0059 Rev. A 68
OSTaskSwHook
void OSTaskSwHook();
DESCRIPTION
Called whenever a context switch happens. The task control block (TCB) for the taskthat is ready to run is accessed via the global variable OSTCBHighRdy, and the TCBfor the task that is being switched out is accessed via the global variable OSTCBCur.
LIBRARY
UCOS2.LIB
OSTCBInitHook
void OSTCBInitHook (OS_TCB *ptcb);
DESCRIPTION
This function is called by OSTCBInit() after setting up most of the task controlblock (TCB). Interrupts may or may not be enabled during this call.
PARAMETER
ptcb Pointer to the TCB of the task being created.
LIBRARY
UCOS2.LIB
µC/OS-II Module 020-0059 Rev. A 69
OSTimeDly
void OSTimeDly (INT16U ticks);
DESCRIPTION
Delays execution of the task for the specified number of clock ticks. No delay will re-sult if ticks is 0. If ticks is >0, then a context switch will result.
PARAMETERS
ticks Number of clock ticks to delay the task.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTimeDlyHMSM, OSTimeDlyResume, OSTimeDlySec
µC/OS-II Module 020-0059 Rev. A 70
OSTimeDlyHMSM
INT8U OSTimeDlyHMSM (INT8U hours, INT8U minutes, INT8U seconds,INT16U milli);
DESCRIPTION
Delays execution of the task until specified amount of time expires. This call allows thedelay to be specified in hours, minutes, seconds and milliseconds instead of ticks. Theresolution on the milliseconds depends on the tick rate. For example, a 10 ms delay isnot possible if the ticker interrupts every 100 ms. In this case, the delay would be set to0. The actual delay is rounded to the nearest tick.
PARAMETERS
hours Number of hours that the task will be delayed (max. is 255)
minutes Number of minutes (max. 59)
seconds Number of seconds (max. 59)
milli Number of milliseconds (max. 999)
RETURN VALUE
OS_NO_ERR Execution delay of task was successful
OS_TIME_INVALID_MINUTES Minutes parameter out of range
OS_TIME_INVALID_SECONDS Seconds parameter out of range
OS_TIME_INVALID_MS Milliseconds parameter out of range
OS_TIME_ZERO_DLY
LIBRARY
OS_TIME.C
SEE ALSO
OSTimeDly, OSTimeDlyResume, OSTimeDlySec
µC/OS-II Module 020-0059 Rev. A 71
OSTimeDlyResume
INT8U OSTimeDlyResume (INT8U prio);
DESCRIPTION
Resumes a task that has been delayed through a call to either OSTimeDly() orOSTimeDlyHMSM(). Note that this function MUST NOT be called to resume a taskthat is waiting for an event with timeout. This situation would make the task look likea timeout occurred (unless this is the desired effect). Also, a task cannot be resumed thathas called OSTimeDlyHMSM()with a combined time that exceeds 65535 clock ticks.In other words, if the clock tick runs at 100 Hz then, a delayed task will not be able tobe resumed that called OSTimeDlyHMSM(0, 10, 55, 350) or higher.
PARAMETERS
prio Priority of the task to resume.
RETURN VALUE
OS_NO_ERR Task has been resumed.
OS_PRIO_INVALID The priority you specify is higher than the maximum al-lowed (i.e. ≥ OS_LOWEST_PRIO).
OS_TIME_NOT_DLY Task is not waiting for time to expire.
OS_TASK_NOT_EXIST The desired task has not been created.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTimeDly, OSTimeDlyHMSM, OSTimeDlySec
µC/OS-II Module 020-0059 Rev. A 72
OSTimeDlySec
INT8U OSTimeDlySec (INT16U seconds);
DESCRIPTION
Delays execution of the task until seconds expires. This is a low-overhead version ofOSTimeDlyHMSM for seconds only.
PARAMETERS
seconds The number of seconds to delay.
RETURN VALUE
OS_NO_ERR The call was successful.
OS_TIME_ZERO_DLY A delay of zero seconds was requested.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTimeDly, OSTimeDlyHMSM, OSTimeDlyResume
µC/OS-II Module 020-0059 Rev. A 73
OSTimeGet
INT32U OSTimeGet (void);
DESCRIPTION
Obtain the current value of the 32-bit counter that keeps track of the number of clockticks.
RETURN VALUE
The current value of OSTime.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTimeSet
OSTimeSet
void OSTimeSet (INT32U ticks);
DESCRIPTION
Sets the 32-bit counter that keeps track of the number of clock ticks.
PARAMETERS
ticks The value to set OSTime to.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTimeGet
µC/OS-II Module 020-0059 Rev. A 74
OSTimeTick
void OSTimeTick (void);
DESCRIPTION
This function takes care of the processing necessary at the occurrence of each systemtick. This function is called from the BIOS timer interrupt ISR, but can also be calledfrom a high priority task. The user definable OSTimeTickHook() is called fromthis function and allows for extra application specific processing to be performed ateach tick. Since OSTimeTickHook() is called during an interrupt, it should performminimal processing as it will directly affect interrupt latency.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTimeTickHook
µC/OS-II Module 020-0059 Rev. A 75
OSTimeTickHook
void OSTimeTickHook(void);
DESCRIPTION
This function, as included with Dynamic C, is a stub that does nothing except return. Itis called every clock tick. Code in this function should be kept to a minimum as it willdirectly affect interrupt latency. This function must preserve any registers it uses otherthan the ones that are preserved at the beginning of the periodic interrupt(periodic_isr in VDRIVER.LIB), and therefore should be written in assembly.At the time of this writing, the registers saved by periodic_isr are: AF,IP,HL,DEand IX.
LIBRARY
UCOS2.LIB
SEE ALSO
OSTimeTick
OSVersion
INT16U OSVersion (void);
DESCRIPTION
Returns the version number of µC/OS-II. The returned value corresponds to µC/OS-II'sversion number multiplied by 100; i.e., version 2.00 would be returned as 200.
RETURN VALUE
Version number multiplied by 100.
LIBRARY
UCOS2.LIB
µC/OS-II Module 020-0059 Rev. A 76