share/man/man4/hwpmc.4

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