embOS

Real-Time
Operating System

CPU & Compiler

specifics for Cortex M
using IAR Embedded
Workbench

Document: UM01014
Software version 4.34
Revision: 0
Date: March 27, 2017

A product of SEGGER Microcontroller GmbH & Co. KG

www.segger.com
2

Disclaimer
Specifications written in this document are believed to be accurate, but are not guar-
anteed to be entirely free of error. The information in this manual is subject to
change for functional or performance improvements without notice. Please make sure
your manual is the latest edition. While the information herein is assumed to be
accurate, SEGGER Microcontroller GmbH & Co. KG (SEGGER) assumes no responsibil-
ity for any errors or omissions. SEGGER makes and you receive no warranties or con-
ditions, express, implied, statutory or in any communication with you. SEGGER
specifically disclaims any implied warranty of merchantability or fitness for a particu-
lar purpose.
Copyright notice
You may not extract portions of this manual or modify the PDF file in any way without
the prior written permission of SEGGER. 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.
© 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG, Hilden / Germany

Trademarks
Names mentioned in this manual may be trademarks of their respective companies.
Brand and product names are trademarks or registered trademarks of their respec-
tive holders.
Contact address
SEGGER Microcontroller GmbH & Co. KG
In den Weiden 11
D-40721 Hilden
Germany
Tel.+49 2103-2878-0
Fax.+49 2103-2878-28
E-mail: [email protected]
Internet: http://www.segger.com

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 3

Manual versions
This manual describes the current software version. If any error occurs, inform us
and we will try to assist you as soon as possible.
Contact us for further information on topics or routines not yet specified.
Print date: March 27, 2017

Software Manual Date By Description

4.34 0 170327 TS Chapter "Compiler specifics" updated.
4.30 0 161213 MC New software version.
4.26 0 161027 RH Chapters "Using embOS" and "embOS C-Spy Plugin" updated.
Chapters "VFP support", "CPU and compiler specifics", and
4.22 0 160531 MC
"embOS C-Spy Plugin" updated.
4.16 0 160122 MC New software version.
4.14 0 151222 MC New software version.
4.12a 0 150917 TS New software version.
4.10 0 150505 TS Chapter "Compiler specifics" updated.
4.06b 0 150330 TS New software version.
Typos corrected.
4.06a 0 150317 TS
New software version.
4.04a 0 150109 SC New generic embOS sources V4.04a.
4.02a 0 140918 TS New generic embOS sources V4.02a.
4.02 0 140819 TS New generic embOS sources V4.02.
4.00 0 140606 TS New generic embOS sources V4.00.
New generic embOS sources V3.90
3.90 0 140228 AW
Updated start projects for EWARM V7.10.
3.88g 0 131104 TS New generic embOS sources V3.88g.
3.88c 0 130813 TS New generic embOS sources V3.88c.
New generic embOS sources V3.88b.
AW Chapter 4, "Thread safe system libraries with IAR compiler
3.88b 0 130528
/TS V6.4 or newer" corrected. One required linker parameter was
missing in previous description.
New generic embOS sources V3.86n.
Chapter 4, "Thread safe system libraries with IAR compiler
3.86n 0 121210 AW
V6.4 or newer" added to describe the procedure to activate
thread safe library support with newer IAR compiler
3.86l 0 121126 TS Software: New embOS sources V3.86l
3.86g 0 120806 AW Software: New embOS sources V3.86g
Software: New embOS sources V3.86f
3.86f 0 120726 AW
Task events are 32bits wide for Cortex-M.
Software: New embOS sources V3.86e
3.86e 0 120708 AW
Modified hard fault handler added to RTOSInit.
Software: New embOS sources V3.86d
3.86d 0 120510 AW
OS_ExtendTaskContext_TLS_VFP() corrected.
Software: Scheduler for CortexM4 with VFP corrected.
Chapter 4: New functions to save and restore VFP context of
3.84c1 1 120203 AW Cortex M4 in ISR handler:
OS_VFP_Save()
OS_VFP_Restore()
3.84c 0 120117 TS Software version updated.
Software: New scheduler uses main stack for OS_Idle().
Chapter 5: Stacks, system stack description updated.
New Chapter 6.8.4 and 6.8.5: Interrupt peripheral identifier
3.84.1 0 111103 AW and priority values used with embOS described more in detail
Chapter 7: Interrupt controller setup using CMSIS described
more in detail. New chapter 7.7.1 describes Differences
between embOS functions and CMSIS functions
Chapter 3.2.1: New libraries with VFPv4 support added.
Chapter 4.3, 4.4: Support for VFPv4 added,
3.84 0 111027 AW OS_ExtendTaskContext_TLS()
OS_ExtendTaskContext_TLS_VFP()
OS_ExtendTaskContext_VFP()
3.82u 0 110701 AW Chapter CMSIS with IAR EWARM V6 added.
3.82s 0 110323 TS New library mode DPL added.
3.82m 0 101117 AW Thread local storage for new IAR workbench V6

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
4

Software Manual Date By Description

Library names updated for new IAR workbench V6
3.82l 0 101027 AW
Thread safe library support modified for IAR workbench V6
3.82h 0 100722 TS embOS CM3 and embOs CM0 manual merged
3.82a 1 100701 AW Chapter Stacks: Task stack size corrected.
3.82a 0 091026 TS First version

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 5

About this document

Assumptions
This document assumes that you already have a solid knowledge of the following:
• The software tools used for building your application (assembler, linker, C com-
piler)
• The C programming language
• The target processor
• DOS command line
If you feel that your knowledge of C is not sufficient, we recommend The C Program-
ming Language by Kernighan and Richie (ISBN 0-13-1103628), which describes the
standard in C-programming and, in newer editions, also covers the ANSI C standard.
How to use this manual
This manual explains all the functions and macros that the product offers. It assumes
you have a working knowledge of the C language. Knowledge of assembly program-
ming is not required.
Typographic conventions for syntax
This manual uses the following typographic conventions:

Style Used for

Body Body text.

Text that you enter at the command-prompt or that appears on

Keyword
the display (that is system functions, file- or pathnames).

Parameter Parameters in API functions.

Sample Sample code in program examples.
Sample comment Comments in program examples.

Reference to chapters, sections, tables and figures or other docu-

Reference
ments.

GUIElement Buttons, dialog boxes, menu names, menu commands.

Emphasis Very important sections.

Table 1.1: Typographic conventions

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
6

SEGGER Microcontroller GmbH & Co. KG develops

and distributes software development tools and ANSI C
software components (middleware) for embedded sys-
tems in several industries such as telecom, medical
technology, consumer electronics, automotive industry
and industrial automation.
SEGGER’s intention is to cut software development time
for embedded applications by offering compact flexible and easy to use middleware,
allowing developers to concentrate on their application.
Our most popular products are emWin, a universal graphic software package for embed-
ded applications, and embOS, a small yet efficient real-time kernel. emWin, written
entirely in ANSI C, can easily be used on any CPU and most any display. It is comple-
mented by the available PC tools: Bitmap Converter, Font Converter, Simulator and
Viewer. embOS supports most 8/16/32-bit CPUs. Its small memory footprint makes it
suitable for single-chip applications.
Apart from its main focus on software tools, SEGGER develops and produces programming
tools for flash micro controllers, as well as J-Link, a JTAG emulator to assist in develop-
ment, debugging and production, which has rapidly become the industry standard for
debug access to ARM cores.

Corporate Office: United States Office:

http://www.segger.com http://www.segger-us.com

EMBEDDED SOFTWARE SEGGER TOOLS

(Middleware)
emWin Flasher
Graphics software and GUI Flash programmer
emWin is designed to provide an effi- Flash Programming tool primarily for micro con-
cient, processor- and display control- trollers.
ler-independent graphical user
interface (GUI) for any application that J-Link
operates with a graphical display. JTAG emulator for ARM cores
USB driven JTAG interface for ARM cores.
embOS
Real Time Operating System J-Trace
embOS is an RTOS designed to offer JTAG emulator with trace
the benefits of a complete multitasking USB driven JTAG interface for ARM cores with
system for hard real time applications Trace memory. supporting the ARM ETM (Embed-
with minimal resources. ded Trace Macrocell).

embOS/IP J-Link / J-Trace Related Software

TCP/IP stack Add-on software to be used with SEGGER’s indus-
embOS/IP a high-performance TCP/IP try standard JTAG emulator, this includes flash
stack that has been optimized for programming software and flash breakpoints.
speed, versatility and a small memory
footprint.

emFile
File system
emFile is an embedded file system with
FAT12, FAT16 and FAT32 support. Vari-
ous Device drivers, e.g. for NAND and
NOR flashes, SD/MMC and Compact-
Flash cards, are available.

USB-Stack
USB device/host stack
A USB stack designed to work on any
embedded system with a USB control-
ler. Bulk communication and most stan-
dard device classes are supported.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 7

