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);

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.

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.

Function pmc_release() releases the PMC denoted by argument pmcid.

RETURN VALUES

If successful, function pmc_allocate() sets the location specified by argument 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 errno 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)