IAR PowerPac RTOS for ARM Cores, CPU and compiler specifics ...

IAR PowerPac RTOSfor ARM CoresCPU and compiler specificsusing IAR Embedded Workbench®PPARM-2

COPYRIGHT NOTICE© Copyright 2006–2007 IAR Systems. All rights reserved.No part of this document may be reproduced without the prior written consent of IARSystems. The software described in this document is furnished under a license and mayonly be used or copied in accordance with the terms of such a license.DISCLAIMERThe information in this document is subject to change without notice and does notrepresent a commitment on any part of IAR Systems. While the information containedherein is assumed to be accurate, IAR Systems assumes no responsibility for any errorsor omissions.In no event shall IAR Systems, its employees, its contractors, or the authors of thisdocument 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.TRADEMARKSIAR, IAR Systems, IAR Embedded Workbench, IAR MakeApp, C-SPY, visualSTATE,From Idea To Target, IAR KickStart Kit and IAR PowerPac are trademarks or registeredtrademarks owned by IAR Systems AB.Microsoft and Windows are registered trademarks of Microsoft Corporation.All other product names are trademarks or registered trademarks of their respectiveowners.EDITION NOTICESecond edition: June 2007Part number: PPARM-2Internal reference: 2.10, 3.40A, Rev. 1, ISUD.PPARM-2

ContentsPreface ................................................................................................................................................................ 5Using IAR PowerPac RTOS with IAR Embedded Workbench® ...........................................................7First steps ............................................................................................................................................. 7The example application Start_2Tasks.c ..........................................................................................8Stepping through the example application using C-SPY ................................................................ 8Build your own application.......................................................................................................................... 15Required files for an IAR PowerPac RTOS application................................................................. 15Change library mode......................................................................................................................... 15Select another CPU .......................................................................................................................... 15ARM core version specifics......................................................................................................................... 17CPU modes ........................................................................................................................................ 17Naming conventions for prebuilt libraries...................................................................................... 17Naming conventions for prebuild libraries compatible to IAR Embedded Workbench version 4.4x... 17Naming conventions for prebuild libraries compatible with IAR Embedded Workbench version 5.x. 19ARM7/9 specifics ........................................................................................................................................... 23Stacks.................................................................................................................................................. 23Task stack for ARM7 and ARM9.......................................................................................................... 23System stack for ARM7 and ARM9...................................................................................................... 23Interrupt stack for ARM7 and ARM9.................................................................................................... 23Stack specifics of the ARM7 and ARM9 family................................................................................... 23Interrupts ........................................................................................................................................... 23What happens when an interrupt occurs? .............................................................................................. 23Defining interrupt handlers in C ............................................................................................................ 24Interrupt handling without vectored interrupt controller ....................................................................... 24Interrupt handling with vectored interrupt controller ............................................................................ 25Interrupt-stack switching ....................................................................................................................... 28Fast Interrupt FIQ .................................................................................................................................. 28Cortex-M3 specifics...................................................................................................................................... 29Stacks.................................................................................................................................................. 29Task stack for Cortex M3 ...................................................................................................................... 29System stack for Cortex M3 .................................................................................................................. 29Interrupt stack for Cortex M3 ................................................................................................................ 29Interrupts ........................................................................................................................................... 29What happens when an interrupt occurs? .............................................................................................. 29Defining interrupt handlers in C ............................................................................................................ 29Interrupt vector table.............................................................................................................................. 30Interrupt-stack switching ....................................................................................................................... 30Fast interrupts with Cortex M3.............................................................................................................. 30Interrupt priorities.................................................................................................................................. 30Interrupt handling with vectored interrupt controller ............................................................................ 30High priority non maskable exceptions ................................................................................................. 32PPARM-2 3

Compiler specifics ......................................................................................................................................... 33Standard system libraries .................................................................................................................33Thread-safe system libraries.............................................................................................................33OS_INIT_SYS_LOCKS(), thread safe system locking.........................................................................33STOP / WAIT Mode...................................................................................................................................... 35Technical data.................................................................................................................................................. 37Memory requirements ......................................................................................................................37Files shipped with IAR PowerPac RTOS ................................................................................................... 39Index................................................................................................................................................................. 414IAR PowerPac RTOSfor ARM CoresPPARM-2

PrefaceWelcome to IAR PowerPac RTOS for ARM Cores. This guide describes how to use IAR PowerPac RTOS forthe ARM Cores using IAR Embedded Workbench®.Who should read this guideYou should read this guide if you plan to develop an embedded system using IAR PowerPac RTOS and need to getinformation about the CPU and compiler specifics using.How to use this guideThis guide describes all CPU and compiler specifics of IAR PowerPac RTOS using ARM-based controllers. Beforeactually using IAR PowerPac RTOS, you should read or at least glance through this guide to become familiar with thesoftware.The chapter Using IAR PowerPac RTOS with IAR Embedded Workbench® gives you a step-by-step introduction, howto use IAR PowerPac RTOS for ARM. If you have no experience using IAR PowerPac RTOS, you should follow thisintroduction, because it is an easy way to learn how to use IAR PowerPac RTOS in your application.Most of the other chapters in this guide are intended to provide you with important detailed information aboutfunctionality and fine-tuning of IAR PowerPac RTOS for the ARM-based controllers.Document conventionsTYPOGRAPHIC CONVENTIONS FOR SYNTAXThis guide uses the following typographic conventions:StyleKeywordParameterSampleReferenceGUIElementEmphasisDescriptionTable 1: Typographic conventionsText that you enter at the command-prompt or that appears on the display (that is systemfunctions, file- or pathnames).Parameters in API functions.Sample code in program examples.Reference to chapters, tables and figures or other documents.Buttons, dialog boxes, menu names, menu commands.Very important sectionsPPARM-2 5

6IAR PowerPac RTOSfor ARM CoresPPARM-2

Using IAR PowerPac RTOS withIAR Embedded Workbench®This chapter describes how to start with and use IAR PowerPac RTOS for ARM and the IAR compiler. You shouldfollow these steps to become familiar with IAR PowerPac RTOS for ARM together with IAR EmbeddedWorkbench.First stepsAfter installation of IAR PowerPac RTOS you can create your first multitasking application. An example workspaceand a project are supplied. We recommend to use these as a starting point for all your applications.To get your new application running, you should proceed as follows:●●●●●Create a work directory for your application, for example c:\workIn the IAR Embedded Workbench IDE, select Example applications in the Startup dialog box.If the Startup dialog box is deactivated, open the dialog over Help | Startup Screen....Select BoardSupport from the Example Applications listSelect the project which is consistent to your hardware, or start with the IAR Simulator project. Choose adestination folder for your project, for example c:\work. After generating the project of your choice, the screenshould look for example like this:● Build the project. It should be build without any error or warning messages.For latest information, open the file ARM\PowerPac\Doc\readme.htm.PPARM-2 7

