Documentation/trace/coresight/coresight-ect.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =============================================
   4 CoreSight Embedded Cross Trigger (CTI & CTM).
   5 =============================================
   6
   7     :Author:   Mike Leach <mike.leach@linaro.org>
   8     :Date:     November 2019
   9
  10 Hardware Description
  11 --------------------
  12
  13 The CoreSight Cross Trigger Interface (CTI) is a hardware device that takes
  14 individual input and output hardware signals known as triggers to and from
  15 devices and interconnects them via the Cross Trigger Matrix (CTM) to other
  16 devices via numbered channels, in order to propagate events between devices.
  17
  18 e.g.::
  19
  20  0000000  in_trigs  :::::::
  21  0 C   0----------->:     :             +======>(other CTI channel IO)
  22  0  P  0<-----------:     :             v
  23  0   U 0  out_trigs :     : Channels  *****      :::::::
  24  0000000            : CTI :<=========>*CTM*<====>: CTI :---+
  25  #######  in_trigs  :     : (id 0-3)  *****      :::::::   v
  26  # ETM #----------->:     :                         ^   #######
  27  #     #<-----------:     :                         +---# ETR #
  28  ####### out_trigs  :::::::                             #######
  29
  30 The CTI driver enables the programming of the CTI to attach triggers to
  31 channels. When an input trigger becomes active, the attached channel will
  32 become active. Any output trigger attached to that channel will also
  33 become active. The active channel is propagated to other CTIs via the CTM,
  34 activating connected output triggers there, unless filtered by the CTI
  35 channel gate.
  36
  37 It is also possible to activate a channel using system software directly
  38 programming registers in the CTI.
  39
  40 The CTIs are registered by the system to be associated with CPUs and/or other
  41 CoreSight devices on the trace data path. When these devices are enabled the
  42 attached CTIs will also be enabled. By default/on power up the CTIs have
  43 no programmed trigger/channel attachments, so will not affect the system
  44 until explicitly programmed.
  45
  46 The hardware trigger connections between CTIs and devices is implementation
  47 defined, unless the CPU/ETM combination is a v8 architecture, in which case
  48 the connections have an architecturally defined standard layout.
  49
  50 The hardware trigger signals can also be connected to non-CoreSight devices
  51 (e.g. UART), or be propagated off chip as hardware IO lines.
  52
  53 All the CTI devices are associated with a CTM. On many systems there will be a
  54 single effective CTM (one CTM, or multiple CTMs all interconnected), but it is
  55 possible that systems can have nets of CTIs+CTM that are not interconnected by
  56 a CTM to each other. On these systems a CTM index is declared to associate
  57 CTI devices that are interconnected via a given CTM.
  58
  59 Sysfs files and directories
  60 ---------------------------
  61
  62 The CTI devices appear on the existing CoreSight bus alongside the other
  63 CoreSight devices::
  64
  65     >$ ls /sys/bus/coresight/devices
  66      cti_cpu0  cti_cpu2  cti_sys0  etm0  etm2  funnel0  replicator0  tmc_etr0
  67      cti_cpu1  cti_cpu3  cti_sys1  etm1  etm3  funnel1  tmc_etf0     tpiu0
  68
  69 The ``cti_cpu<N>`` named CTIs are associated with a CPU, and any ETM used by
  70 that core. The ``cti_sys<N>`` CTIs are general system infrastructure CTIs that
  71 can be associated with other CoreSight devices, or other system hardware
  72 capable of generating or using trigger signals.::
  73
  74   >$ ls /sys/bus/coresight/devices/etm0/cti_cpu0
  75   channels  ctmid  enable  nr_trigger_cons mgmt  power powered  regs
  76   connections subsystem triggers0 triggers1  uevent
  77
  78 *Key file items are:-*
  79    * ``enable``: enables/disables the CTI. Read to determine current state.
  80      If this shows as enabled (1), but ``powered`` shows unpowered (0), then
  81      the enable indicates a request to enabled when the device is powered.
  82    * ``ctmid`` : associated CTM - only relevant if system has multiple CTI+CTM
  83      clusters that are not interconnected.
  84    * ``nr_trigger_cons`` : total connections - triggers<N> directories.
  85    * ``powered`` : Read to determine if the CTI is currently powered.
  86
  87 *Sub-directories:-*
  88    * ``triggers<N>``: contains list of triggers for an individual connection.
  89    * ``channels``: Contains the channel API - CTI main programming interface.
  90    * ``regs``: Gives access to the raw programmable CTI regs.
  91    * ``mgmt``: the standard CoreSight management registers.
  92    * ``connections``: Links to connected *CoreSight* devices. The number of
  93      links can be 0 to ``nr_trigger_cons``. Actual number given by ``nr_links``
  94      in this directory.
  95
  96
  97 triggers<N> directories
  98 ~~~~~~~~~~~~~~~~~~~~~~~
  99
 100 Individual trigger connection information. This describes trigger signals for
 101 CoreSight and non-CoreSight connections.
 102
 103 Each triggers directory has a set of parameters describing the triggers for
 104 the connection.
 105
 106    * ``name`` : name of connection
 107    * ``in_signals`` : input trigger signal indexes used in this connection.
 108    * ``in_types`` : functional types for in signals.
 109    * ``out_signals`` : output trigger signals for this connection.
 110    * ``out_types`` : functional types for out signals.
 111
 112 e.g::
 113
 114     >$ ls ./cti_cpu0/triggers0/
 115     in_signals  in_types  name  out_signals  out_types
 116     >$ cat ./cti_cpu0/triggers0/name
 117     cpu0
 118     >$ cat ./cti_cpu0/triggers0/out_signals
 119     0-2
 120     >$ cat ./cti_cpu0/triggers0/out_types
 121     pe_edbgreq pe_dbgrestart pe_ctiirq
 122     >$ cat ./cti_cpu0/triggers0/in_signals
 123     0-1
 124     >$ cat ./cti_cpu0/triggers0/in_types
 125     pe_dbgtrigger pe_pmuirq
 126
 127 If a connection has zero signals in either the 'in' or 'out' triggers then
 128 those parameters will be omitted.
 129
 130 Channels API Directory
 131 ~~~~~~~~~~~~~~~~~~~~~~
 132
 133 This provides an easy way to attach triggers to channels, without needing
 134 the multiple register operations that are required if manipulating the
 135 'regs' sub-directory elements directly.
 136
 137 A number of files provide this API::
 138
 139    >$ ls ./cti_sys0/channels/
 140    chan_clear         chan_inuse      chan_xtrigs_out     trigin_attach
 141    chan_free          chan_pulse      chan_xtrigs_reset   trigin_detach
 142    chan_gate_disable  chan_set        chan_xtrigs_sel     trigout_attach
 143    chan_gate_enable   chan_xtrigs_in  trig_filter_enable  trigout_detach
 144    trigout_filtered
 145
 146 Most access to these elements take the form::
 147
 148   echo <chan> [<trigger>] > /<device_path>/<operation>
 149
 150 where the optional <trigger> is only needed for trigXX_attach | detach
 151 operations.
 152
 153 e.g.::
 154
 155    >$ echo 0 1 > ./cti_sys0/channels/trigout_attach
 156    >$ echo 0 > ./cti_sys0/channels/chan_set
 157
 158 Attaches trigout(1) to channel(0), then activates channel(0) generating a
 159 set state on cti_sys0.trigout(1)
 160
 161
 162 *API operations*
 163
 164    * ``trigin_attach, trigout_attach``: Attach a channel to a trigger signal.
 165    * ``trigin_detach, trigout_detach``: Detach a channel from a trigger signal.
 166    * ``chan_set``: Set the channel - the set state will be propagated around
 167      the CTM to other connected devices.
 168    * ``chan_clear``: Clear the channel.
 169    * ``chan_pulse``: Set the channel for a single CoreSight clock cycle.
 170    * ``chan_gate_enable``: Write operation sets the CTI gate to propagate
 171      (enable) the channel to other devices. This operation takes a channel
 172      number. CTI gate is enabled for all channels by default at power up. Read
 173      to list the currently enabled channels on the gate.
 174    * ``chan_gate_disable``: Write channel number to disable gate for that
 175      channel.
 176    * ``chan_inuse``: Show the current channels attached to any signal
 177    * ``chan_free``: Show channels with no attached signals.
 178    * ``chan_xtrigs_sel``: write a channel number to select a channel to view,
 179      read to show the selected channel number.
 180    * ``chan_xtrigs_in``: Read to show the input triggers attached to
 181      the selected view channel.
 182    * ``chan_xtrigs_out``:Read to show the output triggers attached to
 183      the selected view channel.
 184    * ``trig_filter_enable``: Defaults to enabled, disable to allow potentially
 185      dangerous output signals to be set.
 186    * ``trigout_filtered``: Trigger out signals that are prevented from being
 187      set if filtering ``trig_filter_enable`` is enabled. One use is to prevent
 188      accidental ``EDBGREQ`` signals stopping a core.
 189    * ``chan_xtrigs_reset``: Write 1 to clear all channel / trigger programming.
 190      Resets device hardware to default state.
 191
 192
 193 The example below attaches input trigger index 1 to channel 2, and output
 194 trigger index 6 to the same channel. It then examines the state of the
 195 channel / trigger connections using the appropriate sysfs attributes.
 196
 197 The settings mean that if either input trigger 1, or channel 2 go active then
 198 trigger out 6 will go active. We then enable the CTI, and use the software
 199 channel control to activate channel 2. We see the active channel on the
 200 ``choutstatus`` register and the active signal on the ``trigoutstatus``
 201 register. Finally clearing the channel removes this.
 202
 203 e.g.::
 204
 205    .../cti_sys0/channels# echo 2 1 > trigin_attach
 206    .../cti_sys0/channels# echo 2 6 > trigout_attach
 207    .../cti_sys0/channels# cat chan_free
 208    0-1,3
 209    .../cti_sys0/channels# cat chan_inuse
 210    2
 211    .../cti_sys0/channels# echo 2 > chan_xtrigs_sel
 212    .../cti_sys0/channels# cat chan_xtrigs_trigin
 213    1
 214    .../cti_sys0/channels# cat chan_xtrigs_trigout
 215    6
 216    .../cti_sys0/# echo 1 > enable
 217    .../cti_sys0/channels# echo 2 > chan_set
 218    .../cti_sys0/channels# cat ../regs/choutstatus
 219    0x4
 220    .../cti_sys0/channels# cat ../regs/trigoutstatus
 221    0x40
 222    .../cti_sys0/channels# echo 2 > chan_clear
 223    .../cti_sys0/channels# cat ../regs/trigoutstatus
 224    0x0
 225    .../cti_sys0/channels# cat ../regs/choutstatus
 226    0x0