FreeBSD manual
download PDF document: pmc_allocate.3.pdf
PMC_ALLOCATE(3) FreeBSD Library Functions Manual PMC_ALLOCATE(3)
NAME
pmc_allocate, pmc_release - allocate and free performance monitoring
counters
LIBRARY
Performance Counters Library (libpmc, -lpmc)
SYNOPSIS
#include <pmc.h>
int
pmc_allocate(const char *eventspecifier, enum pmc_mode mode,
uint32_t flags, int cpu, pmc_id_t *pmcid, uint64_t count);
int
pmc_release(pmc_id_t pmc);
DESCRIPTION
Function pmc_allocate() allocates a performance monitoring counter that
measures the events named by argument eventspecifier, and writes the
allocated handle to the location pointed to by argument pmcid.
Argument eventspecifier comprises an PMC event name followed by an
optional comma separated list of keywords and qualifiers. The allowed
syntax for argument eventspecifier is processor specific and is listed in
section EVENT SPECIFIERS in the pmc(3) manual page.
The desired PMC mode is specified by argument mode. Legal values for the
mode argument are:
PMC_MODE_SC Allocate a system-scope counting PMC.
PMC_MODE_SS Allocate a system-scope sampling PMC.
PMC_MODE_TC Allocate a process-scope counting PMC.
PMC_MODE_TS Allocate a process-scope sampling PMC.
Mode specific modifiers may be specified using argument flags. The flags
supported at PMC allocation time are:
PMC_F_DESCENDANTS For process-scope PMCs, automatically track
descendants of attached processes.
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.
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.
PMCs allocated with flags PMC_F_LOG_PROCCSW and PMC_F_LOG_PROCEXIT need a
log file to be configured before they are started.
For system scope PMCs, the argument 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 PMC_CPU_ANY for this
argument.
The count argument behaves identically to the pmc_set(3) function's value
argument. For counting PMCs, count specifies the initial value of the
allocated PMC. For sampling PMCs, count specifies the reload count.
to indicate the error.
The pmc_release() function returns the value 0 if successful; otherwise
the value -1 is returned and the global variable errno is set to indicate
the error.
ERRORS
[EINVAL] The argument mode to function pmc_allocate() had an
invalid value.
[EINVAL] Argument cpu to function pmc_allocate() had an invalid
CPU number.
[EINVAL] Argument flags contained flags that were unsupported
or otherwise incompatible with the requested PMC mode.
[EINVAL] Argument eventspecifier to function pmc_allocate()
specified an event not supported by hardware or
contained a syntax error.
[ENXIO] Function pmc_allocate() requested the use of a
hardware resource that was absent or administratively
disabled.
[EOPNOTSUPP] The underlying hardware does not support the
capabilities needed for a PMC being allocated by a
call to pmc_allocate().
[EPERM] A system scope PMC allocation was attempted without
adequate process privilege.
[ESRCH] Function pmc_release() was called without first having
allocated a PMC.
[EINVAL] Argument pmcid to function pmc_release() did not
specify a PMC previously allocated by this process.
SEE ALSO
pmc(3), pmc_attach(3), pmc_configure_logfile(3), pmc_start(3), hwpmc(4)
FreeBSD 14.0-RELEASE-p11 April 21, 2021 FreeBSD 14.0-RELEASE-p11