1.. SPDX-License-Identifier: GPL-2.0 2 3============================================= 4CoreSight Embedded Cross Trigger (CTI & CTM). 5============================================= 6 7 :Author: Mike Leach <mike.leach@linaro.org> 8 :Date: November 2019 9 10Hardware Description 11-------------------- 12 13The CoreSight Cross Trigger Interface (CTI) is a hardware device that takes 14individual input and output hardware signals known as triggers to and from 15devices and interconnects them via the Cross Trigger Matrix (CTM) to other 16devices via numbered channels, in order to propagate events between devices. 17 18e.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 30The CTI driver enables the programming of the CTI to attach triggers to 31channels. When an input trigger becomes active, the attached channel will 32become active. Any output trigger attached to that channel will also 33become active. The active channel is propagated to other CTIs via the CTM, 34activating connected output triggers there, unless filtered by the CTI 35channel gate. 36 37It is also possible to activate a channel using system software directly 38programming registers in the CTI. 39 40The CTIs are registered by the system to be associated with CPUs and/or other 41CoreSight devices on the trace data path. When these devices are enabled the 42attached CTIs will also be enabled. By default/on power up the CTIs have 43no programmed trigger/channel attachments, so will not affect the system 44until explicitly programmed. 45 46The hardware trigger connections between CTIs and devices is implementation 47defined, unless the CPU/ETM combination is a v8 architecture, in which case 48the connections have an architecturally defined standard layout. 49 50The 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 53All the CTI devices are associated with a CTM. On many systems there will be a 54single effective CTM (one CTM, or multiple CTMs all interconnected), but it is 55possible that systems can have nets of CTIs+CTM that are not interconnected by 56a CTM to each other. On these systems a CTM index is declared to associate 57CTI devices that are interconnected via a given CTM. 58 59Sysfs files and directories 60--------------------------- 61 62The CTI devices appear on the existing CoreSight bus alongside the other 63CoreSight 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 69The ``cti_cpu<N>`` named CTIs are associated with a CPU, and any ETM used by 70that core. The ``cti_sys<N>`` CTIs are general system infrastructure CTIs that 71can be associated with other CoreSight devices, or other system hardware 72capable 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 97triggers<N> directories 98~~~~~~~~~~~~~~~~~~~~~~~ 99 100Individual trigger connection information. This describes trigger signals for 101CoreSight and non-CoreSight connections. 102 103Each triggers directory has a set of parameters describing the triggers for 104the 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 112e.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 127If a connection has zero signals in either the 'in' or 'out' triggers then 128those parameters will be omitted. 129 130Channels API Directory 131~~~~~~~~~~~~~~~~~~~~~~ 132 133This provides an easy way to attach triggers to channels, without needing 134the multiple register operations that are required if manipulating the 135'regs' sub-directory elements directly. 136 137A 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 146Most access to these elements take the form:: 147 148 echo <chan> [<trigger>] > /<device_path>/<operation> 149 150where the optional <trigger> is only needed for trigXX_attach | detach 151operations. 152 153e.g.:: 154 155 >$ echo 0 1 > ./cti_sys0/channels/trigout_attach 156 >$ echo 0 > ./cti_sys0/channels/chan_set 157 158Attaches trigout(1) to channel(0), then activates channel(0) generating a 159set 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 193The example below attaches input trigger index 1 to channel 2, and output 194trigger index 6 to the same channel. It then examines the state of the 195channel / trigger connections using the appropriate sysfs attributes. 196 197The settings mean that if either input trigger 1, or channel 2 go active then 198trigger out 6 will go active. We then enable the CTI, and use the software 199channel control to activate channel 2. We see the active channel on the 200``choutstatus`` register and the active signal on the ``trigoutstatus`` 201register. Finally clearing the channel removes this. 202 203e.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 227