CoreSight Embedded Cross Trigger (CTI & CTM)

CTI trigger와 CTM channel 전파

이 문서는 Mike Leach가 2019년 11월에 작성했으며, CoreSight Embedded Cross Trigger를 구성하는 CTI와 CTM의 하드웨어 동작을 설명한다.

CoreSight Cross Trigger Interface(CTI)는 장치에서 들어오거나 장치로 나가는 개별 hardware signal을 trigger로 취급한다. CTI는 이 trigger들을 번호가 부여된 channel에 연결하고, Cross Trigger Matrix(CTM)를 통해 다른 장치의 CTI로 이어 장치 사이에 event를 전파한다.

원문 그림에서 CPU와 ETM의 `in_trigs`는 CTI로 들어가고 `out_trigs`는 CTI에서 되돌아간다. CTI의 channel 0-3은 CTM과 양방향으로 연결되며, CTM은 다른 CTI의 channel I/O로 event를 전달한다. 반대편 CTI는 ETR 같은 장치의 trigger와 연결될 수 있다.

CTI driver는 trigger를 channel에 attach하도록 CTI를 programming한다. input trigger가 active가 되면 연결된 channel이 active가 되고, 그 channel에 attach된 모든 output trigger도 active가 된다. active channel은 CTM을 통해 다른 CTI로 전파되어 그곳의 output trigger를 활성화하지만, CTI channel gate가 막으면 전파되지 않는다.

system software가 CTI register를 직접 programming해 channel을 활성화하는 것도 가능하다. system은 CTI를 CPU 또는 trace data path의 다른 CoreSight device와 연계해 등록하고, 그 device가 enable될 때 연결된 CTI도 enable한다.

power-up 기본 상태에서는 CTI에 trigger/channel 연결이 programming되어 있지 않으므로 명시적으로 설정하기 전에는 system에 영향을 주지 않는다. CTI와 장치 사이의 hardware trigger 배선은 보통 구현에 따라 다르지만, v8 architecture의 CPU/ETM 조합에는 architecture가 정한 표준 layout이 있다.

hardware trigger signal은 UART 같은 non-CoreSight device에 연결하거나 chip 밖의 hardware I/O line으로 전달할 수도 있다.

모든 CTI device는 CTM과 연계된다. 많은 system에는 하나의 CTM 또는 서로 연결된 여러 CTM으로 이루어진 하나의 실효적 CTM이 있다. 반면 서로 CTM으로 연결되지 않은 여러 CTI+CTM network가 있을 수도 있으며, 이때는 CTM index로 같은 CTM을 통해 상호 연결된 CTI를 묶는다.

.. SPDX-License-Identifier: GPL-2.0

=============================================
CoreSight Embedded Cross Trigger (CTI & CTM).
=============================================

    :Author:   Mike Leach <[email protected]>
    :Date:     November 2019

Hardware Description
--------------------

The CoreSight Cross Trigger Interface (CTI) is a hardware device that takes
individual input and output hardware signals known as triggers to and from
devices and interconnects them via the Cross Trigger Matrix (CTM) to other
devices via numbered channels, in order to propagate events between devices.

e.g.::

 0000000  in_trigs  :::::::
 0 C   0----------->:     :             +======>(other CTI channel IO)
 0  P  0<-----------:     :             v
 0   U 0  out_trigs :     : Channels  *****      :::::::
 0000000            : CTI :<=========>*CTM*<====>: CTI :---+
 #######  in_trigs  :     : (id 0-3)  *****      :::::::   v
 # ETM #----------->:     :                         ^   #######
 #     #<-----------:     :                         +---# ETR #
 ####### out_trigs  :::::::                             #######

The CTI driver enables the programming of the CTI to attach triggers to
channels. When an input trigger becomes active, the attached channel will
become active. Any output trigger attached to that channel will also
become active. The active channel is propagated to other CTIs via the CTM,
activating connected output triggers there, unless filtered by the CTI
channel gate.

It is also possible to activate a channel using system software directly
programming registers in the CTI.

The CTIs are registered by the system to be associated with CPUs and/or other
CoreSight devices on the trace data path. When these devices are enabled the
attached CTIs will also be enabled. By default/on power up the CTIs have
no programmed trigger/channel attachments, so will not affect the system
until explicitly programmed.

The hardware trigger connections between CTIs and devices is implementation
defined, unless the CPU/ETM combination is a v8 architecture, in which case
the connections have an architecturally defined standard layout.

The hardware trigger signals can also be connected to non-CoreSight devices
(e.g. UART), or be propagated off chip as hardware IO lines.

