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 \&No 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 "ldlat=value" 101.It Li l3miss 102Configure IBS to only sample if an l3miss occurred. 103.It Li ldlat= Ns Ar value 104Configure the counter to only sample events with load latencies above 105.Ar ldlat . 106IBS only supports filtering latencies that are a multiple of 128 and between 107128 and 2048. 108Load latency filtering can only be used with ibs-op events and imply the 109l3miss qualifier. 110.It Li randomize 111Randomize the sampling rate. 112.El 113.Ss AMD IBS Events Specifiers 114The IBS event class provides only two event specifiers: 115.Bl -tag -width indent 116.It Li ibs-fetch Xo 117.Op ,l3miss 118.Op ,randomize 119.Xc 120Collect performance samples during instruction fetch. 121The 122.Ar randomize 123qualifier randomly sets the bottom four bits of the sample rate. 124.It Li ibs-op Xo 125.Op ,l3miss 126.Op ,ldlat= Ns Ar ldlat 127.Op ,randomize 128.Xc 129Collect performance samples during instruction execution. 130The 131.Ar randomize 132qualifier, upon reaching the maximum count, restarts the count with a value 133between 1 and 127. 134.El 135.Pp 136You may collect both events at the same time. 137N.B. AMD discouraged doing so with certain older processors, stating that 138sampling both simultaneously perturbs the results. 139Please see the processor programming reference for your specific processor. 140.Sh SEE ALSO 141.Xr pmc 3 , 142.Xr pmc.amd 3 , 143.Xr pmc.soft 3 , 144.Xr pmc.tsc 3 , 145.Xr pmclog 3 , 146.Xr hwpmc 4 147.Sh HISTORY 148AMD IBS support was first introduced in 149.Fx 16.0 . 150.Sh AUTHORS 151AMD IBS support and this manual page were written 152.An Ali Mashtizadeh Aq Mt ali@mashtizadeh.com 153and sponsored by Netflix, Inc. 154