PMU

Data Structures
struct	pmu_counter_config
	PMU counter configuration entry. More...

Macros
#define	PMU_MAX_COUNTERS   8
	Maximum number of logical event counters this API can describe.

Functions
int	pmu_init (void)
	Initialize the PMU for the current logical CPU.
uint32_t	pmu_num_counters (void)
void	pmu_get_info (pmu_info_t *info)
	Fill info with PMU identification for the current logical CPU.
int	pmu_counter_config (uint32_t counter, pmu_evt_t event)
	Map hardware event counter counter to architectural event event.
void	pmu_counter_enable (uint32_t counter)
	Enable counting on hardware event counter counter.
void	pmu_counter_disable (uint32_t counter)
	Disable counting on hardware event counter counter.
void	pmu_counter_enable_all (void)
	Enable all implemented event counters (and the cycle counter where applicable).
void	pmu_counter_disable_all (void)
	Disable all event counters (and the cycle counter where applicable).
uint64_t	pmu_counter_read (uint32_t counter)
	Read the current value of hardware event counter counter.
void	pmu_counter_reset (uint32_t counter)
	Reset hardware event counter counter to zero.
void	pmu_counter_reset_all (void)
	Reset all hardware event counters to zero (implementation-defined; may include cycle counter policies).
uint64_t	pmu_cycle_count (void)
	Read the architectural cycle count register (if implemented).
void	pmu_cycle_reset (void)
	Reset the cycle count register to zero (implementation-defined).
void	pmu_start (void)
	Start counting: enable the PMU globally (implementation-defined).
void	pmu_stop (void)
	Stop counting: disable the PMU globally (implementation-defined).
bool	pmu_counter_overflow (uint32_t counter)
	Return whether hardware event counter counter has overflowed since the flag was cleared.
void	pmu_counter_clear_overflow (uint32_t counter)
	Clear the overflow flag for hardware event counter counter.

Detailed Description

Macro Definition Documentation

PMU_MAX_COUNTERS

#define PMU_MAX_COUNTERS   8

#include <zephyr/arch/pmu.h>

Maximum number of logical event counters this API can describe.

A given backend may implement fewer active hardware counters.

Function Documentation

pmu_counter_clear_overflow()

void pmu_counter_clear_overflow

(

uint32_t

counter

)

#include <zephyr/arch/pmu.h>

Clear the overflow flag for hardware event counter counter.

Parameters

counter

Event counter index [0, pmu_num_counters()).

pmu_counter_config()

int pmu_counter_config	(	uint32_t	counter,
		pmu_evt_t	event )

#include <zephyr/arch/pmu.h>

Map hardware event counter counter to architectural event event.

Parameters

counter	Event counter index in the range [0, pmu_num_counters()).
event	Event selector (pmu_evt_t from the architecture supplement when present).

Returns

0 on success, negative errno on failure

pmu_counter_disable()

void pmu_counter_disable

(

uint32_t

counter

)

#include <zephyr/arch/pmu.h>

Disable counting on hardware event counter counter.

Parameters

counter

Event counter index [0, pmu_num_counters()).

pmu_counter_disable_all()

void pmu_counter_disable_all

(

void

)

#include <zephyr/arch/pmu.h>

Disable all event counters (and the cycle counter where applicable).

pmu_counter_enable()

void pmu_counter_enable

(

uint32_t

counter

)

#include <zephyr/arch/pmu.h>

Enable counting on hardware event counter counter.

Parameters

counter

Event counter index [0, pmu_num_counters()).

pmu_counter_enable_all()

void pmu_counter_enable_all

(

void

)

#include <zephyr/arch/pmu.h>

Enable all implemented event counters (and the cycle counter where applicable).

pmu_counter_overflow()

bool pmu_counter_overflow

(

uint32_t

counter

)

#include <zephyr/arch/pmu.h>

Return whether hardware event counter counter has overflowed since the flag was cleared.

Parameters

counter

Event counter index [0, pmu_num_counters()).

Returns

true if overflow is pending, false otherwise or if PMU is unavailable

pmu_counter_read()

uint64_t pmu_counter_read

(

uint32_t

counter

)

#include <zephyr/arch/pmu.h>

Read the current value of hardware event counter counter.

Parameters

counter

Event counter index [0, pmu_num_counters()).

Returns

Counter value, or 0 if PMU is unavailable or counter is out of range

pmu_counter_reset()

void pmu_counter_reset

(

uint32_t

counter

)

#include <zephyr/arch/pmu.h>

Reset hardware event counter counter to zero.

Parameters

counter

Event counter index [0, pmu_num_counters()).

pmu_counter_reset_all()

void pmu_counter_reset_all

(

void

)

#include <zephyr/arch/pmu.h>

Reset all hardware event counters to zero (implementation-defined; may include cycle counter policies).

pmu_cycle_count()

uint64_t pmu_cycle_count

(

void

)

#include <zephyr/arch/pmu.h>

Read the architectural cycle count register (if implemented).

Returns

Cycle count, or 0 if unavailable

pmu_cycle_reset()

void pmu_cycle_reset

(

void

)

#include <zephyr/arch/pmu.h>

Reset the cycle count register to zero (implementation-defined).

pmu_get_info()

void pmu_get_info

(

pmu_info_t *

info

)

#include <zephyr/arch/pmu.h>

Fill info with PMU identification for the current logical CPU.

info must not be NULL. Fields are only meaningful after a successful pmu_init on this CPU; contents are backend-defined (see arch pmu_info_t).

pmu_init()

int pmu_init

(

void

)

#include <zephyr/arch/pmu.h>

Initialize the PMU for the current logical CPU.

Architecture-neutral interface for hardware performance counters. Backends implement these functions for each supported architecture (for example ARMv8-A PMUv3 on AArch64, future ARMv8-R / Cortex-R52, RISC-V HPM CSRs, etc.).

Architectural event codes are defined by the architecture supplement (for example pmu_evt_t in <zephyr/arch/arm64/pmuv3.h> when CONFIG_ARM64 is enabled).

PMU is not initialized during kernel startup. Call pmu_init() before other pmu_*() functions on this CPU.

Call once per logical CPU that will use counters, before any other pmu_*() API on that CPU. Idempotent on success: later calls return 0 if this CPU already initialized successfully, or -ENOTSUP if this CPU recorded that no PMU is available.

PMU control and counters are per-CPU. On SMP, use the PMU only while running on the intended CPU — for example pin the thread with k_thread_cpu_pin() (requires CONFIG_SCHED_CPU_MASK), or constrain its CPU affinity with k_thread_cpu_mask_enable() / k_thread_cpu_mask_disable(), so it does not migrate during a measurement.

There is no SYS_INIT hook; callers choose when to probe (for example at the start of a benchmark).

Return values

0	Success
-ENOTSUP	No PMU or not usable at this exception level on this CPU

pmu_num_counters()

uint32_t pmu_num_counters

(

void

)

#include <zephyr/arch/pmu.h>

Returns

Number of event counters on this CPU, or 0 if PMU unavailable

pmu_start()

void pmu_start

(

void

)

#include <zephyr/arch/pmu.h>

Start counting: enable the PMU globally (implementation-defined).

pmu_stop()

void pmu_stop

(

void

)

#include <zephyr/arch/pmu.h>

Stop counting: disable the PMU globally (implementation-defined).