| blob | 89592e12b4fdea8c4279f9c4841d0dfcc5cd03b3 |
1 .\" $NetBSD: pmc.9,v 1.8 2006/01/29 02:40:40 rpaulo Exp $
2 .\"
3 .\" Copyright (c) 2002, 2005 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 December 20, 2005
37 .Dt PMC 9
38 .Os
39 .Sh NAME
40 .Nm pmc ,
41 .Nm pmc_get_num_counters ,
42 .Nm pmc_get_counter_type ,
43 .Nm pmc_save_context ,
44 .Nm pmc_restore_context ,
45 .Nm pmc_enable_counter ,
46 .Nm pmc_disable_counter ,
47 .Nm pmc_counter_isrunning ,
48 .Nm pmc_counter_isconfigured ,
49 .Nm pmc_configure_counter ,
50 .Nm pmc_get_counter_value ,
51 .Nm pmc_accumulate ,
52 .Nm pmc_alloc_kernel_counter ,
53 .Nm pmc_free_kernel_counter ,
54 .Nm pmc_start_profiling ,
55 .Nm pmc_stop_profiling ,
56 .Nm PMC_ENABLED
57 .Nd Hardware Performance Monitoring Interface
58 .Sh SYNOPSIS
59 .In sys/pmc.h
60 .Ft int
61 .Fn pmc_get_num_counters "void"
62 .Ft int
63 .Fn pmc_get_counter_type "int ctr"
64 .Ft void
65 .Fn pmc_save_context "struct lwp *l"
66 .Ft void
67 .Fn pmc_restore_context "struct lwp *l"
68 .Ft int
69 .Fn pmc_enable_counter "struct lwp *l" "int ctr"
70 .Ft int
71 .Fn pmc_disable_counter "struct lwp *l" "int ctr"
72 .Ft int
73 .Fn pmc_counter_isrunning "struct lwp *l" "int ctr"
74 .Ft int
75 .Fn pmc_counter_isconfigured "struct lwp *l" "int ctr"
76 .Ft int
77 .Fn pmc_configure_counter "struct lwp *l" "int ctr" \
78 "struct pmc_counter_cfg *cfg"
79 .Ft int
80 .Fn pmc_get_counter_value "struct lwp *l" "int ctr" "int flags" \
81 "uint64_t *pval"
82 .Ft int
83 .Fn pmc_accumulate "struct lwp *l_parent" "struct lwp *l_exiting"
84 .Ft int
85 .Fn pmc_alloc_kernel_counter "int ctr" "struct pmc_counter_cfg *cfg"
86 .Ft int
87 .Fn pmc_free_kernel_counter "int ctr"
88 .Ft int
89 .Fn pmc_start_profiling "int ctr" "struct pmc_counter_cfg *cfg"
90 .Ft int
91 .Fn pmc_stop_profiling "int ctr"
92 .Ft int
93 .Fn PMC_ENABLED "struct lwp *l"
94 .Sh DESCRIPTION
95 Provides a machine-independent interface to the hardware performance counters
96 which are available on several CPU families.
97 The capabilities of these counters vary from CPU to CPU, but they
98 basically count hardware events such as data cache hits or misses,
99 branches taken, branched mispredicted, and so forth.
100 Some can interrupt the processor when a certain threshold has been reached.
101 Some can count events in user space and kernel space independently.
102 .Pp
103 The
104 .Nm
105 interface is intended to allow monitoring from within the kernel as well
106 as monitoring of userland applications.
107 If the hardware can interrupt the CPU in a specific implementation,
108 then it may also be used as a profiling source instead of the clock.
109 .Sh NOTES
110 All function calls in this interface may be defined as
111 .Xr cpp 1
112 macros.
113 If any function is not implemented as a macro, its prototype must be
114 defined by the port-specific header
115 .Aq Pa machine/pmc.h .
116 .Pp
117 Counters are numbered from 0 to
118 .Dv N\-1
119 where
120 .Dv N
121 is the number of counters available on the system
122 (see
123 .Fn pmc_get_num_counters
124 below).
125 .Pp
126 Upon a process fork, implementations must
127 .Bl -bullet
128 .It
129 Zero performance counters for the new process, and
130 .It
131 Inherit any enabled performance counters.
132 .El
133 .Sh DATA TYPES
134 Each implementation must specify two new types:
135 .Bl -tag -width pmc_evid_t
136 .It Fa pmc_evid_t
137 An integer type which can contain the event IDs for a given processor.
138 .It Fa pmc_ctr_t
139 An integer type defining the value which may be contained in a given
140 counter register.
141 .El
142 .Pp
143 Counters are configured with the
144 .Fa struct pmc_counter_cfg .
145 This structure is defined as
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 .Pp
154 .Fa flags
155 are currently unused.
156 .Sh FUNCTIONS
157 .Bl -tag -width width
158 .It Fn pmc_get_num_counters "void"
159 Returns the number of counters present on the current system.
160 Valid values for
161 .Fa ctr
162 in the interface entry points below are from zero to one less than the
163 return value from this function.
164 .It Fn pmc_get_counter_type "int ctr"
165 Returns an implementation-dependent type describing the specified counter.
166 If
167 .Fa ctr
168 is specified as \-1, returns a machine-dependent type describing the
169 CPU or counter configuration.
170 For example, on an ia32 architecture, it may distinguish between
171 586-, 686-, and K7-style counters.
172 .It Fn pmc_save_context "struct lwp *l"
173 Saves the PMC context for the current process.
174 This is called just before
175 .Xr cpu_switch 9 .
176 If there is kernel PMC state, it must be maintained across this call.
177 .It Fn pmc_restore_context "struct lwp *l"
178 Restores the PMC context for the current process.
179 This is called just after
180 .Xr cpu_switch 9
181 returns.
182 If there is kernel PMC state, it must be maintained across this call.
183 .It Fn pmc_enable_counter "struct lwp *l" "int ctr"
184 Enables counter
185 .Fa ctr
186 for the specified process.
187 The counter should have already been configured with a call to
188 .Fn pmc_configure_counter .
189 This starts the counter running if it is not already started and enables
190 any interrupts, as appropriate.
191 .It Fn pmc_disable_counter "struct lwp *l" "int ctr"
192 Disables counter
193 .Fa ctr
194 for the specified process.
195 This stops the counter from running, and disables any interrupts,
196 as appropriate.
197 .It Fn pmc_counter_isrunning "struct lwp *l" "int ctr"
198 Returns non-zero if the specified counter in the specified process is
199 running or if the counter is running in the kernel.
200 .It Fn pmc_counter_isconfigured "struct lwp *l" "int ctr"
201 Returns non-zero if the specified counter in the specified process is
202 configured or if the counter is in use by the kernel.
203 .It Fn pmc_configure_counter "struct lwp *l" "int ctr" \
204 "struct pmc_counter_cfg *cfg"
205 Configures counter
206 .Fa ctr
207 according to the configuration information stored in
208 .Fa cfg .
209 .It Fn pmc_get_counter_value "struct lwp *l" "int ctr" "int flags" \
210 "uint64_t *pval"
211 Returns the value of counter
212 .Fa ctr
213 in the space pointed to by
214 .Fa pval .
215 The only recognized flag is
216 .Fa PMC_VALUE_FLAGS_CHILDREN
217 which specifies that the returned counts should be accumulated values
218 for any exited child processes.
219 .It Fn pmc_accumulate "struct lwp *l_parent" "struct lwp *l_exiting"
220 Accumulates any counter data from the exiting process
221 .Fa p_exiting
222 into the counters for the parent process
223 .Fa p_parent .
224 .It Fn pmc_alloc_kernel_counter "int ctr" "struct pmc_counter_cfg *cfg"
225 Allocates counter
226 .Fa ctr
227 for use by the kernel and configures it with
228 .Fa cfg .
229 .It Fn pmc_free_kernel_counter "int ctr"
230 Returns counter
231 .Fa ctr
232 to the available pool of counters that may be used by processes.
233 .It Fn pmc_start_profiling "int ctr" "struct pmc_counter_cfg *cfg"
234 Allocates counter
235 .Fa ctr
236 for use by the kernel for profiling and configures it with
237 .Fa cfg .
238 .It Fn pmc_stop_profiling "int ctr"
239 Stops profiling with counter
240 .Fa ctr .
241 .It Fn PMC_ENABLED "struct lwp *l"
242 Returns non-zero if the given process or the kernel is using the PMC at all.
243 .El
244 .Sh SEE ALSO
245 .Xr pmc 1 ,
246 .Xr pmc_control 2 ,
247 .Xr pmc_get_info 2
248 .Sh HISTORY
249 The
250 .Nm
251 interface appeared in
252 .Nx 2.0 .
253 .Sh AUTHORS
254 The
255 .Nm
256 interface was designed and implemented by Allen Briggs for Wasabi Systems, Inc.
257 Additional input on the
258 .Nm
259 design was provided by Jason R. Thorpe.