Performance Monitor

The Performance Monitor component provides APIs to use ESP32-S3 internal performance counters to profile functions and applications.

Application Example

An example which combines performance monitor is provided in examples/system/perfmon directory. This example initializes the performance monitor structure and execute them with printing the statistics.

High level API Reference

API Reference

Functions

esp_err_t xtensa_perfmon_init(int id, uint16_t select, uint16_t mask, int kernelcnt, int tracelevel)

Init Performance Monitoor.

Initialize performance monitor register with define values

Return

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if one of the arguments is not correct

Parameters

  • [in] id: performance counter number

  • [in] select: select value from PMCTRLx register

  • [in] mask: mask value from PMCTRLx register

  • [in] kernelcnt: kernelcnt value from PMCTRLx register

  • [in] tracelevel: tracelevel value from PMCTRLx register

esp_err_t xtensa_perfmon_reset(int id)

Reset PM counter.

Reset PM counter. Writes 0 to the PMx register.

Return

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if id out of range

Parameters

  • [in] id: performance counter number

void xtensa_perfmon_start(void)

Start PM counters.

Start all PM counters synchronously. Write 1 to the PGM register

void xtensa_perfmon_stop(void)

Stop PM counters.

Stop all PM counters synchronously. Write 0 to the PGM register

uint32_t xtensa_perfmon_value(int id)

Read PM counter.

Read value of defined PM counter.

Return

  • Performance counter value

Parameters

  • [in] id: performance counter number

esp_err_t xtensa_perfmon_overflow(int id)

Read PM overflow state.

Read overflow value of defined PM counter.

Return

  • ESP_OK if there is no overflow (overflow = 0)

  • ESP_FAIL if overflow occure (overflow = 1)

Parameters

  • [in] id: performance counter number

void xtensa_perfmon_dump(void)

Dump PM values.

Dump all PM register to the console.

Functions

esp_err_t xtensa_perfmon_exec(const xtensa_perfmon_config_t *config)

Execute PM.

Execute performance counter for dedicated function with defined parameters

Return

  • ESP_OK if no errors

  • ESP_ERR_INVALID_ARG if one of the required parameters not defined

  • ESP_FAIL - counter overflow

Parameters

  • [in] config: pointer to the configuration structure

void xtensa_perfmon_view_cb(void *params, uint32_t select, uint32_t mask, uint32_t value)

Dump PM results.

Callback to dump perfmon result to a FILE* stream specified in perfmon_config_t::callback_params. If callback_params is set to NULL, will print to stdout

Parameters

  • [in] params: used parameters passed from configuration (callback_params). This parameter expected as FILE* hanle, where data will be stored. If this parameter NULL, then data will be stored to the stdout.

  • [in] select: select value for current counter

  • [in] mask: mask value for current counter

  • [in] value: counter value for current counter

Structures

struct xtensa_perfmon_config

Performance monitor configuration structure.

Structure to configure performance counter to measure dedicated function

Public Members

int repeat_count

how much times function will be called before the calback will be repeated

float max_deviation

Difference between min and max counter number 0..1, 0 - no difference, 1 - not used

void *call_params

This pointer will be passed to the call_function as a parameter

void (*call_function)(void *params)

pointer to the function that have to be called

void (*callback)(void *params, uint32_t select, uint32_t mask, uint32_t value)

pointer to the function that will be called with result parameters

void *callback_params

parameter that will be passed to the callback

int tracelevel

trace level for all counters. In case of negative value, the filter will be ignored. If it’s >=0, then the perfmon will count only when interrupt level > tracelevel. It’s useful to monitor interrupts.

uint32_t counters_size

amount of counter in the list

const uint32_t *select_mask

list of the select/mask parameters

Type Definitions

typedef struct xtensa_perfmon_config xtensa_perfmon_config_t

Performance monitor configuration structure.

Structure to configure performance counter to measure dedicated function

Provide feedback about this document