dcpi2pix - Translate DIGITAL Continuous Profiling Infrastructure profile data to pixie format
dcpi2pix [<options>] [-scale] [-version] image-file
Dcpi2pix processes an image file and one or more DIGITAL Continuous Profiling Infrastructure profiles for that image and produces a pixie-style output file (*.Counts) containing the relative execution counts for each basic block in the image.
The execution counts are estimated from cycles samples using heuristics as in dcpicalc(1). When a basic block's estimated execution count has too low a confidence, dcpi2pix arbitrarily writes a count of 0 for the block in the Counts file. Users will typically want to use the -conf_low option to include low-confidence data.
Before running dcpi2pix, one must gather cycles samples using dcpid(1) and construct a Addrs file using pixie.
Since the Continuous Profiling Infrastructure is a sampling-based profiling system and pixie produces exact basic block execution counts through instrumentation, profiles produced by dcpi2pix might confuse downstream tools. In particular, if a downstream tool depends on having exact counter values, with basic block counts that satisfy the flow constraints of the control flow graph, then it might become confused when confronted by a dcpi2pix-generated Counts, which will not have this property (see BUGS, below, for an example). If the tools use the basic block counts only to determine which parts of the program were frequently executed, however, the output produced by dcpi2pix should work fine.
Pixie files contain an embedded CPU type in the profile data. Dcpi2pix determines the cpu type using the cpu type of the machine on which the first specified sample file was gathered.
- -scale
- By default, an estimated count of 1 denotes P executions, where P is the average sampling period used to gather the cycles samples. With -scale, the estimated basic-block counts are scaled by P.
- -version
- Print dcpi2pix version string.
The following options can be used to control the heuristics for estimating execution counts and identifying the causes of stalls.
- -conf_low
- Generate low, medium, and high confidence data.
- -conf_med
- Generate medium and high confidence data. (default)
- -conf_high
- Generate only high confidence data.
- -cross_procedure [optimistic | pessimistic | selective]
- Choose what assumption to make when a procedure call boundary is encountered while looking for reasons to explain dynamic stalls. A procedure call boundary is either a call made by the procedure being analyzed or the beginning or end of that procedure. With pessimistic, assume that whatever happens outside the analyzed procedure can cause a dynamic stall inside it. With optimistic, assume that it cannot. With selective, the assumption is based on standard procedure call convention. (The default is optimistic.)
- -do_gp
- Use a (non-linear time) constraint solver to exploit global flow constraints when estimating execution counts. The estimates may still violate flow constraints.
- -tab foo.tab
- Get execution counts from output of dcpix(1) instead of making estimates, which may be inaccurate. Requires a .xct file.
- -xct foo.xct
- Get execution counts from output of dcpix(1) instead of making estimates, which may be inaccurate. Requires a .tab file.
- -xct_factor num
- Scales counts from .xct files by num. Useful when you run a program once under dcpix(1) but multiple (num) times under dcpid(1) to get more samples. Used in conjuction with -tab and -xct.
By default, this command automatically finds all of the relevant profile files. The following options can be used to guide the search for the profile files.
- -db <directory name>
- Search for profile files in the specified profile database directory. The directory name should be the same name as the one specified when dcpid was started. I.e., the named directory should contain a set of epochs. If this option is not specified, the directory name is obtained from the DCPIDB environment variable. If neither this option, nor the DCPIDB environment variable are set, the name of the directory used by the last invocation of dcpid on this machine is used. If none of these methods succeed in finding the appropriate directory, and no explicit set of profile files is provided via the -profiles option, then the command fails.
- -epoch latest
- Search for profile files in the latest epoch. This is the default.
- -epoch latest-k
- Search for profile files in the "k+1"th oldest epoch. For example, search in the third last epoch if "-epoch latest-2" is specified.
- -epoch all
- Search for profile files in all epochs.
- -epoch <name>
- Search for profile files in the named epoch. The epoch name should be the name of a subdirectory corresponding to a single epoch within the profile database directory. Epoch subdirectory names usually take the form YYMMDDHHMM (year-month-day-hours-minutes). For example, an epoch started on December 4, 1996 at 23:34 is named 9612042334. If an epoch is given a symbolic name by creating a symbol link to the actual epoch directory, then the symbolic name can also be used as an argument to the -epoch option.
- -events all
- Search for profile files corresponding to all event types such as cycles, icache misses, branch mispredictions, etc. This is the default.
- -events type(+type)*
- Search for profiles files for the specified event types. For example, search for cycles, icache misses, and data cache misses when the option -events cycles+imiss+dmiss is specified.
- -events all(-type)*
- Search for profile files for all event types except for the specified types. For example, search for all event types except for branch mispredictions when the option -events all-branchmp is specified.
- -label <label>
- Search for profile files with the specified label (see dcpilabel). If no labels are specified on the command line, profile file labels are ignored entirely. If any labels are specified on the command line (this option can be repeated several times), only profile files that have one of the specified labels are used.
- -profiles <file names...> --
- Use just the profile files named by the specified file names. The list of profile file names can be terminated either via --, or by the end of the option list. The command prints an error message and fails if the -profiles option is used in conjunction with any of the earlier automatic profile finding options. (Use either the automatic profile lookup mechanism, or explicitly name the profile file with the -profile option, but not both.)
Using pixstats(1) with profiles generated by dcpi2pix is known to give incorrect procedure-level information. Pixstats relies on having exact basic-block counts and only checks to see if a basic block starts a new procedure when the basic block's count is bigger than 0. If the entry basic block for a procedure does not accrue any samples during profiling using the Continuous Profiling Infrastructure, then the basic block's effects will be incorrectly attributed to a previous procedure in the image.
- pixie image
- Run pixie(1) over executable image, producing the file image.Addrs containing the address of each basic block in image, and the pixified executable file image.pixie. The image.pixie file can be deleted since it is not needed by dcpi2pix.
- dcpid db; run image; dcpiflush
- Get cycles samples for image.
- dcpi2pix -conf_low image -db db
- Run dcpi2pix over executable image and cycles samples in db, producing the pixie-format file image.Counts. Note that dcpi2pix automatically loads the image.Addrs file generated by pixie.
- pixstats image
- Run pixstats(1) over executable image and image.Counts, generating a program execution analysis report.
- 1.16
- First version to use dcpicalc's heuristics for estimating execution counts.
- 1.10
- First external release beyond SRC/WRL.
dcpi(1), dcpiflow(1), dcpiprof(1), dcpilist(1), dcpidis(1), dcpiscan(1), dcpiepoch(1), dcpiflush(1), dcpicalc(1), dcpilabel(1), dcpi2ps(1), dcpicat(1), dcpiquit(1), dcpidiff(1), dcpitopstalls(1), dcpiwhatcg(1), dcpictl(1), dcpisource(1), dcpicc(1), dcpiversion(1), dcpiuninstall(1), dcpikdiff(1), dcpix(1), dcpisumxct(1), dcpistats(1), dcpid(1), dcpiformat(4), dcpiloader(5)
For more information, see the DIGITAL Continuous Profiling Infrastructure project home page (http://www.research.digital.com/SRC/dcpi/ from outside DIGITAL).
This page was generated automatically by mtex software.Jeff Dean, Mark Vandevoorde, Carl Waldspurger