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 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 783using address range comparator 0. ‘mode’ bits 30 / 31 modify this setting to 784set 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 786secure EL, and NS EL2) 787 788Once the reset parameter has been used, and/or custom programming has been 789implemented - using these bits will result in the EL bits for address 790comparator 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 793data trace. As A-profile data trace is architecturally prohibited in ETMv4, 794these have been omitted here. Possible uses could be where a kernel has 795support for control of R or M profile infrastructure as part of a heterogeneous 796system. 797 798Bits 17, 28-29 are unused. 799