The example application Start_2Tasks.cThe following is a printout of the example application Start_2Tasks.c. It is a good startingpoint for yourapplication. (Note that the file actually shipped with your port of IAR PowerPac RTOS may look slightly different fromthis one.)What happens is easy to see:After initialization of IAR PowerPac RTOS; two tasks are created and started.The two tasks are activated and execute until they run into the delay, then suspend for the specified time and continueexecution.#include "RTOS.H"OS_STACKPTR int Stack0[128], Stack1[128]; /* Task stacks */OS_TASK TCB0, TCB1; /* Task-control-blocks */void HPTask(void) {while (1) {OS_Delay (10);}}void LPTask(void) {while (1) {OS_Delay (50);}}/************************************************************ main***********************************************************/void main(void) {OS_IncDI(); /* Initially disable interrupts */OS_InitKern(); /* Initialize OS */OS_InitHW(); /* Initialize Hardware for OS *//* You need to create at least one task here ! */OS_CREATETASK(&TCB0, "HP Task", HPTask, 100, Stack0);OS_CREATETASK(&TCB1, "LP Task", LPTask, 50, Stack1);OS_Start(); /* Start multitasking */}Stepping through the example application using C-SPYWhen starting the debugger, you will see the main function (see example screenshot below). The main functionappears as long as the C-SPY option Run to main is selected, which it is by default. Now you can step through theprogram. OS_IncDI() initially disables interrupts.OS_InitKern() is part of the IAR PowerPac RTOS library and written in assembler; you can therefore only step intoit in disassembly mode. It initializes the relevant OS variables. Because of the previous call of OS_IncDI(), interruptsare not enabled during execution of OS_InitKern().OS_InitHW() is part of RTOSInit_*.c and therefore part of your application. Its primary purpose is to initialize thehardware required to generate the timer-tick-interrupt for IAR PowerPac RTOS. Step through it to see what is done.8IAR PowerPac RTOSfor ARM CoresPPARM-2

Using IAR PowerPac RTOS with IAR Embedded Workbench®OS_Start() should be the last line in main, because it starts multitasking and does not return.PPARM-29

Before you step into OS_Start(), you should set two breakpoints in the two tasks as shown below.As OS_Start() is part of the IAR PowerPac RTOS library, you can step through it in disassembly mode only.10IAR PowerPac RTOSfor ARM CoresPPARM-2

Using IAR PowerPac RTOS with IAR Embedded Workbench®Click GO, step over OS_Start(), or step into OS_Start() in disassembly mode until you reach the highest prioritytask.PPARM-211

If you continue stepping, you will arrive in the task that has lower priority:Continue to step through the program, there is no other task ready for execution. IAR PowerPac RTOS will thereforestart the idle-loop, which is an endless loop which is always executed if there is nothing else to do (no task is ready, nointerrupt routine or timer executing).12IAR PowerPac RTOSfor ARM CoresPPARM-2

Using IAR PowerPac RTOS with IAR Embedded Workbench®You will arrive there when you step into the OS_Delay() function in disassembly mode. OS_Idle() is part ofRTOSInit*.c. You may also set a breakpoint there before you step over the delay in LPTask.If you set a breakpoint in one or both of our tasks, you will see that they continue execution after the given delay.PPARM-213

As can be seen by the value of IAR PowerPac RTOS timer variable OS_Time, shown in the Watch window, HPTaskcontinues operation after expiration of the 10 ms delay.14IAR PowerPac RTOSfor ARM CoresPPARM-2

Build your own applicationTo build your own application, you should always start with one of the supplied sample workspaces and projects.Therefore, select a workspace as described in First steps on page 7 and modify the project to fit your needs. Usinga sample project as starting point has the advantage that all necessary files are included and all settings for theproject are already done.Required files for an IAR PowerPac RTOS applicationTo build an application using IAR PowerPac RTOS, the following files from your IAR PowerPac RTOS distributionare required and have to be included in your project:● RTOS.h from subfolder Inc\.This header file declares all IAR PowerPac RTOS API functions and data types and has to be included in anysource file using IAR PowerPac RTOS functions.● RTOSInit_*.c from one Setup subfolder.It contains hardware-dependent initialization code for IAR PowerPac RTOS timer.● One IAR PowerPac RTOS library from the subfolder Lib\.● OS_Error.c from subfolder Setup\.The error handler is used if any library other than Release build library is used in your project.● RTOSVect.asm from the subfolder Setup\.It contains the low level interrupt handler entry for ARM7/9 CPUs running with IAR PowerPac RTOS.● UserIRQ.c from subfolder Src\.It contains the application-specific interrupt handler function which is called from IAR PowerPac RTOS IRQhandler. This file may not be necessary for target CPUs with built in vectored interrupt controller.● Additional low level init code may be required according to CPU.When you decide to write your own startup code or use a __low_level_init function, ensure that non-initializedvariables are initialized with zero, according to C standard. This is required for some IAR PowerPac RTOS internalvariables.Also ensure, that main() is called with CPU running in supervisor or system mode.Your main() function has to initialize IAR PowerPac RTOS by call of OS_InitKern() and OS_InitHW() prior anyother IAR PowerPac RTOS functions are called.You should then modify or replace the Start_2Task.c source file in the subfolder Application\.Change library modeFor your application you might want to choose another library. For debugging and program development you shoulduse an IAR PowerPac RTOS-debug library. For your final application you may wish to use an IAR PowerPac RTOSreleaselibrary or a stack check library.Therefore you have to select or replace the IAR PowerPac RTOS library in your project or target:●●●If your selected library is already available in your project, just select the appropriate configuration.To add a library, you may add a new Lib group to your project and add this library to the new group. Exclude allother library groups from build, delete unused Lib groups or remove them from the configuration.Check and set the appropriate OS_LIBMODE_* define as preprocessor option.Select another CPUIAR PowerPac RTOS for ARM contains CPU-specific code for various ARM CPUs. The folder BoardSupportcontains workspaces for different target CPUs and specific eval boards.PPARM-2 15

Check whether your CPU is supported by IAR PowerPac RTOS. CPU-specific functions are located in the Setupsubfolder in each board support project folder. To select a CPU which is already supported, just select the appropriateproject from the Example application list in the Embedded Workbench Startup dialog box.If your ARM CPU is currently not supported, examine all RTOSInit files in the CPU-specific subfolders and selectone which almost fits your CPU. You may have to modify OS_InitHW(), OS_COM_Init(), and the interrupt serviceroutines for IAR PowerPac RTOS timer tick.16IAR PowerPac RTOSfor ARM CoresPPARM-2

