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  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
93
94triggers<N> directories
95~~~~~~~~~~~~~~~~~~~~~~~
96
97Individual trigger connection information. This describes trigger signals for
98CoreSight and non-CoreSight connections.
99
100Each triggers directory has a set of parameters describing the triggers for
101the connection.
102
103   * ``name`` : name of connection
104   * ``in_signals`` : input trigger signal indexes used in this connection.
105   * ``in_types`` : functional types for in signals.
106   * ``out_signals`` : output trigger signals for this connection.
107   * ``out_types`` : functional types for out signals.
108
109e.g::
110
111    >$ ls ./cti_cpu0/triggers0/
112    in_signals  in_types  name  out_signals  out_types
113    >$ cat ./cti_cpu0/triggers0/name
114    cpu0
115    >$ cat ./cti_cpu0/triggers0/out_signals
116    0-2
117    >$ cat ./cti_cpu0/triggers0/out_types
118    pe_edbgreq pe_dbgrestart pe_ctiirq
119    >$ cat ./cti_cpu0/triggers0/in_signals
120    0-1
121    >$ cat ./cti_cpu0/triggers0/in_types
122    pe_dbgtrigger pe_pmuirq
123
124If a connection has zero signals in either the 'in' or 'out' triggers then
125those parameters will be omitted.
126
127Channels API Directory
128~~~~~~~~~~~~~~~~~~~~~~
129
130This provides an easy way to attach triggers to channels, without needing
131the multiple register operations that are required if manipulating the
132'regs' sub-directory elements directly.
133
134A number of files provide this API::
135
136   >$ ls ./cti_sys0/channels/
137   chan_clear         chan_inuse      chan_xtrigs_out     trigin_attach
138   chan_free          chan_pulse      chan_xtrigs_reset   trigin_detach
139   chan_gate_disable  chan_set        chan_xtrigs_sel     trigout_attach
140   chan_gate_enable   chan_xtrigs_in  trig_filter_enable  trigout_detach
141   trigout_filtered
142
143Most access to these elements take the form::
144
145  echo <chan> [<trigger>] > /<device_path>/<operation>
146
147where the optional <trigger> is only needed for trigXX_attach | detach
148operations.
149
150e.g.::
151
152   >$ echo 0 1 > ./cti_sys0/channels/trigout_attach
153   >$ echo 0 > ./cti_sys0/channels/chan_set
154
155Attaches trigout(1) to channel(0), then activates channel(0) generating a
156set state on cti_sys0.trigout(1)
157
158
159*API operations*
160
161   * ``trigin_attach, trigout_attach``: Attach a channel to a trigger signal.
162   * ``trigin_detach, trigout_detach``: Detach a channel from a trigger signal.
163   * ``chan_set``: Set the channel - the set state will be propagated around
164     the CTM to other connected devices.
165   * ``chan_clear``: Clear the channel.
166   * ``chan_pulse``: Set the channel for a single CoreSight clock cycle.
167   * ``chan_gate_enable``: Write operation sets the CTI gate to propagate
168     (enable) the channel to other devices. This operation takes a channel
169     number. CTI gate is enabled for all channels by default at power up. Read
170     to list the currently enabled channels on the gate.
171   * ``chan_gate_disable``: Write channel number to disable gate for that
172     channel.
173   * ``chan_inuse``: Show the current channels attached to any signal
174   * ``chan_free``: Show channels with no attached signals.
175   * ``chan_xtrigs_sel``: write a channel number to select a channel to view,
176     read to show the selected channel number.
177   * ``chan_xtrigs_in``: Read to show the input triggers attached to
178     the selected view channel.
179   * ``chan_xtrigs_out``:Read to show the output triggers attached to
180     the selected view channel.
181   * ``trig_filter_enable``: Defaults to enabled, disable to allow potentially
182     dangerous output signals to be set.
183   * ``trigout_filtered``: Trigger out signals that are prevented from being
184     set if filtering ``trig_filter_enable`` is enabled. One use is to prevent
185     accidental ``EDBGREQ`` signals stopping a core.
186   * ``chan_xtrigs_reset``: Write 1 to clear all channel / trigger programming.
187     Resets device hardware to default state.
188
189
190The example below attaches input trigger index 1 to channel 2, and output
191trigger index 6 to the same channel. It then examines the state of the
192channel / trigger connections using the appropriate sysfs attributes.
193
194The settings mean that if either input trigger 1, or channel 2 go active then
195trigger out 6 will go active. We then enable the CTI, and use the software
196channel control to activate channel 2. We see the active channel on the
197``choutstatus`` register and the active signal on the ``trigoutstatus``
198register. Finally clearing the channel removes this.
199
200e.g.::
201
202   .../cti_sys0/channels# echo 2 1 > trigin_attach
203   .../cti_sys0/channels# echo 2 6 > trigout_attach
204   .../cti_sys0/channels# cat chan_free
205   0-1,3
206   .../cti_sys0/channels# cat chan_inuse
207   2
208   .../cti_sys0/channels# echo 2 > chan_xtrigs_sel
209   .../cti_sys0/channels# cat chan_xtrigs_trigin
210   1
211   .../cti_sys0/channels# cat chan_xtrigs_trigout
212   6
213   .../cti_sys0/# echo 1 > enable
214   .../cti_sys0/channels# echo 2 > chan_set
215   .../cti_sys0/channels# cat ../regs/choutstatus
216   0x4
217   .../cti_sys0/channels# cat ../regs/trigoutstatus
218   0x40
219   .../cti_sys0/channels# echo 2 > chan_clear
220   .../cti_sys0/channels# cat ../regs/trigoutstatus
221   0x0
222   .../cti_sys0/channels# cat ../regs/choutstatus
223   0x0
224