sprofil(2) sprofil(2)
NAME [Toc] [Back]
sprofil() - execution time profile for disjointed text spaces
SYNOPSIS [Toc] [Back]
#include <sys/time.h>
#include <sys/profil.h>
int sprofil(
struct prof *profp,
int profcnt,
struct timeval *tvp,
unsigned int flags
);
DESCRIPTION [Toc] [Back]
sprofil() controls profiling, by which the system maintains estimates
of the amount of time the calling program spends executing at various
places in its address space. It differs from its predecessor profil(2)
in that it allows simultaneous profiling of many disjointed regions of
memory.
profp must point to an ordered array of prof structures.
The prof structure is defined as:
struct prof {
void *pr_base; /* buffer base */
unsigned int pr_size; /* buffer size */
void *pr_offset; /* pc offset */
unsigned int pr_scale; /* pc scaling */
};
profcnt specifies the number of prof structures in the profp array.
If profcnt is 0, profiling is disabled.
If non-NULL, tvp points to a struct timeval which on return contains
the time value corresponding to one clock tick.
The only valid flags values are PROF_USHORT, PROF_UINT, and
PROF_UINT64. The flags parameter must be set to one of these values.
When profiling is enabled, each thread's program counter (pc) is
examined each clock tick (CLK_TICK times per second), and the system
searches the profp array for a region that includes pc.
Each prof structure is interpreted as follows:
pr_base must point to an area of memory whose length (in
bytes) is given by pr_size. This memory must not be
modified or freed while profiling is enabled. This memory
is treated as an array of 2, 4 or 8-byte elements
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
sprofil(2) sprofil(2)
corresponding to the PROF_USHORT, PROF_UINT, or PROF_UINT64
flag specified by the flags parameter.
pr_size must be a non-zero multiple of the element size.
pr_offset is the start address of the region to be profiled.
Note that it is always interpreted as a text address and
never as the address of a function descriptor.
pr_scale is interpreted as an unsigned, fixed-point value
with sixteen bits to the right of the binary point.
The pc value falls within a region if ( offset = (( pc-pr_offset)*
pr_scale ) / 65536) < pr_size
If a matching region is found, offset is rounded down to a 2, 4 or 8-
byte boundary corresponding to the element size specified by the flags
parameter. The element at pr_base + offset is incremented by 1,
unless that would result in overflow.
If the calculation above results in an invalid address, profiling is
silently disabled.
The profp array must be sorted in ascending order by pr_offset value.
The profiling regions must not overlap.
If a pr_scale field is set to 0 or 1, the corresponding prof array
entry is ignored.
The last entry in the profp array is special. If its pr_offset field
is set to 0 and its pr_scale field is set to 2, it is treated as an
overflow descriptor. In this case, its pr_size field must be set to
the size of one element. If the pc value did not fall within the
range of one of the preceding descriptors, the single element
specified by the pr_base field is incremented, unless that would
result in overflow.
Each call to sprofil() disables profiling if it was enabled and then
enables profiling of the regions specified by the prof array entries.
Due to variations in instruction length on different architectures,
the pr_scale setting results in different entry-to-instruction ratios.
The following tables show the number of instructions that map into
each element of the array that pr_base points to based on instruction
size, pr_scale and flags.
On PA-RISC machines, instructions are 4 bytes each.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
sprofil(2) sprofil(2)
________________________________________________
|Scale | PROF_USHORT PROF_UINT PROF_UINT64 |
|_______|_______________________________________|
| 2 | 16384 32768 65536 |
| 4 | 8192 16384 32768 |
| 8 | 4096 8192 16384 |
| 16 | 2048 4096 8192 |
| 32 | 1024 2048 4096 |
| 64 | 512 1024 2048 |
| 128 | 256 512 1024 |
| 256 | 128 256 512 |
| 512 | 64 128 256 |
| 1024 | 32 64 128 |
| 2048 | 16 32 64 |
| 4096 | 8 16 32 |
| 8192 | 4 8 16 |
| 16384 | 2 4 8 |
| 32768 | 1 2 4 |
| 65536 | 0.5 1 2 |
|131072 | 0.25 0.5 1 |
|_______|_______________________________________|
On Itanium-based machines, pc points to a 16-byte bundle containing
three instructions. It is not possible to profile individual
instructions.
_______________________________________________
|Scale | PROF_USHORT PROF_UINT PROF_UINT64 |
|______|_______________________________________|
| 2 | 4096 8192 16384 |
| 4 | 2048 4096 8192 |
| 8 | 1024 2048 4096 |
| 16 | 512 1024 2048 |
| 32 | 256 512 1024 |
| 64 | 128 256 512 |
| 128 | 64 128 256 |
| 256 | 32 64 128 |
| 512 | 16 32 64 |
| 1024 | 8 16 32 |
| 2048 | 4 8 16 |
| 4096 | 2 4 8 |
| 8192 | 1 2 4 |
|16384 | 0.5 1 2 |
|32768 | 0.25 0.5 1 |
|______|_______________________________________|
Note that a 1-1 mapping of PROF_UINT counters consumes twice as much
space as for PROF_USHORT counters, and should only be used in those
cases where you expect a 16-bit counter to overflow. Likewise, a 1-1
mapping of PROF_UINT64 counters consumes twice as much space as for
PROF_UINT counters, and should only be used in those cases where you
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
sprofil(2) sprofil(2)
expect a 32-bit counter to overflow.
The results of specifying a pr_scale that corresponds to an
instruction-to-profiling element ratio smaller than 1-1 mapping
produces undefined behavior.
If overlapping text regions are specified, then the pr_base associated
with the largest offset less than the value of the program counter
(pc) gets incremented. If more than one text region has the same
offset, the first one is chosen.
A text region with the pr_offset of 0 and pr_scale of 0x0002 acts as
an overflow bin. Any pc value not previously matched or outside the
regions of text space specified is considered to match this text
region and the first counter of the specified pr_base is incremented.
If specified, such an overflow bin should always be last in the list
of specified regions.
Notes [Toc] [Back]
Profiling is turned off when an exec(2) is executed, but remains on in
both child and parent processes after a fork(2).
A call to profil(2) has the same effect as calling sprofil() with just
one member in the profp array with the fields profcnt, tvp, and flags
taking on the values of 1, NULL, and PROF_USHORT respectively.
RETURN VALUE [Toc] [Back]
On success, sprofil() returns 0. Otherwise, it returns -1 and sets
the global variable errno to indicate the error.
ERRORS [Toc] [Back]
The sprofil()functionfailsif:
[E2BIG] profcnt was less than or equal to 0, or greater than
sysconf(_SC_PROFIL_MAX).
[EFAULT] Either profp or tvp points to an illegal address.
[EINVAL] The flags parameter is not valid or a pr_size field is
zero or greater than (2^46 * pr_scale) / 65536 or is
not a multiple of the element size or the overflow
descriptor is not last in the list of specified regions
or is more than one element long or the regions are not
sorted in ascending order by pr_offset or the regions
overlap.
SEE ALSO [Toc] [Back]
profil(2), prof(1), intro(2), monitor(3C), smonitor(3C), times(2).
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003 [ Back ] |
