IAR PowerPac™ RTOS

User Guide

PPRTOS-3

COPYRIGHT NOTICE
© Copyright 2006-2008 IAR Systems AB. No part of this document may be reproduced without the prior written consent of IAR Systems AB. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such a license.

DISCLAIMER
The information in this document is subject to change without notice and does not represent a commitment on any part of IAR Systems AB. While the information contained herein is assumed to be accurate, IAR Systems assumes no responsibility for any errors or omissions. In no event shall IAR Systems, its employees, its contractors, or the authors of this document be liable for special, direct, indirect, or consequential damage, losses, costs, charges, claims, demands, claim for lost profits, fees, or expenses of any nature or kind.

TRADEMARKS
IAR Systems, IAR Embedded Workbench, C-SPY, visualSTATE, From Idea To Target, IAR KickStart Kit, IAR PowerPac, IAR YellowSuite, IAR Advanced Development Kit, IAR, and the IAR Systems logotype are trademarks or registered trademarks owned by IAR Systems AB. J-Link is a trademark licensed to IAR Systems AB. Microsoft and Windows are registered trademarks of Microsoft Corporation. All other product names are trademarks or registered trademarks of their respective owners.

EDITION NOTICE
Third edition: October 2008 Part number: PPRTOS-3

Internal reference: SW v3.62, ISUD.

PPRTOS-3

Contents
Preface ........................................................................................................................................................................ 9 Introduction to IAR PowerPac RTOS ............................................................................................................ 11
What is IAR PowerPac RTOS .................................................................................................................. 11 Features ......................................................................................................................................................... 11

Basic concepts ....................................................................................................................................................... 13
Tasks ............................................................................................................................................................... 13 Single-task systems (superloop) ............................................................................................................... 13 Multitasking systems ................................................................................................................................... 13 Cooperative multitasking ...................................................................................................................... 14 Preemptive multitasking ....................................................................................................................... 15 Scheduling ...................................................................................................................................................... 15 Round-robin scheduling algorithm ....................................................................................................... 15 Priority-controlled scheduling algorithm .............................................................................................. 16 Priority inversion .................................................................................................................................. 16 Communication between tasks ................................................................................................................ 16 Global variables .................................................................................................................................... 16 Communication mechanisms ................................................................................................................ 16 Mailboxes and queues ........................................................................................................................... 17 Semaphores ........................................................................................................................................... 17 Events .................................................................................................................................................... 17 How task-switching works ......................................................................................................................... 17 Switching stacks ........................................................................................................................................... 17 Change of task status .................................................................................................................................. 18 How the OS gains control ......................................................................................................................... 19 OS_InitKern() ....................................................................................................................................... 20 OS_Start() ............................................................................................................................................. 20 Different builds of IAR PowerPac RTOS ............................................................................................... 21 IAR PowerPac RTOSIAR PowerPac RTOSList of libraries ................................................................ 21

Tasks ......................................................................................................................................................................... 23
Introduction .................................................................................................................................................. 23 Example of task routine as an endless loop .......................................................................................... 23 Example of task routine that terminates itself ...................................................................................... 23 API function .................................................................................................................................................. 23 OS_CREATETASK() ........................................................................................................................... 24 OS_CreateTask() .................................................................................................................................. 25 OS_CREATETASK_EX() ................................................................................................................... 26 OS_CreateTaskEx() .............................................................................................................................. 27 OS_Delay() ........................................................................................................................................... 28 OS_DelayUntil() ................................................................................................................................... 28 OS_ExtendTaskContext() ..................................................................................................................... 29 OS_GetpCurrentTask() ......................................................................................................................... 31 OS_GetPriority() ................................................................................................................................... 31 OS_GetSuspendCnt() ............................................................................................................................ 31 OS_GetTaskID() ................................................................................................................................... 32
PPRTOS-3

3

............................................................................................................................................................................................................................................................47 OS_GetTimerStatusEx() ....................................................................................................................................................................................................................38 OS_CreateTimer() ..........................................................................................................................................................................................................................................................................................................................................................................................................................................46 OS_DeleteTimerEx() ...................48 Resource semaphores ...............................................................................................................................................................................................................................................................................................................41 OS_GetTimerValue() .33 OS_Suspend() ..................................................................................................37 API functions ....................................................................47 OS_GetTimerPeriodEx() ..........39 OS_StartTimer() ...............................................................................................42 OS_GetTimerStatus() ..................................................................................................................................................................................................................................................................32 OS_SetPriority() ..................................34 OS_WakeTask() ...............................................43 OS_CreateTimerEx() .........................................................................................................................................................................................................................................................................................................37 OS_CREATETIMER() .....................................................................................................................................................................................................................................52 OS_Request() ...............................................................................................................................41 OS_GetTimerPeriod() ..........................................................49 API functions .......................................................................................................47 OS_GetpCurrentTimerEx() ................................................................................................................45 OS_StopTimerEx() .........................................................................................54 IAR PowerPac™ RTOS 4 User Guide PPRTOS-3 ..............................................................................................................40 OS_RetriggerTimer() .....................................................................................................42 OS_CREATETIMER_EX() ..............34 OS_Terminate() ..........................................................................................................................................................45 OS_RetriggerTimerEx() ............................................................................................40 OS_SetTimerPeriod() ...................................................................................................................................... 49 Introduction ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................54 OS_GetResourceOwner() ...................................................44 OS_StartTimerEx() ................................................................................................................................................................47 OS_GetTimerValueEx() ............................................53 OS_GetSemaValue() ........................................32 OS_Resume() .................................................................................................................................................................37 Extended software timer ......................................................................................................................................................................................................................................................................................42 OS_GetpCurrentTimer() .....................................................................................................................................................................................................................54 OS_DeleteRSema() ...................................................................51 OS_Unuse() ...............................................................................................................................................................51 OS_CREATERSEMA() .............................................................................................................................51 OS_Use() ..OS_IsTask() ...............................................................33 OS_SetTaskName() .........................................................................................................................................................40 OS_DeleteTimer() .................................................45 OS_SetTimerPeriodEx() .....................................................39 OS_StopTimer() .............................35 Software timers .........................................................................................................................................................................................................33 OS_SetTimeSlice() .............................. 37 Software timer ...35 OS_Yield() ......................

................................................................................................................. 75 OS_Q_GetMessageCnt() ................................................................................................................ 58 OS_SetCSemaValue() ......... 67 OS_WaitMail() .............. 77 OS_WaitSingleEvent() ................................................... 73 OS_Q_GetPtrTimed() ............................................. 59 Mailboxes . 55 OS_CreateCSema() ... 77 API functions ................................................................................ 71 Introduction .................................................................................................................................................................................................................................................................... 58 OS_DeleteCSema() .......................................................................................................... 77 OS_WaitEvent() ........................................................ 72 OS_Q_GetPtr() ................................................ 55 API functions .......................................................................................................................................................................... 61 Single-byte mailbox functions ................................................................ 78 PPRTOS-3 5 ..................................................... 57 OS_WaitCSemaTimed() ...............................................................Contents Counting Semaphores .................................................................................................................................................................................................................................................................................................................................................................. 71 OS_Q_Put() ..................................................... 66 OS_GetMailTimed() .............................................................. 68 OS_GetMessageCnt() .................... 66 OS_GetMailCond() / OS_GetMailCond1() ................................................................................................................................................................................................................... 63 OS_PutMail() / OS_PutMail1() .......................................................................................................................................................................................................................................................................................................................... 58 OS_GetCSemaValue() ..................................................................................................................... 63 OS_PutMailCond() / OS_PutMailCond1() ............................................................................................................................................. 61 Basics .......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... 55 Introduction ....................... 71 OS_Q_Create() ....... 68 OS_DeleteMB() ........ 74 OS_Q_Purge() ....................................................................................................................................................................................................................................................... 61 Introduction ............................. 65 OS_GetMail() / OS_GetMail1() ................................................................................................................................... 62 OS_CREATEMB() ................................................................................................................................................................................................................................................................................................................................................ 64 OS_PutMailFront() / OS_PutMailFront1() ................................. 57 OS_CSemaRequest() ............................................................................. 69 Queues ........................................................................................................................................................................................................................................................................................................ 71 Basics ...................................................................................................................................................................................................................................................... 62 API functions ....................................... 77 Introduction ......................................................................................................................................................................................................................................................................... 72 OS_Q_GetPtrCond() ................................................. 65 OS_PutMailFrontCond() / OS_PutMailFrontCond1() .................................................................... 75 Task Events .............................................................. 55 OS_CREATECSEMA() .................................................................. 56 OS_WaitCSema() ................................................................................................................................................................................................................................................................................................................................ 71 API functions .. 56 OS_SignalCSemaMax() .......................................................................... 74 OS_Q_Clear() ............................... 56 OS_SignalCSema() .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. 61 Typical applications ................................ 68 OS_ClearMB() ............................................

..................87 Heap type memory management ...............................................................................................................................................................................................................................................................................................................................................................93 OS_MEMF_Release() ............89 API functions ...........................................................................................................................................................................................................................................................................................80 Event objects ....................................................................................................................................................................91 API functions .........................................................................................................................................................................................................................................................................................................79 OS_SignalEvent() .......................................................................................................................................................................................................................91 OS_MEMF_Delete() ....... 83 Introduction ...............................................85 OS_EVENT_Reset() ....................93 OS_MEMF_FreeBlock() .........................94 OS_MEMF_GetMaxUsed() ...................................................................................................................................................................................................................................................................................................................................................................................97 API functions ......................................................................................................................................................................78 OS_WaitSingleEventTimed() .......................................................................................................................................................................................................................................................97 Interrupt stack ........................................ 91 Introduction ..................................................................95 Stacks ....................................................................................................................................92 OS_MEMF_Request() ..............................................................................................................83 API functions .....................................95 OS_MEMF_IsInPool() ...............................................................................................................................................................................................................OS_WaitEventTimed() ......................................................................................................................................................................................................................................................87 OS_EVENT_Delete() ............89 Fixed block size memory pools .....................................................83 OS_EVENT_Wait() .................................................................................................................................................................................................................................................................83 OS_EVENT_Create() ..........................................................................................................................................................................98 OS_GetStackSize() ...........................................................................................94 OS_MEMF_GetNumFreeBlocks() ............................................................................................................................................................................................................................................................................................................................92 OS_MEMF_AllocTimed() ...........................................................................................................................................................................92 OS_MEMF_Alloc() .................................................................................................................99 OS_GetStackUsed() ...............91 OS_MEMF_Create() .........84 OS_EVENT_WaitTimed() .......................................................97 Task stack ....................................................................................98 OS_GetStackSpace() ..............................94 OS_MEMF_GetBlockSize() ...................................................................................................................................................... 89 Introduction .............................................................................. 97 Introduction ................................................................................84 OS_EVENT_Set() ........................................................................80 OS_ClearEvents() .97 System stack .......................................................................................99 IAR PowerPac™ RTOS 6 User Guide PPRTOS-3 ..........................................................................................................................................................................................87 OS_EVENT_Get() ..................................................................................................................................................................................................94 OS_MEMF_GetNumBlocks() ..........................................................86 OS_EVENT_Pulse() ...................................................................................................................................................................................................79 OS_GetEventsOccurred() ................................................................................98 OS_GetStackBase() ...................................................

......................................................................................................................................................................................108 Critical Regions .......................................................................................................................................................................................................................................................... 109 OS_EnterRegion() .....................................................................................119 Tick handler ................................................................................................................117 Time variables .................................................................................................................................................................................................................................. 112 High-resolution measurement .................................................... 117 Introduction ........................................ 117 System tick .........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................108 Non-maskable interrupts (NMIs) ........................................................ 104 OS_CallNestableISR() ..........................................................................................111 Low-resolution measurement .................................................................................................................. 103 OS_CallISR() ...117 OS_TimeDex ............................................................................................. 109 Time measurement ...................................................................... 109 Introduction ................................................................................119 API functions .....................................................................................................................................................................................................................................................................................................................104 OS_EnterInterrupt() ........................................................................................................................................................................................................................ 101 Interrupt latency ...................................................... 111 Introduction .......................................................................... 103 API functions ....................... 107 Definitions of interrupt control macros (in RTOS.................................................................. 106 OS_DI() / OS_EI() / OS_RestoreI() ...............................................................111 API functions ......... 113 API functions .....................................................105 Example using OS_EnterInterrupt()/OS_LeaveInterrupt() ................................ 119 Introduction ....................................................................................................................................................................................................................................................................................................................................Contents Interrupts ............................................................................................. 117 OS_Time ...........................................................................h) ...........................102 High / low priority interrupts ... 107 Nesting interrupt routines ....... 101 Additional causes for interrupt latencies .................................................................................................................................................. 103 General rules .............................................................................................109 API functions ...............................................101 Causes of interrupt latencies .................................................................................................................................................................................................................................................................................................................................................................................................................... 105 OS_LeaveInterruptNoSwitch() .................. 108 OS_LeaveNestableInterrupt() ...... 101 Zero interrupt latency ......................................................................................................................................... 109 OS_LeaveRegion() .......................................................................................................................................................................................................................................................................................................................................................................................................................................106 OS_IncDI() / OS_DecRI() ......................................................................................................................................... 105 Enabling / disabling interrupts from C ................................................................................................ 117 OS internal variables and data-structures ................................................................................................................................................................................................................................................................................................................................................................105 Example using OS_EnterInterrupt()/OS_LeaveInterrupt() ................................................. 114 Example .................................................. 101 What are interrupts? ................. 119 PPRTOS-3 7 .................................................. 107 OS_EnterNestableInterrupt() .............................................................. 103 Additional rules for preemptive multitasking ......... 115 System variables .................................................................................................................................................................................................................................................................... 104 OS_LeaveInterrupt() .............................................................................................................. 102 Rules for interrupt handlers ................................................................................

......................................................................................................................................................................................124 Changing the tick frequency .................................................................................................................................................................................................................................................................................................... 145 Glossary ................................................................................................................................................................................133 Benchmarking .............................................................128 Settings ......................................................................................................................................................................................................................................................................................................................................123 Hardware-specific routines ......................................................................................................................................................................................................................................................................................................................................................................................... 143 Introduction ..........................125 Task list .........................................................................................................................................................................133 Measurement with port pins and oscilloscope ...............................................................................................133 Performance ..........................................................130 Performance and resource usage ....................Hooking into the system tick ...............................................................................................................................................................................................143 Building IAR PowerPac RTOS libraries ................121 Configuration of target system (BSP) ..133 Memory requirements ........................................................................123 Configuration defines ....................................... 125 Enabling the C-SPY plug-in module .......................................................................................................................................................... 141 Source code of kernel and library ................................................................. 123 Introduction ...........................................................................................................................................125 Overview ...............................................................................................................................................................................................................................................................................................................................................................124 STOP / HALT / IDLE modes ............................................126 Mailboxes ..........................127 System information ..................................................................................................................................................................................................................................................................................................................................................................................................................................................................... 129 Runtime errors .........................................................................................................................................123 Using a different timer to generate the tick-interrupts for IAR PowerPac RTOS .............................. 147 Index .........................................................................................................................................144 FAQ (frequently asked questions) ........................................................123 How to change settings ............................................................................................................................................................................................................................. 133 Introduction ...........................121 API functions ...........................................................................................................................................................................................................................144 OS_SUPPORT_CLEANUP_ON_TERMINATE .127 Resource semaphores ..............................................................................................................................................................................................................................................................143 OS_RR_SUPPORTED .........................................................143 Major compile time switches ....129 List of error codes ......................................................................................................................... 139 Limitations ........... 149 IAR PowerPac™ RTOS 8 User Guide PPRTOS-3 ...................................................................................................124 RTOS-aware debugging .......................126 Timers ..........................................................128 Debugging ......123 Setting the system frequency OS_FSYS ..................................................................................................................................................134 Reentrancy ..........................................................................................................................................