Table of Contents

1 Using embOS...................................................................................................................9
1.1 Installation ............................................................................................. 10
1.2 First steps .............................................................................................. 11
1.3 The example application OS_StartLEDBlink.c ............................................... 12
1.4 Stepping through the sample application .................................................... 13

2 Build your own application .............................................................................................17

2.1 Introduction............................................................................................ 18
2.2 Required files for an embOS...................................................................... 18
2.3 Change library mode ................................................................................ 18
2.4 Select another CPU .................................................................................. 18

3 Libraries .........................................................................................................................21
3.1 Naming conventions for prebuilt libraries .................................................... 22

4 CPU and compiler specifics ...........................................................................................23

4.1 Standard system libraries ......................................................................... 24
4.2 Thread-safe system libraries ..................................................................... 25
4.2.1 Thread safe system libraries with IAR compiler V6.x ..................................... 25
4.2.2 Thread safe system libraries with IAR compiler V6.4 or newer........................ 25
4.2.3 Thread safe system libraries with IAR compiler V8.x ..................................... 26
4.3 Thread-Local Storage TLS ......................................................................... 27
4.3.1 OS_ExtendTaskContext_TLS() ................................................................... 27

5 Stacks ............................................................................................................................29
5.1 Task stack for Cortex-M............................................................................ 30
5.2 System stack for Cortex-M........................................................................ 30
5.3 Interrupt stack for Cortex-M...................................................................... 30

6 Interrupts........................................................................................................................31
6.1 What happens when an interrupt occurs? .................................................... 32
6.2 Defining interrupt handlers in C ................................................................. 32
6.3 Interrupt vector table............................................................................... 32
6.4 Interrupt-stack switching .......................................................................... 33
6.5 Zero latency interrupts ............................................................................. 33
6.5.1 Zero latency interrupts with Cortex-M ........................................................ 33
6.6 Interrupt priorities ................................................................................... 33
6.6.1 Interrupt priorities with Cortex-M cores ...................................................... 33
6.6.2 Priority of the embOS scheduler ................................................................ 34
6.6.3 Priority of the embOS system timer............................................................ 34
6.6.4 Priority of embOS software timers.............................................................. 34
6.6.5 Priority of application interrupts for Cortex M3 / M4 / M7 core........................ 34
6.7 Interrupt nesting ..................................................................................... 34
6.7.1 OS_EnterInterrupt() ................................................................................ 35
6.7.2 OS_EnterNestableInterrupt()..................................................................... 35
6.7.3 Required embOS system interrupt handlers................................................. 35
6.8 Interrupt handling with vectored interrupt controller..................................... 36
6.8.1 OS_ARM_EnableISR(): Enable specific interrupt........................................... 36
6.8.2 OS_ARM_DisableISR(): Disable specific interrupt ......................................... 37

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
8

6.8.3 OS_ARM_ISRSetPrio(): Set priority of specific interrupt ................................ 37

7 CMSIS............................................................................................................................39
7.1 The generic CMSIS start project ................................................................ 40
7.2 Device specific files needed for embOS with CMSIS...................................... 40
7.3 Device specific functions/variables needed for embOS with CMSIS ................. 40
7.4 CMSIS generic functions needed for embOS with CMSIS............................... 41
7.5 Customizing the embOS CMSIS generic start project.................................... 41
7.6 Adding CMSIS to other embOS start projects .............................................. 42
7.6.1 Differences between embOS projects and CMSIS ......................................... 42
7.6.1.1 Different peripheral ID numbers ................................................................ 42
7.6.1.2 Different interrupt priority values .............................................................. 42
7.7 Interrupt and exception handling with CMSIS.............................................. 44
7.8 Enable and disable interrupts .................................................................... 44
7.9 Setting the Interrupt priority..................................................................... 44

8 VFP support ...................................................................................................................45

8.1 Vector Floating Point support VFPv4........................................................... 46
8.1.1 Using embOS libraries with VFP support ..................................................... 46
8.1.2 Using the VFP in interrupt service routines.................................................. 46

9 RTT and SystemView ....................................................................................................47

9.1 SEGGER Real Time Transfer...................................................................... 48
9.1.1 Shipped files related to SEGGER RTT.......................................................... 48
9.2 SEGGER SystemView ............................................................................... 49
9.2.1 Shipped files related to SEGGER SystemView .............................................. 49

10 embOS C-Spy plug-in ..................................................................................................51

10.1 Overview ............................................................................................... 52
10.1.1 embOS C-Spy plug-in .............................................................................. 52
10.1.2 Requirements ......................................................................................... 52
10.2 Installation ............................................................................................. 53
10.3 Configuration.......................................................................................... 54
10.4 Using the embOS C-Spy plug-in ................................................................ 55
10.4.1 Tasks .................................................................................................... 56
10.4.1.1 Task sensitivity ....................................................................................... 56
10.4.1.2 State of suspended tasks ......................................................................... 57
10.4.1.3 Call stack with embOS libraries ................................................................. 58
10.4.2 Mailboxes............................................................................................... 59
10.4.3 Timers ................................................................................................... 59
10.4.4 Resource semaphores .............................................................................. 60
10.4.5 System information ................................................................................. 60
10.4.6 Settings ................................................................................................. 60
10.4.7 About .................................................................................................... 61

11 Technical data..............................................................................................................63
11.1 Memory requirements.............................................................................. 64

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 9

Chapter 1

Using embOS

This chapter describes how to start with and use embOS. You should follow these
steps to become familiar with embOS.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
10 1 Using embOS

1.1 Installation
embOS is shipped as a zip-file in electronic form.
To install it, proceed as follows:
Extract the zip-file to any folder of your choice, preserving the directory structure of
this file. Keep all files in their respective sub directories. Make sure the files are not
read only after copying.
Assuming that you are using an IDE to develop your application, no further installa-
tion steps are required. You will find a lot of prepared sample start projects, which
you should use and modify to write your application. So follow the instructions of
section First steps.
You should do this even if you do not intend to use the IDE for your application devel-
opment to become familiar with embOS.
If you do not or do not want to work with the IDE, you should: Copy either all or only
the library-file that you need to your work-directory. The advantage is that when
switching to an updated version of embOS later in a project, you do not affect older
projects that use embOS, too. embOS does in no way rely on an IDE, it may be used
without the IDE using batch files or a make utility without any problem.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 11

1.2 First steps

After installation of embOS you can create your first multitasking application. You
have received several ready to go sample start workspaces and projects and every
other files needed in the subfolder Start. It is a good idea to use one of them as a
starting point for all of your applications. The subfolder BoardSupport contains the
workspaces and projects which are located in manufacturer- and CPU-specific sub-
folders.
To start with, you may use any project from BoardSupport subfolder:
To get your new application running, you should proceed as follows:
• Create a work directory for your application, for example c:\work.
• Copy the whole folder Start which is part of your embOS distribution into your
work directory.
• Clear the read-only attribute of all files in the new Start folder.
• Open one sample workspace/project in
Start\BoardSupport\<DeviceManufactor>\<CPU>
with your IDE (for example, by double clicking it).
• Build the project. It should be built without any error or warning messages.
After generating the project of your choice, the screen should look like this:

For additional information you should open the ReadMe.txt file which is part of every
specific project. The ReadMe file describes the different configurations of the project
and gives additional information about specific hardware settings of the supported
eval boards, if required.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
12 1 Using embOS

1.3 The example application OS_StartLEDBlink.c

The following is a printout of the example application OS_StartLEDBlink.c. It is a
good starting point for your application. (Note that the file actually shipped with your
port of embOS may look slightly different from this one.)
What happens is easy to see:
After initialization of embOS; 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.

/*********************************************************************
* SEGGER Microcontroller GmbH & Co. KG *
* The Embedded Experts *
**********************************************************************
File : OS_StartLEDBlink.c
Purpose : embOS sample program running two simple tasks, each toggling
a LED of the target hardware (as configured in BSP.c).
--------- END-OF-HEADER ----------------------------------------------
*/

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

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

static 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_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;
}

/****** End Of File *************************************************/

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 13

1.4 Stepping through the sample application

When starting the debugger, you will see the main() function (see example screen-
shot below). The main() function appears as long as project option Run to main is
selected, which it is enabled by default. Now you can step through the program.
OS_IncDI() initially disables interrupts.
OS_InitKern() is part of the embOS library and written in assembler; you can there-
fore only step into it in disassembly mode. It initializes the relevant OS variables.
OS_InitHW() is part of RTOSInit_*.c and therefore part of your application. Its pri-
mary purpose is to initialize the hardware required to generate the system tick inter-
rupt for embOS. Step through it to see what is done.
OS_Start() should be the last line in main(), because it starts multitasking and does
not return.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
14 1 Using embOS

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

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 15

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

