Wind River System Viewer User's Guide, 3.

Wind River
®

System Viewer
USER'S GUIDE

3.2
Copyright © 2009 Wind River Systems, Inc.
All rights reserved. No part of this publication may be reproduced or transmitted in any
form or by any means without the prior written permission of Wind River Systems, Inc.
Wind River, the Wind River logo, Tornado, and VxWorks are registered trademarks of
Wind River Systems, Inc. Any third-party trademarks referenced are the property of their
respective owners. For further information regarding Wind River trademarks, please see:
http://www.windriver.com/company/terms/trademark.html
This product may include software licensed to Wind River by third parties. Relevant
notices (if any) are provided in your product installation under the following directory:
installDir/product_name/3rd_party_licensor_notice.pdf.

Corporate Headquarters
Wind River Systems, Inc.
500 Wind River Way
Alameda, CA 94501-1153
U.S.A.

toll free (U.S.): (800) 545-WIND

telephone: (510) 748-4100
facsimile: (510) 749-2010

For additional contact information, please visit the Wind River URL:
http://www.windriver.com
For information on how to contact Customer Support, please visit the following URL:
http://www.windriver.com/support

Wind River System Viewer User's Guide, 3.2

10 Nov 09
Part #: DOC-16378-ND-00
 Contents

1 Overview ............................................................................................... 1

1.1 What Is the Wind River System Viewer? ........................................................... 1

1.2 System Viewer Tools .............................................................................................. 2

1.2.1 Accessing System Viewer Logs .............................................................. 3
1.2.2 Accessing System Viewer Tools ............................................................. 3

1.3 System Viewer Architectural Overview (VxWorks) ........................................ 4

2 Familiarization ...................................................................................... 5

2.1 Quick Start ............................................................................................................... 5

2.2 Getting a Log ........................................................................................................... 5

2.3 Navigating a Log ..................................................................................................... 6

2.3.1 Preliminary Analysis in the Overview .................................................. 6
2.3.2 Range Selection in the Overview ........................................................... 7
2.3.3 Selection in the Event Graph .................................................................. 7
2.3.4 Selection in the Event Table .................................................................... 8
2.3.5 More Uncluttering and Clarification ..................................................... 8
2.3.6 Use Linked Views and Multiple Analyses ........................................... 9

iii
 Wind River System Viewer
User's Guide, 3.2

2.3.7 Use Bookmarks ......................................................................................... 9

2.3.8 Save the Analysis ...................................................................................... 9

3 Configuring a Logging Session .......................................................... 11

3.1 Configuration Workflow ....................................................................................... 11

3.2 Beyond the Basics ................................................................................................... 13

3.3 General Notes .......................................................................................................... 13

4 The Event Logging Level ..................................................................... 15

4.1 What is an Event? ................................................................................................... 15

4.2 What is an Event Logging Level? ........................................................................ 16

4.2.1 Which Level Do I Select? ......................................................................... 16

5 The Upload Mode ................................................................................. 19

5.1 Upload Mode Configuration: General Considerations .................................. 19

5.2 Deferred Upload Or Continuous Upload? ........................................................ 20

5.2.1 Deferred Upload ....................................................................................... 20
5.2.2 Continuous Upload .................................................................................. 21
5.2.3 Configuration Options: Deferred Upload and Continuous Upload . 22

5.3 Post-Mortem Upload Modes ................................................................................ 23

5.3.1 Using Post Mortem for Non-Fatal Problems ........................................ 23
5.3.2 Preparation: Kernel Configuration for Post-Mortem Upload ........... 23
Post-Mortem Upload Kernel Configuration ........................................ 24
Post Mortem Mode (using pmLib) Kernel Configuration ................. 25
5.3.3 Rebuild the Kernel and the Boot Loader .............................................. 25
5.3.4 Post-Mortem Upload Mode ................................................................... 26

5.4 System ViewerTroubleshooting Upload Modes .............................................. 27

iv
 Contents

5.4.1 The Ring Buffer ......................................................................................... 27

5.4.2 Symptoms and Solutions ........................................................................ 29
Problem: Logging Stops Prematurely / Ring Buffer Stops Updating 29
Possible Causes ......................................................................... 29
Possible Solutions ...................................................................... 29
Problem: Upload Fails (Continuous Upload Only) ............................. 30
Possible Causes and Solutions ................................................ 30
Problem: Buffer Thrashing (Continuous Upload Only) ..................... 31
Possible Solution ....................................................................... 31

6 The Upload Method .............................................................................. 33

6.1 The Upload Method ............................................................................................... 33

6.1.1 Upload Method Selection Errors ............................................................ 34

6.2 Using the Memory Read Upload Method ......................................................... 34

6.3 Using TSFS Upload Methods .............................................................................. 35

6.4 Automatic Upload of Logs .................................................................................... 35

6.5 Socket Via TSFS and Socket Via TCP/IP Configuration ................................ 37

6.6 File Via TSFS ........................................................................................................... 37

6.7 File Via NFS ............................................................................................................. 38

6.8 File Via netDrv ........................................................................................................ 38

6.9 The Event Receive Utility ..................................................................................... 39

7 Logging and Uploading Data .............................................................. 41

7.1 Start Logging ........................................................................................................... 41

7.2 The Configuration Editor Log Manager ............................................................ 42

7.3 Using the System Viewer API to Control Logging .......................................... 43

wvOn( ) and wvOff( ) .............................................................................. 43
VxWorks API Libraries ............................................................................ 44

v
 Wind River System Viewer
User's Guide, 3.2

7.4 VxWorks Core Dump Log Upload ...................................................................... 44

8 Loading Log Files ................................................................................ 47

8.1 Opening Logs .......................................................................................................... 47

8.1.1 Load Progress View ................................................................................. 48
8.1.2 Errors and Warning Messages on Opening Logs ................................ 48

9 Primary Overviews ............................................................................... 49

9.1 Overview Modes ..................................................................................................... 49

Range Selection in the Overview ........................................................... 50

9.2 All Events ................................................................................................................. 50

9.3 Peak Activity ........................................................................................................... 50

9.4 Event Intensity ........................................................................................................ 51

10 Analysis Types ..................................................................................... 53

10.1 General Notes .......................................................................................................... 53

10.2 Event Graph/Table .................................................................................................. 54

Event Icons and State Stipples ................................................................ 54
Visualization of Multicore Behavior ...................................................... 54

10.3 Memory Usage ........................................................................................................ 55

10.4 Core Usage per Core ............................................................................................... 55

10.5 Core Usage Aggregate ........................................................................................... 56

10.6 System Load ............................................................................................................. 56

Examples of Load Figures ....................................................................... 57

10.7 Running State .......................................................................................................... 58

10.8 Ready State .............................................................................................................. 58

vi
 Contents

11 Filtering and Searching ....................................................................... 59

11.1 Filtering .................................................................................................................... 59

11.1.1 Creating Filters ......................................................................................... 60

11.2 Searching .................................................................................................................. 60

12 Timestamps .......................................................................................... 63

12.1 Timelines .................................................................................................................. 63

12.2 Timestamp Ticks ..................................................................................................... 64

12.3 High-Resolution Timestamping .......................................................................... 64

12.4 Sequential Timestamping ..................................................................................... 65

12.5 Custom Timestamp Drivers ................................................................................. 65

13 Triggering ............................................................................................. 67

13.1 Introduction ............................................................................................................. 67

13.2 Getting Started ........................................................................................................ 68

13.2.1 To Create a Trigger ................................................................................... 68
13.2.2 Using Sample Trigger Files ..................................................................... 69
Understanding Functions with Triggering ........................................... 69

13.3 Using Triggering ..................................................................................................... 69

13.3.1 Using the Trigger Maintenance Utility .................................................. 70
To Create a Trigger ................................................................................... 70
13.3.2 Defining Variables to Validate Triggers ................................................ 73
13.3.3 Downloading and Running Triggers ..................................................... 74
Reading Target Icons ................................................................................ 74
Reading Trigger Icons .............................................................................. 75

13.4 Creating and Running the Sample Triggers ...................................................... 76

vii
 Wind River System Viewer
User's Guide, 3.2

13.4.1 Simple Conditional Trigger Example .................................................... 76

13.4.2 Chaining Simple Conditional Triggers Example ................................. 78
13.4.3 Chaining Triggers for System Viewer Logging Example ................... 80

13.5 Using Functions with Triggering ......................................................................... 83

13.5.1 Using a Function as a Condition ............................................................ 83
Defining and Loading Condition Functions ........................................ 84
Writing Condition Function Code ......................................................... 85
13.5.2 Writing a Call Function as an Action ..................................................... 85
13.5.3 Starting and Stopping System Viewer with User Events ................... 86

13.6 Importing Previous Version Trigger Files .......................................................... 88

14 User Events (VxWorks Family) ............................................................ 91

14.1 Introduction ............................................................................................................. 91

14.2 User Event Display ................................................................................................. 92

14.3 The User Events Description File ........................................................................ 93

14.3.1 Location of the User Events Description File ....................................... 93
14.3.2 Structure of the User Events Description File ...................................... 93
Description of EventRangeDescription Attributes .......................... 95
14.3.3 Editing the User Event EventRangeDescription ................................ 97
14.3.4 Editing a Single User Event, or a Block of User Events ...................... 97
Inserting a New EventRangeDescription ............................................ 99
Inserting New EventDescriptions ......................................................... 100
Using Textual Icons .................................................................................. 101
The Extended Form of the icon Attribute .............................. 101
14.3.5 Example of a Complete VxWorks 6.N user.xml File ........................... 104

14.4 Validating XML Modifications ............................................................................ 104

Examples .................................................................................................... 105

14.5 Advanced Techniques: Custom Parameter Formatting ................................... 106

viii
 Contents

15 System Viewer for Wind River Linux .................................................. 109

15.1 Configuring Wind River Linux for System Viewer ......................................... 109

15.2 Using System Viewer Configuration in Workbench ....................................... 110

15.2.1 Configuration Summary ......................................................................... 110
15.2.2 Instrumentation Configuration .............................................................. 110
Arming and Disarming Modules and Markers on a Target Shell ..... 111
Adding a New Marker ............................................................................ 111
Removing a Module or Marker .............................................................. 112
Listing Armed Modules and Markers ................................................... 113
15.2.3 Recording Mode Options ........................................................................ 113
15.2.4 Target File System Options ..................................................................... 113
15.2.5 Buffer Configuration ................................................................................ 114
15.2.6 Output Filename ...................................................................................... 114
15.2.7 Log Conversion Options ......................................................................... 115
15.2.8 Module Manager ...................................................................................... 115

15.3 Customizing the Appearance and Classification of Events ........................... 116

15.3.1 Customizing the Visual Appearance of an Event ................................ 116
Adding an Event or Customizing Its Appearance .............................. 116
15.3.2 Customizing an Event’s Classification .................................................. 117
Adding a New Event Class and Assigning Events to It ..................... 117

15.4 Custom Events for Wind River Linux 3.0 .......................................................... 118
Sample Marker File .................................................................................. 118
Enabling Custom Markers ...................................................................... 118
Method 1: On the Target Shell ................................................. 118
Method 2: In the Configuration File ....................................... 119

15.5 Custom Events for Wind River Linux 2.x .......................................................... 120
15.5.1 General Steps for Using Custom Events ............................................... 122
15.5.2 Marker Example Module ........................................................................ 122

ix
 Wind River System Viewer
User's Guide, 3.2

A VxWorks: Deployment ......................................................................... 123

A.1 VxWorks Image Projects ....................................................................................... 123

A.1.1 Kernel Configuration ............................................................................... 123

A.2 Preparing for Deployment .................................................................................... 124

B Programming Data Collection ............................................................. 125

B.1 Introduction ............................................................................................................. 125

B.2 Instrumenting Objects Programmatically ......................................................... 126

B.2.1 Kernel Libraries ........................................................................................ 126
B.2.2 Additional Libraries ................................................................................. 132
memLib ...................................................................................................... 132
wvNetDLib ................................................................................................ 132

B.3 Adding Eventpoints ............................................................................................... 134

The e( ) Routine ......................................................................................... 134
The wvEvent( ) Routine ........................................................................... 135

B.4 Timestamping .......................................................................................................... 136

High-Resolution Timestamp Driver ...................................................... 136
Sequential Timestamp Driver ................................................................. 137

B.5 Dynamic Buffer Allocation .................................................................................. 138

B.5.1 Configuring the Event Log Buffer ......................................................... 139
Upload Modes .......................................................................................... 139
Deferred Upload ........................................................................ 139
Continuous Upload .................................................................. 140
Post-mortem Mode ................................................................... 141
rBuff Task Priority .................................................................................... 141
Target Memory Constraints .................................................................... 142
B.5.2 Configuration Tuning .............................................................................. 142

x
 Contents

C Triggering API ....................................................................................... 143

C.1 Introduction ............................................................................................................. 143

Macros ....................................................................................... 144
Triggering Structure .................................................................. 146

C.2 Using the Triggering API Functions ................................................................... 146

Adding a Trigger to the Trigger List ....................................... 147
Deleting a Trigger from the Trigger List ................................ 147
Activating and Deactivating Triggering ................................ 147
Showing Information on Triggers ........................................... 148
Changing Trigger Status .......................................................... 148
Creating a User Event to Fire a Trigger .................................. 149

D Configuring VxWorks for System Viewer ........................................... 151

D.1 Introduction ............................................................................................................. 151

D.2 Configuring the Kernel ......................................................................................... 152

D.3 System Viewer Components ................................................................................ 153

D.3.1 Basic System Viewer Components ......................................................... 153
D.3.2 Upload Method Components ................................................................. 153
D.3.3 Upload Mode Buffer Components ........................................................ 154
D.3.4 Timestamping Components ................................................................... 154
D.3.5 Triggering Components .......................................................................... 154
D.3.6 Network Components ............................................................................. 154

E VxWorks6.N user.xml Example File .................................................... 155

E.1 Introduction ............................................................................................................. 155

E.2 VxWorks 6.N user.xml Example File ................................................................... 156

Index .............................................................................................................. 159

xi
Wind River System Viewer
User's Guide, 3.2

xii
 1
Overview

1.1 What Is the Wind River System Viewer? 1

1.2 System Viewer Tools 2
1.3 System Viewer Architectural Overview (VxWorks) 4

1.1 What Is the Wind River System Viewer?

The Wind River System Viewer is a logic analyzer for embedded software that lets
you visualize and troubleshoot complex target activities.
Often the interactions between the operating system, the application, and the
target hardware occur within specified time constraints, characterized by
resolutions of microseconds or finer.
Commonly used debugging and benchmarking tools for embedded systems, such
as source-level debuggers and profilers, provide only static information.
The System Viewer logs activities on a running target, whereby the type of data
and aspects of a system that you want to view are highly configurable, and can be
saved for later analysis.

1
 Wind River System Viewer
User's Guide, 3.2

The Wind River System Viewer helps you:

„
Visualize multicore system behaviour, and, for example, identify CPU affinity
problems.
„
Detect race conditions, deadlocks, CPU starvation, and other problems
relating to task interaction.
„
Determine application responsiveness and performance.
„
See cyclic patterns in application behavior.
„ Save data for deferred analysis.

NOTE: Features and functionality of Wind River Workbench are described in

Wind River documentation only.
Eclipse documentation, including the Eclipse Workbench User Guide, C/C++
Development User Guide, and the RSE User Guide, is provided for your convenience.
They are not produced by Wind River and do not reflect features provided by your
Wind River product.

1.2 System Viewer Tools

The main System Viewer tools are:
„
System Viewer Configuration

Use this to configure what you want logged, how to upload the log from the
target to the host, and to select how to view analysis data.
„
Triggering

Use this to precisely specify when (at which event) to start and stop logging.
Most events that are logged can also be used as a trigger.
„
Event Receive

NOTE: Triggering is not available for the operating system. For information
on creating custom events, see 15.5 Custom Events for Wind River Linux 2.x,
p.120.

A socket listener for collecting log data uploaded by the target.

2
 1 Overview
1.2 System Viewer Tools

„
Visualizations
1
These include a graphical and tabular presentation of the all logged events , as
well as several views that show analyses derived from the log. These include
core usage (for example on multicore systems), memory data, state statistics,
system load, and so on.

1.2.1 Accessing System Viewer Logs

„ You can open logs that you have created or, or have previously opened,
directly from the Workbench Project Explorer.
„ You can open any existing System Viewer log files by choosing File > Open on
the main Wind River Workbench menu.
System Viewer log files have either a .wvr extension, which is a so-called raw
file with log data only, or a .wva extension, which is an analysis file that
includes information on how the previous viewing session was configured
(range selection, bookmarking, filtering, and so on) so that you (or somebody
else) can pick up from where you left off.

1.2.2 Accessing System Viewer Tools

„ To use the System Viewer configuration tools (Configuration and Triggering
editors) you must be be connected to a target because these tools read
information from the target.
Once you have succesfully established a connection, you can access these tools
from the Wind River Workbench main Analyze menu, or from the Remote
Systems view’s right-click context menu.
„ To open Event Recieve, choose Analyze > Event Recieve on the main
Workbench menu.
However, usually there is no need to do this because the
System Viewer Configuration editor automatically opens the utility when
uploading to a socket.

3
 Wind River System Viewer
User's Guide, 3.2

1.3 System Viewer Architectural Overview (VxWorks)

As you can see in Figure 1-1 (a VxWorks example), the System Viewer provides
both host and target side functionality, whereby as much processing as possible
done on the host to minimize the effect of logging on target activities.

Figure 1-1 Wind River System Viewer Architecture

HOST VXWORKS TARGET

Host Tools Kernel Application

Event Event
View Window Library Trigger
Event Event
VxWorks
Control
Parser
System Viewer Log and
Timestamp Triggering
Event Base
Buffer System Viewer
Control
rt
po
Ex

Upload System Viewer

Task

The host side functionaly is the main subject of the rest of this manual. The target
side includes instrumentation points, buffering, event logging, timestamping, data
upload, and triggering of actions such as when to start and stop logging. All of
these things can be individually configured from the host. For a detailed list of
which VxWorks components are needed for specific target side functionality, see
D. Configuring VxWorks for System Viewer. For information relating to , see
15. System Viewer for Wind River Linux.
Communication between the host and target uses the WDB protocol over a serial
line or a network connection. This path is shared by all Wind River Workbench
tools to communicate with a target.

4
 2
Familiarization

2.1 Quick Start 5

2.2 Getting a Log 5
2.3 Navigating a Log 6

2.1 Quick Start

This chapter introduces some basic System Viewer handling and suggestions to
help you get going quickly. Default settings are assumed throughout.
The procedures described below assume you are familiar with Wind River
Workbench and how to use it to get your software system running on a target.

2.2 Getting a Log

1. Build your software system.
2. Connect to a target.
3. Launch your program on the connected target.

5
 Wind River System Viewer
User's Guide, 3.2

4. In Workbench’s Remote Systems view, right-click on the target connection and

select System Viewer Configuration.
– The System Viewer Configuration utility opens in the main editor pane.
As stated above, this section is intended as a simple introduction that uses
default settings, so there is nothing to configure.
– The System Viewer Configuration menu appears on the main
Workbench menu.
5. On the main menu, select System Viewer Configuration > Start Logging.
Logging commences, and the Log Manager tab comes into focus.
6. After letting your program run for a while, click the Upload Log button on the
Log Manager tab.

2.3 Navigating a Log

By default, the log is initially opened in two tabbed views, the Event Graph and the
Event Table, plus the log Overview, which is located along the top of the tabs.
You will not normally be interested in the entire log, but only in certain areas; for
example, events leading up to a failure, or regions of high target activity. Log range
selection is therefore an indispensable aid in focussing and clarifying.
The Overview along the top of the Event Graph (and Table) plots events against a
timeline (x-axis) and is your main selection tool for focussing on areas of interest.
Before going on to focus on specific log ranges, however, a few more quick
preliminary analysis steps in the Overview could be helpful.

2.3.1 Preliminary Analysis in the Overview

There are various Primary Overviews (right-click the Overview and

Select Primary Overview), the default initial Overview shows Event Intensity.
This is a heat-map; that is, the brighter the little green squares in the Overview are,
the more events occurred at that point in time; these areas of high target activity
are likely to be of interest.

6
 2 Familiarization
2.3 Navigating a Log

In addition to Primary Overviews, you can add overlays (right-click the Overview
and Select Overlay) to the Overview. These overlays are vertically compressed
visualizations of ready-made analyses that can help you quickly identify potential
problem areas. One such analysis is Memory Usage, another example is, in a
multicore environment, Core Usage. Very generally speaking, if there are areas in
a primary overview or in an overlay that look in some way conspicuous, these
might be worth investigating.

2.3.2 Range Selection in the Overview

Having used the Overview to identify parts of the log that are potentially worth
investigating, you will want to focus on each of these areas in turn.
Initially, only the left (earliest) portion of the log is selected in the Overview (black
background). You can relocate the selection in several ways, including:
„ clicking into the Overview (the selected range centres around your click)
„ dragging the selected range 12
„ keyboard left/right arrows and page up/down
„ mouse wheel
„ various menu commands
To change the scope of the selection in the Overview, drag the left and/or right
margins (or use a Zoom context-menu command).
Notice that when you change the selection in the Overview, the displayed data in
the Event Graph (and Table) also changes to match the selected range in the
Overview.

2.3.3 Selection in the Event Graph

The Event Graph plots events along a timeline (x-axis). The events are grouped by
context down the y-axis (the so-called Context Tree), whereby the contexts are
arranged by decreasing priority from top to bottom in the tree.
If you are not familiar with the icons and stipples used to depict events and states
in the Event Graph, select System Viewer > Open Legend.
The graph displays the events in the range selected in the Overview. Within this
range, you can define a so-called Measured Range. The quickest way to create such
a Measured Range in the Event Graph is to click into the graph and drag the
mouse. You can then, for example, right-click and Zoom to Measured Range.
Clicking anywhere into the graph will remove the Measured Range.

7
 Wind River System Viewer
User's Guide, 3.2

You can highlight an individual event by right-clicking on it and choosing

Set Cursor; this sets the so-called Event Cursor (a dashed vertical red line in the
Event Graph and in the Overview, as well as in other open graphs).
Double-clicking on an event will also set the Event Cursor and show the Event
Properties, but will remove a Measured Range if you have set one.
Although you can set the Event Cursor manually as described above, one of its
main functions is to highlight events when you navigate matched items after
running a search.

2.3.4 Selection in the Event Table

The Event Table (on the tab behind the Event Graph) tabulates events in order of
occurrence in the range selected in the Overview. Within this range, you can, like
in the Graph, define a Measured Range. The quickest way to create a Measured
Range in the Event Table is to click on an event, then shift-click on another event.
You can highlight an individual event (set the Event Cursor) by double-clicking on
it; this also shows the Event Properties.
Selecting nodes in the Context Tree to the left of the table constrains the displayed
events to those that belong the selected context. If no nodes are selected, or if the
topmost node is selected, all events are displayed.

2.3.5 More Uncluttering and Clarification

Over and above range-selection as described above, there are various other things
you can do to further unclutter and clarify displayed data.
„ You can Crop the Overview to your selection.
This zooms the Overview in so that your selection occupies the entire available
space in the Overview (you can right-click and Remove Cropping at any
time).
„
In the Context Tree, right-click and select Hide Inactive.
This will hide contexts that do not have any associated events.
„
You might find it helpful to unnest nested contexts in the Event Graph’s
Context Tree. To do so, right-click in the tree and select Show as Flat Tree.
„
Use filters to hide data that you are not interested in, see 11. Filtering and
Searching.

8
 2 Familiarization
2.3 Navigating a Log

2.3.6 Use Linked Views and Multiple Analyses

You can open any number of different analyses as tabs in the main Workbench
editor panel by selecting System Viewer > Analysis Types. However, it is often
more useful to see different analyses in conjunction, to do so select
System Viewer > Open Linked View.
Anything you do in any one of the open views (selection, bookmarking, filtering,
and so on) will be reflected in all the other views that are open on the log.
General handling and selection techniques within the various graphs and tables
are the same as those described above in the context of the Event Graph and the
Event Table.
The choice as to which analysis views you open will obviously depend on the
problems you are trying to solve; if you noticed anomalies in Overview overlays
(2.3.1 Preliminary Analysis in the Overview, p.6) you will probably open the
associated analyses for a closer look.
Depending on the view you are looking at, using different filters can prove useful. 12
For example, if you are investigation memory leaks, you could link to the
Memory Usage analysis, and then filter out everything except memory events.

2.3.7 Use Bookmarks

To set bookmarks, right-click into any open analysis view and select
Add Bookmark. The bookmark is tied to a timestamp and will appear as a blue
triangle at the selected timestamp in all views.
Because bookmarks are persisted in saved analyses, they are particularly useful if
you intend to work in multiple sessions, or make your analysis available to others
for further investigation.

2.3.8 Save the Analysis

System Viewer log files have either a .wvr extension, which is a so-called raw
file with log data only, or a .wva extension, which is an analysis file that
includes information on how the previous viewing session was configured
(range selection, bookmarking, filtering, and so on) so that you (or somebody
else) can pick up from where you left off.

9
Wind River System Viewer
User's Guide, 3.2

10
 3
Configuring a Logging Session

3.1 Configuration Workflow 11

3.2 Beyond the Basics 13
3.3 General Notes 13

3.1 Configuration Workflow

