Reference

pmc.ibs(3)

Instruction Based Sampling for AMD CPUs

NAME

pmc.ibs – Instruction Based Sampling for AMD CPUs

LIBRARY

library “libpmc”

SYNOPSIS

#include <pmc.h>

DESCRIPTION

AMD Instruction Based Sampling (IBS) was introduced with the K10 family of CPUs. AMD IBS is an alternative approach that samples instructions or micro-ops and provides a per-instruction or micro-op breakdown of the sources of stalls.

Unlike traditional counters, IBS can only be used in the sampling mode and provides extra data embedded in the callchain. IBS events set the PMC_F_MULTIPART flag to signify multiple payload types are contained in the callchain. The first 8 bytes of the callchain contain four tuples with a one byte type and a one byte length field. The regular PMC callchain can be found following the multipart payload.

IBS only provides two events that analyze instruction fetches and instruction execution. The instruction fetch (ibs-fetch) event provides data on the processor front-end including reporting instruction cache and TLB events. The instruction execution (ibs-op) event provides data on the processor execution including reporting mispredictions, data cache and TLB events. You should use the AMD PMC counters documented in pmc.amd(3) to analyze stalls relating instruction issue including reservation contention.

A guide to analyzing IBS data is provided in Appendix G of the Software Optimization Guide for AMD Family 10h and 12h Processors, Publication No. 40546, Advanced Micro Devices, Inc., February 2011. A more recent document should be used for decoding all of the flags and fields in the IBS data. For example, see the AMD Zen 5 documentation Processor Programming Reference (PPR) for AMD Family 1Ah Model 02h, Publication No. 57238, Advanced Micro Devices, Inc., March 6, 2026.

PMC Features

AMD IBS supports the following capabilities.

CapabilitySupport
PMC_CAP_CASCADENo
PMC_CAP_EDGEYes
PMC_CAP_INTERRUPTYes
PMC_CAP_INVERTNo
PMC_CAP_READNo
PMC_CAP_PRECISEYes
PMC_CAP_SYSTEMYes
PMC_CAP_TAGGINGNo
PMC_CAP_THRESHOLDNo
PMC_CAP_USERYes (Zen 6)
PMC_CAP_WRITENo

By default AMD IBS enables the edge, interrupt, system and precise flags.

Event Qualifiers

Event specifiers for AMD IBS can have the following optional qualifiers:

usr

Valid for both ibs-fetch and ibs-op events. Configure the counter to only sample user-mode events. Requires Zen 6 IBS extensions (CPUID Fn8000_0001B()) EAX[IbsAddrBit63Filtering], and is rejected when the CPU does not advertise support.

os

Valid for both ibs-fetch and ibs-op events. Configure the counter to only sample kernel-mode events. Requires Zen 6 IBS extensions (CPUID Fn8000_0001B()) EAX[IbsAddrBit63Filtering], and is rejected when the CPU does not advertise support.

fetchlat=value

Valid only for ibs-fetch events. Configure the counter to only sample fetches whose latency is greater than or equal to value core clock cycles. The valid range is 128 to 1920 in steps of 128. Requires Zen 6 IBS extensions (CPUID Fn8000_0001B()) EAX[IbsFetchLatencyFiltering], and is rejected when the CPU does not advertise support.

l3miss

Valid for both ibs-fetch and ibs-op events. Configure IBS to only sample if an l3miss occurred.

ldlat=value

Valid only for ibs-op events. Configure the counter to only sample events with load latencies above ldlat. IBS only supports filtering latencies that are a multiple of 128 and between 128 and 2048. On pre-Zen 6 hardware this qualifier implies the l3miss qualifier; on Zen 6 and later, latency-only filtering without l3miss is permitted.

opcount

Valid only for ibs-op events. Count ops rather than cycles.

randomize

Valid only for ibs-fetch events. Randomize the sampling rate.

streamstore

Valid only for ibs-op events. Configure the counter to only sample streaming (non-temporal) store operations. Requires Zen 6 IBS extensions (CPUID Fn8000_0001B()) EAX[IbsStrmStAndRmtSocket], and is rejected when the CPU does not advertise support.

AMD IBS Events Specifiers

The IBS event class provides only two event specifiers:

ibs-fetch

[,usr] [,os] [,fetchlat=value] [,l3miss] [,randomize] Collect performance samples during instruction fetch. The randomize qualifier randomly sets the bottom four bits of the sample rate.

ibs-op

[,usr] [,os] [,l3miss] [,ldlat=ldlat] [,opcount] [,streamstore] Collect performance samples during instruction execution. The opcount qualifier, upon reaching the maximum count, restarts the count with a random value between 1 and 127.

You may collect both events at the same time. N.B. AMD discouraged doing so with certain older processors, stating that sampling both simultaneously perturbs the results. Please see the processor programming reference for your specific processor.

SEE ALSO

pmc(3), pmc.amd(3), pmc.soft(3), pmc.tsc(3), pmclog(3), hwpmc(4)

HISTORY

AMD IBS support was first introduced in FreeBSD 16.0.

AUTHORS

AMD IBS support and this manual page were written Ali Mashtizadeh ⟨[email protected]⟩ and sponsored by Netflix, Inc.