Sun WorkShop(TM) 6 Profiling Tools (TCOV) README
Updated 00/04/14
 
Contents 
  • Introduction
  • About Sun WorkShop 6 TCOV
  • Features 
  • Software Corrections 
  • Problems and Workarounds 
  • Limitations and Incompatibilities 
  • Documentation Errata 

  • Introduction

    Sun WorkShop 6 Release

    This document contains last minute information about Sun WorkShop 6 TCOV profiling tools. It describes the software corrections addressed by this release and lists the known problems, limitations, and incompatibilities. 

    To access the HTML version of this document, point your Netscape(TM) Communicator 4 or compatible browser to:
          file:/opt/SUNWspro/docs/index.html

    Note: If your Sun WorkShop software is not installed in the standard /opt directory, ask your system administrator for the equivalent path on your system. 

    For more information about this product, see: 

      Sun WorkShop 6 Release Notes -- This documentation describes installation-related and late-breaking information about this release. Information in the release notes overrides information in all readme files. 
    • tcov(1) man page -- This man page describes the tcov command-line options.

    •  
    • About Sun WorkShop 6 Documentation -- Describes the documentation available with this Sun WorkShop release and how to access it.
      •  
    • What's New In Sun WorkShop 6 -- Describes the new features in this release.

    • These documents are accessible in HTML by pointing your browser to 
             /opt/SUNWspro/docs/index.html
      in a standard installation of Sun WorkShop.

    About Sun WorkShop 6 tcov

    Sun WorkShop 6 tcov runs on SPARC(TM) processors running Solaris(TM) SPARC Platform Edition versions 2.6 and 7, and Intel(R) x86 processors running Solaris Intel Platform Edition, versions 2.6 and 7. 

    This README describes the tcov command, which can be used to generate a detailed statement-by-statement coverage profile of program's execution.

    Profile feedback allows you to help the compiler optimizer to gather runtime in formation about the program that the compiler can use to better optimize the program.

    Both require compiling programs with special compiler options.


    Features

    This release of Sun WorkShop 6 tcov includes the following features: 

    Profile feedback has two phases: collect (collection of data about the program) and use (the compiler uses the data that the collect phase gathered). The collect phase "instruments" the code, which means that it inserts counters into the code to count the number of times some code was executed. 

    TCOV, Profile Feedback Flags, and Environment Variables

    Profile feedback and tcov share a common way of collecting and recording data, which includes placing their output in the same directory, and using the same environment variables to control where the profile output goes and what it is called. The term "profile-bucket" specifies the directory in which profile output is generated (both tcov profile output and profile feedback output).

    By default, you compile the program with either tcov or profile feedback collection turned on, and run the program. At exit, the running program generates a profile-bucket. If a previous profile-bucket exists, the program uses that profile-bucket. If a profile-bucket does not exist, it creates the profile-bucket.

    The default profile-bucket that the program creates is named after the executable with a ".profile" extension, and is created in the place where the executable is run. Therefore, if you are in /home/joe, and run a program called /usr/bin/foo, the default behavior is to create a profile-bucket called foo.profile in /home/joe.

    There are two ways to override the default. In the first way, you have the ability to specify the exact profile-bucket that you want generated on the compile line. The running executable honors this even in the presence of environment variables. This is only done for profile feedback.

    The second way is to use environment variables. There are two things that can be changed about a profile-bucket. The first is the name of the profile-bucket, which can be changed using the environment variable SUN_PROFDATA. The second is the directory where the profile-bucket is placed, which can be controlled with SUN_PROFDATA_DIR. The environment variables override the default location and name of the profile-bucket, and both can be overridden independently. For instance, if you only choose to set SUN_PROFDATA_DIR, then the profile-bucket goes into the directory that you set SUN_PROFDATA_DIR to be. The default name (which is the executable name followed by a ".profile") will still be the name used for the profile-bucket.

    There are two forms of directories that you can specify by using SUN_PROFDATA_DIR and on the profile feedback compile line: absolute pathnames (which start with a '/'), and relative pathnames. If you use an absolute pathname, then the profile-bucket is dropped into that directory. If you specify a relative pathname, then it is relative to the current working directory where the executable is being run. So, if you are in /home/joe, and run a program called /usr/bin/foo, and have SUN_PROFDATA_DIR set to "..", then the profile-bucket is called /home/joe/../foo.profile: the value specified in the environment variable was relative, and therefore, it was relative to /home/joe. Also, the default profile-bucket name is used, which is named after the executable.

    Earlier versions of tcov (enabled by compiling with the -xa/-a flag) used an environment variable called TCOVDIR. TCOVDIR specified the directory where the tcov counter files would go to instead of next to the source files. We have retained compatibility with this environment variable, in that the new SUN_PROFDATA_DIR environment variable behaves like the TCOVDIR environment variable, and if both are set, a warning is output and SUN_PROFDATA_DIR takes precedence over TCOVDIR.

    Environment Variables

    SUN_PROFDATA

    Can be used to specify the name of the profile-bucket at runtime. The value of this variable is always appended to the value of SUN_PROFDATA_DIR, if they are both set.
    SUN_PROFDATA_DIR
    Can be used to specify the name of the directory containing the profile-bucket. It is used at runtime and in the tcov command.
    TCOVDIR
    TCOVDIR is supported as a synonym for SUN_PROFDATA_DIR for the sake of backwards compatibility. Any setting of SUN_PROFDATA_DIR causes TCOVDIR to be ignored. If both SUN_PROFDATA_DIR and TCOVDIR are set, a warning is issued when the profile-bucket is being generated.
    TCOVDIR used at runtime by a program compiled with -xprofile=tcov and it is used by the tcov command.


    Compiler options

    -xprofile=collect[:nameopt]

    This flag instructs the compiler to instrument the code for profile feedback data collection.

    nameopt specifies a name for the generated profile-bucket. It is not a pathname to the profile-bucket, but the actual name. nameopt can name an absolute or relative profile-bucket.

    If nameopt is not specified, then the default output profile-bucket is placed in the current working directory, and is called what the executable is called with a ".profile" appended to it.

    If nameopt is specified, then the profile-bucket is called nameopt. If nameopt is a relative pathname to the profile-bucket, it is generated relative to the current working directory.

    If nameopt is specified, then it should be a path to the profile-bucket. The compiler does not mangle the name of the profile-bucket in any way, and does not append a ".profile" to the name of the profile-bucket specified by the user. If nameopt is an absolute name, then it is used as-is, otherwise nameopt is relative to the current working directory.

    If nameopt is specified, the environment variables do not affect it in any way: the compiler uses nameopt as the name of the profile-bucket.

    -xprofile=use[:nameopt]
    This flag instructs the compiler to use profile feedback data that was collected from a program instrumented to collect this data.

    If nameopt is not specified, then the default profile-bucket name the compiler uses is a.out.profile in the current working directory.

    If nameopt is specified, then it should be a path to the profile-bucket. The compiler does not mangle the name of the profile-bucket in any way, and does not append a ".profile" to the name of the profile-bucket specified by the user. If nameopt is an absolute name, then it is used as-is, otherwise nameopt is relative to the current working directory.

    If nameopt is specified, the environment variables do not affect it in any way: the compiler uses nameopt as the name of the profile-bucket.

    -xprofile=tcov
    This flag instructs the compiler to instrument the code for tcov data collection. It does not create any user visible files at compile time, unlike the previous version of tcov, which created coverage files at compile time.
    Runtime of an instrumented executable

    All relative path names start at the current working directory of the program, which includes the environment variables and the directory names specified on the command line.

    For -xprofile=collect and -xprofile=tcov

    By default the profile-bucket is called <argv(0)>.profile in the current directory.

    If you set SUN_PROFDATA, the profile-bucket is called $SUN_PROFDATA, wherever it is located.

    If you set SUN_PROFDATA_DIR, the profile-bucket is placed in the specified directory.

    SUN_PROFDATA and SUN_PROFDATA_DIR are independent, in that if both are specified, the profile-bucket name is generated by using SUN_PROFDATA_DIR to find the profile-bucket, and SUN_PROFDATA to name the profile-bucket in that directory.

    A UNIX process can change its current working directory during the execution of a program. The current working directory that is used to generate the profile-bucket is the current working directory of the program at exit. In the rare case where a program actually does change its current working directory during execution, the environment variables can easily control where the profile-bucket is generated.

    For a program compiled with -xprofile=collect:nameopt
    If nameopt is given, then it is used as-is for the name of the profile-bucket. None of the environment variables have any effect if nameopt is used. This option is for users who would like to make sure that the profile feedback data goes into a single profile-bucket, no matter what the environment of the program being used looks like. This is useful for groups trying to put an executable in a common area for many people to use and collect data on, without having to set environment variables.
    tcov Command

    -x profile-bucket

    This option specifies the name of the profile-bucket to use for the tcov analysis. SUN_PROFDATA_DIR or TCOVDIR are prepended to this argument, if they are set.
    Some Sample User Scenarios 

    A) If you want to profile different programs over a period of time, and want to have a private directory where the profile-buckets are created.

    - Set SUN_PROFDATA_DIR to your private directory and leave it set. Make sure this private directory is writable.
    B) If you want to collect data from two different sets of runs by using the same binary, then do this:
    - Set SUN_PROFDATA to the name of a *specific* profile-bucket which will be created, if necessary. 
    - Run your program repeatedly with different inputs. 
    - Set SUN_PROFDATA to a different name. 
    - Run your program repeatedly on a different set of inputs. 
    - Unset the SUN_PROFDATA variable.
    C) You have multiple executables in the same directory, and wish to profile all of them.
    - Compile your program with only -xprofile=collect, and by default, the profile data for each individual program goes into a separate profile-bucket, each named after the different executable.
    D) You would like to make sure the output of your profile run always goes to a certain directory, and you don't like to use environment variables
    - Compile your program with -xprofile=collect:<my_profile_bucket>
    - Run your program, and the output goes to that profile-bucket. 
    - To use this data, recompile your program with -xprofile=use:<my_profile_bucket>.
     

    Example:

    Compile your program with -xprofile=collect, and specify where you would like the output to go 
        % cc -xprofile=collect:/home/bar/run1 -o foo

    Run your program. The profile-bucket /home/bar/run1 is created. 
        % foo

    Recompile your program to use the profile information 
        % cc -xprofile=use:/home/bar/run1 -o foo


    E) You are a user of earlier versions of tcov, and already have TCOVDIR set in your environment, and you would like to try out the new version of tcov.

    - Compile your program (called foo, for example) with -xprofile=tcov
    - Run foo, and the output goes to $TCOVDIR/foo.profile
    - Run the tcov command: 
          tcov -x foo.profile filename.c 
    and the output from tcov will be in filename.c.tcov
    Note: 

    -xprofile and regular tcov may fail to collect data on a target that allocates all available memory, or leaves open all available file descriptors, or otherwise leaves the process in a state where the resources needed to write the performance data are not available.


    Software Corrections

    There is no new information at this time.


    Problems and Work Arounds

    This section discusses the following software bugs that could not be fixed in time for this release. (Check Hot News for Sun WorkShop 6 (http://www.sun.com/workshop/users/ws.html) for updated information): 

    • The report produced by tcov can be unreliable if there is inlining of subprograms as a result of the -O4, -O5, -fast, or -inline options. Coverage of calls to routines that have been inlined is not recorded.

    Limitations and Incompatibilities

    This section discusses the following incompatibilities between Sun WorkShop 6 TCOV and previous releases.


    Documentation Errata 

    There is no new information at this time. 


    Copyright 2000 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303, U.S.A. All rights reserved. 
    Sun, Sun Microsystems, the Sun logo, docs.sun.com, and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems Inc. in the U.S. and other countries.