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. 6*e6bda3ffSRobert Mustacchi.\" Copyright 2023 Oxide Computer Company 7*e6bda3ffSRobert Mustacchi.Dd March 23, 2023 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 4611845c32SPeter Tribblelibrary available at runtime. 477e3dbbacSRobert Mustacchi.It Xr cpc_cciname 3CPC 48c10c16deSRichard LoweReturn a printable string to describe the performance counters of the 49c10c16deSRichard Loweprocessor. 507e3dbbacSRobert Mustacchi.It Xr cpc_npic 3CPC 51c10c16deSRichard LoweReturn the number of performance counters on the processor. 5211845c32SPeter Tribble.It Xr cpc_cpuref 3CPC 53c10c16deSRichard LoweReturn a reference to documentation that should be consulted to understand how 54c10c16deSRichard Loweto use and interpret data from the performance counters. 557e3dbbacSRobert Mustacchi.El 567e3dbbacSRobert Mustacchi.Ss Performance Counter Access 5711845c32SPeter TribblePerformance counters can be present in hardware but not accessible because 58c10c16deSRichard Loweeither some of the necessary system software components are not available or 597e3dbbacSRobert Mustacchinot installed, or the counters might be in use by other processes. 607e3dbbacSRobert MustacchiThe 617e3dbbacSRobert Mustacchi.Xr cpc_open 3CPC 627e3dbbacSRobert Mustacchifunction determines the accessibility of the counters and 63c10c16deSRichard Lowemust be invoked before any attempt to program the counters. 647e3dbbacSRobert Mustacchi.Ss "Finding Events" 65c10c16deSRichard LoweEach different type of processor has its own set of events available for 667e3dbbacSRobert Mustacchimeasurement. 677e3dbbacSRobert MustacchiThe 687e3dbbacSRobert Mustacchi.Xr cpc_walk_events_all 3CPC 697e3dbbacSRobert Mustacchiand 707e3dbbacSRobert Mustacchi.Xr cpc_walk_events_pic 3CPC 717e3dbbacSRobert Mustacchifunctions allow an application to determine the 727e3dbbacSRobert Mustacchinames of events supported by the underlying processor. 737e3dbbacSRobert MustacchiA collection of generic, platform independent event names are defined by 747e3dbbacSRobert Mustacchi.Xr generic_events 3CPC . 75c10c16deSRichard LoweEach generic event maps to an underlying hardware event specific to the 767e3dbbacSRobert Mustacchiunderlying processor and any optional attributes. 777e3dbbacSRobert MustacchiThe 787e3dbbacSRobert Mustacchi.Xr cpc_walk_generic_events_all 3CPC 797e3dbbacSRobert Mustacchiand 807e3dbbacSRobert Mustacchi.Xr cpc_walk_generic_events_pic 3CPC 817e3dbbacSRobert Mustacchifunctions allow an application to determine the generic events supported 827e3dbbacSRobert Mustacchion the underlying platform. 83d0e58ef5SRobert Mustacchi.Ss Intel Processor Specific Events 84d0e58ef5SRobert MustacchiThe following manual pages provide more detailed information on the 85d0e58ef5SRobert Mustacchievents available for the specific Intel processor models. 86d0e58ef5SRobert MustacchiThe covered processor models are listed in hexadecimal. 877e3dbbacSRobert Mustacchi.Bl -tag -width Xr 887e3dbbacSRobert Mustacchi.It Xr bdw_de_events 3CPC 897e3dbbacSRobert MustacchiIntel Broadwell-DE events; covers model 56h. 907e3dbbacSRobert Mustacchi.It Xr bdw_events 3CPC 917e3dbbacSRobert MustacchiIntel Broadwell client events; covers models 3dh and 47h. 927e3dbbacSRobert Mustacchi.It Xr bdx_events 3CPC 937e3dbbacSRobert MustacchiIntel Broadwell server events; covers model 4fh. 947e3dbbacSRobert Mustacchi.It Xr bnl_events 3CPC 957e3dbbacSRobert MustacchiIntel Atom Bonnell events; covers models 35h, 36h, 27h, 26h, and 1ch. 96c18e9bc3SRobert Mustacchi.It Xr clx_events 3CPC 97c18e9bc3SRobert MustacchiIntel Cascade Lake server events; covers model 55h, steppings 5-fh. 987e3dbbacSRobert Mustacchi.It Xr glm_events 3CPC 997e3dbbacSRobert MustacchiIntel Goldmont SoC events; covers models 5fh and 5ch. 1007e3dbbacSRobert Mustacchi.It Xr glp_events 3CPC 1017e3dbbacSRobert MustacchiIntel Goldmont Plus SoC events; covers model 7ah. 1027e3dbbacSRobert Mustacchi.It Xr hsw_events 3CPC 1037e3dbbacSRobert MustacchiIntel Haswell client events; covers models 46h, 45h, and 3ch. 1047e3dbbacSRobert Mustacchi.It Xr hsx_events 3CPC 1057e3dbbacSRobert MustacchiIntel Haswell server events; covers model 3fh. 10611845c32SPeter Tribble.It Xr icl_events 3CPC 10743449cdcSRobert MustacchiIntel Ice Lake client events; covers model 7eh. 1087e3dbbacSRobert Mustacchi.It Xr ivb_events 3CPC 1097e3dbbacSRobert MustacchiIntel Ivy Bridge client events; covers model 3ah. 1107e3dbbacSRobert Mustacchi.It Xr ivt_events 3CPC 1117e3dbbacSRobert MustacchiIntel Ivy Bridge server events; covers model 3eh. 1127e3dbbacSRobert Mustacchi.It Xr jkt_events 3CPC 1137e3dbbacSRobert MustacchiIntel Sandy Bridge server events; covers model 2dh. 1147e3dbbacSRobert Mustacchi.It Xr nhm_ep_events 3CPC 1157e3dbbacSRobert MustacchiIntel Nehalem-EP events; covers models, 1ah, 1fh, and 1eh. 1167e3dbbacSRobert Mustacchi.It Xr nhm_ex_events 3CPC 1177e3dbbacSRobert MustacchiIntel Sandy Bridge server events; covers model 23h. 1187e3dbbacSRobert Mustacchi.It Xr skl_events 3CPC 11943449cdcSRobert MustacchiIntel Skylake client events; covers model a6h, a5h, 9eh, 8eh, 5e, and 4eh. 1207e3dbbacSRobert Mustacchi.It Xr skx_events 3CPC 121c18e9bc3SRobert MustacchiIntel Skylake server events; covers model 55h, steppings 0-4h. 1227e3dbbacSRobert Mustacchi.It Xr slm_events 3CPC 1237e3dbbacSRobert MustacchiIntel Atom Silvermont events; covers models 4ch, 4dh, and 37h. 12443449cdcSRobert Mustacchi.It Xr snr_Events 3CPC 12543449cdcSRobert MustacchiIntel Atom Snow Ridge events; covers model 86h. 1267e3dbbacSRobert Mustacchi.It Xr snb_events 3CPC 12743449cdcSRobert MustacchiIntel Sandy Bridge client events; covers model 2ah. 12843449cdcSRobert Mustacchi.It Xr tgl_events 3CPC 12943449cdcSRobert MustacchiIntel Tiger Lake client events; covers models 8ch and 8dh. 1307e3dbbacSRobert Mustacchi.It Xr wsm_ep_dp_events 3CPC 1317e3dbbacSRobert MustacchiIntel Westmere-EP-DP events; covers model 2ch. 1327e3dbbacSRobert Mustacchi.It Xr wsm_ep_sp_events 3CPC 1337e3dbbacSRobert MustacchiIntel Westmere-EP-SP events; covers model 25h. 1347e3dbbacSRobert Mustacchi.It Xr wsm_ex_events 3CPC 1357e3dbbacSRobert MustacchiIntel Westmere-EX events; covers model 2fh. 1367e3dbbacSRobert Mustacchi.El 137d0e58ef5SRobert Mustacchi.Ss AMD Processor Specific Events 138d0e58ef5SRobert MustacchiThe following manual pages provide more detailed information on the 139d0e58ef5SRobert Mustacchievents available for the specific AMD processor models. 140d0e58ef5SRobert MustacchiThe covered processor families are listed in hexadecimal. 141d0e58ef5SRobert Mustacchi.Bl -tag -width Xr 14231aa6202SRobert Mustacchi.It Xr amd_f17h_zen1_events 3CPC 14331aa6202SRobert MustacchiAMD Family 17h Zen 1 processors, including models 00-2fh. 144281939dfSRobert MustacchiIncludes Ryzen, ThreadRipper, and EPYC branded processors. 14531aa6202SRobert Mustacchi.It Xr amd_f17h_zen2_events 3CPC 146*e6bda3ffSRobert MustacchiAMD Family 17h Zen 2 processors, including models 30-afh. 147281939dfSRobert MustacchiIncludes Ryzen, ThreadRipper, and EPYC branded processors. 148281939dfSRobert Mustacchi.It Xr amd_f17h_zen3_events 3CPC 14964168f2bSRobert MustacchiAMD Family 19h Zen 3 processors, including models 00-0fh, 20-2fh, and 150*e6bda3ffSRobert Mustacchi40-5fh. 151*e6bda3ffSRobert MustacchiIncludes Ryzen, ThreadRipper, and EPYC branded processors. 152*e6bda3ffSRobert Mustacchi.It Xr amd_f17h_zen4_events 3CPC 153*e6bda3ffSRobert MustacchiAMD Family 19h Zen 4 processors, including models 10-1fh, 60-7fh, and 154*e6bda3ffSRobert Mustacchia0-afh. 1558efb7381SRobert MustacchiIncludes Ryzen and EPYC branded processors. 156d0e58ef5SRobert Mustacchi.El 1577e3dbbacSRobert Mustacchi.Ss Using Attributes 158c10c16deSRichard LoweSome processors have advanced performance counter capabilities that are 1597e3dbbacSRobert Mustacchiconfigured with attributes. 1607e3dbbacSRobert MustacchiThe 1617e3dbbacSRobert Mustacchi.Xr cpc_walk_attrs 3CPC 1627e3dbbacSRobert Mustacchifunction can be used to determine the names of attributes supported by 1637e3dbbacSRobert Mustacchithe underlying processor. 1647e3dbbacSRobert MustacchiThe documentation referenced by 1657e3dbbacSRobert Mustacchi.Xr cpc_cpuref 3CPC 1667e3dbbacSRobert Mustacchishould be consulted to understand the meaning of a processor's performance 1677e3dbbacSRobert Mustacchicounter attributes. 1687e3dbbacSRobert Mustacchi.Ss Performance Counter Context 169c10c16deSRichard LoweEach processor on the system possesses its own set of performance counter 1707e3dbbacSRobert Mustacchiregisters. 1717e3dbbacSRobert MustacchiFor a single process, it is often desirable to maintain the illusion 172c10c16deSRichard Lowethat the counters are an intrinsic part of that process (whichever processors 173c10c16deSRichard Loweit runs on), since this allows the events to be directly attributed to the 174c10c16deSRichard Loweprocess without having to make passive all other activity on the system. 1757e3dbbacSRobert Mustacchi.Pp 1767e3dbbacSRobert MustacchiTo achieve this behavior, the library associates 1777e3dbbacSRobert Mustacchi.Em performance counter context 1787e3dbbacSRobert Mustacchiwith each 1797e3dbbacSRobert Mustacchi.Sy LWP 1807e3dbbacSRobert Mustacchiin the process. 1817e3dbbacSRobert MustacchiThe context consists of a small amount of kernel memory to hold the counter 1827e3dbbacSRobert Mustacchivalues when the 1837e3dbbacSRobert Mustacchi.Sy BLWP 1847e3dbbacSRobert Mustacchiis not running, and some simple kernel functions to save and restore those counter 1857e3dbbacSRobert Mustacchivalues from and to the hardware registers when the 1867e3dbbacSRobert Mustacchi.Sy LWP 1877e3dbbacSRobert Mustacchiperforms a normal context switch. 1887e3dbbacSRobert MustacchiA process can only observe and manipulate its own copy of the 189c10c16deSRichard Loweperformance counter control and data registers. 1907e3dbbacSRobert Mustacchi.Ss Performance Counters \&In Other Processes 191c10c16deSRichard LoweThough applications can be modified to instrument themselves as demonstrated 192c10c16deSRichard Loweabove, it is frequently useful to be able to examine the behavior of an 1937e3dbbacSRobert Mustacchiexisting application without changing the source code. 1947e3dbbacSRobert MustacchiA separate library, 1957e3dbbacSRobert Mustacchi.Sy libpctx , 1967e3dbbacSRobert Mustacchiprovides a simple set of interfaces that use the facilities of 197bbf21555SRichard Lowe.Xr proc 5 1987e3dbbacSRobert Mustacchito control a target process, and together with functions in 1997e3dbbacSRobert Mustacchi.Sy libcpc , 2007e3dbbacSRobert Mustacchiallow 2017e3dbbacSRobert Mustacchi.Sy truss No -like 2027e3dbbacSRobert Mustacchitools to be constructed to measure the performance counters in other 2037e3dbbacSRobert Mustacchiapplications. 2047e3dbbacSRobert MustacchiAn example of one such application is 2057e3dbbacSRobert Mustacchi.Xr cputrack 1 . 2067e3dbbacSRobert Mustacchi.Pp 2077e3dbbacSRobert MustacchiThe functions in 2087e3dbbacSRobert Mustacchi.Sy libpctx 2097e3dbbacSRobert Mustacchiare independent of those in 2107e3dbbacSRobert Mustacchi.Sy libcpc . 2117e3dbbacSRobert MustacchiThese functions manage a process using an event-loop paradigm \(em that is, the 212c10c16deSRichard Loweexecution of certain system calls by the controlled process cause the library 213c10c16deSRichard Loweto stop the controlled process and execute callback functions in the context of 2147e3dbbacSRobert Mustacchithe controlling process. 2157e3dbbacSRobert MustacchiThese handlers can perform various operations on the target process using APIs 2167e3dbbacSRobert Mustacchiin 2177e3dbbacSRobert Mustacchi.Sy libpctx 2187e3dbbacSRobert Mustacchiand 2197e3dbbacSRobert Mustacchi.Sy libcpc 2207e3dbbacSRobert Mustacchithat consume 2217e3dbbacSRobert Mustacchi.Vt pctx_t 2227e3dbbacSRobert Mustacchihandles. 2237e3dbbacSRobert Mustacchi.Sh SEE ALSO 2247e3dbbacSRobert Mustacchi.Xr cputrack 1 , 2257e3dbbacSRobert Mustacchi.Xr cpc_bind_curlwp 3CPC , 2267e3dbbacSRobert Mustacchi.Xr cpc_buf_create 3CPC , 2277e3dbbacSRobert Mustacchi.Xr cpc_enable 3CPC , 2287e3dbbacSRobert Mustacchi.Xr cpc_npic 3CPC , 2297e3dbbacSRobert Mustacchi.Xr cpc_open 3CPC , 2307e3dbbacSRobert Mustacchi.Xr cpc_set_create 3CPC , 2317e3dbbacSRobert Mustacchi.Xr cpc_seterrhndlr 3CPC , 2327e3dbbacSRobert Mustacchi.Xr generic_events 3CPC , 2337e3dbbacSRobert Mustacchi.Xr pctx_capture 3CPC , 2347e3dbbacSRobert Mustacchi.Xr pctx_set_events 3CPC , 2357e3dbbacSRobert Mustacchi.Xr libcpc 3LIB , 236bbf21555SRichard Lowe.Xr proc 5 , 237bbf21555SRichard Lowe.Xr cpustat 8 238