share/man/man4/hwpmc.4

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