SEGGER embOS Operating Instruction

Download

embOS

Real-Time Operating System

embOS plug-in for IAR C-Spy Debugger

Document: UM01025

Software Version: 3.6

Revision: 0

Date: February 11, 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: February 11, 2021

Software Revision Date By Description

3.6 1 210211 MC

3.6 0 201030 MC

3.5 0 200603 MC

3.4 0 200325 MM

3.3 0 191205 MC

3.2 0 191106 MC

3.1 1 180924 MC

3.1 0 180503 MC

3.0 0 170915 MM

New plug-in versions 6.10.3.7, 7.10.3.7, 7.50.3.7, 8.10.3.7, 8.30.3.7, and

9.10.3.7.

New plug-in versions 6.10.3.6, 7.10.3.6, 7.50.3.6, 8.10.3.6, and 8.30.3.6.

New plug-in versions 6.10.3.5, 7.10.3.5, 7.50.3.5, 8.10.3.5, and 8.30.3.5.

New plug-in versions 6.10.3.4, 7.10.3.4, 7.50.3.4, 8.10.3.4, and 8.30.3.4.

New plug-in version 8.30.3.3.

New plug-in versions 6.10.3.2, 7.10.3.2, 7.50.3.2, 8.10.3.2, and 8.30.3.2.

Updated to include most recent versions of IAR embedded workbench and their compatible plug-ins.

New plug-in versions 6.10.3.1, 7.10.3.1, 7.50.3.1, 8.10.3.1, and 8.30.3.1.

New plug-in versions 6.10.3.0, 7.10.3.0, 7.50.3.0, and 8.10.3.0.

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 Introduction ....................................................................................................................8

1.1 Overview ...................................................................................................... 9

1.2 Supported Embedded Workbench variants .......................................................10

2 Installation ...................................................................................................................11

2.1 Installation Procedure ................................................................................... 12

2.2 Configuration ............................................................................................... 13

3 Getting Started ............................................................................................................14

3.1 Overview .....................................................................................................15

3.2 Task List ..................................................................................................... 16

3.3 Timers ........................................................................................................ 19

3.4 Mailboxes .................................................................................................... 20

3.5 Queues ....................................................................................................... 21

3.6 Mutexes ...................................................................................................... 22

3.7 Semaphores ................................................................................................ 23

3.8 Memory Pools .............................................................................................. 24

3.9 Event Objects .............................................................................................. 25

3.10 Watchdogs .................................................................................................26

3.11 System Information .................................................................................... 27

3.12 Settings .................................................................................................... 28

3.13 About ........................................................................................................30

4 Support ........................................................................................................................31

4.1 Contacting support ....................................................................................... 32

Chapter 1 Introduction

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

9 CHAPTER 1 Overview

1.1 Overview

1.1.1 embOS C-Spy Plug-in for IAR Embedded Workbench

SEGGER’s embOS C-Spy plug-in for IAR Embedded Workbench provides embOS-awareness during debug sessions. This enables you to inspect the state of several embOS primitives such as the task list, queues, mutexes, semaphores, mailboxes, software timers, memory pools, event objects, watchdogs, and major system variables.

1.1.2 embOS

embOS is a real-time operating system for embedded applications designed to offer the benefits of a fully-fledged multitasking system at minimum cost. The kernel is fully interruptible and so efficient that embOS can be used in very time critical situations. The memory footprint in both RAM and ROM is so small that embOS can be used in single-chip applications, leaving maximum room for the user-program.

1.1.3 IAR Embedded Workbench

IAR Embedded Workbench is a set of development tools for building and debugging embedded applications using assembler, C and C++. It provides a completely integrated development environment that includes a project manager, editor, build tools and the C-SPY debugger. IAR Embedded Workbench supports a wide range of microcontrollers and cores from different chip manufacturers. It offers the same intuitive user interface regardless of which microcontroller you have chosen to work with -- coupled with general and target-specific support for each chip.

10 CHAPTER 1 Supported Embedded Workbench variants

1.2 Supported Embedded Workbench variants

The following plug-ins are available and may be used with the listed versions of IAR’s Embedded Workbench:

embOS Port IAR Embedded Workbench Version

78K0

8051

ARM7 / ARM9 / Cortex-A/R/M

AVR

AVR32

Coldfire Any 3.82.3.0

CR16C

H8 Any 6.0.1.0

M16C

M32C Any 6.0.1.0

MSP430

R32C Any 6.10.3.7

RH850

RL78

SH Any 6.10.3.7

STM8

V850

≤ 4.80 ≥ 4.81

≤ 8.30 ≥ 9.10 and ≤ 9.30 ≥ 10.10

