Man Page er_bit.1




NAME

     er_bit - generates	an experiment from data	 collected  on	a
     bit-instrumented program (Solaris only)


SYNOPSIS

     er_bit experiment_args target [ debug_args	] bat_args
     er_bit  experiment_args  target  bit-snap-file1  [	bit-snap-
     file2 ...]


DESCRIPTION

     The er_bit	command	can process instrumentation data  from	a
     run of a program instrumented by bit, and generate	a perfor-
     mance experiment from that	data.  The command  is	not  nor-
     mally  invoked  directly  by  a user, but is invoked by bit,
     typically in response to the user collecting count	data with
     the -c option to collect.

     NOTE: er_bit is currently	only  available	 on  Solaris  and
     OpenSolaris platforms.

     The experiment  generated	appears	 as  a	hardware-counter-
     overflow  profiling experiment with multiple counters in the
     same run, generated  on  the  uninstrumented  target.   Only
     leaf-PCs  are  captured,  no CPU or thread	IDs are	recorded,
     and no timestamps are recorded.  The data	may  be	 examined
     with  a  GUI  program  (analyzer)	or a command-line version
     (er_print).

     target is the path	name of	the executable for which you want
     to	 collect  performance data. Programs that are targets for
     the er_bit	command	can be	compiled  with	any  optimization
     -xO1  or  greater,	 and must be prepared by compiling with	-
     xbinopt=prepare. In order to see annotated	 source,  targets
     should  be	 compiled  with	 the  -g  flag,	and should not be
     stripped.

     The prepared binaries must	be instrumented	using  bit,  then
     the resulting instrumented	binary (e.g., target.binstr) must
     be	run on a typical workload. This	run creates  the  instru-
     mentation	datafile  which	 is  used by er_bit to create the
     experiment.  Typically both these steps are accomplished  by
     using bit -collect.

     When the -er option is provided to	bit, bit  invokes  er_bit
     using  the	 first	synopsis.  er_bit then invokes postopt to
     create temporary bit-snap-files which it then uses	to create
     the  experiment.	The  second  synopsis  is mostly used for
     debugging.	It makes use of	bit-snap-files	which  have  been
     created  by  a  previous  invocation  of er_bit -vv -keeptmp
     -er*.



OPTIONS

     If	invoked	with no	arguments, print a usage message.

  experiment_args
     -C	comment
	  Put the comment, either a single  token,  or	a  quoted
	  string, into the experiment.	Up to ten comments may be
	  provided.

     -o	experiment-name
	  Use experiment-name as the name of the experiment to be
	  recorded.   The  experiment-name string must end in the
	  string .er; if not, report an	error and do not run  the
	  experiment.

	  If -o	is not specified, 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 the string 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 run the 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.

     -d	directory_name
	  Place	the experiment in directory  directory_name.   if
	  none	is  given, record into the current working direc-
	  tory.

     -g	group_name
	  Consider the experiment to be	part of	experiment  group
	  group_name.	The  group_name	 string	 must  end in the
	  string .erg; if not, report an error and do not run the
	  experiment.

     -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 exper-
		    iment.

	  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.

     -V	  Print	the current  version.	Do  not	 examine  further
	  arguments, and do no further processing.

     -v	  Print	the current version and	further	detailed informa-
	  tion about the experiment being generated.

  debug_args
     -vv  Print	verbose	information about er_bit processing.

     -keeptmp
	  Don't	delete temporary files.

     -Yo,path
	  Find postopt using path.


  bat_args
     All bat (binary analyzer) arguments are passed on by  er_bit
     when it invokes postopt.  See the binary analyzer section of
     the bit(1)	man page.  Any binary analyzer arguments  can  be
     used, and the appropriate reports will be generated, but the
     -er arguments are special to er_bit:

     -er* At least one bit argument beginning with  -er	 must  be
	  provided  in	order  to create an experiment.	Note that
	  the =<filename> suffix of the	-er bit	argument  can  be
	  omitted  when	 using	er_bit.	 er_bit	 will  create the
	  necessary temporary file names and pass them on to bit.
	  See bit(1) for further information about the options.



DATA RECORDED

  Program-based	metrics
     Hardware Counter Overflow Profiling
	  Count	data is	recorded  as  hardware	counter	 overflow
	  profiling  records.	The data does not include the CPU
	  ID, thread ID, and LWP IDs; it is aggregated across all
	  threads  and	CPUs.	Records	 generated by er_bit have
	  only a leaf PC in their callstacks, and  PCs	refer  to
	  the uninstrumented target.  Timestamps are meaningless.

	  The counters generated depend	on the	arguments  passed
	  to  bit.  See	 bit(1)	for information	on custom counter
	  information available	by means of filtering options.

     Instruction frequency metrics
	  An er_bit experiment 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.



SEE ALSO

     analyzer(1), bit(1),  collect(1),	er_archive(1),	er_cp(1),
     er_export(1),  er_mv(1),  er_print(1),  er_rm(1), er_src(1),
     and the Performance Analyzer manual.