Performance Monitor¶
The Performance Monitor component provides APIs to use ESP32 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.
API Reference¶
Header File¶
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
id
: performance counter numberselect
: select value from PMCTRLx registermask
: mask value from PMCTRLx registerkernelcnt
: kernelcnt value from PMCTRLx registertracelevel
: 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
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
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
id
: performance counter number
-
void
xtensa_perfmon_dump
(void)¶ Dump PM values.
Dump all PM register to the console.
Header File¶
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
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
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.select
: select value for current countermask
: mask value for current countervalue
: 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
-
int
Type Definitions¶
-
typedef struct xtensa_perfmon_config
xtensa_perfmon_config_t
¶ Performance monitor configuration structure.
Structure to configure performance counter to measure dedicated function