share/man/man3cpc/cpc_getcpuver.3cpc

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
   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_GETCPUVER 3CPC "Mar 28, 2005"
   7 .SH NAME
   8 cpc_getcpuver, cpc_getcciname, cpc_getcpuref, cpc_getusage, cpc_getnpic,
   9 cpc_walk_names \- determine CPU performance counter configuration
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ]
  14 #include <libcpc.h>
  15
  16 \fBint\fR \fBcpc_getcpuver\fR(\fBvoid\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBconst char *\fR\fBcpc_getcciname\fR(\fBint\fR \fIcpuver\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBconst char *\fR\fBcpc_getcpuref\fR(\fBint\fR \fIcpuver\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBconst char *\fR\fBcpc_getusage\fR(\fBint\fR \fIcpuver\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBuint_t\fR \fBcpc_getnpic\fR(\fBint\fR \fIcpuver\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBvoid\fR \fBcpc_walk_names\fR(\fBint\fR \fIcpuver\fR, \fBint\fR \fIregno\fR, \fBvoid *\fR\fIarg\fR,
  42      \fBvoid (*\fR\fIaction\fR)(void *\fIarg\fR, int \fIregno\fR,  const char *\fIname\fR,
  43      uint8_t \fIbits\fR));
  44 .fi
  45
  46 .SH DESCRIPTION
  47 .sp
  48 .LP
  49 The \fBcpc_getcpuver()\fR function returns an abstract integer that corresponds
  50 to the distinguished version of the underlying processor.  The library
  51 distinguishes between processors solely on the basis of their support for
  52 performance counters, so the version returned should not be interpreted in any
  53 other way. The set of values returned by the library is unique across all
  54 processor implementations.
  55 .sp
  56 .LP
  57 The \fBcpc_getcpuver()\fR function returns \(mi1 if the library cannot support
  58 CPU performance counters on the current architecture.  This may be because the
  59 processor has no such counter hardware, or because the library is unable to
  60 recognize it. Either way, such a return value indicates that the configuration
  61 functions described on this manual page cannot be used.
  62 .sp
  63 .LP
  64 The \fBcpc_getcciname()\fR function returns a printable description of the
  65 processor performance counter interfaces-for example, the string \fIUltraSPARC
  66 I&II\fR. Note that this name should not be assumed to be the same as the name
  67 the manufacturer might otherwise ascribe to the processor.  It simply names the
  68 performance counter interfaces as understood by the library, and thus names the
  69 set of performance counter events that can be described by that interface. If
  70 the \fIcpuver\fR argument is unrecognized, the function returns \fINULL\fR.
  71 .sp
  72 .LP
  73 The \fBcpc_getcpuref()\fR function returns a string that describes a reference
  74 work that should be consulted to (allow a human to) understand the semantics of
  75 the performance counter events that are known to the library. If the
  76 \fIcpuver\fR argument is unrecognized, the function returns \fINULL\fR. The
  77 string returned might be substantially longer than 80 characters. Callers
  78 printing to a terminal might want to insert line breaks as appropriate.
  79 .sp
  80 .LP
  81 The \fBcpc_getusage()\fR function returns a compact description of the
  82 \fBgetsubopt()\fR-oriented syntax that is consumed by
  83 \fBcpc_strtoevent\fR(3CPC). It is returned as a space-separated set of tokens
  84 to allow the caller to wrap lines at convenient boundaries. If the \fIcpuver\fR
  85 argument is unrecognized, the function returns \fINULL\fR.
  86 .sp
  87 .LP
  88 The \fBcpc_getnpic()\fR function returns the number of valid fields in the
  89 \fBce_pic\fR[] array of a \fBcpc_event_t\fR data structure.
  90 .sp
  91 .LP
  92 The library maintains a list of events that it believes the processor capable
  93 of measuring, along with the bit patterns that must be set in the corresponding
  94 control register, and which counter the result will appear in.  The
  95 \fBcpc_walk_names()\fR function calls the \fIaction\fR(\|) function on each
  96 element of the list so that an application can print appropriate help on the
  97 set of events known to the library.  The \fIarg\fR parameter is passed
  98 uninterpreted from the caller on each invocation of the \fIaction\fR(\|)
  99 function.
 100 .sp
 101 .LP
 102 If the parameters specify an invalid or unknown CPU or register number, the
 103 function silently returns without invoking the action function.
 104 .SH USAGE
 105 .sp
 106 .LP
 107 Prior to calling any of these functions, applications should call
 108 \fBcpc_access\fR(3CPC) to determine if the counters are accessible on the
 109 system.
 110 .SH ATTRIBUTES
 111 .sp
 112 .LP
 113 See \fBattributes\fR(5) for descriptions of the following attributes:
 114 .sp
 115
 116 .sp
 117 .TS
 118 box;
 119 c | c
 120 l | l .
 121 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 122 _
 123 MT-Level        MT-Safe
 124 _
 125 Interface Stability     Obsolete
 126 .TE
 127
 128 .SH SEE ALSO
 129 .sp
 130 .LP
 131 \fBcpc\fR(3CPC), \fBcpc_access\fR(3CPC), \fBcpc_cciname\fR(3CPC),
 132 \fBcpc_cpuref\fR(3CPC), \fBcpc_npic\fR(3CPC),
 133 \fBcpc_walk_events_all\fR(3CPC), \fBlibcpc\fR(3LIB), \fBattributes\fR(5)
 134 .SH NOTES
 135 .sp
 136 .LP
 137 The \fBcpc_getcpuver()\fR, \fBcpc_getcciname()\fR, \fBcpc_getcpuref()\fR,
 138 \fBcpc_getusage()\fR, \fBcpc_getnpic()\fR, and \fBcpc_walk_names()\fR functions
 139 exist for binary compatibility only. Source containing these functions will not
 140 compile. These functions are obsolete and might be removed in a future release.
 141 Applications should use \fBcpc_cciname\fR(3CPC), \fBcpc_cpuref\fR(3CPC),
 142 \fBcpc_npic\fR(3CPC), and \fBcpc_npic\fR(3CPC) instead.
 143 .sp
 144 .LP
 145 Only SPARC processors are described by the SPARC version of the library, and
 146 only x86 processors are described by the x86 version of the library.