IAR PowerPac™ RTOS

for Freescale ColdFire® Cores

CPU and compiler specifics

using IAR Embedded Workbench®

PPCF-1
COPYRIGHT NOTICE
© Copyright 2007 IAR Systems. All rights reserved.
No part of this document may be reproduced without the prior written consent of IAR
Systems. 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. 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, IAR Systems, IAR Embedded Workbench, IAR MakeApp, C-SPY, visualSTATE,
From Idea To Target, IAR KickStart Kit and IAR PowerPac are trademarks or registered
trademarks 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 respective
owners.

EDITION NOTICE
First edition: October 2007
Part number: PPCF-1
Internal reference: ISUD.

PPCF-1
Contents
Preface ........................................................................................................................................................................ 5
Using PowerPac RTOS with IAR Embedded Workbench .......................................................................... 7
First steps ........................................................................................................................................................ 7
The example application Start_LEDBlink.c ............................................................................................ 8
Stepping through the example application using C-SPY ..................................................................... 9
Building an application ......................................................................................................................................... 13
Getting started ............................................................................................................................................. 13
Required files for an application ............................................................................................................... 13
Change library mode .................................................................................................................................. 13
Select another CPU .................................................................................................................................... 14
Freescale ColdFire specifics .............................................................................................................................. 15
CPU modes ................................................................................................................................................... 15
Available libraries ........................................................................................................................................ 15
Compiler specifics ................................................................................................................................................ 17
Standard system libraries .......................................................................................................................... 17
Stacks ........................................................................................................................................................................ 19
Task stack for Freescale ColdFire ........................................................................................................... 19
System stack for Freescale ColdFire ...................................................................................................... 19
Interrupt stack for Freescale ColdFire ................................................................................................... 19
Interrupts ................................................................................................................................................................ 21
What happens if an interrupt occurs ...................................................................................................... 21
Defining interrupt handlers in C .............................................................................................................. 21
Interrupt vector table ................................................................................................................................. 21
Fast interrupts with Freescale ColdFire ................................................................................................ 21
Interrupt priorities ...................................................................................................................................... 22
Interrupt handling with vectored interrupt controller ....................................................................... 22
High-priority non-maskable exceptions ................................................................................................. 23
Technical data ......................................................................................................................................................... 25
Memory requirements ............................................................................................................................... 25
Files shipped with PowerPac RTOS ................................................................................................................ 27

PPCF-1 3
 IAR PowerPac™ RTOS
4 Freescale ColdFire® Cores PPCF-1
Preface
Welcome to the guide IAR PowerPac™ RTOS Freescale ColdFire® Cores. This guide describes how to use
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 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 PowerPac RTOS using Freescale ColdFire based controllers.
Before actually using PowerPac RTOS, you should read 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 about
how to use PowerPac RTOS. If you have no experience using PowerPac RTOS, you should follow this introduction,
because it is an easy way to learn how to use 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 PowerPac RTOS for IAR Embedded Workbench for ColdFire.

Document conventions
TYPOGRAPHIC CONVENTIONS FOR SYNTAX
This guide uses the following typographic conventions:
Style Description
Text that you enter at the command-prompt or that appears on the display (that is system
Keyword
functions, file- or pathnames).
Parameter Parameters in API functions.
Sample Sample code in program examples.
Reference Reference to chapters, tables and figures or other documents.
GUIElement Buttons, dialog boxes, menu names, menu commands.
Emphasis Very important sections
Table 1: Typographic conventions

PPCF-1 5
 IAR PowerPac™ RTOS
6 Freescale ColdFire® Cores PPCF-1
Using PowerPac RTOS with IAR
Embedded Workbench
The following chapter describes how to start with and use PowerPac RTOS for Freescale ColdFire and IAR
Embedded Workbench. You should follow these steps to become familiar with PowerPac RTOS for Freescale
ColdFire and IAR Embedded Workbench.

First steps
After you installed of PowerPac RTOS you can create your first multitasking application. You received ready to go
example start workspaces and projects and it is recommended to use one of these as a starting point of all your
applications.
Your PowerPac RTOS distribution contains one folder Start which contains the sample start workspaces and projects
and every additional files used to build your application.
To get your new application running, you should proceed as follows:
1 Create a working directory for your application, for example c:\work.
2 In the IAR Embedded Workbench IDE, select Example Application in the Startup dialog box. To open the Startup
dialog box, choose Help | Startup Screen.
3 Select BoardSupport from the Example Application list.
4 Select the project which is consistent to your hardware, or start with the IAR Simulator project. In this guide the
Start_M52223.eww is used.

PPCF-1 7
 5 Choose a destination folder for your project, for example C:\Work. After generating the project of your choice, the
screen should look something like this:

6 Build the project; it should be built without any error or warning messages.