All the CTI devices are associated with a CTM. On many systems there will be a
single effective CTM (one CTM, or multiple CTMs all interconnected), but it is
possible that systems can have nets of CTIs+CTM that are not interconnected by
a CTM to each other. On these systems a CTM index is declared to associate
CTI devices that are interconnected via a given CTM.

CoreSight bus의 CTI sysfs 항목

CTI device는 다른 CoreSight device와 함께 기존 CoreSight bus의 `/sys/bus/coresight/devices` 아래에 나타난다. 예제 목록에는 `cti_cpu0`부터 `cti_cpu3`, `cti_sys0`, `cti_sys1`, ETM, funnel, replicator, TMC와 TPIU가 함께 보인다.

`cti_cpu<N>`은 해당 CPU와 그 core가 사용하는 ETM에 연계된다. `cti_sys<N>`은 다른 CoreSight device 또는 trigger signal을 만들거나 사용하는 다른 system hardware와 연계할 수 있는 일반 system infrastructure CTI다.

CTI device directory의 `enable`은 CTI를 enable 또는 disable하고 읽으면 현재 요청 상태를 보여 준다. `enable=1`인데 `powered=0`이면 지금 동작 중이라는 뜻이 아니라 device에 power가 들어올 때 enable하라는 요청이 설정됐다는 뜻이다.

`ctmid`는 연계된 CTM을 나타내며 서로 연결되지 않은 CTI+CTM cluster가 여러 개일 때만 중요하다. `nr_trigger_cons`는 `triggers<N>` directory로 표현되는 전체 connection 수이고, `powered`는 CTI에 현재 power가 공급되는지 보여 준다.

하위 directory 중 `triggers<N>`은 개별 connection의 trigger 목록, `channels`는 CTI의 주 programming interface인 channel API, `regs`는 raw programmable CTI register, `mgmt`는 표준 CoreSight management register를 제공한다.

`connections`는 연결된 CoreSight device로 가는 link를 제공한다. link 수는 0부터 `nr_trigger_cons`까지일 수 있으며, 실제 수는 이 directory의 `nr_links`에 기록된다.

Sysfs files and directories
---------------------------

The CTI devices appear on the existing CoreSight bus alongside the other
CoreSight devices::

    >$ ls /sys/bus/coresight/devices
     cti_cpu0  cti_cpu2  cti_sys0  etm0  etm2  funnel0  replicator0  tmc_etr0
     cti_cpu1  cti_cpu3  cti_sys1  etm1  etm3  funnel1  tmc_etf0     tpiu0

The ``cti_cpu<N>`` named CTIs are associated with a CPU, and any ETM used by
that core. The ``cti_sys<N>`` CTIs are general system infrastructure CTIs that
can be associated with other CoreSight devices, or other system hardware
capable of generating or using trigger signals.::

  >$ ls /sys/bus/coresight/devices/etm0/cti_cpu0
  channels  ctmid  enable  nr_trigger_cons mgmt  power powered  regs
  connections subsystem triggers0 triggers1  uevent

*Key file items are:-*
   * ``enable``: enables/disables the CTI. Read to determine current state.
     If this shows as enabled (1), but ``powered`` shows unpowered (0), then
     the enable indicates a request to enabled when the device is powered.
   * ``ctmid`` : associated CTM - only relevant if system has multiple CTI+CTM
     clusters that are not interconnected.
   * ``nr_trigger_cons`` : total connections - triggers<N> directories.
   * ``powered`` : Read to determine if the CTI is currently powered.

*Sub-directories:-*
   * ``triggers<N>``: contains list of triggers for an individual connection.
   * ``channels``: Contains the channel API - CTI main programming interface.
   * ``regs``: Gives access to the raw programmable CTI regs.
   * ``mgmt``: the standard CoreSight management registers.
   * ``connections``: Links to connected *CoreSight* devices. The number of
     links can be 0 to ``nr_trigger_cons``. Actual number given by ``nr_links``
     in this directory.

triggers<N> connection 정보

각 `triggers<N>` directory는 하나의 trigger connection을 설명하며 CoreSight connection과 non-CoreSight connection을 모두 표현할 수 있다.

`name`은 connection 이름이다. `in_signals`와 `out_signals`는 이 connection에서 사용하는 input 및 output trigger signal index를 나타내고, `in_types`와 `out_types`는 각 signal의 기능 유형을 나타낸다.

