pmc_allocate(3) manual page

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.

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

[`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.

Manual Pages — PMC_ALLOCATE

NAME

CONTENTS

LIBRARY

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

`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.

`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.