ARM core version specificsCPU modesIAR PowerPac RTOS supports nearly all memory and code model combinations that IAR C/C++ Compiler supports.Naming conventions for prebuilt librariesThe IAR PowerPac RTOS library naming conventions are derived from the library naming conventions which is usedin the compatible version of IAR Embedded Workbench.NAMING CONVENTIONS FOR PREBUILD LIBRARIES COMPATIBLETO IAR EMBEDDED WORKBENCH VERSION 4.4XIAR PowerPac RTOS is shipped withdifferent prebuilt libraries with different combinations of the following features:●●●●●●●Architecture - archCPU mode - modeInterworking - interworkVFP - float (all prebuilt libraries are built with software floating-point support)Byte order - endianessStack alignment - stackalign (all prebuilt libraries are built using stack alignment 8, which is also compatiblewith stack alignment 4)Library mode - libmode.The libraries are named as follows:p.r79Parameter Description Valuestype Type of library. os: IAR PowerPac RTOS libraryisa Specifies the architecture. 4t: v4T5t: v5T, v67m: v7-Mp - -mode Specifies the CPU mode. a: ARMt: Thumb / Thumb2interwork Specifies if interwork option is enabled. i: Enable interworkingn: Do not use interworkingFPU Specifies type of floating-point support. v: VFPv1 floating-point supportn: Software floating-point supportendianess Specifies target byte order. b: Bigl: Littlestackalign Stack alignment used in the library. 8: 8 byte4: 4 bytelibmode Specifies the library mode r: Releases: Stack checkd: DebugTable 2: Library naming conventionsPPARM-2 17

Exampleos4tptinl8r.r79 is the IAR PowerPac RTOS library for a project supporting an ARM architecture v4T core, usingThumb mode, compiled with the interwork option and software floating-point support, for little-endian byte order,using 8-byte stack alignment, and release build configuration.Available prebuilt librarieslibrary name isa mode interworking float endianess libmodeos4tpannb8r.r79 v4T ARM No No Big Releaseos4tpannb8s.r79 v4T ARM No No Big Stack checkos4tpannb8d.r79 v4T ARM No No Big Debugos4tpannl8r.r79 v4T ARM No No Little Releaseos4tpannl8s.r79 v4T ARM No No Little Stack checkos4tpannl8d.r79 v4T ARM No No Little Debugos4tpainb8r.r79 v4T ARM Yes No Big Releaseos4tpainb8s.r79 v4T ARM Yes No Big Stack checkos4tpainb8d.r79 v4T ARM Yes No Big Debugos4tpainl8r.r79 v4T ARM Yes No Little Releaseos4tpainl8s.r79 v4T ARM Yes No Little Stack checkos4tpainl8d.r79 v4T ARM Yes No Little Debugos4tptnnb8r.r79 v4T Thumb No No Big Releaseos4tptnnb8s.r79 v4T Thumb No No Big Stack checkos4tptnnb8d.r79 v4T Thumb No No Big Debugos4tptnnl8r.r79 v4T Thumb No No Little Releaseos4tptnnl8s.r79 v4T Thumb No No Little Stack checkos4tptnnl8d.r79 v4T Thumb No No Little Debugos4tptinb8r.r79 v4T Thumb Yes No Big Releaseos4tptinb8s.r79 v4T Thumb Yes No Big Stack checkos4tptinb8d.r79 v4T Thumb Yes No Big Debugos4tptinl8r.r79 v4T Thumb Yes No Little Releaseos4tptinl8s.r79 v4T Thumb Yes No Little Stack checkos4tptinl8d.r79 v4T Thumb Yes No Little Debugos5tpannb8r.r79 v5T, v6 ARM No No Big Releaseos5tpannb8s.r79 v5T, v6 ARM No No Big Stack checkos5tpannb8d.r79 v5T, v6 ARM No No Big Debugos5tpannl8r.r79 v5T, v6 ARM No No Little Releaseos5tpannl8s.r79 v5T, v6 ARM No No Little Stack checkos5tpannl8d.r79 v5T, v6 ARM No No Little Debugos5tpainb8r.r79 v5T, v6 ARM Yes No Big Releaseos5tpainb8s.r79 v5T, v6 ARM Yes No Big Stack checkos5tpainb8d.r79 v5T, v6 ARM Yes No Big Debugos5tpainl8r.r79 v5T, v6 ARM Yes No Little Releaseos5tpainl8s.r79 v5T, v6 ARM Yes No Little Stack checkos5tpainl8d.r79 v5T, v6 ARM Yes No Little Debugos5tptnnb8r.r79 v5T, v6 Thumb No No Big Releaseos5tptnnb8s.r79 v5T, v6 Thumb No No Big Stack checkos5tptnnb8d.r79 v5T, v6 Thumb No No Big Debugos5tptnnl8r.r79 v5T, v6 Thumb No No Little Releaseos5tptnnl8s.r79 v5T, v6 Thumb No No Little Stack checkTable 3: Prebuilt libraries18IAR PowerPac RTOSfor ARM CoresPPARM-2

ARM core version specificslibrary name isa mode interworking float endianess libmodeos5tptnnl8d.r79 v5T, v6 Thumb No No Little Debugos5tptinb8r.r79 v5T, v6 Thumb Yes No Big Releaseos5tptinb8s.r79 v5T, v6 Thumb Yes No Big Stack checkos5tptinb8d.r79 v5T, v6 Thumb Yes No Big Debugos5tptinl8r.r79 v5T, v6 Thumb Yes No Little Releaseos5tptinl8s.r79 v5T, v6 Thumb Yes No Little Stack checkos5tptinl8d.r79 v5T, v6 Thumb Yes No Little Debugos7mptnnb8r.r79 v7-M Thumb2 No No Big Releaseos7mptnnb8s.r79 v7-M Thumb2 No No Big Stack checkos7mptnnb8d.r79 v7-M Thumb2 No No Big Debugos7mptnnl8r.r79 v7-M Thumb2 No No Little Releaseos7mptnnl8s.r79 v7-M Thumb2 No No Little Stack checkos7mptnnl8d.r79 v7-M Thumb2 No No Little DebugTable 3: Prebuilt libraries (Continued)NAMING CONVENTIONS FOR PREBUILD LIBRARIES COMPATIBLEWITH IAR EMBEDDED WORKBENCH VERSION 5.XIAR PowerPac RTOS is shipped with different prebuilt libraries with different combinations of the following features:●●●●●●Instruction set architecture - isaCPU mode - modeFPU (all prebuilt libraries are built with software floating-point support) - floatInterworking - interworkByte order - endianessLibrary mode - libmode.The libraries are named as follows:_.r79Parameter Meaning Valuestype Type of library. os: IAR PowerPac RTOS libraryisa Specifies the instruction set 4t: v4Tarchitecture.5t: v5T, v67m: v7Mmode Specifies the CPU mode. a: ARMt: Thumb / Thumb2endianess Specifies target endianess. b: Bigl: Littlefloat Specifies type of floating-point _: Software floating-point supportExamplesupport.s: VFP with software parametersv: VFP with VFP parametersinterwork Specifies if interwork option is enabled. i: Enable interworking_: Do not use interworkinglibmode Specifies the library mode r: Releases: Stack checkd: DebugTable 4: Library naming conventionsos4t_tl_ir.a is the IAR PowerPac RTOS library for a project supporting an ARM architecture v4T core, usingThumb mode, little-endian byte order, software floating-point support, compiled with the interwork option and releasebuild configuration.PPARM-219