All basic log configuration is done in the System Viewer Configuration editor.
Your first step in configuring a logging session is therefore to open this editor, so
right-click on a connected target and choose
Target Tools > System Viewer Configuration.
The editor opens with the Configuration tab uppermost, associated toolbar
buttons appear on the main Workbench toolbar, and the
System Viewer Configuration menu appears on the main Workbench menu.
The order of appearance of the nodes (from top to bottom) on the Configuration
tab of the System Viewer Configuration editor can be seen as a reasonable,
although not prescriptive, “configuration workflow”. In practice, you will
probably not always follow this workflow, but be aware that there are
dependencies that flow from top to bottom.
The main thing to bear in mind when you configure a logging session is that
logging is intrusive (itself influences target behavior), and that the more data you
collect (the higher the Event Logging Level), the more intrusive it gets. Over and

11
Wind River System Viewer
User's Guide, 3.2

above the volume of data collected, the selected Upload Mode and associated
buffering also influences intrusiveness.
Each of the nodes (configuration categories) introduced below is individually
discussed later. The following is intended merely as an overview that also
illustrates a few potential inter-category dependencies.
„
The topmost node, Configuration Summary, is a read-only summary of the
the configuration settings in the other nodes below it. If everything looks
correct here, forget about the rest of the nodes and start logging.
„ The Event Logging Level node—How much information do you want to
collect? What do you want log?
Deciding what you want to log seems a logical enough place start any
configuration work.
Furthermore, because real-time debugging with the System Viewer can, like
any other kind of debugging, often be a question of “homing in” on the
problem (or on different problems in succession), this is also the configuration
category you are most likely to want to revisit.
Modifications to the scope and type of data you want to collect can, in turn,
influence your decisions in the next node down, Upload Mode.
„ The Upload Mode node—When do want to upload the log? How will it be
buffered on the target until that time?
If, for example, your application can be expected to generate huge amounts of
data at the Event Logging Level you selected above, this can influence your
decisions on buffer allocation.
Apart from the expected data volume, the type of problem you are interested
in (which you will also have thought about in the context of selecting an
Event Logging Level) will have an effect on Upload Mode settings.
For example, do you want to see the events immediately preceding (and
precipitating) a crash? Or, for example, are you interested in observing
long-term target behavior?
„
The Upload Method node—How do host and target communicate? Where do
you want the target to put the logs on the host file system?
This last node is mostly about aligning host and target communication settings
(whereby the System Viewer can only use what is available on the target) and
where you want the logs to be uploaded to. Once everything is correct on this
bottom node, you will normally not need to modify this configuration

12
 3 Configuring a Logging Session
3.2 Beyond the Basics

category very often, although there can be a dependency on the selected

Upload Mode, and therefore indirectly also on the Event Logging Level.

3.2 Beyond the Basics

Over and above the basic configuration you set System Viewer Configuration
editor, triggering (see 13. Triggering) lets you fine-tune exactly when to start and
stop logging.

3.3 General Notes

The System Viewer’s log configuration settings are persistently stored on the host.
That is, the target knows nothing about these settings, so if you use a different host
to connect to the same target, you have to re-configure for the current host.

13
Wind River System Viewer
User's Guide, 3.2

14
 4
The Event Logging Level

4.1 What is an Event? 15

4.2 What is an Event Logging Level? 16

4.1 What is an Event?

Before deciding what level of events you want to log, it might be worth looking at
what the System Viewer sees as an event.
The System Viewer defines an event as any action undertaken by a task or an
interrupt service routine (ISR) that can affect the state of a real-time system. The
information logged for each event includes
„
the action that occurred, such as semGive( )
„
the context in which the event occurred, that is, the ISR, task, or idle loop
„
the timestamp
„
other status information as appropriate, such as the semaphore ID for a
semGive
„
parameter details
„
calling routines
„
and so on. For detailed information, see the Wind River Workbench User Interface
Reference: System Viewer Event Dictionary.

15
 Wind River System Viewer
User's Guide, 3.2

Examples of events are:

„
semaphore gives and takes
„
task spawns and deletions
„
timer expirations
„
interrupts
„
message queue sends and receives
„
watchdog timer activity
„ exceptions
„ signal activity
„ system calls
„ I/O activity
„ networking activity
„ memory allocation, freeing, partitioning, and so on
The System Viewer provides details about the parameters logged for each library
or event, the routines that call them, and so on. For more information, see the
Wind River Workbench User Interface Reference: System Viewer Event Dictionary.

4.2 What is an Event Logging Level?

An event logging level determines the type of events (see 4.1 What is an Event?, p.15)
logged; that is, the breadth and depth of data collection.
In the Event Logging Level node of the System Viewer Configuration editor
there is one main control for selecting logging levels, the
Event Logging Level Selection list.
The Event Logging Level Selection list is ordered from lowest to highest
complexity, and therefore intrusiveness. These levels are cumulative; that is, each
level is the sum of all lower levels, plus whatever new options the selected level
itself provides. The user interface provides descriptions of what kind of events
each Event Logging Level will capture, so click your way through the levels to see
the descriptions.

4.2.1 Which Level Do I Select?

To help you decide which level to select, use your knowledge of:

16
 4 The Event Logging Level
4.2 What is an Event Logging Level?

„
your application and its (potential) problem areas
„
how your application interacts with the operating system
If this not enough, you might try an iterative approach, especially if you are new
to System Viewer:
„
Start by collecting at the most simple level, Context Switch, then, after you 4
have done the rest of your configuration settings and have generated a log,
examine the results in the Log Viewer.
„ If you do not see what you need, try the next highest level,
Task State Transition.
The Task State Transition level captures, in addition to the changes in
execution context logged by the Context Switch level, the events that resulted
in such changes.
„ If that does not work for you, move up to the highest level,
Additional Instrumentation.
The Additional Instrumentation level is configurable and allows logging of
selected operating system specific event types. Try to narrow down your
selection to likely looking candidates for the problem(s) you are interested in.
Note, however, that if you do not select any libraries, the output will be exactly
the same as if you had selected Task State Transition.

17
Wind River System Viewer
User's Guide, 3.2

18
 5
The Upload Mode

5.1 Upload Mode Configuration: General Considerations 19

5.2 Deferred Upload Or Continuous Upload? 20
5.3 Post-Mortem Upload Modes 23
5.4 System ViewerTroubleshooting Upload Modes 27

5.1 Upload Mode Configuration: General Considerations

When you configure the Upload Mode, there are two questions you have to
answer:
1. When do you want to upload the collected event log data from the target?
This depends mainly on what kind of problem you are trying to track down:
– If you want to see the events leading up to a crash, you have to use a
Post-Mortem Upload mode.
– If you want to debug non-fatal problems, you can choose between
Deferred Upload and Continuous Upload.
2. How do you want to configure the target buffer that holds the data until it is
uploaded?
Normally you do not want configure the buffer at all. You can generally just
accept the default buffer configurations associated with each Upload Mode.

19
 Wind River System Viewer
User's Guide, 3.2

Although manual buffer configuration is rare and “advanced” (you have to

know something about the buffering strategies used by each Upload Mode),
there are cases where you might want/have to modify the default
configurations. Such cases range from “advanced tweaking” (for example, to
minimize logging intrusiveness) to troubleshooting problems like
log-collection stoppages or upload failures.
Since you will not normally need to customize the buffer configuration when
you are setting up a logging session, discussion of this subject is confined to
the troubleshooting section of this chapter, 5.4 System ViewerTroubleshooting
Upload Modes, p.27.

5.2 Deferred Upload Or Continuous Upload?

Deferred Upload or Continuous Upload is the basic decision you have to make
for debugging non-fatal problems.

5.2.1 Deferred Upload

This is the default mode. Data is uploaded when you issue an Upload command
from the System Viewer user interface.
If you use a non-circular buffer, logging stops when the buffer is full.
„ Deferred Upload Limitations

The volume of data collected is limited to whatever free memory is available

on the target.
However, this may in fact not really be a limitation because, for example:
– You are looking at an application that runs its course fairly quickly
(and/or you have sufficiently optimized the Event Logging Level
configuration).
– You have localized the problem to some extent, which means that you do
not need to collect data for hours or days on end.

20
 5 The Upload Mode
5.2 Deferred Upload Or Continuous Upload?

In such a case you might set triggers to start/stop logging, and you would
probably also be able to constrain the volume of data collected via the
Event Logging Level configuration.
– You have additional off-board memory.
„
Deferred Upload Advantages

– Least complex and therefore least problem-prone. 5

– Minimal intrusiveness of logging.

– Minimal configuration overhead.

5.2.2 Continuous Upload

In this mode, data is periodically uploaded from the target as buffers are filled.
Logging continues until stopped by a trigger, an API call, or on demand. If the
Upload Method is configured to
Automatically view the data on upload completion, uploading takes place as
soon as logging is stopped.
„ Continuous Upload Limitations

This mode is more complex than Deferred Upload in that, over above
collecting data and allocating buffers, it has to concurrently upload filled
buffers (and potentially free them). This has a number of implications:
– More complexity may, but by no means necessarily, lead to problems and
therefore also some additional configuration overhead.
– Intrusiveness is higher because events associated with periodic uploading
are reflected in the log.
– Periodic uploading impacts target performance.
– This mode is not compatible with the host-driven Memory Read upload
method, see 6.2 Using the Memory Read Upload Method, p.34.
„ Continuous Upload Advantages

The major advantage, or reason to use, the Continuous Upload mode is the
huge volume of data you can collect without interruption (the physical limit is
the available hard-disk space on the host).
For long-term, uninterrupted observation and situations where you do not
know how to characterize the problem (and therefore cannot set triggers) this
is the mode of choice.

21
 Wind River System Viewer
User's Guide, 3.2

5.2.3 Configuration Options: Deferred Upload and Continuous Upload

Both Deferred Upload and Continuous Upload modes provide the following
configuration options:
Buffer size (default = 32Kb)
This refers to the size of individual buffers in a dynamic ring of multiple
buffers. The smallest possible value (the default of 38Kb) therefore represents
the best fit in terms of how many individual buffers the available target
memory can accommodate.
If target memory constraints are not an issue because the expected volume of
data is relatively low and/or you have ample free target memory, you can
increase the size of individual buffers. Because buffers are dynamically
allocated (and in Continuous Upload mode also sometimes freed), this will
reduce the overhead, and therefore also intrusiveness, of memory
(de-)allocation.
Advanced >>
This button opens options that you do not normally need to look at. These
options are relevant only for troubleshooting or advanced tweaking; as such,
they are described under 5.4 System ViewerTroubleshooting Upload Modes, p.27.

22
 5 The Upload Mode
5.3 Post-Mortem Upload Modes

5.3 Post-Mortem Upload Modes

VxWorksPost-Mortem upload is used primarily to collect events leading up to a
system failure. Events are stored in a circular (wrap-around) ring of buffers where
the oldest data is overwritten with the newest data when the ring is full.
So even if you collect data for days or weeks, the events immediately preceding the
failure will be recorded and stored in the target buffer. After a crash and a warm 5
reboot you can then upload the buffer contents by issuing an Upload command
from the System Viewer user interface.
This can only work if the buffer is stored in memory that is not overwritten on
rebooting, which means you will usually have to first configure system memory
accordingly (see 5.3.2 Preparation: Kernel Configuration for Post-Mortem Upload,
p.23) and then align the System Viewer configuration settings to match. Bear in
mind that if you reconfigure kernel memory, you will have to rebuild the VxWorks
image, as well as the boot loader.

5.3.1 Using Post Mortem for Non-Fatal Problems

You can also use Post-Mortem Upload even if you do not expect the target to
crash. This is particularly useful on systems (like VxWorks 653) that do not support
Deferred Upload with the Use a circular buffer option. This way, you can take
advantage the corresponding circular (wrap-around) buffer feature used by
Post-Mortem. In this case, you would not need to rebuild the boot loader.

5.3.2 Preparation: Kernel Configuration for Post-Mortem Upload

Because post-mortem mode must preserve the buffer after an application failure,
the buffer cannot reside in system memory. This means you will have to configure
the kernel accordingly, unless one of the following applies:
„
You are using a BSP that does not reset system memory on a warm reboot.
„
You are using shared or off-board memory.
If neither of the above apply, you will have to configure the kernel, regardless of
which post-mortem mode (on systems that provide more than one) you want to
use.
Your first step is therefore to open the Kernel Configuration Editor (accessing the
Kernel Configuration Editor and using the Find dialog to locate components is
described under D.2 Configuring the Kernel, p.152).

23
 Wind River System Viewer
User's Guide, 3.2

How you proceed from here, depends on which mode (if your system provides
more that one) you want to use. Recall: both will achieve the same objective.
– Either follow the steps under Post-Mortem Upload Kernel Configuration, p.24
– Or follow the steps under Post Mortem Mode (using pmLib) Kernel
Configuration, p.25

Post-Mortem Upload Kernel Configuration

To configure memory for Post Mortem Upload you have to set the following
macro values:
LOCAL_MEM_AUTOSIZE = FALSE
USER_RESERVED_MEM = required memory size (as large as possible)

To do so:
„ In the Kernel Configuration Editor’s Find dialog, start typing
LOCAL_MEM_AUTOSIZE.
The macro name should be matched after the first few keystrokes.
„ Double-click on the match and, in the Properties view, set the Value of
LOCAL_MEM_AUTOSIZE to FALSE.
„ Open the Find dialog again, and start typing USER_RESERVED_MEM.
The macro name should be matched after the first few keystrokes.
„ Double-click on the match and, in the Properties view, set the Value of
USER_RESERVED_MEM to as high a value as possible.
For example, to reserve 512 Kb of memory for the post-mortem log buffer, set
the value to 0x80000.
If you do not know how much memory is available for reservation, use a
Target or Host Shell and:
– To find the top of VxWorks memory, enter sysMemTop( )
– To find the top of all local memory, enter sysPhysMemTop( )
You have now reserved memory for the post-mortem log buffer. Please continue as
described under 5.3.3 Rebuild the Kernel and the Boot Loader, p.25

24
 5 The Upload Mode
5.3 Post-Mortem Upload Modes

Post Mortem Mode (using pmLib) Kernel Configuration

To configure memory for the Post-Mortem Upload (using pmLib) mode, you
have to set the macro:
PM_RESERVED_MEM = required memory size (as large as possible)
To do so:
5
„ In the Kernel Configuration Editor’s Find dialog, start typing
PM_RESERVED_MEM.
The macro name should be matched after the first few keystrokes.
„ Double-click on the match and, in the Properties view, set the Value of
PM_RESERVED_MEM to as high a value as possible.
For example, to reserve 512 Kb of memory for the post-mortem log buffer, set
the value to 0x80000.

NOTE: The size defined by the PM_RESERVED_MEM value is for the whole
arena, the amount of memory available for use by System Viewer depends on
the amount of memory used by other components in the arena such as ED&R.

You have now reserved memory for the post-mortem log buffer using the
persistent memory feature. Please continue as described under 5.3.3 Rebuild the
Kernel and the Boot Loader, p.25

5.3.3 Rebuild the Kernel and the Boot Loader

If you have modified the kernel in order to support post-mortem upload, you have
to rebuild and reboot it.
Furthermore, unless you are using post-mortem as described under 5.3.1 Using
Post Mortem for Non-Fatal Problems, p.23, you will have to rebuild VxWorks boot
loader images. This is necessary to ensure that the boot process does not clear
memory reserved for the System Viewer log buffer or the system image, which
could lead to changes in memory allocations.

25
 Wind River System Viewer
User's Guide, 3.2

5.3.4 Post-Mortem Upload Mode

Once you have configured the kernel as outlined under 5.3.2 Preparation: Kernel
Configuration for Post-Mortem Upload, p.23, you can select the Post-Mortem Upload
in the System Viewer Configuration editor.
Normally the start and end addresses displayed in the
Post-Mortem Upload Buffer Configuration pane can be correctly calculated by
System Viewer. If not, a warning is displayed. Possible problems include:
„ The target does not support user-reserved memory (for example, VxSim).
„ You have not correctly configured user-reserved memory on the kernel, see
Post-Mortem Upload Kernel Configuration, p.24.

26
 5 The Upload Mode
5.4 System ViewerTroubleshooting Upload Modes

5.4 System ViewerTroubleshooting Upload Modes

Although the System Viewer upload mode configuration defaults generally
suffice, there may be extreme situations that demand custom configuration. You
will probably only realize this during or after an initial logging session (failure);
that is, you will have to re-configure.
The kind of problems that could be solved by upload mode (re-)configuration are: 5

„
Logging stops prematurely.
„
In Continuous mode only:
– upload fails and/or
– there is excessive buffer allocation/freeing (known as thrashing)
Generally speaking, such extreme situations, where System Viewer defaults do not
suffice, arise if too many events are fired too rapidly to be properly handled. To
overcome the problem, there are two main areas to look at:
„
Constrain the volume of data collected by setting triggers (see 13. Triggering)
and/or by refining the Event Logging Level if possible (see 4. The Event
Logging Level).
„
Modify the target buffer configuration, which is what the rest of this section is
about.

5.4.1 The Ring Buffer

Almost all custom (re-)configuration of upload modes relates to target buffer

management, so it is worth taking a brief look at the System Viewer buffering
strategy.
System Viewer uses a ring of individual buffers for storing event logs on the target.
Depending on the upload mode, this ring can use:
„
Dynamic buffering
Buffers are allocated as needed, up to a configurable maximum count, or until
there is no more target memory available (whichever comes first).
– Dynamic buffer allocation is supported in Deferred Upload and
Continuous Upload modes.
In Continuous Upload mode, excess buffers are freed as data is read and
uploaded from filled buffers.

27
Wind River System Viewer
User's Guide, 3.2

In both Deferred Upload and Continuous Upload modes you can

suppress dynamic buffering by setting the minimum number of buffers to
equal the maximum number of buffers. In this case, all available target
memory is pre-allocated for use by System Viewer.
However, be aware that in these modes the buffer’s memory requirements
are provided by the system memory partition, the general partition from
which all malloc( ) requests are sourced.
– Post-Mortem Upload modes are non-dynamic. These modes pre-allocate
buffers by subdividing all available user-reserved or persistent memory
(depending on the post-mortem mode selected) into a ring of ten
individual buffers.
„ Linear or Circular buffering
– Linear buffering—Buffers are allocated and filled as needed, up to a
configurable maximum count, or until there is no more target memory
available (whichever comes first). At this point logging stops.
– Deferred Upload uses linear buffering if Use Circular buffer (on
systems that support the option) is not selected. On VxWorks 653
Deferred Upload buffering is always linear.
– Continuous Upload uses linear buffering. In the normal course of
events, buffers are continuously emptied and uploaded, making them
available for new data, so the end of the ring should never be reached.
All the more so because upload timing is based on the minimum
buffer allocation, and all remaining buffers serve as a reserve for
catching any backlog of events generated during extreme peaks of
activity.
– Circular buffering—Buffers are allocated and filled as needed, up to a
configurable maximum count, or until there is no more target memory
available (whichever comes first). At this point the buffer wraps around;
that is, the oldest buffer is reused and overwritten. This continues until
stopped by a trigger, an API call, or on demand (or a full upload-host
disk).
– Deferred Upload uses circular buffering if Use circular buffer (on
systems that support the option) is selected. This option is not
supported on VxWorks 653.
– Post-Mortem Upload modes always use circular buffering. This
ensures that the events immediately preceding (precipitating) a
system failure are recorded.

28
 5 The Upload Mode
5.4 System ViewerTroubleshooting Upload Modes

5.4.2 Symptoms and Solutions

This section focusses on logging problems where there is a good chance that some
upload-mode related re-configuration could provide a solution.

Problem: Logging Stops Prematurely / Ring Buffer Stops Updating

5

This is observable in the Log Manager (see 7.2 The Configuration Editor Log
Manager, p.42).
Although this could potentially happen in any mode, Continuous Upload is most
likely to be affected due to the additional overhead of concurrently uploading data.

Possible Causes

In all modes this can be because:

„ Too many events are generated too quickly for buffers to be allocated in time.
„ Not enough memory is allocated for buffering on the target.

Possible Solutions

All modes:
„ Increase the buffer allocation task priority. You can do this either in the host or
target shell, or in the Kernel Configuration Editor (in which case you will
need to rebuild and reboot).
The default buffer allocation task priority is 100. So you would increase this to
some higher integer, say 150.
– To increase buffer allocation priority, in the host or target shell, enter:
-> wvRBuffMgrPrioritySet(150)
– To increase buffer allocation priority in the Kernel Configuration Editor,
search for WV_RBUFF_MGR_PRIORITY and enter a value of, say, 150.

Post-Mortem modes:
„
Allocate more user-reserved or persistent memory (depending on mode used)
if possible, see 5.3.2 Preparation: Kernel Configuration for Post-Mortem Upload,
p.23.

29
 Wind River System Viewer
User's Guide, 3.2

Deferred and Continuous modes:

„
Change the Advanced Buffer Configuration settings (click Advanced >>).
Which (combination) of the following you do depends on (1) what you suspect
is causing the problem, and (2) target constraints.
Always bear in mind that log buffering in these modes uses the same memory
partition as system and applications.
– To make more total memory available for log buffering on the target,
increase the Max. Buffer Count (default is 10).
This assumes there is physically more memory available on the target.
– To reduce the frequency of buffer allocation, increase the Buffer Size.
Note, however, that this can (probably) reduce total available buffer size
(at the same Max. Buffer Count) if target memory is constrained because
the bigger the individual buffers, the worse the fit is likely to be.
– To eliminate buffer allocation overhead altogether, set Min. Buffer Count
to equal Max. Buffer Count.
This pre-allocates all available memory.

Problem: Upload Fails (Continuous Upload Only)

Continuous Upload depends, apart from buffer configuration, on a number of

factors:
„ The rate at which the target application generates events
„ Target memory constraints
„ Relative host and target performance
„ Network bandwidth
„ Upload method
All of the above might want looking at, possible upload mode issues are described
below.

Possible Causes and Solutions

„
Buffer allocation failed—see Problem: Logging Stops Prematurely / Ring Buffer
Stops Updating, p.29.
„
The ring buffer is filled to capacity faster than individual buffers are uploaded.
In this case, the Log Manager will show that all buffers are full.

30
 5 The Upload Mode
5.4 System ViewerTroubleshooting Upload Modes

Possible solution: Click Advanced >> and increase Max. Buffer Count (the
default is 10).
„
The upload task priority is not high enough; that is, higher-priority tasks
execute so frequently that they prevent uploading (rare).
Possible solution: Use wvUploadTaskConfig( int stackSize, int priority) to
change the priority (do not modify stackSize).
5
The default upload task priority is 150. So you would increase this to some
higher integer, say 200.
To increase upload task priority, in the host or target shell, set the second
parameter of wvUploadTaskConfig to, say, 200:
-> wvUploadTaskConfig(5000, 200)

Problem: Buffer Thrashing (Continuous Upload Only)

In a balanced system, the ring buffer is not constantly resized; it remains at the
original, minimum ring size (Min. Buffer Count in the
Advanced Buffer Configuration), allowing a steady upload of event data. All
remaining buffers up to Max. Buffer Count should serve only as a reserve for
temporarily holding any upload-backlog induced by sudden, massive bursts of
data.
Thrashing refers to a situation where buffers are repeatedly allocated and freed.
This interferes with target performance and generates intrusive event data, which
will be reflected in the log.

Possible Solution

If you notice the behavior described above in the Log Manager, increase the
minimum number of buffers in the ring:
Click Advanced >> and increase Min. Buffer Count (the default is 2).

31
Wind River System Viewer
User's Guide, 3.2

32
 6
The Upload Method

6.1 The Upload Method 33

6.2 Using the Memory Read Upload Method 34
6.3 Using TSFS Upload Methods 35
6.4 Automatic Upload of Logs 35
6.5 Socket Via TSFS and Socket Via TCP/IP Configuration 37
6.6 File Via TSFS 37
6.7 File Via NFS 38
6.8 File Via netDrv 38
6.9 The Event Receive Utility 39

6.1 The Upload Method

The Upload Method node lets you configure how the System Viewer event log is
uploaded from the target to the host and where the uploaded log is stored.
The Upload Method Selection drop-list provides the following communication
options:
„
Memory Read
„
Socket Via TSFS

33
 Wind River System Viewer
User's Guide, 3.2

„
Socket Via TCP/IP
„
File Via TSFS
„
File Via NFS
„
File Via netDrv

6.1.1 Upload Method Selection Errors

If you see a red X icon against the Upload Method node in the tree at the left, it
means that the current Upload Method Selection is invalid; uploading of log files
is therefore disabled.
The error can be due to one or more of the following (the user interface will tell you
which of these applies):
„ The target does not support the selected communication option.
If you want to use such an option, see D. Configuring VxWorks for System Viewer
for information about how to add the necessary components.
„ The Upload Method Selection configuration parameters have not yet been
validated by System Viewer.
Click the Apply button.
„ The Upload Method Selection is incorrectly configured.
See the user interface descriptions and the notes below.

6.2 Using the Memory Read Upload Method

The Memory Read upload method is host driven, whereas all the other available
methods for transferring a System Viewer log file from the target to the host are
target driven. That is, this method does not rely on the target pushing the data to
the host. Instead, the structure of the log is processed by the host, and the data is
read directly from the target's memory by the host
This method of transferring log data to the host has a number of advantages. The
main ones are:
„
Log transfer is not compromised by task starvation.

34
 6 The Upload Method
6.3 Using TSFS Upload Methods