≤ 6.70 ≥ 7.10 and ≤ 7.40 ≥ 7.50 and ≤ 7.80 ≥ 8.10 and ≤ 8.22 ≥ 8.30 and ≤ 8.50 ≥ 9.10

≤ 6.40 ≥ 6.50 and ≤ 6.80 ≥ 7.10

≤ 4.21 ≥ 4.30

≤ 3.20 ≥ 3.30

≤ 3.60 ≥ 3.70

≤ 5.60 ≥ 6.10 and ≤ 6.50 ≥ 7.10 and ≤ 7.12 ≥ 7.20

≤ 1.30 = 1.40 = 2.10 ≥ 2.20

≤ 1.30 ≥ 1.40 and ≤ 2.21 = 3.10 ≥ 4.10

≤ 2.50 ≥ 2.60 and ≤ 2.90 = 3.10 ≥ 4.10

≤ 1.42 ≥ 2.10 and ≤ 2.20 = 3.10 ≥ 3.11

≤ 4.10 ≥ 4.20

Compatible

Plug-In version

6.10.3.7

7.10.3.7

6.10.3.7

7.10.3.7

8.10.3.7

6.10.3.7

7.10.3.7

7.50.3.7

8.10.3.7

8.30.3.7

9.10.3.7

6.10.3.7

7.10.3.7

8.10.3.7

6.10.3.7

7.10.3.7

6.10.3.7

7.10.3.7

6.10.3.7

7.10.3.7

6.10.3.7

7.10.3.7

8.10.3.7

8.30.3.7

7.10.3.7

7.50.3.7

8.10.3.7

8.30.3.7

6.10.3.7

7.10.3.7

8.10.3.7

8.30.3.7

6.10.3.7

7.10.3.7

8.10.3.7

8.30.3.7

6.10.3.7

7.10.3.7

8.10.3.7

8.30.3.7

6.10.3.7

7.10.3.7

Chapter 2 Installation

This chapter describes the installation steps required to use the embOS C-Spy plug-in.

12 CHAPTER 2 Installation Procedure

2.1 Installation Procedure

Typically, there is no installation required since the IAR Embedded Workbench comes with the plug-in already pre-installed. In case you want to update the plug-in to a more recent version, however, you would need to replace two files that are located within the Embedded Workbench installation directory with the respective files from the embOS C-Spy plug-in package. The Embedded Workbench installation directory should resemble the following structure:

If appropriate folders do not yet exist with your installation, you should create a directory called embOS within the CPU specific folder plugin\rtos\, and subsequently copy the files from the embOS C-Spy plug-in package into that folder. Note that IAR Embedded Workbench must not be running during the update process.

Note

Before replacing any files already found in the plugin\rtos\embOS folder of the IAR Embedded Workbench, you may want to backup these files. You should also check the version number of the plug-in inside embOSPlugin.ewplugin. Therein, the version number is shown as the last entry and looks like follows:

The first part, 8.30, is the major version number and indicates the C-Spy SDK this plug-in was created with. Typically, it is not recommended to replace previous plugin versions with more recent major versions, but with more recent minor versions only. Minor versions are indicated by the second part of the version number, i.e.

3.6. It’s recommended to replace the plug-in currently installed with your Embedded Workbench if its minor version is lower than the minor version of the plug-in that is shipped with embOS.

13 CHAPTER 2 Configuration

2.2 Configuration

By default, embOS start projects will enable the embOS C-Spy plug-in upon project load. The plug-in may be explicitly disabled, individually for each project configuration, in the debugger section of the project’s options:

Chapter 3 Getting Started

This chapter describes the embOS C-Spy plug-in and its capabilities in greater detail.

15 CHAPTER 3 Overview

3.1 Overview

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. A Release build, for instance, won’t show any information about semaphores, queues, event objects, or mailboxes.

16 CHAPTER 3 Task List

3.2 Task List

Column Description

* A green arrow points at the task that is currently executed.

Prio The priority of the task.

Id The task control block address that uniquely identifies a task.

Name If available, the task name is shown here.

The task status as a short text. If the task is waiting for an OS object

Status

Timeout

Stack Info

Run count The number of times a task has been activated by the scheduler.

Time slice

Events The event mask of a task.

(e.g. semaphore), the object’s type and control block address is given and, in paranthesis, the object’s identifier (if any).

If a task is blocked with timeout, this column shows the remaining timeout value in system ticks and, in parenthesis, the system time at which the timeout will expire.

If available, this column shows the maximum used amount of stack, the total stack size, and the stack’s base address which uniquely identifies a task stack.

If round-robin scheduling is available, this column shows the number of currently remaining time slices and the time slice reload value.

