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*d0e58ef5SRobert Mustacchi.Dd March 25, 2019 77e3dbbacSRobert Mustacchi.Dt CPC 3CPC 87e3dbbacSRobert Mustacchi.Os 97e3dbbacSRobert Mustacchi.Sh NAME 107e3dbbacSRobert Mustacchi.Nm cpc 117e3dbbacSRobert Mustacchi.Nd hardware performance counters 127e3dbbacSRobert Mustacchi.Sh DESCRIPTION 137e3dbbacSRobert MustacchiModern microprocessors contain 147e3dbbacSRobert Mustacchi.Em hardware performance counters 157e3dbbacSRobert Mustacchithat allow 16c10c16deSRichard Lowethe measurement of many different hardware events related to CPU behavior, 17c10c16deSRichard Loweincluding instruction and data cache misses as well as various internal states 187e3dbbacSRobert Mustacchiof the processor. 197e3dbbacSRobert MustacchiThe counters can be configured to count user events, system 207e3dbbacSRobert Mustacchievents, or both. 217e3dbbacSRobert MustacchiData from the performance counters can be used to analyze and 22c10c16deSRichard Lowetune the behavior of software on a particular type of processor. 237e3dbbacSRobert Mustacchi.Pp 24c10c16deSRichard LoweMost processors are able to generate an interrupt on counter overflow, allowing 25c10c16deSRichard Lowethe counters to be used for various forms of profiling. 267e3dbbacSRobert Mustacchi.Pp 277e3dbbacSRobert MustacchiThis manual page describes a set of APIs that allow illumos applications to use 287e3dbbacSRobert Mustacchithese counters. 297e3dbbacSRobert MustacchiApplications can measure their own behavior, the behavior of 30c10c16deSRichard Loweother applications, or the behavior of the whole system. 317e3dbbacSRobert Mustacchi.Ss Shared Counters or Private Counters 327e3dbbacSRobert MustacchiThere are two principal models for using these performance counters. 337e3dbbacSRobert MustacchiSome users of these statistics want to observe system-wide behavior. 347e3dbbacSRobert MustacchiOther users want to view the performance counters as part of the register set 357e3dbbacSRobert Mustacchiexported by each 367e3dbbacSRobert Mustacchi.Sy LWP . 377e3dbbacSRobert MustacchiOn a machine performing more than one activity, these two models are 38c10c16deSRichard Lowein conflict because the counters represent a critical hardware resource that 39c10c16deSRichard Lowecannot simultaneously be both shared and private. 407e3dbbacSRobert Mustacchi.Ss Configuration Interfaces 41c10c16deSRichard LoweThe following configuration interfaces are provided: 427e3dbbacSRobert Mustacchi.Bl -tag -width Xr 437e3dbbacSRobert Mustacchi.It Xr cpc_open 3CPC 44c10c16deSRichard LoweCheck the version the application was compiled with against the version of the 457e3dbbacSRobert Mustacchi.It Xr cpc_cciname 3CPC 46c10c16deSRichard LoweReturn a printable string to describe the performance counters of the 47c10c16deSRichard Loweprocessor. 487e3dbbacSRobert Mustacchi.It Xr cpc_npic 3CPC 49c10c16deSRichard LoweReturn the number of performance counters on the processor. 507e3dbbacSRobert Mustacchi.It cpc_cpuref 3CPC 51c10c16deSRichard LoweReturn a reference to documentation that should be consulted to understand how 52c10c16deSRichard Loweto use and interpret data from the performance counters. 537e3dbbacSRobert Mustacchi.El 547e3dbbacSRobert Mustacchi.Ss Performance Counter Access 55c10c16deSRichard LowePerformance counters can be present in hardware but not acccessible because 56c10c16deSRichard Loweeither some of the necessary system software components are not available or 577e3dbbacSRobert Mustacchinot installed, or the counters might be in use by other processes. 587e3dbbacSRobert MustacchiThe 597e3dbbacSRobert Mustacchi.Xr cpc_open 3CPC 607e3dbbacSRobert Mustacchifunction determines the accessibility of the counters and 61c10c16deSRichard Lowemust be invoked before any attempt to program the counters. 627e3dbbacSRobert Mustacchi.Ss "Finding Events" 63c10c16deSRichard LoweEach different type of processor has its own set of events available for 647e3dbbacSRobert Mustacchimeasurement. 657e3dbbacSRobert MustacchiThe 667e3dbbacSRobert Mustacchi.Xr cpc_walk_events_all 3CPC 677e3dbbacSRobert Mustacchiand 687e3dbbacSRobert Mustacchi.Xr cpc_walk_events_pic 3CPC 697e3dbbacSRobert Mustacchifunctions allow an application to determine the 707e3dbbacSRobert Mustacchinames of events supported by the underlying processor. 717e3dbbacSRobert MustacchiA collection of generic, platform independent event names are defined by 727e3dbbacSRobert Mustacchi.Xr generic_events 3CPC . 73c10c16deSRichard LoweEach generic event maps to an underlying hardware event specific to the 747e3dbbacSRobert Mustacchiunderlying processor and any optional attributes. 757e3dbbacSRobert MustacchiThe 767e3dbbacSRobert Mustacchi.Xr cpc_walk_generic_events_all 3CPC 777e3dbbacSRobert Mustacchiand 787e3dbbacSRobert Mustacchi.Xr cpc_walk_generic_events_pic 3CPC 797e3dbbacSRobert Mustacchifunctions allow an application to determine the generic events supported 807e3dbbacSRobert Mustacchion the underlying platform. 81*d0e58ef5SRobert Mustacchi.Ss Intel Processor Specific Events 82*d0e58ef5SRobert MustacchiThe following manual pages provide more detailed information on the 83*d0e58ef5SRobert Mustacchievents available for the specific Intel processor models. 84*d0e58ef5SRobert MustacchiThe covered processor models are listed in hexadecimal. 857e3dbbacSRobert Mustacchi.Bl -tag -width Xr 867e3dbbacSRobert Mustacchi.It Xr bdw_de_events 3CPC 877e3dbbacSRobert MustacchiIntel Broadwell-DE events; covers model 56h. 887e3dbbacSRobert Mustacchi.It Xr bdw_events 3CPC 897e3dbbacSRobert MustacchiIntel Broadwell client events; covers models 3dh and 47h. 907e3dbbacSRobert Mustacchi.It Xr bdx_events 3CPC 917e3dbbacSRobert MustacchiIntel Broadwell server events; covers model 4fh. 927e3dbbacSRobert Mustacchi.It Xr bnl_events 3CPC 937e3dbbacSRobert MustacchiIntel Atom Bonnell events; covers models 35h, 36h, 27h, 26h, and 1ch. 94c18e9bc3SRobert Mustacchi.It Xr clx_events 3CPC 95c18e9bc3SRobert MustacchiIntel Cascade Lake server events; covers model 55h, steppings 5-fh. 967e3dbbacSRobert Mustacchi.It Xr glm_events 3CPC 977e3dbbacSRobert MustacchiIntel Goldmont SoC events; covers models 5fh and 5ch. 987e3dbbacSRobert Mustacchi.It Xr glp_events 3CPC 997e3dbbacSRobert MustacchiIntel Goldmont Plus SoC events; covers model 7ah. 1007e3dbbacSRobert Mustacchi.It Xr hsw_events 3CPC 1017e3dbbacSRobert MustacchiIntel Haswell client events; covers models 46h, 45h, and 3ch. 1027e3dbbacSRobert Mustacchi.It Xr hsx_events 3CPC 1037e3dbbacSRobert MustacchiIntel Haswell server events; covers model 3fh. 1047e3dbbacSRobert Mustacchi.It Xr ivb_events 3CPC 1057e3dbbacSRobert MustacchiIntel Ivy Bridge client events; covers model 3ah. 1067e3dbbacSRobert Mustacchi.It Xr ivt_events 3CPC 1077e3dbbacSRobert MustacchiIntel Ivy Bridge server events; covers model 3eh. 1087e3dbbacSRobert Mustacchi.It Xr jkt_events 3CPC 1097e3dbbacSRobert MustacchiIntel Sandy Bridge server events; covers model 2dh. 1107e3dbbacSRobert Mustacchi.It Xr nhm_ep_events 3CPC 1117e3dbbacSRobert MustacchiIntel Nehalem-EP events; covers models, 1ah, 1fh, and 1eh. 1127e3dbbacSRobert Mustacchi.It Xr nhm_ex_events 3CPC 1137e3dbbacSRobert MustacchiIntel Sandy Bridge server events; covers model 23h. 1147e3dbbacSRobert Mustacchi.It Xr skl_events 3CPC 1157e3dbbacSRobert MustacchiIntel Skylake client events; covers model 9eh, 8eh, 5e, and 4eh. 1167e3dbbacSRobert Mustacchi.It Xr skx_events 3CPC 117c18e9bc3SRobert MustacchiIntel Skylake server events; covers model 55h, steppings 0-4h. 1187e3dbbacSRobert Mustacchi.It Xr slm_events 3CPC 1197e3dbbacSRobert MustacchiIntel Atom Silvermont events; covers models 4ch, 4dh, and 37h. 1207e3dbbacSRobert Mustacchi.It Xr snb_events 3CPC 1217e3dbbacSRobert MustacchiIntel Sandy Bridge Client events; covers model 2ah. 1227e3dbbacSRobert Mustacchi.It Xr wsm_ep_dp_events 3CPC 1237e3dbbacSRobert MustacchiIntel Westmere-EP-DP events; covers model 2ch. 1247e3dbbacSRobert Mustacchi.It Xr wsm_ep_sp_events 3CPC 1257e3dbbacSRobert MustacchiIntel Westmere-EP-SP events; covers model 25h. 1267e3dbbacSRobert Mustacchi.It Xr wsm_ex_events 3CPC 1277e3dbbacSRobert MustacchiIntel Westmere-EX events; covers model 2fh. 1287e3dbbacSRobert Mustacchi.El 129*d0e58ef5SRobert Mustacchi.Ss AMD Processor Specific Events 130*d0e58ef5SRobert MustacchiThe following manual pages provide more detailed information on the 131*d0e58ef5SRobert Mustacchievents available for the specific AMD processor models. 132*d0e58ef5SRobert MustacchiThe covered processor families are listed in hexadecimal. 133*d0e58ef5SRobert Mustacchi.Bl -tag -width Xr 134*d0e58ef5SRobert Mustacchi.It Xr amd_f17h_events 3CPC 135*d0e58ef5SRobert MustacchiAMD Family 17h processors, including models 00-2fh. 136*d0e58ef5SRobert MustacchiInclude Ryzen, ThreadRipper, and EPYC branded processors. 137*d0e58ef5SRobert Mustacchi.El 1387e3dbbacSRobert Mustacchi.Ss Using Attributes 139c10c16deSRichard LoweSome processors have advanced performance counter capabilities that are 1407e3dbbacSRobert Mustacchiconfigured with attributes. 1417e3dbbacSRobert MustacchiThe 1427e3dbbacSRobert Mustacchi.Xr cpc_walk_attrs 3CPC 1437e3dbbacSRobert Mustacchifunction can be used to determine the names of attributes supported by 1447e3dbbacSRobert Mustacchithe underlying processor. 1457e3dbbacSRobert MustacchiThe documentation referenced by 1467e3dbbacSRobert Mustacchi.Xr cpc_cpuref 3CPC 1477e3dbbacSRobert Mustacchishould be consulted to understand the meaning of a processor's performance 1487e3dbbacSRobert Mustacchicounter attributes. 1497e3dbbacSRobert Mustacchi.Ss Performance Counter Context 150c10c16deSRichard LoweEach processor on the system possesses its own set of performance counter 1517e3dbbacSRobert Mustacchiregisters. 1527e3dbbacSRobert MustacchiFor a single process, it is often desirable to maintain the illusion 153c10c16deSRichard Lowethat the counters are an intrinsic part of that process (whichever processors 154c10c16deSRichard Loweit runs on), since this allows the events to be directly attributed to the 155c10c16deSRichard Loweprocess without having to make passive all other activity on the system. 1567e3dbbacSRobert Mustacchi.Pp 1577e3dbbacSRobert MustacchiTo achieve this behavior, the library associates 1587e3dbbacSRobert Mustacchi.Em performance counter context 1597e3dbbacSRobert Mustacchiwith each 1607e3dbbacSRobert Mustacchi.Sy LWP 1617e3dbbacSRobert Mustacchiin the process. 1627e3dbbacSRobert MustacchiThe context consists of a small amount of kernel memory to hold the counter 1637e3dbbacSRobert Mustacchivalues when the 1647e3dbbacSRobert Mustacchi.Sy BLWP 1657e3dbbacSRobert Mustacchiis not running, and some simple kernel functions to save and restore those counter 1667e3dbbacSRobert Mustacchivalues from and to the hardware registers when the 1677e3dbbacSRobert Mustacchi.Sy LWP 1687e3dbbacSRobert Mustacchiperforms a normal context switch. 1697e3dbbacSRobert MustacchiA process can only observe and manipulate its own copy of the 170c10c16deSRichard Loweperformance counter control and data registers. 1717e3dbbacSRobert Mustacchi.Ss Performance Counters \&In Other Processes 172c10c16deSRichard LoweThough applications can be modified to instrument themselves as demonstrated 173c10c16deSRichard Loweabove, it is frequently useful to be able to examine the behavior of an 1747e3dbbacSRobert Mustacchiexisting application without changing the source code. 1757e3dbbacSRobert MustacchiA separate library, 1767e3dbbacSRobert Mustacchi.Sy libpctx , 1777e3dbbacSRobert Mustacchiprovides a simple set of interfaces that use the facilities of 1787e3dbbacSRobert Mustacchi.Xr proc 4 1797e3dbbacSRobert Mustacchito control a target process, and together with functions in 1807e3dbbacSRobert Mustacchi.Sy libcpc , 1817e3dbbacSRobert Mustacchiallow 1827e3dbbacSRobert Mustacchi.Sy truss No -like 1837e3dbbacSRobert Mustacchitools to be constructed to measure the performance counters in other 1847e3dbbacSRobert Mustacchiapplications. 1857e3dbbacSRobert MustacchiAn example of one such application is 1867e3dbbacSRobert Mustacchi.Xr cputrack 1 . 1877e3dbbacSRobert Mustacchi.Pp 1887e3dbbacSRobert MustacchiThe functions in 1897e3dbbacSRobert Mustacchi.Sy libpctx 1907e3dbbacSRobert Mustacchiare independent of those in 1917e3dbbacSRobert Mustacchi.Sy libcpc . 1927e3dbbacSRobert MustacchiThese functions manage a process using an event-loop paradigm \(em that is, the 193c10c16deSRichard Loweexecution of certain system calls by the controlled process cause the library 194c10c16deSRichard Loweto stop the controlled process and execute callback functions in the context of 1957e3dbbacSRobert Mustacchithe controlling process. 1967e3dbbacSRobert MustacchiThese handlers can perform various operations on the target process using APIs 1977e3dbbacSRobert Mustacchiin 1987e3dbbacSRobert Mustacchi.Sy libpctx 1997e3dbbacSRobert Mustacchiand 2007e3dbbacSRobert Mustacchi.Sy libcpc 2017e3dbbacSRobert Mustacchithat consume 2027e3dbbacSRobert Mustacchi.Vt pctx_t 2037e3dbbacSRobert Mustacchihandles. 2047e3dbbacSRobert Mustacchi.Sh SEE ALSO 2057e3dbbacSRobert Mustacchi.Xr cputrack 1 , 2067e3dbbacSRobert Mustacchi.Xr cpustat 1M , 2077e3dbbacSRobert Mustacchi.Xr cpc_bind_curlwp 3CPC , 2087e3dbbacSRobert Mustacchi.Xr cpc_buf_create 3CPC , 2097e3dbbacSRobert Mustacchi.Xr cpc_enable 3CPC , 2107e3dbbacSRobert Mustacchi.Xr cpc_npic 3CPC , 2117e3dbbacSRobert Mustacchi.Xr cpc_open 3CPC , 2127e3dbbacSRobert Mustacchi.Xr cpc_set_create 3CPC , 2137e3dbbacSRobert Mustacchi.Xr cpc_seterrhndlr 3CPC , 2147e3dbbacSRobert Mustacchi.Xr generic_events 3CPC , 2157e3dbbacSRobert Mustacchi.Xr pctx_capture 3CPC , 2167e3dbbacSRobert Mustacchi.Xr pctx_set_events 3CPC , 2177e3dbbacSRobert Mustacchi.Xr libcpc 3LIB , 2187e3dbbacSRobert Mustacchi.Xr proc 4 219