That is, the low priority upload task which is normally responsible for
uploading System Viewer logs is not used, there is therefore no risk of it being
starved of CPU time by other, higher priority tasks.
„
The log can be transferred as many times as needed (as long as the option to
delete the log on the target is not selected) to any host directory.
„
The host knows exactly where the log will end up when transfer is complete.
„ Logs can be transferred without needing to call any target functions.
6
„ Configuration is easy: Enter a filename and directory for storing the
System Viewer log(s) on the host, and set the other options as desired.

NOTE: The Memory Read method is not compatible with the Continuous Upload
mode, see 5.2.2 Continuous Upload, p.21. The log must be complete and static before
a Memory Read transfer can begin.

6.3 Using TSFS Upload Methods

The advantage of using the Target Server File System (TSFS) is that it does not
require extra facilities. If you are on a network, TSFS uses already configured
bandwidth to upload event log data. If you do not have network support, TSFS
uses the serial connection.
To use either of the TSFS methods (file or socket), the target server must be
configured to provide support for this. The TSFS system must be enabled and
set to support read and write operations. In addition, the TSFS root directory
must be specified. For information on target server configuration, see the
Wind River Workbench User’s Guide.

6.4 Automatic Upload of Logs

If log data are to be automatically uploaded and saved to files, you have to specify
a valid file system location on the host the target sends the logs to.

35
Wind River System Viewer
User's Guide, 3.2

„
If you use Socket upload methods, you set the host file system location for the
uploaded log in the File Name field.
– If the target uploads data to a remote host, you would open the
Event Receive utility on that host, and set the information there (see
6.9 The Event Receive Utility, p.39).
– If the target uploads data to the current host, you can set this directly in the
System Viewer Configuration editor, without having to open the
Event Receive utility.
„ If you use File upload methods, you set the host file system location for the
uploaded log in the Directory containing uploaded log field:
This option is only available if the
Automatically view log on upload completion checkbox is selected. The
directory must be a path the host can follow to access the target's output file.
For example, if you are running System Viewer on a Windows machine and
the target in use is writing to a Unix machine, you have to map a Windows
network drive that allows you to set a Windows path to the Unix directory
holding the target’s output file.

36
 6 The Upload Method
6.5 Socket Via TSFS and Socket Via TCP/IP Configuration

6.5 Socket Via TSFS and Socket Via TCP/IP Configuration

„
Host

The IP address or name of the host to which the data is to be uploaded. The
default is the name of the current host.
Specifying a remote host requires the Event Receive utility to be started on the
remote host and ready to accept data at the specified socket number, otherwise
validation of the upload method is not possible (see 6.9 The Event Receive 6
Utility, p.39).
„
Port Number

The socket port on the host to which the event log data is uploaded. The
default port number is 6164.

6.6 File Via TSFS

„
TSFS path and filename

You can enter a relative path segment (optional) and filename. The path
segment, if used, will be relative to the target’s TSFS root directory path
(displayed further down in the current view).
„
Directory containing uploaded log

If the target’s current TSFS root directory (displayed above the field) is a path
that can be directly accessed by the current host, then enter the path exactly as
displayed, plus any relative path you entered in the TSFS path and filename
field. Otherwise, see 6.4 Automatic Upload of Logs, p.35.

37
 Wind River System Viewer
User's Guide, 3.2

6.7 File Via NFS

„
NFS directory and file name

You can enter a relative path segment (optional) and filename. The path
segment, if used, will be relative to the target’s NFS directory.
„
Directory containing uploaded log

See 6.4 Automatic Upload of Logs, p.35.

6.8 File Via netDrv

The netDrv driver typically uses either ftp or rsh for file transfer from the target to
the host.
„
Directory containing uploaded log

See 6.4 Automatic Upload of Logs, p.35.

„
netDrv directory and filename

You can enter a relative path segment (optional) and filename. The path
segment, if used, will be relative to the target’s netDrv directory.
„
Host
This is for information purposes only. If no host name or IP address can be
determined, the upload method is not available for use.

38
 6 The Upload Method
6.9 The Event Receive Utility

6.9 The Event Receive Utility

This section is only relevant if you have socket connections on a remote host.
The Event Receive utility allows a remote host to listen for an incoming connection
from a target that has an event buffer to upload. Event Receive then accepts this
log and writes it to a file on the host's file system. The .wvr file extension is
automatically appended to the saved log files.
To open the Event Receive utility from Wind River Workbench select 6
Analyze > Event Receive.
The Event Receive utility allows you to upload data directly from the target to a
socket connection. The uploaded data is then saved to a file which is specified by
Event Receive.
From the Event Receive utility, you can view or adjust these options for data
upload.
„
File Name

Specifies the path and filename to which log files are saved. The default is
userHomeDir/eventLog.wvr.
„
Port Number

Specifies the host TCP/IP port over which the Event Receive utility listens for
event data from the upload task. The default event port number for
Event Receive is 6164. If your target uses a different event port, specify the port
number in this field.
„
Increment Filenames

Multiple log files are distinguished with the naming pattern, filename.num.wvr,
whereby num is an integer incremented by one for each file. Although, you
cannot specify the num segment of the filename, you can influence the integer
at which it begins. If you select Overwrite Existing Files, the event receive
session begins numbering its log files at zero, and overwrites any files from
previous event receive sessions.
„
Overwrite Files

If not selected, the next free incremental number (files with increment numbers
already exist in the directory) is used.

39
Wind River System Viewer
User's Guide, 3.2

40
 7
Logging and Uploading Data

7.1 Start Logging 41

7.2 The Configuration Editor Log Manager 42
7.3 Using the System Viewer API to Control Logging 43
7.4 VxWorks Core Dump Log Upload 44

7.1 Start Logging

To begin collecting data you must have a target (or target simulator) running an
operating system configured for System Viewer.
If logs are to be uploaded to a remote host via a socket connection, make sure the
Event Receive dialog is up and listening on that host. For more information, see
6.9 The Event Receive Utility, p.39
System Viewer provides various methods to start logging and to upload data:
Configuration
The System Viewer Configuration editor is the simplest and most
straightforward method to manually start and stop logging. For more
information, see 7.2 The Configuration Editor Log Manager, p.42.

41
 Wind River System Viewer
User's Guide, 3.2

Triggering
With Triggering, you specify events and conditions that can be validated
and used to start and stop System Viewer logging. For more information,
see 13. Triggering.
Wind River System Viewer API
The Wind River System Viewer API is the most precise method to
determine when logging starts and stops. It is especially useful when there
is a lot of activity on the target. You can issue commands from the host
shell or include them in your application code. Although precise, this
method is more complex than Triggering. For more information, see
7.3 Using the System Viewer API to Control Logging, p.43.
Event Receive
The Event Receive dialog is used to receive data on a socket that is sent
from the target. For more information, see 6.9 The Event Receive Utility,
p.39.
If you prefer not to use a socket that listens to the target, you can also upload data
using a file with TSFS, NFS, or netDrv. For more information, see 6. The Upload
Method.

NOTE: After a target reboot, the target connection can be resumed automatically,
but the System Viewer has to be reconnected manually.

7.2 The Configuration Editor Log Manager

System Viewer dynamically enables or disables items to start and stop logging on
the main System Viewer Configuration menu and the toolbar according to the
status of log collection.
Refreshing information can be slightly intrusive on the target, so System Viewer
provides the ability to control how and when data gets refreshed using the
Refresh Controls that appear at the top of the Log Manager.
The default view of the Log Manager displays the total size of the ring buffer, and
the amount of data currently in the buffer. The current state is also displayed in a
ring
Colors used in the ring:

42
 7 Logging and Uploading Data
7.3 Using the System Viewer API to Control Logging

Orange
Buffer has been allocated and is ready to be used.
Green
A green buffer indicates the buffer has been used. If the buffer is partially
green, the buffer is still being used and is not yet full.
Red
In post mortem or using a circular buffer, red indicates that the buffer contains
the oldest set of data and will be overwritten when the buffer currently in use
is filled.
7
Clicking the More Detail >> button provides further information related to the
buffer and its state. Note that the Bytes Read value is always zero in deferred or
post-mortem modes because no data is read from the buffer (uploaded).

7.3 Using the System Viewer API to Control Logging

Using the Wind River System Viewer API is the most precise method to determine
when logging starts and stops. Use this method when there is a lot of activity on
the target as using the System Viewer Configuration utility may generate
unnecessarily large logs.
You can either issue Wind River System Viewer API commands from the Host
Shell or programmatically in your application code. As described below, use one
of the following API groups.

wvOn( ) and wvOff( )

These routines provide the easiest method to control logging. The wvOn( ) and
wvOff( ), routines are defined in usrWindView.c.
These routines start a typical instance of event logging and upload. Because these
routines are not used by Wind River System Viewer itself, you can safely modify
them to suit your specific needs. To start event logging use wvOn( ), then start the
target application. To close the host-target connection, use wvOff( ) on the target.
To examine the source code and how these routines are used, refer to
installDir/vxWorks-N.N/target/config/comps/src/usrWindView.c.

43
 Wind River System Viewer
User's Guide, 3.2

VxWorks API Libraries

Please see the VxWorks OS Libraries API Reference documentation for more
information on the following libraries that you can use for controlling
System Viewer:
rBuffLib
Provides functions to create and delete the ring buffers used to hold events.
wvLib
Provides the underlying functions to create System Viewer logs, start and stop
logging, and to control the amount of events stored.
wvNetDLib
Provides precise control over the events logged by the network stack.
The order in which you invoke these libraries is critical. You can also use the e( )
routine with System Viewer, which is documented in the reference entry for
dbgLib. For more information, see also B. Programming Data Collection.

7.4 VxWorks Core Dump Log Upload

System Viewer supports uploading of System Viewer logs from VxWorks core files
using the Memory Read upload method (see 6.2 Using the Memory Read Upload
Method, p.34).
To access log files in a VxWorks core file, proceed as follows:
1. Create a target server connection for your core file and make sure the tgtsvr -A
option is included (as it is by default). This will include all local and global
symbols in the core file.
2. Start System Viewer Configuration as you would for any other target.
When it appears, you will see that it has a Core File Log Uploader tab that
resembles the Log Manager on a standard VxWorks target. The difference is
that it has a panel that allows you to choose a destination filename and
directory. If there are no logs in the list then the core file does not have any
uploadable System Viewer log files.
Once you have selected a directory and filename, you can either upload an
individual log by selecting it in the list and clicking the Upload button, or you

44
 7 Logging and Uploading Data
7.4 VxWorks Core Dump Log Upload

can upload all the logs by selecting

System Viewer Configuration > Upload All Event Logs on the main menu.

45
Wind River System Viewer
User's Guide, 3.2

46
 8
Loading Log Files

8.1 Opening Logs

There are a number of ways you can open System Viewer log files:
„
You can use the Wind River Workbench File > Open menu to open *.wvr (raw
logs, as originally uploaded), or all *.wva files (analysis logs, which can
include any annotations you have made to raw files).
„
For logs created in the System Viewer integration with Wind River Workbench
3.0, or newer, Wind River Workbench Projects are automatically created for the
log files. In this case, you can simply double-click the file in the Project
Explorer, or use the context menu to select the viewer you want to open the log
in.

NOTE: There is no documentation support for

Open With > System Viewer Log Viewer (External); this is the old viewer
that runs as a standalone application and is not integrated in the Wind River
Workbench.

„
In addition, System Viewer can automatically open a log file upon upload.
There are two ways to configure System Viewer to automatically open a log
file:
– In the Upload Method Configuration node of the
System Viewer Configuration editor, select
Automatically view log on upload completion. For more information,
see 6.1 The Upload Method, p.33.

47
 Wind River System Viewer
User's Guide, 3.2

– In the Event Receive utility, select View Files Automatically. For more
information, see 6.9 The Event Receive Utility, p.39.

NOTE: If you are using triggering to start and stop System Viewer, the resulting
log file may not open automatically when System Viewer is stopped. Of course,
you must explicitly press upload if you are using deferred upload mode. If you are
using continuous mode, the log has been uploaded but it will not open until you
either refresh triggers or click Upload. For more information, see 5. The Upload
Mode and 13. Triggering.

8.1.1 Load Progress View

When you open a System Viewer log, a load progress view appears. You can copy
and paste text from this view. The view remains open if there are fatal errors, in
which case your log file will not open for viewing.
A log can load successfully or with warnings. If there are warnings, it is possible
that the contents of the log will be truncated from the point where the warnings
were encountered.

8.1.2 Errors and Warning Messages on Opening Logs

A log file may fail to load for one of the following reasons:
1. The log file is not a System Viewer log file.
2. The log file does not exist.
3. The log file is from a target operating system not supported by the
System Viewer installation.
4. The log contains unknown events.
In the first three cases, the error is fatal and log loading cannot proceed. In the final
case, the log is loaded up to the point where the unrecognized event is
encountered.

48
 9
Primary Overviews

9.1 Overview Modes 49

9.2 All Events 50
9.3 Peak Activity 50
9.4 Event Intensity 51

9.1 Overview Modes

To choose an Overview mode use System Viewer > Select Primary Overview. A
number of standard Overview modes are common to all operating systems.
In all modes, the (horizontal) x- axis of the Overview represents time and extends
over the entire range of the event log. The timeline along the bottom of the
Overview is divided into a number of equal time slices. The number of slices
allocated is automatically determined by System Viewer when an event log is
loaded, and is based on the timestamping configuration.
The Overview data collection mechanism operates on an event log after filtering is
applied and will therefore hide activity associated with filtered out items.
In addition to a selected Primary Overview, you can add overlays (vertically
compressed graphs) of several analysis types, see 10. Analysis Types, to the
Overview.

49
 Wind River System Viewer
User's Guide, 3.2

Range Selection in the Overview

The selected Overview range (all modes) defines the scope of the display in all
Analysis views. This is introduced under 2.3.2 Range Selection in the Overview, p.7.

9.2 All Events

The All Events Overview is a simple, time-based separation of event and
state-change activity displayed as a bar graph. The y-axis represents magnitude—
the higher the bar displayed at a given point on the time axis, the more
event/state-change activity occurred during that time period. Each event and state
change is given the same weighting, regardless of the context in which it occurred.

9.3 Peak Activity

Peak Activity shows how peak activity runs through the displayed contexts over
the course of the event log.
It is easy to locate an area of peak activity by setting this Overview mode. The
y-axis represents the vertical location of a context in the Context Tree, as displayed
alongside the Event Graph or the Event Table. Within each time slice, the context
that exhibits the greatest number of events or state-changes is identified, and a
small horizontal line is plotted at its corresponding vertical location in the tree of
event contexts. If the Overview shows a line in the middle of the vertical range of
the Overview, this corresponds to a context that is in the middle of the vertical
range of the displayed contexts in the Event Graph or Event Table.

50
 9 Primary Overviews
9.4 Event Intensity

9.4 Event Intensity

Event Intensity depicts a heat-map of events.
The y-axis is a compressed representation of the Context Tree, as displayed
alongside the Event Graph or the Event Table tools. In this mode, the number of
event or state changes that occur in each context, over the given time slice, is
represented by the intensity of a colored square. The brighter the square, the more
activity occurred. For example, suppose an event intensity Overview shows a
bright green block 1/3 of the way through a log and 2/3 of the way down the
Overview's vertical range. First select the Overview range that contains the
brightest block (this changes the selected range accordingly), then scroll down in
the Event Graph to reveal the context that is 2/3 of the way down the tree.

10

51
Wind River System Viewer
User's Guide, 3.2

52
 10
Analysis Types

10.1 General Notes 53

10.2 Event Graph/Table 54
10.3 Memory Usage 55
10.4 Core Usage per Core 55
10.5 Core Usage Aggregate 56
10.6 System Load 56
10.7 Running State 58
10.8 Ready State 58

10.1 General Notes

General graph and table handling (selection, bookmarking, and so on) is
essentially the same for all Analysis Type views. This is introduced, using the
Event Graph/Table as an example, under 2.3.3 Selection in the Event Graph, p.7, and
2.3.4 Selection in the Event Table, p.8.

53
 Wind River System Viewer
User's Guide, 3.2

10.2 Event Graph/Table

Events in the graph are laid out horizontally, from left to right, in order of
occurrence. The vertical arrangement is defined by the nodes in the Context Tree
to the left of the graph. The nodes of the Context Tree are arranged in descending
order of priority, with the highest initial priority at the top (changes to a task
priority during execution do not change its vertical position).
The Event Table also displays a Context Tree. Selecting the topmost context
displays all events. Selecting any other context, or a group of contexts, displays
only the events in the selected context(s). This behavior differs from the way the
Context Tree is used in the Event Graph.

Event Icons and State Stipples

The Event Graph uses event icons and state stipples to identify elements in the graph.
The event icons indicate the type of event that occurred at a given time. The state
stipples are represented as horizontal lines and indicate the state of each task at a
given time. To see what the icons/stipples mean, select
System Viewer > Open Legend.

Visualization of Multicore Behavior

The Event Graph uses the following annotations to graphically visualize multicore
behavior (see Figure 10-1):
„
A colored underbar to the executing state line, where the color represents a
core number.
„
A number next to the underbar which also represents the core number
These features are only present in logs which contain data from more than one
core.

54
 10 Analysis Types
10.3 Memory Usage

Figure 10-1 Visualizing multicore behavior

In Figure 10-1, above, you can see that core0 is executing task tShell0 which is
pre-empted by the higher priority task tLogTask. Since tShell0 remains runnable,
it migrates to run on core1.

10.3 Memory Usage

The Memory Usage Analysis charts memory allocation and deallocation resulting
from memLib function calls and is therefore only available for applications that
use the memLib library to allocate and free memory.
While the Event Graph indicates when memory events occur, it does not show how
much memory is allocated at any time. Memory Usage shows the addresses of
memory blocks that get allocated and freed. The analysis is especially useful for
detecting memory leaks. To diagnose rises in memory usage, you can filter out all
events except memory events.

10.4 Core Usage per Core

This analysis provides a representation of core usage for each core on the target.
The analysis is based on the activity of the idle context for each of the cores in the

55
 Wind River System Viewer
User's Guide, 3.2

system. When the system is not idle at any given instant of time, core usage is
deemed to be 100%.
The set of values used to show the core usage is calculated by dividing the log into
a configurable number of sample periods. Each of the sample periods will be of
equal duration (with the exception of the first and last ones, which will typically
half as long in order calculate a crossing point). For each of the sample periods, the
time the idle task is “running” is calculated as a percentage of the sample period.
This value is then used to create a core usage percentage, which is given a time
value in the middle of the sample period.
You can influence sampling in two ways:
„ Set the number of samples
This will divide the log up into the specified number of sample periods (plus
two extra for calculation of initial and end value crossing-points)
„ Set the sample duration
From the start of the selected range, the log will be divided up into the
specified time slices of equal length. The end of the selected range will be the
point where the time at the end of the log is too small to fit into a full sample
period.

10.5 Core Usage Aggregate

This analysis is visualized and constructed in the same way as 10.4 Core Usage per
Core, p.55. The main difference being that all of the CPUs in the system are
aggregated to provide a single system-wide core usage analysis.

10.6 System Load

System load is calculated, like core usage, using sample periods. However, the
calculations are based on the sum of the duration of the running and ready states
over the sample period. The calculated load value is therefore not a percentage, but

56
 10 Analysis Types
10.6 System Load

a floating point value. In other words, the full load will always be the number of
cores in the system (and not 100%).

Examples of Load Figures

Example 10-1 Single core system (Full load = 1)

One context is running and no others are ready:

Load = 1
One context is running and another is ready:
Load = 2 8

One context is running and two others are ready:

Load = 3
One context is running for 50% of the time, no others are running or ready:
Load = 0.5
Two contexts are each running for 50% of the time, no others are ready:
Load = 1
Two contexts are each running for 50% of the time, one other context is ready 50%
of the time:
Load = 1.5.

Example 10-2 Quad core system (Full load = 4)

One context is running and no others are ready or running:

Load = 1
Four contexts are running and no others are ready:
Load = 4
Two contexts are each running for 50% of the time, one other context is ready 50%
of the time:
Load = 1.5
Two contexts are each running for 50% of the time, two other contexts are ready
50% of the time:
Load = 2

57
 Wind River System Viewer
User's Guide, 3.2

10.7 Running State

This is an analysis of the time the contexts were in the running state.
The analysis can be useful for detecting core affinity problems; that is, either where
a context will tend to run on a particular core (the context will be seen as running
on that core all the time), or where a context switches cores unduly (the number of
states for a given context running is high, even though the context is running a
large percentage of the selected period).
The overview shows the states in relation to time and duration. The data display
shows a tabular representation of the context names, number of states, and the
time as a percentage over the selected range that the context was in the running
state. The states are shown for each core.

10.8 Ready State

This analysis can be useful for detecting priority problems. For example, contexts
that are ready (blocked) for long periods because their priority is too low.
This is analogous the Running State, p.58, except that the contexts’ ready states are
used in the analysis. The ready state is not attributable to any CPU so the analysis
is system based rather than core based.

58
 11
Filtering and Searching

11.1 Filtering 59
11.2 Searching 60

11.1 Filtering
You can filter information displayed to focus only on specific tasks and events that
you want to study at a given time. When large numbers of events that are typically
generated in high volume, such as interrupt and network events, are viewed at low
zoom levels, they slow the redrawing of the viewing tools and can also obscure
other events. You can unclutter the display by filtering.
All views, including the Overview, reflect any filters you set. Filtering only affects
the displayed information, not the actual data stored in the log. To change
information that is actually logged, you have to change the event logging level or
the event libraries for which you enable logging. You would do this prior to
starting logging, see 4. The Event Logging Level.
The Event Graph/Table context menu provides context sensitive filters that let you
hide all instances of selected event(s) or, in multicore environments, CPU(s).

59
 Wind River System Viewer
User's Guide, 3.2

11.1.1 Creating Filters

You create your own filters by choosing System Viewer > Filter. This opens the
Filtering dialog box, where you can filter out anything from entire containers or
contexts, through event classes, to individual event types, and objects. In multicore
environments you can also selectively show/hide cores.
Clear the checkboxes of the things you want to hide (you can use the right-click
context menu to (de)select subtrees). Note that there is a dependency that flows
from left to right through the tabs; for example, if you deselect something on the
Container tab, anything on the Event or other tabs will also be hidden (regardless
of whether the checkbox is selected or not) if it is a member of a hidden container.
Once you have created filters, you can later access them by selecting
System Viewer > Filter/Search History. If a filter is active, this is indicated by an
icon in the status bar.

11.2 Searching
You create/run searches by choosing System Viewer > Search. This opens the
Search dialog box, where you can select anything from entire containers or
contexts, through event classes, to individual event types and objects. In multicore
environments you can also selectively choose which core(s) to include in your
search. On the Range tab, you can restrict the scope of your search to the selected
range in the Overview.
Select the checkboxes of the things you want to find (you can use the right-click
context menu to (de)select subtrees). Note that there is a dependency that flows
from left to right through the tabs; for example, if you deselect something on the
Container tab, anything on the Event or other tabs will not be matched (regardless
of whether the checkbox is selected or not) if it is a member of a hidden container.
Furthermore, if you have applied a filter (see 11.1 Filtering, p.59) the search applies
to the filtered display.
Once you have created searches, you can later access them by selecting
System Viewer > Filter/Search History.
When you run a search by clicking OK in the Search dialog box, the Analysis
Filter/Search view opens with a list of matched items. To navigate matches, you
can either use the arrow buttons at the top-right of the panel, or double-click on a

60
 11 Filtering and Searching
11.2 Searching

match; this will position the Event Cursor to the matched item in the open analysis
views.

12

61
Wind River System Viewer
User's Guide, 3.2

62
 12
Timestamps

12.1 Timelines 63
12.2 Timestamp Ticks 64
12.3 High-Resolution Timestamping 64
12.4 Sequential Timestamping 65
12.5 Custom Timestamp Drivers 65

12.1 Timelines
When you develop your application for a target with a supported timestamp
driver, the instrumented kernel uses timestamps. The instrumented kernel can tag
certain events with high-resolution timestamps, sequence numbers, or with user
defined timestamps. These events are then displayed in various views along a
timeline that shows when each event occurred, based on these timestamps.

! CAUTION: On supported targets with limited hardware resources, System Viewer

manages the system clock, the auxiliary clock, or both when the timestamp driver
is enabled. In this case, these clocks are not available for your system.

63
 Wind River System Viewer
User's Guide, 3.2

12.2 Timestamp Ticks

All time measurements such as any event, bookmark, measurement marker, range
selection, and so on, are aligned to a tick. The amount of time defining a tick, may
or may not be a real time unit:
„
In a sequential log, every event captured is assigned a tick value which
increments by 1 for successive events. When displayed, these sequential
timestamps are shown as #n where n is an incrementing number. This indicates
that the timestamps logged against each event is not a real-time measurement,
but a sequence number. For more information, see 12.4 Sequential
Timestamping, p.65.
„
In a real-time log, the time per tick is specified in the raw log as the number of
ticks per second and this is related to the resolution of the clock hardware
being used with the BSP for timestamping purposes. The timestamps are
printed out using s, ms, us, ns, ps; whichever is most appropriate based on the
formula: time = tick / (ticks-per-second)
The timestamp driver’s resolution is hardware dependent, but is typically
between 100 KHz (10 microseconds per tick) and 1 MHz (1 microsecond per
tick).
For information on the system timestamp driver for any supported board, see the
entry for the board in the online BSP APIs.

12.3 High-Resolution Timestamping

