Recon3 C/C++ Trace Manager - SRS

@(#)r3ctsrs.htm 1.4 - 02/12/04

Table of Contents:


1.0 Introduction
1.1 Purpose
1.2 Scope
1.3 Definitions, Acronyms and Abbreviations
1.4 References
1.5 Overview
2.0 General Description
2.1 Product Perspective
2.2 Product Functions
2.3 User Characteristics
2.4 General Constraints
2.5 Assumptions and Dependencies
3.0 Specific Requirements
3.1 Functional Requirements
3.1.1 Trace Manager Interface Functions - Basic Architecture
3.1.2 Trace Manager Interface Functions - Extended and Distributed Architectures
3.1.3 Trace Manager Client Functions - Extended Architecture
3.1.4 Trace Manager Client Functions - Distributed Architecture
3.1.5 Trace Manager Server Functions - Distributed Architecture
3.1.6 Conversion Utility Functions
3.2 External Interface Requirements
3.2.1 Choice of Platform and Architecture
3.2.2 Compilation of the Trace Manager Interface
3.3 Performance Requirements
3.4 Design Constraints
3.5 Attributes
3.6 Other Requirements
Appendixes

Figures


Figure 1 - Top-Level DFD for r3ctm and r3uanc
Figure 2 - DFD for r3ctm in the Basic Architecture
Figure 3 - DFD for r3ctm in the Extended Architecture
Figure 4 - DFD for r3ctm in the Distributed Architecture

Tables


Table 1 - Trace Event C Function Prototypes
Table 2 - Trace Command C Function Prototypes
Table 3 - R3ctmc Trace Commands
Table 4 - R3ctmc Diagnostic Commands
Table 5 - Files Needed to Compile r3ctmi

1.0 Introduction

1.1 Purpose

This document gives the requirements for the C/C++ language versions of the Recon3 Trace Manager (r3ctm) which includes the Trace Manager Interface (r3ctmi), Trace Manager Client (r3ctmc), and Trace Manager Server (r3ctms). It also provides a sketch of a Conversion Utility (r3uanc) used for backwards compatibility with the Recon2 analysis program. The document is intended as a guide for developers, testers and maintainers of these components.

1.2 Scope

The C/C++ Trace Manager (r3ctm) is part of the Recon3 tool set for the dynamic analysis of software. The reader of this SRS should first read [AR3] for many of the general concepts and terminology of Recon3.

[Note that only the basic architecture and extended architecture versions of the Trace Manager are specified at this time. Functionalities and components appearing only in the distributed architecture are mentioned only as placeholders for future development.]

The components described here are:

1.3 Definitions, Acronyms and Abbreviations

Block, Decision, Subroutine Entry and Subroutine Return

See [AR3 section "Trace Events"] for definitions of these different kinds of trace event.

Instrumentation Statements, Instrumented Target Program, Target Program, Trace Event

See [AR3 section "Definitions, Acronyms and Abbreviations"]

Trace Mode: immediate, subroutine, order, count

See [AR3 section "Trace Modes"]

Basic Architecture, Extended Architecture, Distributed Architecture

See [AR3 section "Definitions, Acronyms and Abbreviations"]

Trace Record

See [AR3 section "Definitions, Acronyms and Abbreviations"]

Trace Collection Process

A trace manager client process initiated with the r3ctmc start command, that continues execution to collect trace records placed in shared memory by the instrumented target program.

Trace Control Process

A trace manager client process initiated with one of the trace control commands other than r3ctmc start, that typically changes one of the tracing configuration parameters and then exits.

1.4 References

[AR3]

"The Architecture of Recon3" Norman Wilde, Laura White, Aaron Tarnosky

1.5 Overview

This SRS follows roughly the ANSI/830 standard. Section 2 gives an overview of each of the components and its functional and other requirements. Section 3 gives the requirements more specifically.

Terms defined in section 1.3 will appear in emphasis, like this.

Where appropriate, program names, file names, and C/C++ language constructs will appear in CODE format like this.

[Brief explanations for certain requirements are given in block quotes like this one.]

2.0 General Description

2.1 Product Perspective

2.1.1 Background and Data Flow Diagrams

The C/C++ Trace Manager (r3ctm) and the Conversion Utility (r3uanc) are components of Recon3 [AR3]. Recon3 is a collection of tools to facilitate dynamic software analysis though instrumentation. Instrumentation statements may be introduced into the target program by the programmer manually or by using Recon3's instrumentors for C/C++. (FORTRAN, Ada, and Java instrumentors will also be available.) The programmer compiles the instrumented target program and runs it. The instrumentation produces traces of execution which are then analyzed using Software Reconnaissance or other techniques. (See Figure 1 of [AR3] for a block diagram showing the general flow of Recon3.)

Figure 1 - Top-Level DFD for r3ctm and r3uanc

Figure 1 is a Data Flow Diagram overview of r3ctm and r3uanc. Figures 2 through 4 are Data Flow Diagrams showing the relationships of the components of r3ctm for the basic, extended, and distributed architectures.

Figure 2 - DFD for r3ctm in the Basic Architecture

2.1.2 A Scenario for the Basic Architecture

Here is a typical scenario for using r3ctm in the basic architecture under Win32. (See also Figure 2).

  1. The user has previously obtained a version of Recon3 for the basic architecture for the Win32 platform. (One way to do this is to obtain the source code, edit the file r3.h to uncomment #define statements that select the platform and architecture, and then compile.)
  2. The user has previously instrumented his C/C++ target program, possibly using one of the Recon3 instrumentors and/or hand instrumentation.
  3. The default trace configuration parameters, such as the trace file name, the trace mode, and the types of trace events are established in the file r3ctminf.h. The user may have modified them before compiling the instrumented target program by editing this file.
  4. The user compiles his instrumented target program along with files r3ctminf.c, r3ctminf.h, and r3.h and links to create the instrumented target executable.
  5. The user starts a test run of the instrumented target executable program in one window. As it executes, the instrumentation statements make calls to r3ctmi trace event functions. These functions immediately open the trace file and write a record for each trace event.
  6. Tracing continues until a call to R3TmiClose() is encountered or until the instrumented target executable exits normally, (in which case the operating system closes the trace file.)
  7. After each test run the user renames the trace file to something meaningful.
  8. When the user has several trace files, he uses the r3uanc conversion utility to convert them to Recon2 format, and then runs the Recon2 r2analyz analysis program to locate a functionality.

Figure 3 - DFD for r3ctm in the Extended Architecture

2.1.3 A Scenario for the Extended Architecture

Here is a typical scenario for using r3ctm in the extended architecture using count mode under Win32. (See also Figure 3).

  1. The user has previously obtained a version of Recon3 for the extended architecture for the Win32 platform. (One way to do this is to obtain the source code, edit the file r3.h to uncomment #define statements that select the platform and architecture, and then compile.)
  2. The user has previously instrumented his C/C++ target program, possibly using one of the Recon3 instrumentors and/or hand instrumentation.
  3. The default trace configuration parameters, such as the trace file name, the trace mode, and the types of trace events are established in the file r3ctminf.h. The user may have modified them before compiling the instrumented target program by editing this file. In this particular scenario, he has edited the file to select count mode.
  4. The user compiles his instrumented target program along with files r3ctminf.c and r3ulbsys.c and links to create the instrumented target executable.
  5. The user starts execution of the instrumented target executable program in one window. As it executes, the instrumentation statements make calls to r3ctmi trace event functions, but these calls have no effect since the trace manager client has not yet started and the shared memory is not yet created.
  6. The user starts the trace manager client r3ctmc trace collection process in another window using the following command: 
    r3ctmc start config.txt
    R3ctmc immediately reads the trace configuration file config.txt named on the command line, to modify the initial trace configuration parameters. It creates the shared memory and opens a trace file.
  7. As the instrumented target program continues execution the calls to the r3ctmi trace event functions now cause trace records to be written to the "records" buffer in shared memory.
  8. The r3ctmc trace collection process takes the records from shared memory and accumulates them in internal data structures (balanced tree).
  9. At the end of each trace frame the r3ctmc trace collection process dumps the trace information from its internal data structures into the trace file.
  10. As tracing progresses, the user can use a third window to give r3ctmc trace commands to change to another trace file, to change trace mode, etc. Each command starts an r3tmc trace control process which either changes the configuration parameters in the shared memory directly, or else puts a trace record in shared memory so that the trace collection process will make the change when it next processes shared memory. The trace control process exits as soon as its job is done.
  11. When the user has several trace files, he uses the r3uanc conversion utility to convert them to Recon2 format, and then runs the Recon2 r2analyz analysis program to locate a functionality.

Figure 4 - DFD for r3ctm in the Distributed Architecture (Preliminary)

2.1.4 A Scenario for the Distributed Architecture

[Distributed architecture functions are not specified at this time.]

2.2 Product Functions

2.2.1 Trace Manager Interface Functions - Basic Architecture

The r3ctmi code is compiled and linked with the instrumented target program, and provides two groups of functions which are called from the that program:
  1. Trace event functions write trace records to the trace output file for each event.
  2. Trace control functions allow for tracing to be suspended and resumed.

2.2.2 Trace Manager Interface Functions - Extended and Distributed Architectures

The r3ctmi code provides the same functions in the extended and distributed architectures, except that instead of writing trace records directly to the trace output file, they are written to shared memory to be read by r3ctmc.

2.2.3 Trace Manager Client Functions - Extended Architecture

The Trace Manager Client r3ctmc is called from the operating system command line. It provides functions for:
  1. Startup of the trace manager client, trace collection, and writing of the trace to the trace output file
  2. Trace control, to change trace parameters as tracing progresses and to shutdown tracing.

2.2.4 Trace Manager Client Functions - Distributed Architecture

[Distributed architecture functions are not specified at this time.]

2.2.5 Trace Manager Server Functions - Distributed Architecture

[Distributed architecture functions are not specified at this time.]

2.2.5 Conversion Utility Functions

The r3uanc conversion utility converts Recon3 trace files to Recon2 trace file format.

2.3 User Characteristics

The user is expected to be an experienced programmer. He will be familiar particularly with how to compile and run the target program.

2.4 General Constraints

It is important that the Recon3 C/C++ Trace Manager should be usable on as wide a variety of platforms as possible. The three architectures basic, extended, and distributed are intended to provide wide flexibility. See [AR3] for a description of these architectures and the platforms each must support.

While it is not possible to provide a quantifiable performance requirement, efficiency is very important for the Recon3 C/C++ Trace Manager because inefficiency may limit its potential applications. If the instrumented target program executes too slowly, users will not be able to use Recon3 except in very limited ways. Trace control functions are provided to let the user suspend and resume tracing and control the events and files to be traced (See 3.1.1.2 and 3.1.3.3). When tracing is disabled, it is especially important that little trace overhead is introduced.

In general developers are urged to take efficiency into account at all points.

2.5 Assumptions and Dependencies

None.

3.0 Specific Requirements

3.1 Functional Requirements

3.1.1 Trace Manager Interface Functions - Basic Architecture
3.1.1.1 Trace Event Functions
3.1.1.1.1 Introduction
The instrumented target program will call one or more of the functions listed in Table 1 to record a trace event.
3.1.1.1.2 Inputs
One of the functions in Table 1 is called from the instrumented target program.
3.1.1.1.3 Processing
If this is the first call to a trace event function, the trace file is created, using the file name that was specified in r3ctminf.h when the instrumented target program was compiled. In all cases a record of the appropriate type is written to the trace file.
3.1.1.1.4 Outputs
A trace record is written to the trace trace file. See [AR3] for the record format.

Trace Event Function Prototype
Comment void R3TmiComment(char *text);
text - User specified comment text.
Block void R3TmiBlock(char *filename, int start_line, int end_line);
filename   - Name of the source file in which the trace event occurred.
start_line - Source file line number at the beginning of the block.
end_line   - Source file line number at the end of the block.
Decision (True) int R3TmiTrue(char *filename, int line); return(1);
filename - Name of the source file in which the trace event occurred.
line     - Source file line number at which the trace event occurred. 
Decision (False) int R3TmiFalse(char *filename, int line); return(0);
filename - Name of the source file in which the trace event occurred.
line     - Source file line number at which the trace event occurred. 
Decision (Switch) int R3TmiSwitch(char *filename, int line, int value); return(value);
filename - Name of the source file in which the trace event occurred.
line     - Source file line number at which the trace event occurred. 
value    - Value of the switch decision.
Subroutine (Entry) void R3TmiEntry(char *filename, int line, char *function);
filename - Name of the source file in which the trace event occurred.
line     - Source file line number of the function entry point.
function - Name of the function in which the trace event occurred.
Subroutine (Return) void R3TmiReturn(char *filename, int line, char *function);
filename - Name of the source file in which the trace event occurred.
line     - Source file line number of the return statement.
function - Name of the function in which the trace event occurred.
Task (Start) void R3TmiStart(char *filename, int line, char *text);
filename - Name of the source file in which the trace event occurred.
line     - Source file line number at which the trace event occurred. 
text     - User specified text.
Task (Rendevous) void R3TmiRendevous(char *filename, int line, char *text);
filename - Name of the source file in which the trace event occurred.
line     - Source file line number at which the trace event occurred. 
text     - User specified text.
Task (Stop) void R3TmiStop(char *filename, int line, char *text);
filename - Name of the source file in which the trace event occurred.
line     - Source file line number at which the trace event occurred. 
text     - User specified text.
User void R3TmiUser(char *filename, int line, char *text);
filename - Name of the source file in which the trace event occurred.
line     - Source file line number at which the trace event occurred. 
text     - User specified text.
Exit int R3TmiExit(char *filename, int line, int value); return(value);
filename - Name of the source file in which the trace event occurred.
line     - Source file line number at which the trace event occurred. 
value    - Value of the exit code.
Table 1: Trace Event C Function Prototypes

3.1.1.2 Trace Command Functions
3.1.1.2.1 Introduction
The instrumented target program may call the functions listed in Table 2 to control tracing.
3.1.1.2.2 Inputs
One of the functions in Table 2 is called from the instrumented target program.
3.1.1.2.3 Processing
The action indicated in Table 2 is taken.
3.1.1.2.4 Outputs
None.

Trace Command Function Prototype Action Taken
Suspend void R3TmiSuspend(void); Writing of trace records is suspended until R3TmiResume() is called.
Resume void R3TmiResume(void); Tracing is resumed.
Table 2: Trace Command C Function Protoypes

3.1.2 Trace Manager Interface Functions - Extended and Distributed Architectures

3.1.2.1 Trace Event Functions
As in the basic architecture, the instrumented target program will call one or more of the functions listed in Table 1 to record a trace event. (See 3.1.1.1.) In the extended architecture, the trace record is written to shared memory. (It is later read by the trace manager client r3ctmc trace collection process as described in 3.1.3.)
3.1.2.2 Trace Command Functions
As in the basic architecture, the instrumented target program may call the functions listed in Table 2 to control tracing. (See 3.1.1.2.)

3.1.3 Trace Manager Client Functions - Extended Architecture
3.1.3.1 Startup and Trace Collection
3.1.3.1.1 Introduction
The trace manager client trace collection process is started and begins collecting trace records from shared memory.
3.1.3.1.2 Inputs
The trace manager client is started by giving the r3ctmc start command described in Table 3.
3.1.3.1.3 Processing
  1. A r3ctmc trace collection process is started.
  2. Shared memory is created so that r3ctmi trace event functions have somewhere to write to.
  3. The initial trace parameters are set to determine the kinds of trace events, the source files to be traced, the trace mode, etc. The default values of these parameters were defined in r3ctminf.h when r3ctmc was compiled. The user shall be able to override the default paramaters in a configuration file read at startup. The name of the configuration file will either be set in r3ctminf.h or else will be specified as part of the r3ctmc start command.
  4. A trace output file is opened.
  5. The remaining processing is periodic:
    1. The trace collector process reads shared memory and either writes trace records immediately (immediate or subroutine trace mode) or stores records into internal data structures count and order trace modes. Note that if the trace mode is count, r3ctmc keeps just one record for each distinct event, and accumulates a count of the number of times the event has occurred in the trace frame. In trace modes immediate, subroutine or order, a record is written or stored for each time the event occurs.
    2. In count and order trace modes, a frame_delay timer controls writing to the trace file. Each time the timer expires, the internal data structrues are traversed and the corresponding records are written to the trace file.
    Processing of trace records continues until the r3ctmc stop trace control command is given (see 3.1.3.2).

Note that either the instrumented target program or the r3tmc trace collection process may start first.

3.1.3.1.4 Outputs
For each frame, a set of records is written to the trace file:
  1. An Overflow Record is the first record of each frame. It serves to mark the beginning of a frame and as well contains information that can help the user detect if records are being lost. (See [AR section "Overflow Record"].)
  2. Records follow for each trace event. The content and number depend on the trace mode. As noted below in section 3.1.3.2.4, comment records will also be present that echo trace control commands.

See [AR3] for the trace file format (trace records).

3.1.3.2 Trace Control
3.1.3.2.1 Introduction
Trace control commands may be given at any time after the "r3ctmc start" command has been given time to create the shared memory. These commands control processing in different ways.
3.1.3.2.2 Inputs
One of the commands given in Table 3 is given at the operating system command prompt.
3.1.3.2.3 Processing
  1. An r3ctmc trace control process is started.
  2. This process writes the trace control command to shared memory and exits. Some commands update the trace configuration parameters in the config section of shared memory immediately. Others, are written to the records section and are picked up and handled by the trace collection process on its next cycle. (See Figure 3).
3.1.3.2.4 Outputs
  1. Tracing is modified as described for each command in Table 3.
  2. A comment trace record containing the trace control command is placed in the output trace file.
    [The echoed trace command is provided to facilitate debugging and to help the user interpret the trace of execution]
3.1.3.3 Trace Manager Client User Interface

The trace manager client program command line usage will be similar to the one shown below: 

     r3ctmc <command> [parameter]
        command - trace command
        parameter - additional command information

Trace commands are shown in Table 3 and diagnostic commands in Table 4.
 
Command Parameter Description
comment <text> Generates a comment trace event.
delay <seconds> Sets the length of the trace frame in seconds. If the specified value is zero, the frame time will be infinite and the trace file will be written only when tracing terminates or when a newtrace or newframe command is given.
eventoff <a|bcdstux> Disables tracing for a particular type of trace event: a = all events, b = block, c = comment, d = decision, s = subroutine, t = task, u = user, x = exit.
eventon <a|bcdstux> Enables tracing for a particular type of trace event: a = all events, b = block, c = comment, d = decision, s = subroutine, t = task, u = user, x = exit.
filelist N/A Lists the name of each source file encountered so far and indicates whether tracing is enabled for the file. The list is written to the trace file as a series of comment records.
fileoff <file> Disables tracing for a particular source file. The file name must be exactly the same as that used in the instrumentation.
fileon <file> Enables tracing for a particular source file. The file name must be exactly the same as that used in the instrumentation.
itemoff <a|hpt> Disables logging of optional trace data items: a = all items, h = thread id, p = process id, t = time.
itemon <a|hpt> Enables logging of optional trace data items: a = all items, h = thread id, p = process id, t = time.
mode <c|i|o|s> Sets the trace mode. Exactly one character must be specified to indicate the mode type: c = count, i = immediate, o = order, s = subroutine.
newconfig <file> Loads a new trace configuration file. Default values will be used for configuration parameters not present in the file. If a file is not specified or cannot be opened, default values will be used for all configuration parameters.
newframe N/A Flushes the trace records from shared memory to internal data structures, writes the internal data structures to the trace output file, and initializes a new trace frame.
newtrace <file> Flushes the trace records from shared memory to internal data structures, writes the internal data structures to the current trace file, closes the current trace file, and creates a new trace file.
resume N/A Instructs the trace manager interface to examine all trace events and process those that are set to the enabled state.
start [file] Starts the trace manager and loads a configuration file. Default values will be used for configuration parameters not present in the file. If a file is not specified or cannot be opened, default values will be used for all configuration parameters.
stop N/A Stops the trace manager. All instrumented executables currently connected to the trace manager will detect this condition and automatically disconnect.
suspend N/A Instructs the trace manager interface to ignore all trace events until a resume command is given.
Table 3: R3ctmc Trace Commands
Command Parameter Description
buffersize N/A Writes to standard error the maximum number of records that can be stored in the trace record buffer in shared memory, and the size of the buffer in megabytes
configlist [totrace] Lists the names and values of several trace configuration parameters. If no parameter is specified, the information will be written to standard output. If the totrace parameter is specified, the information will be written to the trace file as a series of comment records.
countoff N/A Disables display of record counts.
counton N/A Turns on display of record counts.
help <command> Writes usage information on a command to standard error
rmipc N/A Destroys all semaphores and shared memory associated with the trace manager.
Table 4: R3ctmc Diagnostic Commands

3.1.4 Trace Manager Client Functions - Distributed Architecture

[Distributed architecture functions are not specified at this time.]

3.1.5 Trace Manager Server Functions - Distributed Architecture
[Distributed architecture functions are not specified at this time.]

3.1.6 Conversion Utility Functions

 To maintain backward compatibility with the Recon2 trace analyzer, the r3uanc a utility program converts the Recon3 trace output file format to the older Recon2 format. Trace events that are not supported by Recon2 will be written out as a TRUE decision event. The utility program command line usage will be similar to the one shown below: 
     r3uanc <source> <destination>
       source - input trace file in Recon 3 format
       destination - output trace file in Recon 2 format

     NOTES: If a hyphen (-) is specified for the source file
            name, input will be read from the standard input device.
            If a hyphen (-) is specified for the destination file
            name, output will be written to the standard output device.

3.2 External Interface Requirements

3.2.1 Choice of Platform and Architecture

 Recon3 will normally be distributed as C code in source form, though precompiled versions may also be made available. The user selects the platform (e.g. Win32, Posix, etc.) and architecture (e.g. basic, extended, distributed) when compiling Recon3 by defining appropriate macros. The definition may be done either on the compile command line (or in the users development environment) or by uncommenting the appropriate macro definitions in the file r3.h.

For further information consult the comments in r3.h.

3.2.2 Compilation of the Trace Manager Interface

The trace manager interface must be compiled and linked with the user's instrumented target program. The files needed for compilation are given in Table 5.
Architecture Needed Files
Basic r3.h, r3ctminf.h, r3ctminf.c
Extended r3.h, r3ctminf.h, r3ctminf.c, r3ulbsys.h, r3ulbsys.c
Distributed [Distributed architecture functions are not specified at this time.]
Table 5: Files Needed to Compile r3ctmi

During this process, initial trace configuration parameters may be set by modifying the file r3ctminf.h.

[This means of controlling the trace is provided as an alternative to the configuration file loaded when the r3ctmc start command is given and to the other r3ctmc trace control commands mentioned earlier since for some environments and target programs r3ctmc may not be useable.]

3.3 Performance Requirements

See section (2.4).

3.4 Design Constraints

See section (2.4).

3.5 Attributes

For maximum portability and to facilitate maintenance, the C/C++ Trace Manager components shall be implemented using ANSI standard C, and using non-ANSI operating system functions only where essential, for example to implement shared memory.

3.6 Other Requirements

None

Appendixes

None