fpt and WinFPT Reference Manual - Command-line Commands

| SimCon Home | Ref Manual Home |

INSERT COVERAGE MONITOR

Syntax:

INSERT COVERAGE [MONITOR]

Recommended Usage:

Add a reference to the fsp file FPTMAIN:coverage.fsp on the command line or in the fsp file for the program to be processed. This fsp file contains the command %insert coverage monitor and also adds the service routines which handle the arrays and files which receive the measurements. Do not write this as the first file on the command line. The first fsp file referenced is used to determine the name of some of the output files.

Function:

This command is used to instrument the user's code to measure coverage. fpt measures the number of times each executable statement is visited, and the proportion of executable statements visited, when the code is run.

fpt divides the user's program into sequences of statements. A sequence of statements is defined so that if any member of the sequence is executed then all members of the sequence are executed. Consider the code:

1 FUNCTION SUMLIS(AR) 2 REAL AR(*) 3 I=1 4 SUMLIS=0 5 DO WHILE (AR(I) .GT. 0.0) 6 SUMLIS=SUMLIS+AR(I) 7 I=I+1 8 ENDDO 9 RETURN 10 END FUNCTION SUMLIS

In this code, statements 1,3 and 4 make up the first sequence, statement 5 the second, statements 6, 7 and 8 make up the next and statement 9 makes up the last.

fpt generates a database file with the same base name as the main input file, and the file name extension .cvd, which describes the sequences. The file for the fragment above, for example, contains:

Sequence: 1, 2 executable statements at Line: 1 File: e:\projects\fpt\fpttest\t.for Notes: None FUNCTION SUMLIS(AR) Sequence: 2, 1 executable statement at Line: 5 File: e:\projects\fpt\fpttest\t.for Notes: None DO WHILE (FPT_COVERAGE_INCREMENT_L4( 1 C_FPT_COVERAGE_TABLE(2),(AR(I) .GT. 0.0))) Sequence: 3, 3 executable statements at Line: 6 File: e:\projects\fpt\fpttest\t.for Notes: None SUMLIS=SUMLIS+AR(I) Sequence: 4, 1 executable statement at Line: 9 File: e:\projects\fpt\fpttest\t.for Notes: None RETURN

This file is readable, and may be used as a reference to investigate sequences which are unexpectedly visited or skipped.

fpt modifies the code to count the number of times each sequence is executed during program execution. The modified code is, for example:

FUNCTION sumlis(ar) ! INCLUDE 't_cvc.fpi' ! REAL ar(*) ! c_fpt_coverage_table(1)=c_fpt_coverage_table(1)+1 i=1 sumlis=0 DO WHILE (fpt_coverage_increment_l4( & c_fpt_coverage_table(2),(ar(i).gt.0.0))) c_fpt_coverage_table(3)=c_fpt_coverage_table(3)+1 sumlis=sumlis+ar(i) i=i+1 ENDDO c_fpt_coverage_table(4)=c_fpt_coverage_table(4)+1 RETURN END FUNCTION sumlis

The array fpt_coverage_table is declared with appropriate bounds in the INCLUDE file t_cvc.fpi which is generated automatically. The base file name is taken from the main input file, with the suffix _cvc and the current default INCLUDE file name extension.

Calls to the subroutines fpt_coverage_init and fpt_coverage_record are inserted at the start of each main program and at all points of program termination respectively. fpt_coverage_init initialises the array c_fpt_coverage_table and fpt_coverage_record writes the table to file. These subroutines reside in the file fpt_cvge.for in the fpt library directory, fpt_lib. They are inserted automatically in the fpt pass if the fsp file fptmain:coverage.fsp is referenced in the fpt run. This fsp file also contains the command % insert coverage monitor. This is the recommended way of using the command. If fpt_cvge.for is not processed by fpt with the program, the INCLUDE files for fpt_coverage_table will not be set up correctly.

Note the treatment of the statement

DO WHILE (ar(i).GT.0.0)

which is modified to read

DO WHILE (fpt_coverage_increment_l4( & c_fpt_coverage_table(2),(ar(i).gt.0.0)))

A difficulty with DO WHILE and ELSEIF statements is that there is no position outside the statement at which a monitor can be inserted. A function invocation is therefore inserted around the logical expression which returns the value of the expression and increments the coverage counter.

By default, every visit to each sequence is recorded in the coverage table. In long runs on fast machines, this could overflow the 32 bit integers used to store the data. The generated code may be modified by the command MAXIMUM COVERAGE COUNT to check for and to avoid overflow. For example, specifying:

% maximum coverage count: 999

generates statements of the form:

c_fpt_coverage_table(1)=MIN(c_fpt_coverage_table(1)+1,999)

fpt checks and reports 3 attributes which may be associated with each code sequence. These are listed in the notes section of the sequence descriptions in the coverage database files. They are:

1. Unreachable: fpt cannot find any path to the code sequence. It is never expected to be executed, but code is inserted to count visits in any case.
2. Unmarkable: There is no point at which fpt can insert a statement to monitor execution of the sequence. This usually happens with single statements such as CASE statement selectors and labelled arithmetic IF statements. The count will always be zero for these sequences.
3. Exception: The code is declared to be part of an exception handler by the directive % EXCEPTION inserted in the code, is reached only from an ERR= clause, or is reached only by paths from other exception handlers.

The coverage data file and the recording of coverage written by fpt_coverage_record, are marked with the name of the main input file used when fpt modified the code, and the date and time when the modification was made. The numbering of the code sequences depends on the way in which fpt was run, and the order and content of the input files. The data and time stamp is used to prevent inconsistent data from being collated in later analyses.

Coverage data may be displayed and collated by the utility program fpt_cvgm.exe. This is conveniently launched by the command fptcv_up. Please refer to the utilities section of this manual for a description of the procedure.

Where to Use this Command

Default

No change is made by default.

See Also

EXCEPTION

MAXIMUM COVERAGE COUNT

Copyright ©1995 to 2024 Software Validation Ltd. All rights reserved.