lib/libpmc/pmc_capabilities.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_CAPABILITIES 3
  28 .Os
  29 .Sh NAME
  30 .Nm pmc_capabilities ,
  31 .Nm pmc_cpuinfo ,
  32 .Nm pmc_ncpu ,
  33 .Nm pmc_npmc ,
  34 .Nm pmc_pmcinfo ,
  35 .Nm pmc_width
  36 .Nd retrieve information about performance monitoring counters
  37 .Sh LIBRARY
  38 .Lb libpmc
  39 .Sh SYNOPSIS
  40 .In pmc.h
  41 .Ft int
  42 .Fn pmc_capabilities "pmc_id_t pmc" "uint32_t *caps"
  43 .Ft int
  44 .Fn pmc_cpuinfo "const struct pmc_cpuinfo **cpu_info"
  45 .Ft int
  46 .Fn pmc_ncpu void
  47 .Ft int
  48 .Fn pmc_npmc "int cpu"
  49 .Ft int
  50 .Fn pmc_pmcinfo "int cpu" "struct pmc_pmcinfo **pmc_info"
  51 .Ft int
  52 .Fn pmc_width "pmc_id_t pmc" "uint32_t *width"
  53 .Sh DESCRIPTION
  54 These functions retrieve information about performance monitoring
  55 hardware.
  56 .Pp
  57 Function
  58 .Fn pmc_capabilities
  59 retrieves the hardware capabilities of a PMC.
  60 Argument
  61 .Fa pmc
  62 is a PMC handle obtained by a prior call to
  63 .Fn pmc_allocate .
  64 The function sets argument
  65 .Fa caps
  66 to a bit mask of capabilities supported by the PMC denoted by
  67 argument
  68 .Fa pmc .
  69 PMC capabilities are described in
  70 .Xr pmc 3 .
  71 .Pp
  72 Function
  73 .Fn pmc_cpuinfo
  74 retrieves information about the CPUs in the system.
  75 Argument
  76 .Fa cpu_info
  77 will be set to point to an internal structure with information about
  78 the system's CPUs.
  79 The caller should not free this pointer value.
  80 This structure has the following fields:
  81 .Bl -tag -width "pm_classes" -offset indent -compact
  82 .It pm_cputype
  83 Specifies the CPU type.
  84 .It pm_ncpu
  85 Specifies the number of CPUs in the system.
  86 .It pm_npmc
  87 Specifies the number of PMC rows per CPU.
  88 .It pm_nclass
  89 Specifies the number of distinct classes of PMCs in the system.
  90 .It pm_classes
  91 Contains an array of
  92 .Vt "struct pmc_classinfo"
  93 descriptors describing the properties of each class of PMCs
  94 in the system.
  95 .El
  96 .Pp
  97 Function
  98 .Fn pmc_ncpu
  99 is a convenience function that returns the maximum CPU number in
 100 the system.
 101 On systems that support sparsely numbered CPUs, not all CPUs may
 102 be physically present.
 103 Applications need to be prepared to deal with nonexistent CPUs.
 104 .Pp
 105 Function
 106 .Fn pmc_npmc
 107 is a convenience function that returns the number of PMCs available
 108 in the CPU specified by argument
 109 .Fa cpu .
 110 .Pp
 111 Function
 112 .Fn pmc_pmcinfo
 113 returns information about the current state of the PMC hardware
 114 in the CPU specified by argument
 115 .Fa cpu .
 116 The location specified by argument
 117 .Fa pmc_info
 118 is set to point an array of
 119 .Vt "struct pmc_info"
 120 structures each describing the state of one PMC in the CPU.
 121 These structure contain the following fields:
 122 .Bl -tag -width pm_ownerpid -offset indent -compact
 123 .It pm_name
 124 A human readable name for the PMC.
 125 .It pm_class
 126 The PMC class for the PMC.
 127 .It pm_enabled
 128 Non-zero if the PMC is enabled.
 129 .It pm_rowdisp
 130 The disposition of the PMC row for this PMC.
 131 Row dispositions are documented in
 132 .Xr hwpmc 4 .
 133 .It pm_ownerpid
 134 If the hardware is in use, the process id of the owner of the PMC.
 135 .It pm_mode
 136 The PMC mode as described in
 137 .Xr pmc 3 .
 138 .It pm_event
 139 If the hardware is in use, the PMC event being measured.
 140 .It pm_flags
 141 If the hardware is in use, the flags associated with the PMC.
 142 .It pm_reloadcount
 143 For sampling PMCs, the reload count associated with the PMC.
 144 .El
 145 .Pp
 146 Function
 147 .Fn pmc_width
 148 is used to retrieve the width in bits of the hardware counters
 149 associated with a PMC.
 150 Argument
 151 .Fa pmc
 152 is a PMC handle obtained by a prior call to
 153 .Fn pmc_allocate .
 154 The function sets the location pointed to by argument
 155 .Fa width
 156 to the width of the physical counters associated with PMC
 157 .Fa pmc .
 158 .Sh RETURN VALUES
 159 Functions
 160 .Fn pmc_ncpu
 161 and
 162 .Fn pmc_npmc
 163 returns a positive integer if successful; otherwise the value -1 is
 164 returned and the global variable
 165 .Va errno
 166 is set to indicate the error.
 167 .Pp
 168 Functions
 169 .Fn pmc_capabilities ,
 170 .Fn pmc_cpuinfo ,
 171 .Fn pmc_pmcinfo
 172 and
 173 .Fn pmc_width
 174 return 0 if successful; otherwise the value -1 is returned and the
 175 global variable
 176 .Va errno
 177 is set to indicate the error.
 178 .Sh ERRORS
 179 A call to function
 180 .Fn pmc_capabilities
 181 may fail with the following errors:
 182 .Bl -tag -width Er
 183 .It Bq Er EINVAL
 184 The argument to the function was invalid.
 185 .El
 186 .Pp
 187 Calls to functions
 188 .Fn pmc_cpuinfo ,
 189 .Fn pmc_ncpu
 190 and
 191 .Fn pmc_npmc
 192 may fail with the following errors:
 193 .Bl -tag -width Er
 194 .It Bq Er ENXIO
 195 A prior call to
 196 .Fn pmc_init
 197 to initialize the PMC library had failed.
 198 .El
 199 .Pp
 200 A call to function
 201 .Fn pmc_pmcinfo
 202 may fail with the following errors:
 203 .Bl -tag -width Er
 204 .It Bq Er EINVAL
 205 The argument
 206 .Fa cpu
 207 was invalid.
 208 .It Bq Er ENXIO
 209 The argument
 210 .Fa cpu
 211 specified a disabled or absent CPU.
 212 .El
 213 .Pp
 214 A call to function
 215 .Fn pmc_width
 216 may fail with the following errors:
 217 .Bl -tag -width Er
 218 .It Bq Er EINVAL
 219 The argument to the function was invalid.
 220 .El
 221 .Sh SEE ALSO
 222 .Xr pmc 3 ,
 223 .Xr pmc_allocate 3 ,
 224 .Xr pmc_get_driver_stats 3 ,
 225 .Xr pmc_name_of_capability 3 ,
 226 .Xr pmc_name_of_cputype 3 ,
 227 .Xr pmc_name_of_class 3 ,
 228 .Xr pmc_name_of_event 3 ,
 229 .Xr pmc_name_of_mode 3 ,
 230 .Xr hwpmc 4