usr/src/man/man3cpc/cpc.3cpc

   1 '\" te
   2 .\" Copyright (c) 2008, 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 3CPC "Oct 8, 2008"
   7 .SH NAME
   8 cpc \- hardware performance counters
   9 .SH DESCRIPTION
  10 .sp
  11 .LP
  12 Modern microprocessors contain \fIhardware performance counters\fR that allow
  13 the measurement of many different hardware events related to CPU behavior,
  14 including instruction and data cache misses as well as various internal states
  15 of the processor. The counters can be configured to count user events, system
  16 events, or both. Data from the performance counters can be used to analyze and
  17 tune the behavior of software on a particular type of processor.
  18 .sp
  19 .LP
  20 Most processors are able to generate an interrupt on counter overflow, allowing
  21 the counters to be used for various forms of profiling.
  22 .sp
  23 .LP
  24 This manual page describes a set of APIs that allow Solaris applications to use
  25 these counters. Applications can measure their own behavior, the behavior of
  26 other applications, or the behavior of the whole system.
  27 .SS "Shared Counters or Private Counters"
  28 .sp
  29 .LP
  30 There are two principal models for using these performance counters. Some users
  31 of these statistics want to observe system-wide behavior. Other users want to
  32 view the performance counters as part of the register set exported by each
  33 \fBLWP\fR. On a machine performing more than one activity, these two models are
  34 in conflict because the counters represent a critical hardware resource that
  35 cannot simultaneously be both shared and private.
  36 .SS "Configuration Interfaces"
  37 .sp
  38 .LP
  39 The following configuration interfaces are provided:
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fBcpc_open\fR(3CPC)\fR
  44 .ad
  45 .RS 21n
  46 Check the version the application was compiled with against the version of the
  47 library.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fBcpc_cciname\fR(3CPC)\fR
  54 .ad
  55 .RS 21n
  56 Return a printable string to describe the performance counters of the
  57 processor.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fBcpc_npic\fR(3CPC)\fR
  64 .ad
  65 .RS 21n
  66 Return the number of performance counters on the processor.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBcpc_cpuref\fR(3CPC)\fR
  73 .ad
  74 .RS 21n
  75 Return a reference to documentation that should be consulted to understand how
  76 to use and interpret data from the performance counters.
  77 .RE
  78
  79 .SS "Performance Counter Access"
  80 .sp
  81 .LP
  82 Performance counters can be present in hardware but not acccessible because
  83 either some of the necessary system software components are not available or
  84 not installed, or the counters might be in use by other processes.  The
  85 \fBcpc_open\fR(3CPC) function determines the accessibility of the counters and
  86 must be invoked before any attempt to program the counters.
  87 .SS "Finding Events"
  88 .sp
  89 .LP
  90 Each different type of processor has its own set of events available for
  91 measurement. The \fBcpc_walk_events_all\fR(3CPC) and
  92 \fBcpc_walk_events_pic\fR(3CPC) functions allow an application to determine the
  93 names of events supported by the underlying processor. A collection of generic,
  94 platform independent event names are defined by \fBgeneric_events\fR(3CPC).
  95 Each generic event maps to an underlying hardware event specific to the
  96 underlying processor and any optional attributes. The
  97 \fBcpc_walk_generic_events_all\fR(3CPC) and
  98 \fBcpc_walk_generic_events_pic\fR(3CPC) functions allow an application to
  99 determine the generic events supported on the underlying platform.
 100 .SS "Using Attributes"
 101 .sp
 102 .LP
 103 Some processors have advanced performance counter capabilities that are
 104 configured with attributes. The \fBcpc_walk_attrs\fR(3CPC) function can be used
 105 to determine the names of attributes supported by the underlying processor. The
 106 documentation referenced by \fBcpc_cpuref\fR(3CPC) should be consulted to
 107 understand the meaning of a processor's performance counter attributes.
 108 .SS "Performance Counter Context"
 109 .sp
 110 .LP
 111 Each processor on the system possesses its own set of performance counter
 112 registers. For a single process, it is often desirable to maintain the illusion
 113 that the counters are an intrinsic part of that process (whichever processors
 114 it runs on), since this allows the events to be directly attributed to the
 115 process without having to make passive all other activity on the system.
 116 .sp
 117 .LP
 118 To achieve this behavior, the library associates \fIperformance counter
 119 context\fR with each \fBLWP\fR in the process. The context consists of a small
 120 amount of kernel memory to hold the counter values when the \fBLWP\fR is not
 121 running, and some simple kernel functions to save and restore those counter
 122 values from and to the hardware registers when the \fBLWP\fR performs a normal
 123 context switch. A process can only observe and manipulate its own copy of the
 124 performance counter control and data registers.
 125 .SS "Performance Counters In Other Processes"
 126 .sp
 127 .LP
 128 Though applications can be modified to instrument themselves as demonstrated
 129 above, it is frequently useful to be able to examine the behavior of an
 130 existing application without changing the source code. A separate library,
 131 \fBlibpctx\fR, provides a simple set of interfaces that use the facilities of
 132 \fBproc\fR(4) to control a target process, and together with functions in
 133 \fBlibcpc\fR, allow \fBtruss\fR-like tools to be constructed to measure the
 134 performance counters in other applications. An example of one such application
 135 is \fBcputrack\fR(1).
 136 .sp
 137 .LP
 138 The functions in \fBlibpctx\fR are independent of those in \fBlibcpc\fR. These
 139 functions manage a process using an event-loop paradigm \(em that is, the
 140 execution of certain system calls by the controlled process cause the library
 141 to stop the controlled process and execute callback functions in the context of
 142 the controlling process. These handlers can perform various operations on the
 143 target process using APIs in \fBlibpctx\fR and \fBlibcpc\fR that consume
 144 \fBpctx_t\fR handles.
 145 .SH SEE ALSO
 146 .sp
 147 .LP
 148 \fBcputrack\fR(1), \fBcpustat\fR(1M), \fBcpc_bind_curlwp\fR(3CPC),
 149 \fBcpc_buf_create\fR(3CPC), \fBcpc_enable\fR(3CPC), \fBcpc_npic\fR(3CPC),
 150 \fBcpc_open\fR(3CPC), \fBcpc_set_create\fR(3CPC), \fBcpc_seterrhndlr\fR(3CPC),
 151 \fBgeneric_events\fR(3CPC), \fBlibcpc\fR(3LIB), \fBpctx_capture\fR(3CPC),
 152 \fBpctx_set_events\fR(3CPC), \fBproc\fR(4)