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