share/man/man4/hwpmc.4

   1 .\" Copyright (c) 2003-2005 Joseph Koshy
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd September 28, 2005
  28 .Dt HWPMC 4
  29 .Os
  30 .Sh NAME
  31 .Nm hwpmc
  32 .Nd "Hardware Performance Monitoring Counter support"
  33 .Sh SYNOPSIS
  34 .Cd "options HWPMC_HOOKS"
  35 .Cd "device hwpmc"
  36 .Pp
  37 Additionally, for i386 systems:
  38 .Cd "device apic"
  39 .Sh DESCRIPTION
  40 The
  41 .Nm
  42 driver virtualizes the hardware performance monitoring facilities in
  43 modern CPUs and provides support for using these facilities from
  44 user level processes.
  45 .Pp
  46 The driver supports multi-processor systems.
  47 .Pp
  48 PMCs are allocated using the
  49 .Dv PMC_OP_PMCALLOCATE
  50 request.
  51 A successful
  52 .Dv PMC_OP_PMCALLOCATE
  53 request will return an integer handle to the requesting process.
  54 Subsequent operations on the allocated PMC use this handle to denote
  55 the specific PMC.
  56 A process that has successfully allocated a PMC is termed an
  57 .Dq "owner process" .
  58 .Pp
  59 PMCs may be allocated to operate in process-private or in system-wide
  60 modes.
  61 .Bl -tag -width ".Em Process-private"
  62 .It Em Process-private
  63 In process-private mode, a PMC is active only when a thread belonging
  64 to a process it is attached to is scheduled on a CPU.
  65 .It Em System-wide
  66 In system-wide mode, a PMC operates independently of processes and
  67 measures hardware events for the system as a whole.
  68 .El
  69 .Pp
  70 The
  71 .Nm
  72 driver supports the use of hardware PMCs for counting or for
  73 sampling:
  74 .Bl -tag -width ".Em Counting"
  75 .It Em Counting
  76 In counting modes, the PMCs count hardware events.
  77 These counts are retrievable using the
  78 .Dv PMC_OP_PMCREAD
  79 system call on all architectures.
  80 Some architectures offer faster methods of reading these counts.
  81 .It Em Sampling
  82 In sampling modes, the PMCs are configured to sample the CPU
  83 instruction pointer after a configurable number of hardware events
  84 have been observed.
  85 These instruction pointer samples are usually directed to a log file
  86 for subsequent analysis.
  87 .El
  88 .Pp
  89 These modes of operation are orthogonal; a PMC may be configured to
  90 operate in one of four modes:
  91 .Bl -tag -width indent
  92 .It Process-private, counting
  93 These PMCs count hardware events whenever a thread in their attached process is
  94 scheduled on a CPU.
  95 These PMCs normally count from zero, but the initial count may be
  96 set using the
  97 .Dv PMC_OP_SETCOUNT
  98 operation.
  99 Applications can read the value of the PMC anytime using the
 100 .Dv PMC_OP_PMCRW
 101 operation.
 102 .It Process-private, sampling
 103 These PMCs sample the target processes instruction pointer after they
 104 have seen the configured number of hardware events.
 105 The PMCs only count events when a thread belonging to their attached
 106 process is active.
 107 The desired frequency of sampling is set using the
 108 .Dv PMC_OP_SETCOUNT
 109 operation prior to starting the PMC.
 110 Log files are configured using the
 111 .Dv PMC_OP_CONFIGURELOG
 112 operation.
 113 .It System-wide, counting
 114 These PMCs count hardware events seen by them independent of the
 115 processes that are executing.
 116 The current count on these PMCs can be read using the
 117 .Dv PMC_OP_PMCRW
 118 request.
 119 These PMCs normally count from zero, but the initial count may be
 120 set using the
 121 .Dv PMC_OP_SETCOUNT
 122 operation.
 123 .It System-wide, sampling
 124 These PMCs will periodically sample the instruction pointer of the CPU
 125 they are allocated on, and will write the sample to a log for further
 126 processing.
 127 The desired frequency of sampling is set using the
 128 .Dv PMC_OP_SETCOUNT
 129 operation prior to starting the PMC.
 130 Log files are configured using the
 131 .Dv PMC_OP_CONFIGURELOG
 132 operation.
 133 .Pp
 134 System-wide statistical sampling can only be enabled by a process with
 135 super-user privileges.
 136 .El
 137 .Pp
 138 Processes are allowed to allocate as many PMCs as the hardware and
 139 current operating conditions permit.
 140 Processes may mix allocations of system-wide and process-private
 141 PMCs.
 142 Multiple processes are allowed to be concurrently using the facilities
 143 of the
 144 .Nm
 145 driver.
 146 .Pp
 147 Allocated PMCs are started using the
 148 .Dv PMC_OP_PMCSTART
 149 operation, and stopped using the
 150 .Dv PMC_OP_PMCSTOP
 151 operation.
 152 Stopping and starting a PMC is permitted at any time the owner process
 153 has a valid handle to the PMC.
 154 .Pp
 155 Process-private PMCs need to be attached to a target process before
 156 they can be used.
 157 Attaching a process to a PMC is done using the
 158 .Dv PMC_OP_PMCATTACH
 159 operation.
 160 An already attached PMC may be detached from its target process
 161 using the converse
 162 .Dv PMC_OP_PMCDETACH
 163 operation.
 164 Issuing a
 165 .Dv PMC_OP_PMCSTART
 166 operation on an as yet unattached PMC will cause it to be attached
 167 to its owner process.
 168 The following rules determine whether a given process may attach
 169 a PMC to another target process:
 170 .Bl -bullet -compact
 171 .It
 172 A non-jailed process with super-user privileges is allowed to attach
 173 to any other process in the system.
 174 .It
 175 Other processes are only allowed to attach to targets that they would
 176 be able to attach to for debugging (as determined by
 177 .Xr p_candebug 9 ) .
 178 .El
 179 .Pp
 180 PMCs are released using
 181 .Dv PMC_OP_PMCRELEASE .
 182 After a successful
 183 .Dv PMC_OP_PMCRELEASE
 184 operation the handle to the PMC will become invalid.
 185 .Ss Modifier Flags
 186 The
 187 .Dv PMC_OP_PMCALLOCATE
 188 operation supports the following flags that modify the behavior
 189 of an allocated PMC:
 190 .Bl -tag -width indent
 191 .It Dv PMC_F_DESCENDANTS
 192 This modifier is valid only for a PMC being allocated in process-private
 193 mode.
 194 It signifies that the PMC will track hardware events for its
 195 target process and the target's current and future descendants.
 196 .It Dv PMC_F_KGMON
 197 This modifier is valid only for a PMC being allocated in system-wide
 198 sampling mode.
 199 It signifies that the PMC's sampling interrupt is to be used to drive
 200 kernel profiling via
 201 .Xr kgmon 8 .
 202 .It Dv PMC_F_LOG_PROCCSW
 203 This modifier is valid only for a PMC being allocated in process-private
 204 mode.
 205 When this modifier is present, at every context switch,
 206 .Nm
 207 will log a record containing the number of hardware events
 208 seen by the target process when it was scheduled on the CPU.
 209 .It Dv PMC_F_LOG_PROCEXIT
 210 This modifier is valid only for a PMC being allocated in process-private
 211 mode.
 212 With this modifier present,
 213 .Nm
 214 will maintain per-process counts for each target process attached to
 215 a PMC.
 216 At process exit time, a record containing the target process' PID and
 217 the accumulated per-process count for that process will be written to the
 218 configured log file.
 219 .El
 220 .Pp
 221 Modifiers
 222 .Dv PMC_F_LOG_PROCEXIT
 223 and
 224 .Dv PMC_F_LOG_PROCCSW
 225 may be used in combination with modifier
 226 .Dv PMC_F_DESCENDANTS
 227 to track the behavior of complex pipelines of processes.
 228 PMCs with modifiers
 229 .Dv PMC_F_LOG_PROCEXIT
 230 and
 231 .Dv PMC_F_LOG_PROCCSW
 232 cannot be started until their owner process has configured a log file.
 233 .Ss Signals
 234 The
 235 .Nm
 236 driver may deliver signals to processes that have allocated PMCs:
 237 .Bl -tag -width ".Dv SIGBUS"
 238 .It Dv SIGIO
 239 A
 240 .Dv PMC_OP_PMCRW
 241 operation was attempted on a process-private PMC that does not have
 242 attached target processes.
 243 .It Dv SIGBUS
 244 The
 245 .Nm
 246 driver is being unloaded from the kernel.
 247 .El
 248 .Sh PROGRAMMING API
 249 The recommended way for application programs to use the facilities of
 250 the
 251 .Nm
 252 driver is using the API provided by the
 253 .Xr pmc 3
 254 library.
 255 .Pp
 256 The
 257 .Nm
 258 driver operates using a system call number that is dynamically
 259 allotted to it when it is loaded into the kernel.
 260 .Pp
 261 The
 262 .Nm
 263 driver supports the following operations:
 264 .Bl -tag -width indent
 265 .It Dv PMC_OP_CONFIGURELOG
 266 Configure a log file for sampling mode PMCs.
 267 .It Dv PMC_OP_FLUSHLOG
 268 Transfer buffered log data inside
 269 .Nm
 270 to a configured output file.
 271 This operation returns to the caller after the write operation
 272 has returned.
 273 .It Dv PMC_OP_GETCPUINFO
 274 Retrieve information about the number of CPUs on the system and
 275 the number of hardware performance monitoring counters available per-CPU.
 276 .It Dv PMC_OP_GETDRIVERSTATS
 277 Retrieve module statistics (for analyzing the behavior of
 278 .Nm
 279 itself).
 280 .It Dv PMC_OP_GETMODULEVERSION
 281 Retrieve the version number of API.
 282 .It Dv PMC_OP_GETPMCINFO
 283 Retrieve information about the current state of the PMCs on a
 284 given CPU.
 285 .It Dv PMC_OP_PMCADMIN
 286 Set the administrative state (i.e., whether enabled or disabled) for
 287 the hardware PMCs managed by the
 288 .Nm
 289 driver.
 290 .It Dv PMC_OP_PMCALLOCATE
 291 Allocate and configure a PMC.
 292 On successful allocation, a handle to the PMC (a small integer)
 293 is returned.
 294 .It Dv PMC_OP_PMCATTACH
 295 Attach a process mode PMC to a target process.
 296 The PMC will be active whenever a thread in the target process is
 297 scheduled on a CPU.
 298 .Pp
 299 If the
 300 .Dv PMC_F_DESCENDANTS
 301 flag had been specified at PMC allocation time, then the PMC is
 302 attached to all current and future descendants of the target process.
 303 .It Dv PMC_OP_PMCDETACH
 304 Detach a PMC from its target process.
 305 .It Dv PMC_OP_PMCRELEASE
 306 Release a PMC.
 307 .It Dv PMC_OP_PMCRW
 308 Read and write a PMC.
 309 This operation is valid only for PMCs configured in counting modes.
 310 .It Dv PMC_OP_SETCOUNT
 311 Set the initial count (for counting mode PMCs) or the desired sampling
 312 rate (for sampling mode PMCs).
 313 .It Dv PMC_OP_PMCSTART
 314 Start a PMC.
 315 .It Dv PMC_OP_PMCSTOP
 316 Stop a PMC.
 317 .It Dv PMC_OP_WRITELOG
 318 Insert a timestamped user record into the log file.
 319 .El
 320 .Ss i386 Specific API
 321 Some i386 family CPUs support the RDPMC instruction which allows a
 322 user process to read a PMC value without needing to invoke a
 323 .Dv PMC_OP_PMCRW
 324 operation.
 325 On such CPUs, the machine address associated with an allocated PMC is
 326 retrievable using the
 327 .Dv PMC_OP_PMCX86GETMSR
 328 system call.
 329 .Bl -tag -width indent
 330 .It Dv PMC_OP_PMCX86GETMSR
 331 Retrieve the MSR (machine specific register) number associated with
 332 the given PMC handle.
 333 .Pp
 334 The PMC needs to be in process-private mode and allocated without the
 335 .Dv PMC_F_DESCENDANTS
 336 modifier flag, and should be attached only to its owner process at the
 337 time of the call.
 338 .El
 339 .Ss amd64 Specific API
 340 AMD64 CPUs support the RDPMC instruction which allows a
 341 user process to read a PMC value without needing to invoke a
 342 .Dv PMC_OP_PMCRW
 343 operation.
 344 The machine address associated with an allocated PMC is
 345 retrievable using the
 346 .Dv PMC_OP_PMCX86GETMSR
 347 system call.
 348 .Bl -tag -width indent
 349 .It Dv PMC_OP_PMCX86GETMSR
 350 Retrieve the MSR (machine specific register) number associated with
 351 the given PMC handle.
 352 .Pp
 353 The PMC needs to be in process-private mode and allocated without the
 354 .Dv PMC_F_DESCENDANTS
 355 modifier flag, and should be attached only to its owner process at the
 356 time of the call.
 357 .El
 358 .Sh SYSCTL VARIABLES AND LOADER TUNABLES
 359 The behavior of
 360 .Nm
 361 is influenced by the following
 362 .Xr sysctl 8
 363 and
 364 .Xr loader 8
 365 tunables:
 366 .Bl -tag -width indent
 367 .It Va kern.hwpmc.debugflags Pq string, read-write
 368 (Only available if the
 369 .Nm
 370 driver was compiled with
 371 .Fl DDEBUG . )
 372 Control the verbosity of debug messages from the
 373 .Nm
 374 driver.
 375 .It Va kern.hwpmc.hashsize Pq integer, read-only
 376 The number of rows in the hash tables used to keep track of owner and
 377 target processes.
 378 The default is 16.
 379 .It Va kern.hwpmc.logbuffersize Pq integer, read-only
 380 The size in kilobytes of each log buffer used by
 381 .Nm Ns 's
 382 logging function.
 383 The default buffer size is 4KB.
 384 .It Va kern.hwpmc.mtxpoolsize Pq integer, read-only
 385 The size of the spin mutex pool used by the PMC driver.
 386 The default is 32.
 387 .It Va kern.hwpmc.nbuffers Pq integer, read-only
 388 The number of log buffers used by
 389 .Nm
 390 for logging.
 391 The default is 16.
 392 .It Va kern.hwpmc.nsamples Pq integer, read-only
 393 The number of entries in the per-CPU ring buffer used during sampling.
 394 The default is 16.
 395 .It Va security.bsd.unprivileged_syspmcs Pq boolean, read-write
 396 If set to non-zero, allow unprivileged processes to allocate system-wide
 397 PMCs.
 398 The default value is 0.
 399 .It Va security.bsd.unprivileged_proc_debug Pq boolean, read-write
 400 If set to 0, the
 401 .Nm
 402 driver will only allow privileged processes to attach PMCs to other
 403 processes.
 404 .El
 405 .Pp
 406 These variables may be set in the kernel environment using
 407 .Xr kenv 1
 408 before
 409 .Nm
 410 is loaded.
 411 .Sh SECURITY CONSIDERATIONS
 412 PMCs may be used to monitor the actual behavior of the system on hardware.
 413 In situations where this constitutes an undesirable information leak,
 414 the following options are available:
 415 .Bl -enum
 416 .It
 417 Set the
 418 .Xr sysctl 8
 419 tunable
 420 .Va security.bsd.unprivileged_syspmcs
 421 to 0.
 422 This ensures that unprivileged processes cannot allocate system-wide
 423 PMCs and thus cannot observe the hardware behavior of the system
 424 as a whole.
 425 This tunable may also be set at boot time using
 426 .Xr loader 8 ,
 427 or with
 428 .Xr kenv 1
 429 prior to loading the
 430 .Nm
 431 driver into the kernel.
 432 .It
 433 Set the
 434 .Xr sysctl 8
 435 tunable
 436 .Va security.bsd.unprivileged_proc_debug
 437 to 0.
 438 This will ensure that an unprivileged process cannot attach a PMC
 439 to any process other than itself and thus cannot observe the hardware
 440 behavior of other processes with the same credentials.
 441 .El
 442 .Pp
 443 System administrators should note that on IA-32 platforms
 444 .Fx
 445 makes the content of the IA-32 TSC counter available to all processes
 446 via the RDTSC instruction.
 447 .Sh IMPLEMENTATION NOTES
 448 .Ss SMP Symmetry
 449 The kernel driver requires all physical CPUs in an SMP system to have
 450 identical performance monitoring counter hardware.
 451 .Ss x86 TSC Handling
 452 Historically, on the x86 architecture,
 453 .Fx
 454 has permitted user processes running at a processor CPL of 3 to
 455 read the TSC using the RDTSC instruction.
 456 The
 457 .Nm
 458 driver preserves this behavior.
 459 .Ss Intel P4/HTT Handling
 460 On CPUs with HTT support, Intel P4 PMCs are capable of qualifying
 461 only a subset of hardware events on a per-logical CPU basis.
 462 Consequently, if HTT is enabled on a system with Intel Pentium P4
 463 PMCs, then the
 464 .Nm
 465 driver will reject allocation requests for process-private PMCs that
 466 request counting of hardware events that cannot be counted separately
 467 for each logical CPU.
 468 .Ss Intel Pentium-Pro Handling
 469 Writing a value to the PMC MSRs found in Intel Pentium-Pro style PMCs
 470 (found in
 471 .Tn "Intel Pentium Pro" ,
 472 .Tn "Pentium II" ,
 473 .Tn "Pentium III" ,
 474 .Tn "Pentium M"
 475 and
 476 .Tn "Celeron"
 477 processors) will replicate bit 31 of the
 478 value being written into the upper 8 bits of the MSR,
 479 bringing down the usable width of these PMCs to 31 bits.
 480 For process-virtual PMCs, the
 481 .Nm
 482 driver implements a workaround in software and makes the corrected 64
 483 bit count available via the
 484 .Dv PMC_OP_RW
 485 operation.
 486 Processes that intend to use RDPMC instructions directly or
 487 that intend to write values larger than 2^31 into these PMCs with
 488 .Dv PMC_OP_RW
 489 need to be aware of this hardware limitation.
 490 .Sh DIAGNOSTICS
 491 .Bl -diag
 492 .It "hwpmc: [class/npmc/capabilities]..."
 493 Announce the presence of
 494 .Va npmc
 495 PMCs of class
 496 .Va class ,
 497 with capabilities described by bit string
 498 .Va capabilities .
 499 .It "hwpmc: kernel version (0x%x) does not match module version (0x%x)."
 500 The module loading process failed because a version mismatch was detected
 501 between the currently executing kernel and the module being loaded.
 502 .It "hwpmc: this kernel has not been compiled with 'options HWPMC_HOOKS'."
 503 The module loading process failed because the currently executing kernel
 504 was not configured with the required configuration option
 505 .Dv HWPMC_HOOKS .
 506 .It "hwpmc: tunable hashsize=%d must be greater than zero."
 507 A negative value was supplied for tunable
 508 .Va kern.hwpmc.hashsize .
 509 .It "hwpmc: tunable logbuffersize=%d must be greater than zero."
 510 A negative value was supplied for tunable
 511 .Va kern.hwpmc.logbuffersize .
 512 .It "hwpmc: tunable nlogbuffers=%d must be greater than zero."
 513 A negative value was supplied for tunable
 514 .Va kern.hwpmc.nlogbuffers .
 515 .It "hwpmc: tunable nsamples=%d out of range."
 516 The value for tunable
 517 .Va kern.hwpmc.nsamples
 518 was negative or greater than 65535.
 519 .El
 520 .Sh COMPATIBILITY
 521 The
 522 .Nm
 523 driver is
 524 .Ud
 525 The API and ABI documented in this manual page may change in
 526 the future.
 527 The recommended method of accessing this driver is using the
 528 .Xr pmc 3
 529 API.
 530 .Sh ERRORS
 531 A command issued to the
 532 .Nm
 533 driver may fail with the following errors:
 534 .Bl -tag -width Er
 535 .It Bq Er EBUSY
 536 A
 537 .Dv PMC_OP_CONFIGURELOG
 538 operation was requested while an existing log was active.
 539 .It Bq Er EBUSY
 540 A DISABLE operation was requested using the
 541 .Dv PMC_OP_PMCADMIN
 542 request for a set of hardware resources currently in use for
 543 process-private PMCs.
 544 .It Bq Er EBUSY
 545 A
 546 .Dv PMC_OP_PMCADMIN
 547 operation was requested on an active system mode PMC.
 548 .It Bq Er EBUSY
 549 A
 550 .Dv PMC_OP_PMCATTACH
 551 operation was requested for a target process that already had another
 552 PMC using the same hardware resources attached to it.
 553 .It Bq Er EBUSY
 554 A
 555 .Dv PMC_OP_PMCRW
 556 request writing a new value was issued on a PMC that was active.
 557 .It Bq Er EBUSY
 558 A
 559 .Dv PMC_OP_PMCSETCOUNT
 560 request was issued on a PMC that was active.
 561 .It Bq Er EDOOFUS
 562 A
 563 .Dv PMC_OP_PMCSTART
 564 operation was requested without a log file being configured for a
 565 PMC allocated with
 566 .Dv PMC_F_LOG_PROCCSW
 567 and
 568 .Dv PMC_F_LOG_PROCEXIT
 569 modifiers.
 570 .It Bq Er EEXIST
 571 A
 572 .Dv PMC_OP_PMCATTACH
 573 request was reissued for a target process that already is the target
 574 of this PMC.
 575 .It Bq Er EFAULT
 576 A bad address was passed in to the driver.
 577 .It Bq Er EINVAL
 578 A process specified an invalid PMC handle.
 579 .It Bq Er EINVAL
 580 An invalid CPU number was passed in for a
 581 .Dv PMC_OP_GETPMCINFO
 582 operation.
 583 .It Bq Er EINVAL
 584 An invalid CPU number was passed in for a
 585 .Dv PMC_OP_PMCADMIN
 586 operation.
 587 .It Bq Er EINVAL
 588 An invalid operation request was passed in for a
 589 .Dv PMC_OP_PMCADMIN
 590 operation.
 591 .It Bq Er EINVAL
 592 An invalid PMC ID was passed in for a
 593 .Dv PMC_OP_PMCADMIN
 594 operation.
 595 .It Bq Er EINVAL
 596 A suitable PMC matching the parameters passed in to a
 597 .Dv PMC_OP_PMCALLOCATE
 598 request could not be allocated.
 599 .It Bq Er EINVAL
 600 An invalid PMC mode was requested during a
 601 .Dv PMC_OP_PMCALLOCATE
 602 request.
 603 .It Bq Er EINVAL
 604 An invalid CPU number was specified during a
 605 .Dv PMC_OP_PMCALLOCATE
 606 request.
 607 .It Bq Er EINVAL
 608 A CPU other than
 609 .Dv PMC_CPU_ANY
 610 was specified in a
 611 .Dv PMC_OP_ALLOCATE
 612 request for a process-private PMC.
 613 .It Bq Er EINVAL
 614 A CPU number of
 615 .Dv PMC_CPU_ANY
 616 was specified in a
 617 .Dv PMC_OP_ALLOCATE
 618 request for a system-wide PMC.
 619 .It Bq Er EINVAL
 620 The
 621 .Ar pm_flags
 622 argument to an
 623 .Dv PMC_OP_PMCALLOCATE
 624 request contained unknown flags.
 625 .It Bq Er EINVAL
 626 A PMC allocated for system-wide operation was specified with a
 627 .Dv PMC_OP_PMCATTACH
 628 request.
 629 .It Bq Er EINVAL
 630 The
 631 .Ar pm_pid
 632 argument to a
 633 .Dv PMC_OP_PMCATTACH
 634 request specified an illegal process ID.
 635 .It Bq Er EINVAL
 636 A
 637 .Dv PMC_OP_PMCDETACH
 638 request was issued for a PMC not attached to the target process.
 639 .It Bq Er EINVAL
 640 Argument
 641 .Ar pm_flags
 642 to a
 643 .Dv PMC_OP_PMCRW
 644 request contained illegal flags.
 645 .It Bq Er EINVAL
 646 A
 647 .Dv PMC_OP_PMCX86GETMSR
 648 operation was requested for a PMC not in process-virtual mode, or
 649 for a PMC that is not solely attached to its owner process, or for
 650 a PMC that was allocated with flag
 651 .Dv PMC_F_DESCENDANTS .
 652 .It Bq Er EINVAL
 653 (On Intel Pentium 4 CPUs with HTT support)
 654 An allocation request for
 655 a process-private PMC was issued for an event that does not support
 656 counting on a per-logical CPU basis.
 657 .It Bq Er ENOMEM
 658 The system was not able to allocate kernel memory.
 659 .It Bq Er ENOSYS
 660 (i386 architectures)
 661 A
 662 .Dv PMC_OP_PMCX86GETMSR
 663 operation was requested for hardware that does not support reading
 664 PMCs directly with the RDPMC instruction.
 665 .It Bq Er ENXIO
 666 A
 667 .Dv PMC_OP_GETPMCINFO
 668 operation was requested for a disabled CPU.
 669 .It Bq Er ENXIO
 670 A system-wide PMC on a disabled CPU was requested to be allocated with
 671 .Dv PMC_OP_PMCALLOCATE .
 672 .It Bq Er ENXIO
 673 A
 674 .Dv PMC_OP_PMCSTART
 675 or
 676 .Dv PMC_OP_PMCSTOP
 677 request was issued for a system-wide PMC that was allocated on a
 678 currently disabled CPU.
 679 .It Bq Er EOPNOTSUPP
 680 A
 681 .Dv PMC_OP_PMCALLOCATE
 682 request was issued for PMC capabilities not supported
 683 by the specified PMC class.
 684 .It Bq Er EOPNOTSUPP
 685 (i386 architectures)
 686 A sampling mode PMC was requested on a CPU lacking an APIC.
 687 .It Bq Er EPERM
 688 A
 689 .Dv PMC_OP_PMCADMIN
 690 request was issued by a process without super-user
 691 privilege or by a jailed super-user process.
 692 .It Bq Er EPERM
 693 A
 694 .Dv PMC_OP_PMCATTACH
 695 operation was issued for a target process that the current process
 696 does not have permission to attach to.
 697 .It Bq Er EPERM
 698 (i386 and amd64 architectures)
 699 A
 700 .Dv PMC_OP_PMCATTACH
 701 operation was issued on a PMC whose MSR has been retrieved using
 702 .Dv PMC_OP_PMCX86GETMSR .
 703 .It Bq Er ESRCH
 704 A process issued a PMC operation request without having allocated any
 705 PMCs.
 706 .It Bq Er ESRCH
 707 A process issued a PMC operation request after the PMC was detached
 708 from all of its target processes.
 709 .It Bq Er ESRCH
 710 A
 711 .Dv PMC_OP_PMCATTACH
 712 request specified a non-existent process ID.
 713 .It Bq Er ESRCH
 714 The target process for a
 715 .Dv PMC_OP_PMCDETACH
 716 operation is not being monitored by the
 717 .Nm
 718 driver.
 719 .El
 720 .Sh SEE ALSO
 721 .Xr kenv 1 ,
 722 .Xr pmc 3 ,
 723 .Xr pmclog 3 ,
 724 .Xr kgmon 8 ,
 725 .Xr kldload 8 ,
 726 .Xr pmccontrol 8 ,
 727 .Xr pmcstat 8 ,
 728 .Xr sysctl 8 ,
 729 .Xr p_candebug 9
 730 .Sh HISTORY
 731 The
 732 .Nm
 733 driver first appeared in
 734 .Fx 6.0 .
 735 .Sh BUGS
 736 The driver samples the state of the kernel's logical processor support
 737 at the time of initialization (i.e., at module load time).
 738 On CPUs supporting logical processors, the driver could misbehave if
 739 logical processors are subsequently enabled or disabled while the
 740 driver is active.
 741 .Pp
 742 On the i386 architecture, the driver requires that the local APIC on the
 743 CPU be enabled for sampling mode to be supported.
 744 Many single-processor motherboards keep the APIC disabled in BIOS; on
 745 such systems
 746 .Nm
 747 will not support sampling PMCs.