3.2.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 for several CPUs. This means that they show the position in the code, the general-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 underlayed 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 17 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.

The task sensitive source window, call stack and register window are supported for the following CPUs:

• ARM7 / ARM9

• ARM Cortex-A

• ARM Cortex-R

• ARM Cortex-M

• Renesas M16C

• Renesas R32C

• Renesas RL78

17 CHAPTER 3 Task List

• Renesas RX

• Renesas SH2A

3.2.1.1 State of suspended tasks

Blocked tasks

Tasks which have given up execution voluntarily by calling a blocking function, such as OS_Delay() or OS_Wait_…(). In this case, the OS saved all registers which can be viewed in the Register window. It might be that scratch registers are not saved and thus not displayed in the Register window.

Tasks waiting for first activation

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

18 CHAPTER 3 Task List

19 CHAPTER 3 Timers

3.3 Timers

Column Description

Id The timer control block address that uniquely identifies a timer.

Name If available, the respective object identifier is shown here.

Hook The function (address and name) that is called after the timeout.

Timeout

Period The timer’s periodicity in system ticks.

Active Indicates whether the timer is currently active (running) or not.

This column shows the remaining timer period in system ticks and, in parenthesis, the system time at which the timer will expire.

20 CHAPTER 3 Mailboxes

3.4 Mailboxes

This view displays information in debug builds of embOS only.

Column Description

Id The mailbox control block address that uniquely identifies a mailbox.

Name If available, the respective object identifier is shown here.

Messages

Message size The size of an individual message in bytes. pBuffer The message buffer address.

Waiting tasks

The number of messages in a mailbox and the maximum number of messages the mailbox can hold.

The list of tasks that are waiting for the mailbox (address and, if available, name). Only those tasks that are displayed in the task list window may be shown here.

21 CHAPTER 3 Queues

3.5 Queues

With embOS V4.38 and subsequent versions, this view displays information in debug builds of embOS only.

Column Description

Id The queue control block address that uniquely identifies a queue.

Name If available, the respective object identifier is shown here.

Messages The number of messages in a queue. pBuffer Address of the buffer which contains the messages.

Buffer size The size of the message buffer.

The list of tasks that are waiting for the queue (address and, if avail-

Waiting tasks

able, name). Only those tasks that are displayed in the task list window may be shown here.

22 CHAPTER 3 Mutexes

3.6 Mutexes

Column Description

Id The mutex control block address that uniquely identifies a mutex.

Name If available, the respective object identifier is shown here.

Owner The address and name of the owner task.

Use counter Counts the number of semaphore uses.

The list of tasks that are waiting for the semaphore (address and, if

Waiting tasks

available, name). Only those tasks that are displayed in the task list window may be shown here.

23 CHAPTER 3 Semaphores

3.7 Semaphores

This view displays information in debug builds of embOS only.

Column Description

Name If available, the respective object identifier is shown here.

Count Counts how often this semaphore can be claimed until it blocks.

Waiting tasks

The semaphore control block address that uniquely identifies a semaphore.

The list of tasks that are waiting for the semaphore (address and, if available, name). Only those tasks that are displayed in the task list window may be shown here.

24 CHAPTER 3 Memory Pools

3.8 Memory Pools

Column Description

Name If available, the respective object identifier is shown here.

Total blocks Shows the available blocks and the maximal number of blocks.

Block size Shows the size of a single memory block.

Max. usage

pPool The address of the memory pool buffer.

Waiting tasks

The memory pool control block address that uniquely identifies a memory pool.

Shows the maximal count of blocks which were simultaneously allocated.

The list of tasks that are waiting for free blocks in the memory pool (address and, if available, name). Only those tasks that are displayed in the task list window may be shown here.

25 CHAPTER 3 Event Objects

3.9 Event Objects

This view displays information in debug builds of embOS only. This view displays information with embOS V4.38 and subsequent versions only.

Column Description

Name If available, the respective object identifier is shown here.

Signaled

Reset Mode The event objects reset mode.

Mask Mode

Waiting tasks

The event object control block address that uniquely identifies an event object.

The hexadecimal value of the bit mask containing the signaled event bits.

The current mask mode indicating whether Or or And logic is used to check whether a task shall resume.

The list of tasks that are waiting for an event object (address and, if available, name). Only those tasks that are displayed in the task list window may be shown here.

26 CHAPTER 3 Watchdogs

3.10 Watchdogs

This view displays information with embOS V4.38 and subsequent versions only.

Column Description

Name If available, the respective object identifier is shown here.

Timeout

Period The period in which the watchdog has to be fed.

The watchdog control block address that uniquely identifies a watchdog.

This column shows the remaining time in system ticks and, in parenthesis, the system time at which the watchdog needs to be fed.