The example application Start_LEDBlink.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 included in your PowerPac RTOS installation might look slightly different from this
one.)
What happens is easy to see:
After initialization of PowerPac RTOS; two tasks are created and started.
The two tasks are activated and execute until they run into the delay. They are then suspend for the specified time and
then continue to execute.

IAR PowerPac™ RTOS

8 Freescale ColdFire® Cores PPCF-1
 Using PowerPac RTOS with IAR Embedded Workbench

#include "RTOS.h"
#include "BSP.h"

OS_STACKPTR int StackHP[128], StackLP[128]; /* Task stacks */

OS_TASK TCBHP, TCBLP; /* Task-control-blocks */

static void HPTask(void) {

while (1) {
BSP_ToggleLED(0);
OS_Delay (50);
}
}

static void LPTask(void) {

while (1) {
BSP_ToggleLED(1);
OS_Delay (200);
}
}

/*********************************************************************
*
* main
*
*********************************************************************/

int main(void) {
OS_IncDI(); /* Initially disable interrupts */
OS_InitKern(); /* initialize OS */
OS_InitHW(); /* initialize Hardware for OS */
BSP_Init(); /* initialize LED ports */
/* You need to create at least one task before calling OS_Start() */
OS_CREATETASK(&TCBHP, "HP Task", HPTask, 100, StackHP);
OS_CREATETASK(&TCBLP, "LP Task", LPTask, 50, StackLP);
OS_Start(); /* Start multitasking */
return 0;
}

Stepping through the example application using C-SPY

When you start 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 PowerPac RTOS library and it is
written in assembler; you can therefore only step into it in disassembly mode. The function 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 PowerPac RTOS. Step through it to see what
is done. OS_Start() is the last line in main, because it starts the multitasking and does not return.

PPCF-1 9
 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 PowerPac RTOS library, you can step through it in disassembly mode only.
Click GO, step over OS_Start(), or step into OS_Start() in disassembly mode until you reach the highest priority
task.

IAR PowerPac™ RTOS

10 Freescale ColdFire® Cores PPCF-1
 Using PowerPac RTOS with IAR Embedded Workbench

If you continue stepping, you will arrive in the task that has the lower priority:

Continue to step through the program, there is no other task ready for execution. 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 is executing).
The function OS_Idle() is part of RTOSInit*.c. Step into the OS_Delay() function to reach the idle-loop. 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.

PPCF-1 11
 As can be seen by the value of the timer variable OS_Time, displayed in the Watch window, HPTask continues
operation after expiration of the 10 ms delay.

IAR PowerPac™ RTOS

12 Freescale ColdFire® Cores PPCF-1
Building an application
This chapter explains how to set up up your own PowerPac RTOS project.

Getting started
To build your own application, you should always start with one of the supplied example workspaces and projects.
Therefore, select a workspace as described in First steps on page 7 and modify the project to fit your needs. Using a
sample project as a starting point has the advantage that all necessary files are included and all settings for the project
are already done.

Required files for an application

To build an application using PowerPac RTOS, the following files from your PowerPac RTOS distribution are required
and have to be included in your project:
● RTOS.h available in the subfolder Inc\.
This header file declares all API functions and data types and has to be included in any source file using PowerPac
RTOS functions.
● RTOSInit_*.c available in the subfolder CPU.
The file contains hardware-dependent initialization code for the PowerPac RTOS timer.
● One PowerPac RTOS library from the subfolder Lib\.
● OS_Error.c from subfolder 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 may be required by 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 the C standard. This is required for some PowerPac RTOS internal
variables.
Also ensure, that main() is called with the CPU running in thread mode using the main stack.
Your main() function has to initialize PowerPac RTOS by calling OS_InitKern() and OS_InitHW() prior to any
other PowerPac RTOS functions are called.
You should then modify or replace the Start_2Task.c source file in the subfolder Src\.

Change library mode

For your application you might want to choose another library. For debugging and program development you should
use a debug library. For your final application you might want to use a release library or a stack check library.
Therefore, you have to select or replace the 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 the build. Delete unused Lib groups or remove them from the configuration.
● Check and set the appropriate OS_LIBMODE_* define as preprocessor option.
Define OS_LIBMODE_D for a debug library, OS_LIBMODE_R for a release library, OS_LIBMODE_S for a stack check
library in the preprocessor option dialog box.

PPCF-1 13
 Select another CPU
PowerPac RTOS for ColdFire contains CPU-specific code for various ColdFire cores. The folder BoardSupport
contains workspaces for different target CPUs and specific evaluation boards.
Check whether your CPU is supported by 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 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 PowerPac RTOS timer tick.

IAR PowerPac™ RTOS

14 Freescale ColdFire® Cores PPCF-1
Freescale ColdFire specifics
CPU modes
PowerPac RTOS supports code models that the IAR C/C++ Compiler supports.

