| =============================================== |
| ETMv4 sysfs linux driver programming reference. |
| =============================================== |
| |
| :Author: Mike Leach <mike.leach@linaro.org> |
| :Date: October 11th, 2019 |
| |
| Supplement to existing ETMv4 driver documentation. |
| |
| Sysfs files and directories |
| --------------------------- |
| |
| Root: ``/sys/bus/coresight/devices/etm<N>`` |
| |
| |
| The following paragraphs explain the association between sysfs files and the |
| ETMv4 registers that they effect. Note the register names are given without |
| the ‘TRC’ prefix. |
| |
| ---- |
| |
| :File: ``mode`` (rw) |
| :Trace Registers: {CONFIGR + others} |
| :Notes: |
| Bit select trace features. See ‘mode’ section below. Bits |
| in this will cause equivalent programming of trace config and |
| other registers to enable the features requested. |
| |
| :Syntax & eg: |
| ``echo bitfield > mode`` |
| |
| bitfield up to 32 bits setting trace features. |
| |
| :Example: |
| ``$> echo 0x012 > mode`` |
| |
| ---- |
| |
| :File: ``reset`` (wo) |
| :Trace Registers: All |
| :Notes: |
| Reset all programming to trace nothing / no logic programmed. |
| |
| :Syntax: |
| ``echo 1 > reset`` |
| |
| ---- |
| |
| :File: ``enable_source`` (wo) |
| :Trace Registers: PRGCTLR, All hardware regs. |
| :Notes: |
| - > 0 : Programs up the hardware with the current values held in the driver |
| and enables trace. |
| |
| - = 0 : disable trace hardware. |
| |
| :Syntax: |
| ``echo 1 > enable_source`` |
| |
| ---- |
| |
| :File: ``cpu`` (ro) |
| :Trace Registers: None. |
| :Notes: |
| CPU ID that this ETM is attached to. |
| |
| :Example: |
| ``$> cat cpu`` |
| |
| ``$> 0`` |
| |
| ---- |
| |
| :File: ``addr_idx`` (rw) |
| :Trace Registers: None. |
| :Notes: |
| Virtual register to index address comparator and range |
| features. Set index for first of the pair in a range. |
| |
| :Syntax: |
| ``echo idx > addr_idx`` |
| |
| Where idx < nr_addr_cmp x 2 |
| |
| ---- |
| |
| :File: ``addr_range`` (rw) |
| :Trace Registers: ACVR[idx, idx+1], VIIECTLR |
| :Notes: |
| Pair of addresses for a range selected by addr_idx. Include |
| / exclude according to the optional parameter, or if omitted |
| uses the current ‘mode’ setting. Select comparator range in |
| control register. Error if index is odd value. |
| |
| :Depends: ``mode, addr_idx`` |
| :Syntax: |
| ``echo addr1 addr2 [exclude] > addr_range`` |
| |
| Where addr1 and addr2 define the range and addr1 < addr2. |
| |
| Optional exclude value:- |
| |
| - 0 for include |
| - 1 for exclude. |
| :Example: |
| ``$> echo 0x0000 0x2000 0 > addr_range`` |
| |
| ---- |
| |
| :File: ``addr_single`` (rw) |
| :Trace Registers: ACVR[idx] |
| :Notes: |
| Set a single address comparator according to addr_idx. This |
| is used if the address comparator is used as part of event |
| generation logic etc. |
| |
| :Depends: ``addr_idx`` |
| :Syntax: |
| ``echo addr1 > addr_single`` |
| |
| ---- |
| |
| :File: ``addr_start`` (rw) |
| :Trace Registers: ACVR[idx], VISSCTLR |
| :Notes: |
| Set a trace start address comparator according to addr_idx. |
| Select comparator in control register. |
| |
| :Depends: ``addr_idx`` |
| :Syntax: |
| ``echo addr1 > addr_start`` |
| |
| ---- |
| |
| :File: ``addr_stop`` (rw) |
| :Trace Registers: ACVR[idx], VISSCTLR |
| :Notes: |
| Set a trace stop address comparator according to addr_idx. |
| Select comparator in control register. |
| |
| :Depends: ``addr_idx`` |
| :Syntax: |
| ``echo addr1 > addr_stop`` |
| |
| ---- |
| |
| :File: ``addr_context`` (rw) |
| :Trace Registers: ACATR[idx,{6:4}] |
| :Notes: |
| Link context ID comparator to address comparator addr_idx |
| |
| :Depends: ``addr_idx`` |
| :Syntax: |
| ``echo ctxt_idx > addr_context`` |
| |
| Where ctxt_idx is the index of the linked context id / vmid |
| comparator. |
| |
| ---- |
| |
| :File: ``addr_ctxtype`` (rw) |
| :Trace Registers: ACATR[idx,{3:2}] |
| :Notes: |
| Input value string. Set type for linked context ID comparator |
| |
| :Depends: ``addr_idx`` |
| :Syntax: |
| ``echo type > addr_ctxtype`` |
| |
| Type one of {all, vmid, ctxid, none} |
| :Example: |
| ``$> echo ctxid > addr_ctxtype`` |
| |
| ---- |
| |
| :File: ``addr_exlevel_s_ns`` (rw) |
| :Trace Registers: ACATR[idx,{14:8}] |
| :Notes: |
| Set the ELx secure and non-secure matching bits for the |
| selected address comparator |
| |
| :Depends: ``addr_idx`` |
| :Syntax: |
| ``echo val > addr_exlevel_s_ns`` |
| |
| val is a 7 bit value for exception levels to exclude. Input |
| value shifted to correct bits in register. |
| :Example: |
| ``$> echo 0x4F > addr_exlevel_s_ns`` |
| |
| ---- |
| |
| :File: ``addr_instdatatype`` (rw) |
| :Trace Registers: ACATR[idx,{1:0}] |
| :Notes: |
| Set the comparator address type for matching. Driver only |
| supports setting instruction address type. |
| |
| :Depends: ``addr_idx`` |
| |
| ---- |
| |
| :File: ``addr_cmp_view`` (ro) |
| :Trace Registers: ACVR[idx, idx+1], ACATR[idx], VIIECTLR |
| :Notes: |
| Read the currently selected address comparator. If part of |
| address range then display both addresses. |
| |
| :Depends: ``addr_idx`` |
| :Syntax: |
| ``cat addr_cmp_view`` |
| :Example: |
| ``$> cat addr_cmp_view`` |
| |
| ``addr_cmp[0] range 0x0 0xffffffffffffffff include ctrl(0x4b00)`` |
| |
| ---- |
| |
| :File: ``nr_addr_cmp`` (ro) |
| :Trace Registers: From IDR4 |
| :Notes: |
| Number of address comparator pairs |
| |
| ---- |
| |
| :File: ``sshot_idx`` (rw) |
| :Trace Registers: None |
| :Notes: |
| Select single shot register set. |
| |
| ---- |
| |
| :File: ``sshot_ctrl`` (rw) |
| :Trace Registers: SSCCR[idx] |
| :Notes: |
| Access a single shot comparator control register. |
| |
| :Depends: ``sshot_idx`` |
| :Syntax: |
| ``echo val > sshot_ctrl`` |
| |
| Writes val into the selected control register. |
| |
| ---- |
| |
| :File: ``sshot_status`` (ro) |
| :Trace Registers: SSCSR[idx] |
| :Notes: |
| Read a single shot comparator status register |
| |
| :Depends: ``sshot_idx`` |
| :Syntax: |
| ``cat sshot_status`` |
| |
| Read status. |
| :Example: |
| ``$> cat sshot_status`` |
| |
| ``0x1`` |
| |
| ---- |
| |
| :File: ``sshot_pe_ctrl`` (rw) |
| :Trace Registers: SSPCICR[idx] |
| :Notes: |
| Access a single shot PE comparator input control register. |
| |
| :Depends: ``sshot_idx`` |
| :Syntax: |
| ``echo val > sshot_pe_ctrl`` |
| |
| Writes val into the selected control register. |
| |
| ---- |
| |
| :File: ``ns_exlevel_vinst`` (rw) |
| :Trace Registers: VICTLR{23:20} |
| :Notes: |
| Program non-secure exception level filters. Set / clear NS |
| exception filter bits. Setting ‘1’ excludes trace from the |
| exception level. |
| |
| :Syntax: |
| ``echo bitfield > ns_exlevel_viinst`` |
| |
| Where bitfield contains bits to set clear for EL0 to EL2 |
| :Example: |
| ``%> echo 0x4 > ns_exlevel_viinst`` |
| |
| Excludes EL2 NS trace. |
| |
| ---- |
| |
| :File: ``vinst_pe_cmp_start_stop`` (rw) |
| :Trace Registers: VIPCSSCTLR |
| :Notes: |
| Access PE start stop comparator input control registers |
| |
| ---- |
| |
| :File: ``bb_ctrl`` (rw) |
| :Trace Registers: BBCTLR |
| :Notes: |
| Define ranges that Branch Broadcast will operate in. |
| Default (0x0) is all addresses. |
| |
| :Depends: BB enabled. |
| |
| ---- |
| |
| :File: ``cyc_threshold`` (rw) |
| :Trace Registers: CCCTLR |
| :Notes: |
| Set the threshold for which cycle counts will be emitted. |
| Error if attempt to set below minimum defined in IDR3, masked |
| to width of valid bits. |
| |
| :Depends: CC enabled. |
| |
| ---- |
| |
| :File: ``syncfreq`` (rw) |
| :Trace Registers: SYNCPR |
| :Notes: |
| Set trace synchronisation period. Power of 2 value, 0 (off) |
| or 8-20. Driver defaults to 12 (every 4096 bytes). |
| |
| ---- |
| |
| :File: ``cntr_idx`` (rw) |
| :Trace Registers: none |
| :Notes: |
| Select the counter to access |
| |
| :Syntax: |
| ``echo idx > cntr_idx`` |
| |
| Where idx < nr_cntr |
| |
| ---- |
| |
| :File: ``cntr_ctrl`` (rw) |
| :Trace Registers: CNTCTLR[idx] |
| :Notes: |
| Set counter control value. |
| |
| :Depends: ``cntr_idx`` |
| :Syntax: |
| ``echo val > cntr_ctrl`` |
| |
| Where val is per ETMv4 spec. |
| |
| ---- |
| |
| :File: ``cntrldvr`` (rw) |
| :Trace Registers: CNTRLDVR[idx] |
| :Notes: |
| Set counter reload value. |
| |
| :Depends: ``cntr_idx`` |
| :Syntax: |
| ``echo val > cntrldvr`` |
| |
| Where val is per ETMv4 spec. |
| |
| ---- |
| |
| :File: ``nr_cntr`` (ro) |
| :Trace Registers: From IDR5 |
| |
| :Notes: |
| Number of counters implemented. |
| |
| ---- |
| |
| :File: ``ctxid_idx`` (rw) |
| :Trace Registers: None |
| :Notes: |
| Select the context ID comparator to access |
| |
| :Syntax: |
| ``echo idx > ctxid_idx`` |
| |
| Where idx < numcidc |
| |
| ---- |
| |
| :File: ``ctxid_pid`` (rw) |
| :Trace Registers: CIDCVR[idx] |
| :Notes: |
| Set the context ID comparator value |
| |
| :Depends: ``ctxid_idx`` |
| |
| ---- |
| |
| :File: ``ctxid_masks`` (rw) |
| :Trace Registers: CIDCCTLR0, CIDCCTLR1, CIDCVR<0-7> |
| :Notes: |
| Pair of values to set the byte masks for 1-8 context ID |
| comparators. Automatically clears masked bytes to 0 in CID |
| value registers. |
| |
| :Syntax: |
| ``echo m3m2m1m0 [m7m6m5m4] > ctxid_masks`` |
| |
| 32 bit values made up of mask bytes, where mN represents a |
| byte mask value for Context ID comparator N. |
| |
| Second value not required on systems that have fewer than 4 |
| context ID comparators |
| |
| ---- |
| |
| :File: ``numcidc`` (ro) |
| :Trace Registers: From IDR4 |
| :Notes: |
| Number of Context ID comparators |
| |
| ---- |
| |
| :File: ``vmid_idx`` (rw) |
| :Trace Registers: None |
| :Notes: |
| Select the VM ID comparator to access. |
| |
| :Syntax: |
| ``echo idx > vmid_idx`` |
| |
| Where idx < numvmidc |
| |
| ---- |
| |
| :File: ``vmid_val`` (rw) |
| :Trace Registers: VMIDCVR[idx] |
| :Notes: |
| Set the VM ID comparator value |
| |
| :Depends: ``vmid_idx`` |
| |
| ---- |
| |
| :File: ``vmid_masks`` (rw) |
| :Trace Registers: VMIDCCTLR0, VMIDCCTLR1, VMIDCVR<0-7> |
| :Notes: |
| Pair of values to set the byte masks for 1-8 VM ID comparators. |
| Automatically clears masked bytes to 0 in VMID value registers. |
| |
| :Syntax: |
| ``echo m3m2m1m0 [m7m6m5m4] > vmid_masks`` |
| |
| Where mN represents a byte mask value for VMID comparator N. |
| Second value not required on systems that have fewer than 4 |
| VMID comparators. |
| |
| ---- |
| |
| :File: ``numvmidc`` (ro) |
| :Trace Registers: From IDR4 |
| :Notes: |
| Number of VMID comparators |
| |
| ---- |
| |
| :File: ``res_idx`` (rw) |
| :Trace Registers: None. |
| :Notes: |
| Select the resource selector control to access. Must be 2 or |
| higher as selectors 0 and 1 are hardwired. |
| |
| :Syntax: |
| ``echo idx > res_idx`` |
| |
| Where 2 <= idx < nr_resource x 2 |
| |
| ---- |
| |
| :File: ``res_ctrl`` (rw) |
| :Trace Registers: RSCTLR[idx] |
| :Notes: |
| Set resource selector control value. Value per ETMv4 spec. |
| |
| :Depends: ``res_idx`` |
| :Syntax: |
| ``echo val > res_cntr`` |
| |
| Where val is per ETMv4 spec. |
| |
| ---- |
| |
| :File: ``nr_resource`` (ro) |
| :Trace Registers: From IDR4 |
| :Notes: |
| Number of resource selector pairs |
| |
| ---- |
| |
| :File: ``event`` (rw) |
| :Trace Registers: EVENTCTRL0R |
| :Notes: |
| Set up to 4 implemented event fields. |
| |
| :Syntax: |
| ``echo ev3ev2ev1ev0 > event`` |
| |
| Where evN is an 8 bit event field. Up to 4 event fields make up the |
| 32-bit input value. Number of valid fields is implementation dependent, |
| defined in IDR0. |
| |
| ---- |
| |
| :File: ``event_instren`` (rw) |
| :Trace Registers: EVENTCTRL1R |
| :Notes: |
| Choose events which insert event packets into trace stream. |
| |
| :Depends: EVENTCTRL0R |
| :Syntax: |
| ``echo bitfield > event_instren`` |
| |
| Where bitfield is up to 4 bits according to number of event fields. |
| |
| ---- |
| |
| :File: ``event_ts`` (rw) |
| :Trace Registers: TSCTLR |
| :Notes: |
| Set the event that will generate timestamp requests. |
| |
| :Depends: ``TS activated`` |
| :Syntax: |
| ``echo evfield > event_ts`` |
| |
| Where evfield is an 8 bit event selector. |
| |
| ---- |
| |
| :File: ``seq_idx`` (rw) |
| :Trace Registers: None |
| :Notes: |
| Sequencer event register select - 0 to 2 |
| |
| ---- |
| |
| :File: ``seq_state`` (rw) |
| :Trace Registers: SEQSTR |
| :Notes: |
| Sequencer current state - 0 to 3. |
| |
| ---- |
| |
| :File: ``seq_event`` (rw) |
| :Trace Registers: SEQEVR[idx] |
| :Notes: |
| State transition event registers |
| |
| :Depends: ``seq_idx`` |
| :Syntax: |
| ``echo evBevF > seq_event`` |
| |
| Where evBevF is a 16 bit value made up of two event selectors, |
| |
| - evB : back |
| - evF : forwards. |
| |
| ---- |
| |
| :File: ``seq_reset_event`` (rw) |
| :Trace Registers: SEQRSTEVR |
| :Notes: |
| Sequencer reset event |
| |
| :Syntax: |
| ``echo evfield > seq_reset_event`` |
| |
| Where evfield is an 8 bit event selector. |
| |
| ---- |
| |
| :File: ``nrseqstate`` (ro) |
| :Trace Registers: From IDR5 |
| :Notes: |
| Number of sequencer states (0 or 4) |
| |
| ---- |
| |
| :File: ``nr_pe_cmp`` (ro) |
| :Trace Registers: From IDR4 |
| :Notes: |
| Number of PE comparator inputs |
| |
| ---- |
| |
| :File: ``nr_ext_inp`` (ro) |
| :Trace Registers: From IDR5 |
| :Notes: |
| Number of external inputs |
| |
| ---- |
| |
| :File: ``nr_ss_cmp`` (ro) |
| :Trace Registers: From IDR4 |
| :Notes: |
| Number of Single Shot control registers |
| |
| ---- |
| |
| *Note:* When programming any address comparator the driver will tag the |
| comparator with a type used - i.e. RANGE, SINGLE, START, STOP. Once this tag |
| is set, then only the values can be changed using the same sysfs file / type |
| used to program it. |
| |
| Thus:: |
| |
| % echo 0 > addr_idx ; select address comparator 0 |
| % echo 0x1000 0x5000 0 > addr_range ; set address range on comparators 0, 1. |
| % echo 0x2000 > addr_start ; error as comparator 0 is a range comparator |
| % echo 2 > addr_idx ; select address comparator 2 |
| % echo 0x2000 > addr_start ; this is OK as comparator 2 is unused. |
| % echo 0x3000 > addr_stop ; error as comparator 2 set as start address. |
| % echo 2 > addr_idx ; select address comparator 3 |
| % echo 0x3000 > addr_stop ; this is OK |
| |
| To remove programming on all the comparators (and all the other hardware) use |
| the reset parameter:: |
| |
| % echo 1 > reset |
| |
| |
| |
| The ‘mode’ sysfs parameter. |
| --------------------------- |
| |
| This is a bitfield selection parameter that sets the overall trace mode for the |
| ETM. The table below describes the bits, using the defines from the driver |
| source file, along with a description of the feature these represent. Many |
| features are optional and therefore dependent on implementation in the |
| hardware. |
| |
| Bit assignments shown below:- |
| |
| ---- |
| |
| **bit (0):** |
| ETM_MODE_EXCLUDE |
| |
| **description:** |
| This is the default value for the include / exclude function when |
| setting address ranges. Set 1 for exclude range. When the mode |
| parameter is set this value is applied to the currently indexed |
| address range. |
| |
| .. _coresight-branch-broadcast: |
| |
| **bit (4):** |
| ETM_MODE_BB |
| |
| **description:** |
| Set to enable branch broadcast if supported in hardware [IDR0]. The primary use for this feature |
| is when code is patched dynamically at run time and the full program flow may not be able to be |
| reconstructed using only conditional branches. |
| |
| There is currently no support in Perf for supplying modified binaries to the decoder, so this |
| feature is only inteded to be used for debugging purposes or with a 3rd party tool. |
| |
| Choosing this option will result in a significant increase in the amount of trace generated - |
| possible danger of overflows, or fewer instructions covered. Note, that this option also |
| overrides any setting of :ref:`ETM_MODE_RETURNSTACK <coresight-return-stack>`, so where a branch |
| broadcast range overlaps a return stack range, return stacks will not be available for that |
| range. |
| |
| .. _coresight-cycle-accurate: |
| |
| **bit (5):** |
| ETMv4_MODE_CYCACC |
| |
| **description:** |
| Set to enable cycle accurate trace if supported [IDR0]. |
| |
| |
| **bit (6):** |
| ETMv4_MODE_CTXID |
| |
| **description:** |
| Set to enable context ID tracing if supported in hardware [IDR2]. |
| |
| |
| **bit (7):** |
| ETM_MODE_VMID |
| |
| **description:** |
| Set to enable virtual machine ID tracing if supported [IDR2]. |
| |
| .. _coresight-timestamp: |
| |
| **bit (11):** |
| ETMv4_MODE_TIMESTAMP |
| |
| **description:** |
| Set to enable timestamp generation if supported [IDR0]. |
| |
| .. _coresight-return-stack: |
| |
| **bit (12):** |
| ETM_MODE_RETURNSTACK |
| **description:** |
| Set to enable trace return stack use if supported [IDR0]. |
| |
| |
| **bit (13-14):** |
| ETM_MODE_QELEM(val) |
| |
| **description:** |
| ‘val’ determines level of Q element support enabled if |
| implemented by the ETM [IDR0] |
| |
| |
| **bit (19):** |
| ETM_MODE_ATB_TRIGGER |
| |
| **description:** |
| Set to enable the ATBTRIGGER bit in the event control register |
| [EVENTCTLR1] if supported [IDR5]. |
| |
| |
| **bit (20):** |
| ETM_MODE_LPOVERRIDE |
| |
| **description:** |
| Set to enable the LPOVERRIDE bit in the event control register |
| [EVENTCTLR1], if supported [IDR5]. |
| |
| |
| **bit (21):** |
| ETM_MODE_ISTALL_EN |
| |
| **description:** |
| Set to enable the ISTALL bit in the stall control register |
| [STALLCTLR] |
| |
| |
| **bit (23):** |
| ETM_MODE_INSTPRIO |
| |
| **description:** |
| Set to enable the INSTPRIORITY bit in the stall control register |
| [STALLCTLR] , if supported [IDR0]. |
| |
| |
| **bit (24):** |
| ETM_MODE_NOOVERFLOW |
| |
| **description:** |
| Set to enable the NOOVERFLOW bit in the stall control register |
| [STALLCTLR], if supported [IDR3]. |
| |
| |
| **bit (25):** |
| ETM_MODE_TRACE_RESET |
| |
| **description:** |
| Set to enable the TRCRESET bit in the viewinst control register |
| [VICTLR] , if supported [IDR3]. |
| |
| |
| **bit (26):** |
| ETM_MODE_TRACE_ERR |
| |
| **description:** |
| Set to enable the TRCCTRL bit in the viewinst control register |
| [VICTLR]. |
| |
| |
| **bit (27):** |
| ETM_MODE_VIEWINST_STARTSTOP |
| |
| **description:** |
| Set the initial state value of the ViewInst start / stop logic |
| in the viewinst control register [VICTLR] |
| |
| |
| **bit (30):** |
| ETM_MODE_EXCL_KERN |
| |
| **description:** |
| Set default trace setup to exclude kernel mode trace (see note a) |
| |
| |
| **bit (31):** |
| ETM_MODE_EXCL_USER |
| |
| **description:** |
| Set default trace setup to exclude user space trace (see note a) |
| |
| ---- |
| |
| *Note a)* On startup the ETM is programmed to trace the complete address space |
| using address range comparator 0. ‘mode’ bits 30 / 31 modify this setting to |
| set EL exclude bits for NS state in either user space (EL0) or kernel space |
| (EL1) in the address range comparator. (the default setting excludes all |
| secure EL, and NS EL2) |
| |
| Once the reset parameter has been used, and/or custom programming has been |
| implemented - using these bits will result in the EL bits for address |
| comparator 0 being set in the same way. |
| |
| *Note b)* Bits 2-3, 8-10, 15-16, 18, 22, control features that only work with |
| data trace. As A-profile data trace is architecturally prohibited in ETMv4, |
| these have been omitted here. Possible uses could be where a kernel has |
| support for control of R or M profile infrastructure as part of a heterogeneous |
| system. |
| |
| Bits 17, 28-29 are unused. |