TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Using the Tasking Logic Analyzer

The following topics are discussed in this document:


Overview

Note: For embedded products, the Tasking Logic Analyzer is available only with the Apex for Rational Exec products.

The Tasking Logic Analyzer allows the Apex Ada programmer to trace task execution and analyze it using saved event files or, by using the debugger, to examine the most recent events. The Trace tool is provided to display event data in such a way as to help in understanding the behavior of the tasks in a number of different ways.

The software consists of an instrumented Ada runtime library, Ada packages to support user program control of logging, support within the Ada debugger, apex_debug, for display of interpreted events and an analysis program, apex_trace_driver.

apex_trace_driver can analyze trace information to generate a text interpretation of the raw events, statistical analysis of tasking behavior, or it can output the data to an X-windows program, apex_xtrace, for graphical display.

apex_debug can also output the current trace buffer to apex_xtrace.

Figure 1 shows an overview of the Tasking Logic Analyzer. An instrumented Ada program writes events to an event buffer. This can either be read by apex_debug or written to a file by user inserted subroutine calls or automatically on program completion. apex_debug and apex_trace_driver use similar analysis to interpret the event buffer or trace file(s) respectively. Using the program's load module and Ada libraries, the logged information is interpreted into Ada names and source positions and output to a Key file and to a temporary trace file (which may consist of a concatenation of multiple trace files). The Key file is a text file providing a list of conversions from numbers to names. The Key file and temporary trace file are inputs to apex_xtrace, an X-windows program that can analyze the data and express it graphically.

Figure 1 Overview of Tasking Logic Analyzer Software


Apex and the Tasking Logic Analyzer

The Tasking Logic Analyzer is integrated into the Apex directory structure.

The software can be found in your APEX_HOME area under the subdirectory bin. The tools are called apex_trace_driver and apex_xtrace.

There exists a subsystem, $APEX_BASE/ada/rts_trace.ss, which contains Ada packages which allow the user program control of tracing. It also contains several examples referenced within this document.

rts_trace.ss
Support packages
event_log_manager.1.ada
event_log_manager.2.ada
krn_event_log_manager.1.ada
krn_event_log_manager.2.ada
Examples
own_buffer.2.ada
phil.2.ada
phil2.2.ada

Other packages of interest for tracing are:

rational.ss
v_i_trace.1.ada
v_i_krn_trace.1.ada

which specify the standard runtime events and some of the low-level logging information.

Trace configuration data can be configured with parameters in the user library, $APEX_BASE/ada/usr_conf.ss/<view>/v_usr_conf.2.ada.


Getting Started

This section walks the user through using the Tasking Logic Analyzer. It is intended to get you using the tool quickly. Explanations are brief. For more detail, please refer to other sections of the manual.

This section assumes you have been able to compile and run an Ada program.

Link in an Instrumented Runtime

When you select the Compile > Link menu item, a Link dialog will be presented. Select the Alternatives Icon button next to the Options > prompt box. Select on the -tracing runtime item and it will appear as an option in the prompt box. Select the OK button and the link will proceed.

Or, from a shell command line, add the option -tracing runtime to your link command. For example, assuming test1.2.ada is your main program source, add the following line to your link command:

Loading a Tracing Kernel

(For Embedded Systems Only) A special kernel must be loaded to support event tracing. Your default kernel is built in the Board Specific krn_conf area and has the name v_krn_main. In the same view should be the file v_ktr_main. This is the tracing kernel. You should download this, either using the Tools > Targets menu option or the File > Download option.

You can also use apex_download to load the kernel from the command line.

Turn Tracing On and Run Your Program

You still have the option of running your relinked program without tracing although it will run slightly slower. This is so that users trying to track down problems can check that program behavior is the same as when linked without tracing.

To enable tracing, select the File > Run... menu item. Select the button labelled "collect trace data" then select OK.

Or, from the shell command line use the csh command,

or, on some more restrictive host systems

and run your program

Note, you will have to perform the setenv command each time you login.

To disable tracing from the shell, enter the csh command

and run your program.

Process log files with an X-Window system

To view the trace data, select the Tools > Trace menu item on your view window.

A dialog window will appear. Select for graphic output, then select OK.

A main window will appear with the title Apex Trace. The graphs of immediate interest are to be found under the View menu item.

Restarting the X-Window version of apex_trace_driver

Several new files will appear in your view directory after running the X window version of apex_trace_driver. These have filenames of the form

