0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =============================================
0004 CoreSight Embedded Cross Trigger (CTI & CTM).
0005 =============================================
0006
0007 :Author: Mike Leach <mike.leach@linaro.org>
0008 :Date: November 2019
0009
0010 Hardware Description
0011 --------------------
0012
0013 The CoreSight Cross Trigger Interface (CTI) is a hardware device that takes
0014 individual input and output hardware signals known as triggers to and from
0015 devices and interconnects them via the Cross Trigger Matrix (CTM) to other
0016 devices via numbered channels, in order to propagate events between devices.
0017
0018 e.g.::
0019
0020 0000000 in_trigs :::::::
0021 0 C 0----------->: : +======>(other CTI channel IO)
0022 0 P 0<-----------: : v
0023 0 U 0 out_trigs : : Channels ***** :::::::
0024 0000000 : CTI :<=========>*CTM*<====>: CTI :---+
0025 ####### in_trigs : : (id 0-3) ***** ::::::: v
0026 # ETM #----------->: : ^ #######
0027 # #<-----------: : +---# ETR #
0028 ####### out_trigs ::::::: #######
0029
0030 The CTI driver enables the programming of the CTI to attach triggers to
0031 channels. When an input trigger becomes active, the attached channel will
0032 become active. Any output trigger attached to that channel will also
0033 become active. The active channel is propagated to other CTIs via the CTM,
0034 activating connected output triggers there, unless filtered by the CTI
0035 channel gate.
0036
0037 It is also possible to activate a channel using system software directly
0038 programming registers in the CTI.
0039
0040 The CTIs are registered by the system to be associated with CPUs and/or other
0041 CoreSight devices on the trace data path. When these devices are enabled the
0042 attached CTIs will also be enabled. By default/on power up the CTIs have
0043 no programmed trigger/channel attachments, so will not affect the system
0044 until explicitly programmed.
0045
0046 The hardware trigger connections between CTIs and devices is implementation
0047 defined, unless the CPU/ETM combination is a v8 architecture, in which case
0048 the connections have an architecturally defined standard layout.
0049
0050 The hardware trigger signals can also be connected to non-CoreSight devices
0051 (e.g. UART), or be propagated off chip as hardware IO lines.
0052
0053 All the CTI devices are associated with a CTM. On many systems there will be a
0054 single effective CTM (one CTM, or multiple CTMs all interconnected), but it is
0055 possible that systems can have nets of CTIs+CTM that are not interconnected by
0056 a CTM to each other. On these systems a CTM index is declared to associate
0057 CTI devices that are interconnected via a given CTM.
0058
0059 Sysfs files and directories
0060 ---------------------------
0061
0062 The CTI devices appear on the existing CoreSight bus alongside the other
0063 CoreSight devices::
0064
0065 >$ ls /sys/bus/coresight/devices
0066 cti_cpu0 cti_cpu2 cti_sys0 etm0 etm2 funnel0 replicator0 tmc_etr0
0067 cti_cpu1 cti_cpu3 cti_sys1 etm1 etm3 funnel1 tmc_etf0 tpiu0
0068
0069 The ``cti_cpu<N>`` named CTIs are associated with a CPU, and any ETM used by
0070 that core. The ``cti_sys<N>`` CTIs are general system infrastructure CTIs that
0071 can be associated with other CoreSight devices, or other system hardware
0072 capable of generating or using trigger signals.::
0073
0074 >$ ls /sys/bus/coresight/devices/etm0/cti_cpu0
0075 channels ctmid enable nr_trigger_cons mgmt power powered regs
0076 connections subsystem triggers0 triggers1 uevent
0077
0078 *Key file items are:-*
0079 * ``enable``: enables/disables the CTI. Read to determine current state.
0080 If this shows as enabled (1), but ``powered`` shows unpowered (0), then
0081 the enable indicates a request to enabled when the device is powered.
0082 * ``ctmid`` : associated CTM - only relevant if system has multiple CTI+CTM
0083 clusters that are not interconnected.
0084 * ``nr_trigger_cons`` : total connections - triggers<N> directories.
0085 * ``powered`` : Read to determine if the CTI is currently powered.
0086
0087 *Sub-directories:-*
0088 * ``triggers<N>``: contains list of triggers for an individual connection.
0089 * ``channels``: Contains the channel API - CTI main programming interface.
0090 * ``regs``: Gives access to the raw programmable CTI regs.
0091 * ``mgmt``: the standard CoreSight management registers.
0092 * ``connections``: Links to connected *CoreSight* devices. The number of
0093 links can be 0 to ``nr_trigger_cons``. Actual number given by ``nr_links``
0094 in this directory.
0095
0096
0097 triggers<N> directories
0098 ~~~~~~~~~~~~~~~~~~~~~~~
0099
0100 Individual trigger connection information. This describes trigger signals for
0101 CoreSight and non-CoreSight connections.
0102
0103 Each triggers directory has a set of parameters describing the triggers for
0104 the connection.
0105
0106 * ``name`` : name of connection
0107 * ``in_signals`` : input trigger signal indexes used in this connection.
0108 * ``in_types`` : functional types for in signals.
0109 * ``out_signals`` : output trigger signals for this connection.
0110 * ``out_types`` : functional types for out signals.
0111
0112 e.g::
0113
0114 >$ ls ./cti_cpu0/triggers0/
0115 in_signals in_types name out_signals out_types
0116 >$ cat ./cti_cpu0/triggers0/name
0117 cpu0
0118 >$ cat ./cti_cpu0/triggers0/out_signals
0119 0-2
0120 >$ cat ./cti_cpu0/triggers0/out_types
0121 pe_edbgreq pe_dbgrestart pe_ctiirq
0122 >$ cat ./cti_cpu0/triggers0/in_signals
0123 0-1
0124 >$ cat ./cti_cpu0/triggers0/in_types
0125 pe_dbgtrigger pe_pmuirq
0126
0127 If a connection has zero signals in either the 'in' or 'out' triggers then
0128 those parameters will be omitted.
0129
0130 Channels API Directory
0131 ~~~~~~~~~~~~~~~~~~~~~~
0132
0133 This provides an easy way to attach triggers to channels, without needing
0134 the multiple register operations that are required if manipulating the
0135 'regs' sub-directory elements directly.
0136
0137 A number of files provide this API::
0138
0139 >$ ls ./cti_sys0/channels/
0140 chan_clear chan_inuse chan_xtrigs_out trigin_attach
0141 chan_free chan_pulse chan_xtrigs_reset trigin_detach
0142 chan_gate_disable chan_set chan_xtrigs_sel trigout_attach
0143 chan_gate_enable chan_xtrigs_in trig_filter_enable trigout_detach
0144 trigout_filtered
0145
0146 Most access to these elements take the form::
0147
0148 echo <chan> [<trigger>] > /<device_path>/<operation>
0149
0150 where the optional <trigger> is only needed for trigXX_attach | detach
0151 operations.
0152
0153 e.g.::
0154
0155 >$ echo 0 1 > ./cti_sys0/channels/trigout_attach
0156 >$ echo 0 > ./cti_sys0/channels/chan_set
0157
0158 Attaches trigout(1) to channel(0), then activates channel(0) generating a
0159 set state on cti_sys0.trigout(1)
0160
0161
0162 *API operations*
0163
0164 * ``trigin_attach, trigout_attach``: Attach a channel to a trigger signal.
0165 * ``trigin_detach, trigout_detach``: Detach a channel from a trigger signal.
0166 * ``chan_set``: Set the channel - the set state will be propagated around
0167 the CTM to other connected devices.
0168 * ``chan_clear``: Clear the channel.
0169 * ``chan_pulse``: Set the channel for a single CoreSight clock cycle.
0170 * ``chan_gate_enable``: Write operation sets the CTI gate to propagate
0171 (enable) the channel to other devices. This operation takes a channel
0172 number. CTI gate is enabled for all channels by default at power up. Read
0173 to list the currently enabled channels on the gate.
0174 * ``chan_gate_disable``: Write channel number to disable gate for that
0175 channel.
0176 * ``chan_inuse``: Show the current channels attached to any signal
0177 * ``chan_free``: Show channels with no attached signals.
0178 * ``chan_xtrigs_sel``: write a channel number to select a channel to view,
0179 read to show the selected channel number.
0180 * ``chan_xtrigs_in``: Read to show the input triggers attached to
0181 the selected view channel.
0182 * ``chan_xtrigs_out``:Read to show the output triggers attached to
0183 the selected view channel.
0184 * ``trig_filter_enable``: Defaults to enabled, disable to allow potentially
0185 dangerous output signals to be set.
0186 * ``trigout_filtered``: Trigger out signals that are prevented from being
0187 set if filtering ``trig_filter_enable`` is enabled. One use is to prevent
0188 accidental ``EDBGREQ`` signals stopping a core.
0189 * ``chan_xtrigs_reset``: Write 1 to clear all channel / trigger programming.
0190 Resets device hardware to default state.
0191
0192
0193 The example below attaches input trigger index 1 to channel 2, and output
0194 trigger index 6 to the same channel. It then examines the state of the
0195 channel / trigger connections using the appropriate sysfs attributes.
0196
0197 The settings mean that if either input trigger 1, or channel 2 go active then
0198 trigger out 6 will go active. We then enable the CTI, and use the software
0199 channel control to activate channel 2. We see the active channel on the
0200 ``choutstatus`` register and the active signal on the ``trigoutstatus``
0201 register. Finally clearing the channel removes this.
0202
0203 e.g.::
0204
0205 .../cti_sys0/channels# echo 2 1 > trigin_attach
0206 .../cti_sys0/channels# echo 2 6 > trigout_attach
0207 .../cti_sys0/channels# cat chan_free
0208 0-1,3
0209 .../cti_sys0/channels# cat chan_inuse
0210 2
0211 .../cti_sys0/channels# echo 2 > chan_xtrigs_sel
0212 .../cti_sys0/channels# cat chan_xtrigs_trigin
0213 1
0214 .../cti_sys0/channels# cat chan_xtrigs_trigout
0215 6
0216 .../cti_sys0/# echo 1 > enable
0217 .../cti_sys0/channels# echo 2 > chan_set
0218 .../cti_sys0/channels# cat ../regs/choutstatus
0219 0x4
0220 .../cti_sys0/channels# cat ../regs/trigoutstatus
0221 0x40
0222 .../cti_sys0/channels# echo 2 > chan_clear
0223 .../cti_sys0/channels# cat ../regs/trigoutstatus
0224 0x0
0225 .../cti_sys0/channels# cat ../regs/choutstatus
0226 0x0
