1 .\" Copyright (c) 2007-2008 Joseph Koshy. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
6 .\" 1. Redistributions of source code must retain the above copyright
7 .\" notice, this list of conditions and the following disclaimer.
8 .\" 2. Redistributions in binary form must reproduce the above copyright
9 .\" notice, this list of conditions and the following disclaimer in the
10 .\" documentation and/or other materials provided with the distribution.
12 .\" This software is provided by Joseph Koshy ``as is'' and
13 .\" any express or implied warranties, including, but not limited to, the
14 .\" implied warranties of merchantability and fitness for a particular purpose
15 .\" are disclaimed. in no event shall Joseph Koshy be liable
16 .\" for any direct, indirect, incidental, special, exemplary, or consequential
17 .\" damages (including, but not limited to, procurement of substitute goods
18 .\" or services; loss of use, data, or profits; or business interruption)
19 .\" however caused and on any theory of liability, whether in contract, strict
20 .\" liability, or tort (including negligence or otherwise) arising in any way
21 .\" out of the use of this software, even if advised of the possibility of
26 .Dd September 22, 2008
32 .Nd allocate and free performance monitoring counters
39 .Fa "const char *eventspecifier"
40 .Fa "enum pmc_mode mode"
46 .Fn pmc_release "pmc_id_t pmc"
50 allocates a performance monitoring counter that measures the events
53 and writes the allocated handle to the location pointed to by argument
58 comprises an PMC event name followed by an optional comma separated
59 list of keywords and qualifiers.
60 The allowed syntax for argument
62 is processor specific and is listed in section
63 .Sx "EVENT SPECIFIERS"
68 The desired PMC mode is specified by argument
73 .Bl -tag -width ".Dv PMC_MODE_SS" -compact
75 Allocate a system-scope counting PMC.
77 Allocate a system-scope sampling PMC.
79 Allocate a process-scope counting PMC.
81 Allocate a process-scope sampling PMC.
84 Mode specific modifiers may be specified using argument
86 The flags supported at PMC allocation time are:
87 .Bl -tag -width ".Dv PMC_F_LOG_PROCEXIT" -compact
88 .It Dv PMC_F_DESCENDANTS
89 For process-scope PMCs, automatically track descendants of attached
91 .It Dv PMC_F_LOG_PROCCSW
92 For process-scope counting PMCs, generate a log event at every context
93 switch containing the incremental number of hardware events seen
94 by the process during the time it was executing on the CPU.
95 .It Dv PMC_F_LOG_PROCEXIT
96 For process-scope counting PMCs, accumulate hardware events seen
97 when the process was executing on a CPU and generate a log event
98 when an attached process exits.
100 PMCs allocated with flags
101 .Dv PMC_F_LOG_PROCCSW
103 .Dv PMC_F_LOG_PROCEXIT
104 need a log file to be configured before they are started.
106 For system scope PMCs, the argument
108 is a non-negative value that specifies the CPU number
109 that the PMC is to be allocated on.
110 Process scope PMC allocations should specify the constant
116 releases the PMC denoted by argument
119 If successful, function
121 sets the location specified by argument
123 to the handle of the allocated PMC and returns 0.
124 In case of an error, the function returns -1 and sets the global
127 to indicate the error.
137 had an invalid value.
143 had an invalid CPU number.
147 contained flags that were unsupported or otherwise incompatible with
148 the requested PMC mode.
154 specified an event not supported by hardware or contained a syntax
159 requested the use of a hardware resource that was absent or
160 administratively disabled.
162 The underlying hardware does not support the capabilities needed for
163 a PMC being allocated by a call to
166 A system scope PMC allocation was attempted without adequate process
171 was called without first having allocated a PMC.
177 did not specify a PMC previously allocated by this process.
182 .Xr pmc_configure_logfile 3 ,