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