Available libraries
PowerPac RTOS for Freescale ColdFire is shipped with 14 different libraries, one for each code model/library mode
combination.
The libraries are named as follows:
os<CodeModel><LibMode>.r68
Parameter Description Values
CodeModel Specifies the code model. n: near code model
f: far code model
LibMode Library mode XR: Release without round-
robin and task names.
R: Release
S: Stack check
D: Debug
Table 2: Library naming conventions

Example
cfrtosndp.r68 is the library for a project using the near code model with debug and profiling support.

Library name Code model Libmode

osnxr.r68 near Release without round-robin and task

names

osnr.r68 near Release

osns.r68 near Stack check

osnd.r68 near Debug

osfxr.r68 far Release w/o round-robin and task names

osfr.r68 far Release

osfs.r68 far Stack check

osfd.r68 far Debug

Table 3: Prebuilt libraries

PPCF-1 15
 IAR PowerPac™ RTOS
16 Freescale ColdFire® Cores PPCF-1
Compiler specifics
Standard system libraries
PowerPac RTOS for Freescale ColdFire and IAR Embedded Workbench may be used with standard IAR Embedded
Workbench system libraries for most of all projects.
The heap management and file operation functions included in the standard system libraries are not reentrant and can
therefore not be used with PowerPac RTOS, if non thread safe-functions are used from different tasks.
For heap management, PowerPac RTOS delivers its own thread-safe functions which can be used. These functions are
described in PowerPac RTOS CPU independent manual.

PPCF-1 17
 IAR PowerPac™ RTOS
18 Freescale ColdFire® Cores PPCF-1
Stacks
This chapter describes the handling of stacks.

Task stack for Freescale ColdFire

All PowerPac RTOS tasks execute in supervisor mode using the supervisor stack pointer. The stack-size required is the
sum of the stack-size of all routines, the basic stack size, and the size used by exceptions.
The basic stack size is the size of memory required to store the CPU registers plus the stack size required by PowerPac
RTOS-routines.
For the Freescale ColdFire CPU, the 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. We recommend at least 256
bytes stack as a start.

System stack for Freescale ColdFire

