svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
cpc_set_add_request(3cpc)
cpc_...eate(3CPC) CPU Performance Counters Library Functions cpc_...eate(3CPC)
NAME
cpc_set_create, cpc_set_destroy, cpc_set_add_request, cpc_walk_requests
- manage sets of counter requests
SYNOPSIS
cc [ flag... ] file... -lcpc [ library... ]
#include <libcpc.h>
cpc_set_t *cpc_set_create(cpc_t *cpc);
int cpc_set_destroy(cpc_t *cpc, cpc_set_t *set);
int cpc_set_add_request(cpc_t *cpc, cpc_set_t *set,
const char *event, uint64_t preset, uint_t flags,
uint_t nattrs, const cpc_attr_t *attrs);
void cpc_walk_requests(cpc_t *cpc, cpc_set_t *set, void *arg,
void (*action)(void *arg, int index, const char *event,
uint64_t preset, uint_t flags, int nattrs,
const cpc_attr_t *attrs));
DESCRIPTION
The cpc_set_create() 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 or hardware sampling present on the processor. The cpc_set_t
data structure is opaque and must not be accessed directly by the ap‐
plication.
Applications wanting to program one or more performance counters and
hardware sampling must create an empty set with cpc_set_create() and
add requests to the set with cpc_set_add_request(). Once all requests
have been added to a set, the set must be bound to the hardware perfor‐
mance counters (see cpc_bind_curlwp(), cpc_bind_pctx(), and
cpc_bind_cpu(), all described on cpc_bind_curlwp(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 for the
CPC request and the sampling buffer is created to store the sampling
results for the SMPL request. These are stored and managed in CPC
buffers separate from the CPC set whose requests are being counted. See
cpc_buf_create(3CPC) and cpc_set_sample(3CPC).
The cpc_set_add_request() function specifies a configuration of a hard‐
ware counter and a hardware sampling. The arguments to cpc_set_add_re‐
quest() are:
event A string containing the name of an event supported by
the system's processor. The cpc_walk_events_all(),
cpc_walk_events_all_common(), cpc_walk_events_pic(),
and cpc_walk_events_pic_common() functions (all de‐
scribed on cpc_npic(3CPC)) can be used to query the
processor for the names of available 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:
CPC_COUNT_USER
The counter should count events that occur while
the processor is in user mode.
CPC_COUNT_SYSTEM
The counter should count events that occur while
the processor is in privileged mode.
CPC_OVF_NOTIFY_EMT
For a CPU performance counter (CPC) request, you
can request a signal to be sent to the application
when the physical counter overflows. A SIGEMT sig‐
nal is delivered if the processor is capable of
delivering an interrupt when the counter counts
past its maximum value. All CPC requests in the
set containing the counter that overflowed are
stopped until the set is rebound.
For a hardware sampling (SMPL) request, you can
request a signal to be sent to the application
when the specified number of SMPL records for the
SMPL request have been collected. A SIGEMT signal
is delivered if the processor is capable of deliv‐
ering an interrupt when a certain number of SMPL
records have been collected. SMPL requests will
not be stopped even after any SMPL request in the
set has collected the requested number of SMPL
records and the counter associated with any CPC
request in the set overflowed.
CPC_HW_SMPL
When adding a hardware sampling (SMPL) request,
this flag must be specified. When adding a CPU
performance counter (CPC) request, this flag
should not be specified.
At least one of CPC_COUNT_USER or CPC_COUNT_SYSTEM
must be specified to program the hardware for count‐
ing.
nattrs, attrs The nattrs argument specifies the number of attributes
pointed to by the attrs argument, which is an array of
cpc_attr_t structures containing processor-specific
attributes that modify the request's configuration.
The cpc_walk_attrs() and cpc_walk_attrs_common() func‐
tions (see cpc_npic(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, al‐
lowing the application to dispose of it immediately
after calling cpc_set_add_request().
When adding a SMPL request, the number of SMPL records
to collect must be requested by using the smpl_nrecs
attribute, which should be an integer value greater
than 0 and equal to or smaller than the supported max‐
imum value returned by cpc_get_max_smpl_rec_count()
function.
The cpc_walk_requests() function calls the action function on each re‐
quest that has been added to the set. The arg argument is passed unmod‐
ified to the action function with each call. The flag argument passed
to action function will include CPC_HW_SMPL flag for a SMPL request.
Note that the flag is not included for a CPC request.
RETURN VALUES
Upon successful completion, cpc_set_create() returns a handle to the
opaque cpc_set_t data structure. Otherwise, NULL is returned and errno
is set to indicate the error.
Upon successful completion, cpc_set_destroy() returns 0. Otherwise, -1
is returned and errno is set to indicate the error.
Upon successful completion, cpc_set_add_request() 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.
ERRORS
These functions will fail if:
EINVAL An event, attribute, or flag passed to cpc_set_add_request()
was invalid.
For cpc_set_destroy() and cpc_set_add_request(), the set pa‐
rameter was not created with the given cpc_t.
ENOMEM There was not enough memory available to the process to cre‐
ate the library's data structures.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelSafe
SEE ALSO
cpc_bind_curlwp(3CPC), cpc_buf_create(3CPC), cpc_npic(3CPC), cpc_seter‐
rhndlr(3CPC), strtol(3C), libcpc(3LIB), attributes(7)
NOTES
The system automatically determines which particular physical counter
to use to count the events specified by each request. Applications can
force the system to use a particular counter by specifying the counter
number in an attribute named picnum that is passed to cpc_set_add_re‐
quest(). Counters are numbered from 0 to n - 1, where n is the number
of counters in the processor as returned by cpc_npic(3CPC) for a CPC
request and by cpc_smpl_npic(3CPC) for a SMPL request.
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 configuration, or an attempt to bind the set will
return EINVAL. If a cpc_errhndlr_t has been registered with cpc_seter‐
rhndlr(3CPC), the error handler is called with subcode CPC_CONFLICT‐
ING_REQS. 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 CPC_COUNT_USER while pic1
is programmed with CPC_COUNT_SYSTEM. Refer to the hardware documenta‐
tion referenced by cpc_cpuref(3CPC) for details about a particular
processor's performance instrumentation hardware.
Oracle Solaris 11.4 20 Aug 2007 cpc_...eate(3CPC)