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 THE AUTHOR AND CONTRIBUTORS ``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 THE AUTHOR OR CONTRIBUTORS 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
32 .Nd allocate and free performance monitoring counters
39 .Fa "const char *eventspecifier"
40 .Fa "enum pmc_mode mode"
47 .Fn pmc_release "pmc_id_t pmc"
51 allocates a performance monitoring counter that measures the events
54 and writes the allocated handle to the location pointed to by argument
59 comprises an PMC event name followed by an optional comma separated
60 list of keywords and qualifiers.
61 The allowed syntax for argument
63 is processor specific and is listed in section
64 .Sx "EVENT SPECIFIERS"
69 The desired PMC mode is specified by argument
74 .Bl -tag -width ".Dv PMC_MODE_SS" -compact
76 Allocate a system-scope counting PMC.
78 Allocate a system-scope sampling PMC.
80 Allocate a process-scope counting PMC.
82 Allocate a process-scope sampling PMC.
85 Mode specific modifiers may be specified using argument
87 The flags supported at PMC allocation time are:
88 .Bl -tag -width ".Dv PMC_F_LOG_PROCEXIT" -compact
89 .It Dv PMC_F_DESCENDANTS
90 For process-scope PMCs, automatically track descendants of attached
92 .It Dv PMC_F_LOG_PROCCSW
93 For process-scope counting PMCs, generate a log event at every context
94 switch containing the incremental number of hardware events seen
95 by the process during the time it was executing on the CPU.
96 .It Dv PMC_F_LOG_PROCEXIT
97 For process-scope counting PMCs, accumulate hardware events seen
98 when the process was executing on a CPU and generate a log event
99 when an attached process exits.
101 PMCs allocated with flags
102 .Dv PMC_F_LOG_PROCCSW
104 .Dv PMC_F_LOG_PROCEXIT
105 need a log file to be configured before they are started.
107 For system scope PMCs, the argument
109 is a non-negative value that specifies the CPU number
110 that the PMC is to be allocated on.
111 Process scope PMC allocations should specify the constant
117 argument behaves identically to the
124 specifies the initial value of the allocated PMC.
127 specifies the reload count.
131 releases the PMC denoted by argument
134 If successful, function
136 sets the location specified by argument
138 to the handle of the allocated PMC and returns 0.
139 In case of an error, the function returns -1 and sets the global
142 to indicate the error.
152 had an invalid value.
158 had an invalid CPU number.
162 contained flags that were unsupported or otherwise incompatible with
163 the requested PMC mode.
169 specified an event not supported by hardware or contained a syntax
174 requested the use of a hardware resource that was absent or
175 administratively disabled.
177 The underlying hardware does not support the capabilities needed for
178 a PMC being allocated by a call to
181 A system scope PMC allocation was attempted without adequate process
186 was called without first having allocated a PMC.
192 did not specify a PMC previously allocated by this process.
197 .Xr pmc_configure_logfile 3 ,