185 lines
5.1 KiB
Groff
185 lines
5.1 KiB
Groff
.\" Copyright (c) 2007 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 Joseph Koshy ``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 Joseph Koshy 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 November 20, 2007
|
|
.Os
|
|
.Dt PMC_ALLOCATE 3
|
|
.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"
|
|
.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
|
|
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 previously
|
|
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
|