/ ========================================== \ || || || FCAT: FORTRAN Coverage Analysis Tool || || || || Version 1.0. Jan 2001. || || Dr. Yifan Hu || || || || || || Copyright: CLRC Daresbury Laboratory 2001 || || || \ ========================================== /
1. SUMMARY The FCAT tool is used for the Coverage Analysis of FORTRAN codes. This includes - finding out "cold-spot" in Fortran codes (the part of the codes that are never executed), and flags these parts line-by-line. - finding out "hot-spot" in Fortran codes (the part of the codes that are most frequently executed), and gives a line by line profile. It is designed to working mainly with F90/F95, even through it can also work with fixed formatted FORTRAN, thus F77. 2. IS IT GOING TO BE OF ANY USE TO ME? For FORTRAN code developer: Finding out "cold-spot" is particularly useful for code developers during the test stage of their software in either eliminating these "cold-spot", or in designing more complete test suite to fully test these parts of the codes. Finding out "hot-spot" could be useful for developers in optimizing their code. For FORTRAN code user: Both capability also helps a user in the analysis and understanding of codes written by other people. FCAT is developed out of a need for a tool in analyzing "cold-spot", although "hot-spot" capability may be useful, they could equally be derived using a FORTRAN profiler like pixie. 3. INSTALLING FCAT comes in a gzipped tar file fcat.tar.gz. On Unix, you need to % gunzip fcat.tar.gz % tar xvf fcat.tar This will create a directory FCAT, which contains two subdirectory FCAT/example and FCAT/bin. You then need to add the FCAT/bin in your path, depend on your system, this may be done by (assume FCAT resides in /home/john/FCAT) % setenv PATH /home/john/FCAT/bin:$PATH % rehash Your can avoid type this line every time you what to use the tool by adding the path in your .cshrc file. This is again system dependent, e.g., you may need to add the following line to the .cshrc file: set path=(/home/john/FCAT/bin $path) and type % source ~/.cshrc Also modify the first line the script FCAT/bin/fcat to give the correct path for "perl" or "perl5" (make sure your perl is of version 5 or above. You can check this by typing "perl -V"). This may be in /usr/local/bin/perl5, or /usr/bin/perl etc, and can usually be found out by typing % which perl Suppose on your system perl is at /usr/bin/perl, then the first lines of the script fcat in FCAT/bin should be "#!/usr/bin/perl". Once the above is done, you are ready to use the tools. 4. USING FCAT Suppose you have the following F90 code called "a.f90" (available in FCAT/example). module sub_mod contains subroutine sub1(j) integer j j = 1 end subroutine sub1 subroutine sub2(j) integer j j = 2 end subroutine sub2 end module sub_mod program junk use sub_mod integer i,j do i = 1, 100 if (i > 200) then call sub1(j) else call sub2(j) end if end do end program junk To analyse the coverage, this is what you do: 4.1) pre-process the a.f90 code and put the output in a_new.f90. Usage: fcat [options] mycode.f90 > mycode2.f90 e.g.: % fcat a.f90 > a_new.f90 4.2) compiling % f90 -o run a_new.f90 4.3) run and direct the input to a file % run > OUTPUT 4.4) analyse the code coverage: Usage: fcat [options] mycode.f90 my_output e.g. % fcat a.f90 OUTPUT The last step (4.4) writes to the screen a file which is the same as a.f90, except that any lines that were not executed are marked with *>. Thus for our example a.f90 we have a coverage analysis in the following module sub_mod contains subroutine sub1(j) integer j *> j = 1 end subroutine sub1 subroutine sub2(j) integer j j = 2 end subroutine sub2 end module sub_mod program junk use sub_mod integer i,j do i = 1, 100 if (i > 200) then *> call sub1(j) else call sub2(j) end if end do end program junk 5. WORKING ITH LARGE CODES If your code have many subroutines/functions/modules in different files, and you use a Makefile, it is easy to incorporate FCAT into the Makefile. What you need to do is to create a tmp directory where your codes are by % mkdir tmp Then modify your make file so that each .f90 code is preprocessed with FCAT first and directed to the tmp directory. The compile the preprocessed code. FCAT/example contains a simple Makefile which can be used to do coverage analysis for two F90 code b.f90 and c.f90, and the original Makefile (in Makefile.old). The crucial lines are .f90.o: fcat $< > tmp/$*.f90 && \ $(F90) $(F90FLAGS) -c tmp/$*.f90 &&\ rm -f tmp/$*.f90 You can see the difference of the original "Makefile.old" and the "Makefile" for coverage analysis by comparing the difference of the two files. After making the excutable, the coverage analysis of any of the codes works in the same way as explained before, e.g., to analysis the code b.f90: %fcat b.f90 OUTPUT where OUTPUT is the screen OUTPUT of your excutable saved earlier. If you are interested in analysing only a few codes out of many, you can "treat" and compile these fews codes only, then analysis them as detailed before. 6. OTHER OPTIONS A number of extra options are available, for example, for "hot-spot" analysis. They are listed the the following 6.1 Dealing with fixed format FORTRAN For preprocessing: fcat -fixedform (or -fixedformat) mycode.f90 > my_newcode.f90 and for post-processing: fcat -fixedform (or -fixedformat) mycode.f90 > myoutput This option should be used when pre/post processing FORTRAN in fixed format. 6.2 "Hot-spot" analysis The options "-count" can be used for "hot-spot analysis". To use this option, you must PUT THE CODE YOU WANT TO ANALYSE TOGETHER WITH THE MAIN PROCEDURE IN ONE FILE! For preprocessing: fcat -count mycode.f90 > my_newcode.f90 and for post-processing: fcat -count mycode.f90 myoutput Which will write out "mycode.f90" with each executable line marked either with "*>" for not being executed, or an integer count of the number of time this line has been executed. Furthermore, you can also get a list of lines in decreasing ordering of the number of times each line is executed by post-processing with fcat -count -report mycode.f90 myoutput For example, applying fcat with -count for preprocessing and with -count -report for post-processing on the previous code a.f0 gives: ========================================= FCAT REPORT a list of executable lines sorted by number of time each is executed line_num procedure_name count ------------------------------- 22 main 100 21 main 100 20 main 100 19 main 100 17 main 100 10 sub2 100 16 main 1 ========================================= FCAT SUMMARY REPORT Code a.f90 has 24 lines: 8 are executable lines of which 2 are not executed ========================================= 7. COVERAGE ANALYSIS FOR PARALLEL CODES FCAT offers some facility for the coverage analysis of parallel codes. It treats a line as being excuted if at least one processor has excuted it. The counter for the line is taken as the maximum of the number of times this line has been excuted over all processors. E.g., if the code has been run on two processors and a line was excuted 5 times on processor one and 0 times on processor two, then the counter for this line is 5. WARNING: because the output of the instrumented code of all processors is written to the same standard output, on some parallel computers an output string may be half-written, then followed by another string. This is can cause problem to FCAT. In such event you may have to run the code again (no need to recompile) and hopefully the problem will not repeat itself. More comprehensive support for parallel analysis may be added if there is a sufficient demand. 8. OTHER INFORMATION AND TROUBLE SHOOTING 8.1 File suffix FCAT can work with file suffix of .F, .f, .F90, .f90. 8.2 Restriction FCAT may not work very well with "statement functions", which is deprecated in F90. Should you program contain such functions and the compilation failed on a preprocessed file at one of these functions, you could edit out calls of the form "FCAT_XXX(XXX)" just before the statement function (you compiler will fail on these lines and will tell you where they are) from the preprocessed files, before try to compiling the file again on its own. 8.3 Trouble shooting If you see "fcat command not find", it is most likely that either *) fcat is not in your path, type % which fcat to see if the correct fcat path is given *) Or you have not modified the first line of FCAT/bin/fcat to give the correct path for Perl. 8.4 Bug reporting While FCAT has been tested on ~300K lines of FORTRAN codes (mostly F90) written by many different people, it is impossible to guarantee that it will work correctly on your code. Should you experience problem, please send me an e-mail together with the offending code. I would also like to hear from you comments and success stories! Enjoy! ACKNOWLEDGEMENT: Thanks are due to my colleagues, particularly Dr. Robert Allan and Prof. John Reid, for testing this software and giving valuable comments.