File: @(#)r3fiREADME.txt 1.2 - 03/18/02 PROGRAM: r3finst - Recon3 Fortran 77 instrumentor SYNOPSIS: Instruments a single Fortran source file by inserting calls to functions in file r3fisubs.f. When executed, the instrumented program will produce traces of execution which may be analyzed by other tools in the Recon toolset. See the Recon2 and Recon3 web sites at: http://www.cs.uwf.edu/~recon for more information about how to use the different tools in the toolset. In accepting and using Recon you agree to the Disclaimer of Warranty posted on that web site. USAGE: r3finst source dest [-bder] [-v[level]] where: source - is the path of the Fortran source file dest - is the path where the instrumented copy should be written bder - flags, in any combination, giving the kinds of instrumentation to perform: b - basic blocks; d - decisions; e - subprogram entry; r - subprogram return The default is '-ber' level - verbosity level for messages, cumulative: 0 = only produce messages on fatal errors 1 = write a final message indicating successful instrumentation - THE DEFAULT 2 = write progress and warning messages 3 = write debug information, intermediate data DESCRIPTION: r3finst copies the file at the path specified by "source" to the path specified by "dest". For example the command: r3finst /convert3/foo.f /convert3inst/foo.f -b will copy the file foo.f from the /convert3 directory to the /convert3inst directory, inserting instrumentation on each basic block as it copies. The source file is not changed. Instrumentation consists of calls to functions in r3fisubs.f. The flags control the kinds of instrumentation to be inserted. When compiling the instrumented source program, the following must be observed: 1. The file r3ficomm.f must be available in the same directory as the instrumented code. If there are several directories, you may need to put a copy in each directory. 2. The subroutines in r3fisubs.f must be available to your Fortran compiler. You may do this by either: - copying r3fisubs.f to the directory with the instrumented code and telling your compiler to compile it and link it with your target program. - insert all of r3fisubs.f at the end of one of your instrumented files. Compile your instrumented target program following whatever procedure your compiler requires. Compilation produces an instrumented target executable. Run the instrumented target executable. Each time you run it it will produce a file named "unknown.r2t" with a trace of execution. You will normally want to rename this file immediately to something meaningful. The trace records are in the format expected by the Recon2 analysis tool r2analyz. See the user manual available on the Recon2 web site for information on the file format and on how to use that tool. When instrumenting a large system, r3finst will need to be called many times to instrument all the files. The user may want to use our Instrumentation Script Builder (ISBuilder) tool, a simple Java program that walks a directory structure creating a script file or batch file of instrumentation commands. KNOWN BUGS OR LIMITATIONS: 1. Only handles "fixed source form" and Fortran 77. r3finst only handles programs in traditional Fortran "fixed source form" with 72 column records, specific columns for statement and comment identifiers, etc. 2. Basic block following a logical IF not instrumented. If using basic block instrumentation, a call to R3BLOC should be inserted at the beginning of each sequence of straight line code. However the following code: ------- 150 IF (IFLU.NE.2.OR.IFLL.NE.1) GO TO 160 CALL INFLUE (N, N1) CALL THREAD(N) 160 IF(ISQADD.GT.0) ISQADD = ISQ(N) ------- is instrumented as: ------- 00150 IF ( IF LU .NE. 2. OR . IF LL .NE. 1 ) THEN CALL R3BLOC ( R3PATH , 1 ) GOTO 160 ENDIF CALL INFLUE ( N , N1 ) CALL THREAD ( N ) 00160 IF ( ISQADD .GT. 0 ) THEN CALL R3BLOC ( R3PATH , 4 ) ISQADD = ISQ ( N ) ENDIF ------- so that the basic block beginning at CALL INFLUE (N, N1) is not instrumented. 3. Two basic blocks on one line are not distinguished. As required for compatibility with r2analyz, basic blocks are identified by file name and line number. However the following code has two basic blocks on one line; the IF and the following statement: ------ 150 IF (X.EQ.1) GO TO 160 ------ It is instrumented as: ------ 00150 CALL R3BLOC ( R3PATH , 1 ) IF ( X .EQ. 1 ) THEN CALL R3BLOC ( R3PATH , 1 ) GOTO 160 ENDIF ------ Both blocks are instrumented, but the same line number (1) is used so that the trace file does not distinguish which of the two was executed. This may make it impossible for r2analyz to locate correctly a functionality that is associated with one, but not the other, of the two blocks. 4. Does not handle "H" format correctly r3finst does not process correctly FORMAT statements containing the (mostly obsolete) "H" format. SEE ALSO: r3uisbREADME.txt - README file for the ISBuilder program The following documentation used by the Recon3 development team provides detailed specifications which may be useful: r3uarch.htm - The Architecture of Recon3. Provides an overall description of the toolset, its design criteria, the relationships between the different tools, the different architectures (Basic, Extended, etc.), the different kinds of program events which may be traced, trace record and file formats in different modes, etc. r3csrs.htm - Recon Instrumentor for C/C++ - SRS. Provides a detailed Software Requirements Specification (SRS) for the Recon3 C/C++ instrumentor (r3cinst). r3ctsrs.htm - Recon3 C/C++ Trace Manager - SRS Provides a detailed Software Requirements Specification (SRS) for the Recon3 C/C++ trace manager (r3ctmc). r3fisrs.htm - Recon Instrumentor for FORTRAN - SRS Provides a detailed Software Requirements Specification (SRS) for the Recon FORTRAN instrumentor.