Continue to step through the program, there is no other task ready for execution.
embOS will therefore start the idle-loop, which is an endless loop always executed if
there is nothing else to do (no task is ready, no interrupt routine or timer executing).
You will arrive there 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
stepping 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.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
16 1 Using embOS

As can be seen by the value of embOS timer variable OS_Global.Time, shown in the
Watch window, HPTask continues operation after expiration of the 50 system tick
delay.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 17

Chapter 2

Build your own application

This chapter provides all information to set up your own embOS project.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
18 2 Build your own application

2.1 Introduction
To build your own application, you should always start with one of the supplied sam-
ple workspaces and projects. Therefore, select an embOS workspace as described in
chapter First steps and modify the project to fit your needs. Using an embOS start
project as starting point has the advantage that all necessary files are included and
all settings for the project are already done.

2.2 Required files for an embOS

To build an application using embOS, the following files from your embOS distribution
are required and have to be included in your project:
• RTOS.h from subfolder Inc\.
This header file declares all embOS API functions and data types and has to be
included in any source file using embOS functions.
• RTOSInit_*.c from one target specific BoardSupport\<Manufac-
turer>\<MCU>\ subfolder.
It contains hardware-dependent initialization code for embOS. It initializes the
system timer interrupt and optional communication for embOSView via UART or
JTAG.
• One embOS library from the subfolder Lib\.
• OS_Error.c from one target specific subfolder BoardSupport\<Manufac-
turer>\<MCU>\. The error handler is used if any debug library is used in your
project.
• Additional CPU and compiler specific files 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-initialized variables are initialized with zero, according to C stan-
dard. This is required for some embOS internal variables.
Your main() function has to initialize embOS by a call of OS_InitKern() and
OS_InitHW() prior any other embOS functions are called.
You should then modify or replace the OS_Start_LEDBlink.c source file in the sub-
folder Application\.

2.3 Change library mode

For your application you might want to choose another library. For debugging and
program development you should use an embOS debug library. For your final applica-
tion you may wish to use an embOS release library or a stack check library.
Therefore you have to select or replace the embOS library in your project or target:
• If your selected library is already available in your project, just select the appro-
priate configuration.
• To add a library, you may add the library to the existing Lib group. Exclude all
other libraries from your build, delete unused libraries or remove them from the
configuration.
• Check and set the appropriate OS_LIBMODE_* define as preprocessor option and/
or modify the OS_Config.h file accordingly.

2.4 Select another CPU

embOS contains CPU-specific code for various CPUs. Manufacturer- and CPU-specific
sample start workspaces and projects are located in the subfolders of the BoardSup-
port folder. To select a CPU which is already supported, just select the appropriate
workspace from a CPU-specific folder.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 19

If your CPU is currently not supported, examine all RTOSInit.c files in the CPU-spe-
cific subfolders and select one which almost fits your CPU. You may have to modify
OS_InitHW(), OS_COM_Init(), the interrupt service routines for embOS system timer
tick and communication to embOSView and the low level initialization.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
20 2 Build your own application

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 21

Chapter 3

Libraries

This chapter describes the available embOS libraries.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
22 3 Libraries

3.1 Naming conventions for prebuilt libraries

embOS for Cortex-M and IAR is shipped with different prebuilt libraries with different
combinations of the following features:
• Instruction set architecture - Arch
• CPU mode - CpuMode
• Byte order - ByteOrder
• Library mode - LibMode
The libraries are named as follows:
os<Arch>_<CpuMode><ByteOrder><VFP_support>_<Libmode>.a

Parameter Meaning Values

6m: Cortex M0 / M0+ / M1
Arch Specifies the CPU variant
7m: Cortex M3 / M4 / M4F / M7 / M7F
CpuMode Specifies the CPU mode. t: Always thumb
b: Big endian
ByteOrder
l: Little endian
_: No hardware VFP support
VFP_support
v: VFPv4 support (Cortex M4F / M7F)
LibMode Specifies the library mode xr: Extreme Release
r: Release
s: Stack check
sp: Stack check + profiling
d: Debug
dp: Debug + profiling
dpl: Debug + profiling + low optimiza-
tion
dt: Debug + profiling + trace
Table 3.1: Naming conventions for prebuild libraries

Example
os6m_tl__dp.a is the library for a project using a Cortex-M0 core, thumb mode, little
endian mode with debug and profiling support.
os7m_tlv_dp.a is the library for a project using a Cortex-M4F core, thumb mode, lit-
tle endian mode and VFPv4 floating point unit with debug and profiling support.
Note:
The libraries for Cortex-M3 can also be used for Cortex-M4 and Cortex-M4F targets as
long as the VFP is not used in Cortex-M4F.
When VFPv4 is selected in the project options, the IAR startup code automatically
adds code to enable the VFP after reset.
When using your own startup code, please ensure the VPF is enabled or diasabled
according the project settings.
Using the VFP requires libraries with VFP support: os7m_tlv_xx.
All libraries can be used with IAR Embedded Workbench for ARM V6.x and V7.x.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 23

Chapter 4

CPU and compiler specifics

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
24 4 CPU and compiler specifics

4.1 Standard system libraries

embOS for Cortex-M and IAR may be used with IAR standard libraries for most of all
projects.
If non thread-safe functions are used from different tasks, embOS functions may be
used to encapsulate these functions and guarantee mutual exclusion.
The system libraries from the IAR Embedded Workbench V6 come with built-in hook
functions, which enable thread safe calls of all system functions automatically when
supported by the operating system.
embOS compiled for IAR Embedded Workbench is prepared to use these hook func-
tions. Adding one or two source code modules which are delivered with embOS acti-
vates the automatic thread locking functionality of the new IAR DLib.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 25

4.2 Thread-safe system libraries

Using embOS with C++ projects and file operations or just normal call of heap man-
agement functions may require thread-safe system libraries if these functions are
called from different tasks. Thread-safe system libraries require some locking mech-
anism which is RTOS specific.
To activate thread safe system library functionality, one or two special source mod-
ules delivered with embOS have to be included in the project.
How to use this locking mechanisms depends on the IAR compiler version
• IAR compiler V8 or newer:
The new runtime libraries of the IAR compiler / workbench implement hook func-
tions for thread safe usage of system functions which can be used and supported
with embOS. The locking has to be initialized once by a call of the embOS
function OS_INIT_SYS_LOCKS().
• IAR compiler V6 and V7:
The new runtime libraries of the IAR compiler / workbench implement hook func-
tions for thread safe usage of system functions which can be used and supported
with embOS.
• IAR compiler version V5.x:
System libraries delivered with compiler version V5 already contain a locking
mechanism which may be used with embOS if required. The locking has to be ini-
tialized once by a call of the embOS function OS_INIT_SYS_LOCKS().

4.2.1 Thread safe system libraries with IAR compiler V6.x

To enable the automatic thread safe locking functions, the source module xmtx.c
which is included in every CPU specific Setup folder of the embOS shipment has to be
included in the project.
To support thread safe file i/o functionality, the source module xmtx2.c has to be
added.
The embOS libraries compiled for and with the new IAR compiler / workbench V6
come with all code required to automatically handle the thread safe system libraries
when the source module xmtx.c or xmtx2.c from the embOS shipment are included
in the project.
Note that thread safe system library and file i/o support is required only, when non
thread safe functions are called from multiple tasks, or thread local storage is used in
multiple tasks.

4.2.2 Thread safe system libraries with IAR compiler V6.4 or

newer
With IAR compiler version V6.4 or newer, the thread safe system library hook func-
tions delivered with embOS are NOT automatically linked in, even if they are included
in the project.
To enable the automatic thread safe locking functions, the project options for the
linker have to be setup to replace the default locking functions from the system
libraries by the functions delivered with embOS.
To enable thread safe system library support, include the two files xmtx.c and
xmtx2.c in the project.
Activate the checkbox “Use command line options” in the dialog
Project -> Options -> Linker ->Extra options
then, in the “Command line options:” field, add the following lines:
--redirect __iar_Locksyslock=__iar_Locksyslock_mtx
--redirect __iar_Unlocksyslock=__iar_Unlocksyslock_mtx
--redirect __iar_Lockfilelock=__iar_Lockfilelock_mtx
--redirect __iar_Unlockfilelock=__iar_Unlockfilelock_mtx
--keep __iar_Locksyslock_mtx

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
26 4 CPU and compiler specifics

4.2.3 Thread safe system libraries with IAR compiler V8.x

To enable the automatic thread safe locking functions, the source module xmtx.c
which is included in every CPU specific Setup folder of the embOS shipment has to be
included in the project and the function OS_INIT_SYS_LOCKS() must be called. Addi-
tionally the option "Enable thread support in library" must be set in project
settings->Library configuration.
To support thread safe file i/o functionality, the source module xmtx2.c has to be
added.
The embOS libraries compiled for and with the new IAR compiler / workbench V8
come with all code required to automatically handle the thread safe system libraries
when the source module xmtx.c or xmtx2.c from the embOS shipment are included
in the project.
Note that thread safe system library and file i/o support is required only, when non
thread safe functions are called from multiple tasks, or thread local storage is used in
multiple tasks.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 27