Some BSPs provided by Wind River have a high-resolution timestamp driver. If
this is the case, include the following component in your system image:
INCLUDE_SYS_TIMESTAMP
BSP specific timestamping
BSP-specific drivers are in located the directory
installDir/vxworks-N.N/target/src/drv/timer; the corresponding header files are
located in installDir/vxworks-N.N/target/h/drv/timer.
If you are using a board that does not have a timestamp driver, or if you do not
want to use the one it has, you can use sequential or user-defined timestamping
and include the appropriate component.

64
 12 Timestamps
12.4 Sequential Timestamping

12.4 Sequential Timestamping

When the real-time system runs on an unsupported board, or on a supported
board without the timestamp driver included, the instrumented kernel
automatically uses its sequence-stamp driver. This driver tags events with sequence
numbers that represent the order in which the events occur on the target. The
events are then spaced equidistantly from each other in the event graph and the
timeline scale is in event sequence numbers rather than seconds. The support
component for sequential timestamping is INCLUDE_SEQ_TIMESTAMP.

12.5 Custom Timestamp Drivers

11
Wind River supplies the system timestamp, but you may write your own
timestamp driver or use the timestamp provided by an emulator. The support
component for user-defined timestamping is INCLUDE_USER_TIMESTAMP. For
more information, see VxWorks Device Driver Developer's Guide:Timestamp Drivers.

65
Wind River System Viewer
User's Guide, 3.2

66
 13
Triggering

13.1 Introduction 67
13.2 Getting Started 68
13.3 Using Triggering 69
13.4 Creating and Running the Sample Triggers 76
13.5 Using Functions with Triggering 83
13.6 Importing Previous Version Trigger Files 88

13.1 Introduction
Triggering is an operating system feature that uses instrumented events, mostly
found at the same point in the code as System Viewer events. As an alterative to
the System Viewer Configuration utility, you can use triggering to start and stop
the logging process. More importantly, triggering allows you to precisely control
when and how to start and stop logging using instrumented events.
Most events that you can log can also be written to activate a trigger. Triggering,
specifies an action to be performed when a trigger is hit. You select the actions for
triggers that include controlling how System Viewer logs events.

67
 Wind River System Viewer
User's Guide, 3.2

NOTE: If your system is configured with triggering support, each time an

instrumented point is hit, the operating system checks whether triggering is
enabled. For more information, see C. Triggering API.

System Viewer provides a triggering interface that manages all aspects of

triggering. Using the triggering interface you can create and run sample triggers
and define them using various functions. Triggering API is also provided so you
can use VxWorks triggering in conjunction with System Viewer logging.
Sample triggering files are available for your use in
installDir/workbench-N.N/wrsv/N.N/samples/vxworksN/triggering. For
information, see C. Triggering API.

13.2 Getting Started

System Viewer provides a triggering interface so you can support, define,
configure, save, validate, download and run trigger files.
Learn how to use triggering by performing the following the steps as per your
development need and preference. Using each set of procedures, you will learn
how to use the triggering interface, create and use basic triggers in coordination
with log files, and the trigger functions in general.

13.2.1 To Create a Trigger

1. Define a trigger specification by defining the conditions to be checked when

the trigger’s specification is matched.
2. Define the action to be taken when the triggers fires and specify the trigger to
enable once the trigger has fired.
3. Save the trigger to a file if required.
4. Prepare your target before downloading the trigger by declaring all objects,
variables and functions on the target before a trigger can be uploaded and
triggering starts.

68
 13 Triggering
13.3 Using Triggering

13.2.2 Using Sample Trigger Files

To understand simple conditional and chained triggers, create and run the sample
triggering examples in
installDir/workbench-N.N/wrsv/N.N/samples/vxworksN/triggering.
1. Re-create and run the simple conditional triggering example described in
13.4.1 Simple Conditional Trigger Example, p.76.
2. Extend the simple conditional trigger to include a trigger that is chained to it,
as described in 13.4.2 Chaining Simple Conditional Triggers Example, p.78.

Understanding Functions with Triggering

As described in 13.5 Using Functions with Triggering, p.83, Triggering allows you to
use a function as a condition or as an action.
1. You can create a trigger defined with a Condition on Function. For more
details, see 13.5.1 Using a Function as a Condition, p.83.
13
2. You can create a trigger defined to use a function as an action. For more details,
see 13.5.2 Writing a Call Function as an Action, p.85.
3. Finally, you can create and upload triggers using the Triggering utility or the
triggering API. For more information, see C. Triggering API, which includes an
example for System Viewer logging described in 13.5.3 Starting and Stopping
System Viewer with User Events, p.86.

NOTE: An application loads events from the required dictionary, therefore if you
open triggering against a live target and the target dies, you can still use triggering
to create and edit triggers even with the target down.

13.3 Using Triggering

The Triggering utility is used to create and use triggers. It can be launched from a
selected target running within the Remote Systems view.
The Triggering utility depicts each trigger in table format with columns
categorizing attributes of the trigger. When you first open triggering,

69
 Wind River System Viewer
User's Guide, 3.2

System Viewer scans the target for triggers, and displays the ones it finds in the
table.

13.3.1 Using the Trigger Maintenance Utility

You specify new triggers, edit triggers, set up conditions and actions for simple
and chain triggers using four panes in the Triggering Maintenance utility.

To Create a Trigger

Step 1: Open the Trigger Maintenance Utility

Select Triggering > New Trigger
A trigger with a default name is presented in the Trigger Maintenance dialog. A
default name is used, however, it is advisable to specify unique names for triggers.

Step 2: Select Attributes to Define the Trigger

Specification contains drop-down list boxes from which you specify the criteria
for defining a trigger..
1. Select Trigger is initially enabled if you wish your trigger to be enabled when
you download it. System Viewer enables this feature by default. If a trigger is
chained, that is enabled by an earlier trigger or started from code, uncheck the
checkbox.
2. VxWorks
3. From Context, specify the context in which the event that causes the trigger to
fire occurs. The event can occur in any context, including the system context.
The Any or Any Interrupt options disable the Call Function option that you
can select from the Action drop-down listbox.
4. From Event, specify the type of event that causes the trigger to fire. The event
can occur in any specific task, or in any ISR (interrupt service routine).
When user# or intEnt is selected from the Event drop-down list box, you can
enter a identification number in the # text box. This is a user event created with
the trgEvent( ) routine. For more information, see the reference entry for
trgEvent( ) and Creating a User Event to Fire a Trigger, p.149.
5. From Object, select the object ID of all objects of the type specified in the Event
listbox. For example, if you selected semGive or semTake as your event for the

70
 13 Triggering
13.3 Using Triggering

trigger, the Object listbox displays any semaphores on the target. If you
created a semaphore on the shell as in,
% mySem = semBCreate()
type mySem in the listbox and triggering finds the appropriate semaphore for
you.
6. Check Disable trigger after firing if the trigger should be disabled after it
fires. System Viewer enables this feature by default. If you do not check this
box, your trigger remains active to continue firing when conditions are met.

Step 3: Select Conditions for the Trigger to Fire

You can define a trigger to isolate an event as close as possible to the start of a
sequence of interest. Once you identify unique events preceding a sequence,
they can then be used as potential trigger points.
For example, you may observe that, shortly before the sequence of interest, a
semaphore is given. It might be possible to identify the task context from
which the semGive( ) is performed and possibly the ID of the semaphore
being given. These criteria can be used to define when the trigger that initiates 13
logging fires.
Sometimes the criteria used to define the trigger are not sufficient to uniquely
detect the start of the region of interest, if a task takes and gives the same
semaphore more than once. To uniquely detect the start of the region of
interest, you can refine the trigger by using a conditional qualification. For
example, you can examine a variable (by symbol or address) for a specific
value or range of values, or you can invoke a specific function and test the
result.
The Condition pane contains a drop-down listbox for defining whether or not
a condition is evaluated, as well as two text boxes and an operator listbox for
specifying a condition to be evaluated. The text box on the left is for a function
or variable name, and the text box on the right is for a constant value.
To make a trigger conditional upon a variable or function that takes a specific
value or range of values, follow these steps and ensure that the correct types
are used:
1. Change Unconditionally to Conditional on Function or
Conditional on Variable. The two text boxes are enabled when
Unconditional is not selected.
2. Enter the function or variable name in the first edit box. The function or
variable name must be a known 32-bit identifier on the target.

71
 Wind River System Viewer
User's Guide, 3.2

3. Select the matching criterion by choosing one of the operators from the
drop-down menu (==, <=, <, and so on).
4. Enter the constant value to test in the second text box. The value must be a
32-bit integer constant in either decimal or hexadecimal format.
The criteria specified for event, context, and object, conditions are tested for on
the target. If the criteria are met, triggering proceeds. For triggering examples
that use conditions, see 13.4.1 Simple Conditional Trigger Example, p.76 and
13.5.1 Using a Function as a Condition, p.83.

Step 4: Select Actions to be performed when the Trigger Conditions are Met
System Viewer performs actions on a trigger when that trigger is set and the
event occurs. You define trigger actions and their range from controlling
System Viewer to performing user-specific requests. These actions are
performed when the specification criteria are met, and any specified condition
is matched.
Select actions for the trigger as follows:

No Action

Select No Action when no action is taken on the trigger. For example, you can
use this option to:
„
fire the first in a sequence of chained triggers, where the first trigger has
no other purpose than to enable another trigger.
„
determine a specific event has occurred when the associated trigger fires.
The trigger is then disabled after it fires, and you can examine the
Triggering utility to see when it has fired.
„
use as a counting mechanism. If the trigger is not disabled after firing, you
can update the Triggering utility using the View menu and see a count of
the number of times the trigger has fired under Status. For more
information, see 13.3.3 Downloading and Running Triggers, p.74.

System Viewer Logging Actions

Select Start System Viewer Logging to start logging when the trigger fires and
Stop System Viewer Logging to stop logging when the trigger fires. For
examples that use triggers to start and stop logging, see 13.4.3 Chaining Triggers
for System Viewer Logging Example, p.80 and 13.5.3 Starting and Stopping
System Viewer with User Events, p.86.

72
 13 Triggering
13.3 Using Triggering

Call Function

Select Call Function to call the specified function on the target with the given
integer parameter. Selecting Call Function enables two text box fields, where
the first field specifies the function name and the second field specifies an
integer argument to that function. For more information, see 13.5.2 Writing a
Call Function as an Action, p.85.

Taskstop

Select Taskstop to stop the task which is currently executing. You can resume
the task by using the taskResume comand on a shell.

Defer Action

Check Defer Action to defer the action until it is safe to execute the trigger
action. For example, suppose you wanted to make sure your action function
did not run within ISR or system context. In this case, check Defer Action, if
the function contains calls to any function that is not permitted in ISR context.

NOTE: Triggering automatically spawns a task called tActDef that executes 13

functions on the trigger work queue when the system is out of any critical region.
If your application runs at a higher priority than tActDef, you may have to adjust
the priority if you want the trigger action to be executed.

Step 5: Determine if the Trigger will be linked to Another Trigger

The trigger can be programmed to enable another trigger when it fires. The
trigger that should be enabled can be specified in this text box. For more
information, see the example in 13.4.2 Chaining Simple Conditional Triggers
Example, p.78.

Step 6: Click OK to return to the Triggering Utility

13.3.2 Defining Variables to Validate Triggers

System Viewer indicates valid triggers in black text. Before using a trigger,
variables on which it depends, must be defined. Invalid triggers require that you
define variables before they can be used.
In the trigger list, a red text item relies on a target requirement that does not exist.
This is typically a variable that needs to be defined.

73
 Wind River System Viewer
User's Guide, 3.2

When you point to the invalid item and pause briefly for the error information,
System Viewer indicates the reason why a red text item is invalid, through a
tooltip. After correcting the error, you can update the trigger by clicking the refresh
toolbar button.
After variables are defined and refreshed in the trigger list, the green GO toolbar
button indicates the triggers are validated and ready to download.

13.3.3 Downloading and Running Triggers

You must download a trigger to the target before you use it by clicking GO. Once
you download a trigger, the Target column indicates the status of that trigger,
changing from Not Set to ARMED, FIRED, COUNTING, and so on, as the trigger
runs.

Reading Target Icons

The Target column indicates whether a trigger is successfully downloaded to the

target, resident on the host computer or in a changing state using icons as follows:
Host-only Triggers
This icon indicates the trigger is not downloaded to the target, and only stored
in triggering. Host-only triggers are lost if the System Viewer launcher is
closed on UNIX, or Wind River Workbench is closed on Windows, and you
have not saved your trigger to a trigger file. Host-only triggers will remain
only if triggering is closed and then re-opened.
Target-Resident Triggers
This icon indicates the trigger is resident on the target. Target-resident triggers
still exist after you close and re-open triggering, that is if the same target is
connected and you have not rebooted the target.
Trigger Changed on Target
This icon indicates the trigger changed on the host since it was downloaded to
the target. System Viewer will update the target trigger the next time the
trigger is started.

74
 13 Triggering
13.3 Using Triggering

Reading Trigger Icons

Various icons in the Trigger column indicates the state of a trigger as follows:
Yellow
This icon indicates the trigger is on the host computer, valid and ready for
download. The GO button is enabled.
Red
This icon indicates the trigger is on the host computer, but not valid and cannot
be downloaded. The GO button is disabled.
Green
This icon indicates the trigger is downloaded to the target and ARMED. If you
are running triggering, the trigger fires when the conditions for firing are met.
If triggering stops before the trigger fires, this icon indicates that the last state
of the trigger is ARMED.
Gray
13
This icon indicates the trigger is downloaded to the target, but not FIRED
because it was initially DISABLED. If you are running triggering, the trigger
does not fire until it is enabled. If triggering stops before the trigger is ARMED
or FIRED, this icon indicates the last state of the trigger is DISABLED.
Gray with Check mark
This icon indicates the trigger is FIRED and now DISABLED. If you are
running triggering, the trigger is ARMED, has FIRED and has been disabled
because the Disable after fire option of the trigger was selected. The trigger
remains in this state until you click GO.
Yellow with 123
This icon indicates a COUNTING trigger. The trigger is FIRED, but has not
disabled because Disable after fire was not selected when the trigger was
defined. If you are running triggering, the trigger is ARMED, has FIRED and
continues to fire each time its firing condition is met. To update the value in the
Hit Count column, click View > Refresh.

75
 Wind River System Viewer
User's Guide, 3.2

13.4 Creating and Running the Sample Triggers

System Viewer provides three sample triggering files:
helloGoodbye.trig
Trigger file that demonstrates the process of chaining in triggering which
uses a combination of trigger files, each invoked from the other.
simpleCond.trig
Trigger file that demonstrates the use of a simple conditional trigger.
startStopwv.trig
Trigger file to start and stop System Viewer logging.

13.4.1 Simple Conditional Trigger Example

This example describes how to create a simple conditional trigger using

simpleCond.trig in
installDir/workbench-N.N/wrsv/N.N/samples/vxworksN/triggering . This trigger
file fires when variable foo takes the value 1. When that condition is met, printf( )
is called with the value helloString.
You can choose to load the example trigger and begin using it, or recreate the
trigger and save it under a different name. If you have not loaded
simpleCond.trig, create and define the trigger as follows.

Step 1: Create and Define the Conditional Trigger

1. Open the Trigger Maintenance Utility.
2. Select Edit > New trigger.
3. Enter hello in Trigger Name.
4. From Specification, define the trigger as follows:
„
Check Trigger is initially enabled
„
Select Any Task from Context
„
Select Any Event from Event. The Event Id will be disabled
„
Select Any Object from Object
„
Check Disable trigger after firing
5. From Condition, define the trigger as follows:
„
Select Conditional on Variable from the drop-down listbox
„
Enter foo as the variable name

76
 13 Triggering
13.4 Creating and Running the Sample Triggers

„
Choose == from the drop-down listbox
„
Enter 1 as the constant value
6. From Actions, define the trigger as follows:
„
Select Call Function in the drop-down listbox
„
Enter printf in the text box
„
Enter helloString in the argument text box
„ Check Defer action
7. As this simple trigger is not chained, from Chaining, select None from
Enable trigger.
8. Save your trigger using a unique name, other than those used in the samples
folder.

Step 2: Define the Variables and Validate the Trigger

1. Start the Host Shell and create the variable foo, as follows:
-> foo=0
new symbol "foo" added to “vxKernel” symbol table.
13
2. Create helloString as follows:
-> helloString="hello\n"
new symbol "helloString" added to “vxKernel” symbol table.

! WARNING: The type entered into the argument text box, in this case helloString,
must be a variable not an integer.

3. Select Triggering > Refresh, or click the Refresh toolbar button to validate the
trigger.

Step 3: Download and Run the Trigger

1. Select Triggering > Start, or click the Start toolbar button to download the
trigger.
2. To fire the trigger, the condition for foo must be met. In the Host Shell, set foo
equal to the value 1, as follows:
-> foo=1

The string “hello” prints out. The trigger status is updated to show that it has
fired.
3. Click Select Triggering > Stop, or click the Stop toolbar button to download
the trigger..

77
 Wind River System Viewer
User's Guide, 3.2

13.4.2 Chaining Simple Conditional Triggers Example

The process of chaining in System Viewer ensures triggers are fired in a certain
order.
Using helloGoodbye.trig in
installDir/workbench-N.N/wrsv/N.N/samples/vxworksN/triggering, this
example shows you how to create a simple set of chained triggers that print out
“hello” and “goodbye” based on the system variable vxTicks.
You can choose to load the example trigger and begin using it, or recreate the
trigger and save it under a different name. If you have not loaded
helloGoodbye.trig, create and define the trigger as follows.

Step 1: Create and Define the Hello Trigger

1. Open the Trigger Maintenance Utility.
2. Select Edit > trigger.
3. Enter hello in Trigger Name.
4. From Specification, define the trigger as follows:
„
Check Trigger is initially enabled
„
Select Any Task from Context
„
Select Any Event from Event. The Event Id will be disabled
„
Select Any Object from Object
„
Check Disable trigger after firing
5. From Condition, define the trigger as follows:
„
Select Conditional on Variable from the drop-down listbox
„
Enter vxTicks as the variable name
„
Choose > from the drop-down listbox
„
Enter 6144 as the constant value
6. From Actions, define the trigger as follows:
„
Select Call Function in the drop-down listbox
„
Enter printf in the text box
„
Enter helloString in the argument text box
„
Check Defer action
7. From Chaining, type goodbye in Enable Trigger. The text turns red because
you have not as yet created the goodbye trigger. After you click OK to
complete your trigger, notice that it appears in red text in the table.

78
 13 Triggering
13.4 Creating and Running the Sample Triggers

8. Save your trigger using a unique name, other than those used in the samples
folder.

Step 2: Define the Goodbye Trigger

1. Open the Trigger Maintenance Utility.
2. Select Edit > New trigger.
3. Enter goodbye in Trigger Name.
4. From Specification, define the trigger as follows:
„
Un-check Trigger is initially enabled
„
Select Any Task from Context
„
Select Any Event from Event. The Event Id will be disabled
„
Select Any Object from Object
„
Check Disable trigger after firing as this trigger is not initially enabled
because it is chained to the hello trigger, therefore it becomes enabled once
that trigger fires.
5. From Condition, define the trigger as follows:
13
„
Select Conditional on Variable from the drop-down listbox
„
Enter vxTicks as the variable name
„
Choose > from the drop-down listbox
„
Enter 6744 as the constant value
6. From Actions, define the trigger as follows:
„
Select Call Function in the drop-down listbox
„
Enter printf in the text box
„
Enter goodbyeString in the argument text box
„
Check Defer action
7. From Chaining, select None from Enable trigger.
8. Save your trigger using a unique name, other than those used in the samples
folder.
Now that you have created the goodbye trigger, notice the hello trigger no longer
appears in red. Triggering looks for matching trigger names or IDs, and if it finds
them, it uses them. If not, it assumes the trigger will be created later, and it keeps
the invalid trigger until the object that validates it is created.
This works for many boxes. If you have a semaphore mySem, you don’t have to
search the object yourself; just enter mySem in the Object listbox and it is matched
if it actually exists.

79
 Wind River System Viewer
User's Guide, 3.2

Step 3: Define the Variables and Validate the Triggers

1. Start the Host Shell and create the variable helloString. as follows:
-> helloString="hello\n"
new symbol "helloString" added to symbol table.

2. Create the variable goodbyeString. as follows:

-> goodbyeString="goodbye\n"
new symbol "goodbyeString" added to symbol table.

3. Select View > Refresh, or simply click the Refresh button to validate the
trigger.

Step 4: Download and Run the Hello and Goodbye Triggers

1. To download the trigger, select Triggering > Start, or click the Start toolbar
button to download the trigger.. vxTicks is a global variable that counts ticks.
Trigger hello prints “hello” when vxTicks is greater than 0x6144.
2. Click View to refresh items or toolbar buttons until the Triggering utility
shows that the hello trigger has fired. Once the hello trigger fires, the goodbye
trigger is activated, and it prints “goodbye” when vxTicks is greater than
0x6744.
3. Select Triggering > Stop, or click the Stop toolbar button to download the
trigger. to stop the triggering. Triggering stops automatically when there are
no triggers left armed or counting.

NOTE: You can use the shell to find the current value of vxTicks and reset the
values in the Trigger Maintenance Utility to be greater than the current value.
Otherwise, one or both triggers fire immediately and the log you collect is almost
empty.

13.4.3 Chaining Triggers for System Viewer Logging Example

To use triggering to collect a System Viewer log, you must define two triggers, one
having the action to start log collection and one with the action to stop log
collection. In most cases, triggers used to collect a System Viewer log are chained,
since the order of their firing is critical.
Using startStopwv.trig in
installDir/workbench-N.N/wrsv/N.N/samples/vxworksN/triggering, you can
create the sample triggers used to start and stop System Viewer logging.

80
 13 Triggering
13.4 Creating and Running the Sample Triggers

You can choose to load the example trigger and begin using it, or recreate the
trigger and save it under a different name. If you have not loaded startStopwv.trig,
create and define the trigger as follows:

Step 1: Define the Start System Viewer Trigger

1. Open the Trigger Maintenance Utility.
2. Select Edit > New trigger.
3. Enter startWV in Trigger Name.
4. From Specification, define the trigger as follows:
„
Check Trigger is initially enabled
„
Select Any Task from Context
„
Select Any Event from Event. The Event Id will be disabled
„
Select Any Object from Object
„
Check Disable trigger after firing. Calling startWV more than once
results in an error, so it is important, for a trigger that starts logging to
disable it after it fires.
13
5. From Condition, define the trigger as follows:
„
Select Conditional on Variable from the drop-down listbox
„
Enter foo as the variable name
„
Choose == from the drop-down listbox
„
Enter 1 as the constant value
6. From Actions, once you have defined how the trigger will fire, select
Start Wind River System Viewer Logging in the drop-down listbox.
Although not required, it is often desirable to define a trigger to stop log
collection. Doing so focuses the log on the sequence of interest and saves both
resources and analysis effort.
7. From Chaining, type stopWV in Enable Trigger, if you decide to create
another trigger to stop log collection.
8. Click OK to save this trigger. The System Viewer Configuration utility opens
automatically, allowing you to review the current configuration, and change it
if necessary.
9. If you are not creating a trigger that stops System Viewer logging, leave the
System Viewer Configuration utility open so you can stop logging manually.
Otherwise, the window my be closed.

81
 Wind River System Viewer
User's Guide, 3.2

Step 2: Define the Stop System Viewer Trigger

To create this trigger, use the same trigger file as for the startWV trigger.
1. Open the Trigger Maintenance Utility.
2. Select Edit > New trigger.
3. Enter stopWV in Trigger Name.
4. From Specification, define the trigger as follows:
„
Un-check Trigger is initially enabled
„
Select Any Task from Context
„
Select Any Event from Event. The Event Id will be disabled
„
Select Any Object from Object
„
Check Disable trigger after firing. This trigger is not initially enabled, but
is chained to the startWV trigger, so that it cannot fire until startWV has
fired.
5. From Condition, define the trigger as follows:
„
Select Conditional on Variable from the drop-down listbox
„
Enter foo as the variable name
„
Choose == from the drop-down listbox
„
Enter 2 as the constant value
6. From Actions, once you have defined how the trigger will fire, select
Stop Wind River System Viewer Logging in the drop-down listbox.
7. From Chaining, select None in Enable Trigger, as the stopWV trigger does
not, itself, chain to another trigger.
8. Click OK to save this trigger. Save both triggers to the same file.

Step 3: Define the Variables and Validate the Trigger

1. Start the Host Shell and create the variable foo as follows:
-> foo=0
new symbol "foo" added to symbol table.

2. Select View > Refresh, or click the Refresh button to validate the trigger.

Step 4: Download and Run the Triggers

1. Select Triggering > Start, or click the Start toolbar button to download the
trigger.to download the trigger.
2. System Viewer logging starts when the startWV trigger fires. To fire this
trigger, the condition for foo for the startWV trigger must be met. When you

82
 13 Triggering
13.5 Using Functions with Triggering

are ready to begin System Viewer logging, enter the following in the Host
Shell:
-> foo=1

3. Click the Update button.

This starts System Viewer logging.
Click refresh on the triggering utility toolbar or View > refresh from the
menu. The trigger is now shown as disabled and the status is updated to show
it has fired.
System Viewer logging stops when the stopWV trigger fires. This trigger has
now become enabled because it was chained to the startWV trigger, which has
fired.
4. To fire the stopWV trigger, the condition for foo for that trigger must be met.
When you are ready to stop logging, enter the following in the Host Shell:
-> foo=2

