NAME
bit - Binary Improvement Tool
SYNOPSIS
bit instrument [ general_option| instrument_option]... tar-
get
bit analyze [ general_option| analyze_option]... target
bit optimize [ general_option| optimize_option]... target
bit coverage [ general_option| coverage_option|
analyze_option]... target
bit collect [-c | instrument_option|
general_option| analyze_option | -O redirectfile ]... tar-
get [ target_arguments ]
bit check target
bit -V
bit -?
Where:
general_option:= {-i {on| static| off}| -D cachedir| -s suf-
fix | -n| -V| -v | -R| -r| -l library | -M| -X| -S| -U exe-
cutable| -u }
instrument_option:= {-m {on| off}| -o outfile } | -k| -K
| -N ignore-lib
optimize_option:= {-O {0| 1| 2}| -f| -Q{y| n} -o outfile
-xinline[= v[,v]...]}
analyze_option:= {-o filename| -o experiment-name.er | -d
directory | -e| -E filterspec| -C comment | -A
{on| off| copy}| -a report| -Ye path_to_sun_studio }
coverage_option:= { -F ignore_function}
report:= {ifreq[={N| function}]| cc[={N| function}]|
bbc[={N| function}]|
branch[={N| function}]| function[={N| function}]|
dis[={N| function}]}
AVAILABILITY
Sun Studio 12
DESCRIPTION
bit is a suite of tools for improving binaries. These tools
are used via six subcommands:
The instrument subcommand instruments a binary (the target)
so that when the instrumented target is run, it creates an
instrumentation data directory with information about the
execution of target.
The analyze subcommand uses the instrumentation data to pro-
duce reports on instruction execution. Analysis reports can
be generated in ascii text, or as an experiment. An experi-
ment may be examined with a GUI (analyzer) or a command-line
program (er_print).
The optimize subcommand uses the instrumentation data to
optimize target.
The coverage subcommand uses the instrumentation data to
produce a code coverage report. A summary textual report is
written to the current -o filename, and an analyzer experi-
ment is created with detailed counters for more precise cov-
erage information.
The collect subcommand combines an instrument subcommand, a
target run, and an analyze subcommand. It first instruments
target, then runs it, passing target_arguments at run time.
Then it analyzes it if certain analyze_options are present
on the command line.
target is the path name of the executable for which you want
to collect performance data. (bit will not search PATH to
find target.) target must be prepared by compiling with
-xbinopt=prepare. (If the Sun(TM) Studio 12 compiler is used
to compile the original target, optimization must also be
turned on using the -O or -xO[1-5] options.) In order to
see annotated source when viewing the experiment, target
should be compiled with the -g flag, and should not be
stripped.
The check subcommand prints information about a target
binary. If it is prepared and ready for use with bit, it
prints "Prepared Binary". Otherwise, it prints a diagnostic
indicating why it is not suitable for use with bit. If the
binary has been previously optimized or instrumented with
bit or binopt(1), it will print information about the previ-
ous processing.
NOTES FOR USERS OF GCC FOR SPARC Systems (GCCfss):
Experiments depend on Sun Studio
The bit coverage subcommand and all features that men-
tion experiments, analyzer, and/or er_print are only
available if Sun Studio 12 is installed on the system.
See the description of the -Ye general option for more
information. If Sun Studio 12 is not available, the
output of bit analyze is limited to textual reports.
Example Use
Typically one would use the commands in a sequence to
instrument, run, and analyze or optimize. To create a simple
experiment, use this sequence of commands:
cc -O -xbinopt=prepare *.c
bit instrument a.out
a.out.instr < input1
bit analyze -e a.out
Or to optimize a binary:
cc -O -xbinopt=prepare *.c
bit instrument a.out
a.out.instr < input1
bit optimize a.out
The first example above can be rewritten more simply using
the collect subcommand:
gcc -xbinopt=prepare *.c
bit collect -e a.out < input1
The above example illustrates that GCC for SPARC(R) Systems
(GCCfss) can be used to prepare binaries, as well as Sun
Studio 12. With the GCCfss compiler, however, no particular
optimization level is required to prepare the binary.
OPTIONS
If invoked with no arguments, print a usage message.
General options
-D cachedir
Store instrumented binaries in cachedir. Note that if
this option is used at instrumentation time, the same
option should be used at analyze/optimize/coverage
time, unless the SUNW_BIT_CACHE_DIR environment vari-
able is used.
By default, the cache directory is
`pwd`/SUNW_Bit_Cache. This directory can be overriden
by using the SUNW_BIT_CACHE_DIR environment variable.
(See ENVIRONMENT section below.)
-u Unlink cached binaries at analyze/optimize/coverage
time. Not valid in the instrument subcommand.
-s suffix
Add suffix to target for the instrumented data direc-
tory name. The default is ".instrdata". Note that if
this option is used at instrumentation time, the same
option should be used at analyze/optimize/coverage
time.
-l library
In addition to target, also operate (instrument,
analyze, optimize or analyze coverage) on library. The
-R option must be used. The full filename must be
given, e.g. libfoo.so.1. If the library is not in the
current directory, the path to the library must also be
included.
-n Print the commands that would be run without executing
them.
-V Print the current version. Do not examine further
arguments, and do no further processing.
-v Print the current version and verbose information about
the commands being executed.
-R Replace target. When using the instrument subcommand
(or during the instrumentation phase of the collect
subcommand), cache target and replace it with the
instrumented target.
When using other subcommands (or after the instrumented
target is run in the collect subcommand), replace tar-
get with the cached original version before performing
the requested operation.
If -R is used when instrumenting, it must also be used
when analyzing, optimizing, or analyzing coverage.
-r OK to reoptimize or reinstrument. In the optimize sub-
command, this is the default. In other subcommands, the
default is to disallow processing of previously optim-
ized or instrumented binaries.
-M Instrument or use multiple libraries. -R must also be
given. In the instrument subcommand, instrument all
static dependencies of target (as reported by ldd(1))
that can be instrumented. In the analyze or coverage
subcommands, analyze target and its dependencies. If an
experiment is being created (coverage or analyze -e or
-E), data for target and its dependencies are combined
in one experiment.
-X Do not instrument target for counting. Modify target to
support counts of its dependent shared objects, but do
not actually instrument its code. If this option is
used with instrument, it must also be given with
analyze or coverage.
-S Sum the data from all library runs for
analyzing/optimizing a library when target is an exe-
cutable and such processing is requested is requested
with the -l or -M flags. Without this flag, unique
data from runs of target are used to do the library
analysis/optimization.
-U executable
Use unique data from the run of executable when analyz-
ing or optimizing target when target is a library. The
default is to sum the counts from the runs of all exe-
cutables.
Instrument options
-k Force reinstrumentation. Any cached copies of binaries
are discarded and the binaries are reinstrumented.
-K Do not read the bit.rc files. See the FILES section
below.
-N library
Add library to the ignored libraries list. Libraries on
this list are not instrumented. library is treated as a
prefix for matching library names. If the argument
starts with a leading '/', it is matched as a prefix
against the full pathname of each candidate library.
Otherwise, it is matched against the basename of the
candidate.
There is a default list which is read from the bit.rc
files. See the FILES section below.
-m {on| off}
-m on means instrument for multithreading. Any mul-
tithreaded application should be instrumented with this
option. The default is on. Turning it off for single-
threaded applications may result in faster instrumenta-
tion runs.
-o outfile
Place a symbolic link to the instrumented binary as
outfile. The default is ./target.instr
Optimize options
These options are valid only for the optimize subcommand.
-i {on| off}
Instrumentation data use.
on Use dynamic instrumentation data. This is the
default mode. The data is stored in files in a
directory called `pwd`/target.instrdata by
default. This directory name can be changed using
the -s suffix and -d directory options. The parent
directory can also be set using the
SUNW_BIT_INSTRDATA_DIR environment variable (see
ENVIRONMENT below).
off Do not use instrumentation data.
-O{0| 1| 2}
Optimize target. At level 0, no optimizations are per-
formed. At level 1, do code reordering optimizations.
At level 2, data-flow information is constructed and
more aggressive optimizations like inlining and address
related optimizations are performed.
The default optimization level is 1.
-o outfile
Write the optimized binary to outfile. The default is
./target.opt.
-f Finalize the output binary so that no more binary
optimizations may be performed.
-Q{y| n}
If -Qy is used, identification information is added to
the output binary. If -Qn is used, this information is
not added. -Qy is the default.
-xinline[=v[,v]...]
where v is [{%auto,func_name,no%func_name}].
Inline only those functions specified in the list. The
list is composed of either a comma-separated list of
function names, or a comma separated list of
no%func_name values, or the value %auto. If
no%func_name is specified, do not inline func_name. If
%auto is specified, attempt to automatically inline
functions.
Collect options
-c Generate coverage information.
-O file
Redirect standard output and standard error of bit to
file.
Coverage options
-F ignore_function
For code coverage purposes, ignore blocks that contain
a call to ignore_function in the summary report.
Analyze options
These options are valid in the analyze, coverage, and col-
lect subcommands. In the collect subcommand, -e, -E, -a, and
-c turn on analysis. If none of these options are present,
any other analyze options are ignored and no analysis will
be performed.
At least one -e or -E option must be provided in order to
create an experiment in the analyze subcommand. The coverage
subcommand produces an experiment by default, as does col-
lect -c. As noted above, Sun Studio is necessary in order to
produce an experiment. All experiment-related options are
ignored if bit cannot find the necessary components of Sun
Studio.
-i {on| static}
Instrumentation data source.
on Use dynamic instrumentation data. This is the
default mode. The data is stored in files in a
directory called `pwd`/target.instrdata by
default. This directory name can be changed using
the -s suffix and -d directory options. The parent
directory can also be set using the
SUNW_BIT_INSTRDATA_DIR environment variable (see
ENVIRONMENT below).
static
Analyze an executable statically. Every instruc-
tion in the program is assumed to execute once. In
the collect subcommand, disable the instrument and
target-run phases.
-d directory
Place the experiment and report output files in direc-
tory. The instrdata directories are also placed in this
directory. The default is ".".
-o filename
If filename does not end in ".er", write textual
reports (see -a report below) to filename. Multiple -o
filename options may be given; each one affects the
destination of subsequent -a report options on the com-
mand line. Default is standard out.
-o experiment-name .er
Use experiment-name as the name of the experiment to be
recorded. Only one -o experiment-name .er option is
allowed on the command line.
If -o experiment-name .er is not specified, and experi-
ment generation is requested with the -e and/or -E
options, record an experiment with a name in the form
stem.n.er, where stem is a string, and n is a number.
If a -g argument is given, use the string appearing
before the .erg suffix in the group name as the stem
prefix; if no -g argument is given, set the stem prefix
to "test".
If the name is not specified in the form stem.n.er,
and the given name is in use, print an error message
and do not generate an experiment. If the name is of
the form stem.n.er, and the name is in use, record the
experiment under a name corresponding to the first
available value of n that is not in use. Issue a warn-
ing if the name is changed.
-e Create an experiment with simulated hardware counters
representing function count, instruction executed
count, and instruction annulled count.
A bit experiment also contains summary data describing
the execution frequency of various instructions in the
run. The data is shown in response to the ifreq com-
mand in er_print, and on the Inst.Freq. tab in the
Analyzer.
-E filterspec
Generate a custom counter in the experiment, which will
be viewed in its own column in analyzer or er_print.
See the FILTERSPEC section for more information. Any
number of -E options can be given. Each unique -E
option will produce one counter in the experiment.
-Ye,path_to_sun_studio
When using the verson of bit distributed with GCCfss,
certain components of Sun Studio must be available in
order for bit to produce experiments. If Sun Studio is
installed in the standard place, i.e. /opt/SUNWspro,
bit will be able to find it. Otherwise, use this flag
to indicate where Sun Studio is installed. This option
is ignored in the bit instrument and bit optimize sub-
commands.
-C comment
Put the comment, either a single token, or a quoted
string, into the experiment. Up to ten comments may be
provided.
-g group_name
Consider the experiment to be part of experiment group
group_name. The group_name string must end in ".erg";
if not, report an error and do not create the experi-
ment.
-A option
Control whether or not load-objects used by the target
process should be copied into the recorded experiment.
The allowed values of option are:
Value Meaning
on Archive load objects into the experiment.
off Do not archive load objects into the experi-
ment.
copy Copy and archive load objects into the
experiment.
If the user copies experiments onto a different
machine, or reads them on a different machine, the user
should specify -A copy. Note that doing so does not
copy any sources or object files. It is the responsi-
bility of the user to ensure that those files are
accessible on the machine where the experiment is
copied.
-a report
Write a textual (ascii) report to the current output
filename (see -o filename above.) In any of these
reports, if the optional argument (=N or =function) is
not given, or if a limit of 0 is given, the report cov-
ers the whole program. Available reports are:
ifreq[=N]
Instruction frequency. Print a profile of instruc-
tion execution counts for the sum of the top N hot
functions, in descending order of frequency.
Example:
bit analyze -a ifreq a.out | head -13
Instruction frequencies for whole program
Instruction Executed (%)
TOTAL 169067648498 (100.0)
float ops 170346 ( 0.0)
float ld st 170346 ( 0.0)
load store 36788000338 ( 21.7)
load 25144202260 ( 14.8)
store 11643798078 ( 6.8)
-------------------------------------------
Instruction Executed (%) Annulled In Delay Slot
add 16935512560 ( 10.0) 2992 3112858420
br 16762242816 ( 9.9) 0 0
sll 14368909396 ( 8.4) 16 916733870
subcc 13842547720 ( 8.1) 0 1938670930
ifreq=<function>
Prints an instruction frequency breakdown for the
named function.
cc[=N]
Caller-callee report. Prints the top N hottest
caller-callee edges. JMPL's (dynamic calls) are
indicated by the function name "**INDIRECT
CALL**".
Example:
bit analyze -a cc=9 a.out
Top 9 caller-callee edges
Count Caller ---> Callee
563227968 compress_block ---> send_bits
397429280 deflate ---> ct_tally
263338416 deflate_fast ---> ct_tally
165937792 deflate_fast ---> longest_match
5842268 build_tree ---> bi_reverse
2805034 send_tree ---> send_bits
313216 send_all_trees ---> send_bits
82828 huft_build ---> malloc
82828 inflate_dynamic ---> free
cc=<function>
Prints a list of callers in frequency order, then
the given function, followed by a frequency-
ordered list of callees. All calls through a jmpl
are summed and attributed to "unknown".
Example:
bit analyze -a cc=deflate a.out
Callers and callees of deflate
Callers and callees of deflate
Callers: Count
15 zip
55 **unknown**
------> 70 deflate
Callees: Count
596143936 ct_tally
18423 fill_window
18213 flush_block
6 deflate_fast
bbc[=N]
Basic Block Count. Prints a list of the top N hot
basic blocks. If the block happens to be a func-
tion entry point, the function name is printed.
The listing includes the PC of the first instruc-
tion of the block and the number of instructions
in the block.
Example:
bit analyze -a bbc=6 a.out
Basic Block Counts for top 6 blocks
Count PC #Instrs Function name
991151488 0x10000e940 24 ct_tally
991151488 0x10000e9cc 2
991151488 0x10000e9dc 16
985851840 0x10000e9a0 11
966297600 0x10000e9d8 1
867284096 0x10000e9d4 1
bbc=<function>
Basic Block Count for all blocks in a function.
branch[=N]
Branch taken/not-taken report. For the top N hot
branches, print branch statistics, including
branch direction (Forward or Backward), total exe-
cution count, taken and not taken counts and per-
centages, and an indication of whether the com-
piler correctly set the prediction bit.
Example:
bit analyze -a branch=6 a.out
Branch taken/not taken report for top 6 branches
PC Dir %Taken %Not Compiler Trip Cnt Taken etc...
Taken Prediction
Correct?
10000e998 F 0.5% 99.5% Y 991151488 5299648 ..
10000e9cc F 12.5% 87.5% Y 991151488 123867416 ..
100003668 F 49.4% 50.6% Y 849549760 420060832 ..
100009484 F 1.4% 98.6% Y 834797568 11554240 ..
1000094d4 F 0.2% 99.8% Y 834797568 1372160 ..
1000094e8 F 0.6% 99.4% Y 834797568 5033466
branch=<function>
Print branch taken/not-taken information for all
branches in <function>.
function[=N]
Function Count. Prints a list of the top N hot
functions, along with their execution counts.
Example:
bit analyze -function=3 a.out
Function Counts for top 3 functions
Count PC Function name
847659008 0x1000fc7a0 __1cKggSpectrumDSet6Mf_v_
297246944 0x10013a100 __1cHmy_rand6F_l_
216990656 0x100134880 __1cKmrMaterial_splat__
function=<function>
Print the execution counts of the given func-
tion.
dis[=N]
Print a disassembly of the top N functions, with
the raw
execution count for each instruction.
Example:
bit analyze -dis=2 a.out
Disassembly for top 2 routines
Disassembly for routine __1cKggSpectrumDSet6Mf_v_
ROUTINE: __1cKggSpectrumDSet6Mf_v_ FREQUENCY: 847659008.0
BLOCK: __1cKggSpectrumDSet6Mf_v_: FREQUENCY: 847659008.0 PC: 0x1000fc7a0
[ 847659008.0] 0x1000fc7a0: st B[B%o0, B#sint=0], B%f3
[ 847659008.0] 0x1000fc7a4: st B[B%o0, B#sint=4], B%f3
[ 847659008.0] 0x1000fc7a8: st B[B%o0, B#sint=8], B%f3
[ 847659008.0] 0x1000fc7ac: st B[B%o0, B#sint=12], B%f3
[ 847659008.0] 0x1000fc7b0: st B[B%o0, B#sint=16], B%f3
[ 847659008.0] 0x1000fc7b4: st B[B%o0, B#sint=20], B%f3
[ 847659008.0] 0x1000fc7b8: st B[B%o0, B#sint=24], B%f3
[ 847659008.0] 0x1000fc7bc: jmpl B[B%o7, B#sint=8], B%g0
[ 847659008.0] 0x1000fc7c0: st B[B%o0, B#sint=28], B%f3
Disassembly for routine __1cHmy_rand6F_l_
ROUTINE: __1cHmy_rand6F_l_ FREQUENCY: 297246944.0
BLOCK: __1cHmy_rand6F_l_: FREQUENCY: 297246944.0 PC: 0x10013a100
[ 297246944.0] 0x10013a100: sethi B#sint=1048576, B%g5
[ 297246944.0] 0x10013a104: sethi B#sint=126976, B%o4
[ 297246944.0] 0x10013a108: or B%g5, B#sint=537, B%o0
[ 3300639.0] 0x10013a1d4: br@(a),B%icc B%disp22($LABEL_rand)
.
. (long function shortened for example)
.
[ 3300639.0] 0x10013a1d8: sra,x B%o5, B#sint=8, B%g2
dis=<function>
Print the disassembly listing of the named func-
tion, with execution counts.
FILTERSPECS
This syntax is used to produce a custom analysis column for
er_print or analyzer. You can use many -E flags in a single
invocation of bit to produce multiple custom columns in the
experiment.
Syntax
-E filterspec
filterspec := element [ ':' element ... ]
element := instrselector | limiter | metricspecifier
instrselector := instr | instrgroup
instr := <lower case mnemonic from SPARCinstruction>
instrgroup := 'BR' | 'LD' | 'ST' | 'CALL' | 'JUMP' | 'SAVE'
| 'RESTORE' | 'CMP' | 'BA' | 'BN' | 'CBR' | 'ICALL' |
'SWITCH'
limiter := positive_limiter | 'n' positive_limiter
positive_limiter := 'ds' | 'float'
metricspecifier := metric ['%'] | 'targetmark'
metric := pmetric | 'n' pmetric
pmetric := 'executed' | 'annul' | 'taken' | 'correct' |
'target'
NOTES:
1. All instrselector elements are logically OR'd to
produce a pool of instructions. Each of the limiters is
logically AND'd against the result.
2. If no instrselector is given, all instructions are
selected.
3. The default metricspecifier is 'executed'
4. Only one metricspecifier is allowed.
5. Only one limiter is allowed.
6. The "%" metricspecifier calls out the frequency of
the specified metric vs. the frequency of the contain-
ing block.
7. n is the 'not' operator, that is, it inverts the
metric.
8. ds selects instructions in the delay slot of a con-
trol transfer instruction.
9. target is the count is the sum of all counts on
incoming branch edges to the instruction. 'ntarget' is
the fallthrough count.
10. targetmark prints the number of branch edges coming
in to the instruction. The 'n' or '%' modifiers are not
allowed.
Examples:
LD:ST:ds will display the issue count for every load or
store in the program that happens to be placed in a delay
slot.
BR:ds will produce a count of zero for every instruction
because a branch cannot be in a delay slot.
BR:ntaken will produce a count showing how many times each
branch was not taken.
BR:correct% will show how often the compiler branch predic-
tion was correct as a percentage.
nop:nds produces counts for all nops that are not in delay
slots
Mnemonics for instr
add addc addcc addccc alignaddr
alignaddrl and andcc andn andncc
array16 array32 array8 bitextract bmask
bpr br bshuffle call casa
casxa done edge16 edge16l edge16ln
edge16n edge32 edge32l edge32ln edge32n
edge8 edge8l edge8ln edge8n fabsd
fabsq fabss faddd faddq fadds
faligndata fand fandnot1 fandnot1s fandnot2
fandnot2s fands fbr fchksm16 fcmpd
fcmped fcmpeq fcmpeq16 fcmpeq32 fcmpes
fcmpgt16 fcmpgt32 fcmple16 fcmple32 fcmpne16
fcmpne32 fcmpq fcmps fdivd fdivq
fdivs fdmulq fdtoi fdtoq fdtos
fdtox fexpand fitod fitoq fitos
flcmpd flcmps flush flushw fmean16
fmovd fmovq fmovrd fmovrq fmovrs
fmovs fmul8sux16 fmul8ulx16 fmul8x16 fmul8x16al
fmul8x16au fmuld fmuld16x16 fmuld8sux16 fmuld8ulx16
fmulq fmuls fnand fnands fnegd
fnegq fnegs fnor fnors fnot1
fnot1s fnot2 fnot2s fone fones
for fornot1 fornot1s fornot2 fornot2s
fors fpack16 fpack32 fpackfix fpadd16
fpadd16s fpadd32 fpadd32s fpadds16 fpadds16s
fpadds32 fpadds32s fpmerge fpmovc16 fpmovc32
fpsub16 fpsub16s fpsub32 fpsub32s fpsubs16
fpsubs16s fpsubs32 fpsubs32s fqtod fqtoi
fqtos fqtox fshl16 fshl32 fshlas16
fshlas32 fshra16 fshra32 fshrl16 fshrl32
fsmuld fsqrtd fsqrtq fsqrts fsrc1
fsrc1s fsrc2 fsrc2s fstod fstoi
fstoq fstox fsubd fsubq fsubs
fxnor fxnors fxor fxors fxtod
fxtoq fxtos fzero fzeros illtrap
jmpl ld lda ldd ldda
ldq ldqa ldsb ldsba ldsh
ldsha ldstub ldstuba ldsw ldswa
ldub lduba lduh lduha lduw
lduwa ldx ldxa lzd membar
mov movr mulscc mulx nop
or orcc orn orncc pdist
popc prefetch prefetcha rd rdpr
restore restored retry return save
saved sbshuffle sdiv sdivcc sdivx
sethi sfabss sfadds sfcmpseq sfcmpsgt
sfcmpsle sfcmpsne sfitos sfmuls sfnegs
sfstoi sfsubs shutdown siam sir
sll smul smulcc sra srl
st sta stb stba stbar
std stda sth stha stq
stqa stw stwa stx stxa
sub subc subcc subccc swap
swapa taddcc taddcctv trap tsubcc
tsubcctv udiv udivcc udivx umul
umulcc wr wrpr xnor xnorcc
xor xorcc
CAVEATS
GCC-compiled Code With Exceptions
If GCC for Sparc(R) Systems (GCCfss) is used to compile
the prepared binary, and exception handling is enabled,
bit will refuse to instrument or optimize the prepared
binary.
Only Prepared Code is Counted
bit can only instrument, analyze, or optimize code
which has been prepared by the compiler by compiling it
with -xbinopt=prepare, with an appropriate optimization
level. The Sun Studio compilers require that -O or
-xO[1-5] options be used. GCCfss has no specific optim-
ization requirement.
Specifically excluded from instrumentation are assembly
language modules and functions which contain "asm"
statements or .il templates.
Only instrumented code is counted. Unless the -M flag
is used, shared libraries and dynamic libraries are
excluded. Extremely small functions in prepared code
modules are not counted when called from nonprepared
code.
Some instructions may be miscounted in the face of
asynchronous events. For example, if a signal handler
calls longjmp(), all instructions in the basic block
which was interrupted will have the same count, even
though some were executed and some were not.
ENVIRONMENT
SUNW_BIT_CACHE_DIR
This environment variable, if set, specifies the root direc-
tory for the cache where BIT stores instrumented binaries.
Its setting overrides the value specified by the -D cachedir
flag.
SUNW_BIT_INSTRDATA_DIR
This environment variable can be used to specify the parent
directory where instrumentation data (target.instrdata
directories) are kept. Its setting overrides the value
specified by the -d directory flag.
FILES
BIT .RC FILES
bit initializes its state by reading a series of .rc files
at startup. A system file,
<compiler_area>/prod/lib/postopt/bit.rc, provides default
values for certain variables. bit reads this file first,
then $HOME/.bit.rc, if it exists, then `pwd`/.bit.rc, if it
exists.
The .rc files contain commands to set, append to, and remove
from variables. Whenever a set command is seen, the previous
value of the variable (if any) is discarded. An append com-
mand will cause its argument to be appended (after a colon
separator) to the existing value of the variable. A remove
command will cause its argument to be removed (along with a
colon separator) from the existing value of the variable.
The variables set in the .rc files include the list of
libraries to ignore while instrumenting, and lists of func-
tions or function prefixes to ignore when computing the per-
centage of nonannotated code in a binary.
For more information, see the header in the system .rc file.
BIT INSTRUMENTATION CACHE
Instrumented binaries are kept in a cache, the root of which
is known as cachedir. By default, cachedir is
`pwd`/SUNW_Bit_Cache.
cachedir can be specified on the command line with the
-D cachedir flag, or by using the SUNW_BIT_CACHE_DIR
environment variable.
INSTRUMENTATION DATA STORAGE
Instrumentation data are kept in files in subdirectories of
an instrumentation data directory. The root directory, by
default, is `pwd`. An alternate root can be specified using
the SUNW_BIT_INSTRDATA_DIR environment variable, or the
-d directory flag.
The subdirectory name is formed by concatenating the name of
the instrumented target or library with a suffix, .instrdata
by default. This suffix can be changed with the -s suffix
flag.
The files in this subdirectory are named
process_name.instrdata, where process_name is the basename
of the program taken from the runtime environment. The
.instrdata suffix of the filenames cannot be changed.
For example, if libfoo.so.1 has been instrumented and is
dynamically linked in by both a.out and b.out, the following
instrumentation files will be created:
./instrdata/libfoo.so.1.instrdata/a.out.instrdata
./instrdata/libfoo.so.1.instrdata/b.out.instrdata
When using this data in the analyze, coverage and optimize
subcommands, data from all process_name.instrdata files is
summed, so as to produce a composite view of all uses of the
library.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
1 An error occurred.
SEE ALSO
analyzer(1), binopt(1), collect(1), er_archive(1),
er_bit(1), er_cp(1), er_export(1), er_mv(1), er_print(1),
er_rm(1), er_src(1), the Performance Analyzer manual, the
BIT User's Guide , and the Binary Optimization Guide.