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(5) 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(5)

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)