CPC_GETCPUVER(3CPC) CPU Performance Counters Library Functions
NAME
cpc_getcpuver, cpc_getcciname, cpc_getcpuref, cpc_getusage,
cpc_getnpic, cpc_walk_names - determine CPU performance counter
configuration
SYNOPSIS
cc [
flag... ]
file... -lcpc [
library... ]
#include <libcpc.h>
int cpc_getcpuver(
void);
const char *cpc_getcciname(
int cpuver);
const char *cpc_getcpuref(
int cpuver);
const char *cpc_getusage(
int cpuver);
uint_t cpc_getnpic(
int cpuver);
void cpc_walk_names(
int cpuver,
int regno,
void *arg,
void (*action)(void *
arg, int
regno, const char *
name,
uint8_t
bits));
DESCRIPTION
The
cpc_getcpuver() function returns an abstract integer that
corresponds to the distinguished version of the underlying processor.
The library distinguishes between processors solely on the basis of
their support for performance counters, so the version returned
should not be interpreted in any other way. The set of values
returned by the library is unique across all processor
implementations.
The
cpc_getcpuver() function returns -1 if the library cannot support
CPU performance counters on the current architecture. This may be
because the processor has no such counter hardware, or because the
library is unable to recognize it. Either way, such a return value
indicates that the configuration functions described on this manual
page cannot be used.
The
cpc_getcciname() function returns a printable description of the
processor performance counter interfaces-for example, the string
UltraSPARC I&II. Note that 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 performance counter interfaces as
understood by the library, and thus names the set of performance
counter events that can be described by that interface. If the
cpuver argument is unrecognized, the function returns
NULL.
The
cpc_getcpuref() 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 library. If the
cpuver argument is unrecognized, the
function returns
NULL. The string returned might be substantially
longer than 80 characters. Callers printing to a terminal might want
to insert line breaks as appropriate.
The
cpc_getusage() function returns a compact description of the
getsubopt()-oriented syntax that is consumed by
cpc_strtoevent(3CPC).
It is returned as a space-separated set of tokens to allow the caller
to wrap lines at convenient boundaries. If the
cpuver argument is
unrecognized, the function returns
NULL.
The
cpc_getnpic() function returns the number of valid fields in the
ce_pic[] array of a
cpc_event_t data structure.
The library maintains a list of events that it believes the processor
capable of measuring, along with the bit patterns that must be set in
the corresponding control register, and which counter the result will
appear in. The
cpc_walk_names() function calls the
action() function
on each element of the list so that an application can print
appropriate help on the set of events known to the library. The
arg parameter is passed uninterpreted from the caller on each invocation
of the
action() function.
If the parameters specify an invalid or unknown CPU or register
number, the function silently returns without invoking the action
function.
USAGE
Prior to calling any of these functions, applications should call
cpc_access(3CPC) to determine if the counters are accessible on the
system.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
|Interface Stability | Obsolete |
+--------------------+-----------------+
SEE ALSO
cpc(3CPC),
cpc_access(3CPC),
cpc_cciname(3CPC),
cpc_cpuref(3CPC),
cpc_npic(3CPC),
cpc_walk_events_all(3CPC),
libcpc(3LIB),
attributes(7)NOTES
The
cpc_getcpuver(),
cpc_getcciname(),
cpc_getcpuref(),
cpc_getusage(),
cpc_getnpic(), and
cpc_walk_names() functions exist
for binary compatibility only. Source containing these functions will
not compile. These functions are obsolete and might be removed in a
future release. Applications should use
cpc_cciname(3CPC),
cpc_cpuref(3CPC),
cpc_npic(3CPC), and
cpc_npic(3CPC) instead.
Only SPARC processors are described by the SPARC version of the
library, and only x86 processors are described by the x86 version of
the library.
March 28, 2005 CPC_GETCPUVER(3CPC)
