|Sun WorkShop(TM) 6 Profiling Tools (TCOV) README|
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:
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:
These documents are accessible in HTML by pointing your browser to
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.
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.
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.
This flag instructs the compiler to instrument the code for profile feedback data collection.-xprofile=use[:nameopt]
This flag instructs the compiler to use profile feedback data that was collected from a program instrumented to collect this data.-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.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
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.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>.
- Compile your program (called foo, for example) with -xprofile=tcovNote:
-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.
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):
Limitations and Incompatibilities
This section discusses the following incompatibilities between Sun WorkShop 6 TCOV and previous releases.
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.