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