4.3 Thread-Local Storage TLS

The dlib of EWARM V6 supports usage of thread-local storage. Several library objects
and functions need local variables which have to be unique to a thread.
Thread-local storage will be required when these functions are called from multiple
threads.
embOS for EWARM V6 is prepared to support the tread-local storage, but does not
use it per default. This has the advantage of no additional overhead as long as
thread-local storage is not needed by the application.
The embOS implementation of thread-local storage allows activation of TLS sepa-
rately for every task.
Only tasks that call functions using TLS need to activate the TLS by calling an initial-
ization function when the task is started.
The IAR runtime environment allocates the TLS memory on the heap. Using TLS with
multiple tasks shall therefore use thread safe system library functionality which is
automatically enabled when the xmtx.c module from the embOS distribution is added
to the project.
Library objects that need thread-local storage when used in multiple tasks are:
• error functions -- errno, strerror.
• locale functions -- localeconv, setlocale.
• time functions -- asctime, localtime, gmtime, mktime.
• multibyte functions -- mbrlen, mbrtowc, mbsrtowc, mbtowc, wcrtomb, wcsrtomb,
wctomb.
• rand functions -- rand, srand.
• etc functions -- atexit, strtok.
• C++ exception engine.

4.3.1 OS_ExtendTaskContext_TLS()
Description
OS_ExtendTaskContext_TLS() may be called from a task to initialize and use
Thread-local storage.
Prototype
void OS_ExtendTaskContext_TLS (void);

Additional Information
OS_ExtendTaskContext_TLS() shall be the first function called from a task when TLS
should be used in the specific task.
The function must not be called multiple times from one task.
The thread-local storage is allocated on the heap. To ensure thread safe heap man-
agement, the thread safe system library functionality shall also be enabled when
using TLS.
Thread safe system library calls are automatically enabled when the source module
xmtx.c which is delivered with embOS in the CPU specific Setup folders is included in
the project.
The function is available in embOS for EWARM6 only.
Example
The following printout shows the sample application OS_ThreadLocalStorage.c,
which demonstrates the usage of task specific TLS in an application.
The sample program is included in the CPU specific Application folder, which contains
all sample applications for embOS.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
28 4 CPU and compiler specifics

/*********************************************************************
* SEGGER Microcontroller GmbH & Co. KG *
* The Embedded Experts *
**********************************************************************
File : OS_ThreadLocalStorage.c
Purpose : embOS sample application to demonstrate the usage of TLS.
TLS support is CPU and compiler specific and may not be
implemented in all OS ports.
-------- END-OF-HEADER ---------------------------------------------
*/

#include "RTOS.h"
#include <errno.h>

static OS_STACKPTR int StackHP[128], StackLP[128], StackMP[128];

static OS_TASK TCBHP, TCBLP, TCBMP;

static void HPTask(void) {

OS_ExtendTaskContext_TLS(); // Initialize TLS for this task
while (errno != 0) {
// errno is local to this task, hence we should not arrive here
}
errno = 3; // Simulate a task specific error
while (1) {
OS_Delay (10);
while (errno != 3) {
// errno is local to this task, hence we should not arrive here
}
}
}

static void MPTask(void) {

OS_ExtendTaskContext_TLS(); // Initialize TLS for this task
while (errno != 0) {
// errno is local to this task, hence we should not arrive here
}
errno = 2; // Simulate a task specific error
while (1) {
OS_Delay (10);
while (errno != 2) {
// errno is local to this task, hence we should not arrive here
}
}
}

static void LPTask(void) { // This task does not use TLS

while (errno != 1) {
// errno is not local to this task so we expect the global value
// that was set in main(), hence we should not arrive here
}
while (1) {
OS_Delay (50);
}
}

/*********************************************************************
*
* main()
*
*********************************************************************/
int main(void) {
errno = 1; /* Simulate an error */
OS_InitKern(); /* Initialize OS */
OS_InitHW(); /* Initialize Hardware for OS */
/* You need to create at least one task before calling OS_Start() */
OS_CREATETASK(&TCBHP, "HP Task", HPTask, 100, StackHP);
OS_CREATETASK(&TCBMP, "MP Task", MPTask, 70, StackMP);
OS_CREATETASK(&TCBLP, "LP Task", LPTask, 50, StackLP);
OS_Start(); /* Start multitasking */
return 0;
}

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 29

Chapter 5

Stacks

This chapter describes how embOS uses the different stacks of the Cortex-M CPU.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
30 5 Stacks

5.1 Task stack for Cortex-M

Each task uses its individual stack. The stack pointer is initialized and set every time
a task is activated by the scheduler. The stack-size required for a task is the sum of
the stack-size of all routines, plus a 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 calling embOS-routines.
For the Cortex-M CPUs, this minimum basic task stack size is about 112 bytes.
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 one exception too. We recommend at least 256 bytes stack as a
start.

5.2 System stack for Cortex-M

The embOS system executes in thread mode, the scheduler executes in handler
mode. The minimum system stack size required by embOS is about 136 bytes (stack
check & profiling build). However, since the system stack is also used by the applica-
tion 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 the project settings. We recom-
mend a minimum stack size of 256 bytes for the CSTACK.

5.3 Interrupt stack for Cortex-M

If a normal hardware exception occurs, the Cortex-M core switches to handler mode
which uses the main stack pointer.
With embOS, the main stack pointer is initialized to use the CSTACK, which is defined
in the linker command file.
The main stack is also used as stack by the embOS scheduler and during idle times,
when no task is ready to run and OS_Idle() is executed.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 31

Chapter 6

Interrupts

The Cortex M core comes with a built-in vectored interrupt controller which supports
up to 240 separate interrupt sources. The real number of interrupt sources depends
on the specific target CPU.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
32 CHAPTER 6 Interrupts

6.1 What happens when an interrupt occurs?

• The CPU-core receives an interrupt request from the interrupt controller.
• As soon as the interrupts are enabled, the interrupt is accepted and 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 excep-
tion was called.
• The CPU restores the temporary registers and return address from the stack and
continues the interrupted function.

6.2 Defining interrupt handlers in C

Interrupt handlers for Cortex M cores are written as normal C-functions which do not
take parameters and do not return any value. Interrupt handler which call an embOS
function need a prolog and epilog function as described in the generic manual and in
the examples below.
Example
Simple interrupt routine:

static void _Systick(void) {

OS_EnterNestableInterrupt(); // Inform embOS that interrupt code is running
OS_HandleTick(); // May be interrupted by higher priority interrupts
OS_LeaveNestableInterrupt(); // Inform embOS that interrupt handler is left
}

6.3 Interrupt vector table

After Reset, the ARM Cortex M 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 handlers.
The interrupt vector table is located in a C source or assembly file 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 installa-
tion. The compile time switch OS_USE_VARINTTABLE is used to enable usage of a vec-
tor table in RAM.
To save RAM, the switch is set to zero per default in RTOSInit_*.c. It may be over-
written 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.
When using your own interrupt vector table, ensure that the addresses of the embOS
exception handlers OS_Exception() and OS_Systick() are included.
When the vector table is not located at address 0x00, the vector base register in the
NVIC controller has to be initialized to point to the vector table base address.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 33

6.4 Interrupt-stack switching

Since Cortex M core based controllers have two separate stack pointers, and embOS
runs the user application on the process stack, there is no need for explicit stack-
switching in an interrupt routine which runs on the main stack. The routines
OS_EnterIntStack() and OS_LeaveIntStack() are supplied for source code compat-
ibility to other processors only and have no functionality.

6.5 Zero latency interrupts

6.5.1 Zero latency interrupts with Cortex-M
Instead of disabling interrupts when embOS 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 numbers define a higher priority. All
interrupts with priority level from 0 to 127 are never disabled. These interrupts are
named zero latency interrupts. You must not execute any embOS function from
within a zero latency interrupt function.

6.6 Interrupt priorities

This section describes interrupt priorities supported by the CortexM CPU cores.
The priority is any number between 0 and 255 as seen by the CPU core. With embOS
and its own setup functions for the interrupt controller and priorities, there is no dif-
ference in the priority values regardless of the different preemption level of specific
devices.
Using the CMSIS functions to set up interrupt priorities requires different values for
the priorities. These values depend on the number of preemption levels of the spe-
cific chip. A description is found in the chapter CMSIS.

6.6.1 Interrupt priorities with Cortex-M cores