refer to Chapter 2 in the CPU & Compiler Specifics manual of IAR PowerPac RTOS documentation. Parameters in API functions. dialog boxes. which includes a step-by-step introduction to using IAR PowerPac RTOS. which describes the standard in C-programming and. linker.or pathnames). Very important sections Reference GUIElement Emphasis Table 1: Typographic conventions PPRTOS-3 9 . For a quick and easy startup with IAR PowerPac RTOS.and compiler-independent introduction to IAR PowerPac RTOS and to be a reference for all IAR PowerPac RTOS API functions. menu names. How to use this guide The intention of this guide is to give you a CPU. file. The purpose of this guide is to provide you with detailed reference information that can help you to use the IAR PowerPac RTOS to best suit your application requirements. in newer editions. This document assumes that you already have a solid knowledge of the following: ● ● ● ● The software tools used for building your application (assembler.Preface Welcome to the IAR PowerPac™ RTOS guide User Guide. we recommend The C Programming Language by Kernighan and Richie (ISBN 0-13-1103628). menu commands. Buttons. Document conventions TYPOGRAPHIC CONVENTIONS FOR SYNTAX This guide uses the following typographic conventions: Style Used for Keyword Parameter Sample Text that you enter at the command-prompt or that appears on the display (that is system functions. If you feel that your knowledge of C is not sufficient. C compiler) The C programming language The target processor DOS command line. Sample code in program examples. Reference to chapters. Who should read this guide You should read this guide if you plan to develop an embedded system using IAR PowerPac RTOS and need to get detailed reference information about it. also covers the ANSI C standard. tables and figures or other documents.

IAR PowerPac™ RTOS 10 User Guide PPRTOS-3 .

the limited resources of microcontrollers have always been kept in mind. Power-consumption is minimized. Size and number of messages can be freely defined when initializing mailboxes.Introduction to IAR PowerPac RTOS What is IAR PowerPac RTOS IAR PowerPac RTOS is a priority-controlled multitasking system. Unlimited number of mailboxes (limited only by the amount of available memory). mailboxes. Every task can have an individual priority => the response of tasks can be precisely defined according to the requirements of the application. Power management. Preemptions can be disabled for entire tasks or for sections of a program. Features Throughout the development process of IAR PowerPac RTOS. except for situations where priority inversion applies. Easily accessible time variable. Time resolution can be freely selected (default is 1ms). Some features of IAR PowerPac RTOS include: ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● ● Preemptive scheduling: Guarantees that of all tasks in READY state the one with the highest priority executes. Unused calculation time can automatically be spent in halt mode. IAR PowerPac RTOS is a high-performance tool that has been optimized for minimum memory consumption in both RAM and ROM. designed to be used as an embedded operating system for the development of real-time applications. 8-bit events for every task. Up to 255 priorities. keeping the ROM size very small. and events. to fit the needs of the industry. A couple of files are supplied in source code to make sure that you do not loose any flexibility by using IAR PowerPac RTOS and that you can customize the system to fully fit your needs. as well as high speed and versatility. Round-robin scheduling for tasks with identical priorities. The internal structure of the real-time operating system (RTOS) has been optimized in a variety of applications with different customers. IAR PowerPac RTOS is highly modular. Unlimited number of software timers (limited only by the amount of available memory). Unlimited number of tasks (limited only by the amount of available memory). which means that only those functions that are needed are linked. The tasks you create can easily and safely communicate with each other using a complete palette of communication mechanisms such as semaphores. 2 types of semaphores: resource and counting. PPRTOS-3 11 . Unlimited number of semaphores (limited only by the amount of available memory).

C or C++ source code. Very short interrupt disable-time => short interrupt latency time. IAR PowerPac RTOS has its own interrupt stack (usage optional). as well as create. semaphores. Frame application for an easy start. Nested interrupts are permitted. Initialization of microcontroller hardware as sources (BSP). Debug version performs runtime checks. Minimum RAM usage. yet small code. Interrupts can wake up or suspend tasks and directly communicate with tasks using all available communication instances (mailboxes.● ● ● ● ● ● ● ● ● ● ● Full interrupt support: Interrupts can call any function except those that require waiting for data. events). API can be called from assembly. delete or change the priority of a task. Very fast and efficient. Core written in assembly language. IAR PowerPac™ RTOS 12 User Guide PPRTOS-3 . simplifying development.

both program (ROM) and RAM size are smaller. calling OS functions to execute the appropriate operations (task level). Single-task systems (superloop) A superloop application is basically a program that runs in an endless loop. However. Also.Basic concepts Tasks In this context. PPRTOS-3 13 . a task is a program running on the CPU core of a microcontroller. Multitasking systems In a multitasking system. Real-time behavior is therefore poor. Task level Superloop Interrupt level ISR Time ISR ISR (nested) Of course. superloops can become difficult to maintain if the program becomes too large. Because one software component cannot be interrupted by another component (only by ISRs). the reaction time of one component depends on the execution time of all other components in the system. No real-time kernel is used. A real-time operating system allows the execution of multiple tasks on a single CPU. meaning that the RTOS can activate and deactivate every task. Without a multitasking kernel (an RTOS). because no real-time kernel is used and only one stack is used. there are different scheduling systems in which the calculation power of the CPU can be distributed among tasks. so interrupt service routines (ISRs) must be used for real-time parts of the software or critical operations (interrupt level). This type of system is typically used in small. there are fewer preemption and synchronization problems with a superloop application. All tasks execute as if they completely “owned” the entire CPU. The tasks are scheduled. This is called a single-task system. uncomplex systems or if real-time behavior is not critical. only one task can be executed by the CPU at a time.

Even if an ISR makes a higher-priority task ready to run. which means that other tasks have no chance of being executed by the CPU while the first task is being carried out. the interrupted task will be returned to and finished before the task switch is made. If they do not.COOPERATIVE MULTITASKING Cooperative multitasking expects cooperation of all tasks. This is illustrated in the diagram below. Low priority task Executing task is interrupted ISR ISR puts high priority task in READY state Time Interrupted task is completed High priority task Higher priority task Is executed IAR PowerPac™ RTOS 14 User Guide PPRTOS-3 . Tasks can only be suspended by calling a function of the operating system. the system “hangs”.

waiting for event.Basic concepts PREEMPTIVE MULTITASKING Real-time systems like IAR PowerPac RTOS operate with preemptive multitasking only. The task which is currently executing is referred to as the active task. whether it is an interrupted task or not. if the response time is not an issue. Round-robin scheduling can be illustrated as follows: All tasks are on the same level. A real-time operating system needs a regular timer-interrupt to interrupt tasks at defined times and to perform task-switches if necessary. and may be defined individually for every task. This time is called timeslice. called schedulers. The scheduler selects one of the tasks in the READY state and activates it (executes the program of this task). If an ISR makes a higher priority task ready. All schedulers have one thing in common: they distinguish between tasks that are ready to be executed (in the READY state) and the other tasks that are suspended for any reason (delay. It works well if you do not need to guarantee response time. and so on). a task switch will occur and the task will be executed before the interrupted task is returned to. The highestpriority task in the READY state is therefore always executed. activates the next task that is in the READY state. or if all tasks have the same priority. waiting for semaphore. Low priority task Executing task is interrupted ISR ISR puts high priority task in READY state. The main difference between schedulers is in how they distribute the computation time between the tasks in READY state. the possession of the CPU changes periodically after a predefined execution time. PPRTOS-3 15 . Round-robin can be used with either preemptive or cooperative multitasking. waiting for mailbox. ROUND-ROBIN SCHEDULING ALGORITHM With round-robin scheduling. task switch occurs High priority task Higher priority task Is executed Time Interrupted task is completed Scheduling There are different algorithms that determine which task to execute. the scheduler has a list of tasks and. when deactivating the active task.

While the display is being updated. but because it cannot guarantee a specific reaction time. or make sure that a resource is used by no more than one task at a time. COMMUNICATION MECHANISMS When multiple tasks work with one another. It is more efficient to assign a different priority to each task. In certain situations. The order of execution depends on this priority. different tasks require different response times. the low-priority task that is blocking the highest-priority task gets assigned the highest priority until it releases the resource. the motor needs to be controlled. One hint at this point: round-robin scheduling is a nice feature because you do not have to think about whether one task is more important than another. Communication between tasks In a multitasking (multithreaded) program. However. This is known as priority inversion. For example. and a display. Roundrobin might work. it immediately becomes the active task. they often have to: ● ● ● exchange data. every task is assigned a priority. For these purposes IAR PowerPac RTOS offers mailboxes. known as critical regions. but most of the time this method has various disadvantages. it will sometimes be necessary for them to exchange information with each other. which will avoid unnecessary task switches. This means that every time a task with higher priority than the active task gets ready. multiple tasks work completely separately. But what happens if the highest-priority task is blocked because it is waiting for a resource owned by a lower-priority task? According to the above rule. The other rule is: No rule without exception. Tasks with identical priority cannot block each other for longer than their timeslices. queues. an improved algorithm should be used. if you want to synchronize a task to start when the value of a global variable changes. This makes preemptive multitasking a must. PRIORITY INVERSION The rule to go by for the scheduler is: Activate the task that has the highest priority of all tasks in the READY state. the motor usually requires faster reaction time than the keyboard and display. synchronize with another task. it would wait until the low-priority-task becomes active again and releases the resource. Because they all work in the same application. you have to poll this variable. To avoid this kind of situation. in an application that controls a motor. a keyboard. IAR PowerPac RTOS uses a priority-controlled scheduling algorithm with round-robin between tasks of identical priority. IAR PowerPac™ RTOS 16 User Guide PPRTOS-3 . unblocking the task which originally had highest priority. For example. because it will constantly switch between the identical-priority tasks. In priority-controlled scheduling. it can make sense for tasks to communicate via global variables. The rule is very simple: Note:The scheduler activates the task that has the highest priority of all tasks in the READY state. wasting precious calculation time and power. and the reaction time depends on how often you poll.PRIORITY-CONTROLLED SCHEDULING ALGORITHM In real-world applications. semaphores and events. the scheduler can be switched off in sections of a program where task switches are prohibited. But round-robin scheduling also costs time if two or more tasks of identical priority are ready and no task of higher priority is ready. GLOBAL VARIABLES The easiest way to do this is by using global variables.

Each task can have a different stack size. EVENTS A task can wait for a particular event without using any calculation time. Switching stacks The following diagram demonstrates the process of switching from one stack to another. This saves a great deal of calculation power and ensures that the task can respond to the event without delay. although counting semaphores are also used. waiting. It works without conflicts even if multiple tasks and interrupts try to access it simultaneously. a received command or character. and temporary storage of intermediate calculation results and register values. The stack has the same function as in a single-task system: storage of return addresses of function calls. The most common are resource semaphores. PPRTOS-3 17 . How task-switching works A real-time multitasking system lets multiple tasks run like multiple single-task programs. automatically switches to this task. residing in a RAM area that can be accessed by the stack pointer A task control block. and every message is allowed to have an individual size. This information allows an interrupted task to continue execution exactly where it left off. A task consists of three parts in the multitasking world: ● ● ● The program code. refer to the Chapter Task Events on page 77 and Chapter Event objects on page 83. For more information. It contains status information of the task. A queue works in a similar manner. current task status (ready. parameters and local variables. Typical applications for events are those where a task waits for data. which usually resides in ROM (though it does not have to) A stack. The idea is as simple as it is convincing. see the Chapter Mailboxes on page 61 and Chapter Queues on page 71. residing in RAM. refer to the Chapter Resource semaphores on page 49 and Chapter Counting Semaphores on page 55. IAR PowerPac RTOS also automatically activates any task that is waiting for a message in a mailbox the moment it receives new data and. including the stack pointer. For details and examples. on a single CPU. task priority. if necessary.Basic concepts MAILBOXES AND QUEUES A mailbox is basically a data buffer managed by the RTOS and is used for sending a message to a task. but handles larger messages than mailboxes. there is no sense in polling if we can simply activate a task the moment the event that it is waiting for occurs. SEMAPHORES Two types of semaphores are used for synchronizing tasks and to manage resources. The task control block (TCB) is a data structure assigned to a task when it is created. or the pulse of an external real-time clock. TCBs are only accessed by the RTOS. More information can be found in the chapter Stacks on page 97. quasi-simultaneously. For further details. a pressed key. reason for suspension) and other management data.

addresses CPU registers SP SP Free Stack area Free Stack area Scheduler CPU Change of task status A task may be in one of several states at any given time. storage ret. it is automatically put into the READY state (TS_READY). It then activates the higher-priority task (Task n) by loading the stack pointer (SP) and the processor registers from the values stored on Task n's stack. If a task with higher priority becomes READY. When a task is created. this higher priority task is activated and the preempted task remains in the READY state. addresses CPU registers Task Control block Stack variables temp. Only one task may be active at a time. Task 0 Task Control block Task n Stack variables temp. storage ret.The scheduler deactivates the task to be suspended (Task 0) by saving the processor registers on its stack. A task in the READY state is activated as soon as there is no other READY task with higher priority. IAR PowerPac™ RTOS 18 User Guide PPRTOS-3 .

() or delay expiration Blocked How the OS gains control When the CPU is reset. The startup code performs the following: ● ● ● Loads the stack pointers with the default values. Initializes all data segments to their respective values. the task is put into the waiting state and the next highest priority task in the READY state is activated. This start address is in a startup module shipped with the C compiler. which for most CPUs is the end of the defined stack segment(s). Not existing OS_CreateTask() OS_CreateTaskEx() OS_Terminate() Ready Scheduler Running API class such as OS_Delay() OS_Wait_. the main() routine is part of your program which takes control immediately after the C startup.. in this case it is put into the DELAY state (TS_DELAY) and the next highest priority task in the READY state is activated. or queue). After reset. program execution begins. IAR PowerPac RTOS works with the standard C startup module without any modification. The active task may also have to wait for an event (or semaphore. The following illustration shows all possible task states and transitions between them. they are documented in the startup file which is shipped with IAR PowerPac RTOS. Calls the main() routine. main() creates one or more tasks and then starts multitasking by calling OS_Start(). OS_Start() PPRTOS-3 19 .Basic concepts The active task may be delayed for or until a specified time. Basically. In a single-task-program. Startup code main() OS_IncDI() OS_InitKern() OS_InitHW() Additional initialization code.() API class such as OS_Signal... and is part of the standard library. mailbox. If the event has not yet occurred. creating at least one task.. it has either not been created yet or it has been terminated. If there are any changes required. A non-existent task is one that is not yet available to IAR PowerPac RTOS. the special-function registers are set to their respective values. the scheduler controls which task is executed. The main() routine is still part of your application program. From then on. The PC register is set to the start address defined by the start vector or start address (depending on the CPU).

} } /* Task stacks */ /* Task-control-blocks */ IAR PowerPac™ RTOS 20 User Guide PPRTOS-3 . A typical main() looks similar to the following example: Example /*********************************************************************** * * main * ************************************************************************ */ void main(void) { OS_InitKern(). TCBLP. the scheduler starts the highest-priority task that has been created in main(). These modules usually have an initialization routine. OS_Start(). /* Start multitasking */ } With the call to OS_Start(). StackLP[128]. The scheduler starts the highest-priority task that has been created in main(). because those tasks are executed only after the call to OS_Start().H" OS_STACKPTR int StackHP[128]. Example #include "RTOS. MODULE5_Init(). Additional Information OS_InitKern() is always the first function which should be called in main(). which creates the required task(s) and/or control structures.The main() routine will not be interrupted by any of the created tasks..c) */ /* Call Init routines of all program modules which in turn will create the tasks they need . Prototype void OS_InitKern (void). Additional Information This function does not return. A good practice is to write software in the form of modules which are (up to a point) reusable. /* Initialize Hardware for OS (in RtosInit. OS_Start() Description Starts multitasking. /* Initialize OS (should be first !) */ OS_InitHW(). OS_TASK TCBHP. static void HPTask(void) { while (1) { OS_Delay (10). Note that OS_Start() is called only once during the startup process and does not return. MODULE4_Init(). It is therefore usually recommended to create all or most of your tasks here. Prototype void OS_Start (void). as well as your control structures such as mailboxes and semaphores.. MODULE3_Init(). (Order of creation may be important) */ MODULE1_Init(). MODULE2_Init(). OS_InitKern() Description Initializes all RTOS variables which require a non zero initial value for arithmetic types or a non NULL pointer value for pointer types.

Does not support round robin scheduling and task names. /* initialize Hardware for OS /* You need to create at least one task here ! OS_CREATETASK(&TCBHP. the performance (and resource usage) is not as important as in the final version which usually goes as release version into the product. } } /********************************************************************* * * main * *********************************************************************/ void main(void) { OS_IncDI(). "LP Task". But during development. IAR PowerPac RTOSIAR PowerPac RTOSLIST OF LIBRARIES In your application program. StackHP). but it will not catch these errors. OS_CREATETASK(&TCBLP. Same as release. Of course. Maximum runtime checking. HPTask. Small. OS_Start(). Build Define Description XR: R: S: D: Extreme Release Release Stack check Debug OS_LIBMODE_XR OS_LIBMODE_R OS_LIBMODE_S OS_LIBMODE_D Smallest fastest build. /* Start multitasking } */ */ */ */ */ Different builds of IAR PowerPac RTOS IAR PowerPac RTOS comes in different builds. you may also use the release version of IAR PowerPac RTOS during development. plus stack checking. you need to let the compiler know which build of IAR PowerPac RTOS you are using. This concept gives you the best of both worlds: a compact and very efficient build for your final product (release or stack check versions of the libraries). While developing software. and a safer (though bigger and slower) version for development which will catch most of the common application programming errors. 50.Basic concepts static void LPTask(void) { while (1) { OS_Delay (50). StackLP). 100. LPTask. or versions of the libraries. "HP Task". The reason for different builds is that requirements vary during development. fast build. Table 1: List of libraries PPRTOS-3 21 . /* Initially disable interrupts OS_InitKern(). This is done by defining a single identifier prior to including RTOS. even small programming errors should be caught by use of assertions.h. normally used for the release version of your application. /* initialize OS OS_InitHW(). These assertions are compiled into the debug version of the IAR PowerPac RTOS libraries and make the code a bit bigger (about 50%) and also slightly slower than the release or stack check version used for the final product.

IAR PowerPac™ RTOS 22 User Guide PPRTOS-3 .

or it must terminate itself (see examples below). The task routine must not return. API function Routine Description OS_CREATETASK() OS_CreateTask() OS_CREATETASK_EX() OS_CreateTaskEx() OS_Delay() OS_DelayUntil() OS_SetPriority() OS_GetPriority() OS_SetTimeSlice() OS_Suspend() Table 1: Task routine API list Creates a task. IAR PowerPac RTOS offers a simple macro that makes this easy and which is fully sufficient in most cases. EXAMPLE OF TASK ROUTINE AS AN ENDLESS LOOP /* Example of a task routine as an endless loop */ void Task1(void) { while(1) { DoSomething() /* Do something */ OS_Delay(1). /* Give other tasks a chance */ } } EXAMPLE OF TASK ROUTINE THAT TERMINATES ITSELF /* Example of a task routine that terminates void Task2(void) { char DoSomeMore. Suspends the specified task. using the macro as in the example start project works fine. at least initially. if you are dynamically creating and deleting tasks. do { DoSomeMore = DoSomethingElse() /* Do something OS_Delay(1). Suspends the calling task until a specified time. a routine is available allowing “fine-tuning” of all parameters. Suspends the calling task for a specified period of time. in which case OS_CreateTaskEx() is used to create it. Creates a task. OS_Terminate(0). Creates a task with parameter. The following rules apply to task routines: ● ● ● The task routine can either not take parameters (void parameter list). However.Tasks Introduction A task that should run under IAR PowerPac RTOS needs a task control block (TCB). Assigns a specified priority to a specified task. Creates a task with parameter. For most applications. /* Give other tasks a chance } while(DoSomeMore). /* Terminate yourself } */ */ */ */ There are different ways to create a task. a stack. in which case OS_CreateTask() is used to create it or take one void pointer as parameter. and a normal routine written in C. Returns the priority of a specified task Assigns a specified timeslice value to a specified task. PPRTOS-3 23 . The task routine should be implemented as an endless loop.

The absolute value of Priority is of no importance. unsigned char Priority. Important The stack that you define has to reside in an area that the CPU can actually use as stack. because it has fewer parameters and is therefore easier to use. Pointer to a routine that should run as a task Priority of the task. Pointer to an area of memory in RAM that will serve as stack area for the task. Determines whether a task control block actually belongs to a valid task. It creates a task and makes it ready for execution by putting it in the READY state. Most CPUs cannot use the entire memory area as stack. Most CPUs require alignment of the stack in multiples of bytes. Some CPUs and standards force other alignment values. either from main() during initialization or from any other task. only the value in comparison to the priorities of other tasks. the new task will be placed right before it. char* pName. IAR PowerPac™ RTOS 24 User Guide PPRTOS-3 . This macro is normally used for creating a task instead of the function call OS_CreateTask(). Description Parameter pTask pName pRoutine Priority Pointer to a data structure of type OS_TASK which will be used as task control block (and reference) for this task. void* pStack). when the task stack is defined as an array of integers. Ends delay of a task immediately. void* pRoutine. Pointer to the name of the task. This is possible only if the memory area has been defined at compile time. if the suspend count reaches zero. This is automatically done. See the device specific manual for further details. If there is another task with the same priority. OS_CREATETASK() can be called at any time. Returns the ID of the currently running task. The recommended strategy is to create all tasks during initialization in main() to keep the structure of your tasks easy to understand. The newly created task will be activated by the scheduler as soon as there is no other task with higher priority in the READY state. pStack Table 2: OS_CREATETASK() parameter list Additional Information OS_CREATETASK() is a macro calling an OS library function. using sizeof().Routine Description OS_Resume() OS_GetSuspendCnt() OS_Terminate() OS_WakeTask() OS_IsTask() OS_GetTaskID() OS_GetpCurrentTask() Table 1: Task routine API list Decrements the suspend count of specified task and resumes the task. Ends (terminates) a task. Can be NULL (or 0) if not used. OS_CREATETASK() determines the size of the stack automatically. Must be within the following range: 1 <= Priority <=255 Higher values indicate higher priorities. Returns the suspension count. Returns a pointer to the task control block structure of the currently running task. OS_CREATETASK() Description Creates a task. Prototype void OS_CREATETASK (OS_TASK* pTask. The size of this block of memory determines the size of the stack area.

Tasks Example OS_STACKPTR int UserStack[150]. "UserTask".TimeSlice denotes the time in IAR PowerPac RTOS timer ticks that the task will run until it suspends. This is automatically done. when the task stack is defined as an array of integers. The task can be dynamically created because the stack size is not calculated automatically as it is with the macro. Important The stack that you define has to reside in an area that the CPU can actually use as stack. Pointer to a routine that should run as task Pointer to an area of memory in RAM that will serve as stack area for the task. The size of this block of memory determines the size of the stack area. Priority of the task. /* Stack-space */ OS_TASK UserTCB. Most CPUs require alignment of the stack in multiples of bytes. } OS_CreateTask() Description Creates a task. StackSize. UserStack). Has an effect only if other tasks are running at the same priority. Some CPUs and standards force other alignment values. Prototype void OS_CreateTask (OS_TASK* char* unsigned char voidRoutine* void* unsigned unsigned char Parameter Description pTask. Must be within the following range: 1 <= Priority <=255 Higher values indicate higher priorities. UserTask. except that all parameters of the task can be specified. pRoutine pStack StackSize TimeSlice Table 3: OS_CreateTask() parameter list Additional Information This function works the same way as OS_CREATETASK(). /* Task-control-blocks */ void UserTask(void) { while (1) { Delay (100). 100. pStack. } } void InitTask(void) { OS_CREATETASK(&UserTCB. This parameter has no effect on some ports of IAR PowerPac RTOS for efficiency reasons. Priority.) pTask pName Priority Pointer to a data structure of type OS_TASK which will be used as the task control block (and reference) for this task. PPRTOS-3 25 . thus enabling another task with the same priority. See the device specific manual for further details. pName. Pointer to the name of the task. TimeSlice). Can be NULL (or 0) if not used. pRoutine. Most CPUs cannot use the entire memory area as stack. Size of the stack Time slice value for round-robin scheduling.

void* pContext). StackClock[50]. Priority of the task. } OS_CREATETASK_EX() Description Creates a task and passes a parameter to the task. Pointer to an area of memory in RAM that will serve as stack area for the task. Using a void pointer as additional parameter gives the flexibility to pass any kind of data to the task function. Example The following example is delivered in the RTOS\Application folder of IAR PowerPac RTOS. Must be within the following range: 1 <= Priority <=255 Higher values indicate higher priorities. StackMain. void Clock(void) { while(1) { /* Code to update the clock */ } } void Main(void) { while (1) { /* Your code */ } } void InitTask(void) { OS_CreateTask(&TaskMain. but allows passing a parameter to the task. OS_SEMA SemaLCD. void* pRoutine. Can be NULL (or 0) if not used. char* pName.c Purpose : Sample program for IAR PowerPac RTOS using OC_CREATETASK_EX --------. Pointer to a routine that should run as a task. NULL. pStack pContext Table 4: OS_CREATETASK_EX() parameter list Additional Information OS_CREATETASK_EX() is a macro calling an IAR PowerPac RTOS library function. 100. void* pStack.2). It works like OS_CREATETASK(). Clock. Prototype void OS_CREATETASK_EX (OS_TASK* pTask. The size of this block of memory determines the size of the stack area. /*-----------------------------------------------------------------File : Main_TaskEx. Pointer to the name of the task. 50. Description Parameter pTask pName pRoutine Priority Pointer to a data structure of type OS_TASK which will be used as task control block (and reference) for this task. Parameter passed to the created task function. OS_CreateTask(&TaskClock.StackClock. unsigned char Priority.sizeof(StackClock). Main.END-OF-HEADER --------------------------------------------*/ IAR PowerPac™ RTOS 26 User Guide PPRTOS-3 . 2). NULL. OS_TASK TaskMain.Example /* Demo-program to illustrate the use of OS_CreateTask */ OS_STACKPTR int StackMain[100].TaskClock. sizeof(StackMain).

/* Start multitasking */ return 0. Parameter passed to the created task. An example of passing parameters to tasks is shown under OS_CREATETASK_EX(). Must be within the following range: 1 <= Priority <=255 Higher values indicate higher priorities. OS_CREATETASK_EX(&TCBLP. TCBLP. This parameter has no effect on some ports of IAR PowerPac RTOS for efficiency reasons. TimeSlice. pContext). /* Task-control-blocks */ /********************************************************************/ static void TaskEx(void* pData) { while (1) { OS_Delay ((OS_TIME) pData).) pTask pName Priority Pointer to a data structure of type OS_TASK which will be used as the task control block (and reference) for this task. "LP Task". StackLP[128]. StackSize. (void*) 50). TaskEx.TimeSlice denotes the time in IAR PowerPac RTOS timer ticks that the task will run until it suspends. Pointer to an area of memory in RAM that will serve as stack area for the task. OS_SendString("Start project will start multitasking !\n"). 100. /* initialize OS */ OS_InitHW(). Size of the stack Time slice value for round-robin scheduling. pName. pRoutine. } } /********************************************************************* * * main * *********************************************************************/ int main(void) { OS_IncDI(). TaskEx. /* Task stacks */ OS_TASK TCBHP.Tasks #include "RTOS. The size of this block of memory determines the size of the stack area. Prototype void OS_CreateTaskEx (OS_TASK* char* unsigned char voidRoutine* void* unsigned unsigned char void* Parameter Description pTask. OS_Start(). /* initialize Hardware for OS */ /* You need to create at least one task before calling OS_Start() */ OS_CREATETASK_EX(&TCBHP. Has an effect only if other tasks are running at the same priority. /* Initially disable interrupts */ OS_InitKern().h" OS_STACKPTR int StackHP[128]. } OS_CreateTaskEx() Description Creates a task and passes a parameter to the task. except that a parameter is passed to the task function. "HP Task". Priority. Pointer to the name of the task. (void*) 200). pRoutine pStack StackSize Timeslice pContext Table 5: OS_Create_Task_Ex() parameter list Additional Information This function works the same way as OS_CreateTask(). Priority of the task. pStack. PPRTOS-3 27 . thus enabling another task with the same priority. StackLP. Pointer to a routine that should run as task. Can be NULL (or 0) if not used. 50. StackHP.

depending on when the interrupt for the scheduler will occur. min++. while (1) { ShowTime(). OS_DelayUntil (t0 += 1000). the task is made ready again and activated according to the rules of the scheduler. The parameter ms specifies the precise interval during which the task has to be suspended specified in basic time intervals (usually 1/1000 sec.OS_Time) <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= (t . Parameter Description t Time to delay until. OS_Delay (5000). printf("The next output will occur in 5 seconds"). Must be within the following range: 1 <= ms <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= ms <= 231-1 = 0x7FFFFFFF for 32-bit CPUs Table 6: OS_Delay() parameter list Additional Information The calling task will be put into the TS_DELAY state for the period of time specified. printf("Delay is over"). After the expiration of a delay.OS_Time) <= 231-1 = 0x7FFFFFFF for 32-bit CPUs Table 7: OS_DelayUntil() parameter list Additional Information The calling task will be put into the TS_DELAY state until the time specified. Parameter Description ms Time interval to delay.OS_Delay() Description Suspends the calling task for a specified period of time. Example void Hello() { printf("Hello"). The task will stay in the delayed state until the specified time has expired. The actual delay (in basic time intervals) will be in the following range: ms . A delay can be ended prematurely by another task or by an interrupt handler calling OS_WakeTask(). Prototype void OS_DelayUntil (int t). } OS_DelayUntil() Description Suspends the calling task until a specified time.1 <= delay <= ms. } } } /* Routine to display time */ IAR PowerPac™ RTOS 28 User Guide PPRTOS-3 . else { sec=0. The OS_DelayUntil() function delays until the value of the time-variable OS_Time has reached a certain value.min. Prototype void OS_Delay (int ms).). if (sec < 59) sec++. Must be within the following range: 1 <= (t . It is very useful if you have to avoid accumulating delays. Example int sec. void TaskShowTime() { int t0 = OS_GetTime().

int GlobalVar.Tasks In the example above. A major advantage is that the task extension is task specific. The save and restore functions have to be declared according the function type used in the structure. OS_ExtendTaskContext() is not available in the XR libraries. */ typedef struct { int GlobalVar. Additional. The same thing is true for the required stack space: Add. making the C library functions thread-safe. Example The following example is delivered in the RTOS\Application folder of IAR PowerPac RTOS. Co-processor registers such as registers of a VFP (floating-point coprocessor). OS_TASK TCBHP. how the task stack has to be addressed to save and restore the extended task context. /*-------------------------------------------------------------------File : ExtendTaskContext. TCBLP.c Purpose : Sample program for IAR PowerPac RTOS demonstrating how to dynamically extend the task context. Table 8: OS_ExtendTaskContext() parameter list Additional Information The OS_EXTEND_TASK_CONTEXT structure is defined as follows: typedef struct OS_EXTEND_TASK_CONTEXT { void (*pfSave) ( void * pStack). but are not limited to: ● ● ● ● Global variables such as “errno” in the C-library. the extended task context consists of just a single * member. } OS_EXTEND_TASK_CONTEXT. -------. /* Task stacks */ /* Task-control-blocks */ /********************************************************************* * * _Restore * _Save * * Function description * This function pair saves and restores an extended task context. void (*pfRestore)(const void * pStack). OS_ExtendTaskContext() Description The function may be used for a variety of purposes. which is a global variable. The advantage is that the task switching time of the other tasks is not affected.h" OS_STACKPTR int StackHP[128].END-OF-HEADER ----------------------------------------------*/ #include "RTOS. Prototype void OS_ExtendTaskContext(const OS_EXTEND_TASK_CONTEXT * pExtendContext). The example below shows. This means that the additional information (such as floating-point registers) needs to be saved only by tasks that actually use these registers. stack space is required only for the tasks which actually save the additional registers. StackLP[128]. PPRTOS-3 29 . * In this case. Data registers of an additional hardware unit such as a CRC calculation unit This allows you to extend the task context as required by his system. This example adds a global variable to the task context of certain tasks. Parameter Description pExtendContext Pointer to the OS_EXTEND_TASK_CONTEXT structure which contains the addresses of the specific save and restore functions which save and restore the extended task context during task switches. optional CPU / registers such as MAC / EMAC registers (multiply and accumulate unit) if they are not saved in the task context by default. Typical applications include. the use of OS_Delay() could lead to accumulating delays and would cause the simple “clock” to be slow.

LPTask. } } /********************************************************************* * * LPTask * * Function description * During the execution of this function. /********************************************************************/ /********************************************************************* * * HPTask * * Function description * During the execution of this function. } IAR PowerPac™ RTOS 30 User Guide PPRTOS-3 . /* Initially disable interrupts */ OS_InitKern(). 100. while (1) { OS_Delay (50). _Restore }. StackLP). */ static void LPTask(void) { OS_ExtendTaskContext(&_SaveRestore). OS_CREATETASK(&TCBLP. GlobalVar = 2.OS_STACK_AT_BOTTOM).} CONTEXT_EXTENSION. // // Save all members of the structure // p->GlobalVar = GlobalVar. HPTask. "HP Task". } } /********************************************************************* * * main */ int main(void) { OS_IncDI(). static void _Save(void * pStack) { CONTEXT_EXTENSION * p. // // Restore all members of the structure // GlobalVar = p->GlobalVar. OS_Start(). StackHP). /* initialize Hardware for OS */ /* You need to create at least one task here ! */ OS_CREATETASK(&TCBHP.(1 .OS_STACK_AT_BOTTOM). 50. p = ((CONTEXT_EXTENSION*)pStack) . /* Start multitasking */ return 0. */ static void HPTask(void) { OS_ExtendTaskContext(&_SaveRestore). } // Create pointer // Create pointer /********************************************************************* * * Global variable which holds the function pointers * to save and restore the task context. /* initialize OS */ OS_InitHW(). p = ((CONTEXT_EXTENSION*)pStack) . } static void _Restore(const void * pStack) { CONTEXT_EXTENSION * p. the thread-specific * global variable has always the same value of 1. */ const OS_EXTEND_TASK_CONTEXT _SaveRestore = { _Save. while (1) { OS_Delay (10). GlobalVar = 1.(1 . the thread-specific * global variable has always the same value of 2. "LP Task".

Tasks OS_GetpCurrentTask() Description Returns a pointer to the task control block structure of the currently running task. Return value OS_TASK*: A pointer to the task control block structure. This function can be used for examining whether a task is suspended by previous calls of OS_Suspend(). Additional Information If pTask is the NULL pointer. OS_GetPriority() Description Returns the priority of a specified task. Parameter Description pTask Pointer to a data structure of type OS_TASK. The release version of IAR PowerPac RTOS cannot check the validity of pTask and may therefore return invalid values if pTask does not specify a valid task. Additional Information This function can be used for determining which task is executing. 0: Task is not suspended. PPRTOS-3 31 . Table 10: OS_GetSuspendCnt() parameter list Return value Suspension count of the specified task as an unsigned character value. >0: Task is suspended by at least one call of OS_Suspend(). OS_GetSuspendCnt() Description The function returns the suspension count and thus suspension state of the specified task. Table 9: OS_GetPriority() parameter list Return value Priority of the specified task as an unsigned character (range 1 to 255). If pTask does not specify a valid task. Parameter Description pTask Pointer to a data structure of type OS_TASK. the function returns the priority of the currently running task. Prototype unsigned char OS_GetPriority (OS_TASK* pTask). Prototype unsigned char OS_GetSuspendCnt (OS_TASK* pTask). Prototype OS_TASK* OS_GetpCurrentTask (void). the debug version of IAR PowerPac RTOS calls OS_Error(). Important This function may not be called from within an interrupt handler. This can be helpful if the reaction of any function depends on the currently running task.

Table 11: OS_IsTask() parameter list Return value Character value: 0: TCB is not used by any task 1: TCB is used by a task Additional Information This function checks if the specified task is still in the internal task list. IAR PowerPac™ RTOS 32 User Guide PPRTOS-3 . } } OS_GetTaskID() Description Returns the ID of the currently running task. Additional Information This function can be used for determining which task is executing. This can be helpful if the reaction of any function depends on the currently running task.Additional Information If pTask does not specify a valid task. Parameter Description pTask Pointer to a data structure of type OS_TASK which is used as task control block (and reference) for this task. Prototype char OS_IsTask (OS_TASK* pTask). OS_IsTask() might be called prior to calling OS_GetSuspendCnt() to examine whether the task is valid. When tasks are created and terminated dynamically. A value of 0 (NULL) indicates that no task is executing. Example /* Demo-function to illustrate the use of OS_GetSuspendCnt() */ void ResumeTask(OS_TASK* pTask) { unsigned char SuspendCnt. /* May cause a task switch */ SuspendCnt--. The release version of IAR PowerPac RTOS can not check the validity of pTask and might therefore return invalid values if pTask does not specify a valid task. while(SuspendCnt > 0) { OS_Resume(pTask). Prototype OS_TASKID OS_GetTaskID (void). the debug version of IAR PowerPac RTOS calls OS_Error(). OS_IsTask() Description Determines whether a task control block actually belongs to a valid task. If the task was terminated. if the suspend count reaches zero. SuspendCnt = OS_GetSuspendCnt(pTask). it is removed from the internal task list. Return value OS_TASKID: A pointer to the task control block. The returned value can be used for resuming a suspended task by calling OS_Resume() as often as indicated by the returned value. This function can be useful to determine whether the task control block and stack for the task may be reused for another task in applications that create and terminate tasks dynamically. OS_Resume() Description Decrements the suspend count of the specified task and resumes it.

the OS_Resume() function checks the suspend count of the specified task. Important This function may not be called from within an interrupt handler. Prototype void OS_SetTaskNamePriority (OS_TASK* pTask. Must be within the following range: 1 <= Priority <= 255 Higher values indicate higher priorities. OS_SetTimeSlice() Description Assigns a specified timeslice value to a specified task. OS_SetPriority() Description Assigns a specified priority to a specified task. When pTask is the NULL pointer.Tasks Prototype void OS_Resume (OS_TASK* pTask). const char* s). the task will be set back in ready state and continues operation according to the rules of the scheduler. Pointer to a zero terminated string which is used as task name. the execution of the specified task is resumed. Prototype void OS_SetPriority (OS_TASK* pTask. If the suspend count is 0 when OS_Resume() is called. Parameter Description pTask Pointer to a data structure of type OS_TASK which is used as task control block (and reference) for the task that should be suspended. Table 12: OS_Resume() parameter list Additional Information The specified task's suspend count is decremented. Parameter Description pTask s Pointer to a data structure of type OS_TASK. Priority of the task. OS_SetTaskName() Description Allows modification of a task name at runtime. the name of the currently running task is modified. Table 14: OS_SetTaskName() parameter list Additional Information Can be called at any time from any task or software timer. Parameter Description pTask Priority Pointer to a data structure of type OS_TASK. If the task is not blocked by other task blocking mechanisms. the specified task is not currently suspended and OS_Error() is called with error OS_ERR_RESUME_BEFORE_SUSPEND. If the resulting value is 0. unsigned char Priority). Table 13: OS_SetPriority() parameter list Additional Information Can be called at any time from any task or software timer. In debug versions of IAR PowerPac RTOS. PPRTOS-3 33 . Calling this function might lead to an immediate task switch.

Table 17: OS_Terminate() parameter list Additional Information If pTask is the NULL pointer. It can only be restarted by a call of OS_Resume(). The specified task will terminate immediately. IAR PowerPac™ RTOS 34 User Guide PPRTOS-3 . The new timeslice value is interpreted as a reload value. In debug versions of IAR PowerPac RTOS. Setting the timeslice value only affects the tasks running in round-robin mode. OS_Terminate() Description Ends (terminates) a task. Must be within the following range: 1 <= TimeSlice <= 255. Table 15: OS_SetTimeSlice() parameter list Return value Previous timeslice value of the task as unsigned char. the task is suspended. If the function succeeds. Prototype void OS_Terminate (OS_TASK* pTask). calling OS_Suspend() more often than OS_MAX_SUSPEND_CNT times without calling OS_Resume(). It is used after the next activation of the task. the current task suspends. Parameter Description pTask Pointer to a data structure of type OS_TASK which is used as a task control block (and reference) for the task that should be suspended. Table 16: OS_Suspend() parameter list Additional Information If pTask is the NULL pointer. It does not affect the remaining timeslice of a running task. the current task terminates. Parameter Description pTask Pointer to a data structure of type OS_TASK which is used as task control block (and reference) for this task. New timeslice value for the task. Prototype void OS_Suspend (OS_TASK* pTask). unsigned char TimeSlice). Every task has a suspend count with a maximum value of OS_MAX_SUSPEND_CNT. Additional Information Can be called at any time from any task or software timer. Parameter Description pTask TimeSlice Pointer to a data structure of type OS_TASK. If the suspend count is greater than zero. The memory used for stack and task control block can be reassigned. execution of the specified task is suspended and the task's suspend count is incremented. The specified task will be suspended immediately.Prototype unsigned char OS_SetTimeSlice (OS_TASK* pTask. the task's internal suspend count is not incremented and OS_Error() is called with the error OS_ERR_SUSPEND_TOO_OFTEN. OS_Suspend() Description Suspends the specified task. This means that another task with the same priority must exist.

OS_WakeTask() Description Ends delay of a task immediately. Table 18: OS_WakeTask() parameter list Additional Information Puts the specified task. or for some other reason). which is already suspended for a certain amount of time with OS_Delay() or OS_DelayUntil() back to the state TS_READY (ready for execution). this command is ignored. terminating tasks that hold any resources is prohibited. OS_Yield() Description Calls the scheduler to force a task switch. Prototype void OS_WakeTask (OS_TASK* pTask). Any task may be terminated regardless of its state. Important This function may not be called from within an interrupt handler. Parameter Description pTask Pointer to a data structure of type OS_TASK which is used as task control block (and reference) for this task. or the delay has already expired. The specified task will be activated immediately if it has a higher priority than the priority of the task that had the highest priority before. Additional Information If the task is running on round-robin. it will be suspended if there is another task with the same priority ready for execution. If the specified task is not in the state TS_DELAY (because it has already been activated. On 8-bit CPUs. This functionality is default for any 16-bit or 32-bit CPU and may be changed by recompiling IAR PowerPac RTOS sources. PPRTOS-3 35 . the IAR PowerPac RTOS sources have to be recompiled with the compile time switch OS_SUPPORT_CLEANUP_ON_TERMINATE activated. Prototype void OS_Yield (void).Tasks IAR PowerPac RTOSall resources which are held by the terminated task are released. To enable safe termination.

IAR PowerPac™ RTOS 36 User Guide PPRTOS-3 .

For that reason they should be kept short just like interrupt routines. and OS_GetTimerPeriod(). timers run in single-shot mode. Creates a software timer without starting it. This means that only 15-bits can be used on 8/16 bit CPUs. OS_GetTimerValue(). A basically unlimited number of software timers can be defined with the macro OS_CREATETIMER(). so they can be interrupted by any hardware interrupt. but because the timer routine can not be called from a critical region (timers are “put on hold”). the timer is restarted with its initial delay time and therefore works just as a free-running timer. which means they expire only once and call their callback routine only once. Sets a new timer reload value for a specified timer. In most systems. you have to make sure your application uses shorter timeouts. we have assumed that your system spends no more than up to 255 ticks in a row in a critical region and defined a macro which defines the maximum timeout value.h as OS_TIMER_MAX_TIME. Stops a specified timer. started and retriggered much like hardware timers. EXTENDED SOFTWARE TIMER Sometimes it may be useful to pass a parameter to the timer callback function. they have a priority higher than the priority of all tasks. a 32-bit value on 32-bit CPUs. this is no more than a single tick. During critical regions timers may expire. Generally. to be safe. This makes it possible to use one callback function for different software timers. you specify any routine that is to be called after the expiration of the delay. When defining a timer. Another factor to take into account is the maximum time spent in critical regions. It is normally 0x7F00 for 8/16-bit systems or 0x7FFFFF00 for 32-bit Systems and defined in RTOS. By calling OS_RetriggerTimer() from within the callback routine. 31-bits on 32-bit CPUs. Stops and deletes a specified timer. Restarts a specified timer with its initial time value.Software timers Software timer A software timer is an object that calls a user-specified routine after a specified delay. The extended timer structure and related extended timer functions were implemented to allow parameter passing to the callback function. Starts a specified timer. thus a 16-bit value on 8/16-bit CPUs. extended timers behave exactly the same as normal IAR PowerPac RTOS software timers and may be used in parallel with normal software timers. Maximum timeout / period The timeout value is stored as an integer. The comparisons are done as signed comparisons. which is not recommended). Except the different callback function with parameter passing. However. PPRTOS-3 37 . the maximum time that the system spends at once in a critical region needs to be deducted. Timer routines are similar to interrupt routines. (because expired time-outs are permitted). Timers can be stopped. API functions Routine Description OS_CREATETIMER() OS_CreateTimer() OS_StartTimer() OS_StopTimer() OS_RetriggerTimer() OS_SetTimerPeriod() OS_DeleteTimer() Table 1: Software timers API Creates and starts a software-timer. Software timers are called by IAR PowerPac RTOS with interrupts enabled. The state of timers can be checked by the functions OS_GetTimerStatus(). If your system spends more than 255 ticks without break in a critical section (effectively disabling the scheduler during this time.

d).h): #define OS_CREATETIMER(pTimer. OS_TIMERROUTINE* Callback. \ OS_StartTimer(pTimer). the callback routine will be called immediately (unless the task is in a critical region or has interrupts disabled). Returns the remaining timer value of a specified timer. OS_TIMERROUTINE is defined in RTOS.Routine Description OS_GetTimerPeriod() OS_GetTimerValue() OS_GetTimerStatus() OS_GetpCurrentTimer() OS_CREATETIMER_EX() OS_CreateTimerEx() OS_StartTimerEx() OS_StopTimerEx() OS_RetriggerTimerEx() OS_SetTimerPeriodEx() OS_DeleteTimerEx() OS_GetTimerPeriodEx() OS_GetTimerValueEx() OS_GetTimerStatusEx() OS_GetpCurrentTimerEx() Table 1: Software timers API Returns the current reload value of a specified timer. Parameter Description pTimer Callback Timeout Pointer to the OS_TIMER data structure which contains the data of the timer. IAR PowerPac™ RTOS 38 User Guide PPRTOS-3 . Returns the current timer status of a specified extended timer. Sets a new timer reload value for a specified extended timer. in new applications these routines should be called directly instead.h as follows: typedef void OS_TIMERROUTINE(void). Returns the current timer status of a specified timer. therefore valid values are 1 <= Timeout <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= Timeout <= 231-1 = 0x7FFFFFFF for 32-bit CPUs Table 2: OS_CREATETIMER() parameter list Additional Information IAR PowerPac RTOS keeps track of the timers by using a linked list. Returns the remaining timer value of a specified extended timer. Returns the current reload value of a specified extended timer. Returns a pointer to the data structure of the extended timer that just expired. Source of the macro (in RTOS. Starts a specified extended timer. Pointer to the callback routine to be called from the RTOS after expiration of the delay. It is supplied for backward compatibility. Restarts a specified extended timer with its initial time value. Creates an extended software timer without starting it. This macro uses the functions OS_CreateTimer() and OS_StartTimer(). OS_CREATETIMER() Description Macro that creates and starts a software-timer.c. Stops a specified extended timer. Stops and deletes a specified extended timer.c. OS_TIME Timeout). Once the timeout is expired.d) \ OS_CreateTimer(pTimer. Initial timeout in basic IAR PowerPac RTOS time units (nominal ms): The data type OS_TIME defaults to an integer. Returns a pointer to the data structure of the timer that just expired. Creates and starts an extended software-timer. Prototype void OS_CREATETIMER (OS_TIMER* pTimer.