Available prebuilt librarieslibrary name isa mode endianess float interworking libmodeos4t_ab__r.a v4T ARM Big No No Releaseos4t_ab__s.a v4T ARM Big No No Stack checkos4t_ab__d.a v4T ARM Big No No Debugos4t_al__r.a v4T ARM Little No No Releaseos4t_al__s.a v4T ARM Little No No Stack checkos4t_al__d.a v4T ARM Little No No Debugos4t_ab_ir.a v4T ARM Big No Yes Releaseos4t_ab_is.a v4T ARM Big No Yes Stack checkos4t_ab_id.a v4T ARM Big No Yes Debugos4t_al_ir.a v4T ARM Little No Yes Releaseos4t_al_is.a v4T ARM Little No Yes Stack checkos4t_al_id.a v4T ARM Little No Yes Debugos4t_tb__r.a v4T Thumb Big No No Releaseos4t_tb__s.a v4T Thumb Big No No Stack checkos4t_tb__d.a v4T Thumb Big No No Debugos4t_tl__r.a v4T Thumb Little No No Releaseos4t_tl__s.a v4T Thumb Little No No Stack checkos4t_tl__d.a v4T Thumb Little No No Debugos4t_tb_ir.a v4T Thumb Big No Yes Releaseos4t_tb_is.a v4T Thumb Big No Yes Stack checkos4t_tb_id.a v4T Thumb Big No Yes Debugos4t_tl_ir.a v4T Thumb Little No Yes Releaseos4t_tl_is.a v4T Thumb Little No Yes Stack checkos4t_tl_id.a v4T Thumb Little No Yes Debugos5t_ab__r.a v5T, v6 ARM Big No No Releaseos5t_ab__s.a v5T, v6 ARM Big No No Stack checkos5t_ab__d.a v5T, v6 ARM Big No No Debugos5t_al__r.a v5T, v6 ARM Little No No Releaseos5t_al__s.a v5T, v6 ARM Little No No Stack checkos5t_al__d.a v5T, v6 ARM Little No No Debugos5t_ab_ir.a v5T, v6 ARM Big No Yes Releaseos5t_ab_is.a v5T, v6 ARM Big No Yes Stack checkos5t_ab_id.a v5T, v6 ARM Big No Yes Debugos5t_al_ir.a v5T, v6 ARM Little No Yes Releaseos5t_al_is.a v5T, v6 ARM Little No Yes Stack checkos5t_al_id.a v5T, v6 ARM Little No Yes Debugos5t_tb__r.a v5T, v6 Thumb Big No No Releaseos5t_tb__s.a v5T, v6 Thumb Big No No Stack checkos5t_tb__d.a v5T, v6 Thumb Big No No Debugos5t_tl__r.a v5T, v6 Thumb Little No No Releaseos5t_tl__s.a v5T, v6 Thumb Little No No Stack checkos5t_tl__d.a v5T, v6 Thumb Little No No Debugos5t_tb_ir.a v5T, v6 Thumb Big No Yes Releaseos5t_tb_is.a v5T, v6 Thumb Big No Yes Stack checkos5t_tb_id.a v5T, v6 Thumb Big No Yes Debugos5t_tl_ir.a v5T, v6 Thumb Little No Yes ReleaseTable 5: Prebuilt libraries20IAR PowerPac RTOSfor ARM CoresPPARM-2

ARM core version specificslibrary name isa mode endianess float interworking libmodeos5t_tl_is.a v5T, v6 Thumb Little No Yes Stack checkos5t_tl_id.a v5T, v6 Thumb Little No Yes Debugos7m_tb__r.a v7M Thumb2 Big No No Releaseos7m_tb__s.a v7M Thumb2 Big No No Stack checkos7m_tb__d.a v7M Thumb2 Big No No Debugos7m_tl__r.a v7M Thumb2 Little No No Releaseos7m_tl__s.a v7M Thumb2 Little No No Stack checkos7m_tl__d.a v7M Thumb2 Little No No DebugTable 5: Prebuilt libraries (Continued)PPARM-221

22IAR PowerPac RTOSfor ARM CoresPPARM-2

ARM7/9 specificsStacksTASK STACK FOR ARM7 AND ARM9All IAR PowerPac RTOS tasks execute in system mode. The stack-size required is the sum of the stack-size of allroutines plus basic stack size. The basic stack size is the size of memory required to store the registers of the CPU plusthe stack size required by IAR PowerPac RTOS-routines. For the ARM7/ARM9, the minimum task stack size is about68 bytes.SYSTEM STACK FOR ARM7 AND ARM9The IAR PowerPac RTOS system executes in supervisor mode. The minimum system stack size required by IARPowerPac RTOS is about 136 bytes (stack check build). However, because the system stack is also used by theapplication before the start of multitasking (the call to OS_Start()), and because software-timers and C level interrupthandlers also use the system-stack, the actual stack requirements depend on the application.The size of the system stack can be changed by modifying CSTACK in your *.xcl linker command file.INTERRUPT STACK FOR ARM7 AND ARM9If a normal hardware exception occurs, the ARM core switches to IRQ mode, which has a separate stack pointer. Toenable support for nested interrupts, execution of the ISR itself in a different CPU mode than IRQ mode is necessary.IAR PowerPac RTOS switches to supervisor mode after saving scratch registers, LR_irq and SPSR_irq onto the IRQstack.As a result, only registers mentioned above are saved onto the IRQ stack. For the interrupt routine itself, the supervisorstack is used. The size of the interrupt stack can be changed by modifying IRQ_STACK in your *.xcl linker commandfile. We recommend at least 128 bytes.STACK SPECIFICS OF THE ARM7 AND ARM9 FAMILYExceptions require space on the supervisor and interrupt stack. The interrupt stack is used to store contents of scratchregisters, the ISR itself uses supervisor stack.InterruptsWHAT HAPPENS WHEN AN INTERRUPT OCCURS?●●●●●●●●●●●●The CPU-core receives an interrupt requestAs soon as the interrupts are enabled, the interrupt is executedThe CPU switches to the Interrupt stackThe CPU saves PC and flags in registers LR_irq and SPSR_irqThe CPU jumps to the vector address 0x18IAR PowerPac RTOS OS_IRQ_SERVICE(): save scratch registersIAR PowerPac RTOS OS_IRQ_SERVICE(): save LR_irq and SPSR_irqIAR PowerPac RTOS OS_IRQ_SERVICE(): switch to supervisor modeIAR PowerPac RTOS OS_IRQ_SERVICE(): execute OS_irq_handler() (defined in RTOSINIT_*.C)IAR PowerPac RTOS OS_irq_handler(): check for interrupt source and execute timer interrupt, serialcommunication or user ISR.IAR PowerPac RTOS OS_IRQ_SERVICE(): switch to IRQ modeIAR PowerPac RTOS OS_IRQ_SERVICE(): restore LR_irq and SPSR_irqPPARM-2 23

