Recon Instrumentor for C/C++ - SRS

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.2.1 User Interface

2.2.2 File Instrumentation

2.3 User Characteristics

2.4 General Constraints

2.5 Assumptions and Dependencies

3.0 Specific Requirements

3.1 Functional Requirements

3.1.1 Command Line Interpreter Subfunction

3.1.2 File Instrumentor Subfunction

3.2 External Interface Requirements

3.2.1 Command Line Description

3.2.2 Source Code Format

3.2.3 Error Handling Policy

3.3 Performance Requirements

3.4 Design Constraints

3.5 Attributes

3.6 Other Requirements

Appendix A - Supported Trace Manager Subfunctions

Appendix B - Example of Instrumentation

Appendix C - Verification Cross-Reference Table

1.0 Introduction

This SRS states the requirements for the Recon Instrumentor for C/C++. It is intended as a guide for developers, testers, and maintainers of this software component.

The Recon3 Instrumentor for C/C++, r3cinst, is part of the Recon3 tool set for dynamic analysis of software [AR3] which is, in turn, a major upgrade and extension of the Recon2 software reconnaissance tool [Recon2].

The main benefit of r3cinst, when used with the Recon3 tool set, is to facilitate the understanding or debugging of C/C++ programs using techniques such as software reconnaissance [SR95].

This SRS follows the IEEE - STD - 830 - 1998 standard. Section 2 gives an overview of r3cinst and its functional and other requirements. Section 3 describes the requirements more specifically. Appendix A describes the Trace Manager subfunction calls that are included in the instrumentation statements. Appendix B gives an example of a Target Program and an Instrumented Target Program. Appendix C contains the Verification Cross-Reference Table which maps each specific requirement to the system-level test where it is verified.

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

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

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

r3cinst is the Recon3 Instrumentor for C/C++. It creates instrumented copies of C/C++ source files that are used by the Trace Manager. It does this by reading in a Target Program which is the C/C++ source code, inserting instrumentation statements, and writing the instrumented code to an output file, the Instrumented Target Program.

Figure 1 shows how r3cinst will work with other components of Recon3. The user invokes r3cinst using a command line interface. Each time it is invoked, r3cinst instruments one C/C++ source file. When the user has instrumented all (or a subset) of the C/C++ files making up his Target Program, he uses his C/C++ compiler to produce an executable from the Instrumented Target and the Trace Manager interface. This new executable is run with appropriate test data to exercise specific features of the program. For each test case, the Trace Manager creates a file of trace records detailing program branch path execution based on the Instrumentation Statements. These files are then input to the Trace Analyzer for comparison and the results of the analysis are output.

r3cinst instruments the Target Program by inserting subfunction calls to the Trace Manager interface into the Instrumented Target Program. These subfunction calls are inserted according to the switch set at the command line. These switches are uniform across the instrumentation programs for different languages. If the - e switch is used, r3cinst will insert instrumentation at the entry point of any function, including main(). If the - r switch is used, r3cinst will insert instrumentation whenever it encounters an explicit or an implicit RETURN. If the - x switch is set, r3cinst will insert instrumentation whenever it encounters an EXIT statement. If the - d switch is used, r3cinst will insert instrumentation whenever it encounters a Decision Construct. If a verbose level was entered at the command line, a progress message will display when the corresponding instrumentation level is processed.

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

To facilitate portability and maintainability r3cinst will be implemented using standard ANSI C [ANSI] to the greatest extent possible.

With respect to pre-ANSI C code, r3cinst shall only be capable of instrumenting decisions.

The instrumentation statements introduced by r3cinst consist of calls to the external subprograms in the TraceManager and must conform to the syntax specified in [TM SRS]. The subprogram calls supported by r3cinst are detailed in Appendix A.

None.

3.0 Specific Requirement

r3cinst has two main functions:

1. To interpret the command line input; and
2. To instrument the target file according to the command line input.

The Command Line Interpreter accepts command line entries and parses them to determine the source file, the destination file, and the instrumentation and verbosity levels desired by the user. It ensures that the source filename points to a valid Target Program. An output file is created for the Instrumented Target Program from the destination filename specified on the command line, or if a file of that name already exists, warns the user that the existing output file will be overwritten. It outputs usage instructions if the command line syntax is incorrect or file parameters are missing. The Command Line Interpreter also outputs error messages if a fatal error is encountered. The command line syntax is defined in section 3.2.1.

3.1.1.2 Processing

r3cinst shall [1] parse the command line arguments to determine the VERBOSITY, INSTRUMENTATION LEVEL, TARGET NAME and INSTRUMENTED TARGET NAME.