The Cortex M3 / M4 and M4F support up to 256 levels of programmable priority with
a maximum of 128 levels of preemption. Most Cortex M chips have fewer supported
levels, for example 8, 16, 32, and so on. The chip designer can customize the chip to
obtain the levels required. There is a minimum of 8 preemption levels. Every inter-
rupt with a higher preemption level may preempt any other interrupt handler running
on a lower preemption level. Interrupts with equal preemption level may not preempt
each other.
With introduction of Zero latency interrupts, interrupt priorities usable for interrupts
using embOS API functions are limited.
• Any interrupt handler using embOS API functions has to run with interrupt prior-
ities from 128 to 255. These embOS interrupt handlers have to start with
OS_EnterInterrupt() or OS_EnterNestableInterrupt() and have to end with
OS_LeaveInterrupt() or OS_LeaveNestableInterrupt().
• Any zero latency interrupt (running at priorities from 0 to 127) must not call any
embOS API function. Even OS_EnterInterrupt() and OS_LeaveInterrupt()
must not be called.
• Interrupt handlers running at low priorities (from 128 to 255) not calling any
embOS API function are allowed, but must not reenable interrupts! The priority
limit between embOS interrupts and zero latency interrupts is fixed at compile
time to 128 and can only be changed by recompiling the embOS libraries! This is
done for efficiency reasons. Basically the define OS_IPL_DI_DEFAULT in RTOS.h
and the RTOS.s file must be modified. There might be other modifications neces-
sary. Please contact the embOS support if you like to change this threshold.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
34 CHAPTER 6 Interrupts

6.6.2 Priority of the embOS scheduler

The embOS scheduler runs on the lowest interrupt priority. The scheduler may be
preempted by any other interrupt with higher preemption priority level. The applica-
tion interrupts shall run on higher preemption levels to ensure short reaction time.
During initialization, the priority of the embOS scheduler is set to 0x03 for Cortex M0
and to 0xFF for Cortex M3 / M4 and M4F, which is the lowest preemption priority
regardless of the number of preemption levels.

6.6.3 Priority of the embOS system timer

The embOS system timer runs on the second lowest preemption level. Thus, the
embOS timer may preempt the scheduler. Application interrupts which require fast
reaction should run on a higher preemption priority level.

6.6.4 Priority of embOS software timers

The embOS software timer callback functions are called from the scheduler and run
on the scheduler’s preemption priority level which is the lowest interrupt priority
level. To ensure short reaction time of other interrupts, other interrupts should run
on a higher preemption priority level and the software timer callback functions should
be as short as possible.

6.6.5 Priority of application interrupts for Cortex M3 / M4 / M7

core
Application interrupts using embOS functions may run on any priority level between
255 to 128. However, interrupts which require fast reaction should run on higher pri-
ority levels than the embOS scheduler and the embOS system timer to allow preemp-
tion of theses interrupt handlers. The interrupt handlers which require the fastest
reaction may run on higher priorities than 128, but must not call any embOS function
(See “Zero latency interrupts” on page 33.). We recommend that application inter-
rupts should run on a higher preemption level than the embOS scheduler, at least at
the second lowest preemption priority level.
As the number of preemption levels is chip specific, the second lowest preemption
priority varies depending on the chip. If the number of preemption levels is not docu-
mented, the second lowest preemption priority can be set as follows, using embOS
functions:

unsigned char Priority;

OS_ARM_ISRSetPrio(_ISR_ID, 0xFF); // Set to lowest level, ALL BITS set
Priority = OS_ARM_ISRSetPrio(_ID_TICK, 0xFF); // Read priority back
Priority -= 1; // Lower preemption level
OS_ARM_ISRSetPrio(_ISR_ID, Priority);

6.7 Interrupt nesting

The Cortex M CPU uses a priority controlled interrupt scheduling which allows nesting
of interrupts per default. Any interrupt or exception with a higher preemption priority
may interrupt an interrupt handler running on a lower preemption priority. An inter-
rupt handler calling embOS functions has to start with an embOS prolog function: it
informs embOS that an interrupt handler is running. For any interrupt handler, the
user may decide individually whether this interrupt handler may be preempted or not
by choosing the prolog function.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 35

6.7.1 OS_EnterInterrupt()
Description
OS_EnterInterrupt(), disables nesting
Prototype
void OS_EnterInterrupt (void);

Additional Information
OS_EnterInterrupt() has to be used as prolog function, when the interrupt handler
should not be preempted by any other interrupt handler that runs on a priority below
the zero latency interrupt priority. An interrupt handler that starts with
OS_EnterInterrupt() has to end with the epilog function OS_LeaveInterrupt().
Example
Interrupt-routine that can not be preempted by other interrupts.

static void _Systick(void) {

OS_EnterInterrupt(); // Inform embOS that interrupt code is running
OS_HandleTick(); // Can not be interrupted by higher priority interrupts
OS_LeaveInterrupt(); // Inform embOS that interrupt handler is left
}

6.7.2 OS_EnterNestableInterrupt()
Description
OS_EnterNestableInterrupt(), enables nesting.
Prototype
void OS_EnterNestableInterrupt (void);

Additional Information
OS_EnterNestableInterrupt(), allow nesting. OS_EnterNestableInterrupt() may
be used as prolog function, when the interrupt handler may be preempted by any
other interrupt handler that runs on a higher interrupt priority. An interrupt handler
that starts with OS_EnterNestableInterrupt() has to end with the epilog function
OS_LeaveNestableInterrupt().
Example
Interrupt-routine that can be preempted by other interrupts.

static void _Systick(void) {

OS_EnterNestableInterrupt(); // Inform embOS that interrupt code is running
OS_HandleTick(); // Can be interrupted by higher priority interrupts
OS_LeaveNestableInterrupt(); // Inform embOS that interrupt handler is left
}

6.7.3 Required embOS system interrupt handlers

embOS for Cortex M core needs two exception handlers which belong to the system
itself. Both are delivered with embOS. Ensure that they are referenced in the vector
table.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
36 CHAPTER 6 Interrupts

6.8 Interrupt handling with vectored interrupt control-

ler
For the Cortex-M core, which has a built-in vectored interrupt controller, functions to
install and setup interrupt handler functions are usually provided with the core-spe-
cific CMSIS files. Please refer to “Enable and disable interrupts” on page 44, as well
as “Setting the Interrupt priority” on page 44 for further information on these generic
CMSIS functions.
With start projects that do not include CMSIS, however, embOS provides additional
functions to install and setup interrupt handlers. To handle interrupts with the vec-
tored interrupt controller, embOS offers the following functions:

6.8.1 OS_ARM_EnableISR(): Enable specific interrupt

Description
OS_ARM_EnableISR() is used to enable interrupt acceptance of a specific interrupt
source in a vectored interrupt controller.
This function is not implemented with Cortex-M start projects that contain the
CMSIS-function NVIC_EnableIRQ(), which then must be used instead.
Prototype
void OS_ARM_EnableISR (int ISRIndex);

Parameters

Parameter Description
Index of the interrupt source that should be enabled.
ISRIndex Note that the index counts from 0 for the first entry in the vec-
tor table.
Table 6.1: OS_ARM_EnableISR() parameter list

Additional Information
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 that the ISRIndex counts from 0 for the first entry in the vector table.
The first peripheral index therefore has the ISRIndex 16, because the first peripheral
interrupt vector is located after the 16 generic vectors in the vector table.
This differs from index values used with CMSIS.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 37

6.8.2 OS_ARM_DisableISR(): Disable specific interrupt

Description
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.
This function is not implemented with Cortex-M start projects that contain the
CMSIS-function NVIC_DisableIRQ(), which then must be used instead.
Prototype
void OS_ARM_DisableISR (int ISRIndex);

Parameters

Parameter Description
Index of the interrupt source that should be disabled.
ISRIndex Note that the index counts from 0 for the first entry in the vec-
tor table.
Table 6.2: OS_ARM_DisableISR() parameter list

Additional Information
This function just disables the interrupt in the interrupt controller. It does not disable
the interrupt of any peripherals. This has to be done elsewhere.
Note that the ISRIndex counts from 0 for the first entry in the vector table.
The first peripheral index therefore has the ISRIndex 16, because the first peripheral
interrupt vector is located after the 16 generic vectors in the vector table.
This differs from index values used with CMSIS.

6.8.3 OS_ARM_ISRSetPrio(): Set priority of specific interrupt

Description
OS_ARM_ISRSetPrio() is used to set or modify the priority of a specific interrupt
source by programming the interrupt controller.
This function is not implemented with Cortex-M start projects that contain the
CMSIS-function NVIC_SetPriority(), which then must be used instead.
Prototype
int OS_ARM_ISRSetPrio (int ISRIndex,
int Prio);

Parameters

Parameter Description
Index of the interrupt source which should be modified.
ISRIndex Note that the index counts from 0 for the first entry in the vec-
tor table.
The priority which should be set for the specific interrupt.
Prio
Prio ranges from 0 (highest priority) to 255 (lowest priority)
Table 6.3: OS_ARM_ISRSetPrio() parameter list

