1cpc_buf_create(3CPCC)PU Performance Counters Library Functioncspc_buf_create(3CPC)
2
6 cpc_buf_create, cpc_buf_destroy, cpc_set_sample, cpc_buf_get,
7 cpc_buf_set, cpc_buf_hrtime, cpc_buf_tick, cpc_buf_sub, cpc_buf_add,
8 cpc_buf_copy, cpc_buf_zero - sample and manipulate CPC data
9
11 cc [ flag... ] file... -lcpc [ library... ]
12 #include <libcpc.h>
13 cpc_buf_t *cpc_buf_create(cpc_t *cpc, cpc_set_t *set);
15 int cpc_buf_destroy(cpc_t *cpc, cpc_buf_t *buf);
18 int cpc_set_sample(cpc_t *cpc, cpc_set_t *set, cpc_buf_t *buf);
21 int cpc_buf_get(cpc_t *cpc, cpc_buf_t *buf, int index, uint64_t *val);
24 int cpc_buf_set(cpc_t *cpc, cpc_buf_t *buf, int index, uint64_t val);
27 hrtime_t cpc_buf_hrtime(cpc_t *cpc, cpc_buf_t *buf);
30 uint64_t cpc_buf_tick(cpc_t *cpc, cpc_buf_t *buf);
33 void cpc_buf_sub(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *a, cpc_buf_t *b);
36 void cpc_buf_add(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *a, cpc_buf_t *b);
39 void cpc_buf_copy(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *src);
42 void cpc_buf_zero(cpc_t *cpc, cpc_buf_t *buf);
45
48 Counter data is sampled into CPC buffers, which are represented by the
49 opaque data type cpc_buf_t. A CPC buffer is created with cpc_buf_cre‐
50 ate() to hold the data for a specific CPC set. Once a CPC buffer has
51 been created, it can only be used to store and manipulate the data of
52 the CPC set for which it was created.
53 Once a set has been successfully bound, the counter values are sampled
56 using cpc_set_sample(). The cpc_set_sample() function takes a snapshot
57 of the hardware performance counters counting on behalf of the requests
58 in set and stores the 64-bit virtualized software representations of
59 the counters in the supplied CPC buffer. If a set was bound with
60 cpc_bind_curlwp(3CPC) or cpc_bind_curlwp(3CPC), the set can only be
61 sampled by the LWP that bound it.
62 The kernel maintains 64-bit virtual software counters to hold the
65 counts accumulated for each request in the set, thereby allowing appli‐
66 cations to count past the limits of the underlying physical counter,
67 which can be significantly smaller than 64 bits. The kernel attempts to
68 maintain the full 64-bit counter values even in the face of physical
69 counter overflow on architectures and processors that can automatically
70 detect overflow. If the processor is not capable of overflow detection,
71 the caller must ensure that the counters are sampled often enough to
72 avoid the physical counters wrapping. The events most prone to wrap are
73 those that count processor clock cycles. If such an event is of inter‐
74 est, sampling should occur frequently so that the counter does not wrap
75 between samples.
76 The cpc_buf_get() function retrieves the last sampled value of a par‐
79 ticular request in buf. The index argument specifies which request
80 value in the set to retrieve. The index for each request is returned
81 during set configuration by cpc_set_add_request(3CPC). The 64-bit vir‐
82 tualized software counter value is stored in the location pointed to by
83 the val argument.
84 The cpc_buf_set() function stores a 64-bit value to a specific request
87 in the supplied buffer. This operation can be useful for performing
88 calculations with CPC buffers, but it does not affect the value of the
89 hardware counter (and thus will not affect the next sample).
90 The cpc_buf_hrtime() function returns a high-resolution timestamp indi‐
93 cating exactly when the set was last sampled by the kernel.
94 The cpc_buf_tick() function returns a 64-bit virtualized cycle counter
97 indicating how long the set has been programmed into the counter since
98 it was bound. The units of the values returned by cpc_buf_tick() are
99 CPU clock cycles.
100 The cpc_buf_sub() function calculates the difference between each
103 request in sets a and b, storing the result in the corresponding
104 request within set ds. More specifically, for each request index n,
105 this function performs ds[n] = a[n] - b[n]. Similarly, cpc_buf_add()
106 adds each request in sets a and b and stores the result in the corre‐
107 sponding request within set ds.
108 The cpc_buf_copy() function copies each value from buffer src into buf‐
111 fer ds. Both buffers must have been created from the same cpc_set_t.
112 The cpc_buf_zero() function sets each request's value in the buffer to
115 zero.
116 The cpc_buf_destroy() function frees all resources associated with the
119 CPC buffer.
120
122 Upon successful completion, cpc_buf_create() returns a pointer to a CPC
123 buffer which can be used to hold data for the set argument. Otherwise,
124 this function returns NULL and sets errno to indicate the error.
125 Upon successful completion, cpc_set_sample(), cpc_buf_get(), and
128 cpc_buf_set() return 0. Otherwise, they return -1 and set errno to
129 indicate the error.
130
132 These functions will fail if:
133 EINVAL For cpc_set_sample(), the set is not bound, the set and/or
135 CPC buffer were not created with the given cpc handle, or the
136 CPC buffer was not created with the supplied set.
137 EAGAIN When using cpc_set_sample() to sample a CPU-bound set, the
140 LWP has been unbound from the processor it is measuring.
141 ENOMEM The library could not allocate enough memory for its internal
144 data structures.
145
148 See attributes(5) for descriptions of the following attributes:
149 ┌─────────────────────────────┬─────────────────────────────┐
154 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
155 ├─────────────────────────────┼─────────────────────────────┤
156 │Interface Stability │Evolving │
157 ├─────────────────────────────┼─────────────────────────────┤
158 │MT-Level │Safe │
159 └─────────────────────────────┴─────────────────────────────┘
160
162 cpc_bind_curlwp(3CPC), cpc_set_add_request(3CPC), libcpc(3LIB),
163 attributes(5)
164
166 Often the overhead of performing a system call can be too disruptive to
167 the events being measured. Once a cpc_bind_curlwp(3CPC) call has been
168 issued, it is possible to access directly the performance hardware reg‐
169 isters from within the application. If the performance counter context
170 is active, the counters will count on behalf of the current LWP.
171 Not all processors support this type of access. On processors where
174 direct access is not possible, cpc_set_sample() must be used to read
175 the counters.
176 SPARC
178 rd %pic, %rN ! All UltraSPARC
179 wr %rN, %pic ! (All UltraSPARC, but see text)
180 x86
184 rdpmc ! Pentium II, III, and 4 only
185 If the counter context is not active or has been invalidated, the %pic
190 register (SPARC), and the rdpmc instruction (Pentium) becomes unavail‐
191 able.
192 Pentium II and III processors support the non-privileged rdpmc instruc‐
195 tion that requires that the counter of interest be specified in %ecx
196 and return a 40-bit value in the %edx:%eax register pair. There is no
197 non-privileged access mechanism for Pentium I processors.
198SunOS 5.11 30 Jan 2004 cpc_buf_create(3CPC)