Segger embOS-MPU User manual

embOS-MPU
Real-Time Operating System
CPU & Compiler specifics for Cortex-
M using IAR Embedded Workbench
Document: UM01065
Software Version: 5.8.2.1
Revision: 0
Date: February 3, 2020
A product of SEGGER Microcontroller GmbH
www.segger.com

2
Disclaimer
Specifications written in this document are believed to be accurate, but are not guaranteed 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 (SEG-
GER) assumes no responsibility for any errors or omissions. SEGGER makes and you receive no
warranties or conditions, express, implied, statutory or in any communication with you. SEGGER
specifically disclaims any implied warranty of merchantability or fitness for a particular 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.
© 2010-2020 SEGGER Microcontroller GmbH, Monheim am Rhein / 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 respective holders.
Contact address
SEGGER Microcontroller GmbH
Ecolab-Allee 5
D-40789 Monheim am Rhein
Germany
Tel. [phone]
Fax. [phone]
E-mail: [email protected]
Internet: www.segger.com
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

3
Manual versions
This manual describes the current software version. If you find an error in the manual or a
problem in the software, please inform us and we will try to assist you as soon as possible.
Contact us for further information on topics or functions that are not yet documented.
Print date: February 3, 2020
Software Revision Date By Description
5.8.2.1 0 200203 TS New software version.
5.8.2.0 0 200106 TS Chapter “MPU support” updated.
5.8.0.0 0 191030 TS Chapter “MPU support” updated.
5.02 0 180629 MC New software version.
4.30 0 161202 TS New software version.
4.26.1 0 160928 MC New software version.
4.26 0 160908 MC First version.
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

4
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

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 compiler).
• 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 Programming Lan-
guage by Kernighan and Richie (ISBN 0--13--1103628), which describes the standard in C pro-
gramming 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 programming is not required.
Typographic conventions for syntax
This manual uses the following typographic conventions:
Style Used for
Body Body text.
Keyword Text that you enter at the command prompt or that appears on
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 Reference to chapters, sections, tables and figures or other doc-
uments.
GUIElement Buttons, dialog boxes, menu names, menu commands.
Emphasis Very important sections.
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

6
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

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 .......................................................................................................................19
3.1 Naming conventions for prebuilt libraries ........................................................ 20
4 CPU and compiler specifics ........................................................................................21
4.1 Standard system libraries ..............................................................................22
4.2 Thread-safe system libraries ..........................................................................22
4.3 Thread-Local Storage TLS ............................................................................. 24
4.4 ARM erratum 837070 ................................................................................... 26
5 Stacks ......................................................................................................................... 27
5.1 Task stack for Cortex-M ................................................................................ 28
5.2 System stack for Cortex-M ............................................................................28
5.3 Interrupt stack for Cortex-M ..........................................................................28
6 Interrupts .....................................................................................................................29
6.1 What happens when an interrupt occurs? ........................................................30
6.2 Defining interrupt handlers in C ..................................................................... 30
6.3 Interrupt vector table ................................................................................... 30
6.4 Interrupt-stack switching .............................................................................. 31
6.5 Zero latency interrupts ................................................................................. 31
6.6 Interrupt priorities ........................................................................................31
6.7 Interrupt nesting ..........................................................................................32
6.8 Interrupt handling API .................................................................................. 34
7 CMSIS .........................................................................................................................39
7.1 The generic CMSIS start project .................................................................... 40
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

8
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 .................................................. 41
7.7 Interrupt and exception handling with CMSIS .................................................. 43
7.7.1 Enable and disable interrupts ............................................................. 43
7.7.2 Setting the Interrupt priority .............................................................. 43
8 VFP support ................................................................................................................44
8.1 Vector Floating Point support ......................................................................... 45
9 MPU support ...............................................................................................................46
9.1 Introduction .................................................................................................47
9.2 Supervisor call .............................................................................................47
9.3 Fault exceptions ........................................................................................... 47
9.4 Alignment ....................................................................................................47
9.5 Memory Attributes ........................................................................................48
9.5.1 Modifying memory attributes of default task regions .............................. 49
9.6 Cache maintenance ...................................................................................... 49
9.7 Changing memory attributes for privileged tasks ..............................................49
9.8 OS_MPU_ExtendTaskContext() ....................................................................... 50
9.9 MPU types ...................................................................................................50
9.10 Buffer for MPU sanity check .........................................................................50
9.11 Cortex-M XN bit (Execute Never) ................................................................. 51
9.12 Further information .................................................................................... 51
10 RTT and SystemView ...............................................................................................52
10.1 SEGGER Real Time Transfer .........................................................................53
10.2 SEGGER SystemView .................................................................................. 54
11 Technical data ...........................................................................................................55
11.1 Memory requirements ................................................................................. 56
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

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-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

