# Performance Monitor

[中文]

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

## Application Examples

- system/perfmon demonstrates how to use the perfmon APIs to monitor and profile functions.

## High-Level API Reference

### Header Files

- perfmon/include/perfmon.h

## API Reference

### Header File

- components/perfmon/include/xtensa_perfmon_access.h

- This header file can be included with:

  >     #include "xtensa_perfmon_access.h"

- This header file is a part of the API provided by the `perfmon` component. To declare that your component depends on `perfmon`, add the following to your CMakeLists.txt:

  >     REQUIRES perfmon

  > or

  >     PRIV_REQUIRES perfmon

### 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

  Parameters:

    - id -- [in] performance counter number

    - select -- [in] select value from PMCTRLx register

    - mask -- [in] mask value from PMCTRLx register

    - kernelcnt -- [in] kernelcnt value from PMCTRLx register

    - tracelevel -- [in] tracelevel value from PMCTRLx register

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if one of the arguments is not correct

esp_err_t xtensa_perfmon_reset(int id)

  Reset PM counter.

  Reset PM counter. Writes 0 to the PMx register.

  Parameters:

    id -- [in] performance counter number

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if id out of range

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.

  Parameters:

    id -- [in] performance counter number

  Returns:

    - Performance counter value

esp_err_t xtensa_perfmon_overflow(int id)

  Read PM overflow state.

  Read overflow value of defined PM counter.

  Parameters:

    id -- [in] performance counter number

  Returns:

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

    - ESP_FAIL if overflow occure (overflow = 1)

void xtensa_perfmon_dump(void)

  Dump PM values.

  Dump all PM register to the console.

### Header File

- components/perfmon/include/xtensa_perfmon_apis.h

- This header file can be included with:

  >     #include "xtensa_perfmon_apis.h"

- This header file is a part of the API provided by the `perfmon` component. To declare that your component depends on `perfmon`, add the following to your CMakeLists.txt:

  >     REQUIRES perfmon

  > or

  >     PRIV_REQUIRES perfmon

### Functions

esp_err_t xtensa_perfmon_exec(const xtensa_perfmon_config_t *config)

  Execute PM.

  Execute performance counter for dedicated function with defined parameters

  Parameters:

    config -- [in] pointer to the configuration structure

  Returns:

    - ESP_OK if no errors

    - ESP_ERR_INVALID_ARG if one of the required parameters not defined

    - ESP_FAIL - counter overflow

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 -- [in] used parameters passed from configuration (callback_params). This parameter is expected to be a FILE* handle, where data will be stored. If this parameter NULL, then data will be stored to the stdout.

    - select -- [in] select value for current counter

    - mask -- [in] mask value for current counter

    - value -- [in] 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 callback 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

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.