NOTE: When a triggering event fires, it is logged as an event in the System Viewer
log. A trigger can start or stop logging part way into a resulting log (for example, 13
25% into the resulting log). This facility is known as pre-triggering and results in a
record of the events on either side of a trigger firing event.

13.5 Using Functions with Triggering

Triggering allows you to use a function as a condition or as a trigger action.

13.5.1 Using a Function as a Condition

You can write and use a function specifically to test a condition. The function used
as a condition is executed during trigger evaluation if the criteria for event, context,
and object conditions are satisfied.
One technique is to write a function that fires after a specified time period, for
instance, by comparing the value of the system tick count against its value when
the trigger to start the sequence fired. A conditional function cannot be deferred.

83
 Wind River System Viewer
User's Guide, 3.2

You must make the function available on the target and enter its function name as
the condition item. The function is executed if all of the criteria defined for the
trigger under Specification are met. Once the function executes, the trigger fires
only when the function returns the value specified by the constant value.
When calling a function as a condition, it is very important that the condition is
only to be used in conjunction with a specification that limits the number of times
the condition is tested. For example, if a condition function to test a semaphore is
written and is tested without a limiting specification, then the execution of the
conditional function will cause more events which will each cause the condition
function to be called. This nesting of calls will cause a race condition on the target
and will eventually lead to the target crashing.

NOTE: If you use a function as a condition, the trigger Specification must define
the Event as user#, and the Event ID as 10. See also 13.5.3 Starting and Stopping
System Viewer with User Events, p.86.

Defining and Loading Condition Functions

The format and content of the condition function must follow the syntax below:
int conditionFunction (void)
{
int returnValue;
*/ Function body */
...
return (returnValue);
}

1. Provide a valid conditional function as per the above example

2. Compile the function and load the resulting object module onto the target. For
example, if a function conditionFunction( ) is contained in a C module called
conditionFunction.c and compiled into an object module
conditionFunction.o, the object module can be loaded on to the target from the
shell using the following command:
-> ld < conditionFunction.o

3. Create a trigger that uses this function as a condition

4. Define the trigger with the function name and the value returned under the
conditions you want your trigger to fire.

84
 13 Triggering
13.5 Using Functions with Triggering

Writing Condition Function Code

The body of a function used as a condition cannot contain any function calls that
are not permitted in an ISR context. This is because, depending on the criteria
specified for event, context, and object conditions, the function provided could be
executed within an ISR. Therefore, unless the combination of trigger specifications
set in the event, context, and object fields guarantees that the function can only be
satisfied in task context, (for example, by setting Context to Any Task or to a specific
task) the body of the function can include only code (or function calls) that can be
safely executed within an ISR or system context. For example, the following
conditional function is invalid because semTake( ) must not be used in an ISR.
int conditionFunction (void)
{
if (vxTicks >= (sysClkRateGet() * 60 * 60))
{
/* semTake NOT ALLOWED in ISR context*/
semTake (mySem);

/* printf NOT ALLOWED in ISR context*/

printf ("The system has been up for more than an hour\n");
13
return 1;
}
return 0;
}

As trigger evaluation points are present throughout the VxWorks kernel, you can
not use printf( ) or logMsg( ) in condition functions. The above example could be
corrected by making the printf( ) into a trigger action function and checking Defer,
described in 13.5.2 Writing a Call Function as an Action, p.85. For information about
which routines can safely be called from ISRs, see the VxWorks Application
Programmer’s Guide.
You can also call a user-defined function that collects appropriate diagnostic
information at the time the trigger fires. One way to do this would be to use
wvEvent( ) in user-defined function. For more information, see The wvEvent( )
Routine, p.135.

13.5.2 Writing a Call Function as an Action

A call function takes an integer argument and returns an integer value. Unlike a
condition function, an action function can be deferred because the function is not
executed to evaluate the trigger; instead it is added to a trigger work queue. For
more information, see Defer Action, p.73.

85
 Wind River System Viewer
User's Guide, 3.2

An example of an action function is:

int myActionFunc (int arg)
{
printf(“Trigger fired.\n”);
/* other code */
return 1; (returnValue); /* return value is ignored */
}

To create a trigger that uses the function

1. Open the Trigger Maintenance Utility.
2. From Action, select Call Function from the drop-down list.
3. Enter the function name in the first text box and the integer argument to the
function in the second text box.
4. Check Defer Action as myActionFunc calls printf( ) for this function.

13.5.3 Starting and Stopping System Viewer with User Events

This example demonstrates how to start and stop System Viewer with a VxWorks
family User Event and triggering. User Event IDs must be in the range of
40000-65535.

Step 1: Create a New Trigger with these Definitions

1. Open the Trigger Maintenance Utility.
2. Select Edit > New trigger.
3. Enter startWV in Trigger Name.
4. From Specification, define the trigger as follows:
„
Check Trigger is initially enabled.
„
Select user# from Event.
„
Enter an Event ID of 10 which is the equivalent of the user event number
40010.
5. From Action, select Start System Viewer Logging.
6. Select stopWv from Enable Trigger.
7. Click OK. If you have not already opened the System Viewer Configuration
utility, System Viewer opens this window, so you can setup configuration.

86
 13 Triggering
13.5 Using Functions with Triggering

Step 2: Create a Second Trigger with these Definitions

1. Open the Trigger Maintenance utility.
2. Select Edit > New trigger.
3. Enter stopWV in Trigger Name. Note the upper-case V.
4. From Specification, define the trigger as follows:
„
Uncheck Trigger is initially enabled.
„
Select user# from Event.
„
Enter an Event Id of 20 which is the equivalent of the user event number
40020.
5. From Action, select Stop System Viewer Logging.
6. Click GO to download the triggers.

Step 3: Create the User Events

1. Start the shell
2. Create a user event using the trgEvent( ) routine and the Event Id for the 13
startWv trigger:
-> trgEvent(40010)

System Viewer logging starts as soon as this event is created.

3. Click Refresh on Triggering to see that the trigger has fired.
4. Create another user event, in the same manner, but this time using the
Event Id for the stopWv trigger as the routine argument:
-> trgEvent(40020)

System Viewer logging stops as soon as this event is created.

Triggering stops automatically. Your triggers still remain on the target, but the
triggering function is turned off. If you are using deferred upload mode,
upload your System Viewer log using the upload button in the
System Viewer Configuration utility.
When you click GO to restart triggering, whatever configuration is currently
in place on the host is downloaded and started. Even if it is the same
configuration that was previously loaded, all triggers are reset as they were
initially. Execution does not continue from where it was when you stopped
triggering.

87
 Wind River System Viewer
User's Guide, 3.2

13.6 Importing Previous Version Trigger Files

Trigger files saved by WindView 2x and WindView 3x have different formats to the
current trigger files. Although trigger files from previous versions of Tornado have
a different format to the trigger files currently used, System Viewer treats a trigger
file generated from Tornado in the same manner as a Wind River Workbench
generated trigger file, and all of the triggering facilities apply.
However, you must import previous version trigger files, and save them in the
current version of System Viewer. To import trigger files from previous versions of
WindView, use the File > Import menu item.
To import previous version trigger files, use the File menu. If you use File > Open,
the parser fails and an Error parsing file message appears.The Import facility
allows you to convert and load old format trigger files. If you import a non
Tornado.x trigger file using the import option or if you use the File > Import to
open a Wind River Workbench generated file, the Trigger Import Error message
appears.
When you import trigger files, the new triggers are created using a name and
number based on the old file. For example, suppose you import from an old trigger
file, tor2.trg which has two triggers. The two triggers are imported and named
tor2.0 and tor2.1.
An imported trigger with an unsupported action or event can be successfully
imported, but it will be marked as invalid and appears in red text. It will remain
invalid until all of the unsupported parameters are corrected.

88
 13 Triggering
13.6 Importing Previous Version Trigger Files

13

89
Wind River System Viewer
User's Guide, 3.2

90
 14
User Events (VxWorks Family)

14.1 Introduction 91
14.2 User Event Display 92
14.3 The User Events Description File 93
14.4 Validating XML Modifications 104
14.5 Advanced Techniques: Custom Parameter Formatting 106

14.1 Introduction
System Viewer can display user-defined events, generally referred to as User
Events. These are inserted into an event log as the thread of execution on a target
passes over the corresponding customer-inserted instrumentation points.

NOTE: User Events with large data payloads will result in copying large amounts
of data into the System Viewer log. This may impact performance of time-critical
code.

Depending on the version and variant of the VxWorks Target Operating System
(referred to as TOS in following) you use, details on how to add these
instrumentation points will vary as described in documentation for that VxWorks
version and variant. This chapter details how the presentation of these events is
controlled in the System Viewer Log Viewer on a VxWorks family TOS.

91
 Wind River System Viewer
User's Guide, 3.2

NOTE: User Events as used by the VxWorks family of operating systems are not to
be confused with Custom Events. Although the purpose and output are essentially
the same, input and internal handling differ.

14.2 User Event Display

All aspects of the definition of the structure of System Viewer events are
encapsulated in a set of XML files which are specific to each supported TOS. User
Events are no exception to this rule.
Changing the way in which User Events are displayed and decoded will involve
editing these XML files, a process which must be performed with the utmost care.
Injecting errors into an XML file will most likely render System Viewer
inoperative.

! CAUTION: Before changing any XML file shipped with System Viewer, you must
ensure that you create a backup copy of that file and put it in a safe place, outside
the Workbench installation tree. You can use these backup files to restore your
installation to its original, functioning state should the need arise.

There are two levels of customization which can be performed on the display of
User Events simply by editing the appropriate section of the supplied XML for
your chosen TOS:
1. change the displayed icon
2. change the displayed text
In addition, the way in which any encapsulated data is formatted for display may
be changed by writing custom formatters in Java and then making these formatters
available to System Viewer at runtime. This is, however, an advanced technique
which should be used only by experienced Java programmers, see 14.5 Advanced
Techniques: Custom Parameter Formatting, p.106. The default formatter provided in
System Viewer should be sufficient for most needs.

92
 14 User Events (VxWorks Family)
14.3 The User Events Description File

14.3 The User Events Description File

Firstly, you will need to know the name and version of the TOS you are running on
your target. In the example below, it is assumed you are using VxWorks 6.4.

14.3.1 Location of the User Events Description File

In your Workbench installation, locate the directory at

installDir/workbench-N.N/wrsv/N.N/host/resource/windview/
Below this directory there will be subdirectories for all installed TOS versions.
Locate the VxWorks variant and version which corresponds to your TOS or its
nearest historical predecessor.
For example, for VxWorks 6.4, the XML dictionary definitions may be found at
installDir/workbench-N.N/wrsv/N.N/host/resource/windview/VxWorks/6.0
Within that directory, the XML file which defines the structure and display
characteristics of User Events is called user.xml. It is this file which must be edited
(after keeping a backup of the original) in order to modify the way in which User 14
Events will be displayed.

14.3.2 Structure of the User Events Description File

The outline structure of a System Viewer XML file is fixed and that format must be
adhered to if the file is to be loaded correctly by the System Viewer runtime.

! CAUTION: All System Viewer XML files must conform to a strict structure, or they
will fail to parse correctly at runtime, and may render System Viewer inoperative.
Before editing any System Viewer XML file, be sure to put a backup copy of the
original file in a safe place (outside the Workbench installation tree) so that you can
restore it should the need arise.

The structure of the file is as follows:

XML Header
Doctype header
<EventDictionary> // start of top level document element
<EventClass> // start of EventClass element
<EventRangeDecription> // 0 or more EventRangeDescription elements
<EventDescription> // 0 or more EventDescription elements
</EventClass> // end of EventClass element
</EventDictionary> // end of top level document element

93
 Wind River System Viewer
User's Guide, 3.2

The formal structure of a System Viewer event dictionary XML file is defined in its
DTD (Document Type Description), which may be inspected at:
installDir/workbench-N.N/wrsv/N.N/host/resource/windview/DTDs/EventDictionary.dtd

! CAUTION: Do not edit the above file!

By default, User Events occupy a single block of contiguous Event IDs. The content
of user.xml for any TOS will reflect this in that all the corresponding XML
descriptions of these events are grouped into a single EventRangeDescription
element.
For example, here is the default user.xml file for VxWorks 6.0 (and higher) which
demonstrates the above XML file structure and shows a single
EventRangeDescription element which describes the entire User Event range:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE EventDictionary SYSTEM "../../DTDs/EventDictionary.dtd">
<EventDictionary>
<EventClass
key="user"
displayName="User Events"
helpTopicId="VXWORKS6_user_CLASS_HELP">
<EventRangeDescription
eventIdStart="40000"
eventIdCount="25536"
nameRoot="EVENT_USER"
displayNameRoot="user"
nameRootSuffixStart="0"
icon="images/defaultUser.gif"
trigger="true"
helpTopicId="VXWORKS6_EVENT_USER_EVENT_HELP"
handler="com.windriver.windview.plugins.wv.vxworks.UserEventDescription">
<EventParam
type="UINT32"
name="pc"
formatStr="0x%08x"/>
<EventParam
type="BLOB"
name="data"
formatter="com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter"/>
</EventRangeDescription>
</EventClass>
</EventDictionary>

! CAUTION: The EventRangeDescription element encapsulates information about

the entire event range and how it should be displayed, as well as describing the
structure of each event and its parameters. It is vital that the structure of the event
(and the EventParam child elements) remains intact, since they reflect the data
structure that will be created by the instrumentation embedded within the TOS.

94
 14 User Events (VxWorks Family)
14.3 The User Events Description File

! CAUTION: The original element defining the User Event range defines the entire
permitted range for User Events (40000-65535 in the example above). Do not, when
editing User Events, stray outside this range.

Description of EventRangeDescription Attributes

Within the EventRangeDescription, the meaning of each attribute is as follows:

eventIdStart
the starting EventID for the user event range
eventIdCount
the number of user events in the range. Note that in the example above,
eventIdStart = "40000" and eventIdCount = "25536", meaning that the range of
Event IDs covered is 40000 to 65535 inclusive.
nameRoot
can be any alphanumeric name, but without spaces.
displayNameRoot
used for display of the event 14
nameRootSuffixStart
can be set to any non-negative integer. It defines the User Event number that
will correspond to the first event in the range. Since, in the default example
above, eventIdStart = "40000", displayNameRoot = "user" and
nameRootSuffixStart = "0", the event with event ID = 40000 will be displayed
as user0; the event with event ID = 40001 will be displayed as user1, and so on.
icon
the path to the icon to be used for the event in the event graph, relative to the
user.xml file.

NOTE: If you design your own icon, please abide by the following guidelines:
„
Your icon should be no more than 16 pixels high.
„
Use a maximum of 256 colours.
„
Use a transparent background.
„
Remember that System Viewer can display your icon on either a black or a
white background. Ensure that your icon will show up against both.

95
Wind River System Viewer
User's Guide, 3.2

It is also possible to get System Viewer to generate a default, textual icon on

the fly, in which case no icons need to be designed and placed in your
installation. See Using Textual Icons, p.101.
trigger
"true" or "false" depending on whether System Viewer Triggering can trigger
on events in this range. Normally you would leave this at "true".
helpTopicId
used to link with the Workbench online help system. Can be omitted.
handler
this is the class name of a Java handler which will add functionality to the
graphical display of the events in this range. The default handler shown will
composite the user event number with the given icon. If this functionality is
not required, the handler attribute may be removed completely.
In the example above, for VxWorks 6.N, there follow two EventParam elements.
The number and type EventParam elements may vary for different VxWorks
versions or variants.
For any EventParam element:
type
do not change the original value!
name
may be changed to any display name you require
formatStr
this is a C-compatible printf format string which will be used to format the
integer value of the parameter. May be changed to any C printf format string
which is valid for an integer.
formatter
whilst this may be changed to name any Java class which implements the
required interface (and is available at runtime), this is an advanced technique
and is best left alone. The default formatter will print the value of any User
Event's payload as ASCII if it contains only ASCII, or as a combined
HEX/ASCII dump if the payload contains any non-ASCII characters.

96
 14 User Events (VxWorks Family)
14.3 The User Events Description File

14.3.3 Editing the User Event EventRangeDescription

If you want to change the display characteristics of all User Events, all you have to
to do is to change the attributes of their collective EventRangeDescription.
As described in the previous section, the attributes that may be changed in the
EventRangeDescription are:
„ nameRoot
„ nameRootSuffixStart
„ icon
„ trigger
„ handler
And, within the EventParam child elements:
„ name
„ formatter

14.3.4 Editing a Single User Event, or a Block of User Events

The first step in editing a User Event is to remove the required UserEvent ID (or 14
block of UserEvent IDs) from the EventRangeDescription. This is done by
splitting the range into two and leaving a "hole" to hold the extracted IDs.
For example, if we want to remove a block of 100 User Events from the range,
starting at EventID=40100, we would replace the original one
EventRangeDescription element with two EventRangeDescriptions, the first
covering the EventID Range 40000-40099 and the second covering the EventID
range 40200-65535. This leaves a hole in the defined Event IDs from 40100 to 40199
(i.e. 100 events).

97
Wind River System Viewer
User's Guide, 3.2

The XML to do this is shown below:

<!-- eventId range 40000-40099 inclusive -->
<EventRangeDescription
eventIdStart="40000"
eventIdCount="100"
nameRoot="EVENT_USER"
displayNameRoot="user"
nameRootSuffixStart="0"
icon="images/defaultUser.gif"
trigger="true"
helpTopicId="VXWORKS6_EVENT_USER_EVENT_HELP"
handler="com.windriver.windview.plugins.wv.vxworks.UserEventDescription">
<EventParam
type="UINT32"
name="pc"
formatStr="0x%08x"/>
<EventParam
type="BLOB"
name="data"
formatter="com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter"/>
</EventRangeDescription>

<!-- there is an event ID gap from 40100-40199 inclusive -->

<!-- eventId range 40200-65535 inclusive -->

<EventRangeDescription
eventIdStart="40200"
eventIdCount="25336"
nameRoot="EVENT_USER"
displayNameRoot="user"
nameRootSuffixStart="200"
icon="images/defaultUser.gif"
trigger="true"
helpTopicId="VXWORKS6_EVENT_USER_EVENT_HELP"
handler="com.windriver.windview.plugins.wv.vxworks.UserEventDescription">
<EventParam
type="UINT32"
name="pc"
formatStr="0x%08x"/>
<EventParam
type="BLOB"
name="data"
formatter="com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter"/>
</EventRangeDescription>

In the first block, the EventIdStart remains at 40000 as before, but only covers 100
events, as shown by the new eventIdCount. Display numbering in this range will
start from 0 as shown in the nameRootSuffixStart attribute. Thus, for an event
with event ID 40000, the displayed name will be user0.
In the second block, the EventIdStart now contains 40200 which is the starting
point of the block defined by this new range. The eventIdCount is 25336. The

98
 14 User Events (VxWorks Family)
14.3 The User Events Description File

defined range is therefore 40200-63335 (inclusive). The nameRootSuffixStart

attribute has been set to 200, meaning that this range will have a display number
starting at 200. Thus, for an event with event ID 40200, the displayed name will be
user200.
The hole (event IDs 40100-40199 inclusive) may be filled in by producing:
„
another EventRangeDescription to cover the entire range
„ 100 EventDescription elements to describe each event in the range
individually
„ any combination of EventRangeDescriptions and EventDescriptions to fill
the hole exactly

! CAUTION: If any EventDescription elements are used, they must appear after all
the EventRangeDescription elements in the XML file. Failure to observe this
restriction will result in the XML file failing to parse and load.

Inserting a New EventRangeDescription

14
To fill in the gap using a single EventRangeDescription, you could, for example,
append the following XML:
<!-- eventId range 40100-40199 inclusive -->
<EventRangeDescription
eventIdStart="40100"
eventIdCount="100"
nameRoot="EVENT_USER"
displayNameRoot="myUserEvent"
nameRootSuffixStart="0"
icon="images/myUserIcon.gif"
trigger="true"
handler="com.windriver.windview.plugins.wv.vxworks.UserEventDescription">
<EventParam
type="UINT32"
name="pc"
formatStr="0x%08x"/>
<EventParam
type="BLOB"
name="data"
formatter="com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter"/>
</EventRangeDescription>

This would fill the hole exactly, from Event IDs 40100-40199. The display of the first
event in this range would be myUserEvent0 since we have changed the
displayNameRoot and the nameRootSuffixStart. Also, the icon for the events
would change to that provided in images/myUserIcon.gif, but still suitably

99
 Wind River System Viewer
User's Guide, 3.2

decorated with the user event number, because we are still using the default value
in the handler attribute. The helpTopicId attribute has been removed since there
will be no corresponding entry in the Workbench documentation for this new
range of event descriptions.

Inserting New EventDescriptions

Gaps in the [re]defined event range may also be filled using discrete
EventDescription elements. Each of these covers just one event ID and offers the
greatest scope for customization of individual events.
As an example, we could fill in the very first event ID in the gap created above with
the following fragment of XML which defines the event for ID 40100:
<!-- This discrete EventDescription is provided for Event ID # 40100 which
has the data structure of a User Event.
The number, order and type of each of the parameters
must be EXACTLY as shown (i.e. EXACTLY as for all other user events),
since this format is dictated by the VxWorks runtime.
Here, the "icon" attribute in the EventDescription has been
modified to point to a user-defined icon for this event.
-->
<EventDescription id="40100"
name="MY_USER_EVENT_0"
trigger="true"
displayName="My User Event #0"
icon="images/myUserEvent0Icon.gif">
<EventParam
type="UINT32"
name="pc"
formatStr="0x%08x"/>
<EventParam
type="BLOB"
name="data"
formatter="com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter"/>
</EventDescription>

Here, event ID 40100 has been defined so that it will display as My User Event #0
and have the custom-supplied icon images/myUserEvent0Icon.gif located relative
to the user.xml file. Nothing else has changed.
The remaining bits of the hole created in the user event ID range may be filled with
any combination of EventRangeDescription and EventDescription elements.

NOTE: It is not necessary to fill in the entire range; holes may be left. However, if
a hole is left, you must be sure that your TOS runtime will not emit any events
which correspond to the omitted event IDs, or your log will fail to parse
completely due to missing event descriptions.

100
 14 User Events (VxWorks Family)
14.3 The User Events Description File

Using Textual Icons

In System Viewer 4.9 and higher, it is possible to use a different form of the icon
attribute of the EventDescription element to have an icon, optionally coloured,
complete with text, inserted on the fly, without having to manually design images
and save them in your installation. This is a real time-saver.
As seen before, the default form of an EventDescription's icon attribute is
icon="images/myIcon.gif", where the value of the icon attribute is simply the path
to an image file relative to the containing XML file.

NOTE: Path separators in the icon attribute must be a forward slash, regardless of
which host operating system you are using; that is, including Windows.

The Extended Form of the icon Attribute

The extended form of the icon attribute allows for quick creation of new
EventDescriptions, removing the need for manually creating image files.
If you want to use the extended form of the icon attribute, you should not use your
own handler attribute. Rather, you should not insert any handler attribute at all.
This is because the extended functionality is provided by the default Event 14
Description handler.

Syntax

The extended form of the icon attribute has a formal syntax as follows:
icon="specifier [,specifier]*"
specifier: text=TEXT | textPosition=TEXTPOSITION | color=#RRGGBB |
icon=ICON_PATH
where:
TEXT
is the text to be composited into the icon (must not contain an equals or
comma character). If the text specifier is omitted, no text will be
composited on to the icon. You can also you can also set the text of the
event to be the event id by using $id notation.
TEXTPOSITION
is the position of the text in relation to the icon. The possible values are:
[north|south|east|west|southeast|southwest|northeast|northwest]

101
 Wind River System Viewer
User's Guide, 3.2

RRGGBB
is the hex Red, Green, and Blue values of the desired color of an
auto-generated icon and any composited text. The format is per HTML
color definitions, with each color component being between 00 and FF Hex.
If the color specifier is omitted, the default color will be used (#00C0C0, a
dark cyan).
ICON_PATH
is the path of a desired icon for compositing, relative to the containing
XML file. If the icon specifier is omitted, a default icon will be generated
on the fly.
The table below summarizes what happens depending on the combination of
specified icon attribute specifiers.

Table 14-1 Combinations of icon Attribute Specifiers

text= color= icon= Meaning

No No No No icon, no text

Yes No No Text and default icon, both in default color

No Yes No No text, default icon in specified color

Yes Yes No Text and default icon, both in specified color

No No Yes Specified icon only

Yes No Yes Text in default color, specified icon

No Yes Yes Specified icon only

Yes Yes Yes Text in specified color, specified icon

Examples

1. icon="text=myUserEvent"
Simply creates an icon with the default shape (a small downward facing
triangle), with the given text composited above, both in the default color (dark
cyan).
2. icon="color=#FF0000"
Creates an icon with the default shape in bright red, with no text.
3. icon="text=myUserEvent,color=#00FF00"

102
 14 User Events (VxWorks Family)
14.3 The User Events Description File

