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