FreeBSD Manual Pages
PMC_ALLOCATE(3) FreeBSD Library Functions Manual PMC_ALLOCATE(3) NAME pmc_allocate, pmc_release -- allocate and free performance monitoring counters LIBRARY Performance Monitoring Counters Interface 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 al- located handle to the location pointed to by argument pmcid. Argument eventspecifier comprises an PMC event name followed by an op- tional comma separated list of keywords and qualifiers. The allowed syn- tax 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 descen- dants 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 ex- its. 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. RETURN VALUES If successful, function pmc_allocate() sets the location specified by ar- gument 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 con- tained a syntax error. [ENXIO] Function pmc_allocate() requested the use of a hard- ware resource that was absent or administratively dis- abled. [EOPNOTSUPP] The underlying hardware does not support the capabili- ties 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 spec- ify a PMC previously allocated by this process. SEE ALSO pmc(3), pmc_attach(3), pmc_configure_logfile(3), pmc_start(3), hwpmc(4) FreeBSD 13.0 September 22, 2008 FreeBSD 13.0
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pmc_allocate&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>