coresight-ect.rst 9.3 KB

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