README.md
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
