cpc_walk_events_all(3cpc)

1cpc_npic(3CPC)    CPU Performance Counters Library Functions    cpc_npic(3CPC)
2
3
4

NAME

6       cpc_npic,   cpc_caps,   cpc_cciname,  cpc_cpuref,  cpc_walk_events_all,
7       cpc_walk_generic_events_all,                       cpc_walk_events_pic,
8       cpc_walk_generic_events_pic, cpc_walk_attrs - determine CPU performance
9       counter configuration
10

SYNOPSIS

12       cc [ flag... ] file... -lcpc [ library... ]
13       #include <libcpc.h>
14
15       uint_t cpc_npic(cpc_t *cpc);
16
17
18       uint_t cpc_caps(cpc_t *cpc);
19
20
21       const char *cpc_cciname(cpc_t *cpc);
22
23
24       const char *cpc_cpuref(cpc_t *cpc);
25
26
27       void cpc_walk_events_all(cpc_t *cpc, void *arg,
28            void (*action)(void *arg, const char *event));
29
30
31       void cpc_walk_generic_events_all(cpc_t *cpc, void *arg,
32            void (*action)(void *arg, const char *event));
33
34
35       void cpc_walk_events_pic(cpc_t *cpc, uint_t picno, void *arg,
36            void (*action)(void *arg, uint_t picno, const char *event));
37
38
39       void cpc_walk_generic_events_pic(cpc_t *cpc, uint_t picno,
40            void *arg, void (*action)(void *arg, uint_t picno,
41            const char *event));
42
43
44       void cpc_walk_attrs(cpc_t *cpc, void *arg,
45            void (*action)(void *arg, const char *attr));
46
47

DESCRIPTION

49       The cpc_cciname() function returns a printable description of the  pro‐
50       cessor  performance  counter interfaces, for example, the string Ultra‐
51       SPARC III+ & IV. This name should not be assumed to be the same as  the
52       name the manufacturer might otherwise ascribe to the processor. It sim‐
53       ply names the performance counter interfaces as understood by the  sys‐
54       tem,  and  thus names the set of performance counter events that can be
55       described by that interface.
56
57
58       The cpc_cpuref() function returns a string that describes  a  reference
59       work  that  should  be  consulted  to (allow a human to) understand the
60       semantics of the performance counter events that are known to the  sys‐
61       tem.  The string returned might be substantially longer than 80 charac‐
62       ters. Callers printing to a terminal might want to insert  line  breaks
63       as appropriate.
64
65
66       The  cpc_npic()  function  returns  the  number of performance counters
67       accessible on the processor.
68
69
70       The cpc_caps() function returns a bitmap containing the bitwise  inclu‐
71       sive-OR  of  zero  or  more flags that describe the capabilities of the
72       processor. If CPC_CAP_OVERFLOW_INTERRUPT is present, the processor  can
73       generate an interrupt when a hardware performance counter overflows. If
74       CPC_CAP_OVERFLOW_PRECISE is present, the processor can  determine  pre‐
75       cisely  which counter overflowed, thereby affecting the behavior of the
76       overflow notification mechanism described in cpc_bind_curlwp(3CPC).
77
78
79       The system maintains a list of performance counter events supported  by
80       the  underlying processor. Some processors are able to count all events
81       on all hardware  counters,  while  other  processors  restrict  certain
82       events  to  be  counted  only on specific hardware counters. The system
83       also maintains a list of processor-specific attributes that can be used
84       for  advanced  configuration of the performance counter hardware. These
85       functions allow applications to determine what  events  and  attributes
86       are  supported  by the underlying processor. The reference work pointed
87       to by cpc_cpuref() should be consulted to understand  the  reasons  for
88       and use of the attributes.
89
90
91       The  cpc_walk_events_all()  function  calls the action function on each
92       element of a global event list. The action function is called with each
93       event  supported by the processor, regardless of which counter is capa‐
94       ble of counting it. The action function is called only  once  for  each
95       event, even if that event can be counted on more than one counter.
96
97
98       The  cpc_walk_events_pic() function calls the action function with each
99       event supported by the counter indicated by the picno  argument,  where
100       picno ranges from 0 to the value returned by cpc_npic().
101
102
103       The system maintains a list of platform independent performance counter
104       events known as generic events (see generic_events(3CPC)).
105
106
107       The cpc_walk_generic_events_all() function calls the action function on
108       each  generic  event available on the processor. The action function is
109       called for each generic event, regardless of which counter  is  capable
110       of counting it. The action function is called only once for each event,
111       even if that event can be counted on more than one counter.
112
113
114       The cpc_walk_generic_events_pic() function calls  the  action  function
115       with each generic event supported by the counter indicated by the picno
116       argument,  where  picno  ranges  from  0  to  the  value  returned   by
117       cpc_npic().
118
119
120       The  system  maintains  a list of attributes that can be used to enable
121       advanced features of the performance counters on the underlying proces‐
122       sor.  The  cpc_walk_attrs() function calls the action function for each
123       supported attribute name. See the reference  material  as  returned  by
124       cpc_cpuref(3CPC) for the semantics use of attributes.
125

RETURN VALUES

127       The  cpc_cciname()  function  always returns a printable description of
128       the processor performance counter interfaces.
129
130
131       The cpc_cpuref() function always returns a string that describes a ref‐
132       erence work.
133
134
135       The  cpc_npic() function always returns the number of performance coun‐
136       ters accessible on the processor.
137
138
139       The cpc_caps() function always returns a bitmap containing the  bitwise
140       inclusive-OR  of  zero  or more flags that describe the capabilities of
141       the processor.
142
143
144       If the user-defined function specified by action  is  not  called,  the
145       cpc_walk_events_all(),     cpc_walk_events_pic(),     cpc_walk_attrs(),
146       cpc_walk_generic_events_pic(), and cpc_walk_generic_events_pic()  func‐
147       tions set errno to indicate the error.
148

ERRORS

150       The   cpc_walk_events_all(),  cpc_walk_events_pic(),  cpc_walk_attrs(),
151       cpc_walk_generic_events_pic(), and cpc_walk_generic_events_pic()  func‐
152       tions will fail if:
153
154       ENOMEM    There is not enough memory available.
155
156

ATTRIBUTES

158       See attributes(5) for descriptions of the following attributes:
159
160
161
162
163       ┌─────────────────────────────┬─────────────────────────────┐
164       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
165       ├─────────────────────────────┼─────────────────────────────┤
166       │Interface Stability          │Committed                    │
167       ├─────────────────────────────┼─────────────────────────────┤
168       │MT-Level                     │Safe                         │
169       └─────────────────────────────┴─────────────────────────────┘
170

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

ATTRIBUTES

SEE ALSO