Creates an icon with the default shape with text "myUserEvent" composited
above, both in bright green.
4. icon="icon=images/myIcon.gif"
Uses the supplied icon, with no text. This is equivalent to the non-extended
form of the icon attribute: icon="images/myIcon.gif"
5. icon="text=myUserEvent,icon=images/myIcon.gif"
Composites the given icon and the given text, with the text in the default color
(dark cyan). The icon will be rendered exactly as in the supplied image file.
6. icon="text=myUserEvent,color=#0000FF,icon=images/myIcon.gif"
Composites the given icon and the given text, with the text in the given color
(bright blue). The icon will be rendered exactly as in the supplied image file.
7. icon="text=$id,color=#FF0000,textPosition=southeast,icon=images/myIcon.gif"
Composites the given icon and the event text, with the text in the given color
(red) positioned southeast of the icon.
So, to redesign our new EventDescription for our User Event with event ID 40100
(as shown above), but using the extended form of the icon attribute, our new
14
EventDescription element could be as follows:
<EventDescription id="40100"
name="MY_TRACE_EVENT_0"
trigger="true"
displayName="Trace#0"
icon="text=Trace0">
<EventParam
type="UINT32"
name="pc"
formatStr="0x%08x"/>
<EventParam
type="BLOB"
name="data"
formatter="com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter"/>
</EventDescription>

By doing this, instances of the event with event ID 40100 would be shown as
Trace#0 as the displayed event name, and have an icon which looks like a small,
downward pointing, dark cyan triangle with the text Trace0 above it, also in dark
cyan.

103
 Wind River System Viewer
User's Guide, 3.2

14.3.5 Example of a Complete VxWorks 6.N user.xml File

An example of a complete new user.xml file, written specifically for VxWorks 6.N,
is provided as an appendix (see E. VxWorks6.N user.xml Example File). The example
demonstrates many of the techniques described in this section.
If your TOS is not VxWorks 6.N, you should use the default user.xml file (see
14.3.1 Location of the User Events Description File, p.93) for your TOS as a prototype,
and be sure not to alter the range of user event IDs permitted for that TOS.

14.4 Validating XML Modifications

All System Viewer installations come complete with a command line utility that
checks the dictionary XML files for consistency and correctness.
It should be run from a shell in which the correct environment has been set up.

Step 1: Set up the environment

1. Open a shell (or Windows Command Prompt).
2. Change directory to the root of your Wind River Workbench installation.
3. At the prompt, type:
wrenv -p workbench-N.N
where N.N is the version of Wind River Workbench you have installed.
You are now ready to run the wrsv-xmldictcc utility to validate your XML.

Step 2: Validate your XML files

The syntax of the command for validating your XML files is:
wrsv-xmldictcc [-v] [-c] path-to-XML-directory
where
-v = verbose
prints OK after the file name of each XML file tested
-c = check images
also tests for the presence of referenced image files

104
 14 User Events (VxWorks Family)
14.4 Validating XML Modifications

The wrsv-xmldictcc utility is located in the directory

installDir/workbench-N.N/wrsv/N.N/host/HostType/bin
where HostType is one of:
„
sun4-solaris2 for Solaris hosts
„
x86-linux2 for Linux hosts
„
x86-win32 for Windows hosts

Examples

These examples illustrate how you would use the xmldictcc command line utility
on different hosts and with given Workbench, System Viewer, and TOS versions.

Example 14-1 Solaris host, Workbench 2.6, System Viewer 4.9

Workbench installation directory:

/user/fred/wb
XML directory to validate:
/user/fred/wb/workbench-2.6/wrsv/4.9/host/resource/windview/VxWorks/6.0

The required command is (all in one line): 14

/user/fred/wb/workbench-2.6/wrsv/4.9/host/sun4-solaris2/bin/wrsv-xmldictcc -v
-c /user/fred/wb/workbench-2.6/wrsv/4.9/host/resource/windview/VxWorks/6.0

Example 14-2 Windows host, Workbench 2.6, System Viewer 4.9

Workbench installation directory:

C:\wb
XML directory to validate:
C:\wb\workbench-2.6\wrsv\4.9\host\resource\windview\VxWorks\6.0

The required command is (all in one line):

C:\wb\workbench-2.6\wrsv\4.9\host\x86-win32\bin\wrsv-xmldictcc.exe -v -c
C:\wb\workbench-2.6\wrsv\4.9\host\resource\windview\VxWorks\6.0

105
 Wind River System Viewer
User's Guide, 3.2

14.5 Advanced Techniques: Custom Parameter Formatting

! CAUTION: Custom formatting of parameters is an advanced technique which

requires knowledge of Java programming and access to a Java 1.4 SDK.

User Events contain a BLOB parameter which can contain a binary payload in the
event generated by the TOS instrumentation. The Java formatter used in the
default user.xml is:
com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter
which will display the content of the BLOB payload as ASCII if the content consists
entirely of ASCII characters, or as a mixed HEX/ASCII decode if there are any
non-ASCII characters in the payload. However, in your own TOS runtime code, it
is possible to construct a binary payload for your User Event which contains a
predefined data structure.
For example, your runtime code may define the following data structure
struct
{
unsigned int field1;
unsigned int field2;
unsigned int field3;
} myUserEventPayload;

and have this included as the BLOB payload for your User Event.
It is then possible to write a custom EventParameterFormatter implementation in
Java which understands and appropriately formats the data structure of this
payload, rather than using the standard Hex/ASCII formatter.
For full details on how to write a custom Event Parameter Formatter, please see the
online Wind River System Viewer API documentation provided for the
com.windriver.windview.agnostic.wv.eventlog.EventParameterFormatter
interface. The easiest way to find the relevant documentation is to open the
Wind River Workbench online help and search for:
“eventlog.EventParameterFormatter”

106
 14 User Events (VxWorks Family)
14.5 Advanced Techniques: Custom Parameter Formatting

! CAUTION: As part of this process, you will need to compile your new Java class
and put it into a Jar file. This must be done with a Java SDK which produces code
that is compatible with Java 1.4. Extensions to the Java language introduced in Java
1.5 (or later) must not be used.
Your Java compilation command line must include the wv.jar Jar file in the
compilation classpath. The wv.jar file is located in
installDir/workbench-N.N/wrsv/N.N/host/java/lib/

14

107
Wind River System Viewer
User's Guide, 3.2

108
 15
System Viewer for
Wind River Linux

15.1 Configuring Wind River Linux for System Viewer 109

15.2 Using System Viewer Configuration in Workbench 110
15.3 Customizing the Appearance and Classification of Events 116
15.4 Custom Events for Wind River Linux 3.0 118
15.5 Custom Events for Wind River Linux 2.x 120

15.1 Configuring Wind River Linux for System Viewer

System Viewer for Wind River Linux leverages the LTTng project. The Wind River
Linux distribution includes the LTTng patches.
To ensure proper System Viewer support in the kernel/filesystem, you must first
do the following
1. Add the ltt-control package to your filesystem.
2. Add LTT to your kernel.

109
 Wind River System Viewer
User's Guide, 3.2

NOTE: If you are using Wind River Linux 2.0, add the ltt-control package to your
filesystem. If you are using Wind River Linux 3.0, add wrsv-ltt package to your
filesystem. You must rebuild your kernel afterwards.
The LTT kernel component can be found using the Workbench kernel configurator.
A filesystem rebuild is required afterwards.
For more information, see Wind River Workbench By Example (Linux 3 Version), 3.1:
Configuring Platform Kernels.

Apart from that, System Viewer configuration for Linux is, on the whole, the same
as for VxWorks. Configuration features are fully supported and generic tasks work
the same way as on VxWorks. See 3. Configuring a Logging Session and following
chapters for general information in this respect.

15.2 Using System Viewer Configuration in Workbench

The System Viewer Configuration editor’s Configuration tab is used to create
commands that are executed on the target to start and stop tracing.
To create the command-line parameters, configuration is subdivided into separate
categories, each of which provide a known parameter as described below.

15.2.1 Configuration Summary

The Configuration Summary provides a full overview of the current configuration

of the System Viewer (not the configuration of your target system), as well as a
copy of the command-line sequence, which you can copy for direct use on the
target shell.

15.2.2 Instrumentation Configuration

This configuration option determines whether the modules and markers that
provide instrumentation for the log collection are armed and disarmed before and
after log collection. Selecting this option ensures that modules and markers are
always armed before logging is started, and disarmed before logging is stopped.

110
 15 System Viewer for Wind River Linux
15.2 Using System Viewer Configuration in Workbench

Enabling this option does have an impact on the time it takes to start logging. This
is because an additional process, which performs the arming of markers and
modules, is executed on the target prior to log collection. This additional process
appears in the summary panel, in the list of commands to be executed.

NOTE: Wind River recommends you select this option. While disabling it
improves log collection startup time, there is a risk that if logging is started before
modules and markers are armed, the collected log will be empty. If logging startup
time is important, see Arming and Disarming Modules and Markers on a Target Shell,
p.111, for information on setting up instrumentation directly on the target.

In addition to this option in Workbench, you can also do the following with the
wrsv-lttconfig program:
„ Arm and disarm modules and markers on the target shell.
„ Add new modules or markers.
„ Remove modules or markers.
„ List the modules and markers to be armed.

Arming and Disarming Modules and Markers on a Target Shell

15

Modules and markers can be armed and disarmed directly on the target with the
wrsv-lttconfig command. To arm, use the command with the -a parameter; to
disarm, use the -d parameter.

Adding a New Marker

The wrsv-lttconfig program parses a configuration file, located at

/etc/wrsv-lttconfig.conf, that specifies the modules and markers to be armed or
disarmed. In the wrsv-lttconfig.conf file, the lists of modules and markers are
enclosed in square brackets ([ ]). To disable a particular module or marker,
comment out its line with a # character. To re-enable it, remove the comment
character.
To add a new marker, do the following:
1. Disarm all current modules and markers. This is done automatically if the
instrumentation option described in 15.2.2 Instrumentation Configuration,
p.110, is selected. If not, enter the following command:

111
 Wind River System Viewer
User's Guide, 3.2

wrsv-lttconfig -d

2. Edit the wrsv-lttconfig.conf file to add the module in which the marker is
contained. For example:
[custom-trace]

3. Add your new marker. For example:

custom_marker1 default dynamic

4. Save the file.

5. If it is not done automatically, re-arm the modules and markers:
wrsv-lttconfig -a

Removing a Module or Marker

To remove a module or marker, do the following:

1. Disarm all current modules and markers. This is done automatically if the
instrumentation option described in 15.2.2 Instrumentation Configuration,
p.110, is selected. If not, enter the following command:
wrsv-lttconfig -d

2. Edit the wrsv-lttconfig.conf file (described in Adding a New Marker, p.111).

Remove the marker by commenting it out. For example:
#custom_marker1 default dynamic

3. If the module containing the marker has no other markers enabled, you can
safely comment out the module. For example:
#[custom-trace]

NOTE: Do not delete any module or marker information from the

configuration file. Instead, only comment out unnecessary lines. This will
enable you to restore the initial state of the configuration file without having
to remember the names of the modules and markers.

4. Save the file.

5. If it is not done automatically, re-arm the modules and markers:
wrsv-lttconfig -a

112
 15 System Viewer for Wind River Linux
15.2 Using System Viewer Configuration in Workbench

Listing Armed Modules and Markers

To list all armed modules and markers, enter the following command:
wrsv-lttconfig -l

15.2.3 Recording Mode Options

There are three recording options available.

„ In normal mode, all information is retained for the duration of logging.
„ Events collected in flight mode are stored in buffers located in target memory.
The trace data remains in the buffers and is not transferred to a file until
requested. The buffers are re-used when full; as a result only the most recent
events will be in the log.
This mode is particularly useful for debugging a target process. If a process
ends unexpectedly for any reason, you can upload the Flight recorder log to
see the sequence of events leading up to the failure.
„ In hybrid mode all critical, low rate information (such as process create/exit),
is recorded for the duration of logging; high rate information (system call
events, interrupt events, and so on) are stored in a flight recorder buffer. 15

15.2.4 Target File System Options

The output directory for storing LTTng target trace files, and the system used when
creating new trace files.
Specify a new name for each trace collected
After every log collection you have to enter a new directory name. The
directory name must not exist on the target. The trace files will remain on the
target until deleted manually.
Add incrementing suffix to target trace name
A unique, sequential number is suffixed to the directory name each time a log
is collected. The trace files will remain on the target until deleted manually.
Overwrite target trace files when collecting a new log
The output directory is re-used, and existing trace files in the directory are
overwritten every time a log is collected.

113
 Wind River System Viewer
User's Guide, 3.2

Append to existing trace

Collected data is appended to the end of the specified trace files. If the trace
files do not exist, new ones will be created.

15.2.5 Buffer Configuration

The number and size of sub-buffers in the target memory used during tracing. If
this option is not selected, default values are used.

NOTE: Choosing 2 buffers of a small size is likely to lead to lost events. To check
for lost event run dmesg(1) on the target. To reduce the risk of losing events either
increase the number of buffers, increase the size of the buffer, or both.

15.2.6 Output Filename

These settings determine the host directory and filename under which to save the
collected event log. The LTTng daemon collects and saves trace files in the
directory you specified in the 15.2.4 Target File System Options, p.113. These files are
then copied from the target to the host.
The trace files are copied from the target and saved in a subdirectory, named in the
Output Filename field, of the directory specified in the Directory field. These files
are then converted to single file, in a format that is understood by the
System Viewer, and saved to the filename you specified in the Output Filename
field. If conversion fails, the LTTng files are left in the specified directory.
The following options are available in Output Filename:
Automatically download log when logging stops
After log collection stops, copy the LTTng files from the target to the host and
convert to a Wind River System Viewer raw file (.wvr).
Automatically view downloaded log
Once the successful download and conversion is complete, automatically open
the log in the Log Viewer.
Add an incrementing suffix to the filename in preference to
a time and date stamp
Append an incrementing index to the filename, instead of a time-and-date
stamp. If this option is not selected, the time and date of the transfer of the log
from the target are appended to the filename. Using this option prevents
existing logs from being overwritten.

114
 15 System Viewer for Wind River Linux
15.2 Using System Viewer Configuration in Workbench

Add target connection name to filename

Append the target connection name to the host filename. This helps to
distinguish logs that have been collected on different targets. When this option
is selected, however, host filenames are much longer.

15.2.7 Log Conversion Options

Save the LTTng trace files after conversion to System Viewer format (.wvr). The
default is to delete trace files after conversion.

15.2.8 Module Manager

The information in this section is specific to System Viewer for Wind River
Linux 2.x.
You can selectively include or exclude instrumentation types logged by
System Viewer. These instrumentation types, called probes, can either be built into
the kernel, or included as modules which are loadable at run time.
The target Module Manager, which appears as a tab in the
System Viewer Configuration utility, lets you configure which instrumentation
15
modules to include or exclude for log collection.
The Module Manager tab presents a list of the probe modules the target supports.
Select the probes you want to collect information about during logging, and click
the Update Modules button.
If you suspect that the Module Configuration list might be out of synch with the
modules currently loaded on the target, click the Refresh from target button to
reread the target data and update the list.

NOTE: If there are no probe modules on the target, the module list will be empty
and it will be assumed that all instrumentation is built into the kernel. If there are
modules available and none are loaded, a warning will be given. This warning will
appear even if only some modules are built into the kernel.

115
 Wind River System Viewer
User's Guide, 3.2

15.3 Customizing the Appearance and Classification of Events

You can customize some aspects of the look and feel of System Viewer events. The
color, icon image, name, and event class of an event can be manipulated to give
events a desired look, or to place them in custom event classes. This capability is
particularly important when you use custom events, as described in 15.5 Custom
Events for Wind River Linux 2.x, p.120.

15.3.1 Customizing the Visual Appearance of an Event

To change the visual presentation of an event, edit the event-icons.txt file. It is

located at:
installDir/workbench-3.1/wrsysviewer/host/resource/windview/wrlinux/3.0

Adding an Event or Customizing Its Appearance

In the event-icons.txt file, the event description has the following format:
event_name text=identifyingText,color=#hexRgbValue,icon=pathToImagesDir/imageFilename

event_name
The name of the event that is contained in the trace files.
text
Optional text to be used alongside an image.
color
An optional color specification, given as a hexadecimal RGB value.
icon
An optional pointer to an image to be used with the event. The path to the
image file is relative to the directory in which the event-icons.txt file is located.
For example, to add a new event named custom1 that uses the identifying text
“my_event1,” the color blue, and the default icon, add the following line to the
event-icons.txt file:
custom1 text=my_event,color=#0000ff

To add a new event named custom2 that has no text (and therefore does not require
a specified color) and uses the default icon, add the following line to the
event-icons.txt file:
custom2 icon=images/customImage.gif

116
 15 System Viewer for Wind River Linux
15.3 Customizing the Appearance and Classification of Events

If the event-icons.txt file does not have an entry for a particular event, a default set
of parameters is used. By default, the event name is used for the text parameter,
color is set to white, and a default icon is used.

NOTE: Any customization of event appearance affects only those System Viewer
logs that are captured in LTTng format and converted to Wind River’s raw format
(.wvr). If you customize the appearance of events, these customizations will not
affect logs that have already been converted to .wvr format.

15.3.2 Customizing an Event’s Classification

All events must be categorized under an event class. You can customize the event
class to which an event belongs.
To change an event’s event class, or to add new event classes, edit the
event-classes.txt file, located at:
installDir/workbench-3.1/wrsysviewer/host/resource/windview/wrlinux/3.0
In the event-classes.txt file, event classes are defined within square brackets ([ ]);
the events that belong to a class follow the event class definition.
15
Adding a New Event Class and Assigning Events to It

To create a new event class, do the following:

1. Open the event-classes.txt file.
2. Add the new event class:
[My Custom Events]

3. Add the events that should belong to this new event class. For this example,
we will use the custom events created in Adding an Event or Customizing Its
Appearance, p.116:
custom1
custom2

4. Save the event-classes.txt file.

In the System Viewer Log Viewer, the custom events now appear in both the
Legend view and Search or Filter dialogs, under the event class
My Custom Events.

117
 Wind River System Viewer
User's Guide, 3.2

NOTE: Any customization of event classes affects only those System Viewer logs
that are captured in LTTng format and converted to Wind River’s raw format
(.wvr). If you customize the classification of events, these customizations will not
affect logs that have already been converted to .wvr format

15.4 Custom Events for Wind River Linux 3.0

Linux kernel markers are the mechanism used to emit events into the LTT trace.
You can create custom markers and then view the resulting events in the
System Viewer.

Sample Marker File

An example of the use of kernel markers is provided in the kernel source at

samples/markers/marker-example.c. This example can be built by configuring the
kernel with the SAMPLE_MARKERS component included. For more information
on markers, see Documentation/markers.txt in the kernel source tree.

Enabling Custom Markers

Once you have created a custom marker, there are two ways to enable it for use
with the System Viewer. With the first method, you enter commands on the target
shell to load the module, arm the markers, and then write the resulting events to
the trace. With the second method, you add the module and markers to the
System Viewer target configuration file; the System Viewer itself then performs the
arming of the instrumentation.

Method 1: On the Target Shell

1. Load the example module manually, on the target console:

insmod /lib/modules/2.6.27.13-
WR3.0ZZ_standard/kernel/samples/markers/marker-example.ko

The markers are now available, but are not yet armed.

118
 15 System Viewer for Wind River Linux
15.4 Custom Events for Wind River Linux 3.0

2. To arm the markers, enter the commands below. In this example, the markers
are named subsystem_event and subsystem_eventb.
echo "connect subsystem_event default" > /proc/ltt
echo "connect subsystem_eventb default" > /proc/ltt

3. Once tracing has started, you can enter the following command to write the
example events to the trace:
cat /proc/marker-example

When you have entered this command, you can then view the resulting events
in the System Viewer on the host. The cat command is simply a means to cause
the example marker points to be hit. When you use markers to debug a real
problem, the cat command is not necessary.

Method 2: In the Configuration File

1. Before you can edit the System Viewer target configuration file, you must
know the names of the module and the markers included in the module. In the
example file marker-example.c, the module is named marker-example and the
markers are subsystem_event and subsystem_eventb.
2. The System Viewer target configuration file is located at
/etc/wrsv-lttconfig.conf. Edit this file by adding the module and marker
names to the list to be loaded. For this example, add the following lines to the 15
configuration file:
[marker-example]
subsystem_event default dynamic
subsystem_eventb default dynamic

Note that the module name is enclosed in square brackets ([ ]), while the
marker names are not. You can add your new lines anywhere in the
wrsv-lttconfig.conf file; placement is not significant. However, you may find
it convenient to put your added lines together, and to preserve the original
structure of the configuration file, so that you can easily find these lines later.
3. Save the wrsv-lttconfig.conf file.
If the instrumentation option described in 15.2.2 Instrumentation Configuration,
p.110, is selected, the new markers are automatically armed when you start
tracing from Workbench.
4. Once tracing has started, you can enter the following command to write the
example events to the trace:
cat /proc/marker-example

119
 Wind River System Viewer
User's Guide, 3.2

When you have entered this command, you can then view the resulting events
in the System Viewer on the host. The cat command is simply a means to cause
the example marker points to be hit. When you use markers to debug a real
problem, the cat command is not necessary.

15.5 Custom Events for Wind River Linux 2.x

LTTng can record custom user-defined events that can be displayed in
System Viewer. These are generally referred to as Custom Events. Custom events
are implemented using LTTng markers and probes.

NOTE: Wind River Linux Custom Events are not to be confused with User Events as
used by the VxWorks family of operating systems. Although the purpose and
output are essentially the same, input and internal handling differ.

For more information on LTTng probes and markers see:

kernel-source-dir/Documentation/marker.txt
The above document introduces markers and discusses their purpose. It shows
some usage examples of the Linux Kernel Markers: how to insert markers within
the kernel, and how to connect probes to a marker.
Custom events are provided through a probe called ltt-probe-kernel-generic: this
module is already part of the kernel and no patching is required. The source to this
module is in kernel-source-dir/ltt/probes/ltt-probe-kernel-generic.c
This LTTng probe defines a number of custom events. Each event takes a
printf-like format string for recording the event-data. The following variations are
provided. Choose one (or more) that best suits the information you want to record.
kernel_generic_string %s
kernel_generic_file_line_msg %s %d %s
kernel_generic_int %d
kernel_generic_int64 %lld
kernel_generic_uint %u
kernel_generic_uint64 %llu
kernel_generic_pointer %p
kernel_generic_size_t %zd
kernel_generic_int_x4 %d %d %d %d

120
 15 System Viewer for Wind River Linux
15.5 Custom Events for Wind River Linux 2.x

kernel_generic_int64_x4 %lld %lld %lld %lld

kernel_generic_string_int_x4 %s %d %d %d %d
kernel_generic_string_int64 _4%s %lld %lld %lld %lld
Your functions should make calls to the logging events using the MARK macro.
The macro will then write the supplied event data into the LTTng trace.

Example 15-1 Using the MARK macro

/* record a string */
MARK(kernel_generic_string, "%s", "example string");

/* record an integer */
MARK(kernel_generic_int, "%d", INT_MIN);

/* record a 64-bit value */

MARK(kernel_generic_int64, "%lld", LLONG_MAX);

/* record a pointer value */

MARK(kernel_generic_pointer, "%p", &foo);

/* record the size of some type */

MARK(kernel_generic_size_t, "%zd", sizeof (1LL));

/* record 4 integer values */

MARK(kernel_generic_int_x4, "%d %d %d %d", 1, 2, 3, 4);

/* record a string, followed by 4 integer values. */ 15

MARK(kernel_generic_string_int_x4, "%s %d %d %d %d","my event: ",1,2,3,4);

Once your kernel function has been instrumented, rebuilt, and loaded (using
modprobe) you can collect event data by configuring System Viewer in the normal
way. You should ensure that the ltt-probe-kernel-generic module is selected when
using the graphical user interface. If the probe is not activated then no event data
will be collected; loading the ltt-probe-kernel-generic module from either the user
interface or using modprobe activates custom events.

NOTE: The code or kernel module containing your MARK macros must be loaded
before the ltt-probe-kernel-generic module. If the ltt-probe-kernel-generic
module is either already loaded, or loaded before your module, then you need to
reload the probe using:
1.rmmod ltt-probe-kernel-generic
2.modprobe ltt-probe-kernel-generic

121
 Wind River System Viewer
User's Guide, 3.2

15.5.1 General Steps for Using Custom Events

The general steps for using custom events are:

1. Add MARK macro to your code
2. Compile and load your code into the kernel.
This assumes your code is a module. If it is built into the kernel then you will
need to reboot.
3. Start data collection using the user interface. Remember to enable the
ltt-probe-kernel-generic module.
4. Stop data collection and view in System Viewer.

15.5.2 Marker Example Module

An example kernel module (marker-example) is also supplied; this module is built

if LTTng is enabled. This marker-example module provides an example of using
each of the custom events. The marker-example source can be found in:
kernel-source-dir/ltt/marker-example.c
To use and activate this module you need to execute the following:
1. Enter modprobe marker-example
2. Enter modprobe ltt-probe-kernel-generic
3. Start log collection.
4. Enter cat /proc/marker-example
This executes a function in the marker-example module that exercises all of
the available custom events.
5. Stop log collection.
You can now use System Viewer to view the events recorded by the
marker-example module.

122
 A
VxWorks: Deployment

A.1 VxWorks Image Projects 123

A.2 Preparing for Deployment 124

A.1 VxWorks Image Projects

This chapter focuses on VxWorks; for information relating to Wind River Linux,
see 15. System Viewer for Wind River Linux.

A.1.1 Kernel Configuration

When you create a VxWorks Image Project in Wind River Workbench, all
components that System Viewer needs are included in the kernel by default. For
reference purposes, or in case the configuration has been modified, all kernel
components required by System Viewer are listed under D. Configuring VxWorks
for System Viewer.