예제의 `cti_cpu0/triggers0` connection 이름은 `cpu0`이다. output signal은 0-2이며 유형은 `pe_edbgreq`, `pe_dbgrestart`, `pe_ctiirq`다. input signal은 0-1이며 유형은 `pe_dbgtrigger`, `pe_pmuirq`다.

connection의 input 또는 output trigger 수가 0이면 해당 방향의 parameter는 directory에서 생략된다.

triggers<N> directories
~~~~~~~~~~~~~~~~~~~~~~~

Individual trigger connection information. This describes trigger signals for
CoreSight and non-CoreSight connections.

Each triggers directory has a set of parameters describing the triggers for
the connection.

   * ``name`` : name of connection
   * ``in_signals`` : input trigger signal indexes used in this connection.
   * ``in_types`` : functional types for in signals.
   * ``out_signals`` : output trigger signals for this connection.
   * ``out_types`` : functional types for out signals.

e.g::

    >$ ls ./cti_cpu0/triggers0/
    in_signals  in_types  name  out_signals  out_types
    >$ cat ./cti_cpu0/triggers0/name
    cpu0
    >$ cat ./cti_cpu0/triggers0/out_signals
    0-2
    >$ cat ./cti_cpu0/triggers0/out_types
    pe_edbgreq pe_dbgrestart pe_ctiirq
    >$ cat ./cti_cpu0/triggers0/in_signals
    0-1
    >$ cat ./cti_cpu0/triggers0/in_types
    pe_dbgtrigger pe_pmuirq

If a connection has zero signals in either the 'in' or 'out' triggers then
those parameters will be omitted.

Channel API 사용 형식

`channels` directory는 `regs`의 여러 register를 직접 조작하지 않고 trigger를 channel에 attach하는 간단한 API를 제공한다.

대부분의 attribute는 `echo <chan> [<trigger>] > /<device_path>/<operation>` 형식으로 사용한다. 선택적인 `<trigger>` 인수는 `trigXX_attach` 또는 `trigXX_detach` 동작에만 필요하다.

예제에서 `echo 0 1 > ./cti_sys0/channels/trigout_attach`는 output trigger 1을 channel 0에 attach한다. 이어 `echo 0 > ./cti_sys0/channels/chan_set`은 channel 0을 active로 만들어 `cti_sys0.trigout(1)`에 set 상태를 발생시킨다.

Channels API Directory
~~~~~~~~~~~~~~~~~~~~~~

This provides an easy way to attach triggers to channels, without needing
the multiple register operations that are required if manipulating the
'regs' sub-directory elements directly.

A number of files provide this API::

   >$ ls ./cti_sys0/channels/
   chan_clear         chan_inuse      chan_xtrigs_out     trigin_attach
   chan_free          chan_pulse      chan_xtrigs_reset   trigin_detach
   chan_gate_disable  chan_set        chan_xtrigs_sel     trigout_attach
   chan_gate_enable   chan_xtrigs_in  trig_filter_enable  trigout_detach
   trigout_filtered

Most access to these elements take the form::

  echo <chan> [<trigger>] > /<device_path>/<operation>

where the optional <trigger> is only needed for trigXX_attach | detach
operations.

e.g.::

   >$ echo 0 1 > ./cti_sys0/channels/trigout_attach
   >$ echo 0 > ./cti_sys0/channels/chan_set

Attaches trigout(1) to channel(0), then activates channel(0) generating a
set state on cti_sys0.trigout(1)

Channel 연결·gate·filter 동작

`trigin_attach`와 `trigout_attach`는 channel을 trigger signal에 연결하고, 대응하는 `detach` 동작은 연결을 제거한다. `chan_set`은 channel을 set하고 이 상태를 CTM을 통해 다른 연결 장치로 전파한다. `chan_clear`는 channel을 clear하며 `chan_pulse`는 CoreSight clock 한 cycle 동안만 set한다.

`chan_gate_enable`은 지정한 channel이 다른 장치로 전파되도록 CTI gate를 enable한다. power-up 기본값은 모든 channel의 gate가 enable된 상태이며, 읽으면 현재 enable된 channel 목록이 나온다. `chan_gate_disable`은 지정한 channel의 gate를 disable한다.

`chan_inuse`는 어느 signal에든 attach된 channel을, `chan_free`는 attach된 signal이 없는 channel을 표시한다.

`chan_xtrigs_sel`에 channel 번호를 쓰면 조회할 channel을 고르고, 읽으면 현재 선택 번호를 보여 준다. `chan_xtrigs_in`과 `chan_xtrigs_out`은 선택한 channel에 attach된 input 및 output trigger를 각각 표시한다.

