Tribblix: manual page: cpc.3cpc

CPC(3CPC) CPU Performance Counters Library Functions CPC(3CPC)

NAME

cpc - hardware performance counters

DESCRIPTION

Modern microprocessors contain hardware performance counters that allow
the measurement of many different hardware events related to CPU
behavior, including instruction and data cache misses as well as
various internal states of the processor. The counters can be
configured to count user events, system events, or both. Data from the
performance counters can be used to analyze and tune the behavior of
software on a particular type of processor.

Most processors are able to generate an interrupt on counter overflow,
allowing the counters to be used for various forms of profiling.

This manual page describes a set of APIs that allow illumos
applications to use these counters. Applications can measure their own
behavior, the behavior of other applications, or the behavior of the
whole system.

Shared Counters or Private Counters

There are two principal models for using these performance counters.
Some users of these statistics want to observe system-wide behavior.
Other users want to view the performance counters as part of the
register set exported by each LWP. On a machine performing more than
one activity, these two models are in conflict because the counters
represent a critical hardware resource that cannot simultaneously be
both shared and private.

Configuration Interfaces

The following configuration interfaces are provided:

cpc_open(3CPC)
Check the version the application was compiled with against
the version of the library available at runtime.

cpc_cciname(3CPC)
Return a printable string to describe the performance
counters of the processor.

cpc_npic(3CPC)
Return the number of performance counters on the processor.

cpc_cpuref(3CPC)
Return a reference to documentation that should be
consulted to understand how to use and interpret data from
the performance counters.

Performance Counter Access

Performance counters can be present in hardware but not accessible
because either some of the necessary system software components are not
available or not installed, or the counters might be in use by other
processes. The cpc_open(3CPC) function determines the accessibility of
the counters and must be invoked before any attempt to program the
counters.

Finding Events

Each different type of processor has its own set of events available
for measurement. The cpc_walk_events_all(3CPC) and
cpc_walk_events_pic(3CPC) functions allow an application to determine
the names of events supported by the underlying processor. A
collection of generic, platform independent event names are defined by
generic_events(3CPC). Each generic event maps to an underlying
hardware event specific to the underlying processor and any optional
attributes. The cpc_walk_generic_events_all(3CPC) and
cpc_walk_generic_events_pic(3CPC) functions allow an application to
determine the generic events supported on the underlying platform.

Intel Processor Specific Events

The following manual pages provide more detailed information on the
events available for the specific Intel processor models. The covered
processor models are listed in hexadecimal.

bdw_de_events(3CPC)
Intel Broadwell-DE events; covers model 56h.

bdw_events(3CPC)
Intel Broadwell client events; covers models 3dh and 47h.

bdx_events(3CPC)
Intel Broadwell server events; covers model 4fh.

bnl_events(3CPC)
Intel Atom Bonnell events; covers models 35h, 36h, 27h,
26h, and 1ch.

clx_events(3CPC)
Intel Cascade Lake server events; covers model 55h,
steppings 5-fh.

glm_events(3CPC)
Intel Goldmont SoC events; covers models 5fh and 5ch.

glp_events(3CPC)
Intel Goldmont Plus SoC events; covers model 7ah.

hsw_events(3CPC)
Intel Haswell client events; covers models 46h, 45h, and
3ch.

hsx_events(3CPC)
Intel Haswell server events; covers model 3fh.

icl_events(3CPC)
Intel Ice Lake client events; covers model 7eh.

ivb_events(3CPC)
Intel Ivy Bridge client events; covers model 3ah.

ivt_events(3CPC)
Intel Ivy Bridge server events; covers model 3eh.

jkt_events(3CPC)
Intel Sandy Bridge server events; covers model 2dh.

nhm_ep_events(3CPC)
Intel Nehalem-EP events; covers models, 1ah, 1fh, and 1eh.

nhm_ex_events(3CPC)
Intel Sandy Bridge server events; covers model 23h.

skl_events(3CPC)
Intel Skylake client events; covers model a6h, a5h, 9eh,
8eh, 5e, and 4eh.

skx_events(3CPC)
Intel Skylake server events; covers model 55h, steppings
0-4h.

slm_events(3CPC)
Intel Atom Silvermont events; covers models 4ch, 4dh, and
37h.

snr_Events(3CPC)
Intel Atom Snow Ridge events; covers model 86h.

snb_events(3CPC)
Intel Sandy Bridge client events; covers model 2ah.

tgl_events(3CPC)
Intel Tiger Lake client events; covers models 8ch and 8dh.

wsm_ep_dp_events(3CPC)
Intel Westmere-EP-DP events; covers model 2ch.

wsm_ep_sp_events(3CPC)
Intel Westmere-EP-SP events; covers model 25h.

wsm_ex_events(3CPC)
Intel Westmere-EX events; covers model 2fh.

AMD Processor Specific Events

The following manual pages provide more detailed information on the
events available for the specific AMD processor models. The covered
processor families are listed in hexadecimal.

amd_f17h_zen1_events(3CPC)
AMD Family 17h Zen 1 processors, including models 00-2fh.
Includes Ryzen, ThreadRipper, and EPYC branded processors.

amd_f17h_zen2_events(3CPC)
AMD Family 17h Zen 2 processors, including models 30-afh.
Includes Ryzen, ThreadRipper, and EPYC branded processors.

amd_f17h_zen3_events(3CPC)
AMD Family 19h Zen 3 processors, including models 00-0fh,
20-2fh, and 40-5fh. Includes Ryzen, ThreadRipper, and EPYC
branded processors.

amd_f19h_zen4_events(3CPC)
AMD Family 19h Zen 4 processors, including models 10-1fh,
60-7fh, and a0-afh. Includes Ryzen and EPYC branded
processors.

amd_f1ah_zen5_events(3CPC)
AMD Family 1ah Zen 5 processors including models 00-1fh,
20-2f, 40-4fh, 60-6fh, and 70-77h. Includes Ryzen and EPYC
branded processors.

Using Attributes

Some processors have advanced performance counter capabilities that are
configured with attributes. The cpc_walk_attrs(3CPC) function can be
used to determine the names of attributes supported by the underlying
processor. The documentation referenced by cpc_cpuref(3CPC) should be
consulted to understand the meaning of a processor's performance
counter attributes.

Performance Counter Context

Each processor on the system possesses its own set of performance
counter registers. For a single process, it is often desirable to
maintain the illusion that the counters are an intrinsic part of that
process (whichever processors it runs on), since this allows the events
to be directly attributed to the process without having to make passive
all other activity on the system.

To achieve this behavior, the library associates performance counter
context with each LWP in the process. The context consists of a small
amount of kernel memory to hold the counter values when the BLWP is not
running, and some simple kernel functions to save and restore those
counter values from and to the hardware registers when the LWP performs
a normal context switch. A process can only observe and manipulate its
own copy of the performance counter control and data registers.

Performance Counters In Other Processes

Though applications can be modified to instrument themselves as
demonstrated above, it is frequently useful to be able to examine the
behavior of an existing application without changing the source code.
A separate library, libpctx, provides a simple set of interfaces that
use the facilities of proc(5) to control a target process, and together
with functions in libcpc, allow truss -like tools to be constructed to
measure the performance counters in other applications. An example of
one such application is cputrack(1).

The functions in libpctx are independent of those in libcpc. These
functions manage a process using an event-loop paradigm -- that is, the
execution of certain system calls by the controlled process cause the
library to stop the controlled process and execute callback functions
in the context of the controlling process. These handlers can perform
various operations on the target process using APIs in libpctx and
libcpc that consume pctx_t handles.