cpc_event(3CPC) CPU Performance Counters Library Functions cpc_event(3CPC)NAME
cpc_event - data structure to describe CPU performance counters
SYNOPSIS
#include <libcpc.h>
DESCRIPTION
The libcpc interfaces manipulate CPU performance counters using the cpc_event_t data structure. This structure contains several fields that
are common to all processors, and some that are processor-dependent. These structures can be declared by a consumer of the API, thus the
size and offsets of the fields and the entire data structure are fixed per processor for any particular version of the library. See
cpc_version(3CPC) for details of library versioning.
SPARC
For UltraSPARC, the structure contains the following members:
typedef struct {
int ce_cpuver;
hrtime_t ce_hrt;
uint64_t ce_tick;
uint64_t ce_pic[2];
uint64_t ce_pcr;
} cpc_event_t;
x86
For Pentium, the structure contains the following members:
typedef struct {
int ce_cpuver;
hrtime_t ce_hrt;
uint64_t ce_tsc;
uint64_t ce_pic[2];
uint32_t ce_pes[2];
#define ce_cesr ce_pes[0]
} cpc_event_t;
The APIs are used to manipulate the highly processor-dependent control registers (the ce_pcr, ce_cesr, and ce_pes fields); the programmer
is strongly advised not to reference those fields directly in portable code. The ce_pic array elements contain 64-bit accumulated counter
values. The hardware registers are virtualized to 64-bit quantities even though the underlying hardware only supports 32-bits (UltraSPARC)
or 40-bits (Pentium) before overflow.
The ce_hrt field is a high resolution timestamp taken at the time the counters were sampled by the kernel. This uses the same timebase as
gethrtime(3C).
On SPARC V9 machines, the number of cycles spent running on the processor is computed from samples of the processor-dependent %tick regis-
ter, and placed in the ce_tick field. On Pentium processors, the processor-dependent time-stamp counter register is similarly sampled and
placed in the ce_tsc field.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Interface Stability |Evolving |
+-----------------------------+-----------------------------+
SEE ALSO gethrtime(3C), cpc(3CPC), cpc_version(3CPC), libcpc(3LIB), attributes(5)SunOS 5.10 12 May 2003 cpc_event(3CPC)
Check Out this Related Man Page
cpc_getcpuver(3CPC) CPU Performance Counters Library Functions cpc_getcpuver(3CPC)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 indi-
cates 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 pro-
cessor. 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 unrec-
ognized, 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 sys-
tem.
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 com-
patibility 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.
SunOS 5.11 28 Mar 2005 cpc_getcpuver(3CPC)