1 ===============================================
2 ETMv4 sysfs linux driver programming reference.
3 ===============================================
4
5 :Author: Mike Leach <mike.leach@linaro.org>
6 :Date: October 11th, 2019
7
8 Supplement to existing ETMv4 driver documentation.
9
10 Sysfs files and directories
11 ---------------------------
12
13 Root: ``/sys/bus/coresight/devices/etm<N>``
14
15
16 The following paragraphs explain the association between sysfs files and the
17 ETMv4 registers that they effect. Note the register names are given without
18 the ‘TRC’ prefix.
19
20 ----
21
22 :File: ``mode`` (rw)
23 :Trace Registers: {CONFIGR + others}
24 :Notes:
25 Bit select trace features. See ‘mode’ section below. Bits
26 in this will cause equivalent programming of trace config and
27 other registers to enable the features requested.
28
29 :Syntax & eg:
30 ``echo bitfield > mode``
31
32 bitfield up to 32 bits setting trace features.
33
34 :Example:
35 ``$> echo 0x012 > mode``
36
37 ----
38
39 :File: ``reset`` (wo)
40 :Trace Registers: All
41 :Notes:
42 Reset all programming to trace nothing / no logic programmed.
43
44 :Syntax:
45 ``echo 1 > reset``
46
47 ----
48
49 :File: ``enable_source`` (wo)
50 :Trace Registers: PRGCTLR, All hardware regs.
51 :Notes:
52 - > 0 : Programs up the hardware with the current values held in the driver
53 and enables trace.
54
55 - = 0 : disable trace hardware.
56
57 :Syntax:
58 ``echo 1 > enable_source``
59
60 ----
61
62 :File: ``cpu`` (ro)
63 :Trace Registers: None.
64 :Notes:
65 CPU ID that this ETM is attached to.
66
67 :Example:
68 ``$> cat cpu``
69
70 ``$> 0``
71
72 ----
73
74 :File: ``ts_source`` (ro)
75 :Trace Registers: None.
76 :Notes:
77 When FEAT_TRF is implemented, value of TRFCR_ELx.TS used for trace session. Otherwise -1
78 indicates an unknown time source. Check trcidr0.tssize to see if a global timestamp is
79 available.
80
81 :Example:
82 ``$> cat ts_source``
83
84 ``$> 1``
85
86 ----
87
88 :File: ``addr_idx`` (rw)
89 :Trace Registers: None.
90 :Notes:
91 Virtual register to index address comparator and range
92 features. Set index for first of the pair in a range.
93
94 :Syntax:
95 ``echo idx > addr_idx``
96
97 Where idx < nr_addr_cmp x 2
98
99 ----
100
101 :File: ``addr_range`` (rw)
102 :Trace Registers: ACVR[idx, idx+1], VIIECTLR
103 :Notes:
104 Pair of addresses for a range selected by addr_idx. Include
105 / exclude according to the optional parameter, or if omitted
106 uses the current ‘mode’ setting. Select comparator range in
107 control register. Error if index is odd value.
108
109 :Depends: ``mode, addr_idx``
110 :Syntax:
111 ``echo addr1 addr2 [exclude] > addr_range``
112
113 Where addr1 and addr2 define the range and addr1 < addr2.
114
115 Optional exclude value:-
116
117 - 0 for include
118 - 1 for exclude.
119 :Example:
120 ``$> echo 0x0000 0x2000 0 > addr_range``
121
122 ----
123
124 :File: ``addr_single`` (rw)
125 :Trace Registers: ACVR[idx]
126 :Notes:
127 Set a single address comparator according to addr_idx. This
128 is used if the address comparator is used as part of event
129 generation logic etc.
130
131 :Depends: ``addr_idx``
132 :Syntax:
133 ``echo addr1 > addr_single``
134
135 ----
136
137 :File: ``addr_start`` (rw)
138 :Trace Registers: ACVR[idx], VISSCTLR
139 :Notes:
140 Set a trace start address comparator according to addr_idx.
141 Select comparator in control register.
142
143 :Depends: ``addr_idx``
144 :Syntax:
145 ``echo addr1 > addr_start``
146
147 ----
148
149 :File: ``addr_stop`` (rw)
150 :Trace Registers: ACVR[idx], VISSCTLR
151 :Notes:
152 Set a trace stop address comparator according to addr_idx.
153 Select comparator in control register.
154
155 :Depends: ``addr_idx``
156 :Syntax:
157 ``echo addr1 > addr_stop``
158
159 ----
160
161 :File: ``addr_context`` (rw)
162 :Trace Registers: ACATR[idx,{6:4}]
163 :Notes:
164 Link context ID comparator to address comparator addr_idx
165
166 :Depends: ``addr_idx``
167 :Syntax:
168 ``echo ctxt_idx > addr_context``
169
170 Where ctxt_idx is the index of the linked context id / vmid
171 comparator.
172
173 ----
174
175 :File: ``addr_ctxtype`` (rw)
176 :Trace Registers: ACATR[idx,{3:2}]
177 :Notes:
178 Input value string. Set type for linked context ID comparator
179
180 :Depends: ``addr_idx``
181 :Syntax:
182 ``echo type > addr_ctxtype``
183
184 Type one of {all, vmid, ctxid, none}
185 :Example:
186 ``$> echo ctxid > addr_ctxtype``
187
188 ----
189
190 :File: ``addr_exlevel_s_ns`` (rw)
191 :Trace Registers: ACATR[idx,{14:8}]
192 :Notes:
193 Set the ELx secure and non-secure matching bits for the
194 selected address comparator
195
196 :Depends: ``addr_idx``
197 :Syntax:
198 ``echo val > addr_exlevel_s_ns``
199
200 val is a 7 bit value for exception levels to exclude. Input
201 value shifted to correct bits in register.
202 :Example:
203 ``$> echo 0x4F > addr_exlevel_s_ns``
204
205 ----
206
207 :File: ``addr_instdatatype`` (rw)
208 :Trace Registers: ACATR[idx,{1:0}]
209 :Notes:
210 Set the comparator address type for matching. Driver only
211 supports setting instruction address type.
212
213 :Depends: ``addr_idx``
214
215 ----
216
217 :File: ``addr_cmp_view`` (ro)
218 :Trace Registers: ACVR[idx, idx+1], ACATR[idx], VIIECTLR
219 :Notes:
220 Read the currently selected address comparator. If part of
221 address range then display both addresses.
222
223 :Depends: ``addr_idx``
224 :Syntax:
225 ``cat addr_cmp_view``
226 :Example:
227 ``$> cat addr_cmp_view``
228
229 ``addr_cmp[0] range 0x0 0xffffffffffffffff include ctrl(0x4b00)``
230
231 ----
232
233 :File: ``nr_addr_cmp`` (ro)
234 :Trace Registers: From IDR4
235 :Notes:
236 Number of address comparator pairs
237
238 ----
239
240 :File: ``sshot_idx`` (rw)
241 :Trace Registers: None
242 :Notes:
243 Select single shot register set.
244
245 ----
246
247 :File: ``sshot_ctrl`` (rw)
248 :Trace Registers: SSCCR[idx]
249 :Notes:
250 Access a single shot comparator control register.
251
252 :Depends: ``sshot_idx``
253 :Syntax:
254 ``echo val > sshot_ctrl``
255
256 Writes val into the selected control register.
257
258 ----
259
260 :File: ``sshot_status`` (ro)
261 :Trace Registers: SSCSR[idx]
262 :Notes:
263 Read a single shot comparator status register
264
265 :Depends: ``sshot_idx``
266 :Syntax:
267 ``cat sshot_status``
268
269 Read status.
270 :Example:
271 ``$> cat sshot_status``
272
273 ``0x1``
274
275 ----
276
277 :File: ``sshot_pe_ctrl`` (rw)
278 :Trace Registers: SSPCICR[idx]
279 :Notes:
280 Access a single shot PE comparator input control register.
281
282 :Depends: ``sshot_idx``
283 :Syntax:
284 ``echo val > sshot_pe_ctrl``
285
286 Writes val into the selected control register.
287
288 ----
289
290 :File: ``ns_exlevel_vinst`` (rw)
291 :Trace Registers: VICTLR{23:20}
292 :Notes:
293 Program non-secure exception level filters. Set / clear NS
294 exception filter bits. Setting ‘1’ excludes trace from the
295 exception level.
296
297 :Syntax:
298 ``echo bitfield > ns_exlevel_viinst``
299
300 Where bitfield contains bits to set clear for EL0 to EL2
301 :Example:
302 ``%> echo 0x4 > ns_exlevel_viinst``
303
304 Excludes EL2 NS trace.
305
306 ----
307
308 :File: ``vinst_pe_cmp_start_stop`` (rw)
309 :Trace Registers: VIPCSSCTLR
310 :Notes:
311 Access PE start stop comparator input control registers
312
313 ----
314
315 :File: ``bb_ctrl`` (rw)
316 :Trace Registers: BBCTLR
317 :Notes:
318 Define ranges that Branch Broadcast will operate in.
319 Default (0x0) is all addresses.
320
321 :Depends: BB enabled.
322
323 ----
324
325 :File: ``cyc_threshold`` (rw)
326 :Trace Registers: CCCTLR
327 :Notes:
328 Set the threshold for which cycle counts will be emitted.
329 Error if attempt to set below minimum defined in IDR3, masked
330 to width of valid bits.
331
332 :Depends: CC enabled.
333
334 ----
335
336 :File: ``syncfreq`` (rw)
337 :Trace Registers: SYNCPR
338 :Notes:
339 Set trace synchronisation period. Power of 2 value, 0 (off)
340 or 8-20. Driver defaults to 12 (every 4096 bytes).
341
342 ----
343
344 :File: ``cntr_idx`` (rw)
345 :Trace Registers: none
346 :Notes:
347 Select the counter to access
348
349 :Syntax:
350 ``echo idx > cntr_idx``
351
352 Where idx < nr_cntr
353
354 ----
355
356 :File: ``cntr_ctrl`` (rw)
357 :Trace Registers: CNTCTLR[idx]
358 :Notes:
359 Set counter control value.
360
361 :Depends: ``cntr_idx``
362 :Syntax:
363 ``echo val > cntr_ctrl``
364
365 Where val is per ETMv4 spec.
366
367 ----
368
369 :File: ``cntrldvr`` (rw)
370 :Trace Registers: CNTRLDVR[idx]
371 :Notes:
372 Set counter reload value.
373
374 :Depends: ``cntr_idx``
375 :Syntax:
376 ``echo val > cntrldvr``
377
378 Where val is per ETMv4 spec.
379
380 ----
381
382 :File: ``nr_cntr`` (ro)
383 :Trace Registers: From IDR5
384
385 :Notes:
386 Number of counters implemented.
387
388 ----
389
390 :File: ``ctxid_idx`` (rw)
391 :Trace Registers: None
392 :Notes:
393 Select the context ID comparator to access
394
395 :Syntax:
396 ``echo idx > ctxid_idx``
397
398 Where idx < numcidc
399
400 ----
401
402 :File: ``ctxid_pid`` (rw)
403 :Trace Registers: CIDCVR[idx]
404 :Notes:
405 Set the context ID comparator value
406
407 :Depends: ``ctxid_idx``
408
409 ----
410
411 :File: ``ctxid_masks`` (rw)
412 :Trace Registers: CIDCCTLR0, CIDCCTLR1, CIDCVR<0-7>
413 :Notes:
414 Pair of values to set the byte masks for 1-8 context ID
415 comparators. Automatically clears masked bytes to 0 in CID
416 value registers.
417
418 :Syntax:
419 ``echo m3m2m1m0 [m7m6m5m4] > ctxid_masks``
420
421 32 bit values made up of mask bytes, where mN represents a
422 byte mask value for Context ID comparator N.
423
424 Second value not required on systems that have fewer than 4
425 context ID comparators
426
427 ----
428
429 :File: ``numcidc`` (ro)
430 :Trace Registers: From IDR4
431 :Notes:
432 Number of Context ID comparators
433
434 ----
435
436 :File: ``vmid_idx`` (rw)
437 :Trace Registers: None
438 :Notes:
439 Select the VM ID comparator to access.
440
441 :Syntax:
442 ``echo idx > vmid_idx``
443
444 Where idx < numvmidc
445
446 ----
447
448 :File: ``vmid_val`` (rw)
449 :Trace Registers: VMIDCVR[idx]
450 :Notes:
451 Set the VM ID comparator value
452
453 :Depends: ``vmid_idx``
454
455 ----
456
457 :File: ``vmid_masks`` (rw)
458 :Trace Registers: VMIDCCTLR0, VMIDCCTLR1, VMIDCVR<0-7>
459 :Notes:
460 Pair of values to set the byte masks for 1-8 VM ID comparators.
461 Automatically clears masked bytes to 0 in VMID value registers.
462
463 :Syntax:
464 ``echo m3m2m1m0 [m7m6m5m4] > vmid_masks``
465
466 Where mN represents a byte mask value for VMID comparator N.
467 Second value not required on systems that have fewer than 4
468 VMID comparators.
469
470 ----
471
472 :File: ``numvmidc`` (ro)
473 :Trace Registers: From IDR4
474 :Notes:
475 Number of VMID comparators
476
477 ----
478
479 :File: ``res_idx`` (rw)
480 :Trace Registers: None.
481 :Notes:
482 Select the resource selector control to access. Must be 2 or
483 higher as selectors 0 and 1 are hardwired.
484
485 :Syntax:
486 ``echo idx > res_idx``
487
488 Where 2 <= idx < nr_resource x 2
489
490 ----
491
492 :File: ``res_ctrl`` (rw)
493 :Trace Registers: RSCTLR[idx]
494 :Notes:
495 Set resource selector control value. Value per ETMv4 spec.
496
497 :Depends: ``res_idx``
498 :Syntax:
499 ``echo val > res_cntr``
500
501 Where val is per ETMv4 spec.
502
503 ----
504
505 :File: ``nr_resource`` (ro)
506 :Trace Registers: From IDR4
507 :Notes:
508 Number of resource selector pairs
509
510 ----
511
512 :File: ``event`` (rw)
513 :Trace Registers: EVENTCTRL0R
514 :Notes:
515 Set up to 4 implemented event fields.
516
517 :Syntax:
518 ``echo ev3ev2ev1ev0 > event``
519
520 Where evN is an 8 bit event field. Up to 4 event fields make up the
521 32-bit input value. Number of valid fields is implementation dependent,
522 defined in IDR0.
523
524 ----
525
526 :File: ``event_instren`` (rw)
527 :Trace Registers: EVENTCTRL1R
528 :Notes:
529 Choose events which insert event packets into trace stream.
530
531 :Depends: EVENTCTRL0R
532 :Syntax:
533 ``echo bitfield > event_instren``
534
535 Where bitfield is up to 4 bits according to number of event fields.
536
537 ----
538
539 :File: ``event_ts`` (rw)
540 :Trace Registers: TSCTLR
541 :Notes:
542 Set the event that will generate timestamp requests.
543
544 :Depends: ``TS activated``
545 :Syntax:
546 ``echo evfield > event_ts``
547
548 Where evfield is an 8 bit event selector.
549
550 ----
551
552 :File: ``seq_idx`` (rw)
553 :Trace Registers: None
554 :Notes:
555 Sequencer event register select - 0 to 2
556
557 ----
558
559 :File: ``seq_state`` (rw)
560 :Trace Registers: SEQSTR
561 :Notes:
562 Sequencer current state - 0 to 3.
563
564 ----
565
566 :File: ``seq_event`` (rw)
567 :Trace Registers: SEQEVR[idx]
568 :Notes:
569 State transition event registers
570
571 :Depends: ``seq_idx``
572 :Syntax:
573 ``echo evBevF > seq_event``
574
575 Where evBevF is a 16 bit value made up of two event selectors,
576
577 - evB : back
578 - evF : forwards.
579
580 ----
581
582 :File: ``seq_reset_event`` (rw)
583 :Trace Registers: SEQRSTEVR
584 :Notes:
585 Sequencer reset event
586
587 :Syntax:
588 ``echo evfield > seq_reset_event``
589
590 Where evfield is an 8 bit event selector.
591
592 ----
593
594 :File: ``nrseqstate`` (ro)
595 :Trace Registers: From IDR5
596 :Notes:
597 Number of sequencer states (0 or 4)
598
599 ----
600
601 :File: ``nr_pe_cmp`` (ro)
602 :Trace Registers: From IDR4
603 :Notes:
604 Number of PE comparator inputs
605
606 ----
607
608 :File: ``nr_ext_inp`` (ro)
609 :Trace Registers: From IDR5
610 :Notes:
611 Number of external inputs
612
613 ----
614
615 :File: ``nr_ss_cmp`` (ro)
616 :Trace Registers: From IDR4
617 :Notes:
618 Number of Single Shot control registers
619
620 ----
621
622 *Note:* When programming any address comparator the driver will tag the
623 comparator with a type used - i.e. RANGE, SINGLE, START, STOP. Once this tag
624 is set, then only the values can be changed using the same sysfs file / type
625 used to program it.
626
627 Thus::
628
629 % echo 0 > addr_idx ; select address comparator 0
630 % echo 0x1000 0x5000 0 > addr_range ; set address range on comparators 0, 1.
631 % echo 0x2000 > addr_start ; error as comparator 0 is a range comparator
632 % echo 2 > addr_idx ; select address comparator 2
633 % echo 0x2000 > addr_start ; this is OK as comparator 2 is unused.
634 % echo 0x3000 > addr_stop ; error as comparator 2 set as start address.
635 % echo 2 > addr_idx ; select address comparator 3
636 % echo 0x3000 > addr_stop ; this is OK
637
638 To remove programming on all the comparators (and all the other hardware) use
639 the reset parameter::
640
641 % echo 1 > reset
642
643
644
645 The ‘mode’ sysfs parameter.
646 ---------------------------
647
648 This is a bitfield selection parameter that sets the overall trace mode for the
649 ETM. The table below describes the bits, using the defines from the driver
650 source file, along with a description of the feature these represent. Many
651 features are optional and therefore dependent on implementation in the
652 hardware.
653
654 Bit assignments shown below:-
655
656 ----
657
658 **bit (0):**
659 ETM_MODE_EXCLUDE
660
661 **description:**
662 This is the default value for the include / exclude function when
663 setting address ranges. Set 1 for exclude range. When the mode
664 parameter is set this value is applied to the currently indexed
665 address range.
666
667 .. _coresight-branch-broadcast:
668
669 **bit (4):**
670 ETM_MODE_BB
671
672 **description:**
673 Set to enable branch broadcast if supported in hardware [IDR0]. The primary use for this feature
674 is when code is patched dynamically at run time and the full program flow may not be able to be
675 reconstructed using only conditional branches.
676
677 There is currently no support in Perf for supplying modified binaries to the decoder, so this
678 feature is only intended to be used for debugging purposes or with a 3rd party tool.
679
680 Choosing this option will result in a significant increase in the amount of trace generated -
681 possible danger of overflows, or fewer instructions covered. Note, that this option also
682 overrides any setting of :ref:`ETM_MODE_RETURNSTACK <coresight-return-stack>`, so where a branch
683 broadcast range overlaps a return stack range, return stacks will not be available for that
684 range.
685
686 .. _coresight-cycle-accurate:
687
688 **bit (5):**
689 ETMv4_MODE_CYCACC
690
691 **description:**
692 Set to enable cycle accurate trace if supported [IDR0].
693
694
695 **bit (6):**
696 ETMv4_MODE_CTXID
697
698 **description:**
699 Set to enable context ID tracing if supported in hardware [IDR2].
700
701
702 **bit (7):**
703 ETM_MODE_VMID
704
705 **description:**
706 Set to enable virtual machine ID tracing if supported [IDR2].
707
708 .. _coresight-timestamp:
709
710 **bit (11):**
711 ETMv4_MODE_TIMESTAMP
712
713 **description:**
714 Set to enable timestamp generation if supported [IDR0].
715
716 .. _coresight-return-stack:
717
718 **bit (12):**
719 ETM_MODE_RETURNSTACK
720 **description:**
721 Set to enable trace return stack use if supported [IDR0].
722
723
724 **bit (13-14):**
725 ETM_MODE_QELEM(val)
726
727 **description:**
728 ‘val’ determines level of Q element support enabled if
729 implemented by the ETM [IDR0]
730
731
732 **bit (19):**
733 ETM_MODE_ATB_TRIGGER
734
735 **description:**
736 Set to enable the ATBTRIGGER bit in the event control register
737 [EVENTCTLR1] if supported [IDR5].
738
739
740 **bit (20):**
741 ETM_MODE_LPOVERRIDE
742
743 **description:**
744 Set to enable the LPOVERRIDE bit in the event control register
745 [EVENTCTLR1], if supported [IDR5].
746
747
748 **bit (21):**
749 ETM_MODE_ISTALL_EN
750
751 **description:**
752 Set to enable the ISTALL bit in the stall control register
753 [STALLCTLR]
754
755
756 **bit (23):**
757 ETM_MODE_INSTPRIO
758
759 **description:**
760 Set to enable the INSTPRIORITY bit in the stall control register
761 [STALLCTLR] , if supported [IDR0].
762
763
764 **bit (24):**
765 ETM_MODE_NOOVERFLOW
766
767 **description:**
768 Set to enable the NOOVERFLOW bit in the stall control register
769 [STALLCTLR], if supported [IDR3].
770
771
772 **bit (25):**
773 ETM_MODE_TRACE_RESET
774
775 **description:**
776 Set to enable the TRCRESET bit in the viewinst control register
777 [VICTLR] , if supported [IDR3].
778
779
780 **bit (26):**
781 ETM_MODE_TRACE_ERR
782
783 **description:**
784 Set to enable the TRCCTRL bit in the viewinst control register
785 [VICTLR].
786
787
788 **bit (27):**
789 ETM_MODE_VIEWINST_STARTSTOP
790
791 **description:**
792 Set the initial state value of the ViewInst start / stop logic
793 in the viewinst control register [VICTLR]
794
795
796 **bit (30):**
797 ETM_MODE_EXCL_KERN
798
799 **description:**
800 Set default trace setup to exclude kernel mode trace (see note a)
801
802
803 **bit (31):**
804 ETM_MODE_EXCL_USER
805
806 **description:**
807 Set default trace setup to exclude user space trace (see note a)
808
809 ----
810
811 *Note a)* On startup the ETM is programmed to trace the complete address space
812 using address range comparator 0. ‘mode’ bits 30 / 31 modify this setting to
813 set EL exclude bits for NS state in either user space (EL0) or kernel space
814 (EL1) in the address range comparator. (the default setting excludes all
815 secure EL, and NS EL2)
816
817 Once the reset parameter has been used, and/or custom programming has been
818 implemented - using these bits will result in the EL bits for address
819 comparator 0 being set in the same way.
820
821 *Note b)* Bits 2-3, 8-10, 15-16, 18, 22, control features that only work with
822 data trace. As A-profile data trace is architecturally prohibited in ETMv4,
823 these have been omitted here. Possible uses could be where a kernel has
824 support for control of R or M profile infrastructure as part of a heterogeneous
825 system.
826
827 Bits 17, 28-29 are unused.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.