xprof_text(4)xprof_text(4)NAMExprof_text - profile feedback text file
DESCRIPTION
Text files generated and recognized, respectively, by xprof_btoa and
xprof_atob have the format described below.
FORMAT
/*
* Note on notation: in the comments below, a syntactic
* entity <x> associated with a printf/scanf format <f>
* is denoted as <x>(<f>) in its description.
*/
/*
* A profile feedback text file begins with a <header> containing
* version information, object file counts, and program counts.
*
* The <header> has the form
*
* PROFILE-FEEDBACK-DATA: <major>.<minor> \
* <n_objfiles> <n_programs> <n_proc_names>
*
* where
*
* <major>(%u), <minor>(%u) are the major and minor version
* numbers of the profile feedback text file format. The
* current <major>.<minor> version number is 3.1.
*
* <n_objfiles(%u)>, <n_programs(%u)>, and <n_proc_names(%u)>
* are the number of profiled object files, programs, and
* indirectly called procedure names, respectively.
*/
#define SUN_PROFDATA_MAJOR_VERSION 4
#define SUN_PROFDATA_MINOR_VERSION 3
/*
* Version information is followed by an <object file section>
* and a <program section>, whose records represent profiled
* object files and programs, respectively.
*
* An <object file section> has the form
*
* OBJFILE: <pathname> <n_procs> <tv_sec> <tv_usec> <n_values_per_vp>
* <signature> [<stats>] {<procedure section>}*
*
* where
*
* <pathname>(%s) is the resolved UNIX pathname of the object
* file, as recorded by the compiler using dladdr(3DL)
* and realpath(3C) at the time the object file was
* generated.
*
* <n_procs>(%u) is an unsigned decimal integer giving the number
* of profiled procedures or functions contained in the
* object file. The value of <n_procs> may be 0.
*
* <tv_sec>(%u) <tv_usec>(%u) are the tv_sec and tv_usec fields
* of a timeval structure returned by gettimeofday(3C) during
* code generation when the object file was compiled.
*
* <n_values_per_vp>(%u) is an unsigned decimal integer giving the
* number of values stored in each of the object file's
* value profile records.
*
* <signature>(0x%llx) is a 64 bit hexadecimal integer whose value
* is a hash of the signatures of the procedures defined in the
* object file. Its purpose is to detect differences between
* two compilations of a given object file.
*
* [<stats>] are optional profile counter statistics, which
* take one of the following forms:
* max <count>(%llu)
* sum <count>(%llu)
* where:
* <count>(%llu) is a 64 bit unsigned decimal integer
* representing either the maximum counter value or
* the sum of all counter values, over all counters
* in the object file profile.
* {<procedure section>}* is a series of <n_procs> procedure sections,
* each of which contains the profile data of one of the
* object file's procedures or functions.
*
* A <procedure section> has the form
*
* PROC: <proc_name> <signature> \
* <n_counters> <n_vp_sites> <n_vp_records> <id>
* [<stats>]
* {<counter record>}*
* {<value profile record>}*
*
* where
*
* <proc_name>(%s) is the procedure's linker symbol name
*
* <signature>(0x%llx) is a 64 bit hexadecimal integer whose
* value is a hash of the procedure's control flow graph (CFG)
* at the point in compilation where the CFG is associated with
* profile counters under -xprofile=collect and with profile
* counter values under -xprofile=use.
*
* The value of <signature> is used to detect differences
* in the input CFG between the two compilations, whether
* due to source code changes or due to code transformations
* applied earlier in the compilation process.
*
* <n_counters>(%u) is the number of counter records contained
* in the procedure section.
*
* <n_vp_exprs>(%u) is the number of value-profiled expressions
* contained in the procedure section.
*
* <n_vp_records>(%u) is the number of value profile records
* contained in the procedure section.
*
* <id>(%u) is an id number defined for use by the compiler.
*
* [<stats>] are optional statistics over the procedure,
* defined in the same manner as [<stats>] under
* <object file section>.
*
* A PROC record is optionallly followed by summary statistics,
* <n_counters> counter records and <n_vp_records> value profile records.
* Note that <n_counters>, <n_vp_sites> and <n_vp_records> may all be 0.
* The value of <n_counters> is 0 for a procedure that was loaded but
* not executed.
*
* A <counter record> has the form
*
* <counter id> <counter value>
*
* where
*
* <counter id>(%u) is a 32 bit unsigned integer id uniquely
* identifying a point of execution within the containing
* procedure or function. <counter id> may represent either
* a basic block or an edge of the procedure's CFG.
*
* <counter value>(%llu) is a 64 bit unsigned integer whose
* value is the number of times that the code at the point
* associated with <counter id> was executed.
*
* A <value profile record> consists of <n_values_per_vp>
* sub-records of the form:
*
* <type> <expr id> <count> <value>
*
* where
*
* <type>(%s) is a keyword string identifying the type
* of the profiled expression. The defined values
* of <type> and their associated C data types are:
*
* VP_INT signed int
* VP_LLONG signed long long int
* VP_FLOAT float
* VP_DOUBLE double
* VP_PROC pointer to indirectly called function
*
* <expr id>(%u) is a 32 bit unsigned integer id uniquely
* identifying a value profiled expression within
* the scope of the containing procedure.
*
* <count>(%llu) is a 64 bit unsigned integer whose value
* is the number of times that the profiled expression was
* observed to have the value represented by <value>.
*
* <value> represents one of the <n_values> most frequently
* observed values of the expression identified by <value>.
*
* If <count> is 0, the <value> field is empty; otherwise,
* its value can be scanned using scanf(3C) with a format
* string determined by the <type> keyword:
*
* VP_INT %d
* VP_LLONG %lld
* VP_FLOAT %g
* VP_DOUBLE %lg
* VP_PROC %s
*
* If <type> = VP_PROC, the form of the <value> field is
* <entry name>:<objfile pathname>
* where
* <entry name> is the called function's entry name
* <objfile pathname> is the UNIX pathname of the object
* file containing the called function.
* If the called function is not profiled, the <value> field
* is empty.
*
* A <program section> has the form
*
* PROGRAM: <pathname> <n_objfiles>
* [<stats>]
* {OBJREF: <objfile name>}*
*
* where
*
* <pathname>(%s) is the UNIX pathname of a profiled executable
* or shared library, as returned by dladdr(3DL) and
* realpath(3C) at the time the executable or shared
* library was loaded for execution.
*
* <n_objfile_refs>(%u) is an unsigned decimal number whose
* value is the number of profiled object files contained
* in the executable or shared library.
*
* [<stats>] are optional statistics over the profiled executable
* or shared library, defined in the same manner as [<stats>]
* under <object file section>.
*
* {<objfile_name>(%s)}* is a series of <n_objfiles> object
* file name records, where each record contains the keyword
* OBJREF: followed by the UNIX pathname of an object
* file included in the executable or shared library. The
* referenced object file must have been previously defined
* in an <object file section>.
*
*/
April 2009 xprof_text(4)