10 CHAPTER 1 Installation
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 installation
steps are required. You will find many prepared sample start projects, which you should
use and modify to write your application. So follow the instructions of section First Steps
on page 11.
You should do this even if you do not intend to use the IDE for your application development
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-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

11 CHAPTER 1 First Steps
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 subfolders.
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\<DeviceManufacturer>\<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-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

12 CHAPTER 1 The example application OS_StartLEDBlink.c
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 *
* The Embedded Experts *
**********************************************************************
-------------------------- END-OF-HEADER -----------------------------
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).
*/
#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_TASK_Delay(50);
}
}
static void LPTask(void) {
while (1) {
BSP_ToggleLED(1);
OS_TASK_Delay(200);
}
}
/*********************************************************************
*
* main()
*/
int main(void) {
OS_Init(); // Initialize embOS
OS_InitHW(); // Initialize required hardware
BSP_Init(); // Initialize LED ports
OS_TASK_CREATE(&TCBHP, "HP Task", 100, HPTask, StackHP);
OS_TASK_CREATE(&TCBLP, "LP Task", 50, LPTask, StackLP);
OS_Start(); // Start embOS
return 0;
}
/*************************** End of file ****************************/
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

13 CHAPTER 1 Stepping through the sample application
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_Init() 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 primary
purpose is to initialize the hardware required to generate the system tick interrupt 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-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

14 CHAPTER 1 Stepping through the sample application
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-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

15 CHAPTER 1 Stepping through the sample application
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_TASK_Delay() function in disassembly
mode. OS_Idle() is part of RTOSInit.c. You may also set a breakpoint there before step-
ping over the delay in LPTask().
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

16 CHAPTER 1 Stepping through the sample application
If you set a breakpoint in one or both of our tasks, you will see that they continue execution
after the given delay.
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-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

Chapter 2
Build your own application
This chapter provides all information to set up your own embOS project.
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

18 CHAPTER 2 Introduction
2.1 Introduction
To build your own application, you should always start with one of the supplied sample
workspaces and projects. Therefore, select an embOS workspace as described in chapter
First Steps on page 11 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\<Manufacturer>\<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.
•OS_Error.c from one target specific subfolder BoardSupport\<Manufacturer>\<MCU>.
The error handler is used if any debug library is used in your project.
• One embOS library from the subfolder Lib\.
• 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 standard. This is re-
quired for some embOS internal variables. Your main() function has to initialize embOS by
calling OS_Init() and OS_InitHW() prior to any other embOS functions that are called.
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 application 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 appropriate
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 BoardSupport\ folder.
To select a CPU which is already supported, just select the appropriate workspace from a
CPU-specific folder.
If your CPU is currently not supported, examine all RTOSInit.c files in the CPU-specific
subfolders and select one which almost fits your CPU. You may have to modify OS_InitH-
W(), OS_COM_Init(), the interrupt service routines for embOS system timer tick and com-
munication to embOSView and the low level initialization.
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

Chapter 3
Libraries
This chapter includes CPU-specific information such as CPU-modes and available libraries.
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH

20 CHAPTER 3 Naming conventions for prebuilt libraries
3.1 Naming conventions for prebuilt libraries
embOS is shipped with different pre-built libraries with different combinations of features.
The libraries are named as follows:
os<Architecture>_t<Endianness><VFP_support>_<LibMode><Errata>.a
Parameter Meaning Values
Architecture Specifies the ARM architecture
6m : Cortex-M0/M0+/M1
7m : Cortex-M3/M4/M7/M33
8mbl: Cortex-M23 (IAR V8.x only)
Endianness Byte order b : Big endian
l : Little endian
VFP_support Floating point support _ : No hardware VFP support
v : VFPv4 (Cortex-M4/M7/M33 only)
LibMode Specifies the library mode
xr : Extreme Release
r : Release
s : Stack check
sp : Stack check + profiling
d : Debug
dp : Debug + profiling + Stack check
dt : Debug + profiling + Stack check
+ trace
dpl : Debug + profiling + Stack check
built with low optimization level
Errata Specifies whether a workaround for ARM errata
was applied.
_837070: Erratum 837070 applied.
: No workaround applied.
Example
os7m_tl__dp.a is the library for a project using Cortex-M3 core, thumb mode, little endian
mode with debug and profiling support.
Note
Up to V5.02 of embOS-MPU for Cortex-M and IAR, the workaround for ARM erra-
tum 837070 was applied by default for ARMv7-M devices. Starting with V5.8.0.0, the
workaround is no longer applied by default. If libraries including the workaround are
desired, a suitable set of libraries is provided, but projects would need to be updated
accordingly. Please have a look in the chapter ARM erratum 837070 for more details.
embOS-MPU for Cortex-M and IAR © 2010-2020 SEGGER Microcontroller GmbH