If a valid INSTRUMENTATION LEVEL is encountered, r3cinst shall [2] set the corresponding EVENT MASK.

If the VERBOSE SWITCH with a LEVEL OF VERBOSITY is specified, r3cinst shall [3] set the corresponding VERBOSITY LEVEL.

If an invalid switch is encountered, r3cinst shall [4] terminate execution and output USAGE INSTRUCTIONS.

If the VERBOSE SWITCH contains an invalid LEVEL OF VERBOSITY, r3cinst shall [5] terminate execution and output USAGE INSTRUCTIONS.

If no switches are specified in the command line, r3cinst shall [6] use the default settings for full instrumentation and no verbosity.

If a SOURCE FILENAME and/or DESTINATION FILENAME is not specified, r3cinst shall [7] terminate execution and output an ERROR MESSAGE.

If the SOURCE FILENAME is the same as the DESTINATION FILENAME, r3cinst shall [8] terminate execution and output an ERROR MESSAGE.

If the SOURCE FILENAME or DESTINATION FILENAME points to a file that cannot be opened, r3cinst shall [9] terminate execution and output an ERROR MESSAGE.

If a relative path is specified in the SOURCE FILENAME, r3cinst shall [10] output a WARNING.

If the file pointed to by the SOURCE FILENAME is successfully opened, r3cinst shall [11] output TARGET NAME.

If the file pointed to by the DESTINATION FILENAME is successfully opened, r3cinst shall [12] output INSTRUMENTED TARGET NAME.

3.1.1.3 Output

3.1.2 File Instrumentor Subfunction

The File Instrumentor inserts instrumentation into the Instrumented Target File when it encounters specific types of statements and constructs and the appropriate flag has been set from the command line arguments. These Instrumentation Statements are calls to subprograms within the Trace Manager interface and must conform to the syntax defined in [TM SRS]. The Trace Manager subfunctions supported by r3cinst are detailed in Appendix B. Function entries are instrumented at the first open brace in the function. Function returns are instrumented at the keyword RETURN for explicit RETURNs. Implicit RETURNs are instrumented just before the last closing brace in a function. Alternate RETURNs are distinguished by the inclusion of line numbers in the instrumentation. Function exits are instrumented at the keyword EXIT.

In general, decisions are instrumented by inserting subprogram calls appropriate to the value of the logical expression. For example, at the TRUE branch of an IF statement, a call to R3TmiTrue would be inserted. To cover the FALSE branch, a call to R3TmiFalse would be inserted. In the case of a switch statement, a call to R3TmiSwitch is inserted and the integer value of the case variable is passed as one of the parameters. r3cinst will insert instrumentation for the following Decision Constructs:

1. A FOR statement,
2. A WHILE statement,
3. An IF statement or an IF ELSE construct, and
4. A SWITCH statement

If a verbose level was specified at the command line, a progress message is sent to standard output when the corresponding instrumentation level is processed.

When r3cinst encounters statements that are not specified in the requirements in para 3.1.1.2 and para 3.1.2.2, it will copy them to the Instrumented Target Program with as few changes as possible.

3.1.2.1 Input

3.1.2.2 Processing

r3cinst shall [1] write the prototypes for the Trace Manager interface to the top of the INSTRUMENTED TARGET PROGRAM.

When EVENT MASK is set to DECISION and an IF or IF ELSE decision construct is encountered, r3cinst shall [2] write DECISION INSTRUMENTATION to the INSTRUMENTED TARGET PROGRAM.

When EVENT MASK is set to DECISION and a WHILE decision construct is encountered, r3cinst shall [3] write DECISION INSTRUMENTATION to the INSTRUMENTED TARGET PROGRAM.

When EVENT MASK is set to DECISION and a FOR decision construct is encountered, r3cinst shall [4] write DECISION INSTRUMENTATION to the INSTRUMENTED TARGET PROGRAM.

When EVENT MASK is set to DECISION and a SWITCH decision construct is encountered, r3cinst shall [5] write DECISION INSTRUMENTATION to the INSTRUMENTED TARGET PROGRAM.

When EVENT MASK is set to ENTRY and a function entry is encountered, r3cinst shall [6] write ENTRY INSTRUMENTATION to the INSTRUMENTED TARGET PROGRAM.

When EVENT MASK is set to RETURN and an explicit return is encountered, r3cinst shall [7] write RETURN INSTRUMENTATION to the INSTRUMENTED TARGET PROGRAM.

When EVENT MASK is set to RETURN and an implicit return is encountered, r3cinst shall [8] write RETURN INSTRUMENTATION to the INSTRUMENTED TARGET PROGRAM.