● IAR PowerPac RTOS OS_IRQ_SERVICE(): pop scratch registers● Return from interrupt.When using an ARM derivate with vectored interrupt controller, ensure that OS_IRQ_SERVICE() is called from everyinterrupt. The interrupt vector itself may then be examined by the C-level interrupt handler in RTOSInit*.c.DEFINING INTERRUPT HANDLERS IN CInterrupt handlers called from the IAR PowerPac RTOS interrupt handler in RTOSInit*.c are just normal C-functionswhich do not take parameters and do not return any value.The default C interrupt handler OS_irq_handler() in RTOSInit*.c first calls OS_Enterinterrupt() orOS_EnterNestableInterrupt() to inform IAR PowerPac RTOS that interrupt code is running. Then this handlerexamines the source of interrupt and calls the related interrupt handler function.Finally, the default interrupt handler OS_irq_handler() in RTOSInit*.c calls OS_LeaveInterrupt() orOS_LeaveNestableInterrupt() and returns to the primary interrupt handler OS_IRQ_SERVICE().Depending on the interrupting source, it may be required to reset the interrupt pending condition of the relatedperipherals.ExampleSimple interrupt routine:void Timer_irq_func(void) {if (__INTPND & 0x0800) { // Interrupt pending ?__INTPND = 0x0800; // reset pending conditionOSTEST_X_ISR0();// handle interrupt}}INTERRUPT HANDLING WITHOUT VECTORED INTERRUPTCONTROLLERStandard ARM CPUs, without implementation of a vectored interrupt controller, always branch to address 0x18 whenan interrupt occurs. The application is responsible to examine the interrupting source.The reaction to an interrupt is as follows:● IAR PowerPac RTOS OS_IRQ_SERVICE() is called● OS_IRQ_SERVICE() saves registers and switches to supervisor mode● OS_IRQ_SERVICE() calls OS_irq_handler()● OS_irq_handler() informs IAR PowerPac RTOS that interrupt code is running by a call● of OS_EnterInterrupt() and then calls OS_USER_irq_func() which has to handle all interrupt sources of theapplication● OS_irq_handler() checks whether IAR PowerPac RTOS timer interrupt has to be handled● OS_irq_handler() informs IAR PowerPac RTOS that interrupt handling ended by a call ofOS_LeaveInterrupt() and returns to OS_IRQ_SERVICE()● OS_IRQ_SERVICE() restores registers and performs a return from interrupt● OS_USER_irq_func() (usually defined in module UserIRQ.C) has to examine and handle all applicationspecific interrupts.ExampleSimple OS_USER_irq_func() routine:void OS_USER_irq_func(void) {if (__INTPND & 0x0800) { // Interrupt pending ?__INTPND = 0x0800;// Reset pending conditionOSTEST_X_ISR0();// Handle interrupt}if (__INTPND & 0x0400) { // Interrupt pending ?__INTPND = 0x0400;// Reset pending conditionOSTEST_X_ISR1();// Handle interrupt}}During interrupt processing, you should not re-enable interrupts, as this would lead in recursion.24IAR PowerPac RTOSfor ARM CoresPPARM-2

ARM7/9 specificsINTERRUPT HANDLING WITH VECTORED INTERRUPTCONTROLLERFor ARM derivates with built in vectored interrupt controller, IAR PowerPac RTOS uses a different interrupt handlingprocedure and delivers additional functions to install and setup interrupt handler functions.When using an ARM derivate with vectored interrupt controller, ensure that OS_IRQ_SERVICE() is called from everyinterrupt. This is default when startup code and hardware initialization delivered with IAR PowerPac RTOS is used.The interrupt vector itself will then be examined by the C-level interrupt handler OS_irq_handler() inRTOSInit*.c.You should not program the interrupt controller for IRQ handling directly. You should use the functions delivered withIAR PowerPac RTOS.The reaction to an interrupt with vectored interrupt controller is as follows:● RTOS OS_IRQ_SERVICE() is called by CPU or interrupt controller● OS_IRQ_SERVICE() saves registers and switches to supervisor mode● OS_IRQ_SERVICE() calls OS_irq_handler() (in RTOSInit*.c)● OS_irq_handler() examines the interrupting source by reading the interrupt vector from the interrupt controller● OS_irq_handler() informs the RTOS that interrupt code is running by a call ofOS_EnterNestableInterrupt() which re-enables interrupts● OS_irq_handler() calls the interrupt handler function which is addressed by the interrupt vector● OS_irq_handler() resets the interrupt controller to re-enable acceptance of new interrupts● OS_irq_handler() calls OS_LeaveNestableInterrupt() which disables interrupts and informs IARPowerPac RTOS that interrupt handling has finished● OS_irq_handler() returns to OS_IRQ_SERVICE● OS_IRQ_SERVICE() restores registers and performs a return from interrupt.Note that different ARM CPUs may have different versions of vectored interrupt controller hardware, and usage of IARPowerPac RTOS supplied functions varies depending on the type of interrupt controller. Refer to the samples deliveredwith IAR PowerPac RTOS which are used in the CPU specific RTOSInit module.To handle interrupts with vectored interrupt controller, IAR PowerPac RTOS offers the following functions.FunctionOS_ARM_InstallISRHandler()OS_ARM_EnableISR()OS_ARM_DisableISR()OS_ARM_ISRSetPrio()OS_ARM_AssignISRSource()OS_ARM_EnableISRSource()OS_ARM_DisableISRSource()OS_ARM_InstallISRHandler(): Install an interrupt handlerDescriptionOS_ARM_InstallISRHandler() is used to install a specific interrupt vector when ARM CPUs with vectoredinterrupt controller are used.PrototypeOS_ISR_HANDLER* OS_ARM_InstallISRHandler (intISRIndex,OS_ISR_HANDLER* pISRHandler);ParameterDescriptionReturn valueDescriptionInstalls an interrupt handlerEnables a specific interruptDisables a specific interruptSets the priority of a specific interruptAssigns a hardware interrupt channel to an interrupt vectorEnables an interrupt channel of a VIC type interrupt controllerDisables an interrupt channel of a VIC type interrupt controllerTable 6: Interrupt handler functions for ARM derivates with built in vectored interrupt controllerISRIndexpISRHandlerIndex of the interrupt source, normally the interrupt vector number.Address of the interrupt handler function.Table 7: OS_ARM_InstallSRHandler() parameter listOS_ISR_HANDLER*: The address of the previously installed interrupt function, which was installed at the addressedvector number before.PPARM-225

Additional InformationThis function just installs the interrupt vector but does not modify the priority and does not automatically enable theinterrupt.OS_ARM_EnableISR(): Enable a specific interruptDescriptionOS_ARM_EnableISR() is used to enable interrupt acceptance of a specific interrupt source in a vectored interruptcontroller.Prototypevoid OS_ARM_EnableISR(int ISRIndex);ParameterDescriptionISRIndexTable 8: OS_ARM_EnableISR() parameter listAdditional InformationThis function just enables the interrupt inside the interrupt controller. It does not enable the interrupt of any peripherals.This has to be done elsewhere.Note:For ARM CPUs with VIC type interrupt controller, this function just enables the interrupt vector itself. To enablethe hardware assigned to that vector, you have to call OS_ARM_EnableISRSource() also.OS_ARM_DisableISR(): Disable a specific interruptDescriptionOS_ARM_DisableISR() is used to disable interrupt acceptance of a specific interrupt source in a vectored interruptcontroller which is not of the VIC type.Prototypevoid OS_ARM_DisableISR(int ISRIndex);ParameterDescriptionISRIndexpISRHandlerTable 9: OS_ARM_DisableISR() parameter listAdditional InformationThis function just disables the interrupt controller. It does not disable the interrupt of any peripherals. This has to bedone elsewhere.Note:When using an ARM CPU with built in interrupt controller of VIC type, use OS_ARM_DisableISRSource()to disable a specific interrupt.OS_ARM_ISRSetPrio(): Set priority of a specific interruptDescriptionOS_ARM_ISRSetPrio() is used to set or modify the priority of a specific interrupt source by programming theinterrupt controller.Prototypeint OS_ARM_ISRSetPrio (int ISRIndex,int Prio);ParameterDescriptionISRIndexPrioTable 10: OS_ARM_ISRSetPrio() parameter listReturn valueIndex of the interrupt source which should be enabled.Index of the interrupt source which should be disabled.Address of the interrupt handler function.Index of the interrupt source which should be modified.The priority which should be set for the specific interrupt.Previous priority which was assigned before the call of OS_ARM_ISRSetPrio().26IAR PowerPac RTOSfor ARM CoresPPARM-2

ARM7/9 specificsAdditional InformationThis function sets the priority of an interrupt channel by programming the interrupt controller. Refer to CPU-specificmanuals about allowed priority levels.Note:This function cannot be used to modify the interrupt priority for interrupt controllers of the VIC type. The interruptpriority with VIC-type controllers depends on the interrupt vector number and cannot be changed.OS_ARM_AssignISRSource(): Assign a hardware interrupt channel to aninterrupt vectorDescriptionOS_ARM_AssignISRSource() is used to assign a hardware interrupt channel to an interrupt vector in an interruptcontroller of VIC type.Prototypevoid OS_ARM_AssignISRSource(int ISRIndex,int Source);ParameterDescriptionISRIndexSourceTable 11: OS_ARM_AssignISRSource() parameter listAdditional InformationThis function assigns a hardware interrupt line to an interrupt vector of VIC type only. It cannot be used for other typesof vectored interrupt controllers. The hardware interrupt channel number of specific peripherals depends on specificCPU derivates and has to be taken from the hardware manual of the CPU.OS_ARM_EnableISRSource(): Enable an interrupt channel of a VIC-typeinterrupt controllerDescriptionOS_ARM_EnableISRSource() is used to enable an interrupt input channel of an interrupt controller of VIC type.PrototypeOS_ARM_DisableISRSource(int SourceIndex);;ParameterDescriptionSourceIndexTable 12: OS_ARM_EnableISRSource() parameter listAdditional InformationThis function enables a hardware interrupt input of a VIC-type interrupt controller. It cannot be used for other types ofvectored interrupt controllers. The hardware interrupt channel number of specific peripherals depends on specific CPUderivates and has to be taken from the hardware manual of the CPU.OS_ARM_DisableISRSource(): Disable an interrupt channel of a VIC-typeinterrupt controllerDescriptionOS_ARM_DisableISRSource() is used to disable an interrupt input channel of an interrupt controller of VIC type.PrototypeIndex of the interrupt source which should be modified.The source channel number which should be assigned to the specified interrupt vector.Index of the interrupt channel which should be enabled.OS_ARM_DisableISRSource(int SourceIndex);;ParameterDescriptionSourceIndexTable 13: OS_ARM_DisableISRSource() parameter listIndex of the interrupt channel which should be disabled.PPARM-227

Additional InformationThis function disables a hardware interrupt input of a VIC-type interrupt controller. It cannot be used for other typesof vectored interrupt controllers. The hardware interrupt channel number of specific peripherals depends on specificCPU derivates and has to be taken from the hardware manual of the CPU.Example/* Install UART interrupt handler */OS_ARM_InstallISRHandler(UART_ID, &COM_ISR);OS_ARM_ISRSetPrio(UART_ID, UART_PRIO);OS_ARM_EnableISR(UART_ID);// UART interrupt vector// UART interrupt priotity// Enable UART interrupt/* Install UART interrupt handler with VIC type interrupt controller*/OS_ARM_InstallISRHandler(UART_INT_INDEX, &COM_ISR); // UART interrupt vectorOS_ARM_AssignISRSource(UART_INT_INDEX, UART_INT_SOURCE);OS_ARM_EnableISR(UART_INT_INDEX);// Enable UART interrupt vectorOS_ARM_EnableISRSource(UART_INT_SOURCE);// Enable UART interrupt sourceINTERRUPT-STACK SWITCHINGBecause ARM core based controllers have a separate stack pointer for interrupts, there is no need for explicit stackswitchingin an interrupt routine. The routines OS_EnterIntStack() and OS_LeaveIntStack() are supplied forsource compatibility to other processors only and have no functionality.The ARM interrupt stack is used for the primary interrupt handler in RTOSVect.asm only.FAST INTERRUPT FIQThe FIQ interrupt cannot be used with IAR PowerPac RTOS functions, it is reserved for high speed user functions.Note the following:● FIQ is never disabled by IAR PowerPac RTOS.● Never call any IAR PowerPac RTOS function from an FIQ handler.● Do not assign any IAR PowerPac RTOS interrupt handler to FIQ.Note:When you decide to use FIQ, ensure the FIQ stack is initialized during startup and that an interrupt vector for FIQhandling is included in your application.28IAR PowerPac RTOSfor ARM CoresPPARM-2

Cortex-M3 specificsStacksTASK STACK FOR CORTEX M3All IAR PowerPac RTOS tasks execute in thread mode using the process stack pointer. The stack-size required is thesum of the stack-size of all routines plus basic stack size plus size used by exceptions. The basic stack size is the sizeof memory required to store the registers of the CPU plus the stack size required by IAR PowerPac RTOS-routines. Forthe Cortex M3 CPU, this minimum task stack size is about 72 bytes. But because any function call uses some amountof stack and every exception also pushes at least 32 bytes onto the current stack, the task stack size has to be largeenough to handle all nested exceptions too. We recommend at least 256 bytes stack as a start.SYSTEM STACK FOR CORTEX M3The IAR PowerPac RTOS system executes in thread mode, the scheduler executes in handler mode. The minimumsystem stack size required by IAR PowerPac RTOS is about 136 bytes (stack check & profiling build) However, sincethe system stack is also used by the application before the start of multitasking (the call to OS_Start()), and becausesoftware-timers and C-level interrupt handlers also use the system-stack, the actual stack requirements depend on theapplication.The size of the system stack can be changed by modifying CSTACK in your *.XCL file.INTERRUPT STACK FOR CORTEX M3If a normal hardware exception occurs, the Cortex M3 core switches to handler mode mode, which uses the main stackpointer. With IAR PowerPac RTOS, the main stack pointer is initialized to use the CSTACK which is defined in the linkercommand file. A separate IRQ_STACK is not used, interrupts run on the system stack.InterruptsThe Cortex M3 core comes with an built in vectored interrupt controller which supports up to 496 separate interruptsources. The real number of interrupt sources depends on the specific target CPU.WHAT HAPPENS WHEN AN INTERRUPT OCCURS?●●●●●●●●●●The CPU-core receives an interrupt request form the interrupt controller.As soon as the interrupts are enabled, the interrupt is executedThe CPU pushes temporary registers and the return address onto the current stack.The CPU switches to handler mode and main stack.The CPU saves an exception return code and current flags onto the main stack.The CPU jumps to the vector address delivered by the NVIC.The interrupt handler is processed.The interrupt handler ends with a “return from interrupt” by reading the exception return code.The CPU switches back to the mode and stack which was active before the exception was called.The CPU restores the temporary registers and return address from the stack and continues the interrupted function.DEFINING INTERRUPT HANDLERS IN CInterrupt handlers for Cortex M3 are written as normal C-functions which do not take parameters and do not return anyvalue.PPARM-2 29

Example“Simple“ interrupt-routine:static void _Systick(void) {OS_EnterNestableInterrupt(); // Inform IAR PowerPac RTOS that interrupt code is runningOS_HandleTick();OS_LeaveNestableInterrupt(); // Inform IAR PowerPac RTOS that interrupt handler isleft}INTERRUPT VECTOR TABLEAfter Reset, the ARM Cortex M3 CPU uses an initial interrupt vector table which is located in ROM at address 0x00.It contains the address for the main stack and addresses for all exceptions.The interrupt vector table is located in the C source file Startup_*.c in the CPU specific subfolder. All interrupthandler function addresses have to be inserted in the vector table, as long as a RAM vector table is not used.The vector table may be copied to RAM to enable variable interrupt handler installation. The compile time switchOS_USE_VARINTTABLE is used to enable usage of a vector table in RAM. To save RAM, the switch is set to zero perdefault in RTOSInit_*.c. It may be overwritten by project settings to enable the vector table in RAM. The first callof OS_InstallISRHandler() will then automatically copy the vector table into RAM.INTERRUPT-STACK SWITCHINGSince Cortex M3 core based controllers have a separate stack pointer for interrupts, there is no need for explicit stackswitchingin an interrupt routine. The routines OS_EnterIntStack() and OS_LeaveIntStack() are supplied forsource compatibility to other processors only and have no functionality.FAST INTERRUPTS WITH CORTEX M3Instead of disabling interrupts when IAR PowerPac RTOS does atomic operations, the interrupt level of the CPU is setto 128. Therefore all interrupt priorities higher than 128 can still be processed. Please note, that lower priority numberdefine a higher priority. All interrupts with priority level from 0 to 128 are never disabled.These interrupts are named Fast interrupts. You must not execute any IAR PowerPac RTOS function from within a fastinterrupt function.INTERRUPT PRIORITIESWith introduction of Fast interrupts, interrupt priorities useable for interrupts using IAR PowerPac RTOS APIfunctions are limited.● Any interrupt handler using IAR PowerPac RTOS API functions has to run with interrupt priorities from 128 to255.These IAR PowerPac RTOS interrupt handlers have to start with OS_EnterInterrupt() orOS_EnterNestableInterrupt() and must end with OS_LeaveInterrupt() orOS_LeaveNestableInterrupt().● Any Fast interrupt (running at priorities from 0 to 127) must not call any IAR PowerPac RTOS API function. EvenOS_EnterInterrupt() and OS_LeaveInterrupt() must not be called.● Interrupt handler running at low priorities (from 128 to 255) not calling any IAR PowerPac RTOS API function areallowed, but must not re-enable interrupts!The priority limit between IAR PowerPac RTOS interrupts and Fast interrupts is fixed to 128 and can only be changedby recompiling IAR PowerPac RTOS libraries!INTERRUPT HANDLING WITH VECTORED INTERRUPTCONTROLLERFor Cortex M3, which has a built in vectored interrupt controller, IAR PowerPac RTOS delivers additional functionsto install and setup interrupt handler functions.30IAR PowerPac RTOSfor ARM CoresPPARM-2

Cortex-M3 specificsTo handle interrupts with the vectored interrupt controller, IAR PowerPac RTOS offers the following functions:FunctionOS_ARM_InstallISRHandler()OS_ARM_EnableISR()OS_ARM_DisableISR()OS_ARM_ISRSetPrio()Table 14: Interrupt handler functions for Cortex M3 coresOS_ARM_InstallISRHandler(): Install an interrupt handlerDescriptionOS_ARM_InstallISRHandler() is used to install a specific interrupt vector when ARM CPUs with vectoredinterrupt controller are used.PrototypeOS_ISR_HANDLER* OS_ARM_InstallISRHandler (intISRIndex,OS_ISR_HANDLER* pISRHandler);ParameterDescriptionISRIndexpISRHandlerReturn valueOS_ISR_HANDLER*: The address of the previously installed interrupt function, which was installed at the addressedvector number before.Additional InformationThis function just installs the interrupt vector but does not modify the priority and does not automatically enable theinterrupt. When the interrupt vector table should be located in RAM, the first call of this function copies the vector tableinto RAM and programs the interrupt controller to use the RAM table. When the interrupt vector table should reside inROM, the function does nothing and always returns NULL.OS_ARM_EnableISR(): Enable a specific interruptDescriptionOS_ARM_EnableISR() is used to enable interrupt acceptance of a specific interrupt source in a vectored interruptcontroller.Prototypevoid OS_ARM_EnableISR(int ISRIndex);ParameterDescriptionAdditional InformationDescriptionInstalls an interrupt handlerEnables a specific interruptDisables a specific interruptSets the priority of a specific interruptIndex of the interrupt source, normally the interrupt vector number.Address of the interrupt handler function.Table 15: OS_ARM_InstallSRHandler() parameter listISRIndexTable 16: OS_ARM_EnableISR() parameter listIndex of the interrupt source which should be enabled.This function just enables the interrupt inside the interrupt controller. It does not enable the interrupt of any peripherals.This has to be done elsewhere.OS_ARM_DisableISR(): Disable a specific interruptDescriptionOS_ARM_DisableISR() is used to disable interrupt acceptance of a specific interrupt source in a vectored interruptcontroller which is not of the VIC type.PPARM-231

Prototypevoid OS_ARM_DisableISR(int ISRIndex);ParameterDescriptionISRIndexIndex of the interrupt source which should be disabled.pISRHandler Address of the interrupt handler function.Table 17: OS_ARM_DisableISR() parameter listAdditional InformationThis function just disables the interrupt controller. It does not disable the interrupt of any peripherals. This has to bedone elsewhere.OS_ARM_ISRSetPrio(): Set priority of a specific interruptDescriptionOS_ARM_ISRSetPrio() is used to set or modify the priority of a specific interrupt source by programming theinterrupt controller.Prototypeint OS_ARM_ISRSetPrio (int ISRIndex,int Prio);ParameterDescriptionISRIndexPrioTable 18: OS_ARM_ISRSetPrio() parameter listReturn valuePrevious priority which was assigned before the call of OS_ARM_ISRSetPrio().Additional InformationIndex of the interrupt source which should be modified.The priority which should be set for the specific interrupt.This function sets the priority of an interrupt channel by programming the interrupt controller. Refer to CPU-specificmanuals about allowed priority levels.HIGH PRIORITY NON MASKABLE EXCEPTIONSHigh priority non maskable exceptions with non configurable priority like Reset, NMI and HardFault can not be usedwith IAR PowerPac RTOS functions. These exceptions are never disabled by IAR PowerPac RTOS.Never call any IAR PowerPac RTOS function from an exception handler of one of these exceptions.32IAR PowerPac RTOSfor ARM CoresPPARM-2

Compiler specificsStandard system librariesIAR PowerPac RTOS for ARM may be used with IAR standard libraries for most of all projects.Heap management and file operation functions of standard system libraries are not reentrant and can therefore not beused with IAR PowerPac RTOS, if non thread-safe functions are used from different tasks.Thread-safe system librariesUsing embOS with C++ projects and file operations or just normal call of heap management functions may requirethread-safe system libraries if these functions are called from different tasks. Thread-safe system libraries require somelocking mechanism which is RTOS specific.System libraries delivered with compiler version 4.41A or newer already contain a locking mechanism which may beused with IAR PowerPac RTOS if required. The locking has to be initialized once by a call ofOS_INIT_SYS_LOCKS().OS_INIT_SYS_LOCKS(), THREAD SAFE SYSTEM LOCKINGTo use the automatic locking mechanism which is implemented in the system libraries which came with compilerversion 4.41A or newer, it has to be initialized once by calling OS_INIT_SYS_LOCKS().This function should be called from main() during the initialization, directly after the call of OS_InitKern(). Aftercalling OS_INIT_SYS_LOCKS() all functions which are normally not thread-safe can be used from any task withoutany precaution. OS_INIT_SYS_LOCKS() does not work when the system libraries which came with compiler version4.40A or older are used.PPARM-2 33

34IAR PowerPac RTOSfor ARM CoresPPARM-2

STOP / WAIT ModeIn case your controller does support some kind of power saving mode, it should be possible to use it also with IARPowerPac RTOS, as long as the timer keeps working and timer interrupts are processed. To enter that mode, you usuallyhave to implement some special sequence in the function OS_Idle(), which you can find in IAR PowerPac RTOSmodule RTOSInit.c.PPARM-2 35

36IAR PowerPac RTOSfor ARM CoresPPARM-2

Technical dataMemory requirementsThese values are neither precise nor guaranteed but they give you a good idea of the memory-requirements. They varydepending on the current version of IAR PowerPac RTOS. Using ARM mode, the minimum ROM requirement for thekernel itself is about 2.500 bytes. In Thumb mode, the kernel itself does have a minimum ROM size of about 1.700bytes.In the table below, which is for release build, you can find minimum RAM size requirements for IAR PowerPac RTOSresources. Note that the sizes depend on selected IAR PowerPac RTOS library mode.IAR PowerPac RTOS resourceTask control block 32Resource semaphore 8Counting semaphore 4Mailbox 20Software timer 20Table 19: Memory requirementsRAM [bytes]PPARM-2 37

38IAR PowerPac RTOSfor ARM CoresPPARM-2

Files shipped with IAR PowerPacRTOSDirectory File ExplanationPowerPac\Doc*.pdfGeneric API and target specific documentation and releasereadme.htmnotes.IncRTOS.hBSP.hInclude file for IAR PowerPac RTOS, to be included in everyC-file using IAR PowerPac RTOS functions.Lib os*.r79 IAR PowerPac RTOS libraries.Src\*.batBuildLib.ewwBatch files to build the IAR PowerPac RTOS libraries andworkspace for building a library.Src\CPU RTOSVect.asm IAR PowerPac RTOS interrupt handler.Src\CPU OS_Priv.h CPU and compiler specific header file.START\GenOSSrc *.* Source for IAR PowerPac RTOS libraries.Table 20: Files shipped with IAR PowerPac RTOSPPARM-2 39

40IAR PowerPac RTOSfor ARM CoresPPARM-2

IndexIndexCcopyright notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2CSTACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Ddisclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2document conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Eedition, of this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Gguidelines, reading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5IInterrupt stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23IRQ_STACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23MMemory requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37OOS_ARM_AssignISRSource() . . . . . . . . . . . . . . . . . . . . . . . . . 27OS_ARM_DisableISRSource(). . . . . . . . . . . . . . . . . . . . . . . . . 27OS_ARM_DisableISR(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26OS_ARM_EnableISRSource() . . . . . . . . . . . . . . . . . . . . . . . . . 27OS_ARM_EnableISR() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26OS_ARM_InstallISRHandler() . . . . . . . . . . . . . . . . . . . . . . . . . 25OS_ARM_ISRSetPrio() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26OS_irq_handler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24OS_IRQ_SERVICE() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24OS_USER_irq_func(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Ppart number, of this guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2publication date, of this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Rreading guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5registered trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2SSyntax, conventions used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5System stack. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23TTask stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Vversion, IAR Embedded Workbench . . . . . . . . . . . . . . . . . . . . . 2PPARM-241