The PowerPac RTOS system and the scheduler executes in supervisor mode. The minimum system stack size required
by PowerPac RTOS is about 136 bytes (stack check & profiling build). However, the system stack is also used by the
application before multitasking is started (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.

Interrupt stack for Freescale ColdFire

If a normal hardware exception occurs, the ColdFire CPU uses the current stack as interrupt stack. Make sure that your
stacks are big enough to have place for the interrupt stack data.

PPCF-1 19
 IAR PowerPac™ RTOS
20 Freescale ColdFire® Cores PPCF-1
Interrupts
This chapter describes the handling of interrupts.

The Freescale ColdFire core comes with a built in vectored interrupt controller which supports up to 57 separate
interrupt sources. The real number of interrupt sources depends on the specific target CPU.

What happens if an interrupt occurs

● The CPU-core receives an interrupt request from the interrupt controller.
● As soon as the interrupts are enabled, the interrupt is executed.
● The CPU enters supervisor mode and fetches an 8-bit vector from the interrupt controller.
● The CPU pushes the status register, the vector number and the return address onto the current stack.
● The CPU jumps to the vector address.
● The interrupt handler is processed.
● The interrupt handler ends with a “return from interrupt” instruction.
● The CPU switches back to the mode which was active before the exception was called.
● The CPU restores both the status register and return address from the stack and continues executing the interrupted
function.

Defining interrupt handlers in C

Interrupt handlers for ColdFire are written as normal C-functions which do not take parameters and do not return any
value.
Example
A simple interrupt routine:

void OS_ISR_TickHandler(void) {
PIT0_PMR |= PIT_PCSR_PIF; /* reset Timer interrupt flag */
OS_HandleTick();
}

Interrupt vector table

After reset, the Freescale ColdFire CPU uses an initial interrupt vector table which is located in ROM at address 0x00.
The interrupt vector table contains the address for the main stack and addresses for all exceptions.
The interrupt vector table is located in the C source code file RTOSINIT_*.c located in the device-specific subfolder.
Only interrupt handler function addresses for fast interrupts have to be inserted manually in the vector table. For all
other interrupts there is a interrupt handler table in RAM. This allows to enable variable interrupt handler installation
with OS_EnableISR()/OS_DisableISR().

Fast interrupts with Freescale ColdFire

Instead of disabling interrupts when PowerPac RTOS performs atomic operations, the interrupt level of the CPU is set
to 5. Therefore, all interrupt priorities higher than 5 can still be processed. Note that a higher priority number defines
a higher priority. All interrupts with priority level from 5 to 7 are never disabled.
These interrupts are named Fast interrupts. You must not execute any PowerPac RTOS function from within a fast
interrupt function.

PPCF-1 21
 Interrupt priorities
Due to the introduction of fast interrupts, interrupt priorities useable for interrupts using PowerPac RTOS API
functions are limited.
● Any interrupt handler using PowerPac RTOS API functions has to execute with interrupt priorities from 0 to 4.
● Any Fast interrupt (running at priorities from 5 to 7) must not call any PowerPac RTOS API function. Even
OS_EnterInterrupt() and OS_LeaveInterrupt() must not be called.

Note:The priority limit between PowerPac RTOS interrupts and Fast interrupts is fixed to 5 and can only be changed
by recompiling the PowerPac RTOS libraries.

Interrupt handling with vectored interrupt controller

For ColdFire, which has a built in vectored interrupt controller, PowerPac RTOS delivers additional functions to install
and set up interrupt handler functions.
To handle interrupts with the vectored interrupt controller, PowerPac RTOS offers the following functions:

OS_EnableISR(): Install an interrupt handler

Description
When a ColdFire CPU with an interrupt controller is used, OS_EnableSR() is used for installing a specific interrupt
vector.
Prototype
OS_ISR_HANDLER* OS_EnableISR (int ISRIndex,
OS_ISR_HANDLER * pISRHandler,
int Prio);
Parameter Description
ISRIndex Index of the interrupt source, normally the interrupt vector number.
pISRHandler Address of the interrupt handler function.
Prio Interrupt priority.
Table 4: OS_EnableISR () parameter list

Return value
The address of the previous installed interrupt function, which was installed at the previous vector number address.
Additional information
This function installs the interrupt vector and modifies the priority and automatically enables the interrupt in the
interrupt controller by setting the interrupt mask.

OS_DisableISR(): Disable specific interrupt

Description
OS_DisableISR() is used to disable the acceptance of a specific interrupt source.

Prototype
Ovoid OS_DisableISR(int ISRIndex);
Parameter Description
ISRIndex Index of the interrupt source which should be disabled.
Table 5: OS_DisableISR () parameter list

Additional information
This function disables the interrupt inside the interrupt controller. The function does not disable the interrupt of any
peripherals. This has to be done elsewhere.

IAR PowerPac™ RTOS

22 Freescale ColdFire® Cores PPCF-1
 Interrupts

High-priority non-maskable exceptions

High-priority non-maskable exceptions with non configurable priority like Reset, NMI and HardFault can not be used
with PowerPac RTOS functions. These exceptions are never disabled by PowerPac RTOS. Never call any PowerPac
RTOS function from an exception handler of one of these exceptions.

PPCF-1 23
 IAR PowerPac™ RTOS
24 Freescale ColdFire® Cores PPCF-1
Technical data
This chapter includes information about the memory requirements of PowerPac RTOS.

Memory requirements
These values are neither precise nor guaranteed but they give you a good idea of the memory-requirements. They vary
depending on the current version of PowerPac RTOS. The kernel itself has a minimum ROM size requirement of about
1.700 bytes.
In the table below, you can find the minimum RAM size for PowerPac RTOS resources for a release build. Note that
sizes depend on the selected PowerPac RTOS library mode.

PowerPac RTOS resource RAM [bytes]

Task control block 32

Resource semaphore 8

Counting semaphore 4

Mailbox 20

Software timer 20
Table 6: Memory requirements

PPCF-1 25
 IAR PowerPac™ RTOS
26 Freescale ColdFire® Cores PPCF-1
Files shipped with PowerPac RTOS
Use this chapter as template for all following chapters.

The following table gives an overview about all PowerPac RTOS related deliverables:

Directory File Explanation

.\Doc *.pdf Generic API and target-specific documentation.

.\BoardSupport Start.* Example workspaces and project files for IAR Embedded
Workbench, including CPU-specific hardware routines for
various CPUs and starter boards.

.\RTOS\Inc RTOS.h Include file for PowerPac RTOS, to be included in every C-

file using PowerPac RTOS functions.

.\RTOS\Src os*.r68 PowerPac RTOS libraries.

.\RTOS\Example *.c Example programs to serve as a start.

.\RTOS\Example OS_Error.c PowerPac RTOS runtime error handler used in stack check
or debug builds.
Table 7: Files shipped with PowerPac RTOS

PPCF-1 27
 IAR PowerPac™ RTOS
28 Freescale ColdFire® Cores PPCF-1
Index System stack. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

T
trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

C V
copyright notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
version, IAR Embedded Workbench . . . . . . . . . . . . . . . . . . . . . 2

D
disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
document conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

E
edition, of this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

G
guidelines, reading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

I
Interrupt priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Interrupt stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Interrupt vector table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

M
Memory models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Memory requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

O
OS_DisableISR() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
OS_EnableISR() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

P
part number, of this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
publication date, of this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

R
reading guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
registered trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

S
Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Syntax, conventions used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
System libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

PPCF-1 29