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