test1.replay.123456
test1.key.123456
test1.trace.123456

where test1 is the name of your main program unit and the 123456 represents a unique 6-character string generated by the mktemp() UNIX system service.

After you exit the trace graphical tool (File > Exit), you can restart the tool at any time by invoking the replay script from a shell prompt. For example:

Alternatively, the Tools > Replay Trace menu item invoked from the View window allows you to select a replay file.

At the prompt box "replay file name" enter the name of the replay file or use the Alternatives Icon to select from all files of the form *.replay.*

Process log files without an X-Window system

From a shell command line, you can still view statistical analysis and a readable text version of the raw events in the log file.

Assuming you are in an Apex shell:

will output the text interpretation of your events into the file tmp.

will output a statistical analysis of your events into file stat.


Runtime Library Instrumentation

The following topics are discussed in this section:

Overview

There are two types of instrumentation. The main type is Runtime Library Instrumentation and is implemented using an instrumented Ada Runtime which is included in the user program by relinking the load module. Trace events are generated by an instrumented Ada Runtime which is included in the user program by relinking the executable. It is also possible to log user events by adding subroutine calls to your code.

Events are saved as records. The first part of the record is common to all types of event and the latter part is variant.

The common fields are

A standard set of runtime events is supported. In addition, the user can log up to 20 user defined event types by the same mechanism. User events are inserted as subprogram calls in the user's program and are logged in the buffer interspersed with the runtime events.

The events are defined in the standard directory in package V_I_Trace (filename v_i_trace.1.ada).

There are a number of types of events.

Runtime Events

The following events are supported. Events ending in _req represent requests from the user's code. They are logged on entry into the task services of the runtime. Events ending in _end are usually logged just before control is returned to the user code.

This list will expand in the future for specialized runtime use.

User Events

The following user events are supported.

The following event names can be used as required by the user.

You can log these events by instrumenting programs with calls to a subprogram supplied with the trace software. Different versions allow you either to log a fixed length (16 character) string or 0 to 4 integers.

Header Events

There is one form of header event. Its format is specified in package V_I_Trace. As well as the usual fields, the following are defined

Task_Name
User notation - an integer value
Phase
User defined - a value of type Duration
Period
User defined - a value of type Duration
Execution_time
A value of type Duration
Priority
A task priority stored as an integer

These are user supplied items, which are designed to be of use in documenting test runs.


User Control

The following topics are discussed in this section:

Steps

There are several steps you must take to obtain trace data. You must at least relink your program with a tracing option.

After relinking you have several options.

1 . If you simply want to generate a default set of Runtime Events, you can either use the File > Run... "collect trace data" button or set the APEX_TRACE environment variable. At the end of program execution, the current event buffer will be transferred to the default trace file in your current working directory.

2 . If you run your program under the debugger, apex_debug, invoked either with the "collect trace data" button set, or with the APEX_TRACE environment variable set, you have a number of control options that you can exercise at any breakpoint. You can enable or disable any runtime events and you can dump the current event buffer to the file of your choice.

3 . You can control logging by modifying your program to call subprograms in the package Event_Log_Manager which is found in the rts_trace.ss subsystem. This package supports a large number of configuration and control options. It also supports logging of user generated events in the same buffer as the Runtime events. This method offers you the greatest control and flexibility, but involves the most work on your part.

Relinking Your Program

The following command line option control tracing.

Option Name
Dialog
Action
- tracing runtime
link dialog
affects linking

In order to generate runtime logs, you must link your program with an instrumented runtime.

In order to do this you must link with at least the following option:

-tracing runtime

If you do not want to generate runtime data, you do not need to link in the instrumented runtime, but you do need to recompile and relink with the normal runtime.

If you have added calls to the package Event_log_Manager, you need to add a view from the rts_trace.ss subsystem to your imports.

The default linking option is no automatic tracing but this doesn't mean you can't trace. If you simply use Event_log_Manager to generate user events and to do your own log file creation and save of event buffers to that file. If you save your own buffer, you will not want to use the File > Run... "collect trace data" button or APEX_TRACE environment variable or you will get two buffer saves.

There are further controls.

You can alter the default name of the trace file by using the shell environment variable APEX_TRACE_FILENAME.

You can change the default size of the event buffer (4096 events) by using a pragma MAIN statement in your main program.

For more information on pragma Main, see the Ada Compiler Reference Guide.

Alternatively, the package Event_Log_Manager allows you to control these and more.

Debugger Control (overview)