Additional Information
This function sets the priority of an interrupt channel by programming the interrupt-
controller. Please refer to CPU-specific manuals about allowed priority levels.
Note that the ISRIndex counts from 0 for the first entry in the vector table.
The first peripheral index therefore has the ISRIndex 16, because the first peripheral
interrupt vector is located after the 16 generic vectors in the vector table.
This differs from index values used with CMSIS.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
38 CHAPTER 6 Interrupts

The priority value is independent of the chip-specific preemption levels. Any value
between 0 and 255 can be used, were 255 always is the lowest priority and 0 is the
highest priority.
The function can be called to set the priority for all interrupt sources, regardless of
whether embOS is used in the specified interrupt handler or not.
Note that interrupt handlers running on priorities from 127 or higher must not call
any embOS function.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 39

Chapter 7

CMSIS

ARM introduced the Cortex Microcontroller Software Interface Standard (CMSIS) as a

vendor independent hardware abstraction layer for simplifying software re-use.
The standard enables consistent and simple software interfaces to the processor, for
peripherals, for real time operating systems as embOS and other middleware.
As SEGGER is one of the CMSIS partners, embOS for Cortex M is fully CMSIS compli-
ant.
embOS comes with a generic CMSIS start project which should run on any Cortex M3
CPU. All other start projects, even those not based on CMSIS, are also fully CMSIS
compliant and can be used as starting points for CPU specific CMSIS projects.
How to use the generic project and adding vendor specific files to this or other
projects is explained in the following chapters.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
40 7 CMSIS

7.1 The generic CMSIS start project

The folder Start\BoardSupport\CMSIS contains a generic CMSIS start project that
should run on any Cortex M3 / M4 / M4F core.
The subfolder DeviceSupport\ contains the device specific source and header files
which have to be replaced by the device specific files of the CM3 / CM4 vendor to
make the CMSIS sample start project device specific.

7.2 Device specific files needed for embOS with CMSIS

• Device.h: Contains the device specific exception and interrupt numbers and
names. embOS needs the Cortex M3 generic exception names PendSV_IRQn and
SysTick_IRQn only which are vendor independent and common for all devices.
The sample file delivered with embOS does not contain any peripheral interrupt
vector numbers and names as those are not needed by embOS.
To make the embOS CMSIS sample device specific and allow usage of peripheral
interrupts, this file has to be replaced by the one which is delivered from the CPU
vendor.
• System_Device.h: Declares at least the two required system timer functions
which are used to initialize the CPU clock system and one variable which allows
the application software to retrieve information about the current CPU clock
speed. The names of the clock controlling functions and variables are defined by
the CMSIS standard and are therefore identical in all vendor specific implementa-
tions.
• System_Device.c: Implements the core specific functions to initialize the CPU,
at least to initialize the core clock. The sample file delivered with embOS contains
empty dummy functions and has to be replaced by the vendor specific file which
contains the initialization functions for the core.
• Startup_Device.s: The startup file which contains the initial reset sequence and
contains exception handler and peripheral interrupt handler for all interrupts.
The handler functions are declared weak, so they can be overwritten by the
application which implements the application specific handler functionality.
The sample which comes with embOS only contains the generic exception vectors
and handler and has to be replaced by the vendor specific startup file.

Startup code requirements:

The reset handler HAS TO CALL the SystemInit() function which is delivered with
the core specific system functions.
When using a Cortex M4 or M4F CPU which may have a VFPv4 floating point unit
equipped, please ensure that the reset handler activates the VFP when VFPv4 is
selected in the project options.
When VFP-support is not selected, the VFP should not be switched on.
Otherwise, the SystemInit() function delivered from the device vendor should also
honor the project settings and enable the VFP or keep it disabled according the
project settings.
Using CMSIS compliant startup code from the chip vendors may require modification
if it enables the VFP unconditionally.

7.3 Device specific functions/variables needed for embOS with

CMSIS
The embOS system timer is triggered by the Cortex M generic system timer. The cor-
rect core clock and pll system is device specific and has to be initialized by a low level
init function called from the startup code.
embOS calls the CMSIS function SysTick_Config() to set up the system timer. The
function relies on the correct core clock initialization performed by the low level ini-

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 41

tialization function SystemInit and the value of the core clock frequency which has to
be written into the SystemCoreClock variable during initialization or after calling Sys-
temCoreClockUpdate().
• SystemInit():The system init function is delivered by the vendor specific CMSIS
library and is normally called from the reset handler in the startup code. The sys-
tem init function has to initialize the core clock and has to write the CPU fre-
quency into the global variable SystemCoreClock.
• SystemCoreClock: Contains the current system core clock frequency and is ini-
tialized by the low level initialization function SystemInit() during startup.
embOS for CMSIS relies on the value in this variable to adjust its own timer and
all time related functions.
Any other files or functions delivered with the vendor specific CMSIS library may be
used by the application, but are not required for embOS.

7.4 CMSIS generic functions needed for embOS with CMSIS

The embOS system timer is triggered by the Cortex M generic system timer which
has to be initialized to generate periodic interrupts in a specified interval. The config-
uration function SysTick_Config() for the system timer relies on correct initialization
of the core clock system which is performed during startup.
• SystemCoreClockUpdate: This CMSIS function has to update the SystemCore-
Clock variable according the current system timer initialization. The function is
device sepcific and may be called before the SystemCoreClock variable is
accessed or any function which relies on the correct setting of the system core
clock variable is called. embOS calls this function during the hardware initializa-
tion function OS_InitHW() before the system timer is initialized.
• SysTick_Config: This CMSIS generic function is declared an implemented in the
core_cm3.h file. It initializes and starts the SysTick counter and enables the
SysTick interrupt. For embOS it is recommended to run the SysTick interrupt at
the second lowest preemption priority. Therefore, after calling the
SysTick_Config() function from OS_InitHW(), the priority is set to the second
lowest preemption priority ba a call of NVIC_SetPriority().
The embOS function OS_InitHW() has to be called after initialization of embOS
during main and is implemented in the RTOSInit_CMSIS.c file.
• SysTick_Handler: The embOS timer interrupt handler, called periodically by the
interrupt generated from the SysTick timer. The SysTick_Handler is declared
weak in the CMSIS startup code and is replaced by the embOS Systick_Handler
function implemented in RTOSInit_CMSIS.c which comes with the embOS start
project.
• PendSV_Handler: The embOS scheduler entry function. It is declared weak in
the CMSIS startup code and is replaced by the embOS internal function contained
in the embOS library. The embOS initialization code enables the PendSV excep-
tion and initializes the priority. The application MUST NOT change the PendSV
priority.

7.5 Customizing the embOS CMSIS generic start project

The embOS CMSIS generic start project should run on every Cortex M3 / M4 or M4F
CPU. As the generic device specific functions delivered with embOS do not initialize
the core clock system and the pll, the timing is not correct, a real CPU will run very
slow.
To run the sample project on a specific Cortex M3 / M4 / M4F CPU, replace all files in
the DeviceSupport\ folder by the versions delivered by the CPU vendor. The vendor
and CPU specific files should be found in the CMSIS release package, or are available
from the core vendor.
No other changes are necessary on the start project or any other files.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
42 7 CMSIS

To run the generic CMSIS start project on a Cortex M0, you have to replace the
embOS libraries by libraries for Cortex M0 and have to add Cortex M0 specific vendor
files.

7.6 Adding CMSIS to other embOS start projects

All CPU specific start projects are fully CMSIS compatible. If required or wanted in
the application, the CMSIS files for the specific CPU may be added to the project
without any modification on existing files.
Note that the OS_InitHW() function in the RTOSInit file initialize the core clock sys-
tem and pll of the specific CPU. The system clock frequency and core clock frequency
are defined in the RTOSInit file.
If the application needs access to the SystemCoreClock, the core specific CMSIS
startup code and core specific initialization function SystemInit has to be included in
the project.
In this case, OS_InitHW() function in RTOSInit may be replaced, or the CMSIS
generic RTOSInit_CMSIS.c file may be used in the project.

7.6.1 Differences between embOS projects and CMSIS

Several embOS start projects are not based on CMSIS, but are fully CMSIS compliant
and can be mixed with CMSIS libraries from the device vendors.
Switching from embOS to CMSIS, or mixing embOS with CMSIS functions is possible
without problems.
Modifications may be required specifically in regards to the interrupt controller setup
functions, which differ between projects based on CMSIS and projects not based on
CMSIS.

7.6.1.1 Different peripheral ID numbers

Using CMSIS, the peripheral IDs to setup the interrupt controller start from 0 for the
first peripheral interrupt. With emboS, the first peripheral is addressed with ID num-
ber 16.
embOS counts the first entry in the interrupt vector table from 0, so, the first periph-
eral interrupt following the 16 Cortex system interrupt entries, is 16.
When the embOS functions should be replaced by the CMSIS functions, this correc-
tion has to be taken into account, or if available, the symbolic peripheral id numbers
from the CPU specific CMSIS device header file may be used with CMSIS.
Note that using these IDs with the embOS functions will work only, when 16 is added
to the IDs from the CMSIS device header files.

