share/man/man3cpc/cpc_event.3cpc

   1 '\" te
   2 .\" Copyright (c) 2003, Sun Microsystems, Inc.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH CPC_EVENT 3CPC "May 12, 2003"
   7 .SH NAME
   8 cpc_event \- data structure to describe CPU performance counters
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <libcpc.h>
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBlibcpc\fR interfaces manipulate CPU performance counters using the
  19 \fBcpc_event_t\fR data structure. This structure contains several fields that
  20 are common to all processors, and some that are processor-dependent. These
  21 structures can be declared by a consumer of the API, thus the size and offsets
  22 of the fields and the entire data structure are fixed per processor for any
  23 particular version of the library. See  \fBcpc_version\fR(3CPC) for details of
  24 library versioning.
  25 .SS "SPARC"
  26 .sp
  27 .LP
  28 For UltraSPARC, the structure contains the following members:
  29 .sp
  30 .in +2
  31 .nf
  32 typedef struct {
  33         int ce_cpuver;
  34         hrtime_t ce_hrt;
  35         uint64_t ce_tick;
  36         uint64_t ce_pic[2];
  37         uint64_t ce_pcr;
  38 } cpc_event_t;
  39 .fi
  40 .in -2
  41
  42 .SS "x86"
  43 .sp
  44 .LP
  45 For Pentium, the structure contains the following members:
  46 .sp
  47 .in +2
  48 .nf
  49 \fBtypedef struct {
  50         int ce_cpuver;
  51         hrtime_t ce_hrt;
  52         uint64_t ce_tsc;
  53         uint64_t ce_pic[2];
  54         uint32_t ce_pes[2];
  55 #define ce_cesr ce_pes[0]
  56 } cpc_event_t;\fR
  57 .fi
  58 .in -2
  59
  60 .sp
  61 .LP
  62 The APIs are used to manipulate the highly processor-dependent control
  63 registers (the \fBce_pcr\fR, \fBce_cesr\fR, and \fBce_pes\fR fields); the
  64 programmer is strongly advised not to reference those fields directly in
  65 portable code. The \fBce_pic\fR array elements contain 64-bit accumulated
  66 counter values.  The hardware registers are virtualized to 64-bit quantities
  67 even though the underlying hardware only supports 32-bits (UltraSPARC) or
  68 40-bits (Pentium) before overflow.
  69 .sp
  70 .LP
  71 The  \fBce_hrt\fR field is a high resolution timestamp taken at the time the
  72 counters were sampled by the kernel.  This uses the same timebase as
  73 \fBgethrtime\fR(3C).
  74 .sp
  75 .LP
  76 On SPARC V9 machines, the number of cycles spent running on the processor is
  77 computed from samples of the processor-dependent  \fB%tick\fR register, and
  78 placed in the  \fBce_tick\fR field. On Pentium processors, the
  79 processor-dependent time-stamp counter register is similarly sampled and placed
  80 in the \fBce_tsc\fR field.
  81 .SH ATTRIBUTES
  82 .sp
  83 .LP
  84 See \fBattributes\fR(5) for descriptions of the following attributes:
  85 .sp
  86
  87 .sp
  88 .TS
  89 box;
  90 c | c
  91 l | l .
  92 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  93 _
  94 Interface Stability     Evolving
  95 .TE
  96
  97 .SH SEE ALSO
  98 .sp
  99 .LP
 100 \fBgethrtime\fR(3C), \fBcpc\fR(3CPC), \fBcpc_version\fR(3CPC),
 101 \fBlibcpc\fR(3LIB), \fBattributes\fR(5)