Assuming you have either set APEX_TRACE or otherwise arranged to log trace events, you can perform a certain amount of logging control from the debugger, apex_debug.

The following actions are possible.

1 . Enable or disable all or single runtime events using the te - trace enable and td - trace disable commands.

2 . Dump the current event buffer to the file of your choice using the to - trace output command.

3 . Pass the current event buffer and a key file of conversions from numbers to names to the X-window display program apex_xtrace.

4 . Browse the event buffer in several different formats. The main formats are concise (one event per line) and verbose. You can also browse in source mode which uses caller's return addresses logged to let you replay your events in the order of logging, modifying the current focus of the debugger so that you "see" your program being replayed.

Using Program Control

You can obtain maximum control of logging by using the package Event_Log_Manager in your actual program. Event_Log_Manager is packaged in the subsystem rts_trace.ss. You need to add a view of this subsystem to your Imports. The source of the package specification is to be found in Event_Log_Manager.1.ada

Event_Log_Manager supports the control of logging, allowing you to enable or disable logging of events, specify one or more log files, open or close these log files, and obtain event data. Event_Log_Manager depends on the packages v_i_trace.1.ada and v_i_krn_trace.1.ada which are in the rational.ss subsystem. These packages specify the event names, the event record format and a user configuration format.

Events are logged in a common event buffer, by a common logging routine. The default address and size of the event buffer can be overridden by the user.

The simplest use of event logging is to add the following statements to your program.

In the context clauses:

Where you wish to start logging:

Where you wish to stop logging:

Note that the routines Start_All_Logging and Stop_All_Logging can also be used. These routines combine the enable/start functions.

These statements cause runtime events to be collected in the default event buffer. When the buffer fills, it is filled from the start again (that is, it is treated as a circular buffer). The flag, V_I_Trace.Log_Overflowed, is set to True. You can browse these events from the debugger.

As described in the debugger documentation, the events can be saved to a file from the debugger. If you want to control the file name, or to run without the debugger, add the following (or similar) statements to your program.

Before logging starts (or after it completes):

After logging completes:

Package Event_Log_Manager offers a number of other control subprograms, e.g., the ability to support several log files, to delete files or to interpret your own events.

Package V_I_Trace contains a configuration table which enables you to customize the event collection. This table is an optional input to the subprogram:

Init_Logging can be called in 2 different ways.

1 . The procedure Trace.Start_Tracing is called during runtime startup. If you are using apex_trace_driver, a configuration table is passed to Init_Logging, otherwise a null pointer is passed and default setup is done. The call to V_I_Trace.Init_Logging is equivalent to a call to Event_Log_Manager.Event_Logging.

2 . Alternately, you can call it with a configuration table of your own to override default settings. This should be done while events are not being collected, that is, before event collection is enabled. One advantage of this is that you do not get events from run-time and user program elaboration if you do not want them.

The declaration of the configuration table is shown below:

It offers you the ability to do the following:

1 . Automatically enable runtime event collection.

2 . Specify an alternate size for the event buffer. If you do not supply an address, a buffer will be allocated from the heap.

3 . Specify an address for the event buffer.

4 . Specify whether collection should wrap around to the start of the buffer when it is full, or whether it should stop when the index points past the end of the buffer. The default behavior is to wrap around.

5 . Specify a callout routine to handle a nearly full buffer.

6 . Specify the event buffer index at which the callout routine is to be called.

7 . Specify an alternate function to handle time measurement. The specification should match:

8 . Disable locking of the event buffer. Could be used in a single processor runtime, which does not use interrupts or time-slicing, to reduce the overhead of logging.

9 . Specify your own event logging routine. You will have to organize your own buffering and wrap around.

The specification should match

Callout Routines

You should note that the callout routines are called from within the kernel. They can only execute a very limited number of things. In particular, they cannot:

You should declare all variables used by the callout program at the library level (in a package's outer level).

Buffer Handling

If you want to analyze your own event buffers in the same program that collects the data, you can avoid having to save the buffers to disk and then reading them in again.

Buffer handling is implemented using the following subprograms.

Open_Buffer

Sets up read pointers. You can specify an alternative buffer or buffer size. If no arguments are supplied, the default buffer is accessed.

Returns false while records are unread.

Read_Log_Event_From_Buffer

Reads the next event. A version of this routine allows you to specify the index in the buffer if you do not wish to read serially.

Reset_Buffer

Resets pointers so that future data collection starts with new data


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS