xref: /illumos-gate/usr/src/man/man3cpc/cpc.3cpc (revision b1e2e3fb17324e9ddf43db264a0c64da7756d9e6)
1.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
2.\" 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.
3.\" 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.
4.\" 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]
5.\" Copyright (c) 2019, Joyent, Inc.
6.Dd March 25, 2019
7.Dt CPC 3CPC
8.Os
9.Sh NAME
10.Nm cpc
11.Nd hardware performance counters
12.Sh DESCRIPTION
13Modern microprocessors contain
14.Em hardware performance counters
15that allow
16the measurement of many different hardware events related to CPU behavior,
17including instruction and data cache misses as well as various internal states
18of the processor.
19The counters can be configured to count user events, system
20events, or both.
21Data from the performance counters can be used to analyze and
22tune the behavior of software on a particular type of processor.
23.Pp
24Most processors are able to generate an interrupt on counter overflow, allowing
25the counters to be used for various forms of profiling.
26.Pp
27This manual page describes a set of APIs that allow illumos applications to use
28these counters.
29Applications can measure their own behavior, the behavior of
30other applications, or the behavior of the whole system.
31.Ss Shared Counters or Private Counters
32There are two principal models for using these performance counters.
33Some users of these statistics want to observe system-wide behavior.
34Other users want to view the performance counters as part of the register set
35exported by each
36.Sy LWP .
37On a machine performing more than one activity, these two models are
38in conflict because the counters represent a critical hardware resource that
39cannot simultaneously be both shared and private.
40.Ss Configuration Interfaces
41The following configuration interfaces are provided:
42.Bl -tag -width Xr
43.It Xr cpc_open 3CPC
44Check the version the application was compiled with against the version of the
45.It Xr cpc_cciname 3CPC
46Return a printable string to describe the performance counters of the
47processor.
48.It Xr cpc_npic 3CPC
49Return the number of performance counters on the processor.
50.It cpc_cpuref 3CPC
51Return a reference to documentation that should be consulted to understand how
52to use and interpret data from the performance counters.
53.El
54.Ss Performance Counter Access
55Performance counters can be present in hardware but not acccessible because
56either some of the necessary system software components are not available or
57not installed, or the counters might be in use by other processes.
58The
59.Xr cpc_open 3CPC
60function determines the accessibility of the counters and
61must be invoked before any attempt to program the counters.
62.Ss "Finding Events"
63Each different type of processor has its own set of events available for
64measurement.
65The
66.Xr cpc_walk_events_all 3CPC
67and
68.Xr cpc_walk_events_pic 3CPC
69functions allow an application to determine the
70names of events supported by the underlying processor.
71A collection of generic, platform independent event names are defined by
72.Xr generic_events 3CPC .
73Each generic event maps to an underlying hardware event specific to the
74underlying processor and any optional attributes.
75The
76.Xr cpc_walk_generic_events_all 3CPC
77and
78.Xr cpc_walk_generic_events_pic 3CPC
79functions allow an application to determine the generic events supported
80on the underlying platform.
81.Ss Intel Processor Specific Events
82The following manual pages provide more detailed information on the
83events available for the specific Intel processor models.
84The covered processor models are listed in hexadecimal.
85.Bl -tag -width Xr
86.It Xr bdw_de_events 3CPC
87Intel Broadwell-DE events; covers model 56h.
88.It Xr bdw_events 3CPC
89Intel Broadwell client events; covers models 3dh and 47h.
90.It Xr bdx_events 3CPC
91Intel Broadwell server events; covers model 4fh.
92.It Xr bnl_events 3CPC
93Intel Atom Bonnell events; covers models 35h, 36h, 27h, 26h, and 1ch.
94.It Xr clx_events 3CPC
95Intel Cascade Lake server events; covers model 55h, steppings 5-fh.
96.It Xr glm_events 3CPC
97Intel Goldmont SoC events; covers models 5fh and 5ch.
98.It Xr glp_events 3CPC
99Intel Goldmont Plus SoC events; covers model 7ah.
100.It Xr hsw_events 3CPC
101Intel Haswell client events; covers models 46h, 45h, and 3ch.
102.It Xr hsx_events 3CPC
103Intel Haswell server events; covers model 3fh.
104.It Xr ivb_events 3CPC
105Intel Ivy Bridge client events; covers model 3ah.
106.It Xr ivt_events 3CPC
107Intel Ivy Bridge server events; covers model 3eh.
108.It Xr jkt_events 3CPC
109Intel Sandy Bridge server events; covers model 2dh.
110.It Xr nhm_ep_events 3CPC
111Intel Nehalem-EP events; covers models, 1ah, 1fh, and 1eh.
112.It Xr nhm_ex_events 3CPC
113Intel Sandy Bridge server events; covers model 23h.
114.It Xr skl_events 3CPC
115Intel Skylake client events; covers model 9eh, 8eh, 5e, and 4eh.
116.It Xr skx_events 3CPC
117Intel Skylake server events; covers model 55h, steppings 0-4h.
118.It Xr slm_events 3CPC
119Intel Atom Silvermont events; covers models 4ch, 4dh, and 37h.
120.It Xr snb_events 3CPC
121Intel Sandy Bridge Client events; covers model 2ah.
122.It Xr wsm_ep_dp_events 3CPC
123Intel Westmere-EP-DP events; covers model 2ch.
124.It Xr wsm_ep_sp_events 3CPC
125Intel Westmere-EP-SP events; covers model 25h.
126.It Xr wsm_ex_events 3CPC
127Intel Westmere-EX events; covers model 2fh.
128.El
129.Ss AMD Processor Specific Events
130The following manual pages provide more detailed information on the
131events available for the specific AMD processor models.
132The covered processor families are listed in hexadecimal.
133.Bl -tag -width Xr
134.It Xr amd_f17h_events 3CPC
135AMD Family 17h processors, including models 00-2fh.
136Include Ryzen, ThreadRipper, and EPYC branded processors.
137.El
138.Ss Using Attributes
139Some processors have advanced performance counter capabilities that are
140configured with attributes.
141The
142.Xr cpc_walk_attrs 3CPC
143function can be used to determine the names of attributes supported by
144the underlying processor.
145The documentation referenced by
146.Xr cpc_cpuref 3CPC
147should be consulted to understand the meaning of a processor's performance
148counter attributes.
149.Ss Performance Counter Context
150Each processor on the system possesses its own set of performance counter
151registers.
152For a single process, it is often desirable to maintain the illusion
153that the counters are an intrinsic part of that process (whichever processors
154it runs on), since this allows the events to be directly attributed to the
155process without having to make passive all other activity on the system.
156.Pp
157To achieve this behavior, the library associates
158.Em performance counter context
159with each
160.Sy LWP
161in the process.
162The context consists of a small amount of kernel memory to hold the counter
163values when the
164.Sy BLWP
165is not running, and some simple kernel functions to save and restore those counter
166values from and to the hardware registers when the
167.Sy LWP
168performs a normal context switch.
169A process can only observe and manipulate its own copy of the
170performance counter control and data registers.
171.Ss Performance Counters \&In Other Processes
172Though applications can be modified to instrument themselves as demonstrated
173above, it is frequently useful to be able to examine the behavior of an
174existing application without changing the source code.
175A separate library,
176.Sy libpctx ,
177provides a simple set of interfaces that use the facilities of
178.Xr proc 4
179to control a target process, and together with functions in
180.Sy libcpc ,
181allow
182.Sy truss No -like
183tools to be constructed to measure the performance counters in other
184applications.
185An example of one such application is
186.Xr cputrack 1 .
187.Pp
188The functions in
189.Sy libpctx
190are independent of those in
191.Sy libcpc .
192These functions manage a process using an event-loop paradigm \(em that is, the
193execution of certain system calls by the controlled process cause the library
194to stop the controlled process and execute callback functions in the context of
195the controlling process.
196These handlers can perform various operations on the target process using APIs
197in
198.Sy libpctx
199and
200.Sy libcpc
201that consume
202.Vt pctx_t
203handles.
204.Sh SEE ALSO
205.Xr cputrack 1 ,
206.Xr cpustat 1M ,
207.Xr cpc_bind_curlwp 3CPC ,
208.Xr cpc_buf_create 3CPC ,
209.Xr cpc_enable 3CPC ,
210.Xr cpc_npic 3CPC ,
211.Xr cpc_open 3CPC ,
212.Xr cpc_set_create 3CPC ,
213.Xr cpc_seterrhndlr 3CPC ,
214.Xr generic_events 3CPC ,
215.Xr pctx_capture 3CPC ,
216.Xr pctx_set_events 3CPC ,
217.Xr libcpc 3LIB ,
218.Xr proc 4
219