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: ``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 623comparator with a type used - i.e. RANGE, SINGLE, START, STOP. Once this tag 624is set, then only the values can be changed using the same sysfs file / type 625used to program it. 626 627Thus:: 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 638To remove programming on all the comparators (and all the other hardware) use 639the reset parameter:: 640 641 % echo 1 > reset 642 643 644 645The ‘mode’ sysfs parameter. 646--------------------------- 647 648This is a bitfield selection parameter that sets the overall trace mode for the 649ETM. The table below describes the bits, using the defines from the driver 650source file, along with a description of the feature these represent. Many 651features are optional and therefore dependent on implementation in the 652hardware. 653 654Bit 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 inteded 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 812using address range comparator 0. ‘mode’ bits 30 / 31 modify this setting to 813set 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 815secure EL, and NS EL2) 816 817Once the reset parameter has been used, and/or custom programming has been 818implemented - using these bits will result in the EL bits for address 819comparator 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 822data trace. As A-profile data trace is architecturally prohibited in ETMv4, 823these have been omitted here. Possible uses could be where a kernel has 824support for control of R or M profile infrastructure as part of a heterogeneous 825system. 826 827Bits 17, 28-29 are unused. 828