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