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