IAR PowerPac RTOS for ARM Cores

Transcription

1 IAR PowerPac RTOS for ARM Cores CPU and compiler specifics using IAR Embedded Workbench

2 COPYRIGHT NOTICE Copyright IAR Systems. 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: Internal reference: ISUD.

3 Contents Preface... 5 Using IAR PowerPac RTOS with IAR Embedded Workbench... 7 First steps... 7 The example application Start_2Tasks.c... 8 Stepping through the sample application using C-SPY... 8 Build your own application Introduction Required files for an IAR PowerPac RTOS application Change library mode Select another CPU ARM core specifics CPU modes Naming conventions for prebuilt libraries Naming conventions for prebuilt libraries ARM7/9 specifics Stacks Task stack for ARM7 and ARM System stack for ARM7 and ARM Interrupt stack for ARM7 and ARM Stack specifics of the ARM7 and ARM9 family Interrupts What happens when an interrupt occurs? Defining interrupt handlers in C Interrupt handling without vectored interrupt controller Interrupt handling with vectored interrupt controller Interrupt-stack switching Fast Interrupt (FIQ) Cortex-M3 specifics Stacks Task stack for Cortex M System stack for Cortex M Interrupt stack for Cortex M Interrupts What happens when an interrupt occurs? Defining interrupt handlers in C Interrupt vector table Interrupt-stack switching Fast interrupts with Cortex M Interrupt priorities Interrupt handling with vectored interrupt controller High-priority non-maskable exceptions

4 Compiler specifics Standard system libraries...33 Thread-safe system libraries...33 OS_INIT_SYS_LOCKS(), thread safe system locking...33 MMU and cache support What happens when an interrupt occurs?...35 MMU and cache handling for ARM9 CPUs...35 OS_ARM_MMU_InitTT() OS_ARM_MMU_AddTTEntries()...35 OS_ARM_MMU_Enable()...36 OS_ARM_ICACHE_Enable()...36 OS_ARM_DCACHE_Enable()...36 OS_ARM_DCACHE_CleanRange()...37 OS_ARM_DCACHE_InvalidateRange()...37 MMU and cache handling for ARM720 CPUs...38 OS_ARM720_MMU_InitTT()...38 OS_ARM720_MMU_AddTTEntries()...38 OS_ARM720_MMU_Enable()...39 OS_ARM720_CACHE_Enable()...39 OS_ARM720_CACHE_CleanRange()...40 OS_ARM720_CACHE_InvalidateRange()...40 MMU and cache handling program sample...41 STOP / WAIT Mode Technical data Memory requirements...45 Files shipped with IAR PowerPac RTOS Index IAR PowerPac RTOS for ARM Cores