7.6.1.2 Different interrupt priority values

Using embOS functions, the interrupt priority value ranges from 0 to 255 and is writ-
ten into the NVIC control registers as is, regardless the number of priority bits.
255 is the lowest priority, 0 is the highest priority.
Using CMSIS, the range of interrupt priority levels used to setup the interrupt con-
troller depends on the number of priority bits implemented in the specific CPU.
The number of priority bits for the specific device shall be defined in the device spe-
cific CMSIS header file as __NVIC_PRIO_BITS.
If it is not defined in the device specific header files, a default of 4 is set in the
generic CMSIS core header file.
A CPU with 4 priority bits supports up to 16 preemption levels.
With CMSIS, the range of interrupt priorities for this CPU would be 0 to 15, where 0
is the highest priority and 15 is the lowest.
To convert an embOS priority value into a value for the CMSIS functions, the value
has to be shifted to the right by (8 - __NVIC_PRIO_BITS).
To convert an CMSIS value for the interrupt priority into the value used with the

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 43

embOS functions, the value has to be shifted to the left by (8 - __NVIC_PRIO_BITS).

In any case, half of the priorities with lower values (from zero) are high priorities
which must not be used with any interrupt handler using embOS functions.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
44 7 CMSIS

7.7 Interrupt and exception handling with CMSIS

The embOS CPU specific projects come with CPU specific vector tables and empty
exception and interrupt handlers for the specific CPU. All handlers are named accord-
ing the names of the CMSIS device specific handlers and are declared weak and can
be replaced by an implementation in the application source files.
The CPU specific vector table and interrupt handler functions in the embOS start
projects can be replaced by the CPU specific CMSIS startup file of the CPU vendor
without any modification on other files in the project.
embOS uses the two Cortex M generic exceptions PendSV and SysTick and delivers
its own handler functions to handle these exceptions.
All peripheral interrupts are device specific and are not used with embOS except for
profiling support and system analysis with embOSView using a UART.

7.8 Enable and disable interrupts

With CMSIS, the generic CMSIS functions NVIC_EnableIRQ() and
NVIC_DisableIRQ() must be used instead of the embOS functions
OS_ARM_EnableISR() and OS_ARM_DisableISR(). The embOS functions are imple-
mented in the CPU specific RTOSInit file only when the NVIC functions are not pro-
vided.
Note that the CMSIS functions use different peripheral ID indices to address the spe-
cific interrupt number.
embOS counts from 0 for the first entry in the interrupt vector table, CMSIS counts
from 0 for the first peripheral interrupt vector, which is ID number 16 for the embOS
functions.
About these differences, also read chapter 7.7.1
To enable and disable interrupts in general, the embOS functions OS_IncDI() and
OS_DecRI() or other embOS functions described in the generic embOS manual
should be used instead of the intrinsic functions from the CMSIS library.

7.9 Setting the Interrupt priority

With CMSIS, the generic CMSIS function NVIC_SetPriority() must be used instead
of the embOS function OS_ARM_ISRSetPrio(). The embOS function is implemented
in the CPU specific RTOSInit file only when the NVIC function is not provided.
Note that with the CMSIS function, the range of valid interrupt priority values
depends on the number of priority bits defined and implemented for the specific
device.
The number of priority bits for the specific device shall be defined in the device spe-
cific CMSIS header file as __NVIC_PRIO_BITS.
If it is not defined in the device specific header files, a default of 4 is set in the
generic CMSIS core header file.
A CPU with 4 priority bits supports up to 16 preemption levels.
With CMSIS, the range of interrupt priorities for this CPU would be 0 to 15, where 0
is the highest priority and 15 is the lowest.
About interrupt priorities in an embOS project, read chapter 6.5 and 6.6., about the
differences between interrupt priority and ID values used to setup the NVIC control-
ler, read chapter 7.7.1

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 45

Chapter 8

VFP support

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller

46 CHAPTER 8 VFP support

8.1 Vector Floating Point support VFPv4

Some Cortex M4F / M7 MCUs come with an integrated vectored floating point unit
VFPv4.
When selecting the CPU and activating the VFPv4 support in the project options, the
compiler and linker will add efficient code which uses the VFP when floating point
operations are used in the application.
With embOS, the VFP registers are automatically saved and restored when preemp-
tive or cooperative task switches are performed.
For efficiency reasons, embOS does not save and restore the VFP registers for tasks
which do not use the VFP unit.

8.1.1 Using embOS libraries with VFP support

When VFP support is selected as project option, one of the embOS libraries with VFP
support have to be used in the project.
The embOS libraries for VFP support require that the VFP is switched on during star-
tup and remains switched on during program execution.
Using your own startup code, ensure that the VFP is switched on during startup.
When the VFP unit is not switched on, the embOS scheduler will fail.
The debug version of embOS checks whether the VFP is switched on when embOS is
initialized by calling OS_InitKern().
When the VFP unit is not detected or not switched on, the embOS error handler
OS_Error() is called with error code OS_ERR_CPU_STATE_ILLEGAL.

8.1.2 Using the VFP in interrupt service routines

Using the VFP in interrupt service routines does not require any additional functions
to save and restore the VFP registers. The VFP registers are automatically saved and
restored by the hardware.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller

 47

Chapter 9

RTT and SystemView

This chapter contains information about SEGGER Real Time Transfer and SEGGER
SystemView.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
48 9 RTT and SystemView

9.1 SEGGER Real Time Transfer

SEGGER's Real Time Transfer (RTT) is the new technology for interactive user I/O in
embedded applications. RTT can be used with any J-Link model and any supported
target processor which allows background memory access.
RTT is included with many embOS start projects.
Some IDEs, such as SEGGER Embedded Studio, support RTT and display RTT output
directly within the IDE. In case the used IDE does not support RTT, SEGGER’s J-Link
RTT Viewer, J-Link RTT Client, and J-Link RTT Logger may be used instead to visual-
ize your application’s debug output.
For more information on SEGGER Real Time Transfer, refer to
https://www.segger.com/jlink-rtt.html.

9.1.1 Shipped files related to SEGGER RTT

All files related to SEGGER RTT are shipped inside the respective start project’s Setup
folder:

File Description
SEGGER_RTT.c Generic implementation of SEGGER RTT.
SEGGER_RTT.h Generic implementation header file.
SEGGER_RTT_Conf.h Generic RTT configuration file.
Generic printf() replacement to write formatted
SEGGER_RTT_printf.c
data via RTT.
Compiler-specific low-level functions for using
printf() via RTT.
SEGGER_RTT_Syscalls_*.c If this file is included in a project, RTT is used
for debug output. To use the standard out of your
IDE, exclude this file from build.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 49

9.2 SEGGER SystemView

SEGGER SystemView is a real-time recording and visualization tool to gain a deep
understanding of the runtime behavior of an application, going far beyond what
debuggers are offering. The SystemView module collects and formats the monitor
data and passes it to RTT.
SystemView is included with many embOS start projects. These projects are by
default configured to use SystemView in debug builds. The associated PC visualiza-
tion application, SystemViewer, is not shipped with embOS. Instead, the most recent
version of that application is available for download from our website.

For more information on SEGGER SystemView, including the SystemViewer down-

load, refer to https://www.segger.com/systemview.html.

9.2.1 Shipped files related to SEGGER SystemView

All files related to SEGGER SystemView are shipped inside the respective start
project’s Setup folder:

File Description
Global type definitios required by
Global.h
SEGGER SystemView.
Generic types and utility function
SEGGER.h
header.
SEGGER_SYSVIEW.c Generic implementation of SEGGER RTT.
SEGGER_SYSVIEW.h Generic implementation include file.
SEGGER_SYSVIEW_Conf.h Generic configuration file.
SEGGER_SYSVIEW_ConfDefaults.h Generic default configuration file.
Target-specific configuration of
SEGGER_SYSVIEW_Config_embOS.c
SystemView with embOS.
Generic interface implementation for
SEGGER_SYSVIEW_embOS.c
SystemView with embOS.
Generic interface implementation header
SEGGER_SYSVIEW_embOS.h
file for SystemView with embOS.
SEGGER_SYSVIEW_Int.h Generic internal header file.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
50 9 RTT and SystemView

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 51

Chapter 10

embOS C-Spy plug-in

This chapter gives a short overview about the embOS C-Spy plug-in for IAR Embed-
ded Workbench.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
52 10 embOS C-Spy plug-in

10.1 Overview
10.1.1 embOS C-Spy plug-in
SEGGER’s embOS C-Spy plug-in for IAR Embedded Workbench provides embOS-
awareness during debugging sessions. This enables you to inspect the state of sev-
eral embOS primitives such as the task list, resource semaphores, mailboxes, and
timers.
Since embOS version 3.62, you can check the general-purpose registers and inspect
the call stack of all available application tasks.

