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