1cpc(3CPC) CPU Performance Counters Library Functions cpc(3CPC)
2
6 cpc - hardware performance counters
7
9 Modern microprocessors contain hardware performance counters that allow
10 the measurement of many different hardware events related to CPU behav‐
11 ior, including instruction and data cache misses as well as various
12 internal states of the processor. The counters can be configured to
13 count user events, system events, or both. Data from the performance
14 counters can be used to analyze and tune the behavior of software on a
15 particular type of processor.
16 Most processors are able to generate an interrupt on counter overflow,
19 allowing the counters to be used for various forms of profiling.
20 This manual page describes a set of APIs that allow Solaris applica‐
23 tions to use these counters. Applications can measure their own behav‐
24 ior, the behavior of other applications, or the behavior of the whole
25 system.
26 Shared Counters or Private Counters
28 There are two principal models for using these performance counters.
29 Some users of these statistics want to observe system-wide behavior.
30 Other users want to view the performance counters as part of the regis‐
31 ter set exported by each LWP. On a machine performing more than one
32 activity, these two models are in conflict because the counters repre‐
33 sent a critical hardware resource that cannot simultaneously be both
34 shared and private.
35 Configuration Interfaces
37 The following configuration interfaces are provided:
38 cpc_open(3CPC) Check the version the application was compiled
40 with against the version of the library.
41 cpc_cciname(3CPC) Return a printable string to describe the perfor‐
44 mance counters of the processor.
45 cpc_npic(3CPC) Return the number of performance counters on the
48 processor.
49 cpc_cpuref(3CPC) Return a reference to documentation that should be
52 consulted to understand how to use and interpret
53 data from the performance counters.
54 Performance Counter Access
57 Performance counters can be present in hardware but not acccessible
58 because either some of the necessary system software components are not
59 available or not installed, or the counters might be in use by other
60 processes. The cpc_open(3CPC) function determines the accessibility of
61 the counters and must be invoked before any attempt to program the
62 counters.
63 Finding Events
65 Each different type of processor has its own set of events available
66 for measurement. The cpc_walk_events_all(3CPC) and
67 cpc_walk_events_pic(3CPC) functions allow an application to determine
68 the names of events supported by the underlying processor. A collection
69 of generic, platform independent event names are defined by
70 generic_events(3CPC). Each generic event maps to an underlying hardware
71 event specific to the underlying processor and any optional attributes.
72 The cpc_walk_generic_events_all(3CPC) and
73 cpc_walk_generic_events_pic(3CPC) functions allow an application to
74 determine the generic events supported on the underlying platform.
75 Using Attributes
77 Some processors have advanced performance counter capabilities that are
78 configured with attributes. The cpc_walk_attrs(3CPC) function can be
79 used to determine the names of attributes supported by the underlying
80 processor. The documentation referenced by cpc_cpuref(3CPC) should be
81 consulted to understand the meaning of a processor's performance
82 counter attributes.
83 Performance Counter Context
85 Each processor on the system possesses its own set of performance
86 counter registers. For a single process, it is often desirable to main‐
87 tain the illusion that the counters are an intrinsic part of that
88 process (whichever processors it runs on), since this allows the events
89 to be directly attributed to the process without having to make passive
90 all other activity on the system.
91 To achieve this behavior, the library associates performance counter
94 context with each LWP in the process. The context consists of a small
95 amount of kernel memory to hold the counter values when the LWP is not
96 running, and some simple kernel functions to save and restore those
97 counter values from and to the hardware registers when the LWP performs
98 a normal context switch. A process can only observe and manipulate its
99 own copy of the performance counter control and data registers.
100 Performance Counters In Other Processes
102 Though applications can be modified to instrument themselves as demon‐
103 strated above, it is frequently useful to be able to examine the behav‐
104 ior of an existing application without changing the source code. A sep‐
105 arate library, libpctx, provides a simple set of interfaces that use
106 the facilities of proc(4) to control a target process, and together
107 with functions in libcpc, allow truss-like tools to be constructed to
108 measure the performance counters in other applications. An example of
109 one such application is cputrack(1).
110 The functions in libpctx are independent of those in libcpc. These
113 functions manage a process using an event-loop paradigm — that is, the
114 execution of certain system calls by the controlled process cause the
115 library to stop the controlled process and execute callback functions
116 in the context of the controlling process. These handlers can perform
117 various operations on the target process using APIs in libpctx and
118 libcpc that consume pctx_t handles.
119
121 cputrack(1), cpustat(1M), cpc_bind_curlwp(3CPC), cpc_buf_create(3CPC),
122 cpc_enable(3CPC), cpc_npic(3CPC), cpc_open(3CPC), cpc_set_create(3CPC),
123 cpc_seterrhndlr(3CPC), generic_events(3CPC), libcpc(3LIB), pctx_cap‐
124 ture(3CPC), pctx_set_events(3CPC), proc(4)
125SunOS 5.11 8 Oct 2008 cpc(3CPC)