50f6c13997
This was added in b2ca2e50b9, and serves to provide an initial value
to the PMC, eliminating the need for a second syscall via pmc_set(3).
Reviewed by: gnn, 0mp (manpages)
MFC after: 1 week
Sponsored by: The FreeBSD Foundation
Differential Revision: https://reviews.freebsd.org/D29885
200 lines
5.4 KiB
Groff
200 lines
5.4 KiB
Groff
.\" Copyright (c) 2007-2008 Joseph Koshy. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd April 21, 2021
|
|
.Dt PMC_ALLOCATE 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pmc_allocate ,
|
|
.Nm pmc_release
|
|
.Nd allocate and free performance monitoring counters
|
|
.Sh LIBRARY
|
|
.Lb libpmc
|
|
.Sh SYNOPSIS
|
|
.In pmc.h
|
|
.Ft int
|
|
.Fo pmc_allocate
|
|
.Fa "const char *eventspecifier"
|
|
.Fa "enum pmc_mode mode"
|
|
.Fa "uint32_t flags"
|
|
.Fa "int cpu"
|
|
.Fa "pmc_id_t *pmcid"
|
|
.Fa "uint64_t count"
|
|
.Fc
|
|
.Ft int
|
|
.Fn pmc_release "pmc_id_t pmc"
|
|
.Sh DESCRIPTION
|
|
Function
|
|
.Fn pmc_allocate
|
|
allocates a performance monitoring counter that measures the events
|
|
named by argument
|
|
.Fa eventspecifier ,
|
|
and writes the allocated handle to the location pointed to by argument
|
|
.Fa pmcid .
|
|
.Pp
|
|
Argument
|
|
.Fa eventspecifier
|
|
comprises an PMC event name followed by an optional comma separated
|
|
list of keywords and qualifiers.
|
|
The allowed syntax for argument
|
|
.Fa eventspecifier
|
|
is processor specific and is listed in section
|
|
.Sx "EVENT SPECIFIERS"
|
|
in the
|
|
.Xr pmc 3
|
|
manual page.
|
|
.Pp
|
|
The desired PMC mode is specified by argument
|
|
.Fa mode .
|
|
Legal values for the
|
|
.Fa mode
|
|
argument are:
|
|
.Bl -tag -width ".Dv PMC_MODE_SS" -compact
|
|
.It Dv PMC_MODE_SC
|
|
Allocate a system-scope counting PMC.
|
|
.It Dv PMC_MODE_SS
|
|
Allocate a system-scope sampling PMC.
|
|
.It Dv PMC_MODE_TC
|
|
Allocate a process-scope counting PMC.
|
|
.It Dv PMC_MODE_TS
|
|
Allocate a process-scope sampling PMC.
|
|
.El
|
|
.Pp
|
|
Mode specific modifiers may be specified using argument
|
|
.Fa flags .
|
|
The flags supported at PMC allocation time are:
|
|
.Bl -tag -width ".Dv PMC_F_LOG_PROCEXIT" -compact
|
|
.It Dv PMC_F_DESCENDANTS
|
|
For process-scope PMCs, automatically track descendants of attached
|
|
processes.
|
|
.It Dv PMC_F_LOG_PROCCSW
|
|
For process-scope counting PMCs, generate a log event at every context
|
|
switch containing the incremental number of hardware events seen
|
|
by the process during the time it was executing on the CPU.
|
|
.It Dv PMC_F_LOG_PROCEXIT
|
|
For process-scope counting PMCs, accumulate hardware events seen
|
|
when the process was executing on a CPU and generate a log event
|
|
when an attached process exits.
|
|
.El
|
|
PMCs allocated with flags
|
|
.Dv PMC_F_LOG_PROCCSW
|
|
and
|
|
.Dv PMC_F_LOG_PROCEXIT
|
|
need a log file to be configured before they are started.
|
|
.Pp
|
|
For system scope PMCs, the argument
|
|
.Fa cpu
|
|
is a non-negative value that specifies the CPU number
|
|
that the PMC is to be allocated on.
|
|
Process scope PMC allocations should specify the constant
|
|
.Dv PMC_CPU_ANY
|
|
for this argument.
|
|
.Pp
|
|
The
|
|
.Fa count
|
|
argument behaves identically to the
|
|
.Xr pmc_set 3
|
|
function's
|
|
.Fa value
|
|
argument.
|
|
For counting PMCs,
|
|
.Fa count
|
|
specifies the initial value of the allocated PMC.
|
|
For sampling PMCs,
|
|
.Fa count
|
|
specifies the reload count.
|
|
.Pp
|
|
Function
|
|
.Fn pmc_release
|
|
releases the PMC denoted by argument
|
|
.Fa pmcid .
|
|
.Sh RETURN VALUES
|
|
If successful, function
|
|
.Fn pmc_allocate
|
|
sets the location specified by argument
|
|
.Fa pmcid
|
|
to the handle of the allocated PMC and returns 0.
|
|
In case of an error, the function returns -1 and sets the global
|
|
variable
|
|
.Va errno
|
|
to indicate the error.
|
|
.Pp
|
|
.Rv -std pmc_release
|
|
.Sh ERRORS
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The argument
|
|
.Fa mode
|
|
to function
|
|
.Fn pmc_allocate
|
|
had an invalid value.
|
|
.It Bq Er EINVAL
|
|
Argument
|
|
.Fa cpu
|
|
to function
|
|
.Fn pmc_allocate
|
|
had an invalid CPU number.
|
|
.It Bq Er EINVAL
|
|
Argument
|
|
.Fa flags
|
|
contained flags that were unsupported or otherwise incompatible with
|
|
the requested PMC mode.
|
|
.It Bq Er EINVAL
|
|
Argument
|
|
.Fa eventspecifier
|
|
to function
|
|
.Fn pmc_allocate
|
|
specified an event not supported by hardware or contained a syntax
|
|
error.
|
|
.It Bq Er ENXIO
|
|
Function
|
|
.Fn pmc_allocate
|
|
requested the use of a hardware resource that was absent or
|
|
administratively disabled.
|
|
.It Bq Er EOPNOTSUPP
|
|
The underlying hardware does not support the capabilities needed for
|
|
a PMC being allocated by a call to
|
|
.Fn pmc_allocate .
|
|
.It Bq Er EPERM
|
|
A system scope PMC allocation was attempted without adequate process
|
|
privilege.
|
|
.It Bq Er ESRCH
|
|
Function
|
|
.Fn pmc_release
|
|
was called without first having allocated a PMC.
|
|
.It Bq Er EINVAL
|
|
Argument
|
|
.Fa pmcid
|
|
to function
|
|
.Fn pmc_release
|
|
did not specify a PMC previously allocated by this process.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr pmc 3 ,
|
|
.Xr pmc_attach 3 ,
|
|
.Xr pmc_configure_logfile 3 ,
|
|
.Xr pmc_start 3 ,
|
|
.Xr hwpmc 4
|