svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
cpc_cpuref(3cpc)
CPU Performance Counters Library Functions cpc_npic(3CPC)
NAME
cpc_npic, cpc_smpl_npic, cpc_caps, cpc_cciname, cpc_smpl_iname,
cpc_cpuref, cpc_walk_events_all, cpc_walk_events_all_common,
cpc_walk_generic_events_all, cpc_walk_events_pic,
cpc_walk_events_pic_common, cpc_walk_generic_events_pic,
cpc_walk_attrs, cpc_walk_attrs_common, cpc_walk_smpl_recitems,
cpc_get_smpl_max_rec_count, cpc_walk_smpl_recitems_req - determine CPU
performance counter configuration
SYNOPSIS
cc [ flag... ] file... -lcpc [ library... ]
#include <libcpc.h>
uint_t cpc_npic(cpc_t *cpc);
uint_t cpc_smpl_npic(cpc_t *cpc);
uint_t cpc_caps(cpc_t *cpc);
const char *cpc_cciname(cpc_t *cpc);
const char *cpc_smpl_iname(cpc_t *cpc);
const char *cpc_cpuref(cpc_t *cpc);
void cpc_walk_events_all(cpc_t *cpc, void *arg,
void (*action)(void *arg, const char *event));
void cpc_walk_events_all_common(cpc_t *cpc, void *arg,
int target, void (*action) (void *arg, const char *event));
void cpc_walk_generic_events_all(cpc_t *cpc, void *arg,
void (*action)(void *arg, const char *event));
void cpc_walk_events_pic(cpc_t *cpc, uint_t picno, void *arg,
void (*action)(void *arg, uint_t picno, const char *event));
void cpc_walk_events_pic_common(cpc_t *cpc, uint_t picno, void *arg,
int target, void (*action)(void *arg, uint_t picno, const char *event));
void cpc_walk_generic_events_pic(cpc_t *cpc, uint_t picno,
void *arg, void (*action)(void *arg, uint_t picno,
const char *event));
void cpc_walk_attrs(cpc_t *cpc, void *arg,
void (*action)(void *arg, const char *attr));
void cpc_walk_attrs_common(cpc_t *cpc, void *arg,
int target, void (*action) (void *arg, const char *attr));
void cpc_walk_smpl_recitems(cpc_t *cpc, void *arg,
void (*action)(void *arg, const char *name, int record_item_index));
void cpc_walk_smpl_recitems_req(cpc_t *cpc, cpc_set_t *set, int request_index, void *arg,
void (*action)(void *arg, cpc_set_t *set, int request_index,
const char *name, int record_item_index));
int cpc_get_smpl_max_rec_count(cpc_t *cpc, uint_t max_rec_count);
DESCRIPTION
The cpc_cciname() function returns a printable description of the pro‐
cessor performance counter interfaces, for example, the string Ultra‐
SPARC III+ & IV. This name should not be assumed to be the same as the
name the manufacturer might otherwise ascribe to the processor. It sim‐
ply names the performance counter interfaces as understood by the sys‐
tem, and thus names the set of performance counter events that can be
described by that interface.
The cpc_smpl_iname() function returns the hardware sampling implementa‐
tion name available on the processor. Currently, only PEBS for Intel
Precise Events Based Sampling is supported as the hardware sampling
implementation name.
The cpc_cpuref() function returns a string that describes a reference
work that should be consulted to (allow a human to) understand the
semantics of the performance counter events that are known to the sys‐
tem. The string returned might be substantially longer than 80 charac‐
ters. Callers printing to a terminal might want to insert line breaks
as appropriate.
The cpc_npic() function returns the number of performance counters for
CPC accessible on the processor. On the processor that shares the per‐
formance counters between CPC and SMPL, the reported number is still
the one counting the performance counters that could be used for CPC.
Therefore, the number may contain the one for the performance counters
that could be also used for SMPL.
The cpc_smpl_npic() function returns the number of performance counters
for SMPL accessible on the processor. On the processor that shares the
performance counters between CPC and SMPL, the reported number is still
the one counting the performance counters that could be used for SMPL.
Therefore, the number may contain the one for the performance counters
that could be also used for CPC. If the specified cpc has not been suc‐
cessfully opened for SMPL, cpc_smpl_npic() sets EINVAL to errno and
returns 0.
The cpc_caps() function returns a bitmap containing the bitwise inclu‐
sive-OR of zero or more flags that describe the capabilities of the
processor. If CPC_CAP_OVERFLOW_INTERRUPT is present, the processor can
generate an interrupt when a hardware performance counter overflows. If
CPC_CAP_OVERFLOW_PRECISE is present, the processor can determine pre‐
cisely which counter overflowed, thereby affecting the behavior of the
overflow notification mechanism described in cpc_bind_curlwp(3CPC). If
CPC_CAP_SMPL is present, the hardware sampling is available on the pro‐
cessor. If CPC_CAP_OVERFLOW_SMPL is present, the hardware sampling
available on the processor supports the overflow. If cpc_open() with
CPC_VER_CURRENT successfully returned a CPC handle, it is still unknown
if the CPC handle can work not only for CPC but also SMPL. To determine
if the CPC handle can work for SMPL, cpc_caps () needs to be used to
check CPC_CAP_SMPL is present in the returned capabilities.
The system maintains a list of performance counter events supported by
the underlying processor. Some processors are able to count all events
on all hardware counters, while other processors restrict certain
events to be counted only on specific hardware counters. The system
also maintains a list of processor-specific attributes that can be used
for advanced configuration of the performance counter hardware. These
functions allow applications to determine what events and attributes
are supported by the underlying processor. The reference work pointed
to by cpc_cpuref() should be consulted to understand the reasons for
and use of the attributes.
The cpc_walk_events_all() function calls the action function on each
element of a global event list that supports CPC. The action function
is called with each event supported by the processor, regardless of
which counter is capable of counting it. The action function is called
only once for each event, even if that event can be counted on more
than one counter.
The cpc_walk_events_all_common() function calls the action function on
each element of a global event list that supports the performance moni‐
toring type specified by target. The supported performance monitoring
type is either CPC_CPC for specifying the CPC performance events or
CPC_SMPL for specifying the SMPL performance events. The
cpc_walk_events_all_common() function with CPC_CPC as target is equiva‐
lent to cpc_walk_events_all().
The Supported macros for target are:
CPC_CPC for specifying CPC performance monitoring type
CPC_SMPL for specifying SMPL performance monitoring type
The cpc_walk_events_pic() function calls the action function with each
CPC event supported by the counter indicated by the picno argument,
where picno ranges from 0 to the value returned by cpc_npic().
The cpc_walk_events_pic_common() function calls the action function
with each event associated with the performance monitoring type speci‐
fied by target and supported by the counter indicated by picno argu‐
ment, where picno ranges [0, value returned by cpc_npic()) when target
is CPC_CPC, or [0, value returned by cpc_smpl_npic()) when target is
CPC_SMPL.
The system maintains a list of platform independent performance counter
events known as generic events (see generic_events(3CPC)).
The cpc_walk_generic_events_all() function calls the action function on
each generic event available on the processor. The action function is
called for each generic event, regardless of which counter is capable
of counting it. The action function is called only once for each event,
even if that event can be counted on more than one counter.
The cpc_walk_generic_events_pic() function calls the action function
with each generic event supported by the counter indicated by the picno
argument, where picno ranges from 0 to the value returned by
cpc_npic().
The system maintains a list of attributes that can be used to enable
advanced features of the performance counters on the underlying proces‐
sor. The cpc_walk_attrs() function calls the action function for each
attribute name supported for CPC.
The cpc_walk_attrs_common() function calls the action function for each
attribute name supported for the performance monitoring type specified
by target. The function cpc_walk_attrs_common() with CPC_CPC as target
is equivalent to cpc_walk_attrs().
See the reference material as returned by cpc_cpuref(3CPC) for the
semantics use of attributes.
The result of the SMPL request is stored in the CPC buffers. It can be
accessed as a form of SMPL record that is an array of uint64_t objects
by using cpc_buf_smpl_get_record() and cpc_buf_smpl_get_item(). How
many record items are contained in a SMPL record and what kind of
record items are included in the SMPL record are platform dependent.
The format of the SMPL record is the layout of record items within a
record. The format of the SMPL record is common among any SMPL events
and any SMPL performance counters on the same processor. The validity
of the kind of record items included in the SMPL record are may vary
depending on the type of SMPL performance counter used and the type of
SMPL event that is requested. The cpc_walk_smpl_recitems() function is
used to determine the kind of record items that are contained in the
SMPL record on this processor. And, cpc_walk_smpl_recitems_req() func‐
tion is used to determine the valid record items in the SMPL record for
a certain SMPL request.
The cpc_walk_smpl_recitems() function calls the action function on each
item in the SMPL record. name is the name string of the SMPL record
item. record_item_index is the integer value index to refer the item in
the SMPL record.
The cpc_walk_smpl_recitems_req() function calls action function on each
item in the SMPL record supported by the SMPL request specified by set
and request_index_name is the name string of the SMPL record item.
record_item_index is the integer value index to refer the item in the
SMPL record.
The cpc_get_smpl_max_rec_count() function returns the maximum number
of SMPL records per a request supported by the kernel for the sampling
hardware on the processor into the uint_t object pointed to by
max_rec_count. The request indicates that one performance monitoring
request is added by cpc_set_add_request(). When adding a SMPL request
using cpc_set_add_request(), the application needs to specify the num‐
ber of SMPL records that should be collected for the request, using
smpl_nrecs attribute. The kernel limits the maximum number of SMPL
records for one request that can be returned to the application at one
time, depending on the underlying sampling hardware. The
cpc_get_smpl_max_rec_count() returns the maximum number that can be
specified to smpl_nrecs attribute.
RETURN VALUES
The cpc_cciname() function always returns a printable description of
the processor performance counter interfaces.
The cpc_smpl_iname() function always returns a printable description of
the hardware sampling implementation available on the processor.
The cpc_cpuref() function always returns a string that describes a ref‐
erence work.
The cpc_npic() function always returns the number of performance coun‐
ters accessible on the processor.
The cpc_smpl_npic() function always returns the number of performance
counters for SMPL accessible on the processor.
The cpc_caps() function always returns a bitmap containing the bitwise
inclusive-OR of zero or more flags that describe the capabilities of
the processor.
If the user-defined function specified by action is not called, the
cpc_walk_events_all(), cpc_walk_events_all_common(),
cpc_walk_events_pic(), cpc_walk_events_pic_common(), cpc_walk_attrs(),
cpc_walk_attrs_common(), cpc_walk_generic_events_pic(),
cpc_walk_smpl_recitems(), and cpc_walk_smpl_recitems_req() functions
set errno to indicate the error.
The cpc_get_smpl_max_rec_count() sets errno to EINVAL and returns -1 if
cpc was not successfully opened for SMPL. Otherwise,
cpc_get_smpl_max_rec_count() returns 0.
ERRORS
The cpc_walk_events_all(), cpc_walk_events_all_common(),
cpc_walk_events_pic(), cpc_walk_events_pic_common(), cpc_walk_attrs(),
cpc_walk_attrs_common(), cpc_walk_generic_events_pic(),
cpc_walk_smpl_recitems(), and cpc_walk_smpl_recitems_req() functions
will fail if:
ENOMEM There is not enough memory available.
The cpc_get_smpl_max_rec_count() function will fail if:
EINVAL CPC was not successfully opened with SMPL.
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), generic_events(3CPC), libcpc(3LIB),
attributes(7)
Oracle Solaris 11.4 8 Oct 2008 cpc_npic(3CPC)