embOS

Real-Time Operating System

embOS plug-in for IAR C-Spy Debugger

Document: UM01025
Software Version: 3.1
Revision: 0
Date: May 3, 2018

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.
© 2005-2018 SEGGER Microcontroller GmbH, 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 respective holders.

Contact address
SEGGER Microcontroller GmbH
In den Weiden 11
D-40721 Hilden

Germany

Tel. +49 2103-2878-0

Fax. +49 2103-2878-28
E-mail: support@segger.com
Internet: www.segger.com

embOS plug-in for IAR C-Spy Debugger © 2005-2018 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: May 3, 2018

Software Revision Date By Description

3.1 0 180503 MC 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.

3.0 0 170915 MM New plug-in versions 6.10.3.0, 7.10.3.0, 7.50.3.0, and 8.10.3.0.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
4

embOS plug-in for IAR C-Spy Debugger © 2005-2018 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.

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 doc-
Reference
uments.
GUIElement Buttons, dialog boxes, menu names, menu commands.
Emphasis Very important sections.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
6

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
7

Table of contents

1 Introduction ....................................................................................................................8
1.1 Overview ...................................................................................................... 9
1.2 Supported CPUs ........................................................................................... 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 ........................................................................................................ 18
3.4 Mailboxes .................................................................................................... 19
3.5 Queues ....................................................................................................... 20
3.6 Resource Semaphores .................................................................................. 21
3.7 Counting Semaphores ...................................................................................22
3.8 Memory Pools .............................................................................................. 23
3.9 Event Objects .............................................................................................. 24
3.10 Watchdogs .................................................................................................25
3.11 System Information .................................................................................... 26
3.12 Settings .................................................................................................... 27
3.13 About ........................................................................................................28

4 Support ........................................................................................................................29
4.1 Contacting Support ...................................................................................... 30

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
 Chapter 1

Introduction

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

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
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, counting semaphores, resource semaphores, mailboxes, soft-
ware 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 inter-
ruptible and so efficient that embOS can be used in very time critical situations. The mem-
ory footprint in both RAM and ROM is so small that embOS can be used in single-chip ap-
plications, 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 em-
bedded applications using assembler, C and C++. It provides a completely integrated de-
velopment 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-spe-
cific support for each chip.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
10 CHAPTER 1 Supported CPUs

1.2 Supported CPUs

The embOS C-Spy plug-in works with 8-bit, 16-bit or 32-bit CPUs in little- or big-endian
mode. 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:

Compatible
embOS Port IAR Embedded Workbench Version
Plug-In version
≤ 4.80 6.10.3.1
78K0
≥ 4.81 7.10.3.1
≤ 8.30 6.10.3.1
8051 ≥ 9.10 and ≤ 9.30 7.10.3.1
≥ 10.10 8.10.3.1
≤ 6.70 6.10.3.1
≥ 7.10 and ≤ 7.40 7.10.3.1
ARM7 / ARM9
≥ 7.50 and ≤ 7.80 7.50.3.1
Cortex-A/R/M
≥ 8.10 and ≤ 8.22 8.10.3.1
≥ 8.30 8.30.3.1
≤ 6.40 6.10.3.1
AVR ≥ 6.50 and ≤ 6.80 7.10.3.1
≥ 7.10 8.10.3.1
≤ 4.21 6.10.3.1
AVR32
≥ 4.30 7.10.3.1
Coldfire Any 3.82.3.1
≤ 3.20 6.10.3.1
CR16C
≥ 3.30 7.10.3.1
H8 Any 6.0.1.0
≤ 3.60 6.10.3.1
M16C
≥ 3.70 7.10.3.1
M32C Any 6.0.1.0
≤ 5.60 6.10.3.1
MSP430 ≥ 6.10 and ≤ 6.50 7.10.3.1
≥ 7.10 8.10.3.1
R32C Any 6.10.3.1
≤ 1.30 7.10.3.1
RH850
≥ 1.40 7.50.3.1
≤ 1.30 6.10.3.1
RL78 ≥ 1.40 and ≤ 2.21 7.10.3.1
≥ 3.10 8.10.3.1
≤ 2.50 6.10.3.1
RX ≥ 2.60 and ≤ 2.90 7.10.3.1
≥ 3.10 8.10.3.1
SH Any 6.10.3.1
≤ 1.42 6.10.3.1
STM8
≥ 2.10 7.10.3.1
≤ 4.10 6.10.3.1
V850
≥ 4.20 7.10.3.1

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
 Chapter 2

