1| Supported Targets | ESP32 | ESP32-S2 | ESP32-S3 |
2| ----------------- | ----- | -------- | -------- |
3
4# Performance Monitor (`perfmon`) example
5
6(See the README.md file in the upper level 'examples' directory for more information about examples.)
7
8## Overview
9This example illustrates usage of `perfmon` APIs to monitor and profile functions.
10The example will calculate performance statistic for simple test function.
11The simple test function could be exchanged to one from the user.
12
13The example contain test function that will be executed with perfmon component and collect CPU statistic. The test function will be executed 200 times in each test case. The first test case collect statistic from all available performance counters, and second test just from defined in the list.
14
15## How to use example
16
17### Hardware Required
18
19Example should be able to run on any commonly available ESP32, ESP32-S2 or ESP32-S3 development board. `perfmon` component isn't supported on Espressif chips with RISC-V CPU architecture.
20
21### Build and Flash
22
23```
24idf.py build flash monitor
25```
26
27(To exit the serial monitor, type ``Ctrl-]``.)
28
29See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.
30
31## Example Output
32
331. Example starts and calls the first test. This test calls the test function `exec_test_function` 200 times and collects all CPU performance metrics.
34
35    <details><summary>Example log output:</summary>
36
37    ```
38    I (288) example: Start
39    I (288) example: Start test with printing all available statistic
40    Value =       750, select =  0, mask = 0001.  Counts cycles.
41                      Amount of cycles
42    Value =         0, select =  1, mask = 0001.  Overflow of counter.
43                      Overflow counter
44    Value =         0, select =  2, mask = 0001.  Successfully Retired Instructions.
45
46                      JX instructions
47    Value =         0, select =  2, mask = 0002.  Successfully Retired Instructions.
48
49                      CALLXn instructions
50    Value =         3, select =  2, mask = 0004.  Successfully Retired Instructions.
51
52                      return instructions (RET, RETW, ...)
53    Value =         0, select =  2, mask = 0008.  Successfully Retired Instructions.
54
55                      supervisor return instructions (RFDE, RFE, RFI, RFWO, RFWU)
56    Value =       100, select =  2, mask = 0010.  Successfully Retired Instructions.
57
58                      Conditional branch instructions where execution
59                      transfers to the target (aka. taken branch),
60                       or loopgtz/loopnez instr where execution skips
61                       the loop (aka. not-taken loop)
62    Value =         0, select =  2, mask = 0020.  Successfully Retired Instructions.
63
64                      J instr
65    Value =         1, select =  2, mask = 0040.  Successfully Retired Instructions.
66
67                      CALLn instr
68    Value =         0, select =  2, mask = 0080.  Successfully Retired Instructions.
69
70                      Conditional branch instr where execution
71                       falls through (aka. not-taken branch)
72    Value =         0, select =  2, mask = 0100.  Successfully Retired Instructions.
73
74                      Loop instr where execution falls into loop (aka. taken loop)
75    Value =         0, select =  2, mask = 0400.  Successfully Retired Instructions.
76
77                      Last inst of loop and execution transfers
78                       to LBEG (aka. loopback taken)
79    Value =         0, select =  2, mask = 0800.  Successfully Retired Instructions.
80
81                      Last inst of loop and execution falls
82                       through to LEND (aka. loopback fallthrough)
83    Value =       309, select =  2, mask = 8000.  Successfully Retired Instructions.
84
85                      Non-branch instr (aka. non-CTI)
86    Value =         0, select =  3, mask = 0002.  Data-related GlobalStall cycles.
87                      Store buffer full stall
88    Value =         0, select =  3, mask = 0004.  Data-related GlobalStall cycles.
89                      Store buffer conflict stall
90    Value =         0, select =  3, mask = 0008.  Data-related GlobalStall cycles.
91                      Data Cache-miss stall (unused)
92    Value =         0, select =  3, mask = 0010.  Data-related GlobalStall cycles.
93                      Data RAM/ROM/XLMI busy stall
94    Value =         0, select =  3, mask = 0020.  Data-related GlobalStall cycles.
95                      Data inbound-PIF request stall (includes s32c1i)
96    Value =         0, select =  3, mask = 0040.  Data-related GlobalStall cycles.
97                      MHT lookup stall
98    Value =         0, select =  3, mask = 0080.  Data-related GlobalStall cycles.
99                      Uncached load stall (included in MHT lookup stall below)
100    Value =         0, select =  3, mask = 0100.  Data-related GlobalStall cycles.
101                      Bank-conflict stall
102    Value =         0, select =  4, mask = 0001.  Instruction-related and Other Glob
103    alStall cycles.
104                      ICache-miss stall
105    Value =         0, select =  4, mask = 0002.  Instruction-related and Other Glob
106    alStall cycles.
107                      Instruction RAM/ROM busy stall
108    Value =         0, select =  4, mask = 0004.  Instruction-related and Other Glob
109    alStall cycles.
110                      Instruction RAM inbound-PIF request stall
111    Value =         0, select =  4, mask = 0008.  Instruction-related and Other Glob
112    alStall cycles.
113                      TIE port stall
114    Value =         0, select =  4, mask = 0010.  Instruction-related and Other Glob
115    alStall cycles.
116                      External RunStall signal status
117    Value =         0, select =  4, mask = 0020.  Instruction-related and Other Glob
118    alStall cycles.
119                      Uncached fetch stall
120    Value =         1, select =  4, mask = 0040.  Instruction-related and Other Glob
121    alStall cycles.
122                      FastL32R stall
123    Value =         0, select =  4, mask = 0080.  Instruction-related and Other Glob
124    alStall cycles.
125                      Iterative multiply stall
126    Value =         0, select =  4, mask = 0100.  Instruction-related and Other Glob
127    alStall cycles.
128                      Iterative divide stall
129    Value =         0, select =  5, mask = 0001.  Exceptions and Pipeline Replays.
130                      Other Pipeline Replay (i.e. excludes cache miss etc.)
131    Value =         0, select =  5, mask = 0002.  Exceptions and Pipeline Replays.
132                      Level-1 interrupt
133    Value =         0, select =  5, mask = 0004.  Exceptions and Pipeline Replays.
134                      Greater-than-level-1 interrupt
135    Value =         0, select =  5, mask = 0008.  Exceptions and Pipeline Replays.
136                      Debug exception
137    Value =         0, select =  5, mask = 0010.  Exceptions and Pipeline Replays.
138                      NMI
139    Value =         0, select =  5, mask = 0020.  Exceptions and Pipeline Replays.
140                      Window exception
141    Value =         0, select =  5, mask = 0040.  Exceptions and Pipeline Replays.
142                      Allocate exception
143    Value =         0, select =  5, mask = 0080.  Exceptions and Pipeline Replays.
144                      Other exceptions
145    Value =         0, select =  5, mask = 0100.  Exceptions and Pipeline Replays.
146                      HW-corrected memory error
147    Value =         0, select =  6, mask = 0001.  Hold and Other Bubble cycles.
148                      Processor domain PSO bubble
149    Value =         0, select =  6, mask = 0004.  Hold and Other Bubble cycles.
150                      R hold caused by Data Cache miss(unused)
151    Value =         0, select =  6, mask = 0008.  Hold and Other Bubble cycles.
152                      R hold caused by Store release
153    Value =         0, select =  6, mask = 0010.  Hold and Other Bubble cycles.
154                      R hold caused by register dependency
155    Value =         0, select =  6, mask = 0020.  Hold and Other Bubble cycles.
156                      R hold caused by MEMW, EXTW or EXCW
157    Value =         0, select =  6, mask = 0040.  Hold and Other Bubble cycles.
158                      R hold caused by Halt instruction (TX only)
159    Value =       322, select =  6, mask = 0080.  Hold and Other Bubble cycles.
160                      CTI bubble (e.g. branch delay slot)
161    Value =         0, select =  6, mask = 0100.  Hold and Other Bubble cycles.
162                      WAITI bubble i.e. a cycle spent in WaitI power down mode.
163    Value =       417, select =  7, mask = 0001.  Instruction TLB Accesses (per inst
164    ruction retiring).
165                      ITLB Hit
166    Value =         0, select =  7, mask = 0002.  Instruction TLB Accesses (per inst
167    ruction retiring).
168                      Replay of instruction due to ITLB miss
169    Value =         0, select =  7, mask = 0004.  Instruction TLB Accesses (per inst
170    ruction retiring).
171                      HW-assisted TLB Refill completes
172    Value =         0, select =  7, mask = 0008.  Instruction TLB Accesses (per inst
173    ruction retiring).
174                      ITLB Miss Exception
175    Value =         0, select =  8, mask = 0001.  Instruction Memory Accesses (per i
176    nstruction retiring).
177                      Instruction Cache Hit
178    Value =         0, select =  8, mask = 0002.  Instruction Memory Accesses (per i
179    nstruction retiring).
180                      Instruction Cache Miss
181    Value =       420, select =  8, mask = 0004.  Instruction Memory Accesses (per i
182    nstruction retiring).
183                      All InstRAM or InstROM accesses
184    Value =         0, select =  8, mask = 0008.  Instruction Memory Accesses (per i
185    nstruction retiring).
186                      Bypass (i.e. uncached) fetch
187    Value =         3, select =  9, mask = 0001.  Data TLB Accesses.
188                      DTLB Hit
189    Value =         0, select =  9, mask = 0002.  Data TLB Accesses.
190                      Replay of load/store due to DTLB miss
191    Value =         0, select =  9, mask = 0004.  Data TLB Accesses.
192                      HW-assisted TLB Refill completes
193    Value =         0, select =  9, mask = 0008.  Data TLB Accesses.
194                      DTLB Miss Exception
195    Value =         0, select = 10, mask = 0001.  Load Instruction (Data Memory).
196                      Data Cache Hit(unused)
197    Value =         0, select = 10, mask = 0002.  Load Instruction (Data Memory).
198                      Data Cache Miss(unused)
199    Value =         3, select = 10, mask = 0004.  Load Instruction (Data Memory).
200                      Load from local memory i.e. DataRAM, DataROM, InstRAM, InstROM
201
202    Value =         0, select = 10, mask = 0008.  Load Instruction (Data Memory).
203                      Bypass (i.e. uncached) load
204    Value =         0, select = 13, mask = 0001.  Load Instruction (Data Memory).
205                      Data Cache Hit(unused)
206    Value =         0, select = 13, mask = 0002.  Load Instruction (Data Memory).
207                      Data Cache Miss(unused)
208    Value =         0, select = 13, mask = 0004.  Load Instruction (Data Memory).
209                      Load from local memory i.e. DataRAM, DataROM, InstRAM, InstROM
210
211    Value =         0, select = 13, mask = 0008.  Load Instruction (Data Memory).
212                      Bypass (i.e. uncached) load
213    Value =         0, select = 16, mask = 0001.  Load Instruction (Data Memory).
214                      Data Cache Hit (unused)
215    Value =         0, select = 16, mask = 0002.  Load Instruction (Data Memory).
216                      Data Cache Miss (unused)
217    Value =         0, select = 16, mask = 0004.  Load Instruction (Data Memory).
218                      Load from local memory i.e. DataRAM, DataROM, InstRAM, InstROM
219
220    Value =         0, select = 16, mask = 0008.  Load Instruction (Data Memory).
221                      Bypass (i.e. uncached) load
222    Value =         0, select = 11, mask = 0001.  Store Instruction (Data Memory).
223                      Data Cache Hit (unused)
224    Value =         0, select = 11, mask = 0002.  Store Instruction (Data Memory).
225                      Data Cache Miss (unused)
226    Value =         0, select = 11, mask = 0004.  Store Instruction (Data Memory).
227                      Store to local memory i.e. DataRAM, InstRAM
228    Value =         0, select = 11, mask = 0008.  Store Instruction (Data Memory).
229                      PIF Store
230    Value =         0, select = 14, mask = 0001.  Store Instruction (Data Memory).
231                      Data Cache Hit(unused)
232    Value =         0, select = 14, mask = 0002.  Store Instruction (Data Memory).
233                      Data Cache Miss(unused)
234    Value =         0, select = 14, mask = 0004.  Store Instruction (Data Memory).
235                      Store to local memory i.e. DataRAM, InstRAM
236    Value =         0, select = 14, mask = 0008.  Store Instruction (Data Memory).
237                      PIF Store
238    Value =         0, select = 17, mask = 0001.  Store Instruction (Data Memory).
239                      Data Cache Hit (unused)
240    Value =         0, select = 17, mask = 0002.  Store Instruction (Data Memory).
241                      Data Cache Miss (unused)
242    Value =         0, select = 17, mask = 0004.  Store Instruction (Data Memory).
243                      Store to local memory i.e. DataRAM, InstRAM
244    Value =         0, select = 17, mask = 0008.  Store Instruction (Data Memory).
245                      PIF Store
246    Value =         0, select = 12, mask = 0001.  Accesses to Data Memory (Load, Sto
247    re, S32C1I, ...).
248                      Cache Miss
249    Value =         0, select = 15, mask = 0001.  Accesses to Data Memory (Load, Sto
250    re, S32C1I, ...).
251                      Cache Miss
252    Value =         0, select = 18, mask = 0001.  Accesses to Data Memory (Load, Sto
253    re, S32C1I, ...).
254                      Cache Miss
255    Value =       415, select = 22, mask = 0001.  Multiple Load/Store.
256                      0 stores and 0 loads
257    Value =         3, select = 22, mask = 0002.  Multiple Load/Store.
258                      0 stores and 1 loads
259    Value =         0, select = 22, mask = 0004.  Multiple Load/Store.
260                      1 stores and 0 loads
261    Value =         0, select = 22, mask = 0008.  Multiple Load/Store.
262                      1 stores and 1 loads
263    Value =         0, select = 22, mask = 0010.  Multiple Load/Store.
264                      0 stores and 2 loads
265    Value =         0, select = 22, mask = 0020.  Multiple Load/Store.
266                      2 stores and 0 loads
267    Value =         0, select = 23, mask = 0001.  Outbound PIF.
268                      Castout
269    Value =         0, select = 23, mask = 0002.  Outbound PIF.
270                      Prefetch
271    Value =         0, select = 24, mask = 0001.  Inbound PIF.
272                      Data DMA
273    Value =         0, select = 24, mask = 0002.  Inbound PIF.
274                      Instruction DMA
275    Value =         0, select = 26, mask = 0001.  Prefetch.
276                      I prefetch-buffer-lookup hit
277    Value =         0, select = 26, mask = 0002.  Prefetch.
278                      D prefetch-buffer-lookup hit
279    Value =         0, select = 26, mask = 0004.  Prefetch.
280                      I prefetch-buffer-lookup miss
281    Value =         0, select = 26, mask = 0008.  Prefetch.
282                      D prefetch-buffer-lookup miss
283    Value =         0, select = 26, mask = 0020.  Prefetch.
284                      Direct fill to (L1) Data Cache (unused)
285    Value =         0, select = 27, mask = 0001.  iDMA.
286                      active cycles
287    Value =         0, select = 28, mask = 0001.  Length of Instructions.
288                      16-bit
289    Value =         0, select = 28, mask = 0002.  Length of Instructions.
290                      24-bit
291    Value =         0, select = 28, mask = 0004.  Length of Instructions.
292                      32-bit
293    Value =         0, select = 28, mask = 0008.  Length of Instructions.
294                      40-bit
295    Value =         0, select = 28, mask = 0010.  Length of Instructions.
296                      48-bit
297    Value =         0, select = 28, mask = 0020.  Length of Instructions.
298                      56-bit
299    Value =         0, select = 28, mask = 0040.  Length of Instructions.
300                      64-bit
301    Value =         0, select = 28, mask = 0080.  Length of Instructions.
302                      72-bit
303    Value =         0, select = 28, mask = 0100.  Length of Instructions.
304                      80-bit
305    Value =         0, select = 28, mask = 0200.  Length of Instructions.
306                      88-bit
307    Value =         0, select = 28, mask = 0400.  Length of Instructions.
308                      96-bit
309    Value =         0, select = 28, mask = 0800.  Length of Instructions.
310                      104-bit
311    Value =         0, select = 28, mask = 1000.  Length of Instructions.
312                      112-bit
313    Value =         0, select = 28, mask = 2000.  Length of Instructions.
314                      120-bit
315    Value =         0, select = 28, mask = 4000.  Length of Instructions.
316                      128-bit
317    ```
318    </details>
319
3202. Example calls the second test, which runs the same function under tests. This time, a user-provided list of metrics is measured.
321
322    <details><summary>Example log output:</summary>
323
324    ```
325    I (1588) example: Start test with user defined statistic
326    Value =       743, select =  0, mask = 0001.  Counts cycles.
327                      Amount of cycles
328    Value =       417, select =  2, mask = 8dff.  Successfully Retired Instructions.
329
330                      JX instructions
331                      CALLXn instructions
332                      return instructions (RET, RETW, ...)
333                      supervisor return instructions (RFDE, RFE, RFI, RFWO, RFWU)
334                      Conditional branch instructions where execution
335                      transfers to the target (aka. taken branch),
336                       or loopgtz/loopnez instr where execution skips
337                       the loop (aka. not-taken loop)
338                      J instr
339                      CALLn instr
340                      Conditional branch instr where execution
341                       falls through (aka. not-taken branch)
342                      Loop instr where execution falls into loop (aka. taken loop)
343                      Last inst of loop and execution transfers
344                       to LBEG (aka. loopback taken)
345                      Last inst of loop and execution falls
346                       through to LEND (aka. loopback fallthrough)
347                      Non-branch instr (aka. non-CTI)
348    Value =         3, select = 10, mask = 0004.  Load Instruction (Data Memory).
349                      Load from local memory i.e. DataRAM, DataROM, InstRAM, InstROM
350
351    Value =         0, select = 11, mask = 0004.  Store Instruction (Data Memory).
352                      Store to local memory i.e. DataRAM, InstRAM
353    Value =       321, select =  6, mask = 01ed.  Hold and Other Bubble cycles.
354                      Processor domain PSO bubble
355                      R hold caused by Data Cache miss(unused)
356                      R hold caused by Store release
357                      R hold caused by MEMW, EXTW or EXCW
358                      R hold caused by Halt instruction (TX only)
359                      CTI bubble (e.g. branch delay slot)
360                      WAITI bubble i.e. a cycle spent in WaitI power down mode.
361    Value =         0, select =  6, mask = 0010.  Hold and Other Bubble cycles.
362                      R hold caused by register dependency
363    Value =         0, select =  1, mask = 0001.  Overflow of counter.
364                      Overflow counter
365    I (1788) example: The End
366
367    ```
368    </details>
369