CPU Performance Counters Library Functions cpcsetcreate(3CPC)
NAME
cpcsetcreate, cpcsetdestroy, cpcsetaddrequest,
cpcwalkrequests - manage sets of counter requests
SYNOPSIS
cc [ flag... ] file... -lcpc [ library... ]
#include
cpcsett *cpcsetcreate(cpct *cpc);
int cpcsetdestroy(cpct *cpc, cpcsett *set);
int cpcsetaddrequest(cpct *cpc, cpcsett *set,
const char *event, uint64t preset, uintt flags,
uintt nattrs, const cpcattrt *attrs);
void cpcwalkrequests(cpct *cpc, cpcsett *set, void *arg,
void (*action)(void *arg, int index, const char *event,
uint64t preset, uintt flags, int nattrs,
const cpcattrt *attrs));
DESCRIPTION
The cpcsetcreate() function returns an initialized and
empty CPC set. A CPC set contains some number of requests,
where a request represents a specific configuration of a
hardware performance instrumentation counter present on the
processor. The cpcsett data structure is opaque and must
not be accessed directly by the application.
Applications wanting to program one or more performance
counters must create an empty set with cpcsetcreate() and
add requests to the set with cpcsetaddrequest(). Once all
requests have been added to a set, the set must be bound to
the hardware performance counters (see cpcbindcurlwp(),
cpcbindpctx(), and cpcbindcpu(), all described on
cpcbindcurlwp(3CPC)) before counting events. At bind time,
the system attempts to match each request with an available
physical counter capable of counting the event specified in
the request. If the bind is successful, a 64-bit virtualized
counter is created to store the counts accumulated by the
hardware counter. These counts are stored and managed in CPC
buffers separate from the CPC set whose requests are being
counted. See cpcbufcreate(3CPC) and cpcsetsample(3CPC).
The cpcsetaddrequest() function specifies a configuration
of a hardware counter. The arguments to
SunOS 5.11 Last change: 20 Aug 2007 1
CPU Performance Counters Library Functions cpcsetcreate(3CPC)
cpcsetaddrequest() are:
event A string containing the name of an event
supported by the system's processor. The
cpcwalkeventsall() and
cpcwalkeventspic() functions (both
described on cpcnpic(3CPC)) can be used to
query the processor for the names of avail-
able events. Certain processors allow the
use of raw event codes, in which case a
string representation of an event code in a
form acceptable to strtol(3C) can be used
as the event argument.
preset The value with which the system initializes
the counter.
flags Three flags are defined that modify the
behavior of the counter acting on behalf of
this request:
CPCOUNTUSER
The counter should count events that
occur while the processor is in user
mode.
CPCOUNTSYSTEM
The counter should count events that
occur while the processor is in
privileged mode.
CPCOVFNOTIFYEMT
Request a signal to be sent to the
application when the physical counter
overflows. A SIGEMT signal is delivered
if the processor is capable of deliver-
ing an interrupt when the counter
counts past its maximum value. All
requests in the set containing the
counter that overflowed are stopped
until the set is rebound.
At least one of CPCOUNTUSER or
CPCOUNTSYSTEM must be specified to pro-
gram the hardware for counting.
SunOS 5.11 Last change: 20 Aug 2007 2
CPU Performance Counters Library Functions cpcsetcreate(3CPC)
nattrs, attrs The nattrs argument specifies the number of
attributes pointed to by the attrs argu-
ment, which is an array of cpcattrt
structures containing processor-specific
attributes that modify the request's confi-
guration. The cpcwalkattrs() function
(see cpcnpic(3CPC)) can be used to query
the processor for the list of attributes it
accepts. The library makes a private copy
of the attrs array, allowing the applica-
tion to dispose of it immediately after
calling cpcsetaddrequest().
The cpcwalkrequests() function calls the action function
on each request that has been added to the set. The arg
argument is passed unmodified to the action function with
each call.
RETURN VALUES
Upon successful completion, cpcsetcreate() returns a han-
dle to the opaque cpcsett data structure. Otherwise, NUL
is returned and errno is set to indicate the error.
Upon successful completion, Cpcsetdestroy() returns 0.
Otherwise, -1 is returned and errno is set to indicate the
error.
Upon successful completion, cpcsetaddrequest() returns an
integer index used to refer to the data generated by that
request during data retrieval. Otherwise, -1 is returned and
errno is set to indicate the error.
ERORS
These functions will fail if:
EINVAL An event, attribute, or flag passed to
cpcsetaddrequest() was invalid.
For cpcsetdestroy() and cpcsetaddrequest(),
the set parameter was not created with the given
cpct.
ENOMEM There was not enough memory available to the pro-
cess to create the library's data structures.
SunOS 5.11 Last change: 20 Aug 2007 3
CPU Performance Counters Library Functions cpcsetcreate(3CPC)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
SEE ALSO
cpcbindcurlwp(3CPC), cpcbufcreate(3CPC), cpcnpic(3CPC),
cpcseterrhndlr(3CPC), libcpc(3LIB), strtol(3C), attri-
butes(5)
NOTES
The system automatically determines which particular physi-
cal counter to use to count the events specified by each
request. Applications can force the system to use a particu-
lar counter by specifying the counter number in an attribute
named picnum that is passed to cpcsetaddrequest().
Counters are numbered from 0 to n - 1, where n is the number
of counters in the processor as returned by cpcnpic(3CPC).
Some processors, such as UltraSPARC, do not allow the
hardware counters to be programmed differently. In this
case, all requests in the set must have the same configura-
tion, or an attempt to bind the set will return EINVAL. If a
cpcerrhndlrt has been registered with
cpcseterrhndlr(3CPC), the error handler is called with sub-
code CPCONFLICTINGREQS. For example, on UltraSPARC pic0
and pic1 must both program events in the same processor mode
(user mode, kernel mode, or both). For example, pic0 cannot
be programmed with CPCOUNTUSER while pic1 is programmed
with CPCOUNTSYSTEM. Refer to the hardware documentation
referenced by cpccpuref(3CPC) for details about a particu-
lar processor's performance instrumentation hardware.
SunOS 5.11 Last change: 20 Aug 2007 4
|
