xref: /illumos-gate/usr/src/man/man3cpc/cpc.3cpc (revision e6bda3ff)
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