Hi Mike,
On 05/06/2019 20:03, Mike Leach wrote:
Add section in coresight.txt explaining operation and use of CTI devices in CoreSight.
Thanks a lot for the detailed documentation. That really helps to get a better picture of the CTI.
PS: I am starting here, to have a better understanding before I look at the driver. :-)
Some minor comments below :
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..bf8125f3e39c 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
How about introducing the term "triggers" here ^^. i.e,
"input and output hardware signals from/to devices *(called "triggers")* and .."
and channels below.
+them via the Cross Trigger Matrix (CTM) to other devices, in order to propagate
"(CTM) to other devices *via channels* to other devices,...."
+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
for better clarity, "CTI to tie a given device trigger to a a single channel."
+channels. When an input trigger becomes active, the attached channel will +become active. Any output trigger also attached to that channel will also
s/output trigger also attached/output trigger attached/
+become active. The active channel is propagated to other CTIs via the CTM
s/via the CTM/via the CTM,/
+affecting output triggers there, unless filtered by the CTI channel gate.
s/affecting/activating/ s/the output triggers there/the output triggers connected to the channels/
+It is also possible to activate a channel using system software.
s/using system software/by directly programming 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 then
s/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 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.
s/by a CTM/to each other/
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.
Enable/disable 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.
minor nit: The above looks a bit inconsistent in terms of spacing. e.,g "* enable" vs "*connections:"
I think, having a TAB at the beginning for the key items might make them more visible (especially when you want to quickly look up the name to see what it implies, for e.g). So :
enable - Enable/Disable the CTI ctmid - Line-1 of this long comment Line-2 of this long comment.
Just my thought, as long as it is aligned and easily distinguishable, I am fine.
+** 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
nit: Should this be named "triggers" to match what they imply ?
+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
I personally find these names a bit difficult to follow and I understand it is terribly painful to group them under a sub-directory. If we assume that the device connected to a given Trigger is always present, we may be able to create permanent attributes to list these triggers. I think this is a fair assumption as we don't care if the device is there or not. All we care is pass/attach the triggers to channels and vice versa. So, we may be able to create an "attribute_group" per trigger with the following attributes:
device in_type out_type in_sig out_sig
e.g,
ls $b5b000.cti/trigger_0/$ device in_type out_type in_sig out_sig
And add it to the coresight device.
We couldn't do this for "graph" connections as we cannot expose the connections unless the device is present and that becomes pain.
+* 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>
You may drop the /<device_path>/
+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 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.
+.../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.
I think all the attributes may/must be documented under ABI/testing/sysfs-bus-coresight-devices-cti/
Cheers Suzuki