SEGGER's embOS plug-in for IAR Embedded Workbench provides embOS awareness during debugging sessions. This enables you to inspect the state of several embOS primitives such as the task list, resource semaphores, mailboxes, or timers.

Requirements

In order to use the embOS IAR plug-in you need a version of IAR's Embedded Workbench installed and a debug target which uses embOS. Specifically:

• An embOS version 3.28 or higher is required. Older embOS versions use different internal structures and the plug-in is therefore of limited use with version prior to 3.28.
• An IAR Embedded Workbench IDE with a C-SPY debugger version 4.3 or higher is required.

Supported CPUs

The embOS plug-in works with 16-bit or 32-bit CPUs in little- or big-endian mode supported by embOS, but due to limited testing, support can only be granted for the CPUs listed below:

• Any ARM7 / ARM9 CPU
• Any ARM Cortex M0 CPU
• Any ARM Cortex M3 CPU
• Atmel AVR / ATMega
• Renesas H8/H8S
• Renesas M16C
• Renesas M16C80
• Renesas M32C
• Renesas R32C
• Renesas R8C
• Renesas RX
• Renesas SH2A
• Renesas (NEC) V850 / V850E / V850ES / V850E2
• Renesas (NEC) 78/K0
• TI MSP430 / MSP430x

How to get the embOS plugin

Every embOS download includes the latest embOS plugin. If it is not included please use the embOS plugin that comes with the IAR embedded workbench.

Installation and Configuration

Installation

The installation procedure is very straightforward since it only requires you to copy the contents of the embOS plug-in package into the IAR CPU specific plug-in directory. The directory structure may look like this:

Create a directory embOS below pluginsrtos in your IAR installation directory. Extract the contents of the embOS plug-in ZIP file into this directory and restart the IAR workbench.

Configuration

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

That's all. The embOS plug-in is now available in debugging sessions and may be accessed from the main menu.

Getting started

Overview

During your debugging session, the embOS plug-in is accessible from the IAR Embedded Workbench main menu. Please 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 certain part is not available, the respective menu item is either grayed out or the window column shows a "N/A".

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

The individual columns are described below:

Column	Description
*	A green arrow points at the currently active embOS task.
Prio	Priority of the task.
Id	The task control block address that uniquely identifies a task.
Name	If available the task name is show here.
Status	The task status as a short text.
Timeout	If a task is delayed, this column shows the timeout value and in parentheses the point in time when the delay will be finished.
Stack Info	If available, this column shows the amount of used stack space, and the available stack space, as well as the value of the current stack bottom pointer.
Run count	The number of task activations.
Time slice	If round robin scheduling is available, this column shows the number of remaining time slices and the number of time slice reloads.
Events	The event mask of a task.

Task sensitivity

To use the Task sensitivity feature of embOS, embOS software version 3.62 or higher and IAR Embedded Workbench V5.20 or higher, is required.
Currently the Task sensitivity feature is available for the following CPUs:

• Any ARM7 / ARM9 / ARM11 and XScale core
• Any ARM Cortex M3 CPU
• Renesas M16C
• Renesas R32C
• Renesas RX
• Renesas SH2A

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

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

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 values of all registers, including the scratch registers.

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.
Messages	Shows the number of messages in a mailbox and the maximum number of messages as mailbox can hold.
Message size	The size of an individual message.
pBuffer	The message buffer address.
Waiting tasks	Shows the list of tasks that are waiting on a mailbox, that is their address and name.

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.
Time	The time delay and the point in time, the timer finishes waiting.
Period	The time period the timer runs.
Active	Shows whether the timer is active or not.

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 owning task.
Use counter	Counts the number of semaphore uses.
Waiting tasks	Lists the tasks (address and name) that are waiting at the semaphore.

System information

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

Settings

To be safe, the embOS plug-in imposes certain limits on the amount of information retrieved from the target, to avoid endless requests in case of false values in the target memory. This dialog allows you to tweak these limits in a certain range, e.g. if your task names are no longer that 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 pressing the OK button, your changes are applied immediately and should become noticeable after the next window update, e.g. when hitting the next breakpoint. However the settings are restored to their defaults on plugin reload.