SEGGER embos Specifications

embOS

Real-Time Operating System

CPU & Compiler specifics

for ARM Cortex-M using

IAR Embedded Workbench

Document: UM01014

Software Version: 5.10.1.0

Revision: 1

Date: March 1, 2021

A product of SEGGER Microcontroller GmbH

www.segger.com

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 (SEGGER) 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.

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.

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. +49 2173-99312-0 Fax. +49 2173-99312-28 E-mail:

Internet: www.segger.com

support@segger.com

By sending us an email your (personal) data will automatically be processed. For further information please refer to our

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: March 1, 2021

Software Revision Date By Description

5.10.0.0 1 210301 MM

5.10.0.0 0 200617 TS/MM

5.06 1 190930 MC

5.06 0 190514 MM

5.02a 0 180727 MM

5.00 0 180522 MM

4.40 0 180104 MC

4.38 0 170928 MC

4.36 0 170721 MC

4.34 0 170327 TS

4.30 0 161213 MC

4.26 0 161027 RH

4.22 0 160531 MC

4.16 0 160122 MC

4.14 0 151222 MC

4.12a 0 150917 TS

4.10 0 150505 TS

4.06b 0 150330 TS

4.06a 0 150317 TS

4.04a 0 150109 SC

4.02a 0 140918 TS

4.02 0 140819 TS

4.00 0 140606 TS

3.90 0 140228 AW

3.88g 0 131104 TS

3.88c 0 130813 TS

3.88b 0 130528 AW/TS

3.86n 0 121210 AW

3.86l 0 121126 TS

3.86g 0 120806 AW

3.86f 0 120726 AW

Added missing chapter “CPU and compiler specifics”.

Chapter “Libraries” updated. Chapter “CPU and compiler specifics -> IAR C-Spy stack check warning” added.

Chapter “Libraries” updated.

New software version.

Chapter “Compiler specifics” updated.

New software version.

Chapters “Using embOS” and “embOS C-Spy Plugin” updated.

Chapters “VFP support”, “CPU and compiler specifics”, and “embOS CSpy Plugin” updated.

New software version.

Chapter “Compiler specifics” updated.

New software version.

Typos corrected. New software version.

New generic embOS sources V4.04a.

New generic embOS sources V4.02a.

New generic embOS sources V4.02.

New generic embOS sources V4.00.

New generic embOS sources V3.90. Updated start project for EWARM V7.10.

New generic embOS sources V3.88g.

New generic embOS sources V3.88c.

New generic embOS sources V3.88b. Chapter 4, “Thread safe system libraries with IAR compiler 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 V6.4 or newer” added to describe the procedure to activate thread safe library support with newer IAR compiler.

Software: New embOS sources V3.86i.

Software: New embOS sources V3.86g.

Software: New embOS sources V3.86f. Task events are 32bits wide for Cortex-M.

Software Revision Date By Description

3.86e 0 120708 AW

3.86d 0 120510 AW

3.84c1 0 120203 AW

3.84c 1 120117 TS

3.84.1 0 111103 AW

3.84 0 111027 AW

3.82u 0 110701 AW

3.82s 0 110323 TS

3.82m 0 101117 AW

3.82l 0 101027 AW

3.82h 0 100722 TS

3.82a 1 100701 AW

3.82a 0 091026 TS

Software: New embOS sources V3.86e. Modified hard fault handler added to RTOSInit.

Software: New embOS sources V3.86d. OS_ExtendTaskContext_TLS_VFP() corrected.

Software: Scheduler for Cortex-M4 with VFP corrected. Chapter 4: New functions to save and restore VFP context of Cortex-M4 in ISR handler:

OS_VFP_Save() OS_VFP_Restore()

Software version updated. Software: New scheduler uses main stack for OS_Idle().

Chapter 5: Stacks, system stack descripton updated. New Chapter 6.8.4 and 6.8.5: Interrupt peripheral identifier 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:

OS_ExtendTaskContext_TLS() OS_ExtendTaskContext_TLS_VFP() OS_ExtendTaskContext_VFP()

Chapter CMSIS with IAR EWARM V6 added.

New library mode DPL added.

Thread local storage for new IAR workbench V6.

Library names updated for new IAR workbench V6. Thread safe library support modified for IAR workbench V6.

embOS CM3 and embOS CM0 manual merged.

Chapter Stacks: Task stack size corrected.

First version.

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 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 programming is not required.

Typographic conventions for syntax

This manual uses the following typographic conventions:

Style Used for

Body Body text.

Keyword

Parameter Parameters in API functions.

Sample Sample code in program examples.

Sample comment Comments in program examples.

Reference

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

Emphasis Very important sections.

Text that you enter at the command prompt or that appears on the display (that is system functions, file- or pathnames).

Reference to chapters, sections, tables and figures or other documents.

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

4.4 IAR C-Spy stack check warning ..................................................................... 25

4.5 ARM erratum 837070 ................................................................................... 26

4.6 ARM TrustZone support .................................................................................27

5 Stacks ......................................................................................................................... 28

5.1 Task stack for Cortex-M ................................................................................ 29

5.2 System stack for Cortex-M ............................................................................ 29

5.3 Interrupt stack for Cortex-M ..........................................................................29

6 Interrupts .....................................................................................................................30

6.1 What happens when an interrupt occurs? ........................................................ 31

6.2 Defining interrupt handlers in C .....................................................................31

6.3 Interrupt vector table ................................................................................... 31

6.4 Interrupt-stack switching .............................................................................. 32

6.5 Zero latency interrupts ................................................................................. 32

6.6 Interrupt priorities ........................................................................................32

6.7 Interrupt nesting ..........................................................................................33

6.8 Interrupt handling API .................................................................................. 35

7 CMSIS .........................................................................................................................40

7.1 The generic CMSIS start project .................................................................... 41

7.2 Device specific files needed for embOS with CMSIS .......................................... 41

7.3 Device specific functions/variables needed for embOS with CMSIS ...................... 41

7.4 CMSIS generic functions needed for embOS with CMSIS ................................... 42

7.5 Customizing the embOS CMSIS generic start project ........................................ 42

7.6 Adding CMSIS to other embOS start projects .................................................. 42

7.7 Interrupt and exception handling with CMSIS .................................................. 44

7.7.1 Enable and disable interrupts ............................................................. 44

7.7.2 Setting the Interrupt priority .............................................................. 44

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

8.1 Vector Floating Point support .........................................................................46

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

9.1 SEGGER Real Time Transfer .......................................................................... 48

9.2 SEGGER SystemView ....................................................................................49

10 Technical data ...........................................................................................................50

10.1 Memory requirements ................................................................................. 51

Chapter 1 Using embOS

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

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.

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.

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 ****************************/

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.

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.

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 stepping over the delay in LPTask().

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.

+ 35 hidden pages

SEGGER embos Specifications

Specifications and Main Features

Frequently Asked Questions

User Manual

About this document

Table of contents

10 CHAPTER 1 Installation

11 CHAPTER 1 First Steps

12 CHAPTER 1 The example application OS_StartLEDBlink.c

13 CHAPTER 1 Stepping through the sample application