HP DCPI tool

dcpiformat(4)

NAME

dcpiformat - DIGITAL Continuous Profiling Infrastructure profile file format.

DESCRIPTION

Each DIGITAL Continuous Profiling Infrastructure profile file contains the samples collected for some particular program or shared-library. A profile file has two parts. The first part is a human-readable ASCII header. The second part is a binary encoding of the samples associated with each distinct instruction address in the image to which this profile belongs.

ASCII HEADER

The header has the following form:

	<header>	: <line>+ <terminator>
	<terminator>	: "samples" <space>* "\n"
	<line>		: <required> "\n"
			| <optional> "\n"
			| <unknown>  "\n"
	<required>	: "version"	<space>+ pdb-<major>.<minor>
			| "image"	<space>+ <hex_digit>+
			| "epoch"	<space>+ <time>
			| "platform"	<space>+ <rest_of_line>
			| "event"	<space>+ <rest_of_line>
			| "period"	<space>+ <digit>+
			| "tstart"	<space>+ <hex_digit>+
			| "tsize"	<space>+ <digit>+
			| "cpuspeed"	<space>+ <digit>+
	<optional>	: "cpuamask"	<space>+ <hex_digit>+
			| "cpuimplv"	<space>+ <digit>+
			| "cpucount"	<space>+ <digit>+
			| "period"	<space>+ <digit>+
			| "path"	<space>+ <rest_of_line>
	<unknown>	: <word>	<space>+ <rest_of_line>

	<major>		: <digit>+
	<minor>		: <digit>+
	<time>		: YYMMDDHHMM	   /* Digits indicating UCT time */
			| YYYYMMDDHHMMSS   /* (Not yet supported) */

	<space>		: [ \t]
	<hex_digit>	: <digit> | [a-f] | [A-F]
	<digit>		: [0-9]
	<word>		: [^ \t\n]+
	<rest_of_line>	: [^ \t\n][^\n]*

For each kind of line that falls under <required>, the profile header should contain exactly one occurrence of that line. To support future extensions to the file format, all programs that modify profile files should preserve all <unknown> header lines when writing out the modified profile.

The format of the binary data is dependent on the major version number present in the ASCII header. The current version number used by the profiling tools is 1.01. The documentation below describes the binary data format for the obsolete versions 0.06 and 0.07. We plan to document major-version 1 in the near future.

BINARY DATA FOR MAJOR-VERSION 0

The binary section of the profile begins immediately after the newline character that terminates the ASCII header. (No whitespace is allowed after the newline.) This section contains a mapping from each instruction address in the image, to a count of the number of samples associated with that address.

The binary section consists of a list of chunks, followed by a fixed length footer.

	<samples>	: <chunk>* <footer>

Each chunk contains the sample counts for a contiguous range of instruction addresses. For each address within this range, the chunk stores the number of samples associated with this address.

	<chunk>		: <offset> <number> <count>+
	<offset>	: <uint32>
	<number>	: <uint32>
	<count>		: <uint32>

The beginning of the address range is text_start(image) + <offset>, where text_start(image) is recorded in the tstart field in the profile header. The length of the address range is <number>. The number of <count> entries in the chunk is <number>. The number of samples associated with the ith address in the address range is given by the ith <count> entry in the chunk.

The instruction-address ranges associated with two distinct chunks in one profile cannot overlap. Furthermore, if two chunks a and b occur in the same profile and a occurs before b, then the offset associated with a has to be smaller than the offset associated with b.

The footer consists of two 4-byte values. The first value is the total number of instruction addresses in the image that have at least one associated sample. The second value is the sum of the sample counts associated with all of the instruction addresses in the image.

	<footer>	: <total_offsets> <total_samples>
	<total_offsets>	: <uint32>
	<total_samples>	: <uint32>

All values in the binary section are stored in little-endian format.

	<uint32>	/* Unsigned little-endian 32 bit value */

For good performance, the length of the ASCII header should be made a multiple of four (by adding extra whitespace at the end of the last line of the ASCII header) so that the binary section is aligned to a 32-bit boundary relative to the beginning of the profile.

VERSION HISTORY

This file documents version 0.07 of the profile file format.

SEE ALSO

dcpi(1), dcpiflow(1), dcpiprof(1), dcpilist(1), dcpidis(1), dcpiscan(1), dcpid(1), dcpiepoch(1), dcpiflush(1), dcpicalc(1), dcpilabel(1), dcpi2ps(1), dcpicat(1), dcpiquit(1), dcpidiff(1), dcpitopstalls(1), dcpiwhatcg(1), dcpictl(1)

For more information, see the HP Continuous Profiling Infrastructure project home page (http://h30097.www3.hp.com/dcpi).

COPYRIGHT

Copyright 1996-2004, Hewlett-Packard Development Company, L.P.

AUTHORS

Sanjay Ghemawat, Carl Waldspurger

This page was generated automatically by mtex software.