MULTI: Developing for osCAN
Green Hills Software, Inc.
30 West Sola Street
Santa Barbara, California 93101
USA
Tel: 805-965-6044
Fax: 805-965-6343
www.ghs.com
DISCLAIMER
GREEN HILLS SOFTWARE, INC., MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT
TO THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. Further, Green Hills Software, Inc.,
reserves the right to revise this publication and to make changes from time to time in the content hereof without obligation
of Green Hills Software, Inc., to notify any person of such revision or changes.
Copyright © 1983-2004 by Green Hills Software, Inc. All rights reserved. No part of this publication may be reproduced,
stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording,
or otherwise, without prior written permission from Green Hills Software, Inc.
Green Hills, the Green Hills logo, CodeBalance, GMART, GSTART, INTEGRITY, and MULTI are registered
trademarks of Green Hills Software, Inc. AdaMULTI, EventAnalyzer, G-Cover, GHnet, GHnetLite, Green Hills Probe,
Integrate, ISIM, PathAnalyzer, Quick Start, ResourceAnalyzer, Safety Critical Products, Slingshot, SuperTrace Probe,
TimeMachine, and TotalDeveloper are trademarks of Green Hills Software, Inc.
All other company, product, or service names mentioned in this book may be trademarks or service marks of their
respective owners.
PubID: 10240
April 28, 2004
Contents
1
Introduction
The MULTI Integrated Development Environment
The MULTI Launcher
MULTI Workspaces
The MULTI 4.0 Document Set
Online Help
Viewing Help on Windows Systems
Viewing Help on UNIX Systems
Conventions Used in This Book
2
Using MULTI for osCAN
Installing MULTI for osCAN
Starting MULTI for osCAN
Work Flow
The OIL Configurator and Generator
The MULTI Builder and Debugger
Unsupported Features
3
1
2
4
5
6
7
7
8
9
11
13
13
14
15
18
19
Using the MULTI for osCAN Kernel-Aware
21
Windows
The osCAN Information Window
Task Windows
The Task List Window
The Task Information Window
Alarms Windows
The Alarm List Window
The Alarm Information Window
The Resource List Window
Message Windows
The Message List Window
The Message Information Window
23
25
25
26
31
31
32
34
34
35
36
Index
39
Green Hills Software, Inc.
i
Contents
ii
MULTI: Developing for osCAN
Chapter 1
Introduction
This Chapter Contains:
• The MULTI Integrated Development Environment
• The MULTI Launcher
• The MULTI 4.0 Document Set
• Online Help
• Conventions Used in This Book
1. Introduction
This chapter provides an overview of the MULTI Integrated Development
Environment and its documentation set.
The MULTI Integrated Development Environment
MULTI is a complete Integrated Development Environment (IDE) designed
especially for embedded systems engineers to assist them in analyzing, editing,
compiling, optimizing, and debugging embedded applications.
The MULTI IDE includes graphical tools for each part of the software
development process. The following tools can be launched from within the IDE
or as separate standalone programs:
• IDE launcher
MULTI Launcher (mstart) — The gateway to the MULTI IDE, which
allows you to quickly launch any of the primary MULTI tools, access
open windows, and manage MULTI workspaces
• Editing tools
MULTI Editor (me) — A graphical editor for modifying text files
Checkout Browser (mcobrowse) — A graphical viewer for files
managed under a version control system
Diff Viewer (diffview) — A graphical viewer that displays differences
between two text files
Hex Editor (mhexedit) — A graphical editor for modifying binary files
• Building tools
MULTI Builder (mbuild) — A graphical interface for managing and
building projects
CodeBalance (codebalance) — A graphical interface for automating the
process of optimizing an executable for size or speed
INTEGRATE (integrate) — A graphical utility for configuring tasks,
connections, and kernel objects across multiple address spaces when
using the INTEGRITY RTOS
Linker Directives File Editor (mldedit) — A graphical editor for
creating and modifying linker directives files
2
MULTI: Developing for osCAN
The MULTI Integrated Development Environment
• Debugging tools
MULTI Debugger (multi) — A graphical source-level debugger
EventAnalyzer (mevgui) — A graphical viewer for monitoring
the complex real-time interactions of an embedded RTOS such as
INTEGRITY or ThreadX
ResourceAnalyzer (wperf) — A graphical viewer for monitoring
the CPU and memory usage of an embedded system running the
INTEGRITY RTOS
Script Debugger (mscriptdbg) — A graphical debugger for writing,
recording, and debugging scripts containing MULTI commands
Serial Terminal (mterminal) — A serial terminal emulator for
connecting to serial ports on embedded devices
• Miscellaneous and administrative tools
Bug Report (gbugrpt) — A utility for providing system configuration
and tool version information to the Green Hills support staff
Green Hills Probe Administrator (gpadmin) — A graphical interface
for configuring and managing Green Hills Debug Probes (Slingshots,
Green Hills Probes, and/or SuperTrace Probes)
Graphical Utilities (wgutils) — A collection of utilities for analyzing
and performing various operations on object files, libraries, and
executables produced with the Green Hills toolchain
MULTI License Administrator (mlmadmin) — A graphical utility for
managing Green Hills tools licenses
Green Hills Software, Inc.
3
1. Introduction
The MULTI Launcher
The MULTI Launcher (mstart) provides a convenient way to launch frequently
used tools, to create new or access recently used files and projects, and to
manage MULTI workspaces. All of the main MULTI components can be
accessed using the following buttons:
•
•
•
•
•
•
•
•
•
•
•
— Runs a shortcut or an action sequence in the current workspace. Also
allows you to create a new workspace or create or edit a shortcut.
— Opens the Builder on a recent or new project.
— Opens the Debugger on a recent or new executable.
— Opens the Editor on a recent or new file.
— Opens the Checkout Browser on a recent or new checkout.
— Opens the Connection Organizer or a recent or new target connection.
— Opens a Serial Terminal using a recent or new connection.
— Opens the EventAnalyzer (licensed separately).
— Opens the ResourceAnalyzer (licensed separately).
— Closes the MULTI Launcher (UNIX only by default).
— Shows/hides the detail pane of the Launcher.
You can also launch the Green Hills License Administrator and (if installed) the
Green Hills Probe Administrator from the Utilities menu.
During development, you can use the MULTI Launcher as a convenient
centralized window manager. You can access any of your open MULTI
windows from the Windows menu of the Launcher.
4
MULTI: Developing for osCAN
The MULTI Launcher
MULTI Workspaces
The MULTI Launcher allows you to create and use workspaces. A MULTI
workspace is a virtual area where the tools, files, and actions required for a
particular project can be organized, accessed, and executed.
A workspace is typically created for each top-level project and includes a
working directory and a group of related actions — for example, opening a
project in the MULTI Builder, connecting to a target, or performing a shell
command. Actions are grouped into action sequences, so that a single mouse
click can perform all the actions in the specified action sequence.
For more information, see Chapter 5, “Using MULTI Workspaces and
Shortcuts” in the MULTI: Editing Files and Configuring the IDE book.
Green Hills Software, Inc.
5
1. Introduction
The MULTI 4.0 Document Set
The primary documentation for using MULTI is provided in the following
books:
• MULTI: Getting Started — Describes how to install MULTI and obtain a
license, and takes you through creating, building, and debugging an example
project.
• MULTI: Editing Files and Configuring the IDE — Describes how to use the
MULTI Editor, how to use a version control system with MULTI, how to use
the MULTI Launcher, and how to configure and license the MULTI IDE.
• MULTI: Building Applications — Describes how to use the MULTI Builder
and compiler drivers and the tools that compile, assemble, and link your
code. Also describes the Green Hills implementation of supported high-level
languages.
• MULTI: Configuring Connections — Describes how to set up your target
debugging interface for use with MULTI and how to configure connections
to your target.
• MULTI: Debugging — Describes how to use the MULTI Debugger and
its associated tools.
These books, and any others you may have received (for example, for the
INTEGRITY or ThreadX operating system, or for the Green Hills Debug
Probes) are available in the following formats:
• A printed book
• Online help, accessible from most MULTI windows via the Help →
Manuals menu (see “Online Help” on page 7)
• An electronic PDF, available in the manuals subdirectory of your installation
Note New or updated information may have become available while this
book was in production. For additional material that was not available at press
time, or for revisions that may have become necessary since this book was
printed, please check your CD-ROM for Release Notes, README files, and
other supplementary documentation.
6
MULTI: Developing for osCAN
Online Help
Online Help
The MULTI online help system provides three different types of online help:
• Full online manuals — You can access an indexed hypertext version of
any MULTI manual by selecting it from the list that appears in the Help
→ Manuals menu.
• Context-sensitive help — Many MULTI windows and dialog boxes are
linked to specific sections of the online manuals. To view the page in online
help that documents an active window or dialog box:
(Windows) Press F1.
(UNIX) Press F1 or Help.
If you are using the MULTI Editor, you can also open context-sensitive
help about a button or a menu item by selecting Help → Identify and then
clicking the button or selecting the menu item.
• Debugger command help — You can obtain help information about a
specific MULTI Debugger command by typing help command_name
in the Debugger command pane. This will open the online version of the
MULTI: Debugging book on the section that documents the specified
command. You can also type usage command_name to print to the
command pane the basic syntax of the specified command.
Viewing Help on Windows Systems
Windows systems display online help via the Microsoft HTML Help viewer.
You can view only one manual at a time with the HTML Help viewer.
There are two panes in the HTML Help viewer. The right-hand pane displays
the contents of a selected help page. You can click any underlined link that
appears in right-hand pane to jump to pages about other related topics. The
left-hand pane provides the following three navigation tabs:
• Contents — Displays the chapter and section headings for the manual
being viewed. Click a plus or minus icon to show or hide headings for
embedded sections. Click a heading to display the associated help page in
the right-hand pane.
• Index — Displays index entries for the manual. Double-click an index entry
to display its help page in the right-hand pane.
Green Hills Software, Inc.
7
1. Introduction
• Search — Provides an interface that allows you to search for specific words
in the manual. Enter a word or phrase in the text box and click List Topics
to display a list of pages related to your search string. Double-click any
entry in the list to display the entry’s help page in the right-hand pane.
Viewing Help on UNIX Systems
Depending on your specific UNIX system, MULTI will automatically choose
one of the following two methods for viewing online help:
• Oracle Help for Java — Displays hypertext version of manuals, including
tables of contents and index entries, and provides full text searching across
multiple manuals, with the ability to sort and rank search results.
This viewer may take up to 30 seconds to initialize and is only available
on systems running Red Hat Linux 7.1 or higher, Solaris 2.6 or higher, or
HP-UX 10.20 or 11.x. Other UNIX systems must use browser-based online
help. If problems occur when MULTI is attempting to start the Oracle
Help for Java application, you will see a message prompting you to use
browser-based help (see below).
The Java Runtime Environment that is included with MULTI has been
configured to use fonts common to most X Window servers. However,
some X Window servers may not display Oracle Help for Java properly. To
configure fonts for the Java Runtime Environment, edit the font.properties
file that is located in the jre/lib directory of your MULTI installation (for
more information, see the Sun Microsystems Java web site).
• Web Browser Help — Displays hypertext version of manuals, including
tables of contents and index entries. In GUI mode, netscape is the default
browser. If netscape is installed on your system and the executable is in
your path, no further configuration should be necessary. In non-GUI mode, a
copy of lynx running inside of an xterm will be used as the default browser.
If you have xterm in your path, no further configuration should be necessary.
For information about using an alternate web browser, see “Using a Custom
Web Browser with UNIX” in Chapter 8, “Configuring and Customizing
MULTI” in the MULTI: Editing Files and Configuring the IDE book.
Note To change your online help settings, choose Config → Options →
General tab, then click Help.
8
MULTI: Developing for osCAN
Conventions Used in This Book
Conventions Used in This Book
All Green Hills documentation assumes that you have a working knowledge
of your host operating system and its conventions, including its command line
and graphical user interface (GUI) modes. For example, you should know how
to use basic commands, how to open, save, and close files, and how to use a
mouse and standard menus.
Green Hills documentation uses a variety of notational conventions to present
information and describe procedures. These conventions are described below.
Convention
Meaning
bold type
Indicates a:
• Filename or pathname
• Command
• Option
• Window title
• Button name
• Menu name or menu choice
Examples
• C:\MyProjects
• setup command
• -G option
• the Task window
• the Browse button
• the File menu
italic type
Indicates that the user should
replace the text in italics with
an appropriate argument,
command, filename, or other
value.
-o filename
ellipsis (...)
Indicates that the preceding
argument or option can be
repeated zero or more times.
debugbutton [name]…
(in command line
instructions)
greater than sign ( > )
Green Hills Software, Inc.
Represents a prompt. Your
actual prompt may be a different > print Test
symbol or string. The > prompt Test
helps to distinguish input from
output in examples of screen
displays.
9
1. Introduction
Convention
Meaning
Examples
pipe ( | )
Indicates that one (and only
one) of the parameters or
options separated by the pipe
or pipes should be specified.
help [command | group]
Indicate optional arguments,
commands, options, and so
on. You can either include or
omit the enclosed elements.
The square brackets should
not appear in your actual
command.
.macro name [list]
(in command line
instructions)
square brackets ( [ ] )
(in command line
instructions)
(The square brackets
indicate that an argument
is optional. If an
argument is specified,
however, it must be either
a command or a group.)
The following command description demonstrates the use of some of these
typographical conventions.
gxyz [-option]… filename
The formatting of this command indicates that:
• The command gxyz should be entered as shown.
• The option -option should either be replaced with one or more appropriate
options or be omitted.
• The word filename should be replaced with the actual filename of an
appropriate file.
The square brackets and the ellipsis should not appear in the actual command
you enter.
10
MULTI: Developing for osCAN
Chapter 2
Using MULTI for osCAN
This Chapter Contains:
• Installing MULTI for osCAN
• Work Flow
• The OIL Configurator and Generator
• The MULTI Builder and Debugger
• Unsupported Features
2. Using MULTI for osCAN
The osCAN real-time operating system is an OSEK-compliant operating system
developed by Vector Informatik, GmbH. OSEK is a German acronym for Offene
Systeme und deren Schnittstellen für die Elektronik im Kraftfahrzeug
(Open Systems and the Corresponding Interfaces for Automotive Electronics).
The osCAN operating system is based on the OSEK-OS specification described
in the document OSEK/VDX Operating System Version 2.1 revision 1. You may
also want to review the following related publications and to browse the OSEK
/ VDX (http://www.osek-vdx.org) web site:
• OSEK/VDX Operating System Specification 2.1 r1
• OIL: OSEK Implementation Language - Version: 2.2
• OSEK COM Communication - Version 2.2.2
Green Hills documentation assumes that the reader is familiar with the OSEK
specification.
The MULTI Software Development Environment works seamlessly with
osCAN to provide detailed, kernel-aware information as you debug C, C++,
Embedded C++ and assembly-language source files.
MULTI for osCAN is fully aware of the following osCAN components:
• Tasks
• Alarms
• Resources
• Messages
Each component type has a minimum of two windows associated with it: a list
window, summarizing all created components of that type, and an information
window, showing detailed information about a specific component. Some
components (e.g. tasks) have additional windows to show more detailed
information.
12
MULTI: Developing for osCAN
Installing MULTI for osCAN
Installing MULTI for osCAN
The osCAN software (kernel sources, OIL (OSEK Implementation Language)
Configurator, Generator, Green Hills build files etc.) is delivered by Vector
Informatik. Please follow the installation instructions provided with the osCAN
product. This manual refers to the examples provided by Vector Informatik.
Follow the instructions in MULTI: Getting Started to install and license
MULTI for osCAN. The MULTI installation comes with the following osCAN
kernel-aware files in the defaults/os_aware subdirectory:
• oscan.plc — osCAN description for kernel awareness
• osCAN.bmp — osCAN bitmap (for MULTI Debugger button)
• oscantarget.rc — Target-specific startup script
• oscantarget.plc — Target-specific description for kernel awareness
The supported target architectures and their associated files are as follows:
• ARM — oscanarm.rc and oscanarm.plc
• MIPS — oscanmips.rc and oscanmips.plc
• NEC V850/V850E — oscan85x.rc and oscan85x.plc
Starting MULTI for osCAN
To start MULTI for osCAN, enter the following from the command line:
multi -rc os_aware/oscantarget.rc
where target is one of the following:
• arm — for ARM processors
• mips — for MIPS processors
• 85x — for NEC 850/850E processors
Tip On Windows, MULTI for osCAN may be available to automatically
open MULTI with the correct options. Of course, Windows users can create
their own shortcuts to launch MULTI with the necessary options and in an
appropriate working directory.
Green Hills Software, Inc.
13
2. Using MULTI for osCAN
Work Flow
The general work flow for producing a program using osCAN and MULTI for
osCAN is as follows:
1. Create a new project using the MULTI Builder. For more information, see
Chapter 2, “The MULTI Builder” in the MULTI: Building Applications
book.
2. Add your source files to your project.
3. Use the OIL Configurator to configure osCAN for the application and to
set the kernel-aware debugging options required by MULTI.
4. Invoke the Generator to convert the resultant OIL file into a generated
source file.
5. Use the MULTI Builder to add the generated source file to your project,
then compile the project into an executable.
6. Debug the executable using the MULTI Debugger with its dedicated
osCAN kernel-aware windows.
Tip We recommend that you build an example project provided by Vector
Informatik to explore the various features of MULTI for osCAN. Simply
complete the following procedures using one of the projects contained in the
Appl directory. For example, use the gen_at project located in the Appl/gen_at
directory.
14
MULTI: Developing for osCAN
The OIL Configurator and Generator
The OIL Configurator and Generator
To use MULTI to debug osCAN applications with maximum effectiveness,
you will need to ensure that certain options are selected in the Configurator
before you generate your C code. For detailed information about using the
OIL Configurator and Generator, refer to the osCAN documentation provided
by Vector Informatik.
To set the OIL options needed to run MULTI for osCAN:
1. Start the OIL Configurator. As an example, open the GEN22.OIL file,
which is located in the Appl/gen_at directory.
2. Go to the OS tab and set the STATUS option on the Properties (0) tab
to EXTENDED.
3. If you require all kernel-aware symbols to be present in the generated
source files, then select the GHSDebugSupport option on the Properties
(2) tab. Not selecting the GHSDebugSupport option will reduce the
amount of ROM space that your application requires, but the osCAN
Information Windows will show a dash ( - ) instead of a name for some
kernel objects.
Green Hills Software, Inc.
15
2. Using MULTI for osCAN
4. To monitor maximum stack use, select the WithStackCheck check box
on the Properties (1) tab.
16
MULTI: Developing for osCAN
The OIL Configurator and Generator
5. Set other options needed to configure the kernel resources for your
application. For a list of features that are not fully supported by MULTI,
see “Unsupported Features” on page 19.
6. Invoke the OIL Generator and generate a source file.
Green Hills Software, Inc.
17
2. Using MULTI for osCAN
The MULTI Builder and Debugger
After adding the initial application source code and the generated source code
to a project file (*.gpj), you can build and debug the project with MULTI.
1. To start MULTI from the command line, navigate to your project’s
directory and enter:
multi -rc os_aware/oscantarget.rc your_project.gpj
As an example, navigate to the Appl/gen_at project and specify the build
file that corresponds to your target processor.
2. In the MULTI Builder, navigate to and select the project file, and click the
Build button ( ). MULTI will build the executable image from all the
source files in the project. For more information about the MULTI Builder,
see the MULTI: Building Applications book for your target.
3. Click the Connect button ( ) to connect to a simulator or target, . When
the Connection Chooser appears, select the Connection Method that
corresponds to the simulator or debug server you are using. If a Connection
Method does not exist for your target connection, you can define a new
one. For more information, see Chapter 3, “Connecting to Your Target”
in the MULTI: Debugging book.
In previous versions of MULTI, commands were used to connect to the
target. If you prefer to use this method, click Custom in the Connection
Chooser, then enter the command for your connection. For example, the
command for the V850 simulator is sim850.
4. Click the Debug button ( ) to begin debugging, . The MULTI Debugger
opens with the debug information of the current executable.
5. Click the osCAN button ( ) to open the main osCAN-Information
window (see “The osCAN Information Window” on page 23). This
window gives you access to all the osCAN kernel-aware windows described
in the next chapter. Once you start the executable, these kernel-aware
windows will contain useful information about your application.
18
MULTI: Developing for osCAN
Unsupported Features
For detailed instructions on how to use the MULTI Debugger, see MULTI:
Debugging.
Unsupported Features
The following settings, available in the osCAN Configurator, are not fully
supported by MULTI for osCAN. If they are specified during the configuration
process, some elements may not be displayed correctly.
• Static Alarms — If the StaticAlarm attribute is selected for an alarm, the
displayed cycle time is not correct.
• UseGeneratedFastAlarm (disabled) — If the OS attribute
UseGeneratedFastAlarm is disabled, the expires in ticks value
shows the absolute value of the system timer when the alarm will expire.
• Multiple counters — If multiple counters are used in the system, the display
of the system tick and the counter in the alarm information window is not
correct.
• Resources on interrupt level — The owner of a resource on interrupt level
is not displayed correctly.
• Nested resource access — If resource nesting is used, only the first nesting
level is taken into account in the owner display and in the calculation of the
ceiling priority.
Green Hills Software, Inc.
19
2. Using MULTI for osCAN
20
MULTI: Developing for osCAN
Chapter 3
Using the MULTI for osCAN
Kernel-Aware Windows
This Chapter Contains:
• The osCAN Information Window
• Task Windows
• Alarms Windows
• The Resource List Window
• Message Windows
3. Using the MULTI for osCAN Kernel-Aware Windows
To open the osCAN Information window, click the osCAN button ( ) in the
MULTI Debugger toolbar. This window gives you access to all the kernel-aware
debugging features of MULTI for osCAN, either directly, or through the other
osCAN windows. The following information applies to all such windows:
• Click the green freeze button to freeze the window. The freeze button
becomes a red stop sign. Click the stop sign to make the window active
again. An active window is updated each time the target is stopped.
• Press ctrl-d when a window is in focus to freeze the current window and
create a duplicate, active copy.
• In all windows, click any button to view that component or more detail about
that component. Double-click any list item to view that component.
• If no useful information exists, then clicking a button may have no effect.
For example, if no messages exist in a system, clicking the Message
button in the osCAN Information window will have no effect. Similarly,
if osCAN’s optional stack checking capability has not been invoked,
stack-peak values are indicated with a dash ( - ).
• Text fields in all osCAN windows are read-only. Even if changes are typed
into these fields, they will have no effect other than to disguise the actual
values of those fields.
Note Bear in mind the following information in order to maximize performance:
• All osCAN windows are automatically updated each time the target is
halted, hits a breakpoint, or stops for any other reason.
• The more osCAN windows that are open, the more target data will be sent to
the host system each time the target stops. Some embedded target debug
connections operate at slower speeds, resulting in degraded performance
when many windows are open and need updating. One way to increase
debugging performance is to close unnecessary osCAN windows. Another
way is to selectively freeze windows that do not need updating.
• Near the upper right corner of each osCAN window is the freeze button, a
green dot. When clicked, this button becomes a red stop sign and freezes the
window, preventing it from being updated. Click the stop sign to re-activate
the window and and have it updated the next time the target stops. To force
an update of all active windows, use the Debugger’s update command.
22
MULTI: Developing for osCAN
The osCAN Information Window
The osCAN Information Window
To launch the osCAN Information window, click the osCAN button ( ). This
window provides summary information for osCAN tasks, alarms, resources,
and messages.
The osCAN Information fields display the following information:
Tasks Count
Displays the number of created tasks in the system.
Click the Tasks button to open the Task List window (see “The Task List
Window” on page 25).
Alarms Count
Displays the number of alarms in the system.
Click the Alarms button to open the Alarm List window (see “The Alarm List
Window” on page 31).
Resources Count
Displays the number of user resources in the system.
Click the Resources button to open the Resources window (see “The Resource
List Window” on page 34).
Green Hills Software, Inc.
23
3. Using the MULTI for osCAN Kernel-Aware Windows
Messages Count
Displays the number of messages in the system (empty when no messages are
present).
Click the Messages button to open the Message List window (see “The Message
List Window” on page 35).
Current Task
Displays the task which was executing when the system was stopped. If the
system was not within a task, then System will be displayed. This most commonly
occurs when the StartOS() function has not yet been called.
Click the Current Task button to open a Task Information window showing
details on the task which was executing when the system was stopped.on
the currently executing task when the system was stopped (see “The Task
Information Window” on page 26).
OS Version
Displays the version ID string of the osCAN kernel. Between parentheses is the
code generator version used to generate the C source code.
System Tick
Displays the system clock when the system was halted. This field is in units of
timer ticks.
Error Status
Displays the current error status of the system, one of:
• E_OK
• E_OS_ACCESS
• E_OS_CALLEVEL
• E_OS_ID
• E_OS_LIMIT
• E_OS_NOFUNC
• E_OS_RESOURCE
• E_OS_STATE
• E_OS_VALUE
• E_OS_SYS_DISINT
24
MULTI: Developing for osCAN
Task Windows
Task Windows
These windows display information about osCAN tasks.
The Task List Window
The Task List window shows a list of all tasks in the system. Double-click
any task to display a Task Information window (see “The Task Information
Window” on page 26).
The Task List window columns are described below.
Name
Displays the name of a task, as specified in the OIL Configurator. If
GHSDebugSupport is disabled, the task’s internal Id will be shown.
State
Displays the current execution state of the task when the system was halted.
The task can be in one of five states:
• Running – The task was executing when the system was halted.
• Ready, Pre-Ready – The task is ready to execute. The task will execute
when it is the highest priority task.
• Waiting – The task is waiting for an event.
• Suspended – The task cannot run because it has not been activated.
Stack Size
Displays the amount of stack allocated to the task, as specified in the OIL
Configurator.
Stack Usage
Displays the amount of stack currently in use by the task.
Green Hills Software, Inc.
25
3. Using the MULTI for osCAN Kernel-Aware Windows
Internal Priority
Displays the priority of the task, as assigned by the OIL Generator. The lower the
number, the higher the priority.
User Set Priority
Displays the priority of the task, as specified in the OIL Configurator. The higher
the number, the higher the priority.
Event Status
For extended tasks, this column displays a hex number representing the individual
bits (events) of the system as specified by the user, followed by a slash ( / ) and
the corresponding event mask. A dash ( - ) displays for basic tasks.
Number of Activations
Displays the number of times the task has been requested to be activated.
The Task Information Window
To open a Task Information window, double-click an entry in the Task List
window or click the Current Task button of the main osCAN Information
window (in the latter case the details of the currently running task will be
displayed). Multiple Task Information windows can be opened at one time
and each stays open, showing the current information for the specified task
until closed.
26
MULTI: Developing for osCAN
Task Windows
The items in the Task Information window are described below:
Task Name
Displays the name of a task, as specified in the OIL Configurator.
Current PC
Displays the name of the function in which the task is currently executing. If no
debugging information is available for that location, this field may be displayed as
an offset from a known label or an address in hexadecimal format. This field is
derived from one of the following:
1. The system PC if this task is currently executing.
2. A PC value as stored on the stack for non-current tasks.
Click the Current PC button to display the current PC location in the MULTI
Debugger source pane.
Current SP
Displays the current stack pointer of the task, displayed as a hexadecimal address.
For tasks that are not currently executing, this field corresponds to the value of
the saved task context. For a task that is currently executing, this field displays
the processor’s stack pointer register.
Click the Current SP button to display a memory view of this task’s stack.
Green Hills Software, Inc.
27
3. Using the MULTI for osCAN Kernel-Aware Windows
Stack Size
Displays the amount of stack allocated for this task, as specified in the OIL
Configurator.
Stack Usage
Displays the amount of stack currently in use by the task.
Stack Peak
Displays the maximum amount of stack used by the task so far (the high water
mark). This requires configuring the executable for stack checking (see “The
OIL Configurator and Generator” on page 15 for details). If stack checking in
not enabled, a dash ( - ) is displayed.
State
Displays the current execution state of the task when the system was halted.
The task can be in one of four states:
• Running – The task was executing when the system was halted.
• Ready, Pre-Ready – The task is ready to execute. The task will execute
when it is the highest priority task.
• Waiting – The task is waiting for an event.
• Suspended – The task cannot run because it has not been activated.
Priority
Displays the priority information of the task. The first number is the internal priority
level of the task, as assigned by the OIL Generator (the lower the number, the
higher the priority). The number between parentheses is the user set priority (as
specified in the OIL Configurator) according to the OSEK rule: the higher the
number, the higher the priority. When the priority of a task is temporarily increased
(for example, because it is the owner of a resource), this field displays the new
(Ceiling) priority followed by a slash ( / ).
Policy
Displays the scheduling policy of the task: either Preemptive or
Non-preemptive.
Type
Displays the type of the task: either Basic or Extended.
Event Status
For extended tasks, displays a hex number representing the individual bits (event
flags) of the system as specified by the user, followed by a slash ( / ) and the
corresponding event mask. A dash ( - ) displays for basic tasks.
Auto Start
Specifies automatic startup: either Yes or No.
28
MULTI: Developing for osCAN
Task Windows
Entry Point
Displays the name of the function called upon task startup. If no debugging
information is available for that location, then this field may be displayed as an
offset from a known label or an address in hexadecimal format.
Click the Entry Point button to display the entry point function in the MULTI
Debugger source pane.
Task BP button
Click this button to set a task-specific breakpoint at the current location. For more
details about how to use this button, see “Setting Task-Specific Breakpoints” on
page 29.
Registers button
Click this button to display a Registers window for this task. The Registers
window is not available on every processor architecture. If this button is not
present, the Registers window is not available.
Task List button
Click this button to open the Task List window (see “The Task List Window”
on page 25).
Setting Task-Specific Breakpoints
A task-specific breakpoint is a specific instance of a more general MULTI
feature: the conditional breakpoint. For more details on breakpoints, see
Chapter 5, “Executing and Controlling Your Program from the Debugger” in
the MULTI: Debugging book .
To set a task-specific breakpoint:
1. Go to the part of the source code that contains the statement or assembly
instruction on which you want to set the breakpoint.
2. Click the green break dot . The blue source pointer should now point to
the breakpoint you just set. (In disassembly-only views, such as libraries
where source code is unavailable, no blue arrow will be shown.)
3. Go to the Task Information window for the task you want to debug and
click the TaskBP button (see “The Task Information Window” on page
26). In the case of a task-specific breakpoint, the condition is: current
task index == selected task index.
Green Hills Software, Inc.
29
3. Using the MULTI for osCAN Kernel-Aware Windows
Placing a task-specific breakpoint in the same location as an unconditional
breakpoint will replace the unconditional breakpoint with a task-specific
breakpoint.
Checking Stack Use
MULTI’s enhanced stack checking and monitoring features help you diagnose
and correct problems with stack overflow. You can monitor and adjust each
task’s stack use through the Stack Use indicator in Task Information windows.
The Stack Peak field shows the high water mark, which is the highest point in
the stack that was changed since the task was created.
The Task Registers Window
The Task Registers window is opened by clicking the Registers button in a
Task Information window, and shows the registers for that task. The specific
registers visible depend on the target processor. If the Task Information
window contains the current running task, the regular Debugger Register
window is launched, showing the register values of the processor. For
non-current tasks, the Register window shows the registers that are saved by
the kernel in the context area (typically the stack) of the corresponding task.
This window is not available for all processor architectures. If no Registers
button is present in the Task Information window, the Registers window is
not available.
30
MULTI: Developing for osCAN
Alarms Windows
Alarms Windows
These windows display information about osCAN alarms.
The Alarm List Window
The Alarm List window shows a list of all alarms in the system. Double-click
any alarm to display an Alarm Information window (see “The Alarm
Information Window” on page 32).
The Alarm List window columns are described below.
Name
Displays the name of an alarm, as specified in the OIL Configurator.
State
Displays the state of the alarm: either Active or Inactive.
Expires in
Displays the number of system ticks before the alarm executes the corresponding
action.
Cycle time
Displays the period of a cyclic alarm in ticks. For single (non-cyclic) alarms, a ’0’
is displayed.
Green Hills Software, Inc.
31
3. Using the MULTI for osCAN Kernel-Aware Windows
The Alarm Information Window
The Alarm Information window shows detailed information about an
individual alarm.
The Alarm Information window items are described below:
Name
Displays the name of an alarm, as specified in the OIL Configurator.
State
Displays the state of the alarm: either Active or Inactive.
Expires in
Displays the number of system ticks before the Alarm executes the corresponding
action.
Cycle Time
Displays the period of a cyclic alarm in ticks. For single (non-cyclic) alarms, a ’0’
is displayed.
Counter
Currently fixed to the System counter (1). To be used by future versions of osCAN.
32
MULTI: Developing for osCAN
Alarms Windows
Action Field
Displays the action to be performed when the alarm expires, where the action
is one of the following:
• Activate:
• Send event
taskname
eventflag to taskname
Click the Action button to open a Task Information window for the task affected
by the action.
Alarm List button
Click this button to open the Alarm List window (“The Alarm List Window” on
page 31).
Green Hills Software, Inc.
33
3. Using the MULTI for osCAN Kernel-Aware Windows
The Resource List Window
The Resources window shows a list of all resources in the system. If a resource
is currently owned by a task, double-clicking that resource will display the
corresponding Task Information window (“The Task Information Window”
on page 26).
The osCAN real-time operating system supports one special resource, which is
called RES_SCHEDULER, and which has the highest possible priority (0).
The Resources window columns are described below:
Name
Displays the name of a resource, as specified in the OIL Configurator.
Ceiling Priority
Displays the (internal) ceiling priority level, as assigned by the OIL code generator.
If a task becomes the owner of a resource, its priority level is temporarily changed
to the ceiling priority level of this resource, until the resource is released.
Owner
Displays the task that currently owns the resource. When a resource is not owned
by any task, a dash ( - ) is displayed.
Message Windows
34
MULTI: Developing for osCAN
Message Windows
These windows display information about osCAN messages.
The Message List Window
The Message List window shows a list of all messages in the system.
Double-click any queued message to display a Message Information window
(see “The Message Information Window” on page 36). Double-click any
unqueued message to view the contents of the message structure.
The Message List window columns are described below.
Name
Displays the name of a message, as specified in the OIL Configurator.
Resource
Displays the value of the message resource as defined in the OSEK COM
specification. If a message resource is taken, the resource value will be greater
than zero.
Type
Displays the message type, either Queued or Unqueued. When a message is
queued, the number in parentheses displays the size of the FIFO-buffer.
Green Hills Software, Inc.
35
3. Using the MULTI for osCAN Kernel-Aware Windows
The Message Information Window
The Message Information window shows detailed information about an
individual (queued) message. Double-clicking a queue opens a structure view
of it.
The columns of the Queue List in the Message Information window are
described below.
Message Name
Displays the name of a message, as specified in the OIL Configurator.
Queue
Displays the internal sequence number.
Receiving Task
Displays the task that receives messages from this message queue.
36
MULTI: Developing for osCAN
Message Windows
State
Displays the state of the message queue, one of:
• E_OK
• E_COM_BUSY
• E_COM_ID
• E_COM_LIMIT
• E_COM_LOCKED
• E_COM_NOMSG
• E_COM_RX_ON
Items
Displays the number of items in the message queue, followed by a ’/’ and the
size of the FIFO-buffer.
Message List button
Click this button to open the Message List window (see “The Message List
Window” on page 35).
The columns of the Notification List in the Message Information window
are described below.
Notification
Displays the internal sequence number.
Action
Displays the corresponding action, one of:
• NONE
• TASK
• EVENT
• CALLBACK
• FLAG
Task
Displays the name of the task being notified.
Event
Displays the event flag being sent to the task, in case of an EVENT action.
Green Hills Software, Inc.
37
3. Using the MULTI for osCAN Kernel-Aware Windows
38
MULTI: Developing for osCAN
Index
A
(IDE), see MULTI Integrated
Development Environment (IDE)
alarms
Alarm Information window, 32
Alarm List window, 31
K
B
kernel-aware features
accessing, 22
breakpoints
setting, 29
L
Launcher, see MULTI Launcher
C
context-sensitive help, 7
conventions, typographical, 9
D
document set
overview, 6
updates, 6
F
F1 key, for help, 7
H
help, see online help
Help menu
online help, obtaining, 7
I
installing
MULTI for osCAN, 13
Integrated Development Environment
Green Hills Software, Inc.
M
messages
Message Information window, 36
Message List window, 35
MULTI for osCAN
about, 12
accessing kernel-aware features in, 22
installing, 13
maximizing performance of, 22
osCAN Information window, 22 to 23
setting breakpoints in, 29
setting OIL options for, 15
starting, 13
supported architectures, 13
using, 12, 18
MULTI Integrated Development
Environment (IDE)
document set, 6
online help, 7
overview, 2
MULTI Launcher
overview, 4
39
Index
O
S
online help
Help menu, 7
overview, 7
UNIX systems, 8
Windows systems, 7
osCAN
about, 12
example applications, 13
OIL Configurator, 14 to 15
OIL Generator, 14, 17
osCAN Information window, 22 to 23
stack
monitoring usage, 16, 30
R
resources
Resources window, 34
40
T
tasks
setting task-specific breakpoints, 29
Task Information window, 26
Task List window, 25
Task Registers window, 30
typographical conventions, 9
W
workspaces
overview, 5
MULTI: Developing for osCAN