1cpc_buf_create(3CPCC)PU Performance Counters Library Functioncspc_buf_create(3CPC)
2
3
4

NAME

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

SYNOPSIS

11       cc [ flag... ] file... -lcpc [ library... ]
12       #include <libcpc.h>
13
14       cpc_buf_t *cpc_buf_create(cpc_t *cpc, cpc_set_t *set);
15
16
17       int cpc_buf_destroy(cpc_t *cpc, cpc_buf_t *buf);
18
19
20       int cpc_set_sample(cpc_t *cpc, cpc_set_t *set, cpc_buf_t *buf);
21
22
23       int cpc_buf_get(cpc_t *cpc, cpc_buf_t *buf, int index, uint64_t *val);
24
25
26       int cpc_buf_set(cpc_t *cpc, cpc_buf_t *buf, int index, uint64_t val);
27
28
29       hrtime_t cpc_buf_hrtime(cpc_t *cpc, cpc_buf_t *buf);
30
31
32       uint64_t cpc_buf_tick(cpc_t *cpc, cpc_buf_t *buf);
33
34
35       void cpc_buf_sub(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *a, cpc_buf_t *b);
36
37
38       void cpc_buf_add(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *a, cpc_buf_t *b);
39
40
41       void cpc_buf_copy(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *src);
42
43
44       void cpc_buf_zero(cpc_t *cpc, cpc_buf_t *buf);
45
46

DESCRIPTION

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
54
55       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
63
64       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
77
78       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
85
86       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
91
92       The cpc_buf_hrtime() function returns a high-resolution timestamp indi‐
93       cating exactly when the set was last sampled by the kernel.
94
95
96       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
101
102       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
109
110       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
113
114       The cpc_buf_zero() function sets each request's value in the buffer  to
115       zero.
116
117
118       The  cpc_buf_destroy() function frees all resources associated with the
119       CPC buffer.
120

RETURN VALUES

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
126
127       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

ERRORS

132       These functions will fail if:
133
134       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
138
139       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
142
143       ENOMEM    The library could not allocate enough memory for its internal
144                 data structures.
145
146

ATTRIBUTES

148       See attributes(5) for descriptions of the following attributes:
149
150
151
152
153       ┌─────────────────────────────┬─────────────────────────────┐
154       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
155       ├─────────────────────────────┼─────────────────────────────┤
156       │Interface Stability          │Evolving                     │
157       ├─────────────────────────────┼─────────────────────────────┤
158       │MT-Level                     │Safe                         │
159       └─────────────────────────────┴─────────────────────────────┘
160

SEE ALSO

162       cpc_bind_curlwp(3CPC),     cpc_set_add_request(3CPC),     libcpc(3LIB),
163       attributes(5)
164

NOTES

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
172
173       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
177       SPARC
178                  rd %pic, %rN        ! All UltraSPARC
179                  wr %rN, %pic        ! (All UltraSPARC, but see text)
180
181
182
183       x86
184                  rdpmc               ! Pentium II, III, and 4 only
185
186
187
188
189       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
193
194       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.
198
199
200
201SunOS 5.11                        30 Jan 2004             cpc_buf_create(3CPC)
Impressum