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