| hwpmc.4 (145774) | hwpmc.4 (147191) |
|---|---|
| 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. --- 8 unchanged lines hidden (view full) --- 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.\" | 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. --- 8 unchanged lines hidden (view full) --- 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: head/share/man/man4/hwpmc.4 145774 2005-05-01 14:11:49Z jkoshy $ | 25.\" $FreeBSD: head/share/man/man4/hwpmc.4 147191 2005-06-09 19:45:09Z jkoshy $ |
| 26.\" 27.Dd Apr 15, 2005 28.Dt HWPMC 4 29.Os 30.Sh NAME 31.Nm hwpmc 32.Nd Hardware performance monitoring counter support 33.Sh SYNOPSIS --- 147 unchanged lines hidden (view full) --- 181After a successful 182.Ic PMC_OP_PMCRELEASE 183operation the handle to the PMC will become invalid. 184.Ss MODIFIER FLAGS 185The 186.Ic PMC_OP_PMCALLOCATE 187operation supports the following flags that modify the behavior 188of an allocated PMC: | 26.\" 27.Dd Apr 15, 2005 28.Dt HWPMC 4 29.Os 30.Sh NAME 31.Nm hwpmc 32.Nd Hardware performance monitoring counter support 33.Sh SYNOPSIS --- 147 unchanged lines hidden (view full) --- 181After a successful 182.Ic PMC_OP_PMCRELEASE 183operation the handle to the PMC will become invalid. 184.Ss MODIFIER FLAGS 185The 186.Ic PMC_OP_PMCALLOCATE 187operation supports the following flags that modify the behavior 188of an allocated PMC: |
| 189.Bl -tag -width indent | 189.Bl -tag -width indent -compact |
| 190.It Dv PMC_F_DESCENDANTS | 190.It Dv PMC_F_DESCENDANTS |
| 191This flag is valid only for a PMC being allocated in process-private | 191This modifier is valid only for a PMC being allocated in process-private |
| 192mode. 193It signifies that the PMC will track hardware events for its 194target process and the target's current and future descendants. | 192mode. 193It signifies that the PMC will track hardware events for its 194target process and the target's current and future descendants. |
| 195.It Dv PMC_F_KGMON 196This modifier is valid only for a PMC being allocated in system-wide 197sampling mode. 198It signifies that the PMC's sampling interrupt is to be used to drive 199kernel profiling via 200.Xr kgmon 8 . 201.It Dv PMC_F_LOG_PROCCSW 202This modifier is valid only for a PMC being allocated in process-private 203mode. 204When this modifier is present, at every process context switch time, 205.Nm 206will append a record containing the count of the hardware events 207seen by the process to the configured log file. 208.It Dv PMC_F_LOG_PROCEXIT 209This modifier is valid only for a PMC being allocated in process-private 210mode. 211With this modifier present, 212.Nm 213will maintain per-process counts for each target process attached to 214a PMC. 215At process exit time, a record containing the target process' pid and 216the accumulated per-process count for that process will be written to the 217configured log file. |
|
| 195.El | 218.El |
| 219Modifiers 220.Dv PMC_F_LOG_PROCEXIT 221and 222.Dv PMC_F_LOG_PROCCSW 223may be used in combination with modifier 224.Dv PMC_F_DESCENDANTS 225to track the behaviour of complex pipelines of processes. |
|
| 196.Ss SIGNALS 197The 198.Nm 199driver may deliver signals to processes that have allocated PMCs: | 226.Ss SIGNALS 227The 228.Nm 229driver may deliver signals to processes that have allocated PMCs: |
| 200.Bl -tag -width indent | 230.Bl -tag -width "XXXXXXXX" -compact |
| 201.It Bq SIGIO 202A 203.Ic PMC_OP_PMCRW 204operation was attempted on a process-private PMC that does not have 205attached target processes. 206.It Bq SIGBUS 207The 208.Nm --- 12 unchanged lines hidden (view full) --- 221allotted to it when it is loaded into the kernel. 222.Pp 223The 224.Nm 225driver supports the following operations: 226.Bl -tag -width indent 227.It Ic PMC_OP_CONFIGURELOG 228Configure a log file for sampling mode PMCs. | 231.It Bq SIGIO 232A 233.Ic PMC_OP_PMCRW 234operation was attempted on a process-private PMC that does not have 235attached target processes. 236.It Bq SIGBUS 237The 238.Nm --- 12 unchanged lines hidden (view full) --- 251allotted to it when it is loaded into the kernel. 252.Pp 253The 254.Nm 255driver supports the following operations: 256.Bl -tag -width indent 257.It Ic PMC_OP_CONFIGURELOG 258Configure a log file for sampling mode PMCs. |
| 259.It Ic PMC_OP_FLUSHLOG 260Transfer buffered log data inside 261.Nm 262to a configured output file. 263This operation returns to the caller after the write operation 264has returned. |
|
| 229.It Ic PMC_OP_GETCPUINFO 230Retrieve information about the number of CPUs on the system and 231the number of hardware performance monitoring counters available per-CPU. 232.It Ic PMC_OP_GETDRIVERSTATS 233Retrieve module statistics (for analyzing the behavior of 234.Nm 235itself). 236.It Ic PMC_OP_GETMODULEVERSION --- 74 unchanged lines hidden (view full) --- 311modifier flag, and should be attached only to its owner process at the 312time of the call. 313.El 314.Sh SYSCTL TUNABLES 315The behavior of 316.Nm 317is influenced by the following 318.Xr sysctl 8 | 265.It Ic PMC_OP_GETCPUINFO 266Retrieve information about the number of CPUs on the system and 267the number of hardware performance monitoring counters available per-CPU. 268.It Ic PMC_OP_GETDRIVERSTATS 269Retrieve module statistics (for analyzing the behavior of 270.Nm 271itself). 272.It Ic PMC_OP_GETMODULEVERSION --- 74 unchanged lines hidden (view full) --- 347modifier flag, and should be attached only to its owner process at the 348time of the call. 349.El 350.Sh SYSCTL TUNABLES 351The behavior of 352.Nm 353is influenced by the following 354.Xr sysctl 8 |
| 355and 356.Xr loader 8 |
|
| 319tunables: 320.Bl -tag -width indent | 357tunables: 358.Bl -tag -width indent |
| 321.It Va kern.hwpmc.debugflags | 359.It Va kern.hwpmc.debugflags Pq string, read-write |
| 322(Only available if the 323.Nm 324driver was compiled with 325.Fl DDEBUG ) . 326Control the verbosity of debug messages from the 327.Nm 328driver. | 360(Only available if the 361.Nm 362driver was compiled with 363.Fl DDEBUG ) . 364Control the verbosity of debug messages from the 365.Nm 366driver. |
| 329.It Va kern.hwpmc.hashsize | 367.It Va kern.hwpmc.hashsize Pq integer, read-only |
| 330The number of rows in the hash-tables used to keep track of owner and 331target processes. | 368The number of rows in the hash-tables used to keep track of owner and 369target processes. |
| 332.It Va kern.hwpmc.mtxpoolsize | 370The default is 16. 371.It Va kern.hwpmc.logbuffersize Pq integer, read-only 372The size in kilobytes of each log buffer used by 373.Nm Ap s 374logging function. 375The default buffers size is 4KB. 376.It Va kern.hwpmc.mtxpoolsize Pq integer, read-only |
| 333The size of the spin mutex pool used by the PMC driver. | 377The size of the spin mutex pool used by the PMC driver. |
| 334.It Va kern.hwpmc.pcpubuffersize 335The size of the per-cpu hash table used when performing system-wide 336statistical profiling. 337.It Va security.bsd.unprivileged_syspmcs | 378The default is 32. 379.It Va kern.hwpmc.nbuffers Pq integer, read-only 380The number of log buffers used by 381.Nm 382for logging. 383The default is 16. 384.It Va kern.hwpmc.nsamples Pq integer, read-only 385The number of entries in the per-cpu ring buffer used during sampling. 386The default is 16. 387.It Va security.bsd.unprivileged_syspmcs Pq boolean, read-write |
| 338If set to non-zero, allow unprivileged processes to allocate system-wide 339PMCs. 340The default value is 0. | 388If set to non-zero, allow unprivileged processes to allocate system-wide 389PMCs. 390The default value is 0. |
| 341.It Va security.bsd.unprivileged_proc_debug | 391.It Va security.bsd.unprivileged_proc_debug Pq boolean, read-write |
| 342If set to 0, the 343.Nm | 392If set to 0, the 393.Nm |
| 344driver will only allow privileged process to attach PMCs to other | 394driver will only allow privileged processes to attach PMCs to other |
| 345processes. 346.El 347.Pp 348These variables may be set in the kernel environment using 349.Xr kenv 1 350before 351.Nm 352is loaded. 353.Sh SECURITY CONSIDERATIONS 354PMCs may be used to monitor the actual behaviour of the system on hardware. 355In situations where this constitutes an undesirable information leak, 356the following options are available: 357.Bl -enum 358.It 359Set the 360.Xr sysctl 8 361tunable 362.Va "security.bsd.unprivileged_syspmcs" 363to 0. | 395processes. 396.El 397.Pp 398These variables may be set in the kernel environment using 399.Xr kenv 1 400before 401.Nm 402is loaded. 403.Sh SECURITY CONSIDERATIONS 404PMCs may be used to monitor the actual behaviour of the system on hardware. 405In situations where this constitutes an undesirable information leak, 406the following options are available: 407.Bl -enum 408.It 409Set the 410.Xr sysctl 8 411tunable 412.Va "security.bsd.unprivileged_syspmcs" 413to 0. |
| 364.Pp | |
| 365This ensures that unprivileged processes cannot allocate system-wide 366PMCs and thus cannot observe the hardware behavior of the system 367as a whole. | 414This ensures that unprivileged processes cannot allocate system-wide 415PMCs and thus cannot observe the hardware behavior of the system 416as a whole. |
| 368.Pp | |
| 369This tunable may also be set at boot time using 370.Xr loader 8 , 371or with 372.Xr kenv 1 373prior to loading the 374.Nm 375driver into the kernel. 376.It 377Set the 378.Xr sysctl 8 379tunable 380.Va "security.bsd.unprivileged_proc_debug" 381to 0. | 417This tunable may also be set at boot time using 418.Xr loader 8 , 419or with 420.Xr kenv 1 421prior to loading the 422.Nm 423driver into the kernel. 424.It 425Set the 426.Xr sysctl 8 427tunable 428.Va "security.bsd.unprivileged_proc_debug" 429to 0. |
| 382.Pp | |
| 383This will ensure that an unprivileged process cannot attach a PMC 384to any process other than itself and thus cannot observe the hardware 385behavior of other processes with the same credentials. 386.El 387.Pp 388System administrators should note that on IA-32 platforms 389.Fx 390makes the content of the IA-32 TSC counter available to all processes 391via the RDTSC instruction. 392.Sh IMPLEMENTATION NOTES | 430This will ensure that an unprivileged process cannot attach a PMC 431to any process other than itself and thus cannot observe the hardware 432behavior of other processes with the same credentials. 433.El 434.Pp 435System administrators should note that on IA-32 platforms 436.Fx 437makes the content of the IA-32 TSC counter available to all processes 438via the RDTSC instruction. 439.Sh IMPLEMENTATION NOTES |
| 440.Ss SMP Symmetry 441The kernel driver requires all physical CPUs in an SMP system to have 442identical performance monitoring counter hardware. |
|
| 393.Ss i386 TSC Handling 394Historically, on the x86 architecture, 395.Fx 396has permitted user processes running at a processor CPL of 3 to 397read the TSC using the RDTSC instruction. 398The 399.Nm 400driver preserves this semantic. | 443.Ss i386 TSC Handling 444Historically, on the x86 architecture, 445.Fx 446has permitted user processes running at a processor CPL of 3 to 447read the TSC using the RDTSC instruction. 448The 449.Nm 450driver preserves this semantic. |
| 401.Pp 402TSCs are treated as shared, read-only counters and hence are 403only allowed to be allocated in system-wide counting mode. | |
| 404.Ss Intel P4/HTT Handling 405On CPUs with HTT support, Intel P4 PMCs are capable of qualifying 406only a subset of hardware events on a per-logical CPU basis. 407Consequently, if HTT is enabled on a system with Intel Pentium P4 408PMCs, then the 409.Nm 410driver will reject allocation requests for process-private PMCs that 411request counting of hardware events that cannot be counted separately 412for each logical CPU. | 451.Ss Intel P4/HTT Handling 452On CPUs with HTT support, Intel P4 PMCs are capable of qualifying 453only a subset of hardware events on a per-logical CPU basis. 454Consequently, if HTT is enabled on a system with Intel Pentium P4 455PMCs, then the 456.Nm 457driver will reject allocation requests for process-private PMCs that 458request counting of hardware events that cannot be counted separately 459for each logical CPU. |
| 460.Ss Intel Pentium-Pro Handling 461Writing a value to the PMC MSRs found ing Intel Pentium-Pro style PMCs 462(found in 463.Tn "Intel Pentium Pro" , 464.Tn "Pentium II" , 465.Tn "Pentium III" , 466.Tn "Pentium M" 467and 468.Tn "Celeron" 469processors) will replicate bit 31 of the 470value being written into the upper 8 bits of the MSR, 471bringing down the usable width of these PMCs to 31 bits. 472For process-virtual PMCs, the 473.Nm 474driver implements a workaround in software and makes the corrected 64 475bit count available via the 476.Ic PMC_OP_RW 477operation. 478Processes that intend to use RDPMC instructions directly or 479that intend to write values larger than 2^31 into these PMCs with 480.Ic PMC_OP_RW 481need to be aware of this hardware limitation. 482.Sh DIAGNOSTICS 483.Bl -diag 484.It hwpmc: tunable hashsize=%d must be greater than zero. 485A negative value was supplied for tunable 486.Va kern.hwpmc.hashsize . 487.It hwpmc: tunable logbuffersize=%d must be greater than zero. 488A negative value was supplied for tunable 489.Va kern.hwpmc.logbuffersize . 490.It hwpmc: tunable nlogbuffers=%d must be greater than zero. 491A negative value was supplied for tunable 492.Va kern.hwpmc.nlogbuffers . 493.It hwpmc: tunable nsamples=%d out of range. 494The value for tunable 495.Va kern.hwpmc.nsamples 496was negative or greater than 65535. 497.El |
|
| 413.Sh ERRORS 414An command issued to the 415.Nm 416driver may fail with the following errors: 417.Bl -tag -width Er 418.It Bq Er EBUSY 419An 420.Ic OP_CONFIGURELOG --- 141 unchanged lines hidden (view full) --- 562does not have permission to attach to. 563.It Bq Er EPERM 564.Pq "i386 and amd64 architectures" 565An 566.Ic PMC_OP_PMCATTACH 567operation was issued on a PMC whose MSR has been retrieved using 568.Ic PMC_OP_PMCX86GETMSR . 569.It Bq Er ESRCH | 498.Sh ERRORS 499An command issued to the 500.Nm 501driver may fail with the following errors: 502.Bl -tag -width Er 503.It Bq Er EBUSY 504An 505.Ic OP_CONFIGURELOG --- 141 unchanged lines hidden (view full) --- 647does not have permission to attach to. 648.It Bq Er EPERM 649.Pq "i386 and amd64 architectures" 650An 651.Ic PMC_OP_PMCATTACH 652operation was issued on a PMC whose MSR has been retrieved using 653.Ic PMC_OP_PMCX86GETMSR . 654.It Bq Er ESRCH |
| 570A process issued a PMC operation request without having allocated any PMCs. | 655A process issued a PMC operation request without having allocated any 656PMCs. |
| 571.It Bq Er ESRCH | 657.It Bq Er ESRCH |
| 658A process issued a PMC operation request after the PMC was detached 659from all of its target processes. 660.It Bq Er ESRCH |
|
| 572A 573.Ic PMC_OP_PMCATTACH 574request specified a non-existent process id. 575.It Bq Er ESRCH 576The target process for a 577.Ic PMC_OP_PMCDETACH 578operation is not being monitored by the 579.Nm 580driver. 581.El 582.Sh BUGS | 661A 662.Ic PMC_OP_PMCATTACH 663request specified a non-existent process id. 664.It Bq Er ESRCH 665The target process for a 666.Ic PMC_OP_PMCDETACH 667operation is not being monitored by the 668.Nm 669driver. 670.El 671.Sh BUGS |
| 583The kernel driver requires all CPUs in an SMP system to be symmetric 584with respect to their performance monitoring counter resources. 585.Pp | |
| 586The driver samples the state of the kernel's logical processor support 587at the time of initialization (i.e., at module load time). 588On CPUs supporting logical processors, the driver could misbehave if 589logical processors are subsequently enabled or disabled while the 590driver is active. 591.Sh SEE ALSO 592.Xr kenv 1 , 593.Xr pmc 3 , | 672The driver samples the state of the kernel's logical processor support 673at the time of initialization (i.e., at module load time). 674On CPUs supporting logical processors, the driver could misbehave if 675logical processors are subsequently enabled or disabled while the 676driver is active. 677.Sh SEE ALSO 678.Xr kenv 1 , 679.Xr pmc 3 , |
| 680.Xr kgmon 8 , |
|
| 594.Xr kldload 8 , 595.Xr pmccontrol 8 , 596.Xr pmcstat 8 , 597.Xr sysctl 8 , 598.Xr p_candebug 9 | 681.Xr kldload 8 , 682.Xr pmccontrol 8 , 683.Xr pmcstat 8 , 684.Xr sysctl 8 , 685.Xr p_candebug 9 |