When EVENT MASK is set to EXIT and an exit statement is encountered, r3cinst shall [9] write EXIT INSTRUMENTATION to the INSTRUMENTED TARGET PROGRAM.

r3cinst shall [10] output PROGRESS INDICATORS to standard output according to the VERBOSITY specified.

3.1.2.3 Output

3.2 External Interface Requirements

To instrument a single source file, the user invokes r3cinst using a command line of the following form:

r3cinst [-derx][-v[level]]source dest

where source is the path of the C/C++ source file to be instrumented, and dest is the path for the instrumented copy of the source file. The instrumentation flags 'd', 'e', 'r' and 'x' may be present in any combination to indicate the kinds of statements and constructs to be instrumented:

If no instrumentation flags are specified, the assumed default is '-derx'.

The -v flag specifies the "verbosity level" for warning and progress messages. Each level builds on the preceding level. The levels of verbosity are:

If no verbosity level is specified, the default is '0'.

If the command line does not provide valid source and destination files, valid flags, and/or the proper number of arguments, a "usage" message is printed and r3cinst exits. The switches entered at the command line may be in any order.

The Target Program source file is expected to consist of one or more C/C++ functions. r3cinst will only process Target Programs that conform to the ANSI 92 C/C++ standard [ANSI]. Multiple statements on a line may not be instrumented correctly.

C/C++ implementations differ considerably; most compilers provide extensions that go beyond the language standards. A priority for r3cinst is that it should be usable for as many C/C++ programs as possible. Thus, if r3cinst encounters statements that it does not recognize, it will copy them to the Instrumented Target Program with as few changes as possible.

Error messages and warnings will be implemented according to the following general policy:

1. If r3cinst encounters an error that will probably impede it from producing a valid C/C++ program equivalent to the Instrumented Target Program, it will write a meaningful error message to standard output and exit.
2. If r3cinst encounters an input that is unrecognized, but that may not impede it from producing a valid C/C++ program equivalent to the Instrumented Target Program, it will write a warning to standard output.

r3cinst has no critical performance requirements. As a general guideline, the Developers should keep in mind that it is intended for use on large C/C++ programs on the order of tens of thousands of lines. The time required to instrument a file should not be significantly greater than the compile time for the same file in the same environment. It is expected that the Instrumented Target Program will compile and run in the same environment as the original Target Program.

See section (2.4).

3.5 Attributes

None.

3.6 Other Requirements

None.

Appendix A - Supported Trace Manager Subprograms

For a complete list of the subfunctions contained in the Trace Manager, see [TM SRS]. The Trace Manager subfunctions supported by r3cinst are:

Appendix B - Instrumentation Example

Target Program:

#include 

void ENT1(int x);
void ENT2(int x);

int main() 
{
  int Y = 10;
  ENT1(Y);
  ENT2(Y);

  return 0;
}

/* Function ENT1   */

void ENT1 (int X)
{   
  float PI = 3.14;
  float Result;

  Result = PI * X;
  printf("Result:  %f\n", Result);
}
      
/* Function ENT2  */
void ENT2(int X)

{
   float TWO_PI = 6.28;
   float Result;

   if (X = 10)
   {
    Result = Two_PI * X;
    printf("Result:  %f\n", Result);
   }

}

Instrumented Target Program:

#include "r3.h"
#include "r3tminf.h"
#static char *R3I_path="/usr/cs/r3/demo.c"

#include 

void ENT1 (int x);
void ENT2 (int x);

 int main()
 {int R3I_entry = R3TmiEntry(R3I_path,7,"main");

    int  Y = 10;
    ENT1(Y);
    ENT2(Y);

    {R3TmiReturn(R3I_path,12,"main");return 0;}
 R3TmiReturn(R3I_path,13,"main");}

 /* function ENT1 */

void ENT1 (int X)
{int R3I_entry = R3TmiEntry(R3I_path,18,"ENT1");
   float PI = 3.14;
   float Result;

   Result = PI * X;
   printf ("Result:  %f\n", Result);
 R3TmiReturn(R3I_path,24,"ENT1");}

 /* function ENT2 */

 void ENT2 (int X)
 {int R3I_entry = R3TmiEntry(R3I_path,29,"ENT2");
    float TWO_PI = 6.28;
    float Result;

    if ((X = 10)?R3TmiTrue(R3I_path,33):R3TmiFalse(R3I_path,33))
    {  Result = TWO_PI * X;
       printf ("Result:  %f\n", Result);
    }
R3TmiReturn(R3I_path,37,"ENT2");}