Table 4: OS_StartTimer() parameter list PPRTOS-3 39 . Parameter Description pTimer Callback Timeout Pointer to the OS_TIMER data structure which contains the data of the timer. OS_TIME Timeout). 100). Parameter Description pTimer Pointer to the OS_TIMER data structure which contains the data of the timer. } OS_CreateTimer() Description Creates a software timer (but does not start it). Once the timeout is expired. Timer100. Initial timeout in basic IAR PowerPac RTOS time units (nominal ms): The data type OS_TIME defaults to an integer. OS_TIMERROUTINE is defined in RTOS. Prototype void OS_StartTimer (OS_TIMER* pTimer). OS_RetriggerTimer(&TIMER100). therefore valid values are 1 <= Timeout <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= Timeout <= 231-1 = 0x7FFFFFFF for 32-bit CPUs Table 3: OS_CreateTimer() parameter list Additional Information IAR PowerPac RTOS keeps track of the timers by using a linked list. 100). Pointer to the callback routine to be called from the RTOS after expiration of the delay. Example OS_TIMER TIMER100. } /* Toggle LED */ /* Make timer periodical */ void InitTask(void) { /* Create Timer100. The timer is not automatically started. OS_RetriggerTimer(&TIMER100). } /* Toggle LED */ /* Make timer periodical */ void InitTask(void) { /* Create and start Timer100 */ OS_CREATETIMER(&TIMER100. OS_TIMERROUTINE* Callback. void Timer100(void) { LED = LED ? 0 : 1. void Timer100(void) { LED = LED ? 0 : 1. This has to be done explicitly by a call of OS_StartTimer() or OS_RetriggerTimer(). the callback routine will be called immediately (unless the task is in a critical region or has interrupts disabled). start it elsewhere */ OS_CreateTimer(&TIMER100.Software timers Example OS_TIMER TIMER100. Timer100.h as follows: typedef void OS_TIMERROUTINE(void). Prototype void OS_CreateTimer (OS_TIMER* pTimer. } OS_StartTimer() Description Starts a specified timer.

OS_StopTimer() Description Stops a specified timer. The timer will start with its initial timer value. TimerCursor. Prototype void OS_RetriggerTimer (OS_TIMER* pTimer). Prototype void OS_StopTimer (OS_TIMER* pTimer). Restart a timer which was stopped by calling OS_StopTimer(). but has expired. In this case. } OS_SetTimerPeriod() Description Sets a new timer reload value for a specified timer. /* Make timer periodical */ } void InitTask(void) { /* Create and start TimerCursor */ OS_CREATETIMER(&TIMERCursor.Additional Information OS_StartTimer() is used for the following reasons: ● ● Start a timer which was created by OS_CreateTimer(). Table 6: OS_RetriggerTimer() parameter list Additional Information OS_RetriggerTimer() restarts the timer using the initial time value programmed at creation of the timer or with the function OS_SetTimerPeriod(). BOOL CursorOn. It also has no effect on timers that are not running. /* Invert character at cursor-position */ OS_RetriggerTimer(&TIMERCursor). OS_RetriggerTimer() Description Restarts a specified timer with its initial time value. Important This function has no effect on running timers. void TimerCursor(void) { if (CursorOn) ToggleCursor(). the timer will continue with the remaining time value which was preserved by stopping the timer. IAR PowerPac™ RTOS 40 User Guide PPRTOS-3 . Table 5: OS_StopTimer() parameter list Additional Information The actual value of the timer (the time until expiration) is kept until OS_StartTimer() lets the timer continue. Parameter Description pTimer Pointer to the OS_TIMER data structure which contains the data of the timer. 500). Use OS_RetriggerTimer() to restart those timers. Example OS_TIMER TIMERCursor. Parameter Description pTimer Pointer to the OS_TIMER data structure which contains the data of the timer.

/* Set timer period to 200 ms for further pulses */ OS_SetTimerPeriod(&TIMERPulse. Parameter Description pTimer Pointer to the OS_TIMER data structure which contains the data of the timer. the timer is also marked as invalid. void TimerPulse(void) { if TogglePulseOutput(). } OS_DeleteTimer() Description Stops and deletes a specified timer. TimerPulse. Parameter Description pTimer Pointer to the OS_TIMER data structure which contains the data of the timer. Period is the reload value of the timer to be used as initial value when the timer is retriggered by OS_RetriggerTimer(). Parameter Description pTimer Period Pointer to the OS_TIMER data structure which contains the data of the timer. Timer period in basic IAR PowerPac RTOS time units (nominal ms): The data type OS_TIME defaults to an integer. 500). PPRTOS-3 41 . 200).Software timers Prototype void OS_SetTimerPeriod (OS_TIMER* pTimer. OS_TIME Period). In debug builds of IAR PowerPac RTOS. /* Toggle output */ OS_RetriggerTimer(&TIMERCursor). which is defined as an integer between 1 and 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs and as an integer between 1 and <= 231-1 = 0x7FFFFFFF for 32-bit CPUs. therefore valid values are 1 <= Timeout <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= Timeout <= 231-1 = 0x7FFFFFFF for 32-bit CPUs Table 7: OS_SetTimerPeriod() parameter list Additional Information OS_SetTimerPeriod() sets the initial time value of the specified timer. Example OS_TIMER TIMERPulse. Table 9: OS_GetTimerPeriod() parameter list Return value Type OS_TIME. OS_GetTimerPeriod() Description Returns the current reload value of a specified timer. BOOL CursorOn. Table 8: OS_DeleteTimer() parameter list Additional Information The timer is stopped and therefore removed out of the linked list of running timers. which is the permitted range of timer values. /* Make timer periodical */ } void InitTask(void) { /* Create and start Pulse Timer with first pulse = 500ms */ OS_CREATETIMER(&TIMERPulse. Prototype OS_TIME OS_GetTimerPeriod (OS_TIMER* pTimer). Prototype void OS_DeleteTimer (OS_TIMER* pTimer).

Table 11: OS_GetTimerStatus parameter list Return value Unsigned character. OS_GetpCurrentTimer() Description Returns a pointer to the data structure of the timer that just expired. Prototype unsigned char OS_GetTimerStatus (OS_TIMER* pTimer). this function can be used for examining the timer that expired.Additional Information The period returned is the reload value of the timer set as initial value when the timer is retriggered by OS_RetriggerTimer(). Return value OS_TIMER*: A pointer to the control structure of a timer. otherwise it is undetermined. Parameter Description pTimer Pointer to the OS_TIMER data structure which contains the data of the timer. Type OS_TIME. which is defined as an integer between 1 and 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs and as an integer between 1 and <= 231-1 = 0x7FFFFFFF for 32-bit CPUs. Prototype OS_TIME OS_GetTimerValue (OS_TIMER* pTimer). OS_GetTimerStatus() Description Returns the current timer status of a specified timer. Parameter Description pTimer Pointer to the OS_TIMER data structure which contains the data of the timer. Additional Information The return value of OS_GetpCurrentTimer() is valid during execution of a timer callback function. Prototype OS_TIMER* OS_GetpCurrentTimer (void). OS_GetTimerValue() Description Returns the remaining timer value of a specified timer. denoting whether the specified timer is running or not: 0: timer has stopped ! = 0: timer is running. IAR PowerPac™ RTOS 42 User Guide PPRTOS-3 . In this version of IAR PowerPac RTOS. the extended timer structure and functions which come with IAR PowerPac RTOS may be used to generate and use software timer with individual parameter for the callback function. The example below shows one usage of OS_GetpCurrentTimer(). which is the permitted range of timer values. If only one callback function should be used for multiple timers. Table 10: OS_GetTimerValue() parameter list Return value The returned time value is the remaining timer time in IAR PowerPac RTOS tick units until expiration of the timer.

Pointer to the callback routine to be called from the RTOS after expiration of the delay.H" /******************************************************** * * Types */ typedef struct { /* Timer object with its own user data */ OS_TIMER Timer. OS_CreateTimer((OS_TIMER*) timer. Timeout pData). /* Initialize OS */ OS_InitHW(). Callback. cb. Timeout). /* Initialize Hardware for OS */ CreateTimer(&Timer_User. OS_Start(). therefore valid values are: 1 <= Timeout <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= Timeout <= 231-1 = 0x7FFFFFFF for 32-bit CPUs A void pointer which is used as parameter for the extended timer callback function. Prototype void OS_CREATETIMER_EX (OS_TIMER_EX* OS_TIMER_EX_ROUTINE* OS_TIME void* Parameter Description pTimerEx. int a. void* pUser. OS_UINT Timeout. pTimerEx Callback Pointer to the OS_TIMER_EX data structure which contains the data of the timer. OS_TIMERROUTINE* Callback. /* Start multitasking */ return 0. &a). void* pUser) { timer->pUser = pUser. /* Examine user data */ OS_RetriggerTimer(&p->Timer). Initial timeout in basic IAR PowerPac RTOS time units (nominal ms): The data type OS_TIME is defined as an integer. /* Retrigger timer */ } /******************************************************** * * main */ int main(void) { OS_InitKern(). void* pUser = p->pUser. /******************************************************** * * Variables */ TIMER_EX Timer_User. } TIMER_EX.Software timers Example #include "RTOS. The callback function has to be of type OS_TIMER_EX_ROUTINE which takes a void pointer as parameter and does not return any value. Timeout pData Table 12: OS_CREATETIMER_EX() parameter list PPRTOS-3 43 . } void cb(void) { /* Timer callback function for multiple timers TIMER_EX* p = (TIMER_EX*)OS_GetpCurrentTimer(). Callback. } */ OS_CREATETIMER_EX() Description Macro that creates and starts an extended software-timer. 100. /******************************************************** * * Local Functions */ void CreateTimer(TIMER_EX* timer.

Timeout pData). pData Table 13: OS_CreateTimerEx() parameter list Additional Information IAR PowerPac RTOS keeps track of the timers by using a linked list.Additional Information IAR PowerPac RTOS keeps track of the timers by using a linked list. OS_TIMER_EX_ROUTINE is defined in RTOS. Pointer to the callback routine of type OS_TIMER_EX_ROUTINE to be called from the RTOS after the timer has expired.h as follows: typedef void OS_TIMER_EX_ROUTINE(void*). \ OS_StartTimerEx(pTimerEx).Timeout. The extended software timer is not automatically started. /* Make timer periodical */ } void InitTask(void) { /* Create and start Timer100 */ OS_CREATETIMER_Ex(&TIMER100. Source of the macro (in RTOS.cb. therefore valid values are: 1 <= Timeout <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= Timeout <= 231-1 = 0x7FFFFFFF for 32-bit CPUs A void pointer which is used as parameter for the extended timer callback function.cb. Once the timeout has expired.h): #define OS_CREATETIMER_EX(pTimerEx. This macro uses the functions OS_CreateTimer_Ex() and OS_StartTimer_Ex(). OS_TIMERROUTINE_EX is defined in RTOS. OS_TASK TCB_HP void Timer100(void) { LED = LED ? 0 : 1. Example OS_TIMER TIMER100. the callback routine will be called immediately (unless the task is in a critical region or has interrupts disabled). the callback routine will be called immediately (unless the task is in a critical region or has interrupts disabled).pData) \ OS_CreateTimerEx(pTimerEx. /* Toggle LED */ if (pTask != NULL) { OS_SignalEvent(0x01.h as follows: typedef void OS_TIMER_EX_ROUTINE(void *). (void*) &TCB_HP). } OS_CreateTimerEx() Description Creates an extended software timer without starting it. Initial timeout in basic IAR PowerPac RTOS time units (nominal ms): The data type OS_TIME is defined as an integer. Callback. 100.Timeout. Prototype void OS_CreateTimerEx (OS_TIMER_EX* OS_TIMER_EX_ROUTINE* OS_TIME void* Parameter Description pTimerEx.pData). Once the timeout is expired. IAR PowerPac™ RTOS 44 User Guide PPRTOS-3 . Timer100. (OS_TASK*)pTask) } OS_RetriggerTimerEx(&TIMER100). This has to be done explicitly by a call of OS_StartTimerEx() or OS_RetriggerTimerEx(). pTimerEx Callback Timeout Pointer to the OS_TIMER_EX data structure which contains the data of the timer.

Table 14: OS_StartTimerEx() parameter list Additional Information OS_StartTimerEx() is used for the following reasons: ● ● Start an extended timer which was created by OS_CreateTimerEx(). (void*) &TCB_HP). Restart a timer which was stopped by calling OS_StopTimerEx(). void Timer100(void* pTask) { LED = LED ? 0 : 1. It also has no effect on timers that are not running. /* Toggle LED */ if (pTask != NULL) { OS_SignalEvent(0x01. start it elsewhere later on */ OS_CreateTimerEx(&TIMER100. /* Make timer periodical */ } void InitTask(void) { /* Create Timer100. Table 15: OS_StopTimerEx() parameter list Additional Information The actual value of the extended software timer (the time until expiration) is kept until OS_StartTimerEx() lets the timer continue.Software timers Example OS_TIMER TIMER100. PPRTOS-3 45 . The timer will start with its initial timer value. Prototype void OS_StopTimerEx (OS_TIMER_EX* pTimerEx). 100. } OS_StartTimerEx() Description Starts an extended software timer. In this case. OS_RetriggerTimerEx() Description Restarts an extended timer with its initial time value. Important This function has no effect on running timers. OS_StopTimerEx() Description Stops an extended software timer. Timer100. Use OS_RetriggerTimerEx() to restart those timers. but has expired. the timer will continue with the remaining time value which was preserved by stopping the timer. Parameter Description pTimerEx Pointer to the OS_TIMER_EX data structure which contains the data of the extended software timer. Prototype void OS_StartTimerEx (OS_TIMER_EX* pTimerEx). OS_TASK TCB_HP. (OS_TASK*)pTask) } OS_RetriggerTimerEx(&TIMER100). Parameter Description pTimerEx Pointer to the OS_TIMER_EX data structure which contains the data of the extended software timer.

} IAR PowerPac™ RTOS 46 User Guide PPRTOS-3 . Parameter Description pTimerEx Period Pointer to the OS_TIMER_EX data structure which contains the data of the timer. /* Make timer periodical */ } void InitTask(void) { /* Create and start TimerCursor */ OS_CREATETIMER_EX(&TIMERCursor. OS_TASK TCB_HP. (void*) &TCB_HP). void TimerCursor(void) { if (CursorOn != 0) ToggleCursor(). OS_RetriggerTimerEx(&TIMERPulse). (void*) &TCB_HP). /* Invert character at cursor-position */ OS_SignalEvent(0x01. Table 16: OS_RetriggerTimerEx() parameter list Additional Information OS_RetriggerTimerEx() restarts the extended software timer using the initial time value which was set at creation of the timer or which was set using the function OS_SetTimerPeriodEx(). OS_TASK TCB_HP. 500. /* Make timer periodical */ } void InitTask(void) { /* Create and start Pulse Timer with first pulse = 500ms */ OS_CREATETIMER_EX(&TIMERPulse. TimerCursor. Parameter Description pTimerEx Pointer to the OS_TIMER_EX data structure which contains the data of the extended software timer. void TimerPulse(void) { OS_SignalEvent(0x01. BOOL CursorOn. (OS_TASK*) pTask). Prototype void OS_SetTimerPeriodEx (OS_TIMER_EX* pTimerEx. /* Set timer period to 200 ms for further pulses */ OS_SetTimerPeriodEx(&TIMERPulse. (OS_TASK*) pTask). Example OS_TIMER TIMERPulse. TimerPulse. OS_RetriggerTimerEx(&TIMERCursor). Timer period in basic IAR PowerPac RTOS time units (nominal ms): The data type OS_TIME is defined as an integer. Example OS_TIMER TIMERCursor. } OS_SetTimerPeriodEx() Description Sets a new timer reload value for a extended software timer. 500.Prototype void OS_RetriggerTimerEx (OS_TIMER_EX* pTimerEx). OS_TIME Period). therefore valid values are 1 <= Timeout <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= Timeout <= 231-1 = 0x7FFFFFFF for 32-bit CPUs Table 17: OS_SetTimerPeriodEx() parameter list Additional Information OS_SetTimerPeriodEx() sets the initial time value of the specified extended software timer. 200). Period is the reload value of the timer to be used as initial value when the timer is retriggered by OS_RetriggerTimerEx(). A call of OS_SetTimerPeriodEx() does not affect the remaining time period of an extended software timer.

which is the permitted range of timer values. OS_GetTimerPeriodEx() Description Returns the current reload value of an extended software timer. Table 20: OS_GetTimerValueEx() parameter list Return value Type OS_TIME. OS_GetTimerStatusEx() Description Returns the current timer status of an extended software timer. Additional Information The period returned is the reload value of the timer which was set as initial value when the timer was created or which was modified by a call of OS_SetTimerPeriodEx(). Parameter Description pTimerEx Pointer to the OS_TIMER_EX data structure which contains the data of the timer. which is defined as an integer between 1 and 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs and as an integer between 1 and <= 231-1 = 0x7FFFFFFF for 32-bit CPUs. OS_GetTimerValueEx() Description Returns the remaining timer value of an extended software timer. Parameter Description pTimerEx Pointer to the OS_TIMER_EX data structure which contains the data of the timer. In debug builds of IAR PowerPac RTOS. Prototype void OS_DeleteTimerEx (OS_TIMER_EX* pTimerEx). Parameter Description pTimerEx Pointer to the OS_TIMER_EX data structure which contains the data of the timer. Table 19: OS_GetTimerPeriodEx() parameter list Return value Type OS_TIME. This reload value will be used as time period when the timer is retriggered by OS_RetriggerTimerEx(). which is the permitted range of timer values.Software timers OS_DeleteTimerEx() Description Stops and deletes an extended software timer. Prototype OS_TIME OS_GetTimerValueEx (OS_TIMER_EX* pTimerEx). Prototype OS_TIME OS_GetTimerPeriodEx (OS_TIMER_EX* pTimerEx). PPRTOS-3 47 . Table 18: OS_DeleteTimerEx() parameter list Additional Information The extended software timer is stopped and therefore removed out of the linked list of running timers. which is defined as an integer between 1 and 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs and as an integer between 1 and <= 231-1 = 0x7FFFFFFF for 32-bit CPUs. The returned time value is the remaining timer time in IAR PowerPac RTOS tick units until expiration of the extended software timer. the timer is also marked as invalid.

Prototype
unsigned char OS_GetTimerStatusEx (OS_TIMER_EX* pTimerEx);
Parameter Description

pTimerEx

Pointer to the OS_TIMER_EX data structure which contains the data of the extended timer.

Table 21: OS_GetTimerStatusEx() parameter list

Return value
Unsigned character, denoting whether the specified timer is running or not:

0: timer has stopped ! = 0: timer is running.

OS_GetpCurrentTimerEx()
Description
Returns a pointer to the data structure of the timer that just expired.

Prototype
OS_TIMER_EX* OS_GetpCurrentTimerEx (void);

Return value
OS_TIMER_EX*: A pointer to the control structure of an extended software timer.

Additional Information
The return value of OS_GetpCurrentTimerEx() is valid during execution of a timer callback function; otherwise it is undetermined. If only one callback function should be used for multiple timers, this function can be used for examining the timer that expired.

Example
#include "RTOS.H" OS_TIMER_EX MyTimerEx; /******************************************************** * * Local Functions */ void cbTimerEx(void* pData) { /* Timer callback function for multiple timers */ OS_TIMER_EX* pTimerEx; pTimerEx = OS_GetpCurrentTimerEx(); OS_SignalEvent(0x01, (OS_TASK*) pData); OS_RetriggerTimer(pTimerEx); /* Retrigger timer */ }

IAR PowerPac™ RTOS

48

User Guide

PPRTOS-3

Resource semaphores
Introduction
Resource semaphores are used for managing resources by avoiding conflicts caused by simultaneous use of a resource. The resource managed can be of any kind: a part of the program that is not reentrant, a piece of hardware like the display, a flash prom that can only be written to by a single task at a time, a motor in a CNC control that can only be controlled by one task at a time, and a lot more. The basic procedure is as follows: Any task that uses a resource first claims it by calling the OS_Use() or OS_Request() routines of IAR PowerPac RTOS. If the resource is available, the program execution of the task continues, but the resource is blocked for other tasks. If a second task now tries to use the same resource while it is in use by the first task, this second task is suspended until the first task releases the resource. However, if the first task that uses the resource calls OS_Use() again for that resource, it is not suspended because the resource is blocked only for other tasks. The following diagram illustrates the process of using a resource:

OS_Use()

Access resource

OS_Unuse()

A resource semaphore contains a counter that keeps track of how many times the resource has been claimed by calling
OS_Request() or OS_Use() by a particular task. It is released when that counter reaches 0, which means the OS_Unuse() routine has to be called exactly the same number of times as OS_Use() or OS_Request(). If it is not,

the resource remains blocked for other tasks. On the other hand, a task cannot release a resource that it does not own by calling OS_Unuse(). In the debug version of IAR PowerPac RTOS, a call of OS_Unuse() for a semaphore that is not owned by this task will result in a call to the error handler OS_Error().

Example of using resource semaphores
Here, two tasks access an LC display completely independently from each other. The LCD is a resource that needs to be protected with a resource semaphore. One task may not interrupt another task which is writing to the LCD, because otherwise the following might occur:
● ● ●

Task A positions the cursor Task B interrupts Task A and repositions the cursor Task A writes to the wrong place in the LCD' s memory.

To avoid this type of situation, every the LCD must be accessed by a task, it is first claimed by a call to OS_Use() (and is automatically waited for if the resource is blocked). After the LCD has been written to, it is released by a call to OS_Unuse().

PPRTOS-3

49

/* * demo program to illustrate the use of resource semaphores */ OS_STACKPTR int StackMain[100], StackClock[50]; OS_TASK TaskMain,TaskClock; OS_SEMA SemaLCD; void TaskClock(void) { char t=-1; char s[] = "00:00"; while(1) { while (TimeSec==t) Delay(10); t= TimeSec; s[4] = TimeSec%10+'0'; s[3] = TimeSec/10+'0'; s[1] = TimeMin%10+'0'; s[0] = TimeMin/10+'0'; OS_Use(&SemaLCD); /* Make sure nobody else uses LCD */ LCD_Write(10,0,s); OS_Unuse(&SemaLCD); /* Release LCD */ } } void TaskMain(void) { signed char pos ; LCD_Write(0,0,"Software tools by OS_Delay(2000); while (1) { for ( pos=14 ; pos >=0 ; pos-OS_Use(&SemaLCD); LCD_Write(pos,1,"train "); OS_Unuse(&SemaLCD); OS_Delay(500); } OS_Use(&SemaLCD); LCD_Write(0,1," ") ; OS_Unuse(&SemaLCD); } }

IAR Systems !

") ;

) { /* Make sure nobody else uses LCD /* Draw train */ /* Release LCD */ /* Make sure nobody else uses LCD /* Release LCD */

*/

*/

void InitTask(void) { OS_CREATERSEMA(&SemaLCD); /* Creates resource semaphore OS_CREATETASK(&TaskMain, 0, Main, 50, StackMain); OS_CREATETASK(&TaskClock, 0, Clock, 100, StackClock); }

*/

In most applications, the routines that access a resource should automatically call OS_Use() and OS_Unuse() so that when using the resource you do not have to worry about it and can use it just as you would in a single-task system. The following is an example of how to implement a resource into the routines that actually access the display:
/* * Simple example when accessing single line dot matrix LCD */ OS_RSEMA RDisp; /* Define resource semaphore */ void UseDisp() { OS_Use(&RDisp); } void UnuseDisp() { OS_Unuse(&RDisp); } /* Simple routine to be called before using display */

/* Simple routine to be called after using display

*/

void DispCharAt(char c, char x) { UseDisp(); LCDGoto(x, y); LCDWrite1(ASCII2LCD(c)); UnuseDisp(); } void DISPInit(void) { OS_CREATERSEMA(&RDisp); }

IAR PowerPac™ RTOS

50

User Guide

PPRTOS-3

The program continues without a break. This is called priority inversion. OS_Use() Description Claims a resource and blocks it for other tasks. the resource is not blocked. Prototype void OS_CREATERSEMA (OS_RSEMA* pRSema).Resource semaphores API functions Routine Description OS_CREATERSEMA() OS_Use() OS_Unuse() OS_Request() OS_GetSemaValue() OS_GetResourceOwner() OS_DeleteRSema() Table 1: Resource semaphore API overview Macro that creates a resource semaphore. blocks it for other tasks if it is available. A value larger than 1 means the resource was already locked by the calling task. Additional Information The following situations are possible: ● ● ● Case A: The resource is not in use. Releases a semaphore currently in use by a task. which means the counter of the semaphore is 0. the value of the counter is 0. Continues execution in any case. In the meantime if the task blocked by the resource semaphore has a higher priority than the task blocking the semaphore. Parameter Description pRSema Table 3: OS_Use() parameter list Pointer to the data structure for a resource semaphore. The execution of this task is suspended until the resource semaphore is released. Deletes a specified resource semaphore. Table 2: OS_CREATESEMA() parameter list Additional Information After creation. If the resource is not used by a task. PPRTOS-3 51 . Returns a pointer to the task that is currently using (blocking) a resource. never reduce it. Returns the value of the usage counter of a specified resource semaphore. Parameter Description pRSema Pointer to the data structure for a resource semaphore. The counter of the semaphore is simply incremented. Case C: The resource is being used by another task. Priority inversion can only temporarily increase the priority of a task. Return value The counter value of the semaphore. OS_CREATERSEMA() Description Macro that creates a resource semaphore. Claims a resource and blocks it for other tasks. the resource will be blocked for other tasks by incrementing the counter and writing a unique code for the task that uses it into the semaphore. Case B: The resource is used by this task. the blocking task is assigned the priority of the task requesting the resource semaphore. Requests a specified semaphore. Prototype int OS_Use (OS_RSEMA* pRSema).

The error code in this case is OS_ERR_RESOURCE_OWNER. If this counter becomes negative. of all the tasks waiting for the resource. by this task No Mark current task as owner Increase Usage counter Usage counter = 1 return return OS_Unuse() Description Releases a semaphore currently in use by a task.) Resource in use? Yes. the debug version will call the IAR PowerPac RTOS error handler OS_Error() with the error code OS_ERR_UNUSE_BEFORE_USE. Important This function may not be called from within an interrupt handler. the task with the highest priority will get access to the resource and can continue program execution. IAR PowerPac™ RTOS 52 User Guide PPRTOS-3 . OS_Error() will also be called if OS_Unuse() is called from a task that does not own the resource. by other task Wait for resource to be released Yes.An unlimited number of tasks can wait for a resource semaphore.. OS_Unuse() decrements the usage counter of the semaphore which must never become negative. According to the rules of the scheduler. Table 4: OS_Unuse() parameter list Additional Information OS_Unuse() may be used on a resource semaphore only after that semaphore has been used by calling OS_Use() or OS_Request(). The following diagram illustrates how the OS_Use() routine works: OS_Use(. Prototype void OS_Unuse (OS_RSEMA* pRSema) Parameter Description pRSema Pointer to the data structure for a resource semaphore. In the debug version..

Parameter Description pRSema Pointer to the data structure for a resource semaphore. Additional Information The following diagram illustrates how OS_Request() works: OS_Request (RSEMA*ps) Resource in use by other task ? No Yes return 0 In use by this task ? No Mark current task as owner Yes Inc Usage counter Usage counter = 1 return 1 return 1 Example if (!OS_Request(&RSEMA_LCD) ) { LED_LCDBUSY = 1. /* Indicate that task is waiting for resource Wait for resource Indicate task is no longer waiting Access the resource LCD Resource LCD is no longer needed */ */ */ */ */ */ PPRTOS-3 53 . /* OS_Unuse(&RSEMA_LCD). Prototype char OS_Request (OS_RSEMA* pRSema). now in use by calling task 0: Resource was not available. Continues execution in any case.Resource semaphores Important This function may not be called from within an interrupt handler. OS_Request() Description Requests a specified semaphore and blocks it for other tasks if it is available. Table 5: OS-Request() parameter list Return value 1: Resource was available. /* } DispTime(). /* LED_LCDBUSY = 0. /* /* OS_Use(&RSEMA_LCD).

Table 6: OS_GetSemaValue() parameter list Return value The counter of the semaphore. In systems with dynamic creation of resource semaphores. Parameter Description pRSema Pointer to the data structure for a resource semaphore. Otherwise the semaphore handling will not work correctly. if a resources semaphore is deleted when it is already used. A value of 0 means the resource is available. The memory of that semaphore may be reused for other purposes or may be used for creating another resources semaphore using the same memory. Prototype void OS_DeleteRSema (OS_RSEMA* pRSema). before re-creating it. make sure that no task is claiming the resources semaphore. The debug version of IAR PowerPac RTOS will call OS_Error(). Table 7: OS_GetResourceOwner() parameter list Return value Pointer to the task that is blocking the resource. OS_GetResourceOwner() Description Returns a pointer to the task that is currently using (blocking) a resource. Parameter Description pRSema Pointer to a data structure of type OS_RSEMA. Parameter Description pRSema Pointer to the data structure for a resource semaphore. Prototype int OS_GetSemaValue (OS_SEMA* pSema). Prototype OS_TASK* OS_GetResourceOwner (OS_RSEMA* pSema). Table 8: OS_DeleteRSema parameter list Additional Information Before deleting a resource semaphore. A value of 0 means the resource is available. OS_DeleteRSema() Description Deletes a specified resource semaphore.OS_GetSemaValue() Description Returns the value of the usage counter of a specified resource semaphore. it is required to delete a resource semaphore. IAR PowerPac™ RTOS 54 User Guide PPRTOS-3 .

100. OS_CREATETASK(&TCB0. Increments the counter of a semaphore up to a specified maximum value. TCB1. void Task0(void) { Loop: Disp("Task0 will wait for task 1 to signal"). /* Task stacks */ OS_TASK TCB0. } void InitTask(void) { OS_CREATECSEMA(&SEMALCD). } /* Create Semaphore /* Create Task0 /* Create Task1 */ */ */ API functions Routine Description OS_CREATECSEMA() OS_CreateCSema() OS_SignalCSema() OS_SignalCSemaMax OS_WaitCSema() OS_CSemaRequest() OS_WaitCSemaTimed OS_GetCSemaValue() OS_SetCSemaValue() OS_DeleteCSema() Macro that creates a counting semaphore with an initial count value of zero. Deletes a specified semaphore. Returns the counter value of a specified semaphore. or any interrupt in any way.Counting Semaphores Introduction Counting semaphores are counters that are managed by IAR PowerPac RTOS. They are used in situations where a task needs to wait for something that can be signaled one or more times. Disp("Task1 has signaled !!"). 50. PPRTOS-3 55 . Stack1). Task0. /* Data-area for tasks (task-control-blocks) */ OS_CSEMA SEMALCD. The semaphores can be accessed from any point. Creates a counting semaphore with a specified initial count value. Table 1: Counting semaphores API overview OS_CREATECSEMA() Description Macro that creates a counting semaphore with an initial count value of zero. any task. events or mailboxes. OS_CREATETASK(&TCB1. Decrements the counter of a semaphore. Stack1[64]. NULL. if available. OS_SignalCSema(&SEMALCD). Increments the counter of a semaphore. Stack0). } void Task1(void) { Loop: OS_Delay(5000). Decrements the counter of a semaphore. but they can be very useful sometimes. Task1. They are not as widely used as resource semaphores. OS_Delay(100). goto Loop. Example of using counting semaphores OS_STACKPTR int Stack0[96]. Sets the counter value of a specified semaphore. NULL. goto Loop. OS_WaitCSema(&SEMALCD). Decrements a semaphore counter if the semaphore is available within a specified time.

InitValue).Prototype void OS_CREATECSEMA (OS_CSEMA* pCSema). use the function OS_CreateCSema(). If one or more tasks are waiting for an event to be signaled to this semaphore. IAR PowerPac™ RTOS 56 User Guide PPRTOS-3 . OS_SignalCSemaMax() Description Increments the counter of a semaphore up to a specified maximum value. you have to create a semaphore with an initial counting value above zero. Prototype void OS_CreateCSema (OS_CSEMA* OS_UINT Parameter Description pCSema. OS_CreateCSema() Description Creates a counting semaphore with a specified initial count value. the task that has the highest priority will become the active task. for any reason. If the value of the created semaphore should be zero. Prototype void OS_SignalCSema (OS_CSEMA * pCSema). OS_SignalCSema() Description Increments the counter of a semaphore. The value of a semaphore created using this macro is zero. The counter can have a maximum value of 0xFFFF for 8/16-bit CPUs / 0xFFFFFFFF for 32-bit CPUs. a data structure of the type OS_CSEMA needs to be defined in memory and initialized using OS_CreateCSema(). It is the responsibility of your application to make sure that this limit will not be exceeded. the macro OS_CREATECSEMA() should be used. pCSema InitValue Pointer to a data structure of type OS_CSEMA. Parameter Description pCSema Pointer to a data structure of type OS_CSEMA. The debug version of IAR PowerPac RTOS detects a counter overflow and calls OS_Error() with the error code OS_ERR_CSEMA_OVERFLOW. If. a data structure of the type OS_CSEMA needs to be defined in memory and initialized using OS_CREATECSEMA(). Parameter Description pCSema Pointer to a data structure of type OS_CSEMA. Table 2: OS_CREATECSEMA() parameter list Additional Information To create a counting semaphore. Table 4: OS_SignalCSema() parameter list Additional Information OS_SignalCSema() signals an event to a semaphore by incrementing its counter. Initial count value of the semaphore: 0 <= InitValue <= 216 = 0xFFFF for 8/16-bit CPUs 0 <= InitValue <= 232 = 0xFFFFFFFF for 32-bit CPUs Table 3: OS_CreateCSema() parameter list Additional Information To create a counting semaphore.

Prototype void OS_WaitCSema (OS_CSEMA* pCSema).Counting Semaphores Prototype void OS_SignalCSemaMax (OS_CSEMA* OS_UINT Parameter Description pCSema. Table 6: OS_WaitCSema() parameter list Additional Information If the counter of the semaphore is not 0. Important This function may not be called from within an interrupt handler. MaxValue ). a timer or an interrupt handler via a call to OS_SignalCSema(). PPRTOS-3 57 . The counter is then decremented and program execution continues. the task—of all the tasks waiting for the semaphore— with the highest priority will continue program execution. Limit of semaphore count value. OS_WaitCSemaTimed() Description Decrements a semaphore counter if the semaphore is available within a specified time. OS_WaitCSema() Description Decrements the counter of a semaphore. OS_SignalCSemaMax() signals an event to a semaphore by incrementing its counter. pCSema MaxValue Pointer to a data structure of type OS_CSEMA. int TimeOut). WaitCSema() waits until the counter is incremented by another task. An unlimited number of tasks can wait for a semaphore. Calling OS_SignalCSemaMax() with a MaxValue of 1 handles a counting semaphore as a binary semaphore. If the counter is 0. 1 <= MaxValue <= 216 = 0xFFFF for 8/16-bit CPUs 1 <= MaxValue <= 232 = 0xFFFFFFFF for 32-bit CPUs Table 5: OS_SignalCSemaMax() parameter list Additional Information As long as current value of the semaphore counter is below the specified maximum value. semaphore was available and counter decremented. semaphore not available before timeout. Parameter Description pCSema Pointer to a data structure of type OS_CSEMA. the counter is decremented and program execution continues. 1: OK. Parameter Description pCSema TimeOut Pointer to a data structure of type OS_CSEMA. Maximum time until semaphore should be available Table 7: OS_WaitCSemaTimed() parameter list Return value Integer value: 0: Failed. the tasks are put into ready state and the task that has the highest priority will become the active task. Prototype int OS_WaitCSemaTimed (OS_CSEMA* pCSema. According to the rules of the scheduler. If one or more tasks are waiting for an event to be signaled to this semaphore.

this function may be called from an interrupt handler. The counter is then decremented and program execution continues. the program execution continues but returns a value of 0. According to the rules of the scheduler. Table 10: OS_SetCSemaValue() parameter list IAR PowerPac™ RTOS 58 User Guide PPRTOS-3 . semaphore was not signaled. Important This function may not be called from within an interrupt handler. If the semaphore was not signaled within the specified time. semaphore was available and counter was decremented once. OS_UINT Value). OS_CSemaRequest() Description Decrements the counter of a semaphore. Parameter Description pCSema Pointer to a data structure of type OS_CSEMA. OS_GetCSemaValue() Description Returns the counter value of a specified semaphore. Prototype char OS_CSemaRequest (OS_CSEMA* pCSema). Parameter Description pCSema Pointer to a data structure of type OS_CSEMA. Additional information If the counter of the semaphore is not 0. 1: OK. OS_SetCSemaValue() Description Sets the counter value of a specified semaphore. If the counter is 0. the task with the highest priority will continue program execution. An unlimited number of tasks can wait for a semaphore. if it is signaled. Table 9: OS_GetCSemaValue() parameter list Return value The counter value of the semaphore. a timer. the counter is decremented and program execution continues. the counter is decremented and program execution continues. WaitCSemaTimed() waits until the semaphore is signaled by another task. or an interrupt handler via a call to OS_SignalCSema(). Table 8: OS_GetCSemaRequest() parameter list Return value 0: Failed. If the counter is 0. Because this function never blocks a calling task. OS_CSemaRequest() does not wait and does not modify the semaphore counter. Prototype int OS_GetCSemaValue (OS_SEMA* pCSema). Prototype int OS_SetCSemaValue (OS_SEMA* pCSema.Additional Information If the counter of the semaphore is not 0. Parameter Description pCSema Pointer to a data structure of type OS_CSEMA. of all the tasks waiting for the semaphore. The function returns with error state.

make sure that no task is waiting for it and that no task will signal that semaphore at a later point. Table 11: OS_DeleteCSema() parameter list Additional Information Before deleting a semaphore. Prototype void OS_DeleteCSema (OS_CSEMA* pCSema). PPRTOS-3 59 . OS_DeleteCSema() Description Returns the counter value of a specified semaphore.Counting Semaphores Return value 0: If the value could be set. Parameter Description pCSema Pointer to a data structure of type OS_CSEMA. != 0: In case of error. The debug version of IAR PowerPac RTOS will reflect an error if a deleted semaphore is signaled.

IAR PowerPac™ RTOS 60 User Guide PPRTOS-3 .

The message in this case is typically a single byte that holds the key code. Unfortunately. there is a way out . The number of mailboxes is limited only by the amount of available memory. It will become clearer in the typical applications explained in the following section. Basics A mailbox is a buffer that is managed by the real-time operating system. Again. but it is a path full of pitfalls. The communication to these interrupt handlers is very easy with mailboxes. semaphores cannot transfer data from one task to another. This is possible. which you define when creating the mailbox. One way out would be the usage of global variables. The message is then retrieved by the task that handles the keyboard input. Typical applications A keyboard buffer In most programs. Number of messages: 1 <= x <= 32767. As with a keyboard buffer. Message size: 1 <= x <= 127 bytes. you may use queues. because it is reliable.Mailboxes Introduction In the preceding chapters. but very simply just means “item of data”. the message size is therefore 1 byte. The advantage of a keyboard buffer is that management is very efficient. If we need to transfer data between tasks via a buffer for example. Mailboxes usually work as FIFO: first in. a software timer or an interrupt handler to check the keyboard. The number of keys that can be stored in the type-ahead buffer depends only on the size of the mailbox buffer. refer to the Chapter Queues on page 71. On top of that. That is why there is an easier way to do this with a real-time OS: The use of mailboxes. a task can easily wait for a key to be pressed without having to poll the buffer.the task could be notified by an event signaled to the task every time a character is placed in the buffer. The buffer behaves like a normal buffer. you use either a task. we could use a resource semaphore every time we accessed the buffer. In this case we would have to disable interrupts every time and in every place that we accessed these variables. It is also not easy for a task to wait for a character to be placed in a buffer without polling the global variable that contains the number of characters in the buffer. PPRTOS-3 61 . that key is put into a mailbox that is used as a keyboard buffer. For handling messages larger than 127 bytes. So a message that is put in first will usually be retrieved first. Both your task programs and your interrupt handlers store or retrieve data to/from the same mailboxes. For more information. you can put something (called a message) in and retrieve it later. The limitations are normally not a problem. It simply calls the OS_GetMail() routine for that particular mailbox. because the interrupt handler is not allowed to wait for the resource semaphore. first out. you do not have to worry about it. proven code and you have a type-ahead buffer at no extra cost. But doing so would make the program less efficient. “Message” might sound abstract. task synchronization by the use of semaphores was described. When detected that a key has been pressed. A buffer for serial I/O In most cases. the message size is 1 character. These limitations have been placed on mailboxes to guarantee efficient coding and also to ensure efficient management. serial I/O is done with the help of interrupt handlers. Another major disadvantage would be that we could not access the buffer from an interrupt handler.

Stores a new single-byte message into a mailbox in front of all other messages. This new message will be retrieved first. OS_GetMail1(). API functions Routine Explanation OS_CREATEMB() OS_PutMail() OS_PutMail1() OS_PutMailCond() OS_PutMailCond1() OS_PutMailFront() OS_PutMailFront1() OS_PutMailFrontCond() OS_PutMailFrontCond1() OS_GetMail() OS_GetMail1() OS_GetMailCond() OS_GetMailCond1() OS_GetMailTimed() Table 1: Mailboxes API overview Macro that creates a new mailbox. or normally with a mailbox used as keyboard buffer. IAR PowerPac™ RTOS 62 User Guide PPRTOS-3 . OS_PutMailCond1(). as you might have in applications that control a machine. mailboxes are used simply to hold and transfer single-byte messages. OS_PutMailCond1(). time is very critical. and OS_GetMailCond1() work exactly the same way as their more universal equivalents and are therefore not described separately. the task receives it using OS_GetMail() or OS_GetMailCond(). To minimize the overhead caused by the mailbox management of IAR PowerPac RTOS. For interrupt-driven receiving. Retrieves a new single-byte message from a mailbox. Single-byte mailbox functions In many (if not the most) situations. for example. Stores a new single-byte message in a mailbox. if the mailbox is able to accept one more message. the task places the character(s) in the mailbox using OS_PutMail() or OS_PutMailCond(). especially if a lot of data is transferred in short periods of time. with a mailbox that takes the character received or sent via serial interface. if a message is available. Stores a new message of a predefined size into a mailbox in front of all other messages. Retrieves a new message of a predefined size from a mailbox. Stores a new message of a predefined size into a mailbox in front of all other messages. Stores a new message of a predefined size in a mailbox. variations on some mailbox functions are available for single-byte mailboxes. Retrieves a new message of a predefined size from a mailbox. The routines OS_PutMail1(). In some of these cases. Retrieves a new single-byte message from a mailbox. if the mailbox is able to accept one more message. Stores a new message of a predefined size in a mailbox. and OS_GetMailCond() can transfer messages of sizes between 1 and 127 bytes each. OS_GetMail(). Stores a new single-byte message in a mailbox. The only difference is that they can only be used for single-byte mailboxes. This is the case. if a message is available within a given time. if a message is available. Retrieves a new message of a predefined size from a mailbox. if the mailbox is able to accept one more message. the interrupt handler that is activated when a new character can be sent retrieves this character with OS_GetMailCond(). Their singlebyte equivalents OS_PutMail1(). OS_PutMailCond(). A simple way to give commands to this task would be to define a structure for commands. the interrupt handler that is activated when a new character is received puts it in the mailbox using OS_PutMailCond(). OS_GetMail1(). Stores a new single-byte message into a mailbox in front of all other messages.For interrupt-driven sending. and OS_GetMailCond1() work the same way with the exception that they execute much faster because management is simpler. if the mailbox is able to accept one more message. A buffer for commands sent to a task Assume you have one task controlling a motor. The general functions OS_PutMail(). It is recommended to use the single-byte versions if you transfer a lot of single byte-data via mailboxes. This new message will be retrieved first. The message size would then be the size of this structure.

maxnofMsg. &MBKeyBuffer). but does not retrieve the message from the mailbox. } OS_PutMail() / OS_PutMail1() Description Stores a new message of a predefined size in a mailbox.Mailboxes Routine Explanation OS_WaitMail() OS_ClearMB() OS_GetMessageCnt() OS_DeleteMB() Table 1: Mailboxes API overview Waits until a mail is available. (1 <= sizeofMsg <= 127) Maximum number of messages. #define MOTORCMD_SIZE 4 char BufferMotor[sizeof(MOTORCMD) * MOTORCMD_SIZE]. sizeof(MBKeyBuffer). Table 2: OS_CREATEMB() parameter list Example Mailbox used as keyboard buffer: OS_MAILBOX MBKey. PPRTOS-3 63 . The buffer has to be big enough to hold the given number of messages of the specified size: sizeofMsg * maxnoMsg bytes. char MBKeyBuffer[6]. Prototype void OS_CREATEMB (OS_MAILBOX* unsigned char unsigned int void* Parameter Description pMB. functioning as type ahead buffer */ OS_CREATEMB(&MBKey. void InitKeyMan(void) { /* Create mailbox. Returns number of messages currently in a specified mailbox. } Mailbox used for transferring complex commands from one task to another: /* * Example of mailbox used for transfering commands to a task * that controls 2 motors */ typedef struct { char Cmd. OS_MAILBOX MBMotor. sizeof(MOTORCMD). &BufferMotor). sizeofMsg. int Position[2]. } MOTORCMD . Clears all messages in a specified mailbox. Size of a message in bytes. Deletes a specified mailbox. 1. void MOTOR_Init(void) { /* Create mailbox that holds commands messages */ OS_CREATEMB(&MBMotor.) pMB sizeofMsg maxnoMsg pMsg Pointer to a data structure of type OS_MAILBOX reserved for managing the mailbox. MOTORCMD_SIZE. int Speed[2]. (1 <= MaxnofMsg <= 32767) Pointer to a memory area used as buffer. OS_CREATEMB() Description Macro that creates a new mailbox. pMsg).

wait if no space in buffer */ } void KEYMAN_Init(void) { /* Create mailbox functioning as type ahead buffer */ OS_CREATEMB(&MBKey. pMB pMail Pointer to the mailbox. pMB. Use OS_PutMailCond()/OS_PutMailCond1() instead if you have to store data in a mailbox from within an ISR. pMail). &k). if the mailbox is able to accept one more message. Additional Information If the mailbox is full. Pointer to the message to store. Important This function may not be called from within an interrupt handler. pMail). Table 4: OS_PutMailCond() / OS_PutMailCond1() overview Return value 0: Success. Table 3: OS_PutMail() / OS_PutMail1() parameter list Additional Information If the mailbox is full. This function never suspends the calling task. Prototype char OS_PutMailCond (OS_MAILBOX* void* char OS_PutMailCond1 (OS_MAILBOX* const char* Parameter Description pMB. it must not be called from an interrupt routine. Pointer to the message to store. Because this routine might require a suspension.Prototype void OS_PutMail (OS_MAILBOX* void* void OS_PutMail1 (OS_MAILBOX* const char* Parameter Description pMB. 1: Message could not be stored (mailbox is full).) pMB pMail Pointer to the mailbox. message stored. &MBKeyBuffer). void KEYMAN_StoreKey(char k) { OS_PutMail1(&MBKey. pMB. char MBKeyBuffer[6]. the calling task is suspended. char KEYMAN_StoreCond(char k) { return OS_PutMailCond1(&MBKey. 1. } OS_PutMailCond() / OS_PutMailCond1() Description Stores a new message of a predefined size in a mailbox. Example Single-byte mailbox as keyboard buffer: OS_MAILBOX MBKey. /* Store key. Example OS_MAILBOX MBKey. sizeof(MBKeyBuffer). /* Store key if space in buffer */ } IAR PowerPac™ RTOS 64 User Guide PPRTOS-3 . &k). char MBKeyBuffer[6]. It may therefore be called from an interrupt routine. the message is not stored. pMail). pMail).

) pMB pMail Pointer to the mailbox. This function is useful to store “emergency” messages into a mailbox which have to be handled quick. the calling task is suspended. Table 5: OS_PutMailFront() / OS_PutMailFront1() parameter list Additional Information If the mailbox is full. wait if no space in buffer*/ } void KEYMAN_Init(void) { /* Create mailbox for command buffer */ OS_CREATEMB(&MBCmd.Mailboxes This example can be used with the sample program shown earlier to handle a mailbox as keyboard buffer. Use OS_PutMailFrontCond()/OS_PutMailFrontCond1() instead if you have to store data in a mailbox from within an ISR. Prototype void OS_PutMailFront (OS_MAILBOX* void* void OS_PutMailFront1 (OS_MAILBOX* const char* Parameter Description pMB. Pointer to the message to store. pMB. if the mailbox is able to accept one more message. Because this routine might require a suspension. This new message will be retrieved first. &k). void KEYMAN_StoreCommand(char k) { OS_PutMailFront1(&MBCmd. OS_PutMailFront() / OS_PutMailFront1() Description Stores a new message of a predefined size at the beginning of a mailbox in front of all other messages. Example Single-byte mailbox as keyboard buffer: OS_MAILBOX MBCmd. pMB pMail Pointer to the mailbox. 1. Important This function may not be called from within an interrupt handler. Table 6: OS_PutMailFrontCond() / OS_PutMailFrontCond1() parameter list PPRTOS-3 65 . /* Store command. pMail). It may also be used in general instead of OS_PutMail() to change the FIFO structure of a mailbox into a LIFO structure. The new message will be retrieved first. pMail). } OS_PutMailFrontCond() / OS_PutMailFrontCond1() Description Stores a new message of a predefined size into a mailbox in front of all other messages. pMail). pMB. char MBCmdBuffer[6]. &MBCmdBuffer). it must not be called from an interrupt routine. Prototype char OS_PutMailFrontCond (OS_MAILBOX* void* char OS_PutMailFrontCond1 (OS_MAILBOX* const char* Parameter Description pMB. pMail). Pointer to the message to store. sizeof(MBCmdBuffer).

Table 7: OS_GetMail() / OS_GetMail1() parameter list Additional Information If the mailbox is empty. the task is suspended until the mailbox receives a new message. Example OS_MAILBOX MBKey. Parameter Description pMB Pointer to the mailbox. Parameter Description pMB pDest Pointer to the mailbox. } OS_GetMailCond() / OS_GetMailCond1() Description Retrieves a new message of a predefined size from a mailbox. Important This function may not be called from within an interrupt handler. void* pDest). Use OS_GetMailCond/OS_GetMailCond1 instead if you have to retrieve data from a mailbox from within an ISR. char OS_GetMailCond1 (OS_MAILBOX * pMB. Pointer to the memory area that the message should be stored at. if a message is available. return c. char* pDest). Make sure that it points to a valid memory area and that there is sufficient space for an entire message. char* pDest). OS_GetMail() / OS_GetMail1() Description Retrieves a new message of a predefined size from a mailbox. it may not be called from an interrupt routine. message stored. Table 8: OS_GetMailCond() / OS_GetMailCond1() parameter list IAR PowerPac™ RTOS 66 User Guide PPRTOS-3 . It may also be used in general instead of OS_PutMailCond() to change the FIFO structure of a mailbox into a LIFO structure. OS_GetMail1(&MBKey. The message size (in bytes) was defined when the mailbox was created.Return value 0: Success. Additional Information If the mailbox is full. It may therefore be called from an interrupt routine. 1: Message could not be stored (mailbox is full). Prototype char OS_GetMailCond (OS_MAILBOX * pMB. char MBKeyBuffer[6]. void OS_GetMail1 (OS_MAILBOX* pMB. This function never suspends the calling task. &c). the message is not stored. Because this routine might require a suspension. Prototype void OS_GetMail (OS_MAILBOX* pMB. void* pDest). char WaitKey(void) { char c. This function is useful to store “emergency” messages into a mailbox which have to be handled quick.

The data type OS_TIME defaults to an integer. as soon as a mail is available within the given timeout. Table 8: OS_GetMailCond() / OS_GetMailCond1() parameter list Return value 0: Success. Make sure that it points to a valid memory area and that there is sufficient space for an entire message. Additional Information If the mailbox is empty. Maximum time in timer ticks until the requested mail has to be available. or after the timeout value has expired. Prototype char OS_GetMailTimed (OS_MAILBOX* pMB. The message size (in bytes) has been defined upon creation of the mailbox. PPRTOS-3 67 . 1: Message could not be retrieved (mailbox is empty). therefore valid values are 1 <= Timeout <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= Timeout <= 231-1 = 0x7FFFFFFF for 32-bit CPUs Timeout Table 9: OS_GetMailTimed() parameter list Return value 0: Success. */ char GetKey(void) { char c = 0. The message size (in bytes) was defined when the mailbox was created. void* pDest. destination remains unchanged.Mailboxes Parameter Description pDest Pointer to the memory area that the message should be stored at. &c) return c. Pointer to the memory area that the message should be stored at. * Otherwise. The task continues execution. OS_GetMailCond1(&MBKey. if a message is available within a given time. destination remains unchanged. it is taken out of the mailbox and returned to caller. OS_TIME Timeout). Parameter Description pMB pDest Pointer to the mailbox. according to the rules of the scheduler. no message is retrieved. /* * If a key has been pressed. message retrieved. message retrieved. It may therefore also be called from an interrupt routine. Make sure that it points to a valid memory area and that there is sufficient space for an entire message. } OS_GetMailTimed() Description Retrieves a new message of a predefined size from a mailbox. 1: Message could not be retrieved (mailbox is empty). no message is retrieved. Example OS_MAILBOX MBKey. 0 is returned. the task is suspended for the given timeout. This function never suspends the calling task. Additional Information If the mailbox is empty. but the program execution continues. Important This function may not be called from within an interrupt handler.

Important This function may not be called from within an interrupt handler. Example OS_MAILBOX MBKey. OS_GetMailTimed(&MBKey. as soon as a mail is available. Prototype void OS_WaitMail (OS_MAILBOX* pMB). Parameter Description pMB Pointer to the mailbox. 0 is returned. otherwise the task continues. it is taken out of the mailbox and returned to caller. } OS_WaitMail() Description Waits until a mail is available.Important This function may not be called from within an interrupt handler. Parameter Description pMB Pointer to the mailbox. IAR PowerPac™ RTOS 68 User Guide PPRTOS-3 . &c. */ char GetKey(void) { char c = 0. /* * Clear keyboard type ahead buffer */ void ClearKeyBuffer(void) { OS_ClearMB(&MBKey). The task continues execution. according to the rules of the scheduler. 10) /* Wait for 10 timer ticks */ return c. } OS_GetMessageCnt() Description Returns the number of messages currently available in a specified mailbox. Table 10: OS_WaitMail() parameter list Additional Information If the mailbox is empty. OS_ClearMB() Description Clears all messages in a specified mailbox. /* * If a key has been pressed. Prototype void OS_ClearMB (OS_MAILBOX* pMB). * Otherwise. but the mail is not retrieved from the mailbox. Table 11: OS_ClearMB() parameter list Example OS_MAILBOX MBKey. but does not retrieve the message from the mailbox. the task is suspended until a mail is available.

has been created first). Table 13: OS_DeleteMB() parameter list Additional Information To keep the system fully dynamic. return 0. Prototype void OS_DeleteMB (OS_MAILBOX* pMB). Parameter Description pMB Pointer to the mailbox. void Cleanup(void) { OS_DeleteMB(MBSerIn). The memory that has been used by the mailbox for the control structure and the buffer can then be reused or reallocated. It is the programmer's responsibility to: ● ● make sure that the program no longer uses the mailbox to be deleted make sure that the mailbox to be deleted actually exists (for example.Mailboxes Prototype unsigned int OS_GetMessageCnt (OS_MAILBOX* pMB). Parameter Description pMB Pointer to the mailbox. This also means there has to be a way to delete a mailbox when it is no longer needed. Example OS_MAILBOX MBSerIn. Table 12: OS_GetMessageCnt() parameter list Return value The number of messages in the mailbox. } PPRTOS-3 69 . it is essential that mailboxes can be created dynamically. OS_DeleteMB() Description Deletes a specified mailbox.

IAR PowerPac™ RTOS 70 User Guide PPRTOS-3 .

Queues work as FIFO: first in. PPRTOS-3 71 . if one message is available or returns without suspension. 2 Retrieving a message from the queue does not copy the message. the message size is passed as a parameter. Basics A queue consists of a data buffer and a control structure that is managed by the real-time operating system. Retrieves a message from a queue. Retrieves a message from a queue within a specified time. if one message is available. first out. OS_Q_Create() Description Creates and initializes a message queue. Returns the number of messages currently in a queue. intertask communication using mailboxes was described. 3 The retrieving function has to delete every message after processing it. Any data structure can be API functions Routine Description OS_Q_Create() OS_Q_Put() OS_Q_GetPtr() OS_Q_GetPtrCond() OS_Q_GetPtrTimed() OS_Q_Purge() OS_Q_Clear() OS_Q_GetMessageCnt() Table 1: Queues API Creates and initializes a message queue. memory. Queues enable intertask communication with larger messages or with messages of various sizes. Mailboxes can handle small messages with fixed data size only. Retrieves a message from a queue. Deletes the last retrieved message in a queue. but returns a pointer to the message and its size. So a message that is put in first will be retrieved first. Both the number and size of queues is limited only by the amount of available written into a queue. When putting a message into a queue.Queues Introduction In the preceding chapter. The queue behaves like a normal buffer. Deletes all message in a queue. There are three major differences between queues and mailboxes: 1 Queues accept messages of various size. you can put something (called a message) in and retrieve it later. when the message is written into the queue. This enhances performance because the data is copied only once. The message size is not fixed. Stores a new message of given size in a queue.

Prototype int OS_Q_Put (OS_Q* pQ. int Len) { return OS_Q_Put(&_MemoryQ. } OS_Q_GetPtr() Description Retrieves a message from a queue. Table 2: OS_Q_Create() parameter list Example #define MEMORY_QSIZE 10000.Prototype void OS_Q_Create (OS_Q* pQ. Parameter Description pQ ppData Pointer to the queue. message stored. Len)). OS_UINT Size). static char _acMemQBuffer[MEMORY_QSIZE]. Parameter Description pQ pData Size Pointer to a data structure of type OS_Q reserved for the management of the message queue. const void* pSrc. void MEMORY_Init(void) { OS_Q_Create(&_MemoryQ. OS_UINT Size). 1: Message could not be stored (queue is full). void*pData. Prototype int OS_Q_GetPtr (OS_Q* pQ. Table 4: OS_Q_GetPtr() parameter list IAR PowerPac™ RTOS 72 User Guide PPRTOS-3 . pData. Pointer to a memory area used as data buffer for the queue. static OS_Q _MemoryQ. This routine never suspends the calling task. void** ppData). It may therefore also be called from an interrupt routine. &_acMemQBuffer. Example char MEMORY_Write(char* pData. Size in bytes of the data buffer. Pointer to the message to store Size of the message to store Table 3: OS_Q_Put() parameter list Return value 0: Success. the function returns a value unequal to 0. } OS_Q_Put() Description Stores a new message of given size in a queue. Additional Information If the queue is full. Address of pointer to the message to be retrieved from queue. Parameter Description pQ pSrc Size Pointer to a data structure of type OS_Q reserved for the management of the message queue. sizeof(_acMemQBuffer)).

Len). it is not removed from the queue. The retrieved message is not removed from the queue. the calling task is suspended until the queue receives a new message. &pData). char* pData. This has to be done by a call of OS_Q_Purge() after the message was processed. If a message could be retrieved. } } /* Get message */ /* Process message */ /* Delete message */ OS_Q_GetPtrCond() Description Retrieves a message from a queue. Prototype int OS_Q_GetPtrCond (OS_Q* pQ. if (Len > 0) { Memory_WritePacket(*(U32*)pData. void** ppData). Parameter Description pQ ppData Pointer to the queue. Because this routine might require a suspension. the function returns 0. while (1) { Len = OS_Q_GetPtrCond(&_MemoryQ. Additional Information If the queue is empty.Queues Return value The size of the retrieved message. int Len. Address of pointer to the message to be retrieved from queue. >0: Size of message that was retrieved from queue. if one message is available. } else { DoSomethingElse(). char* pData. int Len. Use OS_GetPtrCond() instead. Example static void MemoryTask(void) { char MemoryEvent. it must not be called from an interrupt routine. OS_Q_Purge(&_MemoryQ). Memory_WritePacket(*(U32*)pData. pData+4. Example static void MemoryTask(void) { char MemoryEvent. &pData). Sets the pointer to the message that should be retrieved. Table 5: OS_Q_GetPtrCond() parameter list Return value 0: No message available in queue. Additional Information If the queue is empty. while (1) { Len = OS_Q_GetPtr(&_MemoryQ. Len). } } } /* Check message */ /* Process message */ /* Delete message */ PPRTOS-3 73 . OS_Q_Purge(&_MemoryQ). Sets the pointer ppData to the message that should be retrieved. This function never suspends the calling task. This has to be done by a call of OS_Q_Purge() after the message was processed. The value of ppData is undefined. It may therefore also be called from an interrupt routine. pData+4.

or after the timeout value has expired. char* pData. Prototype int OS_Q_GetPtrTimed (OS_Q* pQ. therefore valid values are 1 <= Timeout <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= Timeout <= 231-1 = 0x7FFFFFFF for 32-bit CPUs Table 6: OS_Q_GetPtrCond() parameter list Return value 0: No message available in queue. Parameter Description pQ ppData Timeout Pointer to the queue. Parameter Description pQ Pointer to the queue. while (1) { Len = OS_Q_GetPtrTimed(&_MemoryQ. The data type OS_TIME defaults to an integer. as soon as a message is available within the given timeout. IAR PowerPac™ RTOS 74 User Guide PPRTOS-3 . pData+4. The task continues execution. Example static void MemoryTask(void) { char MemoryEvent. } } } /* Check message */ /* Process message */ /* Delete message */ /* Timeout */ OS_Q_Purge() Description Deletes the last retrieved message in a queue. Address of pointer to the message to be retrieved from queue. the task is suspended for the given timeout. Sets the pointer ppData to the message that should be retrieved. Len). Maximum time in timer ticks until the requested message has to be available. after the message is processed. no message is retrieved. Additional Information If the queue is empty. OS_Q_Purge(&_MemoryQ).OS_Q_GetPtrTimed() Description Retrieves a message from a queue within a specified time if a message is available. &pData. >0: Size of message that was retrieved from queue. according to the rules of the scheduler. Prototype void OS_Q_Purge (OS_Q* pQ). } else { DoSomethingElse(). OS_TIME Timeout). void** ppData. int Len. Table 7: OS_Q_Purge() parameter list Additional Information This routine should be called by the task that retrieved the last message from the queue. 10). if (Len > 0) { Memory_WritePacket(*(U32*)pData.

Queues

Example
static void MemoryTask(void) { char MemoryEvent; int Len; char* pData; while (1) { Len = OS_Q_GetPtr(&_MemoryQ, &pData); Memory_WritePacket(*(U32*)pData, pData+4, Len); OS_Q_Purge(&_MemoryQ); } } /* Get message */ /* Process message */ /* Delete message */

OS_Q_Clear()
Description
Deletes all message in a queue.

Prototype
void OS_Q_Clear (OS_Q* pQ);
Parameter Description

pQ

Pointer to the queue.

Table 8: OS_Q_Clear() parameter list

OS_Q_GetMessageCnt()
Description
Returns the number of messages currently in a queue.

Prototype
int OS_Q_GetMessageCnt (OS_Q* pQ);
Parameter Description

pQ

Pointer to the queue.

Table 9: OS_Q_GetMessageCnt() parameter list

Return value
The number of messages in the queue.

PPRTOS-3

75

IAR PowerPac™ RTOS

76

User Guide

PPRTOS-3

Task Events
Introduction
Task events are another way of communication between tasks. In contrast to semaphores and mailboxes, task events are messages to a single, specified recipient. In other words, a task event is sent to a specified task. The purpose of a task event is to enable a task to wait for a particular event (or for one of several events) to occur. This task can be kept inactive until the event is signaled by another task, a S/W timer or an interrupt handler. The event can consist of anything that the software has been made aware of in any way. For example, the change of an input signal, the expiration of a timer, a key press, the reception of a character, or a complete command. Every task has a 1-byte (8-bit) mask, which means that 8 different events can be signaled to and distinguished by every task. By calling OS_WaitEvent(), a task waits for one of the events specified as a bitmask. As soon as one of the events occurs, this task must be signaled by calling OS_SignalEvent(). The waiting task will then be put in the READY state immediately. It will be activated according to the rules of the scheduler as soon as it becomes the task with the highest priority of all the tasks in the READY state.

API functions
Routine Description

OS_WaitEvent() OS_WaitSingleEvent() OS_WaitEventTimed() OS_WaitSingleEventTimed() OS_SignalEvent() OS_GetEventsOccurred() OS_ClearEvents()
Table 1: Events API overview

Waits for one of the events specified in the bitmask and clears the event memory after an event occurs. Waits for one of the events specified as bitmask and clears only that event after it occurs. Waits for the specified events for a given time, and clears the event memory after an event occurs. Waits for the specified events for a given time; after an event occurs, only that event is cleared. Signals event(s) to a specified task. Returns a list of events that have occurred for a specified task. Returns the actual state of events and then clears the events of a specified task.

OS_WaitEvent()
Description
Waits for one of the events specified in the bitmask and clears the event memory after an event occurs.

Prototype
char OS_WaitEvent (char EventMask);
Parameter Description

EventMask

The events that the task will be waiting for.

Table 2: OS_WaitEvent() parameter list

Return value
All events that have actually occurred.

PPRTOS-3

77

Parameter Description EventMask The events that the task will be waiting for. a S/W timer. see OS_SignalEvent(). 0 if no events were signaled in time. The first of the specified events will wake the task if the event is signaled by another task. OS_WaitSingleEvent() Description Waits for one of the events specified by the bitmask and clears only that event after it occurs. Prototype char OS_WaitSingleEvent (char EventMask). Any bit in the 8-bit event mask may enable the corresponding event. These events are signaled by another task. Example OS_WaitSingleEvent(3). Any bit in the 8-bit event mask may enable the corresponding event. a S/W timer. Maximum time in timer ticks until the events have to be signaled. IAR PowerPac™ RTOS 78 User Guide PPRTOS-3 . /* Wait for event 1 or 2 to be signaled */ For a further example. These events are signaled by another task. Additional Information If none of the specified events are signaled. the task is suspended. a S/W timer or an interrupt handler. the task is activated after the specified timeout and all actual events are returned and then cleared. or an interrupt handler within the specified TimeOut time.Additional Information If none of the specified events are signaled. Prototype char OS_WaitEventTimed (char EventMask. and clears the event memory after an event occurs. The first of the specified events will wake the task. The data type OS_TIME defaults to an integer. therefore valid values are 1 <= Timeout <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= Timeout <= 231-1 = 0x7FFFFFFF for 32-bit CPUs Table 4: OS_WaitEventTimed() parameter list Return value The events that have actually occurred within the specified time. /* Wait for event 1 or 2 to be signaled */ OS_WaitEventTimed() Description Waits for the specified events for a given time. The first of the specified events will wake the task. All unmasked events remain unchanged. Example OS_WaitEvent(3). OS_TIME TimeOut). the task is suspended. Table 3: OS_WaitSingleEvent() parameter list Return value All masked events that have actually occurred. Parameter Description EventMask Timeout The events that the task will be waiting for. If no event is signaled. the task is suspended for the given time. or an interrupt handler. Any bit in the 8-bit event mask may enable the corresponding event. Additional Information If none of the specified events are available.

6 will signal events 2 & 3). All unmasked events remain unchanged. Parameter Description Event The event(s) to signal: 1 means event 1 2 means event 2 4 means event 3 . Task that the events are sent to. Additional Information If none of the specified events are available. after an event occurs.. The first of the specified events will wake the task if the event is signaled by another task.. PPRTOS-3 79 . /* Wait for event 1 or 2 to be signaled within 10 ms */ OS_SignalEvent() Description Signals event(s) to a specified task. /* Wait for event 1 or 2 to be signaled within 10 ms */ OS_WaitSingleEventTimed() Description Waits for the specified events for a given time. Example OS_WaitSingleEventTimed(3. If no event is signaled. only that event is cleared.Task Events Example OS_WaitEventTimed(3. therefore valid values are 1 <= Timeout <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= Timeout <= 231-1 = 0x7FFFFFFF for 32-bit CPUs Table 5: OS_WaitSingleEventTimed() parameter list Return value The masked events that have actually occurred within the specified time. OS_TASK* pTask). it will be put in the READY state and activated according to the rules of the scheduler. the task is activated after the specified timeout and the function returns zero. pTask Table 6: OS_SignalEvent() parameter list Additional Information If the specified task is waiting for one of these events. 10). Multiple events can be signaled as the sum of the single events (for example. 10). 128 means event 8. Any bit in the 8bit event mask may enable the corresponding event. a S/W timer or an interrupt handler within the specified TimeOut time. the task is suspended for the given time. Prototype char OS_WaitSingleEventTimed (char EventMask. The data type OS_TIME defaults to an integer. Maximum time in timer ticks until the events have to be signaled. OS_TIME TimeOut). 0 if no masked events were signaled in time. Prototype void OS_SignalEvent (char Event. Parameter Description EventMask Timeout The events that the task will be waiting for.

events are a good option. Table 7: OS_getEventsOccured() parameter list Return value The event mask of the events that have actually occurred. &TCB0). Stack0). The task is not suspended if no events are available. This is one way for a task to find out which events have been signaled. /* Notify Task that key was pressed */ } void InitTask(void) { OS_CREATETASK(&TCB0. OS_ClearEvents() Description Returns the actual state of events and then clears the events of a specified task. 100. If the task has to handle multiple mailboxes. /* Data area for tasks (task control blocks) */ void Task0(void) { OS_U8 MyEvent. IAR PowerPac™ RTOS 80 User Guide PPRTOS-3 . NULL means current task. Task0. OS_GetEventsOccurred() Description Returns a list of events that have occurred for a specified task. TCB1. Prototype char OS_GetEventsOccurred (OS_TASK* pTask). /* Task stacks */ OS_TASK TCB0. 0. Additional Information By calling this function. while(1) MyEvent = OS_WaitEvent(EVENT_KEYPRESSED | EVENT_SERIN) if (MyEvent & EVENT_KEYPRESSED) { /* handle key press */ } if (MyEvent & EVENT_SERIN) { /* Handle serial reception */ } } } void TimerKey(void) { /* More code to find out if key has been pressed */ OS_SignalEvent(EVENT_SERIN. } /* Create Task0 */ If the task was only waiting for a key to be pressed. OS_GetMail() could simply be called. The task would then be deactivated until a key is pressed. The event memory is not cleared.Example The task that handles the serial input and the keyboard waits for a character to be received either via the keyboard (EVENT_KEYPRESSED) or serial interface (EVENT_SERIN): /* * Just a small demo for events */ #define EVENT_KEYPRESSED (1) #define EVENT_SERIN (2) OS_STACKPTR int Stack0[96]. Stack1[64]. Parameter Description pTask The task who's event mask is to be returned. as in this case. the actual events remain signaled.

Parameter Description pTask The task who's event mask is to be returned.Task Events Prototype char OS_ClearEvents (OS_TASK* pTask). PPRTOS-3 81 . NULL means current task. Table 8: OS_ClearEvents() parameter list Return value The events that were actually signaled before clearing.

IAR PowerPac™ RTOS 82 User Guide PPRTOS-3 .

event objects are standalone objects which are not owned by any task. On creation. The tasks can be kept suspended until the event is set by another task. a S/W timer. and the list of waiting tasks is deleted. API functions Routine Description OS_EVENT_Create() OS_EVENT_Wait() OS_EVENT_WaitTimed() OS_EVENT_Set() OS_EVENT_Reset() OS_EVENT_Pulse() OS_EVENT_Get() OS_EVENT_Delete() Table 1: Event object API overview Creates an event object. if any. Has to be called before the event object can be used. Waits for an event and resets the event after it occurs. and then resets the event. Example OS_EVENT _HW_Event. Sets the event. the reception of a character. or an interrupt handler. OS_EVENT_Create(&HW_Event). if the event object was already created before the call of OS_EVENT_Create(). In contrast to task-events. the expiration of a timer. OS_EVENT_Create() Description Creates an event object and resets the event. or resumes waiting tasks. a key press. Deletes the specified event object. The event can be anything that the software is made aware of in any way. The debug version of IAR PowerPac RTOS checks whether the specified event object was already created and calls OS_Error() with error code OS_ERR_2USE_EVENTOBJ. Prototype void OS_EVENT_Create (OS_EVENT* pEvent) Parameter Description pEvent Pointer to an event object data structure. Returns the state of an event object. Compared to a task event. /* Create and initialize event object */ PPRTOS-3 83 . the event is set in non-signaled state. it has to be created once by a call of OS_EVENT_Create(). or a complete command. the signalling function does not need to know which task is waiting for the event to occur. Waits for an event with timeout and resets the event after it occurs. Examples include the change of an input signal.Event objects Introduction Event objects are another type of communication and synchronization objects. resumes waiting tasks. Table 2: OS_EVENT_Create() parameter list Additional Information Before the event object can be used. OS_EVENT_Create() must not be called for an event object which was already created before. Therefore. The purpose of an event object is to enable one or multiple tasks to wait for a particular event to occur. Sets the events. Resets the event to unsignaled state.

the calling task resets the event and continues operation. the calling task resets the event and continues operation. If the specified event object is not set. Prototype char OS_EVENT_WaitTimed (OS_EVENT* pEvent. Example OS_EVENT_Wait(&_HW_Event). 1: The event was not signaled and a timeout occurred.OS_EVENT_Wait() Description Waits for an event and suspends the calling task as long as the event is not signaled. Table 3: OS_EVENT_Wait() parameter list Additional Information If the specified event object is already set. The debug version of IAR PowerPac RTOS will check whether pEvent addresses a valid event object and will call OS_Error() with error code OS_ERR_EVENT_INVALID in case of an error. The debug version of IAR PowerPac RTOS will check whether pEvent addresses a valid event object and will call OS_Error() with error code OS_ERR_EVENT_INVALID in case of an error. which has to be created before the call of OS_EVENT_WaitTimed(). The data type OS_TIME defaults to an integer. OS_TIME Timeout) Parameter Description pEvent Timeout Pointer to the event object that the task will be waiting for. Maximum time in timer ticks until the event have to be signaled. /* Wait for event object */ OS_EVENT_WaitTimed() Description Waits for an event and suspends the calling task for a specified time as long as the event is not signaled. IAR PowerPac™ RTOS 84 User Guide PPRTOS-3 . therefore valid values are 1 <= Timeout <= 215-1 = 0x7FFF = 32767 for 8/16-bit CPUs 1 <= Timeout <= 231-1 = 0x7FFFFFFF for 32-bit CPUs Table 4: OS_EVENT_Wait() parameter list Return value 0: Success. Additional Information If the specified event object is already set. the event was signaled within the specified time. the calling task is suspended until the event object becomes signaled. Important This function may not be called from within an interrupt handler or software timer. Important This function may not be called from within an interrupt handler or software timer. which has to be created before the call of OS_EVENT_Wait(). the calling task is suspended until the event object becomes signaled or the timeout time has expired. pEvent has to address an existing event object. Prototype void OS_EVENT_Wait (OS_EVENT* pEvent) Parameter Description pEvent Pointer to the event object that the task will be waiting for. If the specified event object is not set. pEvent has to address an existing event object.

} } PPRTOS-3 85 . TCBLP. handle event */ .. all waiting tasks are resumed and the event object is not set to the signaled state.. /****** local functions *********************************************/ static void _HWTask(void) { /* Initialize HW functionality */ OS_Delay(100). Prototype void OS_EVENT_Set (OS_EVENT* pEvent) Parameter Description pEvent Pointer to the event object which should be set to signaled state. #include "RTOS. pEvent has to address an existing event object. If at least one task is already waiting at the event object. StackLP[128]. handle timeout */ . /* Init done.h" OS_STACKPTR int StackHP[128]. /* Task stacks */ /* Task-control-blocks */ /********************************************************************/ /****** Interface to HW module **************************************/ void HW_Wait(void).. Example The following example uses event objects to synchronize tasks to a hardware initialization function. } OS_EVENT_Set() Description Sets an event object to signaled state. 10) == 0) { /* event was signaled within tim out time. OS_TASK _TCBHW. while (1) { OS_Delay (40). /* Task stack /* Task-control-block */ */ /****** local data **************************************************/ static OS_EVENT _HW_Event. which has to be created before a call of OS_EVENT_Create(). OS_TASK TCBHP.. or resumes tasks which are waiting at the event object. the event object is set to signaled state. /********************************************************************/ /****** HW module ***************************************************/ OS_STACKPTR int _StackHW[128]. void HW_Init(void). Table 5: OS_EVENT_Set() parameter list Additional Information If no tasks are waiting at the event object. void HW_Free(void). The debug version of IAR PowerPac RTOS will check whether pEvent addresses a valid event object and will call OS_Error() with error code OS_ERR_EVENT_INVALID in case of an error. } else { /* event was not signaled within tim out time. send broadcast to waiting tasks */ HW_Free().Event objects Example if (OS_EVENT_WaitTimed(&_HW_Event.

StackHP). StackLP). /* Initialize OS OS_InitHW(). _HWTask. "LP Task". 25. OS_Start(). } void HW_Free(void) { OS_EVENT_Set(&_HW_Event). } /********************************************************************/ /********************************************************************/ static void HPTask(void) { HW_Wait(). 100. OS_CREATETASK(&TCBLP. /* Initially disable interrupts OS_InitKern(). Table 6: OS_EVENT_Reset() parameter list Additional Information pEvent has to address an existing event object. while (1) { OS_Delay (50). HPTask. Prototype void OS_EVENT_Reset (OS_EVENT* pEvent) Parameter Description pEvent Pointer to the event object which should be reset to non-signaled state. } } /* Wait until HW module is set up */ /* Wait until HW module is set up */ /********************************************************************* * * main **********************************************************************/ int main(void) { OS_IncDI(). IAR PowerPac™ RTOS 86 User Guide PPRTOS-3 . /* Start multitasking return 0. which has been created before by a call of OS_EVENT_Create(). /* Initialize Hardware for OS HW_Init(). LPTask. OS_SendString("Start project will start multitasking !\n"). OS_EVENT_Create(&_HW_Event). The debug version of IAR PowerPac RTOS will check whether pEvent addresses a valid event object and will call OS_Error() with the error code OS_ERR_EVENT_INVALID in case of an error. "HWTask". /* Initialize HW module /* You need to create at least one task before calling OS_Start() OS_CREATETASK(&TCBHP. } } static void LPTask(void) { HW_Wait(). } void HW_Init(void) { OS_CREATETASK(&_TCBHW. while (1) { OS_Delay (200)./****** global functions ********************************************/ void HW_Wait(void) { OS_EVENT_Wait(&_HW_Event). "HP Task". } */ */ */ */ */ */ OS_EVENT_Reset() Description Resets the specified event object to non-signaled state. 50. _StackHW).

It is your responsibility to make sure that: ● ● the program no longer uses the event object to be deleted the event object to be deleted actually exists (has been created first) PPRTOS-3 87 . Prototype void OS_EVENT_Pulse (OS_EVENT* pEvent). Prototype void OS_EVENT_Delete (OS_EVENT* pEvent). OS_EVENT_Get() Description Returns the state of an event object.Event objects Example OS_EVENT_Reset(&_HW_Event). Table 7: OS_EVENT_Pulse() parameter list Additional Information If any tasks are waiting at the event object. Table 8: OS_EVENT_Get() parameter list Return value 0: Event object is not set to signaled state 1: Event object is set to signaled state. then resets the event object to non-signaled state. Table 9: OS_EVENT_Delete() parameter list Additional Information To keep the system fully dynamic. Parameter Description pEvent Pointer to an event object which should be deleted. The event object remains un-signaled. the tasks are resumed. The memory that has been used by the event object’s control structure can then be reused or reallocated. OS_EVENT_Delete() Description Deletes an event object. The debug version of IAR PowerPac RTOS will check whether pEvent addresses a valid event object and will call OS_Error() with error code OS_ERR_EVENT_INVALID in case of an error. pEvent has to address an existing event object. it is essential that event objects can be created dynamically. the actual state of the event object remains unchanged. Additional Information By calling this function. This also means there has to be a way to delete an event object when it is no longer needed. Prototype unsigned char OS_EVENT_Get (OS_EVENT* pEvent). Parameter Description pEvent Pointer to an event object who’s state should be examined. The debug version of IAR PowerPac RTOS will check whether pEvent addresses a valid event object and will call OS_Error() with the error code OS_ERR_EVENT_INVALID in case of an error. Parameter Description pEvent Pointer to the event object which should be pulsed. /* Reset event object to non-signaled state */ OS_EVENT_Pulse() Description Signals an event object and resumes waiting tasks. which has been created before by a call of OS_EVENT_Create().

If any task is waiting at the event object which is deleted. IAR PowerPac™ RTOS 88 User Guide PPRTOS-3 . The debug version of IAR PowerPac RTOS will check whether pEvent addresses a valid event object and will call OS_Error() with error code OS_ERR_EVENT_INVALID in case of an error. pEvent has to address an existing event object. To avoid any problems. an event object should not be deleted in a normal application. which has been created before by a call of OS_EVENT_Create(). the debug version of IAR PowerPac RTOS calls OS_Error() with error code OS_ERR_EVENT_DELETE.● no tasks are waiting at the event object when it is deleted.

Heap type memory management
Introduction
ANSI C offers some basic dynamic memory management functions. These are malloc, free, and realloc. Unfortunately, these routines are not thread-safe, unless a special thread-safe implementation exists in the compiler specific runtime libraries; they can only be used from one task or by multiple tasks if they are called sequentially. Therefore, IAR PowerPac RTOS offer task-safe variants of these routines. These variants have the same names as their ANSI counterparts, but are prefixed OS_; they are called OS_malloc(), OS_free(), OS_realloc(). The threadsafe variants that IAR PowerPac RTOS offers use the standard ANSI routines, but they guarantee that the calls are serialized using a resource semaphore. Heap type memory management is part of the IAR PowerPac RTOS libraries. It does not use any resources if it is not referenced by the application (that is, if the application does not use any memory management API function). Note that another aspect of these routines may still be a problem: the memory used for the functions (known as heap) may fragment. This can lead to a situation where the total amount of memory is sufficient, but there is not enough memory available in a single block to satisfy an allocation request.

API functions
API routine Description

OS_malloc() OS_free() OS_realloc()

Allocates a block of memory on the heap. Frees a block of memory previously allocated. Changes allocation size.

Table 1: Heap type memory manager API overview

PPRTOS-3

89

IAR PowerPac™ RTOS

90

User Guide

PPRTOS-3

Fixed block size memory pools
Introduction
Fixed block size memory pools contain a specific number of fixed-size blocks of memory. The location in memory of the pool, the size of each block, and the number of blocks are set at runtime by the application via a call to the OS_MEMF_CREATE() function. The advantage of fixed memory pools is that a block of memory can be allocated from within any task in a very short, determined period of time.

API functions
All API functions for fixed block size memory pools are prefixed OS_MEMF_.
API routine Description

Create / Delete
OS_MEMF_Create OS_MEMF_Delete Creates fixed block memory pool. Deletes fixed block memory pool.

Allocation
OS_MEMF_Alloc OS_MEMF_AllocTimed OS_MEMF_Request Allocates memory block from a given memory pool. Waits indefinitely if no block is available. Allocates memory block from a given memory pool. Waits no longer than given time limit if no block is available. Allocates block from a given memory pool, if available. Non-blocking.

Release
OS_MEMF_Release OS_MEMF_FreeBlock Releases memory block from a given memory pool. Releases memory block from any pool.

Info
OS_MEMF_GetNumFreeBlocks OS_MEMF_IsInPool OS_MEMF_GetMaxUsed OS_MEMF_GetNumBlocks OS_MEMF_GetBlockSize
Table 1: Memory pools API overview

Returns the number of available blocks in a pool. Returns !=0 if block is in memory pool. Returns the maximum number of blocks in a pool which have been used at a time. Returns the number of blocks in a pool. Returns the size of one block of a given pool.

OS_MEMF_Create()
Description
Creates and initializes a fixed block size memory pool.

Prototype
void OS_MEMF_Create (OS_MEMF* void* OS_U16 OS_U16
Parameter Description

pMEMF, pPool, NumBlocks, BlockSize);

pMEMF pPool

Pointer to the control data structure of memory pool. Pointer to memory to be used for the memory pool. Required size is: NumBlocks * (BlockSize + OS_MEMF_SIZEOF_BLOCKCONTROL).

Table 2: OS_MEMF_Create() parameter list

PPRTOS-3

91

For most applications it is preferred to have a static memory pool design. The debug version of libraries mark the memory pool as deleted. This is a parameter which is used for debugging purpose only. Parameter Description pMEMF Purpose Pointer to the control data structure of memory pool. the memory pool and memory blocks inside this pool can no longer be used. OS_MEMF_Delete() Description Deletes a fixed block size memory pool. but may be remembered in debug builds to allow runtime analysis of memory allocation problems. The release and stack check versions do not. The retrieved pointer must be delivered to OS_MEMF_Release() as a parameter to free the memory block. it has to be created. Table 4: OS_MEMF_Alloc() parameter list Return value Pointer to the allocated block. OS_MEMF_AllocTimed() Description Requests allocation of a memory block. Table 3: OS_MEMF_Delete() parameter list Additional Information This routine is provided for completeness. Size in bytes of one block. Required size is: NumBlocks * (BlockSize + OS_MEMF_SIZEOF_BLOCKCONTROL). IAR PowerPac™ RTOS 92 User Guide PPRTOS-3 . Prototype void OS_MEMF_Delete (OS_MEMF* pMEMF). the calling task is suspended until a memory block becomes available. Parameter Description pMEMF Pointer to the control data structure of memory pool. memory pools are created at startup (before calling OS_Start()) and will never be deleted. It is guaranteed to be 0 in release or stack check builds. The debug version of libraries keeps track of created and deleted memory pools. After deletion. Its value has no effect on program execution. Waits until a block of memory is available or the timeout has expired. Waits until a block of memory is available.Parameter Description NumBlocks BlockSize Pointer to memory to be used for the memory pool. OS_MEMF_Alloc() Description Requests allocation of a memory block. The pointer must not be modified. Additional Information If there is no free memory block in the pool. Before using any memory pool. Table 2: OS_MEMF_Create() parameter list Additional Information OS_MEMF_SIZEOF_BLOCKCONTROL gives the number of bytes used for control and debug purposes. It is not used in the majority of applications because there is no need to dynamically create/delete memory pools. int Purpose). Prototype void* OS_MEMF_Alloc (OS_MEMF* pMEMF.

OS_MEMF_Release() Description Releases a memory block that was previously allocated. The retrieved pointer must be delivered to OS_MEMF_Release() as parameter to free the memory block. but may be remembered in debug builds to allow runtime analysis of memory allocation problems. int Purpose). Its value has no effect on program execution. Table 5: OS_MEMF_Alloc_Timed() Return value !=NULL pointer to the allocated block NULL if no block has been allocated. Additional Information If there is no free memory block in the pool. Its value has no effect on program execution. Prototype void OS_MEMF_Release (OS_MEMF* pMEMF. Time limit before timeout. Table 7: OS_MEMF_Release() parameter list PPRTOS-3 93 . Parameter Description pMEMF pMemBlock Pointer to the control data structure of memory pool. Prototype void* OS_MEMF_Request (OS_MEMF* pMEMF. OS_MEMF_Request() Description Requests allocation of a memory block. int Timeout. Continues execution in any case. int Purpose). the calling task is suspended until a memory block becomes available or the timeout has expired. Additional Information The calling task is never suspended by calling OS_MEMF_Request(). The pointer must not be modified. Parameter Description pMEMF Purpose Pointer to the control data structure of memory pool. Table 6: OS_MEMF_Request() parameter list Return value !=NULL pointer to the allocated block NULL if no block has been allocated. specified in ticks. The pointer must not be modified.Fixed block size memory pools Prototype void* OS_MEMF_AllocTimed (OS_MEMF* pMEMF. This is a parameter which is used for debugging purpose only. The retrieved pointer must be delivered to OS_MEMF_Release() as parameter to free the memory block. Pointer to the memory block to free. but may be remembered in debug builds to allow runtime analysis of memory allocation problems. Parameter Description pMEMF Timeout Purpose Pointer to the control data structure of memory pool. 0 or negative values are permitted. This is a parameter which is used for debugging purpose only. void* pMemBlock).

OS_MEMF_GetNumBlocks() Description Information routine to examine the total number of available memory blocks in the pool. The memory block becomes available for other tasks waiting for a memory block from the pool. Parameter Description pMemBlock Pointer to the memory block to free. Table 9: OS_MEMF_GetNumBlocks() parameter list Return value Returns the number of blocks in the specified memory pool. OS_MEMF_GetBlockSize() Description Information routine to examine the size of one memory block in the pool. The memory block becomes available for other tasks waiting for a memory block from the pool. it is activated according to the rules of the scheduler. This is the value that was given as parameter during creation of the memory pool. Parameter Description pMEMF Pointer to the control data structure of memory pool. Table 8: OS_MEMF_FreeBlock() parameter list Additional Information The pMemBlock pointer has to be the one that was delivered form any retrieval function described above.Additional Information The pMemBlock pointer has to be the one that was delivered from any retrieval function described above. it is activated according to the rules of the scheduler. It has the advantage that only one parameter is needed. The memory pool does not need to be denoted. The pointer must not be modified between allocation and release. OS_MEMF_GetNumFreeBlocks() Description Information routine to examine the number of free memory blocks in the pool. OS_MEMF_FreeBlock() Description Releases a memory block that was previously allocated. IAR PowerPac™ RTOS 94 User Guide PPRTOS-3 . Prototype int OS_MEMF_GetBlockSize (OS_MEMF* pMEMF). Table 10: OS_MEMF_GetBlockSize() parameter list Return value Size in bytes of one memory block in the specified memory pool. This function may be used instead of OS_MEMF_Release(). If any task is waiting for a fixed memory block. Prototype int OS_MEMF_GetNumBlocks (OS_MEMF* pMEMF). Prototype void OS_MEMF_FreeBlock (void* pMemBlock). This is the value of the parameter when the memory pool was created. IAR PowerPac RTOS itself will find the associated memory pool. Parameter Description pMEMF Pointer to the control data structure of memory pool. The pointer must not be modified between allocation and release. If any task is waiting for a fixed memory block.

Table 13: OS_MEMF_IsInPool() parameter list Return value 0: Pointer does not belong to memory pool. Parameter Description pMEMF Pointer to the control data structure of memory pool. Prototype char OS_MEMF_IsInPool (OS_MEMF* pMEMF. Prototype int OS_MEMF_GetMaxUsed (OS_MEMF* pMEMF). 1: Pointer belongs to the pool. void* pMemBlock). OS_MEMF_IsInPool() Description Information routine to examine whether a memory block reference pointer belongs to the specified memory pool. Parameter Description pMEMF Pointer to the control data structure of memory pool. Table 12: OS_MEMF_GetMaxUsed() parameter list Return value Maximum number of blocks in the specified memory pool that were used concurrently since the pool was created. Pointer to a memory block that should be checked.Fixed block size memory pools Prototype int OS_MEMF_GetNumFreeBlocks (OS_MEMF* pMEMF). Parameter Description pMEMF pMemBlock Pointer to the control data structure of memory pool. PPRTOS-3 95 . Table 11: OS_MEMF_GetNumFreeBlocks() parameter list Return value The number of free blocks actually available in the specified memory pool. OS_MEMF_GetMaxUsed() Description Information routine to examine the amount of memory blocks in the pool that were used concurrently since creation of the pool.

IAR PowerPac™ RTOS 96 User Guide PPRTOS-3 .

The location and size of this stack is defined when creating the task. TASK STACK Each IAR PowerPac RTOS task has a separate stack. if available. However. because code that uses them might reduce stack size on another CPU or a new version of IAR PowerPac RTOS with support for an interrupt stack for your CPU. A “normal” single-task program needs exactly one stack. To detect a stack overflow. INTERRUPT STACK To reduce stack size in a multitasking environment. For details about interrupt stacks. the debug and stack check builds of IAR PowerPac RTOS fill the stack with control characters when it is created and check these characters every time the task is deactivated. IAR PowerPac RTOS cannot reliably detect a stack overflow. For details regarding required size of your system stack. IAR PowerPac RTOS may support a separate stack for interrupts by calling the function OS_EnterIntStack() at beginning of an interrupt service routine and OS_LeaveIntStack() at its very end. also interrupt stack size in the debug version). The stack needs to have a minimum size which is determined by the sum of the stack usage of the routines in the worstcase nesting. If an overflow is detected. these function calls are implemented as empty macros. the system stack is used only when no task is executed for the following: ● ● IAR PowerPac RTOS scheduler IAR PowerPac RTOS software timers (and the callback).Stacks Introduction The stack is the memory area used for storing the return address of function calls. Even if the CPU does not support a hardware interrupt stack. IAR PowerPac RTOS monitors the stack size (and. If there is no interrupt stack. In case the CPU already supports hardware interrupt stacks or if a separate interrupt stack is not supported at all. see the CPU & Compiler Specifics manual of IAR PowerPac RTOS documentation. We recommend using OS_EnterIntStack() and OS_LeaveIntStack() even if there is currently no additional benefit for your specific CPU. some processors use a specific stack area for interrupt service routines (called a hardware interrupt stack). refer to the CPU & Compiler Specifics manual of IAR PowerPac RTOS documentation. and a serious program failure is most likely to occur. If the stack is too small. parameters. a section of the memory that is not reserved for the stack will be overwritten. For details. SYSTEM STACK Before IAR PowerPac RTOS takes over control (before the call to OS_Start()). every task has to have its own stack. a program uses the system stack. Interrupt routines also use the stack to save the return address and flag registers. In a multitasking system. you will have to add stack requirements of your interrupt service routines to each task stack. as well as for temporary storage. and local variables. OS_Error() is called. Note that defining a larger stack than necessary will waist memory. except in cases where the CPU has a separate stack for interrupt functions. The minimum size of a task stack pretty much depends on the CPU and the compiler. PPRTOS-3 97 . and calls the failure routine OS_Error() if it detects a stack overflow. This is the same stack that a non-IAR PowerPac RTOS program for this CPU would use. see the CPU & Compiler Specifics manual of IAR PowerPac RTOS documentation. Refer to the CPU & Compiler Specifics manual of IAR PowerPac RTOS documentation for details on your processor's stack. After transferring control to the IAR PowerPac RTOS scheduler by calling OS_Start().

OS_Delay(1000). Example void CheckStackBase(void) { printf("Addr Stack[0] %x". because only these builds initialize the stack space used for the tasks. Additional Information This function is only available in the debug and stack check builds of IAR PowerPac RTOS. Returns the used portion of a task stack. OS_GetStackBase() Description Returns a pointer to the base of a task stack. Parameter Description pTask The task whose stack base has to be returned. } OS_GetStackSize() Description Returns the size of a task stack. IAR PowerPac™ RTOS 98 User Guide PPRTOS-3 . OS_Delay(1000). NULL means current task. OS_GetStackBase(&TCB[0]). Prototype int OS_GetStackSize (OS_TCB* pTask). Returns the unused portion of a task stack. because only these builds initialize the stack space used for the tasks. OS_GetStackBase(&TCB[1]). Table 2: OS_GetStackBase() parameter list Return value The pointer to the base address of the stack. printf("Addr Stack[1] %x".API functions Routine Description OS_GetStackBase() OS_GetStackSize() OS_GetStackSpace() OS_GetStackUsed() Table 1: Stacks API overview Returns the base address of a task stack. Table 3: OS_GetStackSize() parameter list Return value The size of the task stack in bytes. Prototype int OS_GetStackBase (OS_TCB* pTask). NULL means current task. Returns the size of a task stack. Parameter Description pTask The task whose stack size is to be checked. Additional Information This function is only available in the debug and stack check builds of IAR PowerPac RTOS.

Prototype int OS_GetStackUsed (OS_TCB* pTask). printf("Unused Stack[1] %d". OS_Delay(1000). because it takes quite some time to calculate the worst-case nesting and the calculation itself is difficult. OS_GetStackSize(&TCB[1]). OS_GetStackSpace(&TCB[1]). Parameter Description pTask The task whose stack space is to be checked. Parameter Description pTask The task whose stack space is to be checked. this routine will detect the correct amount of stack bytes. because it can only detect modified bytes on the stack. Additional Information In most cases. Prototype int OS_GetStackSpace (OS_TCB* pTask). This function is only available in the debug and stack check builds of IAR PowerPac RTOS. However. which returns the number of unused bytes on the stack. Important This routine does not reliably detect the amount of stack space left. the stack size required by a task cannot be easily calculated. you can reduce the size of this stack and vice versa. } OS_GetStackUsed() Description Returns the used portion of a task stack. OS_Delay(1000). OS_GetStackSpace(&TCB[0]). In most cases. NULL means current task. because only these builds initialize the stack space used for the tasks. Example void CheckStackSpace(void) { printf("Unused Stack[0] %d". If there is a lot of space left. the required stack size can be calculated using the function OS_GetStackSpace(). space used for register storage or local variables is not always modified. } OS_GetStackSpace() Description Returns the unused portion of a task stack. Table 4: OS_GetStackSpace() parameter list Return value The unused portion of the task stack in bytes. but in case of doubt. PPRTOS-3 99 . OS_Delay(1000). OS_GetStackSize(&TCB[0]). Table 5: OS_GetStackUsed() parameter list Return value The used portion of the task stack in bytes. printf("Size Stack[1] %d". NULL means current task.Stacks Example void CheckStackSize(void) { printf("Size Stack[0] %d". Unfortunately. be generous with your stack space or use other means to verify that the allocated stack space is sufficient. OS_Delay(1000).

OS_Delay(1000). printf("Used Stack[1] %d". because it can only detect modified bytes on the stack. the stack size required by a task cannot be easily calculated. In most cases. However. Unfortunately. space used for register storage or local variables is not always modified. because only these builds initialize the stack space used for the tasks. because it takes quite some time to calculate the worst-case nesting and the calculation itself is difficult. Important This routine does not reliably detect the amount of stack space used. If there is a lot of space left. OS_GetStackUsed(&TCB[0]). } IAR PowerPac™ RTOS 100 User Guide PPRTOS-3 . OS_Delay(1000). Example void CheckStackUsed(void) { printf("Used Stack[0] %d". OS_GetStackUsed(&TCB[1]). which returns the number of used bytes on the stack. but in case of doubt. you can reduce the size of this stack and vice versa.Additional Information In most cases. be generous with your stack space or use other means to verify that the allocated stack space is sufficient. This function is only available in the debug and stack check builds of IAR PowerPac RTOS. the required stack size can be calculated using the function OS_GetStackUsed(). this routine will detect the correct amount of stack bytes.

or memory-copy instructions are the instructions which require most clock cycles. Because the mode switch has flushed the pipeline. Interrupt latency Interrupt latency is the time between an interrupt request and the execution of the first instruction of the interrupt service routine.they can be recognized and executed within other ISRs.LR}. the CPU saves its registers and executes a subroutine referred to as an interrupt service routine. Interrupts effectively allow events to be processed as they occur. divide. There are several good reasons for using interrupt routines. the instruction STMDB SP!. Specific details for your CPU and compiler can be found in the CPU & Compiler specifics manual of the IAR PowerPac RTOS documentation. the expiration of a hardware timer. On top of the cycles required by the CPU. push-multiple. on most systems. An instruction is executed when it has reached its final stage of the pipeline. the program returns to the highest-priority task in the READY state. The CPU requires 15 clock cycles. It stores 13 32-bit registers on the stack. After the ISR is completed. This instruction can take a lot of cycles. Pipeline fill Most modern CPUs are pipelined. they can occur at any time unless they are disabled with the CPU's “disable interrupt” instruction. Depending on the synchronization logic. a few extra cycles are required to refill the pipeline. In general. (Push parameters and perm. These depend on the type of system used. modern CPUs (such as ARM) perform a mode switch. CAUSES OF INTERRUPT LATENCIES ● ● ● ● ● The first delay is typically in the hardware: The interrupt request signal needs to be synchronized to the CPU clock. What are interrupts? Interrupts are interruptions of a program caused by hardware. register) is typically the worst case instruction. They can respond very quickly to external events such as the status change on an input. Every computer system has an interrupt latency. PPRTOS-3 101 . typically up to 3 CPU cycles can be lost before the interrupt request has reached the CPU core. but we list a few of them. or other types of events.Interrupts This chapter explains how to use interrupt service routines (ISRs) in cooperation with IAR PowerPac RTOS. In an ARM7 system. When an interrupt occurs. The memory system may require additional cycles for wait states. The interrupt latency is the sum of a lot of different smaller delays explained below. ADDITIONAL CAUSES FOR INTERRUPT LATENCIES There can be additional causes for interrupt latencies. The CPU will typically complete the current instruction. or ISR. After the current instruction is completed. ISRs are also nestable . the CPU performs a mode switch or pushes registers (typically. reception or completion of transmission of a character via serial interface. which requires less CPU cycles than saving registers. The latency depends on various factors and differs even on the same computer system. Normal interrupts are maskable. there are in most cases additional cycles required for memory access.{R0-R11. Execution of an instruction happens in various stages of the pipeline. PC and flag registers) on the stack. The value that one is typically interested in is the worst case interrupt latency.

In this case. A cache miss may cause a line to be replaced. Interrupt routines. not only the required data is loaded from memory. the FIQ is treated as “High priority interrupt”. causing add. IAR PowerPac RTOS distinguishes two different levels of interrupts: High / Low priority interrupts. it needs to be written back to main memory. but of course causes add. but in a lot of cases a complete line fill needs to be performed. the application program can cause additional latencies by disabling interrupts. This can make sense in some situations. Different priorities have two effects: ● ● If different interrupts occur simultaneously. one interrupt disables further interrupts. Even if the interrupts are re-enabled in the ISR. Some RTOSes disable all interrupts. If the memory system has one or multiple caches. the interrupt with higher priority takes precedence and its ISR is executed first. the differences are: Low-priority interrupts ● ● May call IAR PowerPac RTOS API functions Latencies caused by IAR PowerPac RTOS High-priority interrupts ● ● May not call IAR PowerPac RTOS API functions No Latencies caused by IAR PowerPac RTOS (Zero latency) Example of different interrupt priority levels ARM CPUs support normal interrupts (IRQ) and fast interrupt (FIQ). reading multiple words from memory. RTOS (Real-time Operating system). Using IAR PowerPac RTOS. In general. causing an additional delay. Application program. The IAR PowerPac RTOS port specific documentation explains where “the line is drawn”. IAR PowerPac™ RTOS 102 User Guide PPRTOS-3 . translation table walks caused by the TLB not containing translations for the handler and/or the data it accesses can increase interrupt latency significantly. What we mean when we say “Zero interrupt latency” is that the latency of high-priority interrupts is not affected by the RTOS. Translation table walks can take a considerable amount of time. In real-time interrupt handlers. effectively increasing interrupt latencies for all interrupts. An RTOS also needs to temporarily disable the interrupts which can call API-functions of the RTOS. which interrupts are considered high and which interrupts are considered low priority. On most systems. Latencies caused by cache write back. Zero interrupt latency Zero interrupt latency in the strict sense is not possible as explained above. If this line is marked as dirty. Details are explained in the CPU/MCU/SOC manuals and the CPU & Compiler Specifics manual of IAR PowerPac RTOS. Interrupts can never be interrupted by other interrupts of the same or lower level of priority. especially as they involve potentially slow main memory accesses. Latencies caused by MMU translation table walks.● ● ● ● ● ● Latencies caused by cache line fill. latency. some (like IAR PowerPac RTOS) disable only low-priority interrupts and do thereby not affect the latency of high priority interrupts. Of course. these may not contain the required data. this takes a few instructions. a system using IAR PowerPac RTOS will have the same worst-case interrupt latency for high priority interrupts as a system running without IAR PowerPac RTOS. latencies. High / low priority interrupts Most CPUs support interrupts with different priorities. How many different levels of interrupts there are depend on the CPU and the interrupt controller.

● ● Interrupt handlers preserve all registers. ADDITIONAL RULES FOR PREEMPTIVE MULTITASKING A preemptive multitasking system like IAR PowerPac RTOS needs to know if the program that is executing is part of the current task or an interrupt handler. This is not a problem for interrupt handlers that do not allow further interruptions (which do not enable interrupts) and that do not call any IAR PowerPac RTOS functions. Informs IAR PowerPac RTOS that the end of the interrupt routine has been reached. Does not change the interrupt disable counter. when the interrupted task is made ready again. Interrupt entry function supporting nestable interrupts. Intensive calculations should be kept out of interrupt handlers. call either OS_LeaveInterrupt() or OS_LeaveInterruptNoSwitch() as last command. the task switch then occurs in the routine OS_LeaveInterrupt(). based on the interrupt disable counter. IAR PowerPac RTOS has to be informed that an interrupt service routine is running. it can only do so at the end of an interrupt handler. and before they return. This environment normally consists of the registers only. This leads us to the following rule: ● Interrupt functions that re-enable interrupts or use any IAR PowerPac RTOS function need to call OS_EnterInterrupt() at the beginning. It should not wait in any form or perform a polling operation. Restores the status of the interrupt flag. Interrupt handlers must restore the environment of a task completely. Decrements the counter and enables interrupts if the counter reaches 0. the ISR would continue as soon as the interrupted task became the current task again. PPRTOS-3 103 . before executing any other command. Informs IAR PowerPac RTOS that interrupt code is executing. Interrupt handlers have to be finished quickly. An interrupt handler should only be used for storing a received value or to trigger an operation in the regular program (task). do not be confused. Increments the interrupt disable counter (OS_DICnt) and disables interrupts. These rules apply to both single-task programming as well as to multitask programming using IAR PowerPac RTOS. API functions Before calling any IAR PowerPac RTOS function from within an ISR. This has proven to be the most efficient way of initiating a task switch from within an interrupt service routine. If a higher priority task is made ready by the ISR.Interrupts Rules for interrupt handlers GENERAL RULES There are some general rules for interrupt handlers. The end of the ISR is executed at a later point. executes task switching within ISR. This is because IAR PowerPac RTOS cannot perform a task switch during the execution of an interrupt handler. so the ISR has to make sure that all registers modified during interrupt execution are saved at the beginning and restored at the end of the interrupt routine. Disables interrupts. If you debug an interrupt routine. If a task switch were to occur during the execution of an ISR. Routine Description OS_CallISR() OS_CallNestableISR() OS_EnterInterrupt() OS_LeaveInterrupt() OS_IncDI() OS_DecRI() OS_DI() OS_EI() OS_RestoreI() Table 1: Interrupt API overview Interrupt entry function. Unconditionally enables Interrupt.

} OS_EnterInterrupt() Note:This function may not be available in all ports. Note:For some specific CPUs OS_CallNestableISR() has to be used to call an interrupt handler because OS_EnterNestableInterrupt() / OS_LeaveNestableInterrupt() may not be available. Disables further interrupts. OS_LeaveNestableInterrupt() Table 1: Interrupt API overview OS_CallISR() Description Entry function for use in an IAR PowerPac RTOS interrupt handler. Refer to the CPU specific manual. IAR PowerPac™ RTOS 104 User Guide PPRTOS-3 . Nestable interrupts disabled. thus locking any other IAR PowerPac RTOS interrupt. Example #pragma interrupt void OS_ISR_Tick(void) { OS_CallNestableISR(_IsrTickHandler). Table 2: OS_CallISR() parameter list Additional Information OS_CallISR() can be used as an entry function in an IAR PowerPac RTOS interrupt handler. Refer to the CPU specific manual. Description Parameter pRoutine Pointer to an interrupt routine. OS_CallISR() has to be used to call an interrupt handler because OS_EnterInterrupt() / OS_LeaveInterrupt() may not be available. when the corresponding interrupt should not be interrupted by another IAR PowerPac RTOS interrupt. OS_CallISR() sets the interrupt priority of the CPU to the user definable ’fast’ interrupt priority level. Prototype void OS_CallNestableISR (void (*pRoutine)(void)). Table 3: OS_CallNestableISR() parameter list Additional Information OS_CallNestableISR() can be used as an entry function in an IAR PowerPac RTOS interrupt handler. when interruption by higher prioritized IAR PowerPac RTOS interrupts should be allowed. Nestable interrupts enabled. thus disabling further task switches. Example #pragma interrupt void OS_ISR_Tick(void) { OS_CallISR(_IsrTickHandler). thus keeping all interrupts with higher priority enabled. Prototype void OS_CallISR (void (*pRoutine)(void)). } OS_CallNestableISR() Description Entry function for use in an IAR PowerPac RTOS interrupt handler. OS_CallNestableISR() does not alter the interrupt priority of the CPU.Routine Description OS_EnterNestableInterrupt() Re-enables interrupts and increments the IAR PowerPac RTOS internal critical region counter. Fast interrupts are not disabled. Note:For some specific CPUs. Description Parameter pRoutine Pointer to an interrupt routine.

OS_LeaveInterrupt() Note:This function may not be available in all ports. it should be the last function to be called in the interrupt handler. The use of this function has the following effects. executes task switching within ISR. EXAMPLE USING OS_ENTERINTERRUPT()/ OS_LEAVEINTERRUPT() Interrupt routine using OS_EnterInterrupt()/OS_LeaveInterrupt(): PPRTOS-3 105 . Additional Information If OS_EnterInterrupt() is used. Additional Information If OS_LeaveInterrupt() is used. it is not executed from within the ISR.&Task). it will be executed (unless the program which was interrupted was in a critical region). Description Informs IAR PowerPac RTOS that the end of the interrupt routine has been reached. } OS_LeaveInterruptNoSwitch() Description Informs IAR PowerPac RTOS that the end of the interrupt routine has been reached but does not execute task switching within ISR. it should be the last function to be called in the interrupt handler. Additional Information If OS_LeaveInterruptNoSwitch() is used. it: ● ● disables task switches keeps interrupts in internal routines disabled. It must be used with either OS_LeaveInterrupt() or OS_LeaveInterruptNoSwitch() as the last function called. Prototype void OS_LeaveInterruptNoSwitch (void). If the interrupt has caused a task switch. This will be the next call of an IAR PowerPac RTOS function or the scheduler interrupt if the program is not in a critical region.Interrupts Description Informs IAR PowerPac RTOS that interrupt code is executing. OS_SignalEvent(1. it should be the first function to be called in the interrupt handler./* Any functionality could be here */ OS_LeaveInterrupt(). If the interrupt has caused a task switch. EXAMPLE USING OS_ENTERINTERRUPT()/ OS_LEAVEINTERRUPT() Interrupt routine using OS_EnterInterrupt()/OS_LeaveInterrupt(): __interrupt void ISR_Timer(void) { OS_EnterInterrupt(). Prototype void OS_EnterInterrupt (void). but at the next possible occasion. Prototype void OS_LeaveInterrupt (void).

but it is recommended to use the functions that IAR PowerPac RTOS offers (to be precise. If you need to disable interrupts for a short moment only where no routine is called. and they should therefore be used with great care. as in the example above. the interrupts have to be temporarily disabled: Bad example: volatile long lvar. OS_IncDI() / OS_DecRI() The following functions are actually macros defined in RTOS. lvar ++. In certain sections of the program. Decrements the counter and enables interrupts if the counter reaches 0.&Task). but are macros in reality). use OS_IncDI() and OS_DecRI(). In case of doubt./* Any functionality could be here */ OS_LeaveInterrupt(). but only checked once. OS_IncDI() Short for Increment and Disable Interrupts.__interrupt void ISR_Timer(void) { OS_EnterInterrupt(). void routine (void) { OS_IncDI().h. } The problem with disabling and re-enabling interrupts is that functions that disable/enable the interrupt cannot be nested. } Enabling / disabling interrupts from C During the execution of a task. We recommend disabling interrupts only for short periods of time. you may run into a problem if routines which require a portion of the code to run with disabled interrupts are nested or call an OS routine. it can be necessary to disable interrupts for short periods of time to make a section of the program an atomic operation that cannot be interrupted. Also. maskable interrupts are normally enabled. OS_SignalEvent(1. They have the disadvantage that they do not work with routines because the status of OS_DICnt is not actually changed. It is important that they are used as a pair: first OS_IncDI(). Example volatile long lvar. An example would be the access to a global volatile variable of type long on an 8/16-bit CPU. the higher the interrupt latency). you could also use the pair OS_DI() and OS_RestoreI(). OS_DecRI(). As long as you only call IAR PowerPac RTOS functions with interrupts enabled. they only look like functions. void routine (void) { lvar ++. so they execute very quickly and are very efficient. OS_DecRI() Short for Decrement and Restore Interrupts. if possible. If you do not use these recommended IAR PowerPac RTOS functions. } OS_IncDI() increments the interrupt disable counter which is used for the entire OS and is therefore consistent with the rest of the program in that any routine can be called and the interrupts will not be switched on before the matching OS_DecRI() has been executed. because this could lead to long interrupt latency times (the longer interrupts are disabled. These functions can still be used. however. you may also safely use the compiler-provided intrinsics to disable interrupts. you should not call routines when interrupts are disabled. Increments the interrupt disable counter (OS_DICnt) and disables interrupts. These are a bit more efficient because the interrupt disable counter OS_DICnt is not modified twice. To make sure that the value does not change between the two or more accesses that are needed. Your C compiler offers two intrinsic functions for enabling and disabling interrupts. IAR PowerPac™ RTOS 106 User Guide PPRTOS-3 . then OS_DecRI().

} { OS_ASSERT_DICnt(). Example volatile long lvar. } { OS_ASSERT_DICnt(). OS_DI(). OS_EI() Short for Enable Interrupts. OS_RestoreI(). These are known as nested interrupts. because it does not take the interrupt disable counter into account. Does not change the interrupt disable counter. PPRTOS-3 107 .h) #define OS_IncDI() #define OS_DecRI() #define OS_RestoreI() { OS_ASSERT_DICnt(). Re-enabling interrupts in an interrupt handler allows the execution of further interrupts with equal or higher priority than that of the current interrupt. interrupts are disabled in an ISR because the CPU disables interrupts with the execution of the interrupt handler. Restores the status of the interrupt flag. if (OS_DICnt==0) OS_EI(). illustrated in the diagram below: Task ISR 1 ISR 2 ISR 3 Interrupt 1 Interrupt 2 Interrupt 3 Time For applications requiring short interrupt latency. } Definitions of interrupt control macros (in RTOS. } Nesting interrupt routines By default. based on the interrupt disable counter. void routine (void) { OS_DI(). OS_DICnt++. Disables interrupts. lvar++. if (--OS_DICnt==0) OS_EI(). Refrain from using this function directly unless you are sure that the interrupt enable count has the value zero.Interrupts OS_DI() / OS_EI() / OS_RestoreI() OS_DI() Short for Disable Interrupts. you may re-enable interrupts inside an ISR by using OS_EnterNestableInterrupt() and OS_LeaveNestableInterrupt() within the interrupt handler. OS_RestoreI() Short for Restore Interrupts.

OS_EnterNestableInterrupt() Note:This function may not be available in all ports. a non-maskable interrupt (NMI) cannot be disabled. Description Disables further interrupts. Description Re-enables interrupts and increments the IAR PowerPac RTOS internal critical region counter. but is more efficient. OS_LeaveNestableInterrupt() Note:This function may not be available in all ports. OS_LeaveNestableInterrupt() disables interrupts right before ending the interrupt routine again. Prototype void OS_EnterNestableInterrupt (void). In this case. meaning it can interrupt these atomic operations. resulting in smaller and faster code. The function OS_EnterNestableInterrupt() is implemented as a macro and offers the same functionality as OS_EnterInterrupt() in combination with OS_DecRI(). IAR PowerPac RTOS needs to know that another ISR is still active and that it may not perform a task switch. NMIs should be used with great care and may under no circumstances call any IAR PowerPac RTOS routines. However. Re-enabling interrupts will make it possible for an IAR PowerPac RTOS scheduler interrupt to shortly interrupt this ISR. Non-maskable interrupts (NMIs) IAR PowerPac RTOS performs atomic operations by disabling interrupts. Therefore. therefore it is not really recommended to enable interrupts within an interrupt handler. IAR PowerPac™ RTOS 108 User Guide PPRTOS-3 . Prototype void OS_LeaveNestableInterrupt (void). resulting in smaller and faster code. then decrements the IAR PowerPac RTOS internal critical region count. thus re-enabling task switches if the counter has reached zero again. but is more efficient. the enabling and disabling of interrupts from within an ISR has to be done using the functions that IAR PowerPac RTOS offers for this purpose.Nested interrupts can lead to problems that are difficult to track. The function OS_LeaveNestableInterrupt() is implemented as a macro and offers the same functionality as OS_LeaveInterrupt() in combination with OS_IncDI(). Additional Information This function is the counterpart of OS_EnterNestableInterrupt(). As it is important that IAR PowerPac RTOS keeps track of the status of the interrupt enable/disable flag. thus restores the default condition. Example Refer to the example for OS_LeaveNestableInterrupt(). and has to be the last function call inside an interrupt handler when nested interrupts have earlier been enabled by OS_EnterNestableInterrupt(). The routine OS_EnterNestableInterrupt() enables interrupts within an ISR and prevents further task switches. Additional Information This function should be the first call inside an interrupt handler when nested interrupts are required. thus disabling further task switches.

A critical region can be defined anywhere during the execution of a task. however. If this counter reaches 0 again. Additional Information OS_EnterRegion() is not actually a function but a macro. Indicates to the OS the end of a critical region. it behaves very much like a function but is much more efficient. which is 0 by default. } */ OS_LeaveRegion() Description Indicates to the OS the end of a critical region. Interrupts are still legal in a critical region. If a task switch becomes due during the execution of a critical region. Effectively. preemptions are switched off. The counter will be decremented by a call to the routine OS_LeaveRegion(). it will be performed right after the region is left. or a section that writes data into global variables used by a different task and therefore needs to make sure the data is consistent. is incremented so that the routine can be nested. the scheduler will be switched on again after the outermost loop is left. A typical example for a critical region would be the execution of a program section that handles a time-critical hardware access (for example writing multiple bytes into an EEPROM where the bytes have to be written in a certain amount of time). API functions Routine Description OS_EnterRegion() OS_LeaveRegion() Table 1: Critical regions API overview Indicates to the OS the beginning of a critical region. OS_EnterRegion() Description Indicates to the OS the beginning of a critical region. A critical region counter (OS_RegionCnt). PPRTOS-3 109 . Using the macro indicates to IAR PowerPac RTOS the beginning of a critical region.Critical Regions Introduction Critical regions are program sections during which the scheduler is switched off. Interrupts are not disabled using OS_EnterRegion(). /* this code will not be interrupted by the OS OS_LeaveRegion(). Example void SubRoutine(void) { OS_EnterRegion(). the critical region ends. so it does not hurt but does not do any good either to declare them as such. Prototype void OS_EnterRegion (void). disabling interrupts will disable preemptive task switches. Software timers and interrupts are executed as critical regions anyhow. Critical regions can be nested. However. meaning that no task switch and no execution of software timers are allowed except in situations where the active task has to wait.

the critical region ends. it behaves very much like a function but is much more efficient. A critical region counter (OS_RegionCnt). If this counter reaches 0 again. Additional Information OS_LeaveRegion() is not actually a function but a macro. However. Usage of the macro indicates to IAR PowerPac RTOS the end of a critical region. IAR PowerPac™ RTOS 110 User Guide PPRTOS-3 . which is 0 by default. is decremented. Example Refer to the example for OS_EnterRegion().Prototype void OS_LeaveRegion (void).

Introduction IAR PowerPac RTOS supports two basic types of run-time measurement which may be used for calculating the execution time of any section of your code. Each measurement can potentially be up to 1 tick less than the actual time. the variable OS_Time is incremented with every tick-interrupt. The low-resolution functions OS_GetTime() and OS_GetTime32() are used for returning the current contents of this variable. High resolution (using a hardware timer). PPRTOS-3 111 . Low-resolution measurements use a time base of ticks. if an interrupt actually occurs at 1. The basic idea behind low-resolution measurement is quite simple: The system time is returned once before the section of code to be timed and once after. or ms.4 ticks.Time measurement IAR PowerPac RTOS supports 2 types of time measurement: ● ● Low resolution (using a time variable). or once every ms. The problem becomes even greater with runtime measurement. while highresolution measurements are based on a time unit called a cycle. Consider the following: with a normal tick of 1 ms. so the difference between two measurements could theoretically be inaccurate by up to two ticks. The length of a cycle depends on the timer clock frequency. Both are explained in this chapter. and the first value is subtracted from the second to obtain the time it took for the code to execute. the system will still have measured only 1 tick as having elapsed). This means that the actual system time can potentially be more than what a low-resolution function will return (for example. Low-resolution measurement The system time variable OS_Time is measured in ticks. The term low-resolution is used because the time values returned are measured in completed ticks. because the system time must be measured twice.

In some cases. However with a tick of 1 ms. Return value The system variable OS_Time as a 16. Additional Information This function returns the system time as a 16-bit value on 8/16-bit CPUs. OS_GetTime32() Description Returns the current system time in ticks as a 32-bit value.The following diagram illustrates how low-resolution measurement works. Therefore. and as a 32-bit value on 32-bit CPUs.0) = 5 ms. IAR PowerPac™ RTOS 112 User Guide PPRTOS-3 . the first call to OS_GetTime() returns 0.or 32-bit integer value. if the return value is 32-bit. OS_GetTime() => 0 Code to be timed OS_GetTime() => 5 OS_Time 0. The OS_Time variable is a 32-bit value.2 ms 0 ms 1 ms 2 ms 3 ms 4 ms 5 ms 6 ms For many applications. Prototype int OS_GetTime (void). low-resolution measurement may be fully sufficient for your needs. API FUNCTIONS Routine Description OS_GetTime() OS_GetTime32() Returns the current system time in ticks.0. which means that its actual execution time is (5.7 ms. Returns the current system time in ticks as a 32-bit value.5) = 4. and the second call returns 5.2 ms.5 ms and ends at 5. We can see that the section of code actually begins at 0. If the return value is 16-bit. it is the lower 16 bits of the OS_Time variable. it is simply the entire contents of the OS_Time variable.2 . Table 1: Low-resolution measurement API overview OS_GetTime() Description Returns the current system time in ticks. The measured execution time of the code would therefore result in (5 . it may be more desirable than high-resolution measurement due to its ease of use and faster computation time.5 ms 5.

For this example.7 ms. which corresponds to 4. making high-resolution measurement about 1000 times more accurate than lowresolution calculations.000 . Although the function OS_Timing_GetCycles() may be used for returning the execution time in cycles as above. This means that with each tick-interrupt. High-resolution measurement High-resolution measurement allows for fine-tuning of time measurement. Look at the illustration below. the timer restarts at 0 and counts up to 10. Additional Information This function always returns the system time as a 32-bit value. Data structure All high-resolution routines take as parameter a pointer to a data structure of type OS_TIMING.5 ms 5.000 cycles (both values are kept track of internally).000. Because the OS_Time variable is also a 32-bit value.000 cycles. Return value The system variable OS_Time as a 32-bit integer value. the return value is simply the entire contents of the OS_Time variable. the return value would be 4. While system resolution depends on the CPU used. which measures the execution time of the same code used in the low-resolution calculation. defined as follows: #define OS_TIMING OS_U32 PPRTOS-3 113 .700 µs. which returns the value in microseconds (µs). while the call to OS_Timing_End() calculates the ending value at 52. it is typically more common to use the function OS_Timing_Getus().2 ms 0 ms 1 ms 2 ms 3 ms 4 ms 5 ms 6 ms The call to OS_Timing_Start() calculates the starting value at 5. an internal count is kept of the number of cycles that have been completed. it is typically about 1 µs. we assume that the CPU has a timer running at 10 MHz and is counting up.000 cycles. In the above example.000) = 47. OS_GetTime() => 0 Code to be timed OS_GetTime() => 5 OS_Time 0. The number of cycles per tick is therefore (10 MHz / 1 kHz) = 10.Time measurement Prototype U32 OS_GetTime32 (void).000. The measured execution time of the code in this example would therefore be (52. Instead of measuring the number of completed ticks at a given time.5.

Parameter Description pCycle Pointer to a data structure of type OS_TIMING. Prototype OS_U32 OS_Timing_Getus (OS_TIMING* pCycle). Prototype void OS_Timing_Start (OS_TIMING* pCycle). Parameter Description pCycle Pointer to a data structure of type OS_TIMING. OS_Timing_Getus() Description Returns the execution time of the code between OS_Timing_Start() and OS_Timing_End() in microseconds. Table 3: OS_TimingStart() parameter list Additional Information This function must be used with OS_Timing_End(). Returns the execution time of the code between OS_Timing_Start() and OS_Timing_End() in cycles. Table 5: OS_Timing_Getus() parameter list Additional Information The execution time in microseconds (µs) as a 32-bit integer value. IAR PowerPac™ RTOS 114 User Guide PPRTOS-3 .API FUNCTIONS Routine Description OS_TimingStart() OS_TimingEnd() OS_Timing_Getus() OS_Timing_GetCycles() Marks the beginning of a code section to be timed. Marks the end of a code section to be timed. Table 4: OS_TimingEnd() parameter list Additional Information This function must be used with OS_Timing_Start(). Table 2: High-resolution measurement API overview OS_TimingStart() Description Marks the beginning of a section of code to be timed. OS_TimingEnd() Description Marks the end of a section of code to be timed. Prototype void OS_Timing_End (OS_TIMING* pCycle). OS_Timing_GetCycles() Description Returns the execution time of the code between OS_Timing_Start() and OS_Timing_End() in cycles. Returns the execution time of the code between OS_Timing_Start() and OS_Timing_End() in microseconds. Parameter Description pCycle Pointer to a data structure of type OS_TIMING.

t = OS_GetTime(). Dummy++). UserCode(). UserCode(). tHi = BenchmarkHiRes(). } void Task(void) { int tLo. return t. } /* Burn some time */ /* * Measure the execution time with low resolution and return it in ms (ticks) */ int BenchmarkLoRes(void) { int t. /* Execute the user code to be benchmarked */ OS_Timing_End(&t).Time measurement Prototype OS_U32 OS_Timing_GetCycles (OS_TIMING* pCycle). void UserCode(void) { for (Dummy=0. /* Execute the user code to be benchmarked */ t = OS_GetTime() . Dummy < 11000. Additional Information Cycle length depends on the timer clock frequency. char ac[80].h> OS_STACKPTR int Stack[1000]. Table 6: OS_Timing_GetCycles() parameter list Return value The execution time in cycles as a 32-bit integer. OS_Timing_Start(&t). /* Task-control-blocks */ volatile int Dummy.H" #include <stdio. while (1) { tLo = BenchmarkLoRes().t. Parameter Description pCycle Pointer to a data structure of type OS_TIMING. OS_U32 tHi. PPRTOS-3 115 . /* Task stacks */ OS_TASK TCB. } /* * Measure the execution time with hi resolution and return it in us */ OS_U32 BenchmarkHiRes(void) { OS_U32 t. return OS_Timing_Getus(&t). Example The following sample demonstrates the use of low-resolution and high-resolution measurement to return the execution time of a section of code: #include "RTOS.

OS_SendString(ac). Stack). tLo). /* Start multitasking } */ */ */ */ The output of the sample is as follows: LoRes: HiRes: LoRes: HiRes: LoRes: 7 ms 6641 us 7 ms 6641 us 6 ms IAR PowerPac™ RTOS 116 User Guide PPRTOS-3 . } } /********************************************************** * * main * **********************************************************/ void main(void) { OS_InitKern(). sprintf(ac. OS_Start(). /* Initialize OS OS_InitHW(). Task. OS_SendString(ac). 100. tHi). "LoRes: %d ms\n". "HiRes: %d us\n". /* Initialize Hardware for OS /* You need to create at least one task here ! OS_CREATETASK(&TCB. "HP Task".sprintf(ac.

Important Do not alter any system variables. OS_TimeDex Basically. but they should only be altered by functions of IAR PowerPac RTOS. Instead of accessing this variable directly. Prototype extern volatile OS_I32 OS_Time. Introduction Note:Do not change the value of any system variables. However.System variables The system variables are described here for a deeper understanding of how the OS works and to make debugging easier. which is normally 1/1000 seconds (1 ms) and is normally the time between two successive calls to the IAR PowerPac RTOS interrupt handler. the task list and timer list will be checked for a task or timer to activate. If ((int)(OS_Time . After activation. use OS_GetTime() or OS_GetTime32() as explained in the Chapter Time measurement on page 111. for internal use only. Contains the time at which the next task switch or timer activation is due. These variables are accessible and are not declared constant. OS internal variables and data-structures IAR PowerPac RTOS internal variables are not explained here as they are in no way required to use IAR PowerPac RTOS. as only the documented API functions are guaranteed to remain unchanged in future versions of IAR PowerPac RTOS. Additional Information The time variable has a resolution of one time unit. especially the time variables. some of these variables can be very useful. OS_TimeDex will be assigned the time stamp of the next task or timer to be activated. Time variables OS_Time Description This is the time variable which contains the current system time in ticks (usually equivalent to ms). PPRTOS-3 117 . Your application should not rely on any of the internal variables.OS_TimeDex)) >= 0.

IAR PowerPac™ RTOS 118 User Guide PPRTOS-3 .

API FUNCTIONS Routine Description OS_TICK_Handle() OS_TICK_HandleEx() OS_TICK_Config() Table 1: API functions Standard IAR PowerPac RTOS tick handler. OS_EnterInterrupt(). OS_TICK_HandleEx() is capable of handling even fractional interrupt rates. one of these need to be called. which increments the tick count by one every time it is called. such as 1. Configures the extended IAR PowerPac RTOS tick handler. code size and execution speed. Tick handler The interrupt service routine used as time base needs to call a tick handler.6 interrupts per tick. but it can not handle situations where the interrupt rate is different from the tick rate.System tick This chapter explains the concept of the system tick. Most application use the standard tick handler OS_TICK_Handle(). This tick handler is small and efficient. Additional Information The IAR PowerPac RTOS tick handler must not be called by the application. OS_TICK_Handle() Description The default IAR PowerPac RTOS timer tick handler which is typically called by the hardware timer interrupt handler. Extended IAR PowerPac RTOS tick handler. Prototype void OS_TICK_Handle ( void ). Introduction Typically a hardware timer generates periodic interrupts used as a time base for the OS. The interrupt service routine then calls one of the tick handlers of the OS. Generating timer interrupts The hardware timer is normally initialized in the OS_InitHW() function which is delivered with the BSP. before calling the IAR PowerPac RTOS tick handler PPRTOS-3 119 . The BSP also includes the interrupt handler which is called by the hardware timer interrupt. generated by a hardware timer and all options available for it. There are different tick handlers available. This interrupt handler has to call one of the IAR PowerPac RTOS system tick handler functions which are explained in this chapter. it has to be called from an interrupt handler. or OS_EnterNestableInterrupt() has to be called. IAR PowerPac RTOS offers tick handlers with different functionality as well as a way to call a hook function from within the system tick handler. The reason why there are different tick handlers is simple: They differ in capabilities.

Table 2: OS_TICK_Config() parameter list Additional Information The “normal” tick handler OS_TICK_Handle() assumes a 1:1 ratio. OS_TICK_Config() Description Configures the tick to interrupt ratio. Refer to OS_TICK_Config() on page 120 about how to configure OS_TICK_HandleEx().Example /* Example of a timer interrupt handler */ /********************************************************************* * * OS_ISR_Tick */ __interrupt void OS_ISR_Tick(void) { OS_EnterNestableInterrupt(). OS_TICK_HandleEx(). Prototype void OS_TICK_HandleEx ( void ). unsigned FractPerTick ). OS_EnterInterrupt() or OS_EnterNestableInterrupt() has to be called before calling the IAR PowerPac RTOS tick handler. OS_LeaveNestableInterrupt(). IAR PowerPac™ RTOS 120 User Guide PPRTOS-3 . } OS_TICK_HandleEx() Description An alternate tick handler which may be used instead of the standard tick handler. Additional Information The IAR PowerPac RTOS tick handler must not be called by the application. the ratio is defined by calling the OS_TICK_Config(). Fractional value per tick. } Assuming the hardware timer runs at a frequency of 500 Hz. It can be used in situations where the basic timer-interrupt interval (tick) is a multiple of 1 ms and the time values used as parameter for delays still should use 1 ms as the time base. This should be done during OS_InitHW(). Example /* Example of a timer interrupt handler using OS_HandleTickEx */ /********************************************************************* * * OS_ISR_Tick */ __interrupt void OS_ISR_Tick(void) { OS_EnterNestableInterrupt(). OS_LeaveNestableInterrupt(). before the IAR PowerPac RTOS timer is started. the IAR PowerPac RTOS tick handler configuration function OS_TICK_Config() should be called as demonstrated in the Example section of OS_TICK_Config(). OS_TICK_HandleEx() needs to be used. Parameter Description FractPerInt FractPerTick Fractional value per interrupt. OS_TICK_Handle(). Prototype void OS_TICK_Config ( unsigned FractPerInt. meaning one interrupt increments the tick count (OS_Time) by one. thus interrupting the system every 2 ms. it has to be called from an interrupt handler. For other ratios.

System tick

Tick frequency is 1kHz, meaning one 1 equals 1ms and interrupt frequency is 500Hz, meaning 1 interrupt every 2 ms. In this case parameters have the following values:
/********************************************************************* * * _ConfigTickHandler */ static void _ConfigTickHandler() { unsigned FractPerInt; unsigned FractPerTick; FractPerInt = 2; FractPerTick = 1; OS_TICK_Config(FractPerInt, FractPerTick); }

Note that fractional values are supported, such as tick is 1 ms, where an interrupt is generated every 1.6ms. This means that FractPerInt and FractPerTick are:
FractPerInt = 16; FractPerTick = 10;

or
FractPerInt = 8; FractPerTick = 5;

Hooking into the system tick
There are various situations in which it can be desirable to call a function from the tick handler. Some examples are:
● ● ●

Watchdog update Periodic status check Periodic I/O update

The same functionality can be achieved with a high-priority task or a software timer with 1 tick period time.

Advantage of using a hook function
Using a hook function is much faster than performing a task switch or activating a software timer, because the hook function is directly called from the IAR PowerPac RTOS timer interrupt handler and does not cause a context switch.

API FUNCTIONS
Routine Description

OS_TICK_AddHook() OS_TICK_RemoveHook()
Table 3: API functions

Adds a tick hook handler. Removes a tick hook handler.

OS_TICK_AddHook()
Description
Adds a tick hook handler.

Prototype
void OS_TICK_AddHook ( OS_TICK_HOOK * pHook, OS_TICK_HOOK_ROUTINE * pfUser );
Parameter Description

pHook pfUser

Pointer to a structure of OS_TICK_HOOK. Pointer to an OS_TICK_HOOK_ROUTINE function.

Table 4: OS_TICK_AddHook() parameter list

PPRTOS-3

121

Additional Information
The hook function is called directly from the interrupt handler. The function therefore should execute as fast as possible. The function called by the tick hook must not re-enable interrupts.

OS_TICK_RemoveHook()
Description
Removes a tick hook handler.

Prototype
void OS_TICK_RemoveHook ( OS_TICK_HOOK * pHook );
Parameter Description

pHook

Pointer to a structure of OS_TICK_HOOK.

Table 5: OS_TICK_RemoveHook() parameter list

Additional Information
The function may be called to dynamically remove a tick hook function which was installed by a call of OS_TICK_AddHook().

IAR PowerPac™ RTOS

122 User Guide

PPRTOS-3

Configuration of target system (BSP)
This chapter explains the target system specific parts of IAR PowerPac RTOS, also called BSP (board support package). If the system is up and running on your target system, there is no need to read this chapter.

Introduction
You do not have to configure anything to get started with IAR PowerPac RTOS. The start project supplied will execute on your system. The file RTOSINIT.c is provided in source code and can be modified to match your target hardware needs. It is compiled and linked with your application program.

Hardware-specific routines
Routine Description

OS_InitHW()

Initializes the hardware timer used for generating interrupts. IAR PowerPac RTOS needs a timer-interrupt to determine when to activate tasks that wait for the expiration of a delay, when to call a software timer, and to keep the time variable upto-date. The idle loop is always executed whenever no other task (and no interrupt service routine) is ready for execution. Reads the timestamp in cycles. Cycle length depends on the system. The IAR PowerPac RTOS timer-interrupt handler. When using a different timer, always check the specified interrupt vector.

OS_Idle() OS_GetTime_Cycles() OS_ISR_Tick()
Table 1: Hardware specific routines

Configuration defines
For most embedded systems, configuration is done by simply modifying the following defines, located at the top of the RTOSInit.c file:
Define Description

OS_FSYS

System frequency (in Hz). Example: 20000000 for 20MHz.

Table 2: Configuration defines overview

How to change settings
The only file which you may need to change is RTOSInit.c. This file contains all hardware-specific routines. The one exception is that some ports of IAR PowerPac RTOS require an additional interrupt vector table file (details can be found in the CPU & Compiler Specifics manual of IAR PowerPac RTOS documentation).

SETTING THE SYSTEM FREQUENCY OS_FSYS
Relevant defines:

PPRTOS-3

123

to switch the CPU to power-saving mode during idle times. If required. IAR PowerPac RTOS usually generates 1 interrupt per ms. the basic time unit can be made 1 ms by using the configuration function OS_TICK_Config(). read the comments in RTOSInit. the value of the time variable OS_Time will no longer be equivalent to multiples of 1 ms. USING A DIFFERENT TIMER TO GENERATE THE TICKINTERRUPTS FOR IAR POWERPAC RTOS Relevant routines: OS_ InitHW() IAR PowerPac RTOS usually generates 1 interrupt per ms.OS_FSYS For most systems it should be sufficient to change the OS_FSYS define at the top of RTOSInit. However. The value of OS_FSYS is used for calculating the desired reload counter value for the system timer for 1000 interrupts/sec. you may modify the OS_Idle() routine. As long as the timer-interrupt will wake up the system with every IAR PowerPac RTOS tick. STOP / HALT / IDLE modes Most CPUs support power-saving STOP. it might just as well be 100 µs or 10 ms or any other value. Different (lower or higher) interrupt rates are possible. Refer to the CPU & Compiler Specific guide of IAR PowerPac RTOS documentation for details about your processor. making the timer-interrupt. these modes may be used for saving power consumption. IAR PowerPac™ RTOS 124 User Guide PPRTOS-3 . Refer to Tick handler on page 119 for detailed information. normally equal to 1 ms.c. OS_FSYS defines the clock frequency of your system in Hz (times per second). or IDLE modes. For details about initialization.c. If you have to use a different timer for your application. If you choose an interrupt frequency different from 1 kHz. CHANGING THE TICK FREQUENCY Relevant defines: OS_FSYS As noted above. or as long as other interrupts will activate tasks. which is part of the hardware-dependant module RTOSInit. you must modify OS_InitHW() to initialize the appropriate timer.c. Because 1 ms is an appropriate value for most applications. HALT. or tick. the basic time unit does not have to be 1 ms. This is done by a timer initialized in the routine OS_InitHW(). The interrupt frequency is therefore normally 1 kHz. Using these types of modes is one possible way to save power consumption during idle times.

The sections below describe these individual windows. The amount of information available depends on the IAR PowerPac RTOS build used during debugging. the respective menu item is either greyed out or the window column shows a N/A. Note that if you are not running a debugging session. For each project configuration you have to explicitly enable the plug-in in the debugger section of the project options: The IAR PowerPac RTOS C-SPY plug-in is now available in debugging sessions and may be accessed from the main menu. If a certain part is not available. Enabling the C-SPY plug-in module By default. the IAR PowerPac RTOS C-SPY plug-in is accessible from the IAR Embedded Workbench IDE main menu.RTOS-aware debugging This chapter describes the IAR PowerPac RTOS C-SPY plug-in and its capabilities in greater detail. the IAR PowerPac RTOS C-SPY plug-in is not loaded during debugging. PPRTOS-3 125 . Overview During your debugging session. From the menu you may activate the individual windows that provide IAR PowerPac RTOS related information. the IAR PowerPac RTOS menu is not available.

this column displays the timeout value and in parentheses the point in time when the delay will be finished. and the available stack space. the task name is displayed here. this column displays the number of remaining time slices and the number of time slice reloads. as well as the value of the current stack bottom pointer. this column shows the amount of used stack space. The task status as a short text. The task control block address that uniquely identifies a task. that is their address and name.Task list The Task List window lists all current tasks. waiting tasks etc. Column Description Id Messages Message size pBuffer Waiting tasks The mailbox address. The number of messages in a mailbox and the maximum number of messages as mailbox can hold. If round robin scheduling is available. If a task is delayed. If available. The buffer behaves like a normal buffer. The message buffer address. Table 4: Mailboxes window items IAR PowerPac™ RTOS 126 User Guide PPRTOS-3 . The number of task activations. you can put something (called a message) in and retrieve it later. The size of an individual message in bytes. This window shows the mailboxes and provides information about the number of messages. It retrieves its information directly from the IAR PowerPac RTOS task list. The individual columns are described below: Column Description * Id Name Status Timeout Events Stack Info Activations Round Robin A green arrow points at the currently active task. Table 3: Task list window items Mailboxes A mailbox is a buffer that is managed by the real-time operating system. The list of tasks that are waiting for a mailbox. If available. The event mask of a task.

The time delay and the point in time. The time period the timer runs. This window provides information about active software timers. This window provides information about available resources. Counts the number of semaphore uses. The address and name of the owner task. Table 5: Timers window items Resource semaphores Resource semaphores are used to manage resources by avoiding conflicts caused by simultaneous use of a resource.RTOS-aware debugging Timers A software timer is an object that calls a user-specified routine after a specified delay. Column Description Id Hook Time Period Active The timer’s address. Column Description Id Owner Use counter Waiting tasks The resource semaphore address. Shows whether the timer is active or not. Table 6: Resource Semaphores window items PPRTOS-3 127 . The function (address and name) that is called after the timeout. Lists the tasks (address and name) that are waiting at the semaphore. when the timer finishes waiting.

for example when hitting the next breakpoint. After changing settings and clicking the OK button. IAR PowerPac™ RTOS 128 User Guide PPRTOS-3 .System information A running IAR PowerPac RTOS contains a number of system variables that are available for inspection. to avoid endless requests in case of false values in the target memory. the settings are restored to their default values on plug-in reload. This window lists the most important ones. your changes are applied immediately and should become noticeable after the next window update. or if they are longer than the default you may increase that value. However. Settings To be safe. for example if your task names are no longer than 32 characters you may set the Maximum string length to 32. This dialog box allows you to tweak these limits in a certain range. the IAR PowerPac RTOS C-SPY plug-in imposes certain limits on the amount of information retrieved from the target.

If IAR PowerPac RTOS detects a runtime error. } When using an emulator.Debugging Runtime errors Some error conditions can be detected during runtime. after re-enabling interrupts. This routine is shipped as source code as part of the module OS_Error. the first statement needs to be the disabling of scheduler via OS_EnterRegion(). you will see that it is more complicated than necessary. Unfortunately. while (OS_Status). you should set a breakpoint at the beginning of this routine or simply stop the program after a failure. looking at this part of the program will make the problem clear. it calls the following routine: void OS_Error(int ErrCode). It simply disables further task switches and then. OS_Status = ErrCode. /* Avoid further task switches */ OS_DICnt =0. The program then waits for this variable to be reset. Simply reset this variable to 0 using your in circuit-emulator. loops forever as follows: Example /* Run time error reaction */ void OS_Error(int ErrCode) { OS_EnterRegion(). These are: ● ● ● ● ● Usage of uninitialized data structures Invalid pointers Unused resource that has not been used by this task before OS_LeaveRegion() called more often than OS_EnterRegion() Stack overflow (this feature is not available for some processors) Which runtime errors that can be detected depend on how much checking is performed. additional checking costs memory and speed (it is not that significant. and you can easily step back to the program sequence causing the problem. The error code is passed to the function as parameter. You can modify the routine to accommodate your own hardware. The actual error code is assigned to the global variable OS_Status. Note:When modifying the OS_Error() routine. If you look at the OS_Error() routine. the last statement needs to be the infinite loop. PPRTOS-3 129 . Most of the time. this could mean that your target hardware sets an error-indicating LED or shows a little message on the display. but there is a difference).c. /* Allow interrupts so we can communicate */ OS_EI().

OS_ERR_LEAVEINT OS_ERR_DICNT Error in OS_LeaveInterrupt(). not initialized or overwritten. The mailbox is not in the list of mailboxes as expected. Illegal function call in an interrupt service routine: A routine that may not be called from within a software timer has been called from within a timer. Control block for counting semaphore invalid. OS_Unuse() has been called before OS_Use(). Control block for resource semaphore invalid. The OS internal task list is destroyed. One of the following 1-byte mailbox functions has been used on a multi. OS_Unuse() has been called from a task which does not own the resource. not initialized or overwritten. Illegal function call in an interrupt service routine: A routine that may not be called from within an ISR has been called from within an ISR. Possible reasons may be that one mailbox data structure was overwritten.byte mailbox: OS_PutMail1() OS_PutMailCond1() OS_GetMail1() OS_GetMailCond1(). not initialized or overwritten. Task control block invalid. The counter is affected by the following API calls: OS_IncDI() OS_DecRI() OS_EnterInterrupt() OS_LeaveInterrupt() OS_Delay() or OS_DelayUntil() called from inside a critical region with interrupts disabled. but interrupt vector not initialized. 136 137 138 140 OS_ERR_MAILBOX_DELETE OS_ERR_CSEMA_DELETE OS_ERR_RSEMA_DELETE OS_ERR_MAILBOX_NOT_IN_LIST 142 150 151 152 153 OS_ERR_TASKLIST_CORRUPT OS_ERR_UNUSE_BEFORE_USE OS_ERR_LEAVEREGION_BEFORE_ENTERREG OS_LeaveRegion() has been called before ION OS_EnterRegion(). OS_DeleteMB() was called on a mailbox with waiting tasks. 154 156 160 OS_ERR_INTERRUPT_DISABLED OS_ERR_RESOURCE_OWNER OS_ERR_ILLEGAL_IN_ISR 161 OS_ERR_ILLEGAL_IN_TIMER Table 1: Error code list IAR PowerPac™ RTOS 130 User Guide PPRTOS-3 .List of error codes Value Define Explanation 100 101 120 121 128 129 130 132 133 135 OS_ERR_ISR_INDEX OS_ERR_ISR_VECTOR OS_ERR_STACK OS_ERR_CSEMA_OVERFLOW OS_ERR_INV_TASK OS_ERR_INV_TIMER OS_ERR_INV_MAILBOX OS_ERR_INV_CSEMA OS_ERR_INV_RSEMA OS_ERR_MAILBOX_NOT1 Index value out of bounds during interrupt controller initialization or interrupt installation. not initialized or overwritten. Default interrupt handler called. OS_DeleteRSema() was called on a resource semaphore which is claimed by a task. Mailbox control block invalid. Counting semaphore overflow. Timer control block invalid. Stack overflow or invalid stack. The interrupt disable counter (OS_DICnt) is out of range (0-15). OS_DeleteCSema() was called on a counting semaphore with waiting tasks. not initialized or overwritten.

Pointer to memory block does not belong to memory pool on Release Pointer to memory block is already free when calling OS_MEMF_Release(). Mailbox control block has been initialized by calling a create function twice. OS_CreateTask() was called with a task priority which is already assigned to another task. same pointer was released twice. Resource semaphore has been initialized by calling a create function twice. Fixed size memory block control structure not created before use. Timer control block has been initialized by calling a create function twice. Counting semaphore has been initialized by calling a create function twice. OS_Rx interrupt handler for embOSView is nested. This error can only occur when IAR PowerPac RTOS was compiled without round robin support. Task control block has been initialized by calling a create function twice. Possibly. OS_MEMF_Create() was called with a memory pool base address which is not located at a word aligned base address OS_MEMF_Create() was called with a data block size which is not a multiple of processors word size.Debugging Value Define Explanation 162 OS_ERR_ILLEGAL_OUT_ISR IAR PowerPac RTOS timer tick handler or UART handler for embOSView was called without a call of OS_EnterInterrupt().c. OS_MEMF_Release() was called for a memory pool. that had no memory block allocated (all available blocks were already free before). Fixed size memory pool has been initialized by calling a create function twice. Nested call of OS_Suspend() exceeded OS_MAX_SUSPEND_CNT OS_Resume() called on a task that was not suspended. An OS_EVENT object was created twice. Disable nestable interrupts. PPRTOS-3 131 . An OS_EVENT object was used before it was created. An OS_EVENT object was deleted with waiting tasks 170 171 172 174 175 176 180 190 191 192 OS_ERR_2USE_TASK OS_ERR_2USE_TIMER OS_ERR_2USE_MAILBOX OS_ERR_2USE_CSEMA OS_ERR_2USE_RSEMA OS_ERR_2USE_MEMF OS_ERR_NESTED_RX_INT OS_ERR_MEMF_INV OS_ERR_MEMF_INV_PTR OS_ERR_MEMF_PTR_FREE 193 OS_ERR_MEMF_RELEASE 194 OS_ERR_POOLADDR 195 200 201 202 OS_ERR_BLOCKSIZE OS_ERR_SUSPEND_TOO_OFTEN OS_ERR_RESUME_BEFORE_SUSPEND OS_ERR_TASK_PRIORITY 210 211 212 OS_ERR_EVENT_INVALID OS_ERR_2USE_EVENTOBJ OS_ERR_EVENT_DELETE Table 1: Error code list (Continued) The latest version of the defined error table is part of the comment just before the OS_Error() function declaration in the source file OS_Error.

IAR PowerPac™ RTOS 132 User Guide PPRTOS-3 .

1600 bytes * 18 . Segger uses these programs to benchmark the IAR PowerPac RTOS performance.Performance and resource usage This chapter covers the performance and resource usage of IAR PowerPac RTOS. It explains how to benchmark IAR PowerPac RTOS and information about the memory requirements in typical systems which can be used to obtain sufficient estimates for most target systems.5 bytes * 9 .25 bytes * 9 . and library model used Performance The following section shows how to benchmark IAR PowerPac RTOS using the supplied example programs. compiler. IAR PowerPac RTOS runs on 8/16/32-bit CPUs. even single-chip systems with less than 2 Kbytes ROM and 1 Kbyte RAM can be supported by IAR PowerPac RTOS. Note. The first method uses port pins and requires an oscilloscope. Example programs for both methods are supplied in the \Example directory of your IAR PowerPac RTOS shipment. configuration.15 bytes * 3 bytes 4 . The second method uses the high-resolution measurement functions. clock speed. Introduction High performance combined with low resource usage has always been a major design consideration. Depending on which features are being used. The following table shows the memory requirements for the different modules.11 bytes * 0 bytes * Depends on CPU. memory model. This section describes two different methods to calculate the execution time of a context switch from a task with lower priority to a task with a higher priority. compiler. Benchmarking IAR PowerPac RTOS is designed to perform fast context switches.). etc. You can use these examples to evaluate the benchmark results. memory model. Memory requirements The memory requirements of IAR PowerPac RTOS (RAM and ROM) differ depending on the used features of the library. optimization. configuration. etc. optimization. that the actual performance depends on many factors (CPU. The actual performance and resource usage depends on many factors (CPU.). Module Memory type Memory requirements IAR PowerPac RTOS kernel IAR PowerPac RTOS kernel Mailbox Binary and counting semaphores Resource semaphore Timer Event Table 1: IAR PowerPac RTOS memory requirements ROM RAM RAM RAM RAM RAM RAM 1100 . PPRTOS-3 133 . toolchain.

MEASUREMENT WITH PORT PINS AND OSCILLOSCOPE The example file MeasureCST_Scope. // Syncronize to tick to avoid jitter // // Display measurement overhead // LED_SetLED0(). StackLP). 100. "HP Task".562us 7. // Stop measurement } } /********************************************************************* * * LPTask */ static void LPTask(void) { while (1) { OS_Delay(100). HPTask.187us All example performance values in the following section are determined with the following system configuration: ATMEL AT91SAM7S256 running with 48 MHz clock speed. The following source code is excerpt from MeasureContextSwitchingTime_Scope. // Task stacks // Task-control-blocks /********************************************************************* * * HPTask */ static void HPTask(void) { while (1) { OS_Suspend(NULL).c: #include "RTOS. StackLP[128]. OS_Start().The following table gives an overview about the variations of the context switch time depending on the memory type and the CPU mode: Target Memory CPU mode Time ATMEL AT91SAM7S256 ATMEL AT91SAM7S256 ATMEL AT91SAM7S256 ATMEL AT91SAM7S256 Table 2: IAR PowerPac RTOS context switch times Flash Flash RAM RAM Thumb ARM ARM Thumb 7.c module to set and clear a port pin. LED_ClrLED0(). TCBLP. All sources are compiled with IAR Embedded Workbench version 4.h" static OS_STACKPTR int StackHP[128]. static OS_TASK TCBHP. OS_CREATETASK(&TCBLP. // Suspend high priority task LED_ClrLED0(). This allows measuring the context switch time with an oscilloscope. // Start multitasking return 0.896us 6. // // Perform measurement // LED_SetLED0(). LPTask.h" #include "LED. // Initialize Hardware for OS LED_Init(). // Resume high priority task to force task switch } } /********************************************************************* * * main */ int main(void) { OS_IncDI(). 99.c uses the LED. The example program executes in of flash memory. "LP Task". // Initialize OS OS_InitHW(). StackHP).40A using Thumb mode with high optimization level.875us 5. // Start measurement OS_Resume(&TCBHP). } IAR PowerPac™ RTOS 134 User Guide PPRTOS-3 . // Initially disable interrupts OS_InitKern(). // Initialize LED ports OS_CREATETASK(&TCBHP.

The real context switch time is shorter. The time needed for a complete context switch including the time needed to switch the LED on and off in subroutines is marked as time tCD.866ns PPRTOS-3 135 .c Hardware: AT91SAM7S256 processor with 48MHz Program is executing in RAM ARM mode is used Compiler used: IAR Embedded Workbench V4. The picture below shows a simplified oscilloscope signal with an active-low LED signal (low means LED is illuminated).501) CPU frequency (fCPU): 47.40.tAB Voltage [V] A B C D tAB tCD Time [t] Example measurements for AT91SAM7S and ARM code in RAM Task switching time has been measured with the parameters listed below: Application program: MeasureCST_Scope. The time of this overhead is also displayed on the oscilloscope as a small peak right before the task switch time display and has to be subtracted from the displayed context switch time. If the LED is switched on with an active low signal.40A (4.9232MHz CPU clock cycle (tCycle): tCycle = 1 / fCPU = 1 / 47. the context switch time is the time between rising and falling edge of the signal. the signal polarity is reversed.1.9232MHz = 20. If the LED is switched on with an active high signal. The context switching time tCS is calculated as follows: tCS = tCD . because the signal also contains the overhead of switching the LED on and off. There are switching points to determine: ● ● ● ● ● A = LED is switched on for overhead measurement B = LED is switched off for overhead measurement C = LED is switched on right before context switch in low-priority task D = LED is switched off right after context switch in high-priority task D = LED is switched off right after context switch in high-priority task The time needed to switch the LED on and off in subroutines is marked as time tAB.Performance and resource usage Oscilloscope analysis The context switch time is the time between switching the LED on and off.

6ns / 20.1. The number of cycles calculates as follows: CyclesAB = tAB / tCycle =312ns / 20.952Cycles => 15Cycles tCD is measured as 6217. The number of cycles calculates as follows: CyclesCD = tCD / tCycle = 6217.Measuring tAB and tCD tAB is measured as 312ns.6ns.tAB = 298Cycles .501) CPU frequency (fCPU): 47.866ns IAR PowerPac™ RTOS 136 User Guide PPRTOS-3 .9232MHz CPU clock cycle (tCycle): tCycle = 1 / fCPU = 1 / 47.40A (4.866ns = 297.9232MHz = 20.15Cycles = 283Cycles => 283Cycles (5.9us @48MHz).977Cycles => 298Cycles Resulting context switching time and number of cycles The time which is required for the pure context switch is: tCS = tCD . Example measurements for AT91SAM7S and Thumb code in FLASH Task switching time has been measured with the parameters listed below: Application program: MeasureCST_Scope.866ns = 14.40.c Hardware: AT91SAM7S256 processor with 48MHz Program is executing in FLASH Thumb mode is used Compiler used: IAR Embedded Workbench V4.

973Cycles => 384Cycles Resulting context switching time and number of cycles The time required for the pure context switch is: tCS = tCD . Refer to section High-resolution measurement on page 113 for detailed information about the IAR PowerPac RTOS high-resolution measurement.8ns. PPRTOS-3 137 .tAB = 384Cycles .c uses a high resolution timer to measure the context switch time from a low priority task to a high priority task and display the results on stdout.56us @48MHz).866ns = 20.866ns = 383. The number of cycles calculates as follows: CyclesAB = tAB / tCycle =436. The number of cycles calculates as follows: CyclesCD = tCD / tCycle = 8012ns / 20. The example MeasureContextSwitchingTime_HRTimerCSpy.8ns / 20.933Cycles => 21Cycles tCD is measured as 8012ns.21Cycles = 363Cycles => 363Cycles (7.Performance and resource usage Measuring tAB and tCD tAB is measured as 436. Measurement with high-resolution timer The context switch time may be measured with the high-resolution timer.

OS_Timing_GetCycles(&MeasureOverhead). // // Perform measurements in endless loop // while (1) { OS_Delay(100). v = OS_ConvertCycles2us(1000 * v). v / 1000.h" #include "stdio. // Task stacks // Task-control-blocks // Timer values /********************************************************************* * * HPTask */ static void HPTask(void) { while (1) { OS_Suspend(NULL). // Resume high priority task to force task switch v = OS_Timing_GetCycles(&_Time) .3u usec\r\n". } } The example program calculates and subtracts the measurement overhead itself. printf("Context switch time: %u. // Stop measurement } } /********************************************************************* * * LPTask */ static void LPTask(void) { OS_U32 MeasureOverhead. static OS_TASK TCBHP. Use the C-SPY terminal I/O window to check the results. StackLP[128].%. // Suspend high priority task OS_Timing_End(&_Time).h" static OS_STACKPTR int StackHP[128]. // Time for Measure Overhead OS_U32 v. // Syncronize to tick to avoid jitter OS_Timing_Start(&_Time). TCBLP.#include "RTOS. // OS_Timing_End(&MeasureOverhead). // // Measure overhead for time measurement so we can take this into // account by subtracting it OS_Timing_Start(&MeasureOverhead). IAR PowerPac™ RTOS 138 User Guide PPRTOS-3 . // Start measurement OS_Resume(&TCBHP). v % 1000). so there is no need to do this. static OS_U32 _Time.

If for some reason you need to have nonreentrant routines in your program that can be used from more than one task.Reentrancy Reentrance All routines that can be used from different tasks at the same time have to be fully reentrant. Everything else has to be thought about carefully. PPRTOS-3 139 . the C compiler generates code that is fully reentrant. Assembly routines and reentrance As long as assembly functions access local variables and parameters only. It is recommended not to use these options. A routine is in use from the moment it is called until it returns or the task that has called it is terminated. although it is possible to do so under certain circumstances. the compiler may have options that force it to generate non-reentrant code. C routines and reentrance Normally. However. they are fully reentrant. it is recommended to use a resource semaphore to avoid this kind of problem. All routines supplied with your real-time operating system are fully reentrant.

IAR PowerPac™ RTOS 140 User Guide PPRTOS-3 .

PPRTOS-3 141 .Limitations The following limitations exist for IAR PowerPac RTOS: Maximum number of tasks: Maximum number of priorities: Maximum number of semaphores: Maximum number of mailboxes: Maximum number of queues: Maximum size of queues: Maximum number of timers Task specific event flags: limited by available RAM only 255 limited by available RAM only limited by available RAM only limited by available RAM only limited by available RAM only limited by available RAM only 8 bits / task If you need to make changes to IAR PowerPac RTOS. the full source code is optionally available.

IAR PowerPac™ RTOS 142 User Guide PPRTOS-3 .

The full source version gives you the ultimate options: IAR PowerPac RTOS can be recompiled for different data sizes. To start the batch build click BuildLibs. Because this document describes the object version.bat. the internal data structures are not explained in detail. The batch files are located under <ToolchainDir>\ARM\PowerPac\RTOS\Src\. The compile-time switches must be changed in RTOS. It also contains DOS batch files that can be used for rebuilding the complete set of the IAR PowerPac RTOS libraries. IAR PowerPac RTOS Normally. the object version does not allow source-level debugging of the library routines and the kernel. The object version offers the full functionality of IAR PowerPac RTOS including all supported configuration of the compiler. Nothing else should require changes Major compile time switches Many features of IAR PowerPac RTOS may be modified by compile-time switches. However. different compile options give you full control of the generated code. The source code distribution of IAR PowerPac RTOS contains the following additional files: ● ● ● The \Src\ folder contains all source code part of the distribution.Source code of kernel and library Introduction IAR PowerPac RTOS is available in two versions: 1 Object version: Object code + hardware initialization source. You can debug the entire system and even modify it for new memory models or other CPUs. or has to be passed as parameters during the library build process. The IAR PowerPac RTOS libraries can only be built if you have purchased a source code version of IAR PowerPac RTOS. PPRTOS-3 143 . Building IAR PowerPac RTOS libraries IAR PowerPac RTOS is shipped with different prebuilt libraries. 2 Full source version: Complete source code.bat and modify the _TOOLPATH_ variable. The \RTOS\Src\GenOSSrc folder contains all IAR PowerPac RTOS source files. making it possible to optimize the system for versatility or minimum memory requirements.h.bat points to the main directory of your compiler relative to the default installation path of IAR PowerPac RTOS. Open BuildLibs. You should be able to build the library without any error or warning messages. you should not modify any of the files in the CPU folder. The \RTOS\Src\CPU folder contains all CPU and compiler specific source code and header files used for building the IAR PowerPac RTOS libraries. Batch files for building the library from the command line are provided. If you have changed the default installation path of IAR PowerPac RTOS the batch build will fail. because the _TOOLPATH_ variable in BuildLibs. All of them are predefined to reasonable values in the distribution of IAR PowerPac RTOS. the debug libraries as described and the source code for idle task and hardware initialization. An example workspace for building a library is also available. IAR PowerPac RTOS sources have to be recompiled with the modified switches.

IAR PowerPac™ RTOS 144 User Guide PPRTOS-3 . or if your application ensures. this switch is activated for 16. If you never use round robin scheduling and all of your tasks run on different individual priorities. Note:By default. you may disable round robin scheduling by defining this switch to 0. it allows termination of tasks which are claiming resource semaphores or are suspended on any synchronization object. When using an 8-bit CPU. All IAR PowerPac RTOS versions enable round robin scheduling by default.and 32-bit CPUs. For 8-bit CPUs it is disabled. Disabling this switch will save some RAM in the task control structure and will also speed up the wait functions for synchronization objects.OS_RR_SUPPORTED This switch defines whether round robin scheduling algorithm is supported. OS_SUPPORT_CLEANUP_ON_TERMINATE IAR PowerPac RTOSIf enabled. Even though the overhead is minimal and execution time is not affected significantly. that tasks are never suspended on any synchronization object or claim any resource semaphores when they are terminated. you have to enable this switch (define it to be unequal to 0) to enable termination of tasks which are suspended on synchronization objects or claim resource semaphores. you may define this switch to zero when you do not terminate tasks in your application. This will save RAM and ROM and will also speed up the task-switching process. Ensure that none of your tasks ever run on the same priority when you disable round robin scheduling.

Normally. the system is fully dynamic. What interrupt priorities can I use for the interrupts my program uses? Any. Can I use a different interrupt source for IAR PowerPac RTOS? Yes. Q: A: Q: A: PPRTOS-3 145 . that is any internal timer. the prioritycontrolled round-robin algorithm is perfect for real-time applications. any periodical signal can be used.FAQ (frequently asked questions) Q: A: Can I implement different priority scheduling algorithms? Yes. which means that task priorities can be changed while the system is running (using OS_SetPriority()). This feature can be used for changing priorities in a way so that basically every desired algorithm can be implemented. One way would be to have a task control task with a priority higher than that of all other tasks that dynamically changes priorities. but it could also be an external signal.

IAR PowerPac™ RTOS 146 User Guide PPRTOS-3 .

Example: Watchdog timer-interrupt. Interrupt Service Routine. The OS divides the processor's time so that the different routines (tasks) appear to be happening simultaneously. ISRs must preserve the entire context of a task (all registers). Queue PPRTOS-3 147 . A data buffer managed by the RTOS. The task that is currently executing is called the active task. queue. A message sent to a single. A section of code which must be executed without interruption. Short for microprocessor. If an ISR makes a higher priority task ready. Cooperative multitasking Counting semaphore CPU Critical region Event ISR Mailbox Message Multitasking NMI Preemptive multitasking Processor Priority Priority inversion A situation in which a high priority task is delayed while it waits for access to a shared resource which is in use by a lower priority task. A scheduling system in which the highest priority task that is ready will always be executed. to a task or an interrupt handler. or other container for data). The “brain” of a microcontroller. used for sending messages to a task or interrupt handler. The CPU core of a controller The relative importance of one task to another. but used for sending larger messages. Non-Maskable Interrupt. Like a mailbox. but the interrupted task will be returned to and finished first. The task then becomes ready. the part of a processor that carries out instructions. that task will be executed before the interrupted task is returned to. or messages of individual size. A type of semaphore that keeps track of multiple resources. Every task in an RTOS has a priority. An item of data (sent to a mailbox. Central Processing Unit.Glossary Active Task Only one task can execute at any given time. A scheduling system in which each task is allowed to run until it gives up the CPU. An interrupt that cannot be masked (disabled) by software. The execution of multiple software routines independently of one another. The lower priority task temporarily gets the highest priority until it releases the resource. The routine is called automatically by the processor when an interrupt is acknowledged. an ISR can make a higher priority task ready. Used when a task must wait for something that can be signaled more than once. specified task that something has occurred.

their relative priorities. A program running on a processor. computation time). The program section of an RTOS that selects the active task. anything used by a task. A multitasking system allows multiple tasks to execute independently from one another. Superloop Task Tick Timeslice IAR PowerPac™ RTOS 148 User Guide PPRTOS-3 . The time (number of ticks) for which a task will be executed until a round-robin task change may occur. timers. Essentially. return addresses. ISRs are used for realtime parts of the software. The OS timer interrupt. In multitasking systems. An area of memory with FIFO storage of parameters. A program that runs in an infinite loop and uses no real-time kernel. Real-time Operating System. Resource semaphore RTOS Scheduler Semaphore Software timer Stack A data structure used for synchronizing tasks. A type of semaphore used for managing resources by ensuring that only one task has access to a resource at a time. and other information that needs to be maintained across function calls.Resource Anything in the computer system with limited availability (for example memory. based on which tasks are ready to run. Usually equals 1 ms. automatic variables. A data structure which calls a user-specified routine after a specified delay. and the scheduling system being used. each task normally has its own stack.

. . 24 OS_CallISR() . . . . . . 91–95 Multitasking systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 preemptives multitasking. . . 87 OS_EVENT_Pulse() . . . . . . . . . 104 OS_CallNestableISR() . . . . . . . . . 43 OS_CreateTimer() . . . . . . . . . . . . . . . . . . . . 28 OS_Delay() . . . . . . . . .16. . . . . . . . . . . . . . . . . 24 OS_CreateTask() . . . . . . . 68 OS_CREATECSEMA() . . . . . . . . . . . 61 single-byte . . . . . . . . . . . . . . 56 OS_CREATEMB() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Interrupt control macros . . . . . 55 OS_CreateCSema() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 features of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 OS_CREATERSEMA() . . . . . . . . . . . . . . . . . . . 59 OS_DeleteMB() . . . . . . . . . 107 OS_EI() . . . . . . 108 O OS . . . . . . .17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Memory management fixed block size . . . . . . . . . . . . . . . . . . . 80 OS_ClearMB() . . . . . . . . . . . . . . . . . . . . . 19 Configuration defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 L Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 high-resolution . . . . . . . . 69 OS_DeleteTimer() . . . . 104 OS_ClearEvents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Non-maskable interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 N Nesting interrupts . . . . . . of embOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 OS_EVENT_Delete() . . . . . . . . . . . . . . . . . . . . . . . 143 Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38. . . . . . . . . . . . . . . . . . . . . . 107 Interrupt level . . . . . . . . . . . . . . . . . . . . . . . . . 87 OS_EVENT_Get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . of embOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 OS_DI() . . . . . . . . . . . . . 21 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . building . . . . . . . . . . . 13 cooperative multitasking . 51 OS_CreateTaskEx() . of embOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Measurement . . . 113 low-resolution . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Counting Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . of this guide . . . .129–131 error codes . . 83–88 G guidelines. . . . . . . 123 Configuration. . . . . . . . . . . . . . . . 109 OS_EVENT_Create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 OS_EnterInterrupt() . . . 106 OS_DelayUntil() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 OS_EVENT_Reset() . . 85 E edition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77–81. . . . . . . . . . . . . . . . . . . . . . . . . 13 Interrupts . . . . . . . . . . . . . . 106 interrupt handler . . . . . . . . . 129 disclaimer . . . . . . . . . . . . . . . . . . .119. . . . . . . . . . . 2 embOS building libraries of . . . . . . . . . . . . . . . . . 39. . . . . . . . . . . . . . . . . . . . . . . . . 91 Memory pools . . . . . . . . . . . . 130 runtime errors . . . . . . . . . . . . . 55 Critical regions . 27 OS_CREATETASK() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101–108 enabling/disabling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Index Index C C startup . . . . . . . . . . . . . . 109–110 M Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 different builds of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 OS_EVENT_Set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Interrupt service routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Events . . . . . . . 17. . . . 11 Error codes . . 25 OS_CREATETASK_EX() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 I Internal data-structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104–105 OS_EnterNestableInterrupt() . . . . . . . . . . . . . . . . . . . . . . . . . . 123–124 copyright notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 OS_DecRI() . . . . . . . . . . . . . . 41. . . . . . . . . . . . . . . . . . . . . reading. . . . . . . 2 document conventions . . . . . . . . . 20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 OS_EnterRegion() . . . . . . . 26 OS_CREATETIMER() . . . 15 D Debug version. . . . . . 11 embOS features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61–69 basics . . . . . . . . . . . . . . . 141 PPRTOS-3 149 . . . . . . . . . . . . . . . . . . 28 OS_DeleteCSema() . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 OS_MEMF_Release(). 74 OS_Q_Put() . . . . . . . . . . . . . . . . . . . . . . . . 107 OS_Resume() . . . . . . . . . . . . . . . . . . . . . . 99 OS_GetStackUsed() . . . . . . . . . . . . .42. . . 47 OS_GetTime() . . . . . . . 58 OS_SetPriority() . . . . . . . . . . . . . 32 OS_RetriggerTimer() . . . . . . . . . . . . 77 OS_WaitMail(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 OS_Timing_Getus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 150 User Guide PPRTOS-3 . . . . . . . . . . . . . 68 OS_WaitSingleEventTimed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 OS_GetTimerValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 OS_TICK_HandleEx() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 OS_PutMailCond1() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 OS_GetTimerStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 OS_MEMF_GetMaxUsed() . . . . . . . . . . 122 OS_Time . . . . . . . . . . . . . . . . . . 63 OS_PutMail1() . . . . . . . . . . . . . . . . . . . 78 OS_WaitEvent() . . . . . . . 34 OS_TICK_AddHook() . . . . . . . . 31 OS_GetpCurrentTimer() . . 66 OS_GetMailCond1() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 OS_realloc() . . . . . . . . 119 OS_TICK_RemoveHook(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 OS_SignalEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 OS_InitHW() . . . . . . . . . . . . . . . . . . . . . . . 64 IAR PowerPac™ RTOS OS_PutMailFrontCond() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 OS_TICK_Handle() . . . . . . . . . . 114 OS_TimingStart() . . . . . . . . . . . . . . . 75 OS_Q_Create() . . . . . . . . . . . . . . . . . . 79 OS_StartTimer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 OS_WaitCSema() . 91 OS_MEMF_Delete() . . . . . . . . . . . . . . . . . . . . . . . 65 OS_PutMailFrontCond1() . . . . . . . . . . . . . . . . . . 112 OS_GetTime_Cycles() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 OS_USE() . . . . . . . . . . . . . . . . . 89 OS_MEMF_AllocTimed() . . . . 123 OS_IncDI() . . . . . . . . . . . 79 OS_WaitSingleEvent() . . . . . . . . . . . . . . . . . . . . . . . . 84 OS_EVENT_Wait(). . . . . . . . . . . . . . . . 94 OS_MEMF_IsInPool() . . . . . . . . . . . . . . . . . . . . . . . . . 84 OS_ExtendTaskContext() . . . . . . . . . . . . 123 OS_ISR_Tick() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 OS_RestoreI() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 OS_LeaveRegion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 OS_GetResourceOwner . 54 OS_GetSemaValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 OS_Timing_GetCycles() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 OS_GetMail(). . . . . . . . . . . . . . . 117 OS_TimingEnd() . . . . 42. . . . . . . . . . . . . 29 OS_free() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 OS_GetEventsOccurred() . . . . . . . . . . . . . . . . 40 OS_Suspend() . . . . . . . . . . . . . . . . . . . . . . . . 20 OS_StopTimer() . . . . . . . . . . . . . . . . . . . . . . . . . 114 OS_Unuse() . . . . . . . . . . . . 105 OS_LeaveNestableInterrupt() . 68 OS_GetpCurrentTask() . . . . . 92 OS_MEMF_Create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 OS_FSYS . . . . . . . . . . . . . . . 123 OS_GetTime32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 OS_PutMail() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 OS_GetMail1() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 OS_WakeTask() . . . . . . . . . . . . . . 72 OS_Q_Purge() . . . . . . . . . . . 66 OS_GetMailTimed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 OS_IsTask() . 54 OS_GetStackBase() . . . . . . . . . . . . . . . . . . 89 OS_Request() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 OS_MEMF_GetBlockSize() . . . . . . . . . . . . . . . . . . . . . 57 OS_WaitEventTimed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 OS_GetTimerPeriod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 OS_WaitCSemaTimed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 OS_SetTimerPeriod() . . . . . . . . . . . . . . . 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 OS_LeaveInterruptNoSwitch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 OS_TICK_Config() . . . . . . 98 OS_GetStackSpace() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 OS_LeaveInterrupt() . . . . . . . . . . . . 95 OS_MEMF_GetNumBlocks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 OS_MEMF_FreeBlock() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .OS_EVENT_WaitTimed() . 99 OS_GetSuspendCnt() . . . . . . . . . . . . . . . . . . . . . . 33 OS_SignalCSema() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 OS_MEMF_GetNumFreeBlocks() . . . . . . . . 65 OS_PutMailFront() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 OS_Yield() . . 93 OS_MEMF_Request() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 OS_GetPriority() . . . . . . . . . . . . . . . . . . . . . 34 OS_Terminate() . . . . . . . . 112 OS_Idle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 OS_PutMailFront1() . . . . . . . . . . . 98 OS_GetStackSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 OS_TimeDex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 OS_SetTimeSlice() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 OS_GetMailCond() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39. . . . . . . . 45 OS_Start() . . . . . . . . . . . . . . . . . . . . . . . . 66 OS_GetMessageCnt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 OS_Q_Clear() . . . . . . . . 45 OS_SetCSemaValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 OS_MEMF_Alloc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 OS_Q_GetPtr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42. . . . . . . . . . . . . . . . . . . . . 71 OS_Q_GetMessageCnt() . . . 33 OS_SetTaskName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 OS_GetTaskID() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 OS_PutMailCond() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 OS_Q_GetPtrCond() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 OS_Q_GetPtrTimed() . . . . . . . . . . . . 41. 109 OS_malloc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 OS_GetCSemaValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . 15 Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Switching stacks . . 17 Superloop . . . . . . . . . . . . 17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Runtime errors . . . . . . . . . . . . . . 18 superloop . . 9 Reentrance . . . . . . . . . . . . . . . . . . . . . . . . . . 13 communication . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Time-related routines . . . . . . . . . . . . . . 16 global variables . . . . . . . . . . . . . . . . . . . . 123 version. . . . . . . . . . . . . . . . . . . . . . . .37–43 Software timers API overview . . . . . . . . . . . . . . . . 17 Stacks switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17. . . . . . . . 37 Stack . . . . . . . . . . . . . . . 23 Task routines . 71–75 R reading guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Q Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 status . . . 16 Task control block . . . . . . . . . . . . . . . . . . 111–116 trademarks . . . of this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49–54 Software timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Priority inversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .c configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55–59 Resource. . . . . . . 117 T Task communication . . . . . . . . . . . . . . . . . . . . . . . . . 2 Preemptive multitasking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Counting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 multitasking systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 System variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 registered trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15–16 RTOSInit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Round-robin . . conventions used . . . . 17 PPRTOS-3 151 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 publication date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Time variables . . . . . . . . . . . . . . . . . . . . . IAR Embedded Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 single-task systems . 17 TCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Release version. 2 V Vector table file . . . . . . . . . . 21 Resource semaphores . .23–35 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . of embOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 S Scheduler . . . . . . . . . . . . . . . . . . . . . . .Index P part number. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97–100 Stack pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . of this guide .

Sign up to vote on this title
UsefulNot useful