CPU Performance Counters Library Functions cpcnpic(3CPC)
NAME
cpcnpic, cpccaps, cpccciname, cpccpuref,
cpcwalkeventsall, cpcwalkgenericeventsall,
cpcwalkeventspic, cpcwalkgenericeventspic,
cpcwalkattrs - determine CPU performance counter confi-
guration
SYNOPSIS
cc [ flag... ] file... -lcpc [ library... ]
#include
uintt cpcnpic(cpct *cpc);
uintt cpccaps(cpct *cpc);
const char *cpccciname(cpct *cpc);
const char *cpccpuref(cpct *cpc);
void cpcwalkeventsall(cpct *cpc, void *arg,
void (*action)(void *arg, const char *event));
void cpcwalkgenericeventsall(cpct *cpc, void *arg,
void (*action)(void *arg, const char *event));
void cpcwalkeventspic(cpct *cpc, uintt picno, void *arg,
void (*action)(void *arg, uintt picno, const char *event));
void cpcwalkgenericeventspic(cpct *cpc, uintt picno,
void *arg, void (*action)(void *arg, uintt picno,
const char *event));
void cpcwalkattrs(cpct *cpc, void *arg,
void (*action)(void *arg, const char *attr));
DESCRIPTION
The cpccciname() function returns a printable description
of the processor performance counter interfaces, for exam-
ple, the string UltraSPARC I] & IV. This name should not
be assumed to be the same as the name the manufacturer might
otherwise ascribe to the processor. It simply names the per-
formance counter interfaces as understood by the system, and
thus names the set of performance counter events that can be
SunOS 5.11 Last change: 8 Oct 2008 1
CPU Performance Counters Library Functions cpcnpic(3CPC)
described by that interface.
The cpccpuref() 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 system. The string returned
might be substantially longer than 80 characters. Callers
printing to a terminal might want to insert line breaks as
appropriate.
The cpcnpic() function returns the number of performance
counters accessible on the processor.
The cpccaps() function returns a bitmap containing the bit-
wise inclusive-OR of zero or more flags that describe the
capabilities of the processor. If CPCAPOVERFLOWINTERUPT
is present, the processor can generate an interrupt when a
hardware performance counter overflows. If
CPCAPOVERFLOWPRECISE is present, the processor can
determine precisely which counter overflowed, thereby
affecting the behavior of the overflow notification mechan-
ism described in cpcbindcurlwp(3CPC).
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 cpccpuref() should be con-
sulted to understand the reasons for and use of the attri-
butes.
The cpcwalkeventsall() function calls the action function
on each element of a global event list. 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 cpcwalkeventspic() function calls the action function
with each event supported by the counter indicated by the
picno argument, where picno ranges from 0 to the value
SunOS 5.11 Last change: 8 Oct 2008 2
CPU Performance Counters Library Functions cpcnpic(3CPC)
returned by cpcnpic().
The system maintains a list of platform independent perfor-
mance counter events known as generic events (see
genericevents(3CPC)).
The cpcwalkgenericeventsall() 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 cpcwalkgenericeventspic() 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 cpcnpic().
The system maintains a list of attributes that can be used
to enable advanced features of the performance counters on
the underlying processor. The cpcwalkattrs() function
calls the action function for each supported attribute name.
See the reference material as returned by cpccpuref(3CPC)
for the semantics use of attributes.
RETURN VALUES
The cpccciname() function always returns a printable
description of the processor performance counter interfaces.
The cpccpuref() function always returns a string that
describes a reference work.
The cpcnpic() function always returns the number of perfor-
mance counters accessible on the processor.
The cpccaps() 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 cpcwalkeventsall(), cpcwalkeventspic(),
cpcwalkattrs(), cpcwalkgenericeventspic(), and
cpcwalkgenericeventspic() functions set errno to indi-
cate the error.
SunOS 5.11 Last change: 8 Oct 2008 3
CPU Performance Counters Library Functions cpcnpic(3CPC)
ERORS
The cpcwalkeventsall(), cpcwalkeventspic(),
cpcwalkattrs(), cpcwalkgenericeventspic(), and
cpcwalkgenericeventspic() functions will fail if:
ENOMEM There is not enough memory available.
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), genericevents(3CPC), libcpc(3LIB),
attributes(5)
SunOS 5.11 Last change: 8 Oct 2008 4
|
