Add section in coresight.txt explaining operation and use of CTI devices in CoreSight.
Signed-off-by: Mike Leach mike.leach@linaro.org --- Documentation/trace/coresight-ect.txt | 164 ++++++++++++++++++++++++++ Documentation/trace/coresight.txt | 7 ++ MAINTAINERS | 1 + 3 files changed, 172 insertions(+) create mode 100644 Documentation/trace/coresight-ect.txt
diff --git a/Documentation/trace/coresight-ect.txt b/Documentation/trace/coresight-ect.txt new file mode 100644 index 000000000000..298123963dd2 --- /dev/null +++ b/Documentation/trace/coresight-ect.txt @@ -0,0 +1,164 @@ +CoreSight Embedded Cross Trigger (CTI & CTM). +--------------------------------------------- + +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, +activiating 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. + +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 connections ctmid enable mgmt power regs subsystem triggers0 +triggers1 uevent + +Key file items are + * enable: enables/disables the CTI. + * ctmid : associated CTM - only relevant if system has multiple CTI+CTM + clusters that are not interconnected. + +Sub-directories:- + *triggers<N>: contains list of triggers for an individual connection + *connections: contains general connection information for the CTI plus + sysfs links to other registered CoreSight components that connect to + this CTI. + *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: This contains a list of general data describing the devices +connected to this CTI, and links to other CoreSight devices. + +>$ ls -l ./cti_cpu0/connections/ +nr_cons trigout_filtered etm0 -> ../../../85c000.etm/etm0 + + * nr_cons - total number of connections - triggers<N> directories. + * trigout_filtered - trigger out signals that are prevented from being + set if filtering is enabled. Prevents accidental edbgreq signals + stopping a core. + * etm0 - link showing connected CoreSight device - this will be named + according to the connected device. Multiple links will appear when a + CTI is connected to multiple CoreSight devices + +** triggers<N>: Individual trigger 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. + +** Channels API : This provides an easy way to attach triggers to channels, +without needing the multiple register operations that are required if +manipluating the 'regs' sub-dir elements directly. + +>$ ls ./cti_sys0/channels/ +chan_clear gate_disable list_gate_enable show_chan_sel trigin_attach +chan_pulse gate_enable list_inuse show_chan_xtrigs trigin_detach +chan_set list_free reset_xtrigs trig_filter_enable trigout_attach +trigout_detach + +Most access to these elements take the form: +echo <chan> [<trigger>] > /<device_path>/<operation> +where the optional <trigger> is only needed for trigXX_at|detach operations. + +e.g. +>$ echo 0 1 > ./cti_sys0/channels/trigin_attach +attach trig_in(1) to channel(0). +echo 0 > ./cti_sys0/channels/chan_set +activate channel(0) + + *gate_enable, gate_disable operations set the CTI gate to propagate + (enable) to other devices. These operation can take a channel number + or 'all' to operate on all channels. CTI gate is enabled by default + at power up. + *list_gate_enable: show the current channels enabled through the gate. + *list_inuse: show the current channels attached to any signal + *list_free: show channels with no attached signals. + *show_chan_sel: select the channel for the show_chan_xtrigs operation. + *show_chan_xtrigs: show the cross triggers programmed for the selected + channel. + +.../cti_sys0/channels# echo 0 1 > trigin_attach +.../cti_sys0/channels# cat list_free +1 2 3 +.../cti_sys0/channels# cat list_inuse +0 +.../cti_sys0/channels# echo 0 > show_chan_sel +.../cti_sys0/channels# cat show_chan_xtrigs +IN: 1 OUT: + + *trig_filter_enable: defaults to enabled, disable to allow potentially + dangerous output signals to be set. + *reset_xtrigs: clear all channel / trigger programming - reset device + hardware to default state. diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.txt index b027d61b27a6..f37d927a368c 100644 --- a/Documentation/trace/coresight.txt +++ b/Documentation/trace/coresight.txt @@ -477,6 +477,13 @@ root@genericarmv8:~#
Details on how to use the generic STM API can be found here [2].
+The CTI Module +-------------- + +A separate documentation file is provided to explain the use of CTI devices. +(Documentation/trace/coresight-ect.txt) + + [1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm [2]. Documentation/trace/stm.rst [3]. https://github.com/Linaro/perf-opencsd diff --git a/MAINTAINERS b/MAINTAINERS index a81f3bd8340a..45cfe624cb8c 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1585,6 +1585,7 @@ F: drivers/hwtracing/coresight/* F: include/dt-bindings/arm/coresight-cti-dt.h F: Documentation/trace/coresight.txt F: Documentation/trace/coresight-cpu-debug.txt +F: Documentation/trace/coresight-ect.txt F: Documentation/devicetree/bindings/arm/coresight.txt F: Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt F: Documentation/devicetree/bindings/arm/coresight-ect-cti.txt