123
 Wind River System Viewer
User's Guide, 3.2

A.2 Preparing for Deployment

In order to be able to capture and log run-time events, System Viewer
instrumentation points are coded into various kernel libraries.
System Viewer instrumentation is included by default in several VxWorks libraries
(such as semBLib) that are provided by several components (such as
INCLUDE_SEM_BINARY). The code that provides this feature therefore effectively
spans several libraries and components. If System Viewer is not going to be used
(as is the case in most deployed systems), a VxWorks Source Build (VSB) project
can be used to eliminate System Viewer instrumentation from all VxWorks
libraries in the system. For more information, see VxWorks Programmer’s Guide:
Kernel Facilities and Kernel Configuration.

124
 B
Programming Data Collection

B.1 Introduction 125

B.2 Instrumenting Objects Programmatically 126
B.3 Adding Eventpoints 134
B.4 Timestamping 136
B.5 Dynamic Buffer Allocation 138

B.1 Introduction
A critical aspect of data collection is managing and controlling the volume of
information you generate in a log as System Viewer allows you to collect a great
deal of information.
At the same time, instrumentation classes allow you to limit data collection either
by limiting the detail you collect, or by limiting detailed data collection to specific
objects. Multiprocessor support and the high-resolution timestamp drivers
contribute to the volume of detailed information that must be stored and
uploaded. The dynamic ring buffer provides a flexible method of balancing the
need to hold large amounts of data for upload to the host and the need to leave the
target applications enough resources to work normally.

125
 Wind River System Viewer
User's Guide, 3.2

The routines in wvLib and wvNetDLib provide a much finer level of control over
how events are logged than the GUI tools or the basic wvOn( ) and wvOff( )
routines described in 7. Logging and Uploading Data.
Detailed information about the routines and examples of their usage are available
in the VxWorks OS Libraries API Reference; you can also examine the source code in
installDir/vxworks-N.N/target/config/comps/src/usrWindview.c. These routines
are more complex to use than wvOn( ) and wvOff( ), and the order in which they
are invoked is critical.

B.2 Instrumenting Objects Programmatically

Instrumentation of events is implemented in System Viewer by classes, which are
designated by the logging levels discussed in 4. The Event Logging Level. When you
select AIL level logging in the Event Logging Level Configuration pane, the
libraries taskLib, semLib, msgQLib, and wdLib are selected by default in the
Additional Instrumentation Library Selection checklist. You can modify the
amount of data collected by selecting all libraries, only one library, or any
combination of the listed libraries.

B.2.1 Kernel Libraries

When you select a library in the GUI by checking the library name in the
Event Logging Level Configuration pane, all objects in that library are
instrumented. When you start data collection, events are logged for these objects.
You might be interested in how specific tasks, semaphores, message queues, and
so on interact so target routines are available to instrument individual objects. This
allows you greater precision in collecting only the data you are interested in seeing.
Table B-1 lists the Wind River System Viewer target routines that you can call to
control the instrumentation of particular objects.

Table B-1 System Viewer Instrumentation Routines

Routine Description

wvObjInst( ) instrument objects

126
 B Programming Data Collection
B.2 Instrumenting Objects Programmatically

Table B-1 System Viewer Instrumentation Routines(Continued)

Routine Description

wvSigInst( ) instrument signals

wvObjInstModeSet( ) set object instrumentation level

wvEvtClassSet( ) set the class of events to log

wvEventInst( ) instrument VxWorks events

wvNetEnable( ) begin reporting network events

wvNetEventEnable( ) instrument specific network events

To instrument individual objects and groups of objects programmatically, call

wvObjInst( ) instead of selecting the library in the
Additional Instrumentation Library Selection checklist. Events that affect these
objects are logged if and when AIL level logging begins.
The wvObjInst( ) routine is declared as follows:
STATUS wvObjInst
(
int objType /* object type: windSemClass, windMsgQClass, */
void * objId /* object ID: specific ID or NULL for all */
/* objects of objType */ A
int mode /* turn instrumentation on/off:
/* INSTRUMENT_ON, INSTRUMENT_OFF */
)

127
Wind River System Viewer
User's Guide, 3.2

The wvObjInst( ) routine sets up instrumentation for objects of the specified type
whether or not they already exist on the target system. To instrument only those
objects that are created after a certain point, use the wvObjInstModeSet( ) routine.
You can instrument specific objects in taskLib, semLib, msgQLib, and wdLib. You
cannot specify particular signals to instrument within sigLib, either all signals are
instrumented, or none are.
To instrument signals programmatically, call wvSigInst( ) instead of selecting the
library in the Additional Instrumentation Library Selection checklist. Either
method results in all signals being instrumented.
The wvSigInst( ) routine is declared as follows:
STATUS wvSigInst
(
int mode /* turn instrumentation on/off:
/* INSTRUMENT_ON, INSTRUMENT_OFF */
)

To instrument VxWorks events programmatically, call wvEventInst( ) instead of

selecting the library in the dialog box checklist. Either method results in all signals
being instrumented.
The wvEventInst( ) routine is declared as follows:
STATUS wvEventInst
(
int mode /* turn instrumentation on/off:
/* INSTRUMENT_ON, INSTRUMENT_OFF */
)

You can start event collection using the GUI, or you can start it programmatically.
The following example code shows how to create a log file on the host, enable
instrumentation of all possible classes, collect VxWorks events, signals, and
network instrumentation data, and start and stop logging.
/**********************************************************************
* wvLogFileUploadStart - create a logfile on the host, and start logging
*
* This routine uses various System Viewer functions to create a log on a
* host, to select the required instrumentation, and to start log
* collection. It is invoked with a logging level, and the name of the
* file to use on the host.
*
* e.g. wvLogFileUploadStart 7, "/tgtsvr/logfile.wvr"
*
* RETURNS: OK, or ERROR
*
* SEE ALSO: wvLogStop()
*
*/

128
 B Programming Data Collection
B.2 Instrumenting Objects Programmatically

STATUS wvLogFileUploadStart
(
int instClass, /* 1, 3, or 7, for CLASS1, CLASS2,
CLASS3 instrumentation */
char * filename /* logfile name */
)
{
STATUS result;
int fd;
int n;

if (filename == NULL || instClass == 0)

{
puts ("Usage is:\n 'wvLogStart <instLevel> <filename>'\n" \
"where instLevel can be 1, 3 or 7\n");
return ERROR;
}

remove (filename);

/* wvOn uses open() which cannot create a file. So we ensure

the file exists */

fd = open (filename, O_WRONLY, 0);

if (fd == ERROR)
{
fd = creat (filename, O_WRONLY);

if (fd == ERROR)
{
logMsg ("Error creating logfile\n",0,0,0,0,0,0);
return ERROR; A
}
}
close (fd);

/* Enable instrumentation for all possible classes */

for (n=0; n < sizeof (instClasses) / sizeof (instClasses [0]); n++)

{
wvObjInst (instClasses [n], NULL, INSTRUMENT_ON);
}

/* Enable events, signals and network instrumentation */

wvEventInst (INSTRUMENT_ON);
wvSigInst (INSTRUMENT_ON);
wvNetEnable (8);

result = wvOn (instClass, (int)filename, O_WRONLY, 0);

return result;
}

129
Wind River System Viewer
User's Guide, 3.2

/*
* Stop collection and close the file.
*/

void wvLogStop (void)

{
wvOff ();
}

The wvObjInstModeSet( ) routine lets you instrument a group of objects

beginning from the time of their creation. This routine is declared as follows:
STATUS wvObjInstModeSet
(
int mode /* turn instrumentation on/off:
/* INSTRUMENT_ON, INSTRUMENT_OFF */
)

For example, suppose you are adding a new module to an already existing piece
of code. You might be only interested in the new objects affect the existing
application and you do not want to instrument any other objects. Within the object
initialization code of the new module, you can surround the creation calls with
wvObjInstModeSet( ), as in the following example:
void newCode ()
{
...

/* enable instrumentation for all objects created here */

status = wvObjInstModeSet(INSTRUMENT_ON);
...
/* create message queue 1 */
mq1Id = msgQCreate (5, 20, MSG_Q_FIFO);
/* create message queue 2 */
mq2Id = msgQCreate (5, 20, MSG_Q_FIFO);
/* create semaphore 1 */
sem1Id = semMCreate (SEM_Q_FIFO);
/* create task 1 */
t1Id = taskSpawn ("task1", TASK_1_PRI, TASK_1_OPTS,
TASK_1_SIZE, task1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0);
...
/* disable object instrumentation */
status = wvObjInstModeSet (INSTRUMENT_OFF)
...
}

All objects created between the two calls to wvObjInstModeSet( ) are

instrumented. Events that affect those objects are logged if and when AIL level
logging is started, for example, with the wvEvtLogStart( ) routine, as in the
following example (which occurs after the newCode( ) fragment shown above):

130
 B Programming Data Collection
B.2 Instrumenting Objects Programmatically