27 CHAPTER 3 System Information

3.11 System Information

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

28 CHAPTER 3 Settings

3.12 Settings

To avoid endless requests in case of erroneous data in target memory, the embOS C-Spy plug-in imposes several limits on the amount of information retrieved from the target. It also configures an entry point for the plug-in at which it will start reading data from the target to avoid accessing invalid data and/or uninitialized memory, e.g. when the debug session is halted during start-up.

The settings dialog allows to configure these limits and the entry point for the plug-in:

29 CHAPTER 3 Settings

Setting

Maximum string length

Maximum number of tasks

Maximum number of mutexes

Maximum number of semaphores

Maximum number of mailboxes

Maximum number of queues

Maximum number of timers

Maximum number of memory pools

Maximum number of event objects

Maximum number of watchdogs

Maximum waitlist length

Permissible

1 to 1024

1 to 256

1 to 64

Perform stack check n/a

Maximum stack check length

Enable plug-in at function

1 to 65,536

n/a

Function name n/a

values

Description

Maximum number of characters to read for each string (e.g. task names).

Maximum number of tasks to display in the Task List.

Maximum number of mutexes to display in the Mutexes view.

Maximum number of semaphores to display in the Semaphores view.

Maximum number of mailboxes to display in the Mailboxes view.

Maximum number of queues to display in the Queues view.

Maximum number of timers to display in the Timers view.

Maximum number of memory pools to display in the Memory Pools view.

Maximum number of event objects to display in the Event Objects view.

Maximum number of watchdogs to display in the Watchdogs view.

Maximum number of waiting tasks to display in the Mutexes, Semaphores, Mailboxes, Queues, Memory Pools, and Event Objects views.

Enables/disables the calculation and display of stack usage information in the Task List.

Maximum number of bytes used to calculate and display in the stack usage information in the Task List.

Enables/disables an entry point for the plug-in. If checked, the plug-in will become active when the target executes the specified function. If unchecked, the plug-in will become active with the start of the debug session.

Name of the function to be used as an entry point for the plug-in.

When clicking the OK button, all entries are checked for valid values. If valid, the settings are applied immediately.

The plug-in settings are stored inside the Windows registry at HKEY_CURRENT_USER\Soft- ware\SEGGER\embOS plug-in for IAR C-Spy 6 and 7 for plug-in versions 6.x and 7.x, at HKEY_CURRENT_USER\Software\SEGGER\embOS plug-in for IAR C-Spy 8 for plug-in version 8.x, and at HKEY_CURRENT_USER\Software\SEGGER\embOS plug-in for IAR C- Spy 9 for plug-in version 9.x.

30 CHAPTER 3 About

3.13 About

The About dialog box contains the embOS C-Spy plug-in version number.

Chapter 4 Support

32 CHAPTER 4 Contacting support

4.1 Contacting support

This chapter should help if any problem occurs and describes how to contact the embOS support.

If you are a registered embOS user there are different ways to contact the embOS support:

1. You can create a support ticket via email to ticket_embos@segger.com.

2. You can create a support ticket at segger.com/ticket.*

3. You can send an email to support_embos@segger.com.*

Please include the following information in the email or ticket:

• Which embOS do you use? (CPU, compiler).

• The embOS version.

• Your embOS registration number.

• If you are unsure about the above information you can also use the name of the embOS zip file (which contains the above information).

• A detailed description of the problem.

• Optionally a project with which we can reproduce the problem.

Note

Even without a valid license, feel free to contact our support e.g. in case of questions during your evaluation of embOS or for hobbyist purposes.

Please also take a few moments to help us improve our services by providing a short feedback once your support case has been solved.

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

to our privacy policy which is available at https://www.segger.com/legal/privacy-policy/.

SEGGER embOS Operating Instruction

Specifications and Main Features

Frequently Asked Questions

User Manual

About this document

Table of contents

9 CHAPTER 1 Overview

10 CHAPTER 1 Supported Embedded Workbench variants

12 CHAPTER 2 Installation Procedure

13 CHAPTER 2 Configuration

15 CHAPTER 3 Overview

16 CHAPTER 3 Task List

19 CHAPTER 3 Timers

20 CHAPTER 3 Mailboxes

21 CHAPTER 3 Queues

22 CHAPTER 3 Mutexes

23 CHAPTER 3 Semaphores

24 CHAPTER 3 Memory Pools

25 CHAPTER 3 Event Objects

26 CHAPTER 3 Watchdogs

27 CHAPTER 3 System Information

28 CHAPTER 3 Settings

The About dialog box contains the embOS C-Spy plug-in version number.

32 CHAPTER 4 Contacting support