'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc.
.TH cpc_event 3CPC "12 May 2003" "SunOS 5.11" "CPU Performance Counters Library Functions"
.SH NAME
cpc_event \- data structure to describe CPU performance counters
.SH SYNOPSIS
.LP
.nf
#include <libcpc.h>
.fi

.SH DESCRIPTION
.sp
.LP
The \fBlibcpc\fR interfaces manipulate CPU performance counters using the \fBcpc_event_t\fR 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  \fBcpc_version\fR(3CPC) for details of library versioning.
.SS "SPARC"
.sp
.LP
For UltraSPARC, the structure contains the following members:
.sp
.in +2
.nf
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;
.fi
.in -2

.SS "x86"
.sp
.LP
For Pentium, the structure contains the following members:
.sp
.in +2
.nf
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;
.fi
.in -2

.sp
.LP
The APIs are used to manipulate the highly processor-dependent control registers (the \fBce_pcr\fR, \fBce_cesr\fR, and \fBce_pes\fR fields); the programmer is strongly advised not to reference those fields directly in portable code. The \fBce_pic\fR 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.
.sp
.LP
The  \fBce_hrt\fR field is a high resolution timestamp taken at the time the counters were sampled by the kernel.  This uses the same timebase as \fBgethrtime\fR(3C). 
.sp
.LP
On SPARC V9 machines, the number of cycles spent running on the processor is computed from samples of the processor-dependent  \fB%tick\fR register, and placed in the  \fBce_tick\fR field. On Pentium processors, the processor-dependent time-stamp counter register is similarly sampled and placed in the \fBce_tsc\fR field.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBgethrtime\fR(3C), \fBcpc\fR(3CPC), \fBcpc_version\fR(3CPC), \fBlibcpc\fR(3LIB), \fBattributes\fR(5)