| blob | 352e789e19afacc2790d2b29338f3018ba3e84ae |
1 .\" $NetBSD: pmc_control.2,v 1.7 2005/10/31 11:34:16 wiz Exp $
2 .\"
3 .\" Copyright (c) 2002 Wasabi Systems, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" Written by Allen Briggs for Wasabi Systems, Inc.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed for the NetBSD Project by
19 .\" Wasabi Systems, Inc.
20 .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
21 .\" or promote products derived from this software without specific prior
22 .\" written permission.
23 .\"
24 .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
27 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC
28 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 .\" POSSIBILITY OF SUCH DAMAGE.
35 .\"
36 .Dd October 27, 2005
37 .Dt PMC_CONTROL 2
38 .Os
39 .Sh NAME
40 .Nm pmc_control ,
41 .Nm pmc_get_info
42 .Nd Hardware Performance Monitoring Interface
43 .Sh LIBRARY
44 .Lb libc
45 .Sh SYNOPSIS
46 .In sys/pmc.h
47 .Ft int
48 .Fn pmc_control "int ctr" "int op" "void *argp"
49 .Ft int
50 .Fn pmc_get_info "int ctr" "int op" "void *argp"
51 .Sh DESCRIPTION
52 .Fn pmc_get_info
53 returns the number of counters in the system or information on a specified
54 counter
55 .Fa ctr .
56 The possible values for
57 .Fa op
58 are:
59 .Bl -tag -width width
60 .It Dv PMC_INFO_NCOUNTERS
61 When querying the number of counters in the system,
62 .Fa ctr
63 is ignored and
64 .Fa argp
65 is of type
66 .Ft int * .
67 Upon return, the integer pointed to by
68 .Fa argp
69 will contain the number of counters that are available in the system.
70 .It Dv PMC_INFO_CPUCTR_TYPE
71 When querying the type of a counter in the system,
72 .Fa ctr
73 refers to the counter being queried, and
74 .Fa argp
75 is of type
76 .Ft int * .
77 Upon return, the integer pointed to by
78 .Fa argp
79 will contain the implementation-dependent type of the specified counter.
80 .Pp
81 If
82 .Fa ctr
83 is \-1, the integer pointed to by
84 .Fa argp
85 will contain the machine-dependent type
86 describing the CPU or counter configuration.
87 .It Dv PMC_INFO_COUNTER_VALUE
88 When querying the value of a counter in the system,
89 .Fa ctr
90 refers to the counter being queried, and
91 .Fa argp
92 is of type
93 .Ft uint64_t * .
94 Upon return, the 64-bit integer pointed to by
95 .Fa argp
96 will contain the value of the specified counter.
97 .It Dv PMC_INFO_ACCUMULATED_COUNTER_VALUE
98 When querying the value of a counter in the system,
99 .Fa ctr
100 refers to the counter being queried, and
101 .Fa argp
102 is of type
103 .Ft uint64_t * .
104 Upon return, the 64-bit integer pointed to by
105 .Fa argp
106 will contain the sum of the accumulated values of specified counter in
107 all exited subprocesses of the current process.
108 .El
109 .Pp
110 .Fn pmc_control
111 manipulates the specified counter
112 .Fa ctr
113 in one of several fashions.
114 The
115 .Fa op
116 parameter determines the action taken by the kernel and also the interpretation of the
117 .Fa argp
118 parameter.
119 The possible values for
120 .Fa op
121 are:
122 .Bl -tag -width width
123 .It Dv PMC_OP_START
124 Starts the specified
125 .Fa ctr
126 running.
127 It must be preceded by a call with
128 .Dv PMC_OP_CONFIGURE .
129 .Fa argp
130 is ignored in this case and may be
131 .Dv NULL .
132 .It Dv PMC_OP_STOP
133 Stops the specified
134 .Fa ctr
135 from running.
136 .Fa argp
137 is ignored in this case and may be
138 .Dv NULL .
139 .It Dv PMC_OP_CONFIGURE
140 Configures the specified
141 .Fa ctr
142 prior to running.
143 .Fa argp
144 is a pointer to a
145 .Ft struct pmc_counter_cfg .
146 .Bd -literal
147 struct pmc_counter_cfg {
148 pmc_evid_t event_id;
149 pmc_ctr_t reset_value;
150 uint32_t flags;
151 };
152 .Ed
153 .Bl -tag -width width
154 .It Dv event_id
155 is the event ID to be counted.
156 .It Dv reset_value
157 is a value to which the counter should be reset on overflow (if supported
158 by the implementation).
159 This is most useful when profiling (see
160 .Dv PMC_OP_PROFSTART ,
161 below).
162 This value is defined to be the number of counter ticks before
163 the next overflow.
164 So, to get a profiling tick on every hundredth data cache miss, set the
165 .Dv event_id
166 to the proper value for
167 .Dq dcache-miss
168 and set
169 .Dv reset_value
170 to 100.
171 .It Dv flags
172 Currently unused.
173 .El
174 .It Dv PMC_OP_PROFSTART
175 Configures the specified
176 .Fa ctr
177 for use in profiling.
178 .Fa argp
179 is a pointer to a
180 .Ft struct pmc_counter_cfg
181 as in
182 .Dv PMC_OP_CONFIGURE ,
183 above.
184 This request allocates a kernel counter, which will fail if any
185 process is using the requested counter.
186 Not all implementations or counters may support this option.
187 .It Dv PMC_OP_PROFSTOP
188 Stops the specified
189 .Fa ctr
190 from being used for profiling.
191 .Fa argp
192 is ignored in this case and may be
193 .Dv NULL .
194 .El
195 .Sh RETURN VALUES
196 A return value of 0 indicates that the call succeeded.
197 Otherwise, \-1 is returned and the global variable
198 .Va errno
199 is set to indicate the error.
200 .Sh ERRORS
201 Among the possible error codes from
202 .Fn pmc_control
203 and
204 .Fn pmc_get_info
205 are
206 .Bl -tag -width Er
207 .It Bq Er EFAULT
208 The address specified for the
209 .Fa argp
210 is invalid.
211 .It Bq Er ENXIO
212 Specified counter is not yet configured.
213 .It Bq Er EINPROGRESS
214 .Dv PMC_OP_START
215 was passed for a counter that is already running.
216 .It Bq Er EINVAL
217 Specified counter was invalid.
218 .It Bq Er EBUSY
219 If the requested counter is already in use--either by the current process
220 or by the kernel.
221 .It Bq Er ENODEV
222 If and only if the specified counter event is not valid for the specified
223 counter when configuring a counter or starting profiling.
224 .It Bq Er ENOMEM
225 If the kernel is unable to allocate memory.
226 .El
227 .Sh SEE ALSO
228 .Xr pmc 1 ,
229 .Xr pmc 9
230 .Sh HISTORY
231 The
232 .Fn pmc_control
233 and
234 .Fn pmc_get_info
235 system calls appeared in
236 .Nx 2.0 .