1cpc_set_create(3CPCC)PU Performance Counters Library Functioncspc_set_create(3CPC)
2
6 cpc_set_create, cpc_set_destroy, cpc_set_add_request, cpc_walk_requests
7 - manage sets of counter requests
8
10 cc [ flag... ] file... -lcpc [ library... ]
11 #include <libcpc.h>
12 cpc_set_t *cpc_set_create(cpc_t *cpc);
14 int cpc_set_destroy(cpc_t *cpc, cpc_set_t *set);
17 int cpc_set_add_request(cpc_t *cpc, cpc_set_t *set,
20 const char *event, uint64_t preset, uint_t flags,
21 uint_t nattrs, const cpc_attr_t *attrs);
22 void cpc_walk_requests(cpc_t *cpc, cpc_set_t *set, void *arg,
25 void (*action)(void *arg, int index, const char *event,
26 uint64_t preset, uint_t flags, int nattrs,
27 const cpc_attr_t *attrs));
28
31 The cpc_set_create() function returns an initialized and empty CPC set.
32 A CPC set contains some number of requests, where a request represents
33 a specific configuration of a hardware performance instrumentation
34 counter present on the processor. The cpc_set_t data structure is
35 opaque and must not be accessed directly by the application.
36 Applications wanting to program one or more performance counters must
39 create an empty set with cpc_set_create() and add requests to the set
40 with cpc_set_add_request(). Once all requests have been added to a set,
41 the set must be bound to the hardware performance counters (see
42 cpc_bind_curlwp(), cpc_bind_pctx(), and cpc_bind_cpu(), all described
43 on cpc_bind_curlwp(3CPC)) before counting events. At bind time, the
44 system attempts to match each request with an available physical
45 counter capable of counting the event specified in the request. If the
46 bind is successful, a 64-bit virtualized counter is created to store
47 the counts accumulated by the hardware counter. These counts are stored
48 and managed in CPC buffers separate from the CPC set whose requests are
49 being counted. See cpc_buf_create(3CPC) and cpc_set_sample(3CPC).
50 The cpc_set_add_request() function specifies a configuration of a hard‐
53 ware counter. The arguments to cpc_set_add_request() are:
54 event A string containing the name of an event supported by
56 the system's processor. The cpc_walk_events_all() and
57 cpc_walk_events_pic() functions (both described on
58 cpc_npic(3CPC)) can be used to query the processor for
59 the names of available events. Certain processors
60 allow the use of raw event codes, in which case a
61 string representation of an event code in a form
62 acceptable to strtol(3C) can be used as the event
63 argument.
64 preset The value with which the system initializes the
67 counter.
68 flags Three flags are defined that modify the behavior of
71 the counter acting on behalf of this request:
72 CPC_COUNT_USER
74 The counter should count events that occur while
76 the processor is in user mode.
77 CPC_COUNT_SYSTEM
80 The counter should count events that occur while
82 the processor is in privileged mode.
83 CPC_OVF_NOTIFY_EMT
86 Request a signal to be sent to the application
88 when the physical counter overflows. A SIGEMT sig‐
89 nal is delivered if the processor is capable of
90 delivering an interrupt when the counter counts
91 past its maximum value. All requests in the set
92 containing the counter that overflowed are stopped
93 until the set is rebound.
94 At least one of CPC_COUNT_USER or CPC_COUNT_SYSTEM
96 must be specified to program the hardware for count‐
97 ing.
98 nattrs, attrs The nattrs argument specifies the number of attributes
101 pointed to by the attrs argument, which is an array of
102 cpc_attr_t structures containing processor-specific
103 attributes that modify the request's configuration.
104 The cpc_walk_attrs() function (see cpc_npic(3CPC)) can
105 be used to query the processor for the list of
106 attributes it accepts. The library makes a private
107 copy of the attrs array, allowing the application to
108 dispose of it immediately after calling
109 cpc_set_add_request().
110 The cpc_walk_requests() function calls the action function on each
114 request that has been added to the set. The arg argument is passed
115 unmodified to the action function with each call.
116
118 Upon successful completion, cpc_set_create() returns a handle to the
119 opaque cpc_set_t data structure. Otherwise, NULL is returned and errno
120 is set to indicate the error.
121 Upon successful completion, Cpc_set_destroy() returns 0. Otherwise, -1
124 is returned and errno is set to indicate the error.
125 Upon successful completion, cpc_set_add_request() returns an integer
128 index used to refer to the data generated by that request during data
129 retrieval. Otherwise, -1 is returned and errno is set to indicate the
130 error.
131
133 These functions will fail if:
134 EINVAL An event, attribute, or flag passed to cpc_set_add_request()
136 was invalid.
137 For cpc_set_destroy() and cpc_set_add_request(), the set
139 parameter was not created with the given cpc_t.
140 ENOMEM There was not enough memory available to the process to cre‐
143 ate the library's data structures.
144
147 See attributes(5) for descriptions of the following attributes:
148 ┌─────────────────────────────┬─────────────────────────────┐
153 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
154 ├─────────────────────────────┼─────────────────────────────┤
155 │Interface Stability │Committed │
156 ├─────────────────────────────┼─────────────────────────────┤
157 │MT-Level │Safe │
158 └─────────────────────────────┴─────────────────────────────┘
159
161 cpc_bind_curlwp(3CPC), cpc_buf_create(3CPC), cpc_npic(3CPC), cpc_seter‐
162 rhndlr(3CPC), libcpc(3LIB), strtol(3C), attributes(5)
163
165 The system automatically determines which particular physical counter
166 to use to count the events specified by each request. Applications can
167 force the system to use a particular counter by specifying the counter
168 number in an attribute named picnum that is passed to
169 cpc_set_add_request(). Counters are numbered from 0 to n - 1, where n
170 is the number of counters in the processor as returned by
171 cpc_npic(3CPC).
172 Some processors, such as UltraSPARC, do not allow the hardware counters
175 to be programmed differently. In this case, all requests in the set
176 must have the same configuration, or an attempt to bind the set will
177 return EINVAL. If a cpc_errhndlr_t has been registered with cpc_seter‐
178 rhndlr(3CPC), the error handler is called with subcode CPC_CONFLICT‐
179 ING_REQS. For example, on UltraSPARC pic0 and pic1 must both program
180 events in the same processor mode (user mode, kernel mode, or both).
181 For example, pic0 cannot be programmed with CPC_COUNT_USER while pic1
182 is programmed with CPC_COUNT_SYSTEM. Refer to the hardware documenta‐
183 tion referenced by cpc_cpuref(3CPC) for details about a particular pro‐
184 cessor's performance instrumentation hardware.
185SunOS 5.11 20 Aug 2007 cpc_set_create(3CPC)