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 53returns the number of counters in the system or information on a specified 54counter 55.Fa ctr . 56The possible values for 57.Fa op 58are: 59.Bl -tag -width width 60.It Dv PMC_INFO_NCOUNTERS 61When querying the number of counters in the system, 62.Fa ctr 63is ignored and 64.Fa argp 65is of type 66.Ft int * . 67Upon return, the integer pointed to by 68.Fa argp 69will contain the number of counters that are available in the system. 70.It Dv PMC_INFO_CPUCTR_TYPE 71When querying the type of a counter in the system, 72.Fa ctr 73refers to the counter being queried, and 74.Fa argp 75is of type 76.Ft int * . 77Upon return, the integer pointed to by 78.Fa argp 79will contain the implementation-dependent type of the specified counter. 80.Pp 81If 82.Fa ctr 83is \-1, the integer pointed to by 84.Fa argp 85will contain the machine-dependent type 86describing the CPU or counter configuration. 87.It Dv PMC_INFO_COUNTER_VALUE 88When querying the value of a counter in the system, 89.Fa ctr 90refers to the counter being queried, and 91.Fa argp 92is of type 93.Ft uint64_t * . 94Upon return, the 64-bit integer pointed to by 95.Fa argp 96will contain the value of the specified counter. 97.It Dv PMC_INFO_ACCUMULATED_COUNTER_VALUE 98When querying the value of a counter in the system, 99.Fa ctr 100refers to the counter being queried, and 101.Fa argp 102is of type 103.Ft uint64_t * . 104Upon return, the 64-bit integer pointed to by 105.Fa argp 106will contain the sum of the accumulated values of specified counter in 107all exited subprocesses of the current process. 108.El 109.Pp 110.Fn pmc_control 111manipulates the specified counter 112.Fa ctr 113in one of several fashions. 114The 115.Fa op 116parameter determines the action taken by the kernel and also the interpretation of the 117.Fa argp 118parameter. 119The possible values for 120.Fa op 121are: 122.Bl -tag -width width 123.It Dv PMC_OP_START 124Starts the specified 125.Fa ctr 126running. 127It must be preceded by a call with 128.Dv PMC_OP_CONFIGURE . 129.Fa argp 130is ignored in this case and may be 131.Dv NULL . 132.It Dv PMC_OP_STOP 133Stops the specified 134.Fa ctr 135from running. 136.Fa argp 137is ignored in this case and may be 138.Dv NULL . 139.It Dv PMC_OP_CONFIGURE 140Configures the specified 141.Fa ctr 142prior to running. 143.Fa argp 144is 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 155is the event ID to be counted. 156.It Dv reset_value 157is a value to which the counter should be reset on overflow (if supported 158by the implementation). 159This is most useful when profiling (see 160.Dv PMC_OP_PROFSTART , 161below). 162This value is defined to be the number of counter ticks before 163the next overflow. 164So, to get a profiling tick on every hundredth data cache miss, set the 165.Dv event_id 166to the proper value for 167.Dq dcache-miss 168and set 169.Dv reset_value 170to 100. 171.It Dv flags 172Currently unused. 173.El 174.It Dv PMC_OP_PROFSTART 175Configures the specified 176.Fa ctr 177for use in profiling. 178.Fa argp 179is a pointer to a 180.Ft struct pmc_counter_cfg 181as in 182.Dv PMC_OP_CONFIGURE , 183above. 184This request allocates a kernel counter, which will fail if any 185process is using the requested counter. 186Not all implementations or counters may support this option. 187.It Dv PMC_OP_PROFSTOP 188Stops the specified 189.Fa ctr 190from being used for profiling. 191.Fa argp 192is ignored in this case and may be 193.Dv NULL . 194.El 195.Sh RETURN VALUES 196A return value of 0 indicates that the call succeeded. 197Otherwise, \-1 is returned and the global variable 198.Va errno 199is set to indicate the error. 200.Sh ERRORS 201Among the possible error codes from 202.Fn pmc_control 203and 204.Fn pmc_get_info 205are 206.Bl -tag -width Er 207.It Bq Er EFAULT 208The address specified for the 209.Fa argp 210is invalid. 211.It Bq Er ENXIO 212Specified counter is not yet configured. 213.It Bq Er EINPROGRESS 214.Dv PMC_OP_START 215was passed for a counter that is already running. 216.It Bq Er EINVAL 217Specified counter was invalid. 218.It Bq Er EBUSY 219If the requested counter is already in use--either by the current process 220or by the kernel. 221.It Bq Er ENODEV 222If and only if the specified counter event is not valid for the specified 223counter when configuring a counter or starting profiling. 224.It Bq Er ENOMEM 225If the kernel is unable to allocate memory. 226.El 227.Sh SEE ALSO 228.Xr pmc 1 , 229.Xr pmc 9 230.Sh HISTORY 231The 232.Fn pmc_control 233and 234.Fn pmc_get_info 235system calls appeared in 236.Nx 2.0 . 237