lib/libpmc/pmc_allocate.3

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