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.txt | 139 ++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+)
diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.txt index efbc832146e7..d3e1147b5156 100644 --- a/Documentation/trace/coresight.txt +++ b/Documentation/trace/coresight.txt @@ -425,6 +425,145 @@ root@genericarmv8:~#
Details on how to use the generic STM API can be found here [2].
+CoreSight Embedded Cross Trigger (CTI & CTM). +--------------------------------------------- + +The CoreSight Cross Trigger Interface (CTI) is a hardware device that takes +individual input and output hardware signals from devices and interconnects +them via the Cross Trigger Matrix (CTM) to other devices, in order to propogate +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 also attached to that channel will also +become active. The active channel is propogated to other CTIs via the CTM +affecting output triggers there, unless filtered by the CTI channel gate. + +It is also possible to activate a channel using system software. + +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 then +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 propogated 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. On these systems a CTM index is declared to associate CTI devices that + are interconnected via the CTM. + +The CTI devices appear on the existing coresight bus alongside the other +CoreSight devices. + +# ls /sys/bus/coresight/devices/858000.cti +channels connections ctmid enable mgmt power regs subsystem uevent + +Key items are: +* enable: enables the CTI. +* ctmid : associated CTM - only relevant if system has multiple CTI+CTM clusters +that are not interconnected. + + +*connections: sub-dir containing the interconnection information for this CTI. +*channels: sub-dir containing the channel API - CTI main programming interface. +*regs: sub-dir giving access to the raw programmable CTI regs. +*mgmt: sub-dir for the standard CoreSight management registers. + +** Connections: This contains a list of read only data describing the devices +connected to this CTI, and the individual trigger signals to and from the +devices: +./b5b000.cti/connections# ls +0_name 0_trgin_type 0_trgout_type 1_trgin_sig 1_trgout_sig nr_cons +0_trgin_sig 0_trgout_sig 1_name 1_trgin_type 1_trgout_type trigout_filtered + +* nr_cons - number of connections +* trigout_filtered - trigger out signals that are prevented from being set if +filtering is enabled. Prevents accidental edbgreq signals stopping a core. + +Each connection has a set of parameters prefixed with the connection index. +Thus 0_name will show the name of connection 0. +* N_name : name of connection +* N_trgin_sig : input trigger signal indexes used in this connection. +* N_trgin_type : functional types for in signals. +* N_trgout_sig : output trigger signals for this connection. +* N_trgout_type : functional types for out signals. + +e.g. +.../85b000.cti/connections# cat 0_name +cpu3 +.../85b000.cti/connections# cat 0_trgin_sig +0 1 +.../85b000.cti/connections# cat 0_trgin_type +pe_dbgtrigger pe_pmuirq + +If a connection has zero signals in either the in or out triggers then those +parameters will be omitted from the connections sub-dir. + + +** 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 /sys/bus/coresight/devices/859000.cti/channels/ +chan_clear gate_disable list_xtrigs trigin_attach trigout_detach +chan_pulse gate_enable reset_xtrigs trigin_detach +chan_set list_chan_inuse trig_filter_enable trigout_attach + +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 > /sys/bus/coresight/devices/859000.cti/channels/trigin_attach +attach trig_in(1) to channel(0). +echo 0 > /sys/bus/coresight/devices/859000.cti/channels/chan_set +activate channel(0) + +*gate_enable, gate_disable operations set the CTI gate to propogate +(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. + +.../85b000.cti/channels# echo 0 1 > trigin_attach +.../85b000.cti/channels# cat list_free +1 2 3 +.../85b000.cti/channels# cat list_inuse +0 +.../85b000.cti/channels# echo 0 > show_chan_sel +.../85b000.cti/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. + [1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm [2]. Documentation/trace/stm.rst [3]. https://github.com/Linaro/perf-opencsd