10.1.2 Requirements
To use the embOS C-Spy plug-in you need a version of IAR Embedded Workbench
installed and a debug target which uses embOS.
The following plug-ins are available and may be used with the listed versions of IAR’s
Embedded Workbench for ARM:

IAR Embedded Workbench Version Compatible Plug-In version

<= 6.70 6.10.2.3
>= 7.10
7.10.2.3
<= 7.40
>= 7.50 7.50.2.3
Table 10.1: Compatible plugin and IDE versions

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 53

10.2 Installation
The installation procedure is very straightforward because it only requires you to
copy the contents of the embOS C-Spy plug-in package into the IAR CPU specific
plug-in folder for rtos plug-ins. The directory structure may look like this:

If not already delivered with the IAR Embedded Workbench IDE, create a directory
embOS below the CPU specific plugin\rtos\ folder and copy the files from the embOS
folder which comes with the plug-in into that folder in your IAR installation directory.
Then restart the IAR Embedded Workbench IDE.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
54 10 embOS C-Spy plug-in

10.3 Configuration
By default, the embOS C-Spy plug-in is not loaded during debugging. For each
project configuration you have to explicitly enable the plugin in the debugger section
of the project options:

The embOS C-Spy plug-in is now available in debugging sessions and may be
accessed from the main menu.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 55

10.4 Using the embOS C-Spy plug-in

During your debugging session, the embOS C-Spy plug-in is accessible from the IAR
Embedded Workbench IDE main menu. Note that if you are not running a debugging
session, there is no embOS menu item available.

From the menu you may activate the individual windows that provide embOS related
information. The sections below describe these individual windows. The amount of
information available depends on the embOS build used during debugging. If a cer-
tain part is not available, the respective menu item is either greyed out or the win-
dow column shows a N/A.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
56 10 embOS C-Spy plug-in

10.4.1 Tasks
The Task List window lists all embOS tasks. It retrieves its information directly from
the embOS task list. The green arrow points to the running task, which is the task
currently executing. If no task is executing, the CPU is executing the Idle-loop. In
this case, the green arrow is in the bottom row of the window, labeled “Idle”.
The bottom row of the task list window is always labeled “Idle”. It does not actually
represent a task, but the Idle loop, which is executed if no task is ready for execu-
tion.

The individual columns are described below:

Column Description
* A green arrow points to the running task.
Prio Priority of the task.
Id The task control block address that uniquely identifies a task.
Name If available, the task name is shown here.
Status The task status as a short text.
If a task is delayed, this column shows the time remaining until the
Timeout
delay expires and in parenthesis the time of expiration.
If available, this column shows the amount of used stack space, and
Stack Info the available stack space, as well as the value of the current stack
bottom pointer.
Run count The number of task activations.
If round robin scheduling is available, this column shows the number
Time slice
of remaining time slices and the number of time slice reloads.
Events The event mask of a task.
Table 10.2: Task list window items

10.4.1.1 Task sensitivity

The Source Code window, the Disassembly window, the Register window, and the
Call Stack window of the C-Spy debugger are task sensitive since version 3.62 of the
embOS C-Spy plug-in. This means that they show the position in the code, the gen-
eral-purpose registers and the call stack of the selected task. By default, the selected
task is always the running task, which is the normal behavior of a debugger that the
user expects.
You can examine a particular thread by double-clicking on the corresponding row in
the window. The selected task will be underlaid in yellow. The C-Spy Debugger
rebuilds the call stack and the preserved general-purpose registers of a suspended
task. Refer to “State of suspended tasks” on page 57 for detailed information about
which information are available for the different task states.
Every time the CPU is started or when the Idle-row of the task window is double
clicked, the selected task is switched back to this default.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 57

10.4.1.2 State of suspended tasks

Blocked tasks (suspended by cooperative task switch)
Tasks which have given up execution voluntarily by calling a blocking function, such
as OS_Delay() or OS_Wait_...(). In this case, there was no need for the OS to save
the scratch registers (in case of ARM R0-R3, R12).
The Register window will show “----------” for the content of these registers.

Tasks waiting for first activation

These basically fall into the same category as blocked tasks, the call stack and regis-
ters look similar to the following screenshots. Similarly, temporary registers are
unknown. The Call Stack shows a single entry OS_StartTask. Run count is 0.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
58 10 embOS C-Spy plug-in

Interrupted tasks
Tasks which have been interrupted and preempted, typically by a task with higher
priority becoming ready. In this case, the OS saved all registers, including the
scratch registers (in case of ARM R0-R3, R12). The Register window shows the val-
ues of all registers, including the scratch registers.

10.4.1.3 Call stack with embOS libraries

All embOS libraries are built with full optimization. Therefore it may happen that not
all function calls are shown in the call stack in detail. The additional embOS library
*dpl.a is built with low optimization. It may be used for application development
instead of the Debug and Profiling library.
This gives the ability to see the complete detailed call stack.

Call stack with DP library Call stack with DPL library

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 59

10.4.2 Mailboxes
A mailbox is a buffer that is managed by the real-time operating system. The buffer
behaves like a normal buffer; you can put something (called a message) in and
retrieve it later. This window shows the mailboxes and provides information about the
number of messages, waiting tasks etc.

Column Description
Id The mailbox address.
The number of messages in a mailbox and the maximum number of
Messages
messages as mailbox can hold.
Message size The size of an individual message in bytes.
pBuffer The message buffer address.
The list of tasks that are waiting for a mailbox, that is their address
Waiting tasks
and name.
Table 10.3: Mailboxes window items

10.4.3 Timers
A software timer is an object that calls a user-specified routine after a specified
delay. This window provides information about active software timers.

Column Description
Id The timer’s address.
Hook The function (address and name) that is called after the timeout.
The time delay and the point in time, when the timer finishes wait-
Time
ing.
Period The time period the timer runs.
Active Shows whether the timer is active or not.
Table 10.4: Timers window items

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
60 10 embOS C-Spy plug-in

10.4.4 Resource semaphores

Resource semaphores are used to manage resources by avoiding conflicts caused by
simultaneous use of a resource. This window provides information about available
resources.

Column Description
Id The resource semaphore address.
Owner The address and name of the owner task.
Use counter Counts the number of semaphore uses.
Lists the tasks (address and name) that are waiting at the sema-
Waiting tasks
phore.
Table 10.5: Resource Semaphores window items

10.4.5 System information

A running embOS contains a number of system variables that are available for
inspection. This window lists the most important ones.

10.4.6 Settings
To be safe, the embOS C-Spy plug-in imposes certain limits on the amount of infor-
mation retrieved from the target, to avoid endless requests in case of false values in
the target memory. This dialog box allows you to tweak these limits in a certain
range, for example if your task names are no longer than 32 characters you may set
the Maximum string length to 32, or if they are longer than the default you may
increase that value.

After changing settings and clicking the OK button, your changes are applied imme-
diately and should become noticeable after the next window update, for example
when hitting the next breakpoint. However, the settings are restored to their default
values on plug-in reload.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 61

10.4.7 About
Finally, the About dialog box contains the embOS C-Spy plug-in version number and
the date of compilation.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
62 10 embOS C-Spy plug-in

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 63

Chapter 11

Technical data

This chapter lists technical data of embOS used with Cortex-M CPUs.

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
64 11 Technical data

11.1 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 embOS.
The minimum ROM requirement for the kernel itself is about 1.700 bytes.
In the table below, which is for X-Release build, you can find minimum RAM size
requirements for embOS resources. Note that the sizes depend on selected embOS
library mode.

embOS resource RAM [bytes]

Task control block 36

Software timer 20

Resource semaphore 16

Counting semaphore 8

Mailbox 24

Queue 36

Task event 0

Event object 12

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
 65

Index

Symbols
__NVIC_PRIO_BITS ....................... 42, 44

C
CMSIS ................................................39
C-Spy plug-in ......................................52

I
Installation .........................................10
interrupt handlers ................................32
Interrupt nesting .................................34
Interrupt priorities ...............................33
Interrupt stack ....................................30
Interrupt vector table ...........................32
Interrupts ...........................................31
Interrupt-stack ....................................33

M
Memory requirements ..........................64

O
OS_ExtendTaskContext_TLS() ...............27
OS_ExtendTaskContext_VFP() ...............46
OS_ThreadLocalStorage.c .....................27

S
Stacks ................................................29
Syntax, conventions used ...................... 5
System stack ......................................30
SystemCoreClock .................................41
SystemInit() .......................................41

T
Task stack ..........................................30
Thread Local Storage ...........................27
TLS ....................................................27

V
Vector Floating Point support .................46
VFPv4 ................................................46

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG
66

X
xmtx.c .......................................... 25–27
xmtx2.c ........................................ 25–26

embOS for Cortex-M and IAR © 2009 - 2017 SEGGER Microcontroller GmbH & Co. KG