5 Preface Welcome to IAR PowerPac RTOS for ARM Cores. This guide describes how to use IAR PowerPac RTOS for the ARM Cores using IAR Embedded Workbench. 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 information about the CPU and compiler specifics using. How to use this guide This guide describes all CPU and compiler specifics of IAR PowerPac RTOS using ARM-based controllers. Before actually using IAR PowerPac RTOS, you should read or at least glance through this guide to become familiar with the software. The chapter Using IAR PowerPac RTOS with IAR Embedded Workbench gives you a step-by-step introduction, how to use IAR PowerPac RTOS for ARM. If you have no experience using IAR PowerPac RTOS, you should follow this introduction, 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 about functionality and fine-tuning of IAR PowerPac RTOS for the ARM-based controllers. Document conventions TYPOGRAPHIC CONVENTIONS FOR SYNTAX This guide uses the following typographic conventions: Style Keyword Parameter Sample Reference GUIElement Emphasis Table 1: Typographic conventions Text that you enter at the command-prompt or that appears on the display (that is system functions, 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 sections 5

6 6 IAR PowerPac RTOS for ARM Cores

7 Using IAR PowerPac RTOS with IAR Embedded Workbench This chapter describes how to start with and use IAR PowerPac RTOS for ARM and the IAR compiler. You should follow these steps to become familiar with IAR PowerPac RTOS for ARM together with IAR Embedded Workbench. First steps After installation of IAR PowerPac RTOS you can create your first multitasking application. An example workspace and 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:\work In 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 list Select the project which is consistent to your hardware, or start with the IAR Simulator project. Choose a destination folder for your project, for example c:\work. After generating the project of your choice, the screen should look for example like this: Build the project. It should be built without any error or warning messages. For latest information, open the file ARM\PowerPac\Doc\ReadMe.txt. 7

8 The example application Start_2Tasks.c The following is a printout of the example application Start_2Tasks.c. It is a good starting point for your application. (Note that the file actually included in the board support package that you are using might look slightly different from this 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 continue execution. #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 sample application using C-SPY When starting the debugger, you will see the main function (see example screenshot below). The main function appears as long as the C-SPY option Run to main is selected, which it is by default. Now you can step through the program. OS_IncDI() initially disables interrupts. OS_InitKern() is part of the IAR PowerPac RTOS library and written in assembler; you can therefore only step into it in disassembly mode. It initializes the relevant OS variables. Because of the previous call of OS_IncDI(), interrupts are 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 the hardware required to generate the timer-tick-interrupt for IAR PowerPac RTOS. Step through it to see what is done. 8 IAR PowerPac RTOS for ARM Cores

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

10 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. 10 IAR PowerPac RTOS for ARM Cores

11 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 task that has the highest priority. 11

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

13 Using IAR PowerPac RTOS with IAR Embedded Workbench You will enter the idle loop when you step into the OS_Delay() function in disassembly mode. OS_Idle() is part of RTOSInit*.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. 13

14 Add the OS_Time timer variable to the Watch window to see that HPTask continues operation after expiration of the 10 ms delay. 14 IAR PowerPac RTOS for ARM Cores

15 Build your own application This chapter provides information about how to set up your own IAR PowerPac RTOS project. Introduction To 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. Using an example project as starting point has the advantage that all necessary files are included and all settings for the project are already done. Required files for an IAR PowerPac RTOS application To build an application using IAR PowerPac RTOS, the following files from your IAR PowerPac RTOS distribution are required and have to be included in your project: RTOS.h available in the subfolder RTOS\Inc\. This header file declares all IAR PowerPac RTOS API functions and data types and has to be included in any source file that uses IAR PowerPac RTOS functions. RTOSInit_*.c available in the BoardSupport\[Manufacturer]\[CPU]\Setup subfolder. It contains hardware-dependent initialization code for IAR PowerPac RTOS timer. One IAR PowerPac RTOS library available in the subfolder RTOS\Lib\. OS_Error.c available in the subfolder BoardSupport\[Manufacturer]\[CPU]\Setup\. The error handler is used if any library other than the Release build library is used in your project. Additional low-level initialization code might be required depending on the CPU. When you decide to write your own startup code or use a low_level_init function, ensure that non-initialized variables are initialized with zero, according to C standard. This is required for some IAR PowerPac RTOS internal variables. Also, ensure that main() is called with CPU running in supervisor or system mode. Your main() function has to initialize IAR PowerPac RTOS by calling OS_InitKern() and OS_InitHW() prior to any other IAR PowerPac RTOS functions are called. You should then modify or replace the Start_2Task.c source file in the subfolder Application\. Change library mode For your application you might want to choose another library. For debugging and program development you should use an IAR PowerPac RTOS-debug library. For your final application you may wish to use an IAR PowerPac RTOSrelease library 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 all other library groups from build, delete unused Lib groups or remove them from the configuration. Check and set the appropriate OS_LIBMODE_* preprocessor symbol on the C/C++ Compiler > Preprocessor options page. 15

16 Select another CPU IAR PowerPac RTOS for ARM contains CPU-specific code for various ARM CPUs. The folder BoardSupport contains workspaces for different target CPUs and specific eval boards. Check whether your CPU is supported by IAR PowerPac RTOS. CPU-specific functions are located in the Setup subfolder in each board support project folder. To select a CPU which is already supported, just select the appropriate project 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 select one which almost fits your CPU. You may have to modify OS_InitHW(), OS_COM_Init(), and the interrupt service routines for IAR PowerPac RTOS timer tick. 16 IAR PowerPac RTOS for ARM Cores

17 ARM core specifics CPU modes IAR PowerPac RTOS supports nearly all code model combinations that the IAR C/C++ Compiler supports. IAR PowerPac RTOS comes with ARM and Thumb libraries for interworking and non interworking mode. Naming conventions for prebuilt libraries The IAR PowerPac RTOS library naming conventions are derived from the library naming conventions which is used in the compatible version of the IAR Embedded Workbench. NAMING CONVENTIONS FOR PREBUILT LIBRARIES IAR PowerPac RTOS is shipped with different prebuilt libraries with different combinations of the following features: Instruction set architecture - isa CPU mode - mode Byte order - byteorder FPU (all prebuilt libraries are built with software floating-point support.) - float Interworking - interwork Library mode - libmode The libraries are named as follows: <type><isa>_<mode><byteorder><float><interwork><libmode>.a Parameter Values type Type of library. os: IAR PowerPac RTOS library isa Specifies the instruction set 4t: v4t architecture. 5t: v5t, v6 7m: v7m mode Specifies the CPU mode. a: ARM t: Thumb / Thumb2 byteorder Specifies the target byte b: Big order. l: Little float Specifies the type of floating-point _: Software floating-point support support. s: Stack check Example v: VFP with VFP parameters interwork Specifies whether the interwork option is i: Enable interworking enabled. _: Do not use interworking libmode Specifies the library mode xr: Extreme Release r: Release s: Stack check d: Debug Table 2: Library naming conventions for prebuild libraries os4t_tl_ir.a is the IAR PowerPac RTOS library for a project supporting an ARM architecture v4t core, using Thumb mode, the little-endian byte order, software floating-point support, compiled with the interwork option and release build configuration. 17

18 Available prebuilt libraries library name isa mode endianess float interworking libmode os4t_ab rx.a v4t ARM Big No No Extreme Release os4t_ab r.a v4t ARM Big No No Release os4t_ab s.a v4t ARM Big No No Stack check os4t_ab d.a v4t ARM Big No No Debug os4t_al xr.a v4t ARM Little No No Extreme Release os4t_al r.a v4t ARM Little No No Release os4t_al s.a v4t ARM Little No No Stack check os4t_al d.a v4t ARM Little No No Debug os4t_ab_ixr.a v4t ARM Big No Yes Extreme Release os4t_ab_ir.a v4t ARM Big No Yes Release os4t_ab_is.a v4t ARM Big No Yes Stack check os4t_ab_id.a v4t ARM Big No Yes Debug os4t_al_ixr.a v4t ARM Little No Yes Extreme Release os4t_al_ir.a v4t ARM Little No Yes Release os4t_al_is.a v4t ARM Little No Yes Stack check os4t_al_id.a v4t ARM Little No Yes Debug os4t_tb xr.a v4t Thumb Big No No Extreme Release os4t_tb r.a v4t Thumb Big No No Release os4t_tb s.a v4t Thumb Big No No Stack check os4t_tb d.a v4t Thumb Big No No Debug os4t_tl xr.a v4t Thumb Little No No Extreme Release os4t_tl r.a v4t Thumb Little No No Release os4t_tl s.a v4t Thumb Little No No Stack check os4t_tl d.a v4t Thumb Little No No Debug os4t_tb_ixr.a v4t Thumb Big No Yes Extreme Release os4t_tb_ir.a v4t Thumb Big No Yes Release os4t_tb_is.a v4t Thumb Big No Yes Stack check os4t_tb_id.a v4t Thumb Big No Yes Debug os4t_tl_ixr.a v4t Thumb Little No Yes Extreme Release os4t_tl_ir.a v4t Thumb Little No Yes Release os4t_tl_is.a v4t Thumb Little No Yes Stack check os4t_tl_id.a v4t Thumb Little No Yes Debug os5t_ab xr.a v5t, v6 ARM Big No No Extreme Release os5t_ab r.a v5t, v6 ARM Big No No Release os5t_ab s.a v5t, v6 ARM Big No No Stack check os5t_ab d.a v5t, v6 ARM Big No No Debug os5t_al xr.a v5t, v6 ARM Little No No Extreme Release os5t_al r.a v5t, v6 ARM Little No No Release os5t_al s.a v5t, v6 ARM Little No No Stack check os5t_al d.a v5t, v6 ARM Little No No Debug os5t_ab_ixr.a v5t, v6 ARM Big No Yes Extreme Release os5t_ab_ir.a v5t, v6 ARM Big No Yes Release os5t_ab_is.a v5t, v6 ARM Big No Yes Stack check os5t_ab_id.a v5t, v6 ARM Big No Yes Debug os5t_al_ixr.a v5t, v6 ARM Little No Yes Extreme Release os5t_al_ir.a v5t, v6 ARM Little No Yes Release Table 3: Prebuilt libraries 18 IAR PowerPac RTOS for ARM Cores

19 ARM core specifics library name isa mode endianess float interworking libmode os5t_al_is.a v5t, v6 ARM Little No Yes Stack check os5t_al_id.a v5t, v6 ARM Little No Yes Debug os5t_tb xr.a v5t, v6 Thumb Big No No Extreme Release os5t_tb r.a v5t, v6 Thumb Big No No Release os5t_tb s.a v5t, v6 Thumb Big No No Stack check os5t_tb d.a v5t, v6 Thumb Big No No Debug os5t_tl xr.a v5t, v6 Thumb Little No No Extreme Release os5t_tl r.a v5t, v6 Thumb Little No No Release os5t_tl s.a v5t, v6 Thumb Little No No Stack check os5t_tl d.a v5t, v6 Thumb Little No No Debug os5t_tb_ixr.a v5t, v6 Thumb Big No Yes Extreme Release os5t_tb_ir.a v5t, v6 Thumb Big No Yes Release os5t_tb_is.a v5t, v6 Thumb Big No Yes Stack check os5t_tb_id.a v5t, v6 Thumb Big No Yes Debug os5t_tl_ixr.a v5t, v6 Thumb Little No Yes Extreme Release os5t_tl_ir.a v5t, v6 Thumb Little No Yes Release os5t_tl_is.a v5t, v6 Thumb Little No Yes Stack check os5t_tl_id.a v5t, v6 Thumb Little No Yes Debug os7m_tb xr.a v7m Thumb2 Big No No Extreme Release os7m_tb r.a v7m Thumb2 Big No No Release os7m_tb s.a v7m Thumb2 Big No No Stack check os7m_tb d.a v7m Thumb2 Big No No Debug os7m_tl xr.a v7m Thumb2 Little No No Extreme Release os7m_tl r.a v7m Thumb2 Little No No Release os7m_tl s.a v7m Thumb2 Little No No Stack check os7m_tl d.a v7m Thumb2 Little No No Debug Table 3: Prebuilt libraries (Continued) 19

20 20 IAR PowerPac RTOS for ARM Cores

21 ARM7/9 specifics Stacks TASK STACK FOR ARM7 AND ARM9 All IAR PowerPac RTOS tasks execute in system mode. Every IAR PowerPac RTOS task has its own individual stack which can be located in any memory area. The stack-size required is the sum of the stack-size of all routines plus basic stack size. The basic stack size is the size of memory required to store the registers of the CPU plus the stack size required by IAR PowerPac RTOS-routines. For the ARM7/ARM9 cores, the minimum task stack size is about 68 bytes. The end address of the task stack has to be aligned to an 8-byte boundary. In the current version of IAR PowerPac RTOS, this alignment is forced during stack pointer initialization. Therefore, an additional margin of about 8 bytes should be added to the calculated maximum task stack size. SYSTEM STACK FOR ARM7 AND ARM9 The IAR PowerPac RTOS system executes in supervisor mode. The minimum system stack size required by IAR PowerPac RTOS is about 136 bytes (stack check build). However, because the system stack is also used by the application before the start of multitasking (the call to OS_Start()), and because software-timers and C level interrupt handlers 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 *.icf linker configuration file. INTERRUPT STACK FOR ARM7 AND ARM9 If a normal hardware exception occurs, the ARM core switches to IRQ mode, which has a separate stack pointer. To enable 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 IRQ stack. As a result, only registers mentioned above are saved onto the IRQ stack. For the interrupt routine itself, the supervisor stack is used. The size of the interrupt stack can be changed by modifying IRQ_STACK in your *.icf linker configuration file. We recommend at least 128 bytes. Every interrupt requires 28 bytes on the interrupt stack. The maximum interrupt stack size required by the application can be calculated according to this form Maximum interrupt nesting level * 28 bytes. For task switching from within an interrupt handler, it is required, that the end address of the interrupt stack is aligned to an 8-byte boundary. This alignment is forced during stack pointer initialization in the startup routine. Therefore, an additional margin of about 8 bytes should be added to the calculated maximum interrupt stack size. For standard applications, we recommend at least 92 to 128 bytes for the IRQ stack. STACK SPECIFICS OF THE ARM7 AND ARM9 FAMILY There are two stacks which have to be declared in the linker configuration file: CSTACK is the system stack. IRQ_STACK is the interrupt stack. The CSTACK is used during startup, during main(), for IAR PowerPac RTOS internal functions, and for C-level interrupt handlers. The IRQ_STACK is used when an interrupt exception is triggered. The exception handler saves some registers and then performs a mode switch which then uses CSTACK as stack for further execution. The startup code initializes the system stack pointer and the IRQ stack pointer. When the CPU starts, it runs in Supervisor mode. 21

22 The startup code switches to IRQ mode and sets the stack pointer to the stack which was defined as IRQ_STACK. The startup code switches to System mode and sets the stack pointer to the stack which was defined as CSTACK. The main() function is therefore called in system mode and uses the CSTACK. When IAR PowerPac RTOS is initialized, the supervisor stack pointer is initialized. The supervisor stack and system stack are the same, both stack pointers point into the CSTACK. This is no problem, because the supervisor mode is not entered as long as main() is executed. All functions run in system mode. After IAR PowerPac RTOS is started with OS_Start(), IAR PowerPac RTOS internal functions run in Supervisor mode, as long as no task is running. The CSTACK can then be used as Supervisor stack, because it is no longer used by other functions. Tasks run in system mode, but they do not use the system stack. Tasks have their own stack which is defined as some variable in any RAM location. Interrupts WHAT HAPPENS WHEN AN INTERRUPT OCCURS? The CPU-core receives an interrupt request. As soon as the interrupts are enabled, the interrupt is executed. The CPU switches to the Interrupt stack. The CPU saves PC and flags in registers LR_irq and SPSR_irq. The CPU jumps to the vector address 0x18. IAR PowerPac RTOS IRQ_Handler(): saves scratch registers. IAR PowerPac RTOS IRQ_Handler(): saves LR_irq and SPSR_irq. IAR PowerPac RTOS IRQ_Handler(): switches to supervisor mode. IAR PowerPac RTOS IRQ_Handler(): executes OS_irq_handler() (defined in RTOSINIT_*.c). IAR PowerPac RTOS OS_irq_handler(): checks for interrupt source and executes timer interrupt, serial communication or user ISR. IAR PowerPac RTOS IRQ_Handler(): switches to IRQ mode. IAR PowerPac RTOS IRQ_Handler(): restores LR_irq and SPSR_irq. IAR PowerPac RTOS IRQ_Handler(): pops scratch registers. Returns from the interrupt. When using an ARM device with a vectored interrupt controller, ensure that IRQ_Handler() is called from every interrupt. The interrupt vector itself can then be examined by the C-level interrupt handler in RTOSInit*.c. DEFINING INTERRUPT HANDLERS IN C Interrupt handlers called from the IAR PowerPac RTOS interrupt handler in RTOSInit*.c are just normal C-functions which 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() or OS_EnterNestableInterrupt() to inform IAR PowerPac RTOS that interrupt code is running. Then this handler examines 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() or OS_LeaveNestableInterrupt() and returns to the primary interrupt handler IRQ_Handler(). Depending on the interrupting source, it may be required to reset the interrupt pending condition of the related peripherals. Example Simple interrupt routine: void Timer_irq_func(void) { if ( INTPND & 0x0800) { // Interrupt pending? INTPND = 0x0800; // reset pending condition OSTEST_X_ISR0(); // handle interrupt } } 22 IAR PowerPac RTOS for ARM Cores

23 ARM7/9 specifics INTERRUPT HANDLING WITHOUT VECTORED INTERRUPT CONTROLLER Standard ARM CPUs, without implementation of a vectored interrupt controller, always branch to address 0x18 when an interrupt occurs. The application is responsible to examine the interrupting source. The reaction to an interrupt is as follows: IAR PowerPac RTOS IRQ_Handler() is called. IRQ_Handler() saves registers and switches to supervisor mode. IRQ_Handler() 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 the application. OS_irq_handler() checks whether the IAR PowerPac RTOS timer interrupt has to be handled. OS_irq_handler() informs IAR PowerPac RTOS that interrupt handling has ended by a call to OS_LeaveInterrupt() and returns to IRQ_Handler(). IRQ_Handler() restores registers and returns from the interrupt. Example Simple OS_USER_irq_func() routine: void OS_USER_irq_func(void) { if ( INTPND & 0x0800) { // Interrupt pending? INTPND = 0x0800; // Reset pending condition OSTEST_X_ISR0(); // Handle interrupt } if ( INTPND & 0x0400) { // Interrupt pending? } } INTPND = 0x0400; OSTEST_X_ISR1(); // Reset pending condition // Handle interrupt During interrupt processing, you should not re-enable interrupts, as this would lead in recursion. INTERRUPT HANDLING WITH VECTORED INTERRUPT CONTROLLER For ARM derivates with built in vectored interrupt controller, IAR PowerPac RTOS uses a different interrupt handling procedure and delivers additional functions to install and setup interrupt handler functions. When using an ARM derivate with vectored interrupt controller, ensure that IRQ_Handler() is called from every interrupt. 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() in RTOSInit*.c. You should not program the interrupt controller for IRQ handling directly. You should use the functions delivered with IAR PowerPac RTOS. The reaction to an interrupt with vectored interrupt controller is as follows: RTOS IRQ_Handler() is called by the CPU or an interrupt controller IRQ_Handler() saves registers and switches to supervisor mode IRQ_Handler() 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 of OS_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 IAR PowerPac RTOS that interrupt handling has finished OS_irq_handler() returns to IRQ_Handler IRQ_Handler() restores registers and returns from the interrupt. Note:Different ARM CPUs may have different versions of vectored interrupt controller hardware, and usage of IAR PowerPac RTOS supplied functions varies depending on the type of interrupt controller. Refer to the samples delivered with IAR PowerPac RTOS which are used in the CPU specific RTOSInit module. 23

24 To handle interrupts with vectored interrupt controller, IAR PowerPac RTOS offers the following functions. Function OS_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 handler OS_ARM_InstallISRHandler() is used to install a specific interrupt vector when ARM CPUs with vectored interrupt controller are used. Prototype OS_ISR_HANDLER* OS_ARM_InstallISRHandler ( int ISRIndex, OS_ISR_HANDLER * pisrhandler ); Parameter Return value OS_ISR_HANDLER*: The address of the previously installed interrupt function, which was installed at the addressed vector number before. Additional Information This function just installs the interrupt vector but does not modify the priority and does not automatically enable the interrupt. OS_ARM_EnableISR(): Enable a specific interrupt OS_ARM_EnableISR() is used to enable interrupt acceptance of a specific interrupt source in a vectored interrupt controller. Prototype void OS_ARM_EnableISR ( int ISRIndex ); Parameter Additional Information Installs an interrupt handler. Enables a specific interrupt. Disables a specific interrupt. Sets the priority of a specific interrupt. Assigns a hardware interrupt channel to an interrupt vector. Enables an interrupt channel of a VIC type interrupt controller. Disables an interrupt channel of a VIC type interrupt controller. Table 4: Interrupt handler functions for ARM devices with built in vectored interrupt controller ISRIndex pisrhandler Table 5: OS_ARM_InstallSRHandler() parameter list ISRIndex Table 6: OS_ARM_EnableISR() parameter list Index of the interrupt source, normally the interrupt vector number. Address of the interrupt handler function. Index 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. Note:For ARM CPUs with VIC type interrupt controller, this function just enables the interrupt vector itself. To enable the hardware assigned to that vector, you have to call OS_ARM_EnableISRSource() also. OS_ARM_DisableISR(): Disable a specific interrupt OS_ARM_DisableISR() is used to disable interrupt acceptance of a specific interrupt source in a vectored interrupt controller which is not of the VIC type. 24 IAR PowerPac RTOS for ARM Cores

25 ARM7/9 specifics Prototype void OS_ARM_DisableISR ( int ISRIndex ); Parameter ISRIndex Index of the interrupt source which should be disabled. Table 7: OS_ARM_DisableISR() parameter list Additional Information This function just disables the interrupt controller. It does not disable the interrupt of any peripherals. This has to be done 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 interrupt OS_ARM_ISRSetPrio() is used to set or modify the priority of a specific interrupt source by programming the interrupt controller. Prototype int OS_ARM_ISRSetPrio ( int ISRIndex, int Prio ); Parameter ISRIndex Prio Table 8: OS_ARM_ISRSetPrio() parameter list Return value Previous priority which was assigned before the call of OS_ARM_ISRSetPrio(). Additional Information This function sets the priority of an interrupt channel by programming the interrupt controller. Refer to CPU-specific manuals about allowed priority levels. Note:This function cannot be used to modify the interrupt priority for interrupt controllers of the VIC type. The interrupt priority with VIC-type controllers depends on the interrupt vector number and cannot be changed. OS_ARM_AssignISRSource(): Assign a hardware interrupt channel to an interrupt vector OS_ARM_AssignISRSource() is used to assign a hardware interrupt channel to an interrupt vector in an interrupt controller of VIC type. Prototype void OS_ARM_AssignISRSource ( int ISRIndex, int Source ); Parameter ISRIndex Source Table 9: OS_ARM_AssignISRSource() parameter list Additional Information Index of the interrupt source which should be modified. The priority which should be set for the specific interrupt. Index of the interrupt source which should be modified. The source channel number which should be assigned to the specified interrupt vector. This function assigns a hardware interrupt line to an interrupt vector of VIC type only. It cannot be used for other types of vectored interrupt controllers. The hardware interrupt channel number of specific peripherals depends on specific CPU derivates and has to be taken from the hardware manual of the CPU. 25

26 OS_ARM_EnableISRSource(): Enable an interrupt channel of a VIC-type interrupt controller OS_ARM_EnableISRSource() is used to enable an interrupt input channel of an interrupt controller of VIC type. Prototype void OS_ARM_DisableISRSource ( int SourceIndex ); Parameter SourceIndex Index of the interrupt channel which should be enabled. Table 10: OS_ARM_EnableISRSource() parameter list Additional Information This function enables a hardware interrupt input of a VIC-type interrupt controller. It cannot be used for other types of vectored interrupt controllers. The hardware interrupt channel number of specific peripherals depends on specific CPU derivates and has to be taken from the hardware manual of the CPU. OS_ARM_DisableISRSource(): Disable an interrupt channel of a VIC-type interrupt controller OS_ARM_DisableISRSource() is used to disable an interrupt input channel of an interrupt controller of VIC type. Prototype void OS_ARM_DisableISRSource ( int SourceIndex ); Parameter SourceIndex Table 11: OS_ARM_DisableISRSource() parameter list Additional Information This function disables a hardware interrupt input of a VIC-type interrupt controller. It cannot be used for other types of vectored interrupt controllers. The hardware interrupt channel number of specific peripherals depends on specific CPU derivates and has to be taken from the hardware manual of the CPU. Example Index of the interrupt channel which should be disabled. /* 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 vector OS_ARM_AssignISRSource(UART_INT_INDEX, UART_INT_SOURCE); OS_ARM_EnableISR(UART_INT_INDEX); // Enable UART interrupt vector OS_ARM_EnableISRSource(UART_INT_SOURCE); // Enable UART interrupt source INTERRUPT-STACK SWITCHING Because ARM core based controllers have a separate stack pointer for interrupts, there is no need for explicit stackswitching in an interrupt routine. The routines OS_EnterIntStack() and OS_LeaveIntStack() are supplied for source compatibility to other processors only and have no functionality. The ARM interrupt stack is used for the primary interrupt handler in RTOS.s only. FAST INTERRUPT (FIQ) The 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. 26 IAR PowerPac RTOS for ARM Cores

27 ARM7/9 specifics Note:When you decide to use FIQ, ensure the FIQ stack is initialized during startup and that an interrupt vector for FIQ handling is included in your application. 27

28 28 IAR PowerPac RTOS for ARM Cores

29 Cortex-M3 specifics Stacks TASK STACK FOR CORTEX M3 All IAR PowerPac RTOS tasks execute in thread mode using the process stack pointer. The stack-size required is the sum of the stack-size of all routines plus basic stack size plus size used by exceptions. The basic stack size is the size of memory required to store the registers of the CPU plus the stack size required by IAR PowerPac RTOS-routines. For the Cortex M3 CPU, this minimum task stack size is about 72 bytes. But because any function call uses some amount of stack and every exception also pushes at least 32 bytes onto the current stack, the task stack size has to be large enough to handle all nested exceptions too. We recommend at least 256 bytes stack as a start. In the current version of IAR PowerPac RTOS, this alignment is forced during stack pointer initialization. Therefore, an additional margin of about 8-bytes should be added to the calculated maximum task stack size. SYSTEM STACK FOR CORTEX M3 The IAR PowerPac RTOS system executes in thread mode, the scheduler executes in handler mode. The minimum system stack size required by IAR PowerPac RTOS is about 136 bytes (stack check & profiling build) However, since the system stack is also used by the application before the start of multitasking (the call to OS_Start()), and because software-timers and C-level interrupt handlers 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 *.icf file. INTERRUPT STACK FOR CORTEX M3 If a normal hardware exception occurs, the Cortex M3 core switches to handler mode mode, which uses the main stack pointer. With IAR PowerPac RTOS, the main stack pointer is initialized to use the CSTACK which is defined in the linker command file. A separate IRQ_STACK is not used, interrupts run on the system stack. Interrupts The Cortex M3 core comes with an built in vectored interrupt controller which supports up to 496 separate interrupt sources. 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 executed. The 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 C Interrupt handlers for Cortex M3 are written as normal C-functions which do not take parameters and do not return any value. 29

30 Example A simple interrupt-routine: static void _Systick(void) { OS_EnterNestableInterrupt(); // Inform IAR PowerPac RTOS that interrupt code is running OS_HandleTick(); OS_LeaveNestableInterrupt(); // Inform IAR PowerPac RTOS that interrupt handler is left } INTERRUPT VECTOR TABLE After 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 interrupt handler 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 switch OS_USE_VARINTTABLE is used to enable usage of a vector table in RAM. To save RAM, the switch is set to zero per default in RTOSInit_*.c. It may be overwritten by project settings to enable the vector table in RAM. The first call of OS_InstallISRHandler() will then automatically copy the vector table into RAM. INTERRUPT-STACK SWITCHING Since Cortex M3 core based controllers have a separate stack pointer for interrupts, there is no need for explicit stackswitching in an interrupt routine. The routines OS_EnterIntStack() and OS_LeaveIntStack() are supplied for source compatibility to other processors only and have no functionality. FAST INTERRUPTS WITH CORTEX M3 Instead of disabling interrupts when IAR PowerPac RTOS does atomic operations, the interrupt level of the CPU is set to 128. Therefore all interrupt priorities higher than 128 can still be processed. Please note, that lower priority number define 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 fast interrupt function. INTERRUPT PRIORITIES With introduction of Fast interrupts, interrupt priorities usable for interrupts using IAR PowerPac RTOS API functions are limited. Any interrupt handler using IAR PowerPac RTOS API functions has to run with interrupt priorities from 128 to 255. These IAR PowerPac RTOS interrupt handlers have to start with OS_EnterInterrupt() or OS_EnterNestableInterrupt() and must end with OS_LeaveInterrupt() or OS_LeaveNestableInterrupt(). Any Fast interrupt (running at priorities from 0 to 127) must not call any IAR PowerPac RTOS API function. Even OS_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 are allowed, 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 changed by recompiling IAR PowerPac RTOS libraries! INTERRUPT HANDLING WITH VECTORED INTERRUPT CONTROLLER For Cortex M3, which has a built in vectored interrupt controller, IAR PowerPac RTOS delivers additional functions to install and setup interrupt handler functions. 30 IAR PowerPac RTOS for ARM Cores

31 Cortex-M3 specifics To handle interrupts with the vectored interrupt controller, IAR PowerPac RTOS offers the following functions: Function OS_ARM_InstallISRHandler() OS_ARM_EnableISR() OS_ARM_DisableISR() OS_ARM_ISRSetPrio() Table 12: Interrupt handler functions for Cortex M3 cores OS_ARM_InstallISRHandler(): Install an interrupt handler OS_ARM_InstallISRHandler() is used to install a specific interrupt vector when ARM CPUs with vectored interrupt controller are used. Prototype OS_ISR_HANDLER* OS_ARM_InstallISRHandler ( int ISRIndex, OS_ISR_HANDLER* pisrhandler ); Parameter ISRIndex pisrhandler Return value OS_ISR_HANDLER*: The address of the previously installed interrupt function, which was installed at the addressed vector number before. Additional Information This function just installs the interrupt vector but does not modify the priority and does not automatically enable the interrupt. When the interrupt vector table should be located in RAM, the first call of this function copies the vector table into RAM and programs the interrupt controller to use the RAM table. When the interrupt vector table should reside in ROM, the function does nothing and always returns NULL. OS_ARM_EnableISR(): Enable a specific interrupt OS_ARM_EnableISR() is used to enable interrupt acceptance of a specific interrupt source in a vectored interrupt controller. Prototype void OS_ARM_EnableISR ( int ISRIndex ); Parameter Additional Information Installs an interrupt handler Enables a specific interrupt Disables a specific interrupt Sets the priority of a specific interrupt Index of the interrupt source, normally the interrupt vector number. Address of the interrupt handler function. Table 13: OS_ARM_InstallSRHandler() parameter list ISRIndex Table 14: OS_ARM_EnableISR() parameter list Index 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 interrupt OS_ARM_DisableISR() is used to disable interrupt acceptance of a specific interrupt source in a vectored interrupt controller which is not of the VIC type. 31

32 Prototype void OS_ARM_DisableISR ( int ISRIndex ); Parameter ISRIndex Index of the interrupt source which should be disabled. Table 15: OS_ARM_DisableISR() parameter list Additional Information This function just disables the interrupt controller. It does not disable the interrupt of any peripherals. This has to be done elsewhere. OS_ARM_ISRSetPrio(): Set priority of a specific interrupt OS_ARM_ISRSetPrio() is used to set or modify the priority of a specific interrupt source by programming the interrupt controller. Prototype int OS_ARM_ISRSetPrio ( int ISRIndex, int Prio ); Parameter ISRIndex Prio Table 16: OS_ARM_ISRSetPrio() parameter list Return value Previous priority which was assigned before the call of OS_ARM_ISRSetPrio(). Additional Information Index 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-specific manuals about allowed priority levels. HIGH-PRIORITY NON-MASKABLE EXCEPTIONS High-priority non-maskable exceptions with non configurable priority like Reset, NMI and HardFault can not be used with 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. 32 IAR PowerPac RTOS for ARM Cores

33 Compiler specifics Standard system libraries IAR 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 be used with IAR PowerPac RTOS, if non thread-safe functions are used from different tasks. Thread-safe system libraries Using IAR PowerPac RTOS with C++ projects and file operations or just normal calls to heap management functions might require thread-safe system libraries if these functions are called from different tasks. Thread-safe system libraries require some locking mechanism which is RTOS specific. System libraries delivered with compiler version 4.41A or newer already contain a locking mechanism which may be used with IAR PowerPac RTOS if required. The locking has to be initialized once by a call of OS_INIT_SYS_LOCKS(). OS_INIT_SYS_LOCKS(), THREAD SAFE SYSTEM LOCKING To use the automatic locking mechanism which is implemented in the system libraries which came with compiler version 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(). After calling OS_INIT_SYS_LOCKS() all functions which are normally not thread-safe can be used from any task without any precaution. OS_INIT_SYS_LOCKS() does not work when the system libraries that came with the compiler version 4.40A or older are used. 33

34 34 IAR PowerPac RTOS for ARM Cores

35 MMU and cache support What happens when an interrupt occurs? IAR PowerPac RTOS comes with functions to support the MMU and cache of ARM9 and ARM720 CPUs which allow virtual-to-physical address mapping with sections of one MByte and cache control. The MMU requires a translation table which can be located in any data area, RAM or ROM, but has to be aligned at a 16Kbyte boundary. The alignment can be forced by a #pragma or by the linker configuration file. A translation table in RAM has to be set up during run time. IAR PowerPac RTOS delivers API functions to set up this table. Assembly language programming is not required. MMU and cache handling for ARM9 CPUs ARM9 CPUs with MMU and cache have separate data and instruction caches. IAR PowerPac RTOS delivers the following functions to set up and handle the MMU and caches. Function OS_ARM_MMU_InitTT() OS_ARM_MMU_AddTTEntries() OS_ARM_MMU_Enable() OS_ARM_ICACHE_Enable() OS_ARM_DCACHE_Enable() OS_ARM_DCACHE_CleanRange() OS_ARM_DCACHE_InvalidateRange() Table 17: MMU and cache handling for ARM9 CPUs Initialize the MMU translation table. Add address entries to the table. Enable the MMU. Enable the instruction cache. Enable the data cache. Clean data cache. Invalidate the data cache. OS_ARM_MMU_InitTT() OS_ARM_MMU_InitTT() is used to initialize an MMU translation table which is located in RAM. The table is filled with zero, thus all entries are marked invalid initially. Prototype void OS_ARM_MMU_InitTT ( unsigned int * ptranslationtable ); Parameter ptranslationtable Table 18: OS_ARM_MMU_InitTT() parameter list Additional Information This function does not need to be called, if the translation table is located in ROM. OS_ARM_MMU_AddTTEntries() Points to the base address of the translation table. OS_ARM_MMU_AddTTEntries() is used to add entries to the MMU address translation table. The start address of the virtual address, physical address, area size and cache modes are passed as parameter. 35