1c10c16deSRichard Lowe.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. 2c10c16deSRichard Lowe.\" 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. 3c10c16deSRichard Lowe.\" 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. 4c10c16deSRichard Lowe.\" 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] 5c18e9bc3SRobert Mustacchi.\" Copyright (c) 2019, Joyent, Inc. 643449cdcSRobert Mustacchi.\" Copyright 2021 Oxide Computer Company 7*8efb7381SRobert Mustacchi.Dd July 26, 2021 87e3dbbacSRobert Mustacchi.Dt CPC 3CPC 97e3dbbacSRobert Mustacchi.Os 107e3dbbacSRobert Mustacchi.Sh NAME 117e3dbbacSRobert Mustacchi.Nm cpc 127e3dbbacSRobert Mustacchi.Nd hardware performance counters 137e3dbbacSRobert Mustacchi.Sh DESCRIPTION 147e3dbbacSRobert MustacchiModern microprocessors contain 157e3dbbacSRobert Mustacchi.Em hardware performance counters 167e3dbbacSRobert Mustacchithat allow 17c10c16deSRichard Lowethe measurement of many different hardware events related to CPU behavior, 18c10c16deSRichard Loweincluding instruction and data cache misses as well as various internal states 197e3dbbacSRobert Mustacchiof the processor. 207e3dbbacSRobert MustacchiThe counters can be configured to count user events, system 217e3dbbacSRobert Mustacchievents, or both. 227e3dbbacSRobert MustacchiData from the performance counters can be used to analyze and 23c10c16deSRichard Lowetune the behavior of software on a particular type of processor. 247e3dbbacSRobert Mustacchi.Pp 25c10c16deSRichard LoweMost processors are able to generate an interrupt on counter overflow, allowing 26c10c16deSRichard Lowethe counters to be used for various forms of profiling. 277e3dbbacSRobert Mustacchi.Pp 287e3dbbacSRobert MustacchiThis manual page describes a set of APIs that allow illumos applications to use 297e3dbbacSRobert Mustacchithese counters. 307e3dbbacSRobert MustacchiApplications can measure their own behavior, the behavior of 31c10c16deSRichard Loweother applications, or the behavior of the whole system. 327e3dbbacSRobert Mustacchi.Ss Shared Counters or Private Counters 337e3dbbacSRobert MustacchiThere are two principal models for using these performance counters. 347e3dbbacSRobert MustacchiSome users of these statistics want to observe system-wide behavior. 357e3dbbacSRobert MustacchiOther users want to view the performance counters as part of the register set 367e3dbbacSRobert Mustacchiexported by each 377e3dbbacSRobert Mustacchi.Sy LWP . 387e3dbbacSRobert MustacchiOn a machine performing more than one activity, these two models are 39c10c16deSRichard Lowein conflict because the counters represent a critical hardware resource that 40c10c16deSRichard Lowecannot simultaneously be both shared and private. 417e3dbbacSRobert Mustacchi.Ss Configuration Interfaces 42c10c16deSRichard LoweThe following configuration interfaces are provided: 437e3dbbacSRobert Mustacchi.Bl -tag -width Xr 447e3dbbacSRobert Mustacchi.It Xr cpc_open 3CPC 45c10c16deSRichard LoweCheck the version the application was compiled with against the version of the 467e3dbbacSRobert Mustacchi.It Xr cpc_cciname 3CPC 47c10c16deSRichard LoweReturn a printable string to describe the performance counters of the 48c10c16deSRichard Loweprocessor. 497e3dbbacSRobert Mustacchi.It Xr cpc_npic 3CPC 50c10c16deSRichard LoweReturn the number of performance counters on the processor. 517e3dbbacSRobert Mustacchi.It cpc_cpuref 3CPC 52c10c16deSRichard LoweReturn a reference to documentation that should be consulted to understand how 53c10c16deSRichard Loweto use and interpret data from the performance counters. 547e3dbbacSRobert Mustacchi.El 557e3dbbacSRobert Mustacchi.Ss Performance Counter Access 56c10c16deSRichard LowePerformance counters can be present in hardware but not acccessible because 57c10c16deSRichard Loweeither some of the necessary system software components are not available or 587e3dbbacSRobert Mustacchinot installed, or the counters might be in use by other processes. 597e3dbbacSRobert MustacchiThe 607e3dbbacSRobert Mustacchi.Xr cpc_open 3CPC 617e3dbbacSRobert Mustacchifunction determines the accessibility of the counters and 62c10c16deSRichard Lowemust be invoked before any attempt to program the counters. 637e3dbbacSRobert Mustacchi.Ss "Finding Events" 64c10c16deSRichard LoweEach different type of processor has its own set of events available for 657e3dbbacSRobert Mustacchimeasurement. 667e3dbbacSRobert MustacchiThe 677e3dbbacSRobert Mustacchi.Xr cpc_walk_events_all 3CPC 687e3dbbacSRobert Mustacchiand 697e3dbbacSRobert Mustacchi.Xr cpc_walk_events_pic 3CPC 707e3dbbacSRobert Mustacchifunctions allow an application to determine the 717e3dbbacSRobert Mustacchinames of events supported by the underlying processor. 727e3dbbacSRobert MustacchiA collection of generic, platform independent event names are defined by 737e3dbbacSRobert Mustacchi.Xr generic_events 3CPC . 74c10c16deSRichard LoweEach generic event maps to an underlying hardware event specific to the 757e3dbbacSRobert Mustacchiunderlying processor and any optional attributes. 767e3dbbacSRobert MustacchiThe 777e3dbbacSRobert Mustacchi.Xr cpc_walk_generic_events_all 3CPC 787e3dbbacSRobert Mustacchiand 797e3dbbacSRobert Mustacchi.Xr cpc_walk_generic_events_pic 3CPC 807e3dbbacSRobert Mustacchifunctions allow an application to determine the generic events supported 817e3dbbacSRobert Mustacchion the underlying platform. 82d0e58ef5SRobert Mustacchi.Ss Intel Processor Specific Events 83d0e58ef5SRobert MustacchiThe following manual pages provide more detailed information on the 84d0e58ef5SRobert Mustacchievents available for the specific Intel processor models. 85d0e58ef5SRobert MustacchiThe covered processor models are listed in hexadecimal. 867e3dbbacSRobert Mustacchi.Bl -tag -width Xr 877e3dbbacSRobert Mustacchi.It Xr bdw_de_events 3CPC 887e3dbbacSRobert MustacchiIntel Broadwell-DE events; covers model 56h. 897e3dbbacSRobert Mustacchi.It Xr bdw_events 3CPC 907e3dbbacSRobert MustacchiIntel Broadwell client events; covers models 3dh and 47h. 917e3dbbacSRobert Mustacchi.It Xr bdx_events 3CPC 927e3dbbacSRobert MustacchiIntel Broadwell server events; covers model 4fh. 937e3dbbacSRobert Mustacchi.It Xr bnl_events 3CPC 947e3dbbacSRobert MustacchiIntel Atom Bonnell events; covers models 35h, 36h, 27h, 26h, and 1ch. 95c18e9bc3SRobert Mustacchi.It Xr clx_events 3CPC 96c18e9bc3SRobert MustacchiIntel Cascade Lake server events; covers model 55h, steppings 5-fh. 977e3dbbacSRobert Mustacchi.It Xr glm_events 3CPC 987e3dbbacSRobert MustacchiIntel Goldmont SoC events; covers models 5fh and 5ch. 997e3dbbacSRobert Mustacchi.It Xr glp_events 3CPC 1007e3dbbacSRobert MustacchiIntel Goldmont Plus SoC events; covers model 7ah. 1017e3dbbacSRobert Mustacchi.It Xr hsw_events 3CPC 1027e3dbbacSRobert MustacchiIntel Haswell client events; covers models 46h, 45h, and 3ch. 1037e3dbbacSRobert Mustacchi.It Xr hsx_events 3CPC 1047e3dbbacSRobert MustacchiIntel Haswell server events; covers model 3fh. 10543449cdcSRobert Mustacchi.It xr icl_events 3CPC 10643449cdcSRobert MustacchiIntel Ice Lake client events; covers model 7eh. 1077e3dbbacSRobert Mustacchi.It Xr ivb_events 3CPC 1087e3dbbacSRobert MustacchiIntel Ivy Bridge client events; covers model 3ah. 1097e3dbbacSRobert Mustacchi.It Xr ivt_events 3CPC 1107e3dbbacSRobert MustacchiIntel Ivy Bridge server events; covers model 3eh. 1117e3dbbacSRobert Mustacchi.It Xr jkt_events 3CPC 1127e3dbbacSRobert MustacchiIntel Sandy Bridge server events; covers model 2dh. 1137e3dbbacSRobert Mustacchi.It Xr nhm_ep_events 3CPC 1147e3dbbacSRobert MustacchiIntel Nehalem-EP events; covers models, 1ah, 1fh, and 1eh. 1157e3dbbacSRobert Mustacchi.It Xr nhm_ex_events 3CPC 1167e3dbbacSRobert MustacchiIntel Sandy Bridge server events; covers model 23h. 1177e3dbbacSRobert Mustacchi.It Xr skl_events 3CPC 11843449cdcSRobert MustacchiIntel Skylake client events; covers model a6h, a5h, 9eh, 8eh, 5e, and 4eh. 1197e3dbbacSRobert Mustacchi.It Xr skx_events 3CPC 120c18e9bc3SRobert MustacchiIntel Skylake server events; covers model 55h, steppings 0-4h. 1217e3dbbacSRobert Mustacchi.It Xr slm_events 3CPC 1227e3dbbacSRobert MustacchiIntel Atom Silvermont events; covers models 4ch, 4dh, and 37h. 12343449cdcSRobert Mustacchi.It Xr snr_Events 3CPC 12443449cdcSRobert MustacchiIntel Atom Snow Ridge events; covers model 86h. 1257e3dbbacSRobert Mustacchi.It Xr snb_events 3CPC 12643449cdcSRobert MustacchiIntel Sandy Bridge client events; covers model 2ah. 12743449cdcSRobert Mustacchi.It Xr tgl_events 3CPC 12843449cdcSRobert MustacchiIntel Tiger Lake client events; covers models 8ch and 8dh. 1297e3dbbacSRobert Mustacchi.It Xr wsm_ep_dp_events 3CPC 1307e3dbbacSRobert MustacchiIntel Westmere-EP-DP events; covers model 2ch. 1317e3dbbacSRobert Mustacchi.It Xr wsm_ep_sp_events 3CPC 1327e3dbbacSRobert MustacchiIntel Westmere-EP-SP events; covers model 25h. 1337e3dbbacSRobert Mustacchi.It Xr wsm_ex_events 3CPC 1347e3dbbacSRobert MustacchiIntel Westmere-EX events; covers model 2fh. 1357e3dbbacSRobert Mustacchi.El 136d0e58ef5SRobert Mustacchi.Ss AMD Processor Specific Events 137d0e58ef5SRobert MustacchiThe following manual pages provide more detailed information on the 138d0e58ef5SRobert Mustacchievents available for the specific AMD processor models. 139d0e58ef5SRobert MustacchiThe covered processor families are listed in hexadecimal. 140d0e58ef5SRobert Mustacchi.Bl -tag -width Xr 14131aa6202SRobert Mustacchi.It Xr amd_f17h_zen1_events 3CPC 14231aa6202SRobert MustacchiAMD Family 17h Zen 1 processors, including models 00-2fh. 143281939dfSRobert MustacchiIncludes Ryzen, ThreadRipper, and EPYC branded processors. 14431aa6202SRobert Mustacchi.It Xr amd_f17h_zen2_events 3CPC 14531aa6202SRobert MustacchiAMD Family 17h Zen 2 processors, including models 30-7fh. 146281939dfSRobert MustacchiIncludes Ryzen, ThreadRipper, and EPYC branded processors. 147281939dfSRobert Mustacchi.It Xr amd_f17h_zen3_events 3CPC 148*8efb7381SRobert MustacchiAMD Family 19h Zen 3 processors, including models 00-0fh and 20-2fh. 149*8efb7381SRobert MustacchiIncludes Ryzen and EPYC branded processors. 150d0e58ef5SRobert Mustacchi.El 1517e3dbbacSRobert Mustacchi.Ss Using Attributes 152c10c16deSRichard LoweSome processors have advanced performance counter capabilities that are 1537e3dbbacSRobert Mustacchiconfigured with attributes. 1547e3dbbacSRobert MustacchiThe 1557e3dbbacSRobert Mustacchi.Xr cpc_walk_attrs 3CPC 1567e3dbbacSRobert Mustacchifunction can be used to determine the names of attributes supported by 1577e3dbbacSRobert Mustacchithe underlying processor. 1587e3dbbacSRobert MustacchiThe documentation referenced by 1597e3dbbacSRobert Mustacchi.Xr cpc_cpuref 3CPC 1607e3dbbacSRobert Mustacchishould be consulted to understand the meaning of a processor's performance 1617e3dbbacSRobert Mustacchicounter attributes. 1627e3dbbacSRobert Mustacchi.Ss Performance Counter Context 163c10c16deSRichard LoweEach processor on the system possesses its own set of performance counter 1647e3dbbacSRobert Mustacchiregisters. 1657e3dbbacSRobert MustacchiFor a single process, it is often desirable to maintain the illusion 166c10c16deSRichard Lowethat the counters are an intrinsic part of that process (whichever processors 167c10c16deSRichard Loweit runs on), since this allows the events to be directly attributed to the 168c10c16deSRichard Loweprocess without having to make passive all other activity on the system. 1697e3dbbacSRobert Mustacchi.Pp 1707e3dbbacSRobert MustacchiTo achieve this behavior, the library associates 1717e3dbbacSRobert Mustacchi.Em performance counter context 1727e3dbbacSRobert Mustacchiwith each 1737e3dbbacSRobert Mustacchi.Sy LWP 1747e3dbbacSRobert Mustacchiin the process. 1757e3dbbacSRobert MustacchiThe context consists of a small amount of kernel memory to hold the counter 1767e3dbbacSRobert Mustacchivalues when the 1777e3dbbacSRobert Mustacchi.Sy BLWP 1787e3dbbacSRobert Mustacchiis not running, and some simple kernel functions to save and restore those counter 1797e3dbbacSRobert Mustacchivalues from and to the hardware registers when the 1807e3dbbacSRobert Mustacchi.Sy LWP 1817e3dbbacSRobert Mustacchiperforms a normal context switch. 1827e3dbbacSRobert MustacchiA process can only observe and manipulate its own copy of the 183c10c16deSRichard Loweperformance counter control and data registers. 1847e3dbbacSRobert Mustacchi.Ss Performance Counters \&In Other Processes 185c10c16deSRichard LoweThough applications can be modified to instrument themselves as demonstrated 186c10c16deSRichard Loweabove, it is frequently useful to be able to examine the behavior of an 1877e3dbbacSRobert Mustacchiexisting application without changing the source code. 1887e3dbbacSRobert MustacchiA separate library, 1897e3dbbacSRobert Mustacchi.Sy libpctx , 1907e3dbbacSRobert Mustacchiprovides a simple set of interfaces that use the facilities of 1917e3dbbacSRobert Mustacchi.Xr proc 4 1927e3dbbacSRobert Mustacchito control a target process, and together with functions in 1937e3dbbacSRobert Mustacchi.Sy libcpc , 1947e3dbbacSRobert Mustacchiallow 1957e3dbbacSRobert Mustacchi.Sy truss No -like 1967e3dbbacSRobert Mustacchitools to be constructed to measure the performance counters in other 1977e3dbbacSRobert Mustacchiapplications. 1987e3dbbacSRobert MustacchiAn example of one such application is 1997e3dbbacSRobert Mustacchi.Xr cputrack 1 . 2007e3dbbacSRobert Mustacchi.Pp 2017e3dbbacSRobert MustacchiThe functions in 2027e3dbbacSRobert Mustacchi.Sy libpctx 2037e3dbbacSRobert Mustacchiare independent of those in 2047e3dbbacSRobert Mustacchi.Sy libcpc . 2057e3dbbacSRobert MustacchiThese functions manage a process using an event-loop paradigm \(em that is, the 206c10c16deSRichard Loweexecution of certain system calls by the controlled process cause the library 207c10c16deSRichard Loweto stop the controlled process and execute callback functions in the context of 2087e3dbbacSRobert Mustacchithe controlling process. 2097e3dbbacSRobert MustacchiThese handlers can perform various operations on the target process using APIs 2107e3dbbacSRobert Mustacchiin 2117e3dbbacSRobert Mustacchi.Sy libpctx 2127e3dbbacSRobert Mustacchiand 2137e3dbbacSRobert Mustacchi.Sy libcpc 2147e3dbbacSRobert Mustacchithat consume 2157e3dbbacSRobert Mustacchi.Vt pctx_t 2167e3dbbacSRobert Mustacchihandles. 2177e3dbbacSRobert Mustacchi.Sh SEE ALSO 2187e3dbbacSRobert Mustacchi.Xr cputrack 1 , 2197e3dbbacSRobert Mustacchi.Xr cpustat 1M , 2207e3dbbacSRobert Mustacchi.Xr cpc_bind_curlwp 3CPC , 2217e3dbbacSRobert Mustacchi.Xr cpc_buf_create 3CPC , 2227e3dbbacSRobert Mustacchi.Xr cpc_enable 3CPC , 2237e3dbbacSRobert Mustacchi.Xr cpc_npic 3CPC , 2247e3dbbacSRobert Mustacchi.Xr cpc_open 3CPC , 2257e3dbbacSRobert Mustacchi.Xr cpc_set_create 3CPC , 2267e3dbbacSRobert Mustacchi.Xr cpc_seterrhndlr 3CPC , 2277e3dbbacSRobert Mustacchi.Xr generic_events 3CPC , 2287e3dbbacSRobert Mustacchi.Xr pctx_capture 3CPC , 2297e3dbbacSRobert Mustacchi.Xr pctx_set_events 3CPC , 2307e3dbbacSRobert Mustacchi.Xr libcpc 3LIB , 2317e3dbbacSRobert Mustacchi.Xr proc 4 232