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