Documentation/trace/coresight/coresight-etm4x-reference.rst

   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:            ``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
 609 comparator with a type used - i.e. RANGE, SINGLE, START, STOP. Once this tag
 610 is set, then only the values can be changed using the same sysfs file / type
 611 used to program it.
 612
 613 Thus::
 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
 624 To remove programming on all the comparators (and all the other hardware) use
 625 the reset parameter::
 626
 627   % echo 1 > reset
 628
 629
 630
 631 The ‘mode’ sysfs parameter.
 632 ---------------------------
 633
 634 This is a bitfield selection parameter that sets the overall trace mode for the
 635 ETM. The table below describes the bits, using the defines from the driver
 636 source file, along with a description of the feature these represent. Many
 637 features are optional and therefore dependent on implementation in the
 638 hardware.
 639
 640 Bit 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
 654 **bit (4):**
 655     ETM_MODE_BB
 656
 657 **description:**
 658     Set to enable branch broadcast if supported in hardware [IDR0].
 659
 660
 661 **bit (5):**
 662     ETMv4_MODE_CYCACC
 663
 664 **description:**
 665     Set to enable cycle accurate trace if supported [IDR0].
 666
 667
 668 **bit (6):**
 669     ETMv4_MODE_CTXID
 670
 671 **description:**
 672     Set to enable context ID tracing if supported in hardware [IDR2].
 673
 674
 675 **bit (7):**
 676     ETM_MODE_VMID
 677
 678 **description:**
 679     Set to enable virtual machine ID tracing if supported [IDR2].
 680
 681
 682 **bit (11):**
 683     ETMv4_MODE_TIMESTAMP
 684
 685 **description:**
 686     Set to enable timestamp generation if supported [IDR0].
 687
 688
 689 **bit (12):**
 690     ETM_MODE_RETURNSTACK
 691 **description:**
 692     Set to enable trace return stack use if supported [IDR0].
 693
 694
 695 **bit (13-14):**
 696     ETM_MODE_QELEM(val)
 697
 698 **description:**
 699     ‘val’ determines level of Q element support enabled if
 700     implemented by the ETM [IDR0]
 701
 702
 703 **bit (19):**
 704     ETM_MODE_ATB_TRIGGER
 705
 706 **description:**
 707     Set to enable the ATBTRIGGER bit in the event control register
 708     [EVENTCTLR1] if supported [IDR5].
 709
 710
 711 **bit (20):**
 712     ETM_MODE_LPOVERRIDE
 713
 714 **description:**
 715     Set to enable the LPOVERRIDE bit in the event control register
 716     [EVENTCTLR1], if supported [IDR5].
 717
 718
 719 **bit (21):**
 720     ETM_MODE_ISTALL_EN
 721
 722 **description:**
 723     Set to enable the ISTALL bit in the stall control register
 724     [STALLCTLR]
 725
 726
 727 **bit (23):**
 728     ETM_MODE_INSTPRIO
 729
 730 **description:**
 731               Set to enable the INSTPRIORITY bit in the stall control register
 732               [STALLCTLR] , if supported [IDR0].
 733
 734
 735 **bit (24):**
 736     ETM_MODE_NOOVERFLOW
 737
 738 **description:**
 739     Set to enable the NOOVERFLOW bit in the stall control register
 740     [STALLCTLR], if supported [IDR3].
 741
 742
 743 **bit (25):**
 744     ETM_MODE_TRACE_RESET
 745
 746 **description:**
 747     Set to enable the TRCRESET bit in the viewinst control register
 748     [VICTLR] , if supported [IDR3].
 749
 750
 751 **bit (26):**
 752     ETM_MODE_TRACE_ERR
 753
 754 **description:**
 755     Set to enable the TRCCTRL bit in the viewinst control register
 756     [VICTLR].
 757
 758
 759 **bit (27):**
 760     ETM_MODE_VIEWINST_STARTSTOP
 761
 762 **description:**
 763     Set the initial state value of the ViewInst start / stop logic
 764     in the viewinst control register [VICTLR]
 765
 766
 767 **bit (30):**
 768     ETM_MODE_EXCL_KERN
 769
 770 **description:**
 771     Set default trace setup to exclude kernel mode trace (see note a)
 772
 773
 774 **bit (31):**
 775     ETM_MODE_EXCL_USER
 776
 777 **description:**
 778     Set default trace setup to exclude user space trace (see note a)
 779
 780 ----
 781
 782 *Note a)* On startup the ETM is programmed to trace the complete address space
 783 using address range comparator 0. ‘mode’ bits 30 / 31 modify this setting to
 784 set EL exclude bits for NS state in either user space (EL0) or kernel space
 785 (EL1) in the address range comparator. (the default setting excludes all
 786 secure EL, and NS EL2)
 787
 788 Once the reset parameter has been used, and/or custom programming has been
 789 implemented - using these bits will result in the EL bits for address
 790 comparator 0 being set in the same way.
 791
 792 *Note b)* Bits 2-3, 8-10, 15-16, 18, 22, control features that only work with
 793 data trace. As A-profile data trace is architecturally prohibited in ETMv4,
 794 these have been omitted here. Possible uses could be where a kernel has
 795 support for control of R or M profile infrastructure as part of a heterogeneous
 796 system.
 797
 798 Bits 17, 28-29 are unused.