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 April 21, 2021 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.Fa "uint64_t count" 45.Fc 46.Ft int 47.Fn pmc_release "pmc_id_t pmc" 48.Sh DESCRIPTION 49Function 50.Fn pmc_allocate 51allocates a performance monitoring counter that measures the events 52named by argument 53.Fa eventspecifier , 54and writes the allocated handle to the location pointed to by argument 55.Fa pmcid . 56.Pp 57Argument 58.Fa eventspecifier 59comprises an PMC event name followed by an optional comma separated 60list of keywords and qualifiers. 61The allowed syntax for argument 62.Fa eventspecifier 63is processor specific and is listed in section 64.Sx "EVENT SPECIFIERS" 65in the 66.Xr pmc 3 67manual page. 68.Pp 69The desired PMC mode is specified by argument 70.Fa mode . 71Legal values for the 72.Fa mode 73argument are: 74.Bl -tag -width ".Dv PMC_MODE_SS" -compact 75.It Dv PMC_MODE_SC 76Allocate a system-scope counting PMC. 77.It Dv PMC_MODE_SS 78Allocate a system-scope sampling PMC. 79.It Dv PMC_MODE_TC 80Allocate a process-scope counting PMC. 81.It Dv PMC_MODE_TS 82Allocate a process-scope sampling PMC. 83.El 84.Pp 85Mode specific modifiers may be specified using argument 86.Fa flags . 87The flags supported at PMC allocation time are: 88.Bl -tag -width ".Dv PMC_F_LOG_PROCEXIT" -compact 89.It Dv PMC_F_DESCENDANTS 90For process-scope PMCs, automatically track descendants of attached 91processes. 92.It Dv PMC_F_LOG_PROCCSW 93For process-scope counting PMCs, generate a log event at every context 94switch containing the incremental number of hardware events seen 95by the process during the time it was executing on the CPU. 96.It Dv PMC_F_LOG_PROCEXIT 97For process-scope counting PMCs, accumulate hardware events seen 98when the process was executing on a CPU and generate a log event 99when an attached process exits. 100.El 101PMCs allocated with flags 102.Dv PMC_F_LOG_PROCCSW 103and 104.Dv PMC_F_LOG_PROCEXIT 105need a log file to be configured before they are started. 106.Pp 107For system scope PMCs, the argument 108.Fa cpu 109is a non-negative value that specifies the CPU number 110that the PMC is to be allocated on. 111Process scope PMC allocations should specify the constant 112.Dv PMC_CPU_ANY 113for this argument. 114.Pp 115The 116.Fa count 117argument behaves identically to the 118.Xr pmc_set 3 119function's 120.Fa value 121argument. 122For counting PMCs, 123.Fa count 124specifies the initial value of the allocated PMC. 125For sampling PMCs, 126.Fa count 127specifies the reload count. 128.Pp 129Function 130.Fn pmc_release 131releases the PMC denoted by argument 132.Fa pmcid . 133.Sh RETURN VALUES 134If successful, function 135.Fn pmc_allocate 136sets the location specified by argument 137.Fa pmcid 138to the handle of the allocated PMC and returns 0. 139In case of an error, the function returns -1 and sets the global 140variable 141.Va errno 142to indicate the error. 143.Pp 144.Rv -std pmc_release 145.Sh ERRORS 146.Bl -tag -width Er 147.It Bq Er EINVAL 148The argument 149.Fa mode 150to function 151.Fn pmc_allocate 152had an invalid value. 153.It Bq Er EINVAL 154Argument 155.Fa cpu 156to function 157.Fn pmc_allocate 158had an invalid CPU number. 159.It Bq Er EINVAL 160Argument 161.Fa flags 162contained flags that were unsupported or otherwise incompatible with 163the requested PMC mode. 164.It Bq Er EINVAL 165Argument 166.Fa eventspecifier 167to function 168.Fn pmc_allocate 169specified an event not supported by hardware or contained a syntax 170error. 171.It Bq Er ENXIO 172Function 173.Fn pmc_allocate 174requested the use of a hardware resource that was absent or 175administratively disabled. 176.It Bq Er EOPNOTSUPP 177The underlying hardware does not support the capabilities needed for 178a PMC being allocated by a call to 179.Fn pmc_allocate . 180.It Bq Er EPERM 181A system scope PMC allocation was attempted without adequate process 182privilege. 183.It Bq Er ESRCH 184Function 185.Fn pmc_release 186was called without first having allocated a PMC. 187.It Bq Er EINVAL 188Argument 189.Fa pmcid 190to function 191.Fn pmc_release 192did not specify a PMC previously allocated by this process. 193.El 194.Sh SEE ALSO 195.Xr pmc 3 , 196.Xr pmc_attach 3 , 197.Xr pmc_configure_logfile 3 , 198.Xr pmc_start 3 , 199.Xr hwpmc 4 200