`trig_filter_enable`은 기본적으로 enable되어 있으며, disable하면 잠재적으로 위험한 output signal도 set할 수 있다. `trigout_filtered`는 filter가 enable일 때 set되지 않도록 차단되는 trigger out signal을 나타낸다. 예를 들어 뜻하지 않은 `EDBGREQ`가 core를 멈추는 사고를 방지할 수 있다.

`chan_xtrigs_reset`에 1을 쓰면 모든 channel/trigger programming을 지우고 device hardware를 기본 상태로 되돌린다.

*API operations*

   * ``trigin_attach, trigout_attach``: Attach a channel to a trigger signal.
   * ``trigin_detach, trigout_detach``: Detach a channel from a trigger signal.
   * ``chan_set``: Set the channel - the set state will be propagated around
     the CTM to other connected devices.
   * ``chan_clear``: Clear the channel.
   * ``chan_pulse``: Set the channel for a single CoreSight clock cycle.
   * ``chan_gate_enable``: Write operation sets the CTI gate to propagate
     (enable) the channel to other devices. This operation takes a channel
     number. CTI gate is enabled for all channels by default at power up. Read
     to list the currently enabled channels on the gate.
   * ``chan_gate_disable``: Write channel number to disable gate for that
     channel.
   * ``chan_inuse``: Show the current channels attached to any signal
   * ``chan_free``: Show channels with no attached signals.
   * ``chan_xtrigs_sel``: write a channel number to select a channel to view,
     read to show the selected channel number.
   * ``chan_xtrigs_in``: Read to show the input triggers attached to
     the selected view channel.
   * ``chan_xtrigs_out``:Read to show the output triggers attached to
     the selected view channel.
   * ``trig_filter_enable``: Defaults to enabled, disable to allow potentially
     dangerous output signals to be set.
   * ``trigout_filtered``: Trigger out signals that are prevented from being
     set if filtering ``trig_filter_enable`` is enabled. One use is to prevent
     accidental ``EDBGREQ`` signals stopping a core.
   * ``chan_xtrigs_reset``: Write 1 to clear all channel / trigger programming.
     Resets device hardware to default state.

Channel 2와 trigger 1·6 설정 예제

마지막 예제는 input trigger index 1과 output trigger index 6을 모두 channel 2에 attach한 뒤 sysfs attribute로 channel/trigger 연결 상태를 확인한다.

이 설정에서는 input trigger 1 또는 channel 2 중 하나가 active가 되면 output trigger 6이 active가 된다. CTI를 enable한 뒤 software channel control로 channel 2를 활성화한다.

`chan_free` 결과 `0-1,3`은 channel 0, 1, 3이 비어 있고, `chan_inuse` 결과 `2`는 channel 2가 사용 중임을 뜻한다. channel 2를 선택해 조회하면 input trigger 1과 output trigger 6이 확인된다.

channel 2를 set하면 `choutstatus=0x4`가 되어 bit 2가 active임을 나타내고, `trigoutstatus=0x40`은 bit 6, 즉 output trigger 6이 active임을 나타낸다. channel 2를 clear하면 두 register가 모두 0으로 돌아간다.

The example below attaches input trigger index 1 to channel 2, and output
trigger index 6 to the same channel. It then examines the state of the
channel / trigger connections using the appropriate sysfs attributes.

The settings mean that if either input trigger 1, or channel 2 go active then
trigger out 6 will go active. We then enable the CTI, and use the software
channel control to activate channel 2. We see the active channel on the
``choutstatus`` register and the active signal on the ``trigoutstatus``
register. Finally clearing the channel removes this.

e.g.::

   .../cti_sys0/channels# echo 2 1 > trigin_attach
   .../cti_sys0/channels# echo 2 6 > trigout_attach
   .../cti_sys0/channels# cat chan_free
   0-1,3
   .../cti_sys0/channels# cat chan_inuse
   2
   .../cti_sys0/channels# echo 2 > chan_xtrigs_sel
   .../cti_sys0/channels# cat chan_xtrigs_trigin
   1
   .../cti_sys0/channels# cat chan_xtrigs_trigout
   6
   .../cti_sys0/# echo 1 > enable
   .../cti_sys0/channels# echo 2 > chan_set
   .../cti_sys0/channels# cat ../regs/choutstatus
   0x4
   .../cti_sys0/channels# cat ../regs/trigoutstatus
   0x40
   .../cti_sys0/channels# echo 2 > chan_clear
   .../cti_sys0/channels# cat ../regs/trigoutstatus
   0x0
   .../cti_sys0/channels# cat ../regs/choutstatus
   0x0