void existingCode ()
{
...
/* area of existing code where objs from newCode module used */
wvEvtLogStart;
...

/* send a message to message queue 1 */

status = msgQSend (mq1Id, &buff, MSG_4, MSG_4_TIMEOUT,
MSG_PRI_NORMAL);
/* receive a message from message queue 2 */
numbytes = msgQReceive (mq2Id, &buff, BUFF_SIZE, TICKS);
/* take semaphore 1 */
status = semTake (sem1Id, SEM_1_TIMEOUT);
/* suspend task 1 */
status = taskSuspend (t1Id);
...

/* interesting section finished; stop event logging */

wvEvtLogStop();
...

To instrument all objects in the system programmatically, perform the following at

the beginning of your application:
„ Call wvObjInst( ) once for each type of instrumented object, with objID set to
NULL to instrument all objects of the specified type, and mode set to
INSTRUMENT_ON. This instruments all objects already created by the
operating system. A

„ Call wvObjInstModeSet( ) with the argument INSTRUMENT_ON. This

instruments all objects you may create thereafter.
„ Call wvSigInst( ) with the argument INSTRUMENT_ON.
„ Call wvEventInst( ) with the argument INSTRUMENT_ON.
These programmatic steps have the same effect as starting Wind River
System Viewer with all libraries checked in the GUI, starting Wind River
System Viewer logging, and starting your application.
For additional insight into the configuration start, stop and upload process, see
installDir/vxworks-N.N/target/config/comps/src/usrWindview.c.

131
 Wind River System Viewer
User's Guide, 3.2

B.2.2 Additional Libraries

The data collected by these instrumented libraries is displayed in the usual way:
with icons in the main Event Graph.
Each instrumented library is enabled or disabled as a whole. To control which
libraries are logged, use the Event Logging Level Configuration pane as
described in 4. The Event Logging Level.

memLib

The information displayed from this library is slightly different from the
information generated and displayed for events in other libraries. While the event
data generated by memlib can be useful, the critical information is usually the
scalar information generated by the event. For example, the most interesting
information about memory activities is usually how much memory is allocated at
a particular time. For more information, see 10.3 Memory Usage, p.55.
On the host, you can view cumulative information depicting what happens as
allocated memory grows and shrinks in each target partition. You can see the
addresses of memory blocks that get allocated and freed. This simplifies detecting
memory leaks. For details about the information collected for events, the routines
associated with them, and so on, see the Wind River System Viewer User’s Reference:
Event Dictionary.

wvNetDLib

This library is available at the AIL level of logging, and includes events related to
activity in the dual IPv4/IPv6 stack. As with other instrumented objects, network
events may be instrumented individually or in groups. wvNetDLib events are
grouped according to class and priority.

132
 B Programming Data Collection
B.2 Instrumenting Objects Programmatically

Networking vents are also divided into five priority levels, with 1 being the
highest. (VERBOSE, INFORMATION, WARNING, CRITICAL, and FATAL). The
network stack is instrumented for the following event classes:
WV_NETD_IP4_DATAPATH_CLASS
This class is for events that are directly related to IPv4 data transfer.
WV_NETD_IP6_DATAPATH_CLASS
This class is for events that are directly related to IPv6 data transfer.
WV_NETD_IP4_CTRLPATH_CLASS
This class is for events related to IPv4 network stack operations, such as
updating the routing table and handling socket operations.
WV_NETD_IP6_CTRLPATH_CLASS
This class is for events related to IPv6 network stack operations, such as
updating the routing table and handling socket operations.
To instrument network event logging programmatically, use the wvNetEnable( )
and wvNetDisable( ) routines, which start and stop network event logging,
respectively.
To enable Wind River System Viewer instrumentation for network events, you
must include network instrumentation in your VxWorks configuration
(INCLUDE_WVNETD). The start routine takes a single parameter specifying the
minimum priority level you wish to log. Events in both core and auxiliary classes
are logged and if no priority is specified, events for all priority levels are logged. A

In general, an instrumented target reports all events having priority greater than
or equal to the selected priority. In addition, the wvNetDLib library contains
routines that give much finer control over networking event logging. For example,
you can explicitly include or exclude individual events whose priorities are lower
than the selected level, explicitly enable or disable other events, and apply filters
to events based on addresses and port numbers.
For more information about logging network events and fine tuning these settings,
see the entry for wvNetDLib in the VxWorks OS Libraries API Reference.

133
 Wind River System Viewer
User's Guide, 3.2

B.3 Adding Eventpoints

You can specify which level of logging to implement, but data is collected only
when events are generated by the instrumented VxWorks kernel and libraries.
Your application will make many calls to VxWorks routines, but sometimes you
will want information on some of your application routines as well. There are two
ways to do this. You can set eventpoints dynamically from the Wind River
Workbench shell with the e( ) routine, or insert event-generating function calls into
application source code.

The e( ) Routine

The simplest type of user-generated event is the eventpoint, which can be set from
the shell with the e( ) routine. Eventpoints are analogous to breakpoints; they are
program locations that display the default User event icon when the instruction at
that location executes.
The e( ) routine has the following syntax:
STATUS e
(
INSTR * addr, /* address to set eventpoint; */
/* NULL = all eventpoints and */
/* breakpoints are raised */
event_t eventNo, /* event number */
int taskNameOrId, /* task in which to raise event- */
/* point; 0 = all tasks */
FUNCPTR evtRtn, /* function to be called when */
/* eventpoint encountered; NULL */
/* = no function, so eventpoint */
/* always raised */
int arg /* argument to evtRtn function */
)

NOTE: Eventpoints follow the same rules as breakpoints, including the following:
(1) Eventpoints in unbreakable tasks are not executed and thus do not appear in
the Event Graph. (2) Eventpoints cannot be set at interrupt level.

To see how a log looks when you set an eventpoint with e( ), follow these steps:
1. To set an eventpoint with an ID of 10 at the address of the sin( ) routine, click
the Launch Shell button and enter the following:
-> e sin, 10, 0, 0, 0
value - 1 = 0x1

2. Click GO to start logging using any event logging level.

134
 B Programming Data Collection
B.3 Adding Eventpoints

3. In the shell window, enter the following:

-> sin 1
value = 1 = 0x1

4. Click STOP to stop logging and upload the data.

5. Locate the numeral 10, click, drag, and zoom in over this area of the
Event Graph repeatedly until you see your user event icon with the numeral
10 beside itm which may appear as in Figure B-1.

Figure B-1 Event Graph with User Event

The wvEvent( ) Routine

The wvEvent( ) routine provides a generic event function which is always

available and which has more flexibility than e( ). The wvEvent( ) routine is
declared as follows:
STATUS wvEvent
(
event_t eventNo, /* event ID */
char * buffer, /* user-supplied buffer */
size_t bufSize /* buffer size */
)

135
 Wind River System Viewer
User's Guide, 3.2

The wvEvent( ) routine can be called from unbreakable tasks or from interrupt
level, and is therefore more flexible than the e( ) routine.
Unbreakable tasks are those that are created with the VX_UNBREAKABLE bit set in
the options argument of the taskInit( ) or taskSpawn( ) routine. For example, you
can use user-generated events for error checking, as shown in the following
example:
if (something)
{
... /* run this code */
}

else
{
... /* we should never get here, but if we do, load any values */
/* of interest into event1Buff, then log using wvEvent */

return = wvEvent (EVENT_1_ID, &event1Buff, EVENT_1_BUFSIZE);

}

If this event is ever encountered, the defaultUser event icon is displayed in the
Event Graph, with the event number just to the right of the icon. You can
double-click this icon to see the event properties.
To see how a log looks when an eventpoint is raised by wvEvent( ), perform the
following:
1. Click GO to start logging using any event logging level.
2. In the shell window, enter the following:
-> wvEvent (99, 0, 0)
value = 0= 0x0

3. Click STOP to stop logging and upload the data.

B.4 Timestamping

High-Resolution Timestamp Driver

When you develop your application for a target with a supported timestamp
driver, the instrumented kernel tags certain events with a high-resolution
timestamp. Those events are displayed in the System Viewer Event Graph along a

136
 B Programming Data Collection
B.4 Timestamping

timeline that shows when each event occurred, based on the timestamps. You can
see the exact timestamp for any particular event in the status bar, for example,
when you click on the corresponding event icon.
The timestamp driver’s resolution is hardware dependent, but is typically between
100 KHz (10 microseconds per tick) and 1 MHz (1 microsecond per tick). For
information on the system timestamp driver for any supported board, see the
entry for the board in the online VxWorks BSP Reference.
In addition to the WRS-supplied system timestamp, you may choose to write your
own timestamp driver or use the timestamp provided by an emulator. For more
information, see VxWorks Device Driver Developer's Guide:Timestamp Drivers.

Sequential Timestamp Driver

When the real-time system runs on an unsupported board, or on a supported

board without the timestamp driver, the instrumented kernel automatically uses
its sequential timestamp driver.
The sequential timestamp driver tags events with sequence numbers that simply
represent the order in which events occur on the target. The distance between
events does not reflect any measurement of time.
Figure B-2 shows data captured with the sequential timestamp driver with events
all equidistant from each other. If the same events were captured with a A
high-resolution timestamp driver, the distance between events would reflect an
actual passage of time.

137
 Wind River System Viewer
User's Guide, 3.2

Figure B-2 Sequential Event Display

B.5 Dynamic Buffer Allocation

Wind River System Viewer uses a dynamic ring buffer (rBuff) structure to support
data collection. The rBuffLib library provides a ring buffer structure which grows
and shrinks dynamically during operation. For more information about rBuffLib,
see the VxWorks OS Libraries API Reference.

138
 B Programming Data Collection
B.5 Dynamic Buffer Allocation

The size of each individual buffer and the minimum and maximum number of
buffers are configured when the buffer ring is created. The library initially allocates
the minimum number plus one additional buffer for immediate addition to the
ring if necessary. If these buffers are filled, more buffers are added until the ring
reaches the maximum size. If data is read from the rBuff, the unused buffer
memory is freed so that it may be used by other processes.

B.5.1 Configuring the Event Log Buffer

Wind River System Viewer allows you to configure the rBuff which holds the
event log as it is captured and stored on the target. How the rBuff is configured
affects how logging interacts with the target application and thus the quality of the
resulting event log.
The optimum rBuff configuration is dependent on two factors:
„ the upload mode
„ any constraints on target memory
The configuration of the rBuff has a significant impact on the frequency with
which it is dynamically extended and, consequently, how much of this activity is
represented in the log. Optimum values depend on whether you are using
deferred or continuous upload mode.
In both deferred and continuous modes, the rBuff’s memory requirements are A
sourced from the system memory partition, the general partition from which all
malloc requests are sourced. Therefore it is important to consider the size of the
rBuff carefully to ensure that it does not conflict with target application
requirements.

Upload Modes

Deferred Upload

The most effective way to use Wind River System Viewer is in deferred upload
mode. In this mode the event data remains on the target during collection and can
be uploaded to the host once logging is completed. The entire log must be stored
on the target, which potentially requires a large ring buffer. If the system partition
is exhausted to the granularity of one buffer block or if the specified maximum
number of buffers is full, data collection stops. Triggering can be used to focus the
sequence captured, avoiding an unnecessarily large buffer requirement.

139
 Wind River System Viewer
User's Guide, 3.2

In deferred upload mode, you may want all available memory to be used to hold
event data. The extendable ring of buffers can share available memory between the
customer application and the buffers. To collect as much event data as possible
within the constraints of the system and application, point the rBuff at the system
memory partition, set the maximum size to infinite by specifying 0xffffffff, and
recreate the problem. The rBuff starts at the specified minimum size, allowing the
application to allocate memory during initialization, and only begins extending
the buffer when its pre-allocated buffer is full.
The limitation of this approach is that the activity necessary to extend the rBuff
appears in the log. This makes it more difficult to determine exactly how the
system behaves when logging is not active. To avoid the intrusion of buffer
allocation on the log, you can pre-allocate the buffer space by setting the minimum
number of buffers equal to the maximum number of buffers. If you choose this
approach, configure the rBuff with a smaller number of large individual buffers.

Continuous Upload

In continuous upload mode, the data in the log is uploaded to the host periodically
as it is captured. Network activity required to upload the data itself generates
events that appear in the log. In addition, any activity required to resize the rBuff
is reflected in the log. This results in logs which are larger and more complex than
would be required to represent the application activity alone.
In continuous upload mode, you select a minimum and maximum number of
buffers. When an individual buffer is full, data is written to the next buffer. If there
are no more buffers and the current number of buffers is less than the maximum,
a new buffer is added. If a buffer is emptied and the current number is greater than
the minimum, the empty buffer is removed. This implementation is flexible and
dynamic. The collected data can fill all the memory available if necessary and if the
maximum number of buffers specified is that large, but the memory is not reserved
for logging if it is not needed.
The size of the individual buffers is used to determine when to start transferring
the event data to the host. A smaller individual buffer size initiates upload sooner
and more often. As there are variations in the rate at which events are generated
on the target and at which the network and host can achieve upload, the rBuff may
dynamically resize to accommodate the events stored on the target. Using a small
individual size maximizes the possibility of a suitable area of memory being
available to extend the rBuff.

140
 B Programming Data Collection
B.5 Dynamic Buffer Allocation

Occasionally, the rBuff is still growing, although data is being uploaded to the
host. This happens when the number of events generated by the upload process is
greater than the number of events being uploaded. This is most likely to occur
when you have specified AIL level logging and instrumented semLib because the
upload implementation generates many semaphore events.
The ability to specify the minimum number of buffers to be retained avoids buffer
thrashing, where the ring is repeatedly extended and shortened as the amount of
data in the buffer crosses a particular threshold. There is nothing special about the
set of buffers that is originally allocated. As the ring of buffers is filled and then
emptied, the initial set is just as likely to be freed as those that are subsequently
allocated to meet demand. In a balanced system, the rBuff is not constantly
resized; the ring of buffers remain at the original size and allows steady upload of
event data.
For these reasons, when using continuous upload mode, configure the rBuff with
a larger number of small sized individual buffers and adjust the minimum number
of buffers if necessary to prevent thrashing.

Post-mortem Mode

In post-mortem mode, Wind River System Viewer automatically configures the

number and size of buffers in the ring. The only configuration step you must take
is to place your buffer in an area of memory that is not overwritten when VxWorks
reboots. For more information, see 5.3 Post-Mortem Upload Modes, p.23.
A

rBuff Task Priority

The rBuff is managed by the task tWvRBuffMgr. The default priority of this task
is 100. This priority is usually appropriate, particularly when you use either
deferred upload mode or post-mortem mode. In some environments when you use
continuous upload mode, tWvRBuffMgr is not high enough priority to be able to
expand the number of buffers before they fill. If you find that the rBuff is
overflowing in continuous mode, use wvRBuffMgrPrioritySet( ) to give
tWvRBuffMgr a higher priority.

141
 Wind River System Viewer
User's Guide, 3.2

Target Memory Constraints

If you are using a target configuration with sufficient memory resource to dedicate
a proportion to Wind River System Viewer, the ring of buffers may be configured
such so its individual buffers are pre-allocated. This is achieved by configuring the
minimum number of buffers in the ring equal to the maximum number of buffers.
If you are using a target with limited memory resource, use the ring buffer
dynamic resizing facility. This is done by allocating a low minimum number of
buffers with a greater maximum number of buffers. In deferred mode, only those
buffers required above the minimum, and for which space is available at the time
of request, are allocated. In continuous mode, the buffer only extends above the
minimum when necessary to hold the upload backlog, and those extra buffers are
freed when not in use. When using a dynamically resizing buffer configuration, the
ring buffer will not give up buffers it is holding to satisfy a request for memory
made by another part of the system. Therefore, care should be taken when
specifying the maximum ring buffer size.
When using post-mortem mode, the ring buffer is automatically configured to
make appropriate use of the available memory dedicated to this purpose.

B.5.2 Configuration Tuning

The precise ring buffer configuration used is dependent upon many factors such
as relative host and target performance, network bandwidth, the rate at which the
target application generates events, and the upload method used. Therefore it is
advisable to experiment with the ring buffer and upload configuration if any of
these factors is altered to find a configuration which best suits your development
system.

142
 C
Triggering API

C.1 Introduction 143

C.2 Using the Triggering API Functions 146

C.1 Introduction
Wind River System Viewer provides a triggering API and triggering that works in
conjunction with logging. You can use the triggering interface to enter specific
information and commands, which are then downloaded to the target. Although
this data is usually entered in the triggering interface window, you can enter data
at command line. After this data is received, the target handles the following tasks:
„
Organizes the data received from the host in a trigger list.
„
Manages the trigger list and sets the flag to activate triggering when necessary.
„
Activates and deactivates event triggering.
„
Performs the actions requested by the host.
„
Interacts with Wind River System Viewer and the event points.
„
Saves the information coming from the host in a trigger structure.
When a flag is set, the event can be detected by the regular Wind River
System Viewer instrumentation, e( ), or trgEvent( ). Once the event occurs, the
ACTION_IS_SET variable is checked to see whether System Viewer
(instrumentation) logging or triggering is active. If triggering is active, the list of
triggers is checked to see if any is related to that event. If one is found, the specified
action is performed. Otherwise, execution continues, as shown in Figure C-1.

143
 Wind River System Viewer
User's Guide, 3.2

Macros

The ACTION_IS_SET macro is shared by both logging and triggering, and

regulates the activation and interactions of both logging and triggering. The
process flow is shown in the following pseudocode:
if ACTION_IS_SET
{
if WV_ACTION_IS_SET
do logging
if TRG_ACTION_IS_SET
do triggering
}

Macros that defined the status of a trigger are:

#define TRG_ENABLE 1
#define TRG_DISABLE 0

Macros that define whether the condition is a variable or a function are:

#define TRIGGER_COND_FUNC 0
#define TRIGGER_COND_VAR 1
#define TRIGGER_COND_LIB 2

144
 C Triggering API
C.1 Introduction

Figure C-1 Process Followed if Triggering is Activated

Is either YES NO NO
logging or Logging On? Triggering On?
triggering
on?

NO YES YES

NO
EXIT Is there a trigger?
Run MACRO

YES

NO
Is it enabled?

YES

Is it the correct NO
type of event,
context, &/or
object?

YES

NO Is there a
condition? B

YES

YES Is there an YES

action? Is it true?

NO
Perform
action NO

NO Is there a NO
Disable current chained trigger?
trigger?
YES
YES
Disable Enable new
trigger trigger

EXIT

145
 Wind River System Viewer
User's Guide, 3.2

Triggering Structure

The triggering structure is defined as follows:

typedef struct trigger
{
OBJ_CORE objCore; /* trigger object core */
event_t eventId; /* event type */
UINT16 status; /* status of the trigger, */
BOOL disable; /* check if disable after use */
int contextType; /* type of context where event occurs */
UINT32 contextId; /* id of context where event occurs */
OBJ_ID objId; /* object type */
struct trigger *chain; /* pointer to chained trigger */
struct trigger *next; /* ptr to next trigger in list */
int conditional; /* check if a condition is set */
int condType; /* check the expression type (var/fn) */
void * condEx1; /* ptr to conditional expression */
int condOp; /* conditional operator */
int condEx2; /* second operand (constant) */
int actionType; /* type of action (none, fn, lib) */
FUNCPTR actionFunc; /* pointer to the action */
int actionArg; /* argument passed to the action */
BOOL actionDef; /* defer the action */
} TRIGGER;

C.2 Using the Triggering API Functions

All the operations allowed on triggers, such as create, destroy, enable, and disable,
are handled by the triggering API functions. Because these functions involve many
parameters, using the GUI tools is preferable because it ensures the proper
environment for the construction or modification of a trigger.
The following functions are used to manipulate the triggering structure, to detect
the presence of a trigger, and to perform the action specified in the trigger
definition:

146
 C Triggering API
C.2 Using the Triggering API Functions

Adding a Trigger to the Trigger List

trgAdd( ) adds a new trigger to the trigger list.

TRIGGER_ID trgAdd
(
event_t event, /* System Viewer event type as defined in
eventP.h */
int status, /* initial status (enabled/disabled) */
int contextType, /* type of context where event occurs */
UINT32 contextId, /* ID (if any) of context where event occurs */
OBJ_ID objId, /* object type, if given */
int conditional, /* flag specifying if there is a condition */
int condType, /* flag specifying variable or a function */
int * condEx1, /* pointer to conditional expression */
int condOp, /* operator (==, !=, <, <=, >, >=, |, &) */
int condEx2, /* second operand (constant) */
BOOL disable, /* flag specifying whether to disable a trigger
/* after it is fired */
TRIGGER *chain, /* flag specifying if trigger is chained */
int actionType, /* action type associated with trigger */
FUNCPTR actionFunc, /* pointer to the function */
BOOL actionDef, /* defer the action */
int actionArg /* argument passed to function if any */
)
{
/* fill in trigger struct and add it to the trigger list; */
/* return the trigger ID */
}

Deleting a Trigger from the Trigger List

Triggers are deleted when they are removed from the trigger list. The function B
trgDelete( ) also checks to see if any other triggers are still active; if none are, but
triggering is still active, it turns triggering off. Triggering introduces some
overhead and should be disabled if no function is present.
STATUS trgDelete
(
TRIGGER_ID trgId
)
{
/* delete trigger from table; if last trigger, turn triggering off */
}

Activating and Deactivating Triggering

When an event point is hit with triggering active, a check for existing triggers is
performed. Because of this overhead, it is important to activate triggering only
when necessary. These functions activate and deactivate triggering.

147
 Wind River System Viewer
User's Guide, 3.2

STATUS trgOn()
{
/* set evtAction to TRG_ACTION_IS_SET if not already set */
}

void trgOff()
{
/* set evtAction to TRG_ACTION_IS_UNSET if it is on */
}

Showing Information on Triggers

The following information is given: trigger ID, event ID, status, condition, disable
trigger, and chained trigger. If options is 1 and trgId is specified, all parameters are
shown for the specified trigger. If trgId is NULL all the triggers are shown.
STATUS trgShow
(
TRIGGER_ID trgId,
int options
)
{
/* display information on specified trigger or on all triggers */
}

Changing Trigger Status

trgEnable( ) sets the status of an existing trigger. This is the mechanism used to
activate a chained trigger. A counter is also incremented to keep track of the total
number of currently enabled triggers. This information is used by trgDisable( ).
STATUS trgEnable
(
TRIGGER_ID trgId
)
{
/* enable trigger unless max number of triggers is already enabled */
}

trgDisable( ) is used to disable a trigger. This function also checks to see if there are
any other triggers still active. This is done through the counter trgCnt. If trgCnt is
0 and triggering is still on, it calls trgOff( ).
STATUS trgDisable
(
TRIGGER_ID trgId
)
{
/* turn off trigger; if last active trigger, turn triggering off */
}

148
 C Triggering API
C.2 Using the Triggering API Functions

Creating a User Event to Fire a Trigger

trgEvent( ) triggers a user event. A trigger must exist and triggering must have
been started with trgOn( ) or from the triggering GUI to use this routine. The evtId
must be in the range from 40000 to 65535 on VxWorks-family Target Operating
Systems, or from 4096 to 4351 on Wind River Linux.
.
void trgEvent
(
event_t evtId /* event*/
)
{
/* set a user event with the specified ID */
}

149
Wind River System Viewer
User's Guide, 3.2

150
 D
Configuring VxWorks for
System Viewer

D.1 Introduction 151

D.2 Configuring the Kernel 152
D.3 System Viewer Components 153

D.1 Introduction
This chapter tells you where and how to configure a VxWorks Image Project to
appropriately support System Viewer functionality in Wind River Workbench.
For more information on VxWorks Image Projects and how to configure,
customize, scale, and build a VxWorks kernel image in Wind River Workbench, see
the Wind River Workbench User’s Guide.
For more information on how to configure and build a VxWorks kernel from the
command line, see the VxWorks Command Line Tools User's Guide. The specific
components you will need to build a kernel with System Viewer instrumentation
are listed in this chapter.

151
 Wind River System Viewer
User's Guide, 3.2

D.2 Configuring the Kernel

You add the various System Viewer components using the Kernel Editor.
1. In the Project Navigator, expand your VxWorks Image Project and
double-click the Kernel Configuration node.
2. In the Kernel Editor that appears, select the Components tab.
3. Expand development tool components > System Viewer components and
include, as needed (components that are not already included are shown in
pale blue):
– D.3.1 Basic System Viewer Components, p.153.
– D.3.2 Upload Method Components, p.153
– D.3.3 Upload Mode Buffer Components, p.154
– D.3.4 Timestamping Components, p.154
– D.3.5 Triggering Components, p.154
– D.3.6 Network Components, p.154

NOTE: The easiest way to find components in the Kernel Editor is to click into the
window and type CTRL+f. In the Find dialog’s Pattern field, type an asterisk (*)
followed by the first few letters of the component.

4. When you are done, save the new kernel configuration.

5. Build your project.

152
 D Configuring VxWorks for System Viewer
D.3 System Viewer Components

D.3 System Viewer Components

The following lists System Viewer kernel components grouped by functionality.

D.3.1 Basic System Viewer Components

INCLUDE_WINDVIEW
Required to initialize and control logging.
INCLUDE_WINDVIEW_CLASS
Required for kernel instrumentation.

D.3.2 Upload Method Components

„ Upload method: Socket via TSFS
Required components:
– INCLUDE_WVUPLOAD_TSFSSOCK
„ Upload method: Socket via TCP/IP
Required components:
– INCLUDE_WVUPLOAD_SOCK
„ Upload method: File via TSFS
Required components:
– INCLUDE_WVUPLOAD_FILE
„
Upload method: File via NFS D
Required components:
– INCLUDE_WVUPLOAD_FILE
– INCLUDE_NFS
– INCLUDE_NFS_MOUNT_ALL
„
Upload method: File via netDrv
Required components:
– INCLUDE_WVUPLOAD_FILE

153
 Wind River System Viewer
User's Guide, 3.2

D.3.3 Upload Mode Buffer Components

INCLUDE_RBUFF
Supports the System Viewer ring buffer library (recommended as
sufficient if you are new to System Viewer).
INCLUDE_WV_BUFF_USER
Allows you to provide a custom implementation of the rBuff library.
INCLUDE_RBUFF_SHOW
Displays rBuff information and statistics about ring buffer performance.
Optional and only available if you include RBUFF.

D.3.4 Timestamping Components

INCLUDE_SEQ_TIMESTAMP
Supports sequential timestamping (recommended if you are new to
System Viewer)
INCLUDE_USER_TIMESTAMP
Supports user-defined timestamping.
INCLUDE_SYS_TIMESTAMP
Supports BSP-specific timestamping (not supported by the simulator).

D.3.5 Triggering Components

NOTE: If you are stripping System Viewer components, do not remove this. It
is a VxWorks component.

INCLUDE_TRIGGERING
Adds support for triggering.

D.3.6 Network Components

INCLUDE_WVNETD
Adds support for dual stack Network Instrumentation (wvNetDLib).

154
 E
VxWorks6.N user.xml
Example File

E.1 Introduction 155

E.2 VxWorks 6.N user.xml Example File 156

E.1 Introduction
This appendix shows an example of a complete new user.xml file, written
specifically for VxWorks 6.N. The example demonstrates many of the techniques
described under 14.3 The User Events Description File, p.93. Explanations, where
required, are provided in embedded comments.
If your Target Operating System (TOS) is not VxWorks 6.N, you should use the
default user.xml file (see 14.3.1 Location of the User Events Description File, p.93) for
your TOS as a prototype, and be sure not to alter the range of user event IDs
permitted for that TOS.

155
 Wind River System Viewer
User's Guide, 3.2

E.2 VxWorks 6.N user.xml Example File

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE EventDictionary SYSTEM "../../DTDs/EventDictionary.dtd">
<EventDictionary>
<EventClass
key="user"
displayName="User Events"
helpTopicId="VXWORKS6_user_CLASS_HELP">

<!-- eventId range 40000-40099 inclusive,

This is just as per the default user.xml, but with a reduced range
-->
<EventRangeDescription
eventIdStart="40000"
eventIdCount="100"
nameRoot="EVENT_USER"
displayNameRoot="user"
nameRootSuffixStart="0"
icon="images/defaultUser.gif"
trigger="true"
helpTopicId="VXWORKS6_EVENT_USER_EVENT_HELP"
handler="com.windriver.windview.plugins.wv.vxworks.UserEventDescription">
<EventParam
type="UINT32"
name="pc"
formatStr="0x%08x"/>
<EventParam
type="BLOB"
name="data"
formatter="com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter"/>
</EventRangeDescription>

<!-- eventId range 40100-40199 inclusive

This range has been extracted in order to change the display
characteristics. The range will be displayed starting with
"myUserEvent0" and use a custom icon which must be located in
"images/myUserIcon.gif" relative to the location of this XML file.
Since the "handler" attribute is included as shown, the user event
number (starting at the the number defined in "nameRootSuffixStart")
will be composited with the given icon.
-->
<EventRangeDescription
eventIdStart="40100"
eventIdCount="100"
nameRoot="EVENT_USER"
displayNameRoot="myUserEvent"
nameRootSuffixStart="0"
icon="images/myUserIcon.gif"
trigger="true"
handler="com.windriver.windview.plugins.wv.vxworks.UserEventDescription">

156
 E VxWorks6.N user.xml Example File
E.2 VxWorks 6.N user.xml Example File

<EventParam
type="UINT32"
name="pc"
formatStr="0x%08x"/>
<EventParam
type="BLOB"
name="data"
formatter="com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter"/>
</EventRangeDescription>

<!-- leaving a gap here for eventIDs 40200-40201 inclusive. These will
be completed using discrete UserEventDescriptions which must appear
after all the defined EventRangeDescriptions.
-->

<!-- eventId range 40202-65535 inclusive

This range is the remainder of the original user event definition.
It starts at EventID 40202 and continues for the remaining 25334
events taking us up to EventID 65535. The range will have a display
name starting with "user202".
-->
<EventRangeDescription
eventIdStart="40202"
eventIdCount="25334"
nameRoot="EVENT_USER"
displayNameRoot="user"
nameRootSuffixStart="202"
icon="images/defaultUser.gif"
trigger="true"
helpTopicId="VXWORKS6_EVENT_USER_EVENT_HELP"
handler="com.windriver.windview.plugins.wv.vxworks.UserEventDescription">
<EventParam
type="UINT32"
name="pc"
formatStr="0x%08x"/> C
<EventParam
type="BLOB"
name="data"
formatter="com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter"/>
</EventRangeDescription>

<!-- This is the end of the EventRangeDescriptions. There now follow

any discrete EventDescriptions to fill in holes.
-->

157
Wind River System Viewer
User's Guide, 3.2

<!-- eventID 40200. Uses the extended icon attribute format.

Displayed event name will be "Trace#0".
Will have the default, auto-generated icon in the default color.
The text "Trace0" will be composited above the icon, also in the
default color.
-->
<EventDescription id="40200"
name="MY_TRACE_EVENT_0"
trigger="true"
displayName="Trace#0"
icon="text=Trace0">
<EventParam
type="UINT32"
name="pc"
formatStr="0x%08x"/>
<EventParam
type="BLOB"
name="data"
formatter="com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter"/>
</EventDescription>

<!-- eventID 40201. Uses the extended icon attribute format.

Displayed event name will be "Trace#1".
Will have the default, auto-generated icon in bright red.
The text "Trace1" will be composited above the icon, also in
bright red.
-->
<EventDescription id="40201"
name="MY_TRACE_EVENT_1"
trigger="true"
displayName="Trace#1"
icon="text=Trace1,color=#FF0000">
<EventParam
type="UINT32"
name="pc"
formatStr="0x%08x"/>
<EventParam
type="BLOB"
name="data"
formatter="com.windriver.windview.agnostic.wv.SmartHexAsciiFormatter"/>
</EventDescription>

</EventClass>
</EventDictionary>

158
 Index

A C
ACTION_IS_SET macro 144 chaining
aggregate core usage analysis 56 conditional triggers 78
AIL (additional instrumentation logging level) 126 triggers for logging 80
all events Overview mode 50 clock
analysis auxiliary, and timestamping 63
aggregate core usage 56 system, and timestamping 63
core usage per core 55 collecting data, see event logging
event graph/table 54 components,removing 124
memory usage 55 condition, using a function as, for triggering 83
ready state 58 configuration 42
running state 58 configure
system load 56 upload mode 19
analysis types 53 configuring
automatic upload 35 timestamping 63
auxiliary clock, and timestamping 63 VxWorks 151
connection
resume 42
continuous upload mode 20
B buffer thrashing 31
and ring buffers 140
boot loader 25
tWvRBuffMgr task priority, setting 141
buffering 27
upload failure 30
bufffer thrashing 31
core dump, VxWorks log upload 44
core usage per core analysis 55
cpu usage analysis 55
cpu, aggregate usage 56
custom events, Wind River Linux 120

159
 Wind River System Viewer
User's Guide, 3.2

D event table 54
events
data defined 15
collectin 41 user, for starting and stopping System
logging 41 Viewer 86
uploading 41
defaultUser event
see also event, eventpoints F
e( ), using 134
wvEvent( ), using 135 file system location,logs 35
deferred upload mode 20 File via netDrv
dynamic ring buffers 139 components 153
defining File via NFS
triggers 70 components 153
deployment 124 File via NFS upload method 38
downloading triggers 74 File via TSFS
components 153
File via TSFS upload method 37
E filtering 59
functions
e( ) 134 call function used in triggering 85
errors in log files, and warnings 48 using as a triggering condition 83
event using with triggering 83
custom, see Wind River Linux
custom events
event function, generic 135 H
event graph
legend icons 54 host, remote 39
event intensity Overview mode 51
Event Receive utility
upload options 39
eventLog.wvr log file, default name 39 I
eventpoints 134
e( ), setting with 134 INCLUDE_NFS 153
wvEvent( ), setting with 135 INCLUDE_NFS_MOUNT_ALL 153
graph 54 INCLUDE_RBUFF 154
logging 125 INCLUDE_RBUFF_SHOW 154
application routines 134 INCLUDE_SEQ_TIMESTAMP 154
memory usage 132 INCLUDE_SYS_TIMESTAMP 154
programming 125 INCLUDE_TRIGGERING 154
sequential timestamping 137 INCLUDE_USER_TIMESTAMP 154
timestamping 136 INCLUDE_WINDVIEW 153
receive 39 INCLUDE_WINDVIEW_CLASS 153
user, see user events (VxWorks family) INCLUDE_WVUPLOAD_FILE 153
event analysis 54 INCLUDE_WVUPLOAD_SOCK 153

160
 Index

INCLUDE_WVUPLOAD_TSFSSOCK 153 INCLUDE_WINDVIEW_CLASS 153

INSTRUMENT_ON 131 kernel configuration 151
instrumentation, removing 124 kernel libraries 126
instrumenting 126 instrumenting 126
individual objects and groups 127
libraries, overview 126
memLib library 132
netLib library 132 L
objects
legend icons 54
from creation time 130
Linux, Wind River 109
programmatically 126
buffer configuration 114
routines 126
configuration summary 110
signals, programmatically 128
configuring for System Viewer 109
custom events 120
log conversion options 115
K output filename 114
System Viewer configuration 110
kernel components target file system options 113
basic load, system 56
INCLUDE_WINDVIEW 153 log files
timestamping default name, eventLog.wvr 39
INCLUDE_SEQ_TIMESTAMP 154 errors and warnings 48
INCLUDE_SYS_TIMESTAMP 154 opening manually and automatically 47
INCLUDE_USER_TIMESTAMP 154 logging 41
triggering chaining triggers for 80
INCLUDE_TRIGGERING 154 control with System Viewer API 43
upload method file via netDrv start 41
WVUPLOAD_FILE 153 with System Viewer Configuration
upload method file via NFS utility 42
INCLUDE_NFS 153 logging, premature stop 29
INCLUDE_NFS_MOUNT_ALL 153 logs,file system location 35
INCLUDE_WVUPLOAD_FILE 153 LTTng 109 Index
upload method file via TSFS custom events 120
INCLUDE_WVUPLOAD_FILE 153
upload method socket via TCP/IP
INCLUDE_WVUPLOAD_SOCK 153
upload method socket via TSFS M
INCLUDE_WVUPLOAD_TSFSSOCK 15
memLib library
3
logging information 132
upload mode
routines associated with events 132
INCLUDE_RBUFF 154
memory
INCLUDE_RBUFF_SHOW 154
leaks, and detection 55
INCLUDE_WV_BUFF_USER 154
usage, and event logging 132
kernel compononts
usage, and ring buffers 142
basic

161
 Wind River System Viewer
User's Guide, 3.2

Memory Read upload method 34 RBUFF_SHOW 154

memory usage analysis 55 rBuffLib 44
message queues, instrumenting 126 reading
mode upload 19 timestamping 63
module manager 115 ready state analysis 58
msgQLib, instrumenting specific objects 128 reboot target 42
multicore visualization 54 remote host, socket connection 39
ring buffer 27
ring buffers
dynamic
N target memory limitations, handling 142
tWvRBuffMgr task priority, setting 141
NFS 153
management task (tWvRBuffMgr) 141
NFS_MOUNT_ALL 153
routines, instrumenting, see instrumenting routines
running state analysis 58

O
objects, instrumenting
S
programmatically 126
searching 60
Overview
semaphores, instrumenting 126
all events mode 50
semLib library, instrumenting specific objects 128
event intensity mode 51
SEQ_TIMESTAMP 154
peak activity mode 50
SEQ_TIMESTAMP component 65
sequential timestamp driver 137
socket connection 39
P socket via TCP/IP upload method 37
Socket via TSFS
peak activity Overview mode 50 components 153
post-mortem mode socket via TSFS upload method 37
ring buffers, dynamic, effect on 141 Socket via TSFS, components 153
typical configuration 26 starting
post-mortem upload 26 logging, with the System Viewer Configuration
post-mortem upload mode 23 utility 42
probe 115 System Viewer
programming with user events 86
event logging 125 state stipples 54
instrumenting objects 126 status
icons for triggers 75
stipples 54
stopping System Viewer, with user events 86
R SYS_TIMESTAMP 154
SYS_TIMESTAMP component 64
RBUFF 154 system clock, and timestamping 63
rBuff 27 system load analysis 56

162
 Index

System Viewer Log Viewer (External) 47 controlling logging 67

function used as a condition 83
getting started with 68
process explained 143
T sample code 68
trigger status icons 75
target
using 67
reboot 42
triggers
routines, instrumenting objects 126
API usage
Target Server File System (TSFS)
activating triggers 147
uploading to a file 37
adding triggers 147
taskInit( ) 136
changing status 148
taskLib library, instrumenting specific objects 128
deactivating 147
tasks
deleting triggers 147
instrumenting 126
displaying information 148
spawning 136
user events, creating trigger-related 149
tWvRBuffMgr 141
chaining for logging 80
unbreakable 136
conditional, chaining 78
taskSpawn( ) 136
counting, for 72
TCP/IP upload method 37
creating and running samples 76
thrashing 31
defining and using 70
ticks, and timestamps 64
downloading and running 74
timestamping
logging examples 86
see also timestamps
"no action," specifying 72
high resolution 136
status icons 75
reading and configuring 63
triggered actions, specifying 72
sequential timestamp driver 137
using functions with triggering 83
timestamps
troubleshooting 27
custom drivers 65
buffer thrashing 31
driver resolution, high-resolution
logging stops 29
timestamping 64
upload failure, continuouse mode 30
SEQ_TIMESTAMP component 65
TSFS upload method, socket 37
sequential timestamping 65 Index
tWvRBuffMgr, priority setting 141
SYS_TIMESTAMP component 64
ticks 64
USER_TIMESTAMP component 65
TRG_DISABLE 144 U
TRG_ENABLE 144
trgEvent( ) example 86 upload
TRIGGER_COND_FUNC 144 data 41
TRIGGER_COND_LIB 144 mode
TRIGGER_COND_VAR 144 ring buffers, effect on dynamic 139
TRIGGERING 154 Upload Method pane 33
triggering upload failure 30
API 143 upload failure, continuous upload mode 30
call function used as an action 85 upload methods

163
 Wind River System Viewer
User's Guide, 3.2

File via NFS 38

File via TSFS 37
W
Memory Read 34 warnings, and log files 48
socket via TCP/IP 37 watchdog timers, instrumenting 126
socket via TSFS 37 wdLib, instrumenting specific objects 128
upload mode 19 Wind River Linux
buffering 27 buffer configuration 114
continuous 20 configuration summary 110
deferred 20 configuring for System Viewer 109
post-mortem 23, 26 custom events 120
troubleshooting 27 log conversion options 115
user events (VxWorks family) 91 output filename 114
advanced techniques 106 System Viewer 109
description file 93 target file system options 113
display 92 WINDVIEW 153
user.xml 93 WINDVIEW_CLASS 153
user.xml example file for VxWorks 6.N 155 WV_BUFF_USERINCLUDE_WV_BUFF_USER 15
validate XML 104 4
USER_TIMESTAMP 154 wvEvent( ) 135
USER_TIMESTAMP component 65 wvLib 44
user-defined events, triggering, for 149 wvNetDLib 44
using wvObjInst( ) 127
File via NFS upload method 38 wvObjInstModeSet( ) 130
File via TSFS upload method 37 wvOff( ) 43
functions with triggering 83 wvOn( ) 43
Memory Read upload method 34 wvRBuffMgrPrioritySet( ) 141
System Viewer API to control logging 43 WVUPLOAD_FILE 153
the System Viewer Configuration utility 42 WVUPLOAD_SOCK 153
triggers 70 WVUPLOAD_TSFSSOCK 153
Upload Method pane 33

V X
XML, validate 104
validating triggers, with variables 73
variables
defining to validate triggers 73
view graphs
sequenced events, displaying 137
timestamped events, displaying 136
VX_UNBREAKABLE 136
VxWorks
configuring 151
core dump log upload 44
user event see user events (VxWorks family)

164
Index

Index

165