1.\" Copyright (c) 2007-2008 Joseph Koshy. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd September 22, 2008 27.Dt PMC_ALLOCATE 3 28.Os 29.Sh NAME 30.Nm pmc_allocate , 31.Nm pmc_release 32.Nd allocate and free performance monitoring counters 33.Sh LIBRARY 34.Lb libpmc 35.Sh SYNOPSIS 36.In pmc.h 37.Ft int 38.Fo pmc_allocate 39.Fa "const char *eventspecifier" 40.Fa "enum pmc_mode mode" 41.Fa "uint32_t flags" 42.Fa "int cpu" 43.Fa "pmc_id_t *pmcid" 44.Fc 45.Ft int 46.Fn pmc_release "pmc_id_t pmc" 47.Sh DESCRIPTION 48Function 49.Fn pmc_allocate 50allocates a performance monitoring counter that measures the events 51named by argument 52.Fa eventspecifier , 53and writes the allocated handle to the location pointed to by argument 54.Fa pmcid . 55.Pp 56Argument 57.Fa eventspecifier 58comprises an PMC event name followed by an optional comma separated 59list of keywords and qualifiers. 60The allowed syntax for argument 61.Fa eventspecifier 62is processor specific and is listed in section 63.Sx "EVENT SPECIFIERS" 64in the 65.Xr pmc 3 66manual page. 67.Pp 68The desired PMC mode is specified by argument 69.Fa mode . 70Legal values for the 71.Fa mode 72argument are: 73.Bl -tag -width ".Dv PMC_MODE_SS" -compact 74.It Dv PMC_MODE_SC 75Allocate a system-scope counting PMC. 76.It Dv PMC_MODE_SS 77Allocate a system-scope sampling PMC. 78.It Dv PMC_MODE_TC 79Allocate a process-scope counting PMC. 80.It Dv PMC_MODE_TS 81Allocate a process-scope sampling PMC. 82.El 83.Pp 84Mode specific modifiers may be specified using argument 85.Fa flags . 86The flags supported at PMC allocation time are: 87.Bl -tag -width ".Dv PMC_F_LOG_PROCEXIT" -compact 88.It Dv PMC_F_DESCENDANTS 89For process-scope PMCs, automatically track descendants of attached 90processes. 91.It Dv PMC_F_LOG_PROCCSW 92For process-scope counting PMCs, generate a log event at every context 93switch containing the incremental number of hardware events seen 94by the process during the time it was executing on the CPU. 95.It Dv PMC_F_LOG_PROCEXIT 96For process-scope counting PMCs, accumulate hardware events seen 97when the process was executing on a CPU and generate a log event 98when an attached process exits. 99.El 100PMCs allocated with flags 101.Dv PMC_F_LOG_PROCCSW 102and 103.Dv PMC_F_LOG_PROCEXIT 104need a log file to be configured before they are started. 105.Pp 106For system scope PMCs, the argument 107.Fa cpu 108is a non-negative value that specifies the CPU number 109that the PMC is to be allocated on. 110Process scope PMC allocations should specify the constant 111.Dv PMC_CPU_ANY 112for this argument. 113.Pp 114Function 115.Fn pmc_release 116releases the PMC denoted by argument 117.Fa pmcid . 118.Sh RETURN VALUES 119If successful, function 120.Fn pmc_allocate 121sets the location specified by argument 122.Fa pmcid 123to the handle of the allocated PMC and returns 0. 124In case of an error, the function returns -1 and sets the global 125variable 126.Va errno 127to indicate the error. 128.Pp 129.Rv -std pmc_release 130.Sh ERRORS 131.Bl -tag -width Er 132.It Bq Er EINVAL 133The argument 134.Fa mode 135to function 136.Fn pmc_allocate 137had an invalid value. 138.It Bq Er EINVAL 139Argument 140.Fa cpu 141to function 142.Fn pmc_allocate 143had an invalid CPU number. 144.It Bq Er EINVAL 145Argument 146.Fa flags 147contained flags that were unsupported or otherwise incompatible with 148the requested PMC mode. 149.It Bq Er EINVAL 150Argument 151.Fa eventspecifier 152to function 153.Fn pmc_allocate 154specified an event not supported by hardware or contained a syntax 155error. 156.It Bq Er ENXIO 157Function 158.Fn pmc_allocate 159requested the use of a hardware resource that was absent or 160administratively disabled. 161.It Bq Er EOPNOTSUPP 162The underlying hardware does not support the capabilities needed for 163a PMC being allocated by a call to 164.Fn pmc_allocate . 165.It Bq Er EPERM 166A system scope PMC allocation was attempted without adequate process 167privilege. 168.It Bq Er ESRCH 169Function 170.Fn pmc_release 171was called without first having allocated a PMC. 172.It Bq Er EINVAL 173Argument 174.Fa pmcid 175to function 176.Fn pmc_release 177did not specify a PMC previously allocated by this process. 178.El 179.Sh SEE ALSO 180.Xr pmc 3 , 181.Xr pmc_attach 3 , 182.Xr pmc_configure_logfile 3 , 183.Xr pmc_start 3 , 184.Xr hwpmc 4 185