1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2026, Netflix, Inc. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd March 15, 2026 28.Dt PMC.IBS 3 29.Os 30.Sh NAME 31.Nm pmc.ibs 32.Nd Instruction Based Sampling for 33.Tn AMD 34CPUs 35.Sh LIBRARY 36.Lb libpmc 37.Sh SYNOPSIS 38.In pmc.h 39.Sh DESCRIPTION 40AMD Instruction Based Sampling (IBS) was introduced with the K10 family of 41CPUs. 42AMD IBS is an alternative approach that samples instructions or micro-ops and 43provides a per-instruction or micro-op breakdown of the sources of stalls. 44.Pp 45Unlike traditional counters, IBS can only be used in the sampling mode and 46provides extra data embedded in the callchain. 47IBS events set the PMC_F_MULTIPART flag to signify multiple payload types are 48contained in the callchain. 49The first 8 bytes of the callchain contain four tuples with a one byte type and 50a one byte length field. 51The regular PMC callchain can be found following the multipart payload. 52.Pp 53IBS only provides two events that analyze instruction fetches and instruction 54execution. 55The instruction fetch (ibs-fetch) event provides data on the processor 56front-end including reporting instruction cache and TLB events. 57The instruction execution (ibs-op) event provides data on the processor 58execution including reporting mispredictions, data cache and TLB events. 59You should use the AMD PMC counters documented in 60.Xr pmc.amd 3 61to analyze stalls relating instruction issue including reservation contention. 62.Pp 63A guide to analyzing IBS data is provided in Appendix G of the 64.Rs 65.%B "Software Optimization Guide for AMD Family 10h and 12h Processors" 66.%N "Publication No. 40546" 67.%D "February 2011" 68.%Q "Advanced Micro Devices, Inc." 69.Re 70A more recent document should be used for decoding all of the flags and fields 71in the IBS data. 72For example, see the AMD Zen 5 documentation 73.Rs 74.%B "Processor Programming Reference (PPR) for AMD Family 1Ah Model 02h" 75.%N "Publication No. 57238" 76.%D "March 6, 2026" 77.%Q "Advanced Micro Devices, Inc." 78.Re 79.Ss PMC Features 80AMD IBS supports the following capabilities. 81.Bl -column "PMC_CAP_INTERRUPT" "Support" 82.It Em Capability Ta Em Support 83.It PMC_CAP_CASCADE Ta \&No 84.It PMC_CAP_EDGE Ta Yes 85.It PMC_CAP_INTERRUPT Ta Yes 86.It PMC_CAP_INVERT Ta \&No 87.It PMC_CAP_READ Ta \&No 88.It PMC_CAP_PRECISE Ta Yes 89.It PMC_CAP_SYSTEM Ta Yes 90.It PMC_CAP_TAGGING Ta \&No 91.It PMC_CAP_THRESHOLD Ta \&No 92.It PMC_CAP_USER Ta Yes (Zen 6) 93.It PMC_CAP_WRITE Ta \&No 94.El 95.Pp 96By default AMD IBS enables the edge, interrupt, system and precise flags. 97.Ss Event Qualifiers 98Event specifiers for AMD IBS can have the following optional 99qualifiers: 100.Bl -tag -width "fetchlat=value" 101.It Li usr 102Valid for both 103.Ar ibs-fetch 104and 105.Ar ibs-op 106events. 107Configure the counter to only sample user-mode events. 108Requires Zen 6 IBS extensions 109.Pq CPUID Fn Fn8000_0001B 110.Va EAX[IbsAddrBit63Filtering] , 111and is rejected when the CPU does not advertise support. 112.It Li os 113Valid for both 114.Ar ibs-fetch 115and 116.Ar ibs-op 117events. 118Configure the counter to only sample kernel-mode events. 119Requires Zen 6 IBS extensions 120.Pq CPUID Fn Fn8000_0001B 121.Va EAX[IbsAddrBit63Filtering] , 122and is rejected when the CPU does not advertise support. 123.It Li fetchlat= Ns Ar value 124Valid only for 125.Ar ibs-fetch 126events. 127Configure the counter to only sample fetches whose latency is greater than or 128equal to 129.Ar value 130core clock cycles. 131The valid range is 128 to 1920 in steps of 128. 132Requires Zen 6 IBS extensions 133.Pq CPUID Fn Fn8000_0001B 134.Va EAX[IbsFetchLatencyFiltering] , 135and is rejected when the CPU does not advertise support. 136.It Li l3miss 137Valid for both 138.Ar ibs-fetch 139and 140.Ar ibs-op 141events. 142Configure IBS to only sample if an l3miss occurred. 143.It Li ldlat= Ns Ar value 144Valid only for 145.Ar ibs-op 146events. 147Configure the counter to only sample events with load latencies above 148.Ar ldlat . 149IBS only supports filtering latencies that are a multiple of 128 and between 150128 and 2048. 151On pre-Zen 6 hardware this qualifier implies the 152.Li l3miss 153qualifier; on Zen 6 and later, latency-only filtering without 154.Li l3miss 155is permitted. 156.It Li opcount 157Valid only for 158.Ar ibs-op 159events. 160Count ops rather than cycles. 161.It Li randomize 162Valid only for 163.Ar ibs-fetch 164events. 165Randomize the sampling rate. 166.It Li streamstore 167Valid only for 168.Ar ibs-op 169events. 170Configure the counter to only sample streaming 171.Pq non-temporal 172store operations. 173Requires Zen 6 IBS extensions 174.Pq CPUID Fn Fn8000_0001B 175.Va EAX[IbsStrmStAndRmtSocket] , 176and is rejected when the CPU does not advertise support. 177.El 178.Ss AMD IBS Events Specifiers 179The IBS event class provides only two event specifiers: 180.Bl -tag -width indent 181.It Li ibs-fetch Xo 182.Op ,usr 183.Op ,os 184.Op ,fetchlat= Ns Ar value 185.Op ,l3miss 186.Op ,randomize 187.Xc 188Collect performance samples during instruction fetch. 189The 190.Ar randomize 191qualifier randomly sets the bottom four bits of the sample rate. 192.It Li ibs-op Xo 193.Op ,usr 194.Op ,os 195.Op ,l3miss 196.Op ,ldlat= Ns Ar ldlat 197.Op ,opcount 198.Op ,streamstore 199.Xc 200Collect performance samples during instruction execution. 201The 202.Ar opcount 203qualifier, upon reaching the maximum count, restarts the count with a random 204value between 1 and 127. 205.El 206.Pp 207You may collect both events at the same time. 208N.B. AMD discouraged doing so with certain older processors, stating that 209sampling both simultaneously perturbs the results. 210Please see the processor programming reference for your specific processor. 211.Sh SEE ALSO 212.Xr pmc 3 , 213.Xr pmc.amd 3 , 214.Xr pmc.soft 3 , 215.Xr pmc.tsc 3 , 216.Xr pmclog 3 , 217.Xr hwpmc 4 218.Sh HISTORY 219AMD IBS support was first introduced in 220.Fx 16.0 . 221.Sh AUTHORS 222AMD IBS support and this manual page were written 223.An Ali Mashtizadeh Aq Mt ali@mashtizadeh.com 224and sponsored by Netflix, Inc. 225