Installation

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

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
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 Work-
bench 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:
<version>8.30.3.1</version>
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 plug-
in 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.1. 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.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
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:

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
 Chapter 3

Getting Started

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

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
15 CHAPTER 3 Overview

3.1 Overview
During your debugging session, the embOS C-Spy plug-in is accessible from the IAR Em-
bedded 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 infor-
mation. 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.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
16 CHAPTER 3 Task List

3.2 Task List

Column Description
* A green arrow points at the currently active embOS task.
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. The name in the parentheses belongs
Status
to the object (semaphore, mailbox, etc.) the task is waiting for.
If a task is delayed, this column shows the timeout value and in
Timeout
parentheses the point in time when the delay will be finished.
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.

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
• Renesas RX
• Renesas SH2A

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
17 CHAPTER 3 Task List

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.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
18 CHAPTER 3 Timers

3.3 Timers

Column Description
Id The timer’s address.
Name If available, the respective object identifier is shown here.
Hook The function (address and name) that is called after the timeout.
Timeout The time delay and the point in time, when the timer finishes waiting.
Period The time period the timer runs.
Active Shows whether the timer is active (running) or not.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
19 CHAPTER 3 Mailboxes

3.4 Mailboxes
This view displays information in debug builds of embOS only.

Column Description
Id The mailbox address.
Name If available, the respective object identifier is shown here.
The number of messages in a mailbox and the maximum number of
Messages
messages the 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 the mailbox (address and, if avail-
Waiting tasks able, name). Only those tasks that are displayed in the task list window
are shown here.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
20 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 address.
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
are shown here.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
21 CHAPTER 3 Resource Semaphores

3.6 Resource Semaphores

Column Description
Id The resource semaphore address.
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 are shown here.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
22 CHAPTER 3 Counting Semaphores

3.7 Counting Semaphores

This view displays information in debug builds of embOS only.

Column Description
Id The counting semaphore address.
Name If available, the respective object identifier is shown here.
Count Counts how often this semaphore can be claimed until it blocks.
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 are shown here.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
23 CHAPTER 3 Memory Pools

3.8 Memory Pools

Column Description
Id The memory pool address.
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.
Shows the maximal count of blocks which were simultaneously allocat-
Max. usage
ed.
pPool The address of the memory pool buffer.
The list of tasks that are waiting for free blocks in the memory pool
Waiting tasks (address and, if available, name). Only those tasks that are displayed
in the task list window are shown here.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
24 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
Id The event object address.
Name If available, the respective object identifier is shown here.
The hexadecimal value of the bit mask containing the signaled event
Signaled
bits.
Reset Mode The event objects reset mode.
The current mask mode indicating whether Or or And logic is used to
Mask Mode
check whether a task shall resume.
The list of tasks that are waiting for an event object (address and, if
Waiting tasks available, name). Only those tasks that are displayed in the task list
window are shown here.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
25 CHAPTER 3 Watchdogs

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

Column Description
Id The watchdog address.
Name If available, the respective object identifier is shown here.
The remaining time (and the system time in parentheses) until the
Timeout
watchdog has to be fed.
Period The period in which the watchdog has to be fed.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
26 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.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
27 CHAPTER 3 Settings

3.12 Settings
in order to avoid endless requests in case of erroneous data in the target memory, the
embOS C-Spy plug-in imposes certain limits on the amount of information retrieved from
the target. This dialog box allows you to tweak these limits within a certain range. For
example, if your task names are no longer than 32 characters, you might want to configure
the Max. string length to 32. Alternatively, if task names are longer than the default
value, you may increase that value according to your needs.

When clicking the OK button, changes to the settings are applied immediately and become
visible in the plug-in windows upon the next window update, e.g. when hitting a breakpoint.
However, the settings are restored to their default values on plug-in reload.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
28 CHAPTER 3 About

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

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
 Chapter 4

Support

This chapter contains information about contacting support and what information to pro-
vide.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH
30 CHAPTER 4 Contacting Support

4.1 Contacting Support

We work hard to avoid as much software defects as possible. However, if you encounter
an error in our software, you may contact our support at support_embos@segger.com. We
will try to correct any malfunction as soon as possible. To do this, we need all relevant
information. Please try to provide us with at least the following information:
• IAR Embedded Workbench IDE & C-SPY debugger versions.
• Information about the target CPU.
• embOS C-Spy plug-in version number.
• A detailled description of the problem and how to reproduce it.
• If possible send us a project that triggers the problem.

embOS plug-in for IAR C-Spy Debugger © 2005-2018 SEGGER Microcontroller GmbH