828 lines · plain
1===============================================2ETMv4 sysfs linux driver programming reference.3===============================================4 5 :Author: Mike Leach <mike.leach@linaro.org>6 :Date: October 11th, 20197 8Supplement to existing ETMv4 driver documentation.9 10Sysfs files and directories11---------------------------12 13Root: ``/sys/bus/coresight/devices/etm<N>``14 15 16The following paragraphs explain the association between sysfs files and the17ETMv4 registers that they effect. Note the register names are given without18the ‘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. Bits26 in this will cause equivalent programming of trace config and27 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: All41: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 driver53 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 -178 indicates an unknown time source. Check trcidr0.tssize to see if a global timestamp is79 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 range92 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 298 99----100 101:File: ``addr_range`` (rw)102:Trace Registers: ACVR[idx, idx+1], VIIECTLR103:Notes:104 Pair of addresses for a range selected by addr_idx. Include105 / exclude according to the optional parameter, or if omitted106 uses the current ‘mode’ setting. Select comparator range in107 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 include118 - 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. This128 is used if the address comparator is used as part of event129 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], VISSCTLR139: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], VISSCTLR151: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_idx165 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 / vmid171 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 comparator179 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 the194 selected address comparator195 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. Input201 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 only211 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], VIIECTLR219:Notes:220 Read the currently selected address comparator. If part of221 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 IDR4235:Notes:236 Number of address comparator pairs237 238----239 240:File: ``sshot_idx`` (rw)241:Trace Registers: None242: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 register264 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 NS294 exception filter bits. Setting ‘1’ excludes trace from the295 exception level.296 297:Syntax:298 ``echo bitfield > ns_exlevel_viinst``299 300 Where bitfield contains bits to set clear for EL0 to EL2301: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: VIPCSSCTLR310:Notes:311 Access PE start stop comparator input control registers312 313----314 315:File: ``bb_ctrl`` (rw)316:Trace Registers: BBCTLR317: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: CCCTLR327:Notes:328 Set the threshold for which cycle counts will be emitted.329 Error if attempt to set below minimum defined in IDR3, masked330 to width of valid bits.331 332:Depends: CC enabled.333 334----335 336:File: ``syncfreq`` (rw)337:Trace Registers: SYNCPR338: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: none346:Notes:347 Select the counter to access348 349:Syntax:350 ``echo idx > cntr_idx``351 352 Where idx < nr_cntr353 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 IDR5384 385:Notes:386 Number of counters implemented.387 388----389 390:File: ``ctxid_idx`` (rw)391:Trace Registers: None392:Notes:393 Select the context ID comparator to access394 395:Syntax:396 ``echo idx > ctxid_idx``397 398 Where idx < numcidc399 400----401 402:File: ``ctxid_pid`` (rw)403:Trace Registers: CIDCVR[idx]404:Notes:405 Set the context ID comparator value406 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 ID415 comparators. Automatically clears masked bytes to 0 in CID416 value registers.417 418:Syntax:419 ``echo m3m2m1m0 [m7m6m5m4] > ctxid_masks``420 421 32 bit values made up of mask bytes, where mN represents a422 byte mask value for Context ID comparator N.423 424 Second value not required on systems that have fewer than 4425 context ID comparators426 427----428 429:File: ``numcidc`` (ro)430:Trace Registers: From IDR4431:Notes:432 Number of Context ID comparators433 434----435 436:File: ``vmid_idx`` (rw)437:Trace Registers: None438:Notes:439 Select the VM ID comparator to access.440 441:Syntax:442 ``echo idx > vmid_idx``443 444 Where idx < numvmidc445 446----447 448:File: ``vmid_val`` (rw)449:Trace Registers: VMIDCVR[idx]450:Notes:451 Set the VM ID comparator value452 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 4468 VMID comparators.469 470----471 472:File: ``numvmidc`` (ro)473:Trace Registers: From IDR4474:Notes:475 Number of VMID comparators476 477----478 479:File: ``res_idx`` (rw)480:Trace Registers: None.481:Notes:482 Select the resource selector control to access. Must be 2 or483 higher as selectors 0 and 1 are hardwired.484 485:Syntax:486 ``echo idx > res_idx``487 488 Where 2 <= idx < nr_resource x 2489 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 IDR4507:Notes:508 Number of resource selector pairs509 510----511 512:File: ``event`` (rw)513:Trace Registers: EVENTCTRL0R514: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 the521 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: EVENTCTRL1R528:Notes:529 Choose events which insert event packets into trace stream.530 531:Depends: EVENTCTRL0R532: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: TSCTLR541: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: None554:Notes:555 Sequencer event register select - 0 to 2556 557----558 559:File: ``seq_state`` (rw)560:Trace Registers: SEQSTR561: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 registers570 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 : back578 - evF : forwards.579 580----581 582:File: ``seq_reset_event`` (rw)583:Trace Registers: SEQRSTEVR584:Notes:585 Sequencer reset event586 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 IDR5596:Notes:597 Number of sequencer states (0 or 4)598 599----600 601:File: ``nr_pe_cmp`` (ro)602:Trace Registers: From IDR4603:Notes:604 Number of PE comparator inputs605 606----607 608:File: ``nr_ext_inp`` (ro)609:Trace Registers: From IDR5610:Notes:611 Number of external inputs612 613----614 615:File: ``nr_ss_cmp`` (ro)616:Trace Registers: From IDR4617:Notes:618 Number of Single Shot control registers619 620----621 622*Note:* When programming any address comparator the driver will tag the623comparator with a type used - i.e. RANGE, SINGLE, START, STOP. Once this tag624is set, then only the values can be changed using the same sysfs file / type625used to program it.626 627Thus::628 629 % echo 0 > addr_idx ; select address comparator 0630 % 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 comparator632 % echo 2 > addr_idx ; select address comparator 2633 % 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 3636 % echo 0x3000 > addr_stop ; this is OK637 638To remove programming on all the comparators (and all the other hardware) use639the reset parameter::640 641 % echo 1 > reset642 643 644 645The ‘mode’ sysfs parameter.646---------------------------647 648This is a bitfield selection parameter that sets the overall trace mode for the649ETM. The table below describes the bits, using the defines from the driver650source file, along with a description of the feature these represent. Many651features are optional and therefore dependent on implementation in the652hardware.653 654Bit assignments shown below:-655 656----657 658**bit (0):**659 ETM_MODE_EXCLUDE660 661**description:**662 This is the default value for the include / exclude function when663 setting address ranges. Set 1 for exclude range. When the mode664 parameter is set this value is applied to the currently indexed665 address range.666 667.. _coresight-branch-broadcast:668 669**bit (4):**670 ETM_MODE_BB671 672**description:**673 Set to enable branch broadcast if supported in hardware [IDR0]. The primary use for this feature674 is when code is patched dynamically at run time and the full program flow may not be able to be675 reconstructed using only conditional branches.676 677 There is currently no support in Perf for supplying modified binaries to the decoder, so this678 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 also682 overrides any setting of :ref:`ETM_MODE_RETURNSTACK <coresight-return-stack>`, so where a branch683 broadcast range overlaps a return stack range, return stacks will not be available for that684 range.685 686.. _coresight-cycle-accurate:687 688**bit (5):**689 ETMv4_MODE_CYCACC690 691**description:**692 Set to enable cycle accurate trace if supported [IDR0].693 694 695**bit (6):**696 ETMv4_MODE_CTXID697 698**description:**699 Set to enable context ID tracing if supported in hardware [IDR2].700 701 702**bit (7):**703 ETM_MODE_VMID704 705**description:**706 Set to enable virtual machine ID tracing if supported [IDR2].707 708.. _coresight-timestamp:709 710**bit (11):**711 ETMv4_MODE_TIMESTAMP712 713**description:**714 Set to enable timestamp generation if supported [IDR0].715 716.. _coresight-return-stack:717 718**bit (12):**719 ETM_MODE_RETURNSTACK720**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 if729 implemented by the ETM [IDR0]730 731 732**bit (19):**733 ETM_MODE_ATB_TRIGGER734 735**description:**736 Set to enable the ATBTRIGGER bit in the event control register737 [EVENTCTLR1] if supported [IDR5].738 739 740**bit (20):**741 ETM_MODE_LPOVERRIDE742 743**description:**744 Set to enable the LPOVERRIDE bit in the event control register745 [EVENTCTLR1], if supported [IDR5].746 747 748**bit (21):**749 ETM_MODE_ISTALL_EN750 751**description:**752 Set to enable the ISTALL bit in the stall control register753 [STALLCTLR]754 755 756**bit (23):**757 ETM_MODE_INSTPRIO758 759**description:**760 Set to enable the INSTPRIORITY bit in the stall control register761 [STALLCTLR] , if supported [IDR0].762 763 764**bit (24):**765 ETM_MODE_NOOVERFLOW766 767**description:**768 Set to enable the NOOVERFLOW bit in the stall control register769 [STALLCTLR], if supported [IDR3].770 771 772**bit (25):**773 ETM_MODE_TRACE_RESET774 775**description:**776 Set to enable the TRCRESET bit in the viewinst control register777 [VICTLR] , if supported [IDR3].778 779 780**bit (26):**781 ETM_MODE_TRACE_ERR782 783**description:**784 Set to enable the TRCCTRL bit in the viewinst control register785 [VICTLR].786 787 788**bit (27):**789 ETM_MODE_VIEWINST_STARTSTOP790 791**description:**792 Set the initial state value of the ViewInst start / stop logic793 in the viewinst control register [VICTLR]794 795 796**bit (30):**797 ETM_MODE_EXCL_KERN798 799**description:**800 Set default trace setup to exclude kernel mode trace (see note a)801 802 803**bit (31):**804 ETM_MODE_EXCL_USER805 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 space812using address range comparator 0. ‘mode’ bits 30 / 31 modify this setting to813set EL exclude bits for NS state in either user space (EL0) or kernel space814(EL1) in the address range comparator. (the default setting excludes all815secure EL, and NS EL2)816 817Once the reset parameter has been used, and/or custom programming has been818implemented - using these bits will result in the EL bits for address819comparator 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 with822data trace. As A-profile data trace is architecturally prohibited in ETMv4,823these have been omitted here. Possible uses could be where a kernel has824support for control of R or M profile infrastructure as part of a heterogeneous825system.826 827Bits 17, 28-29 are unused.828