diff options
Diffstat (limited to 'Documentation/trace/coresight')
| -rw-r--r-- | Documentation/trace/coresight/coresight-config.rst | 294 | ||||
| -rw-r--r-- | Documentation/trace/coresight/coresight-cpu-debug.rst | 3 | ||||
| -rw-r--r-- | Documentation/trace/coresight/coresight-dummy.rst | 32 | ||||
| -rw-r--r-- | Documentation/trace/coresight/coresight-ect.rst | 226 | ||||
| -rw-r--r-- | Documentation/trace/coresight/coresight-etm4x-reference.rst | 33 | ||||
| -rw-r--r-- | Documentation/trace/coresight/coresight-perf.rst | 158 | ||||
| -rw-r--r-- | Documentation/trace/coresight/coresight-tpda.rst | 52 | ||||
| -rw-r--r-- | Documentation/trace/coresight/coresight-tpdm.rst | 45 | ||||
| -rw-r--r-- | Documentation/trace/coresight/coresight-trbe.rst | 38 | ||||
| -rw-r--r-- | Documentation/trace/coresight/coresight.rst | 209 | ||||
| -rw-r--r-- | Documentation/trace/coresight/ultrasoc-smb.rst | 83 |
11 files changed, 1164 insertions, 9 deletions
diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst new file mode 100644 index 000000000000..6d5ffa6f7347 --- /dev/null +++ b/Documentation/trace/coresight/coresight-config.rst @@ -0,0 +1,294 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================== +CoreSight System Configuration Manager +====================================== + + :Author: Mike Leach <mike.leach@linaro.org> + :Date: October 2020 + +Introduction +============ + +The CoreSight System Configuration manager is an API that allows the +programming of the CoreSight system with pre-defined configurations that +can then be easily enabled from sysfs or perf. + +Many CoreSight components can be programmed in complex ways - especially ETMs. +In addition, components can interact across the CoreSight system, often via +the cross trigger components such as CTI and CTM. These system settings can +be defined and enabled as named configurations. + + +Basic Concepts +============== + +This section introduces the basic concepts of a CoreSight system configuration. + + +Features +-------- + +A feature is a named set of programming for a CoreSight device. The programming +is device dependent, and can be defined in terms of absolute register values, +resource usage and parameter values. + +The feature is defined using a descriptor. This descriptor is used to load onto +a matching device, either when the feature is loaded into the system, or when the +CoreSight device is registered with the configuration manager. + +The load process involves interpreting the descriptor into a set of register +accesses in the driver - the resource usage and parameter descriptions +translated into appropriate register accesses. This interpretation makes it easy +and efficient for the feature to be programmed onto the device when required. + +The feature will not be active on the device until the feature is enabled, and +the device itself is enabled. When the device is enabled then enabled features +will be programmed into the device hardware. + +A feature is enabled as part of a configuration being enabled on the system. + + +Parameter Value +~~~~~~~~~~~~~~~ + +A parameter value is a named value that may be set by the user prior to the +feature being enabled that can adjust the behaviour of the operation programmed +by the feature. + +For example, this could be a count value in a programmed operation that repeats +at a given rate. When the feature is enabled then the current value of the +parameter is used in programming the device. + +The feature descriptor defines a default value for a parameter, which is used +if the user does not supply a new value. + +Users can update parameter values using the configfs API for the CoreSight +system - which is described below. + +The current value of the parameter is loaded into the device when the feature +is enabled on that device. + + +Configurations +-------------- + +A configuration defines a set of features that are to be used in a trace +session where the configuration is selected. For any trace session only one +configuration may be selected. + +The features defined may be on any type of device that is registered +to support system configuration. A configuration may select features to be +enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a +specific CTI on the system. + +As with the feature, a descriptor is used to define the configuration. +This will define the features that must be enabled as part of the configuration +as well as any preset values that can be used to override default parameter +values. + + +Preset Values +~~~~~~~~~~~~~ + +Preset values are easily selectable sets of parameter values for the features +that the configuration uses. The number of values in a single preset set, equals +the sum of parameter values in the features used by the configuration. + +e.g. a configuration consists of 3 features, one has 2 parameters, one has +a single parameter, and another has no parameters. A single preset set will +therefore have 3 values. + +Presets are optionally defined by the configuration, up to 15 can be defined. +If no preset is selected, then the parameter values defined in the feature +are used as normal. + + +Operation +~~~~~~~~~ + +The following steps take place in the operation of a configuration. + +1) In this example, the configuration is 'autofdo', which has an + associated feature 'strobing' that works on ETMv4 CoreSight Devices. + +2) The configuration is enabled. For example 'perf' may select the + configuration as part of its command line:: + + perf record -e cs_etm/autofdo/ myapp + + which will enable the 'autofdo' configuration. + +3) perf starts tracing on the system. As each ETMv4 that perf uses for + trace is enabled, the configuration manager will check if the ETMv4 + has a feature that relates to the currently active configuration. + In this case 'strobing' is enabled & programmed into the ETMv4. + +4) When the ETMv4 is disabled, any registers marked as needing to be + saved will be read back. + +5) At the end of the perf session, the configuration will be disabled. + + +Viewing Configurations and Features +=================================== + +The set of configurations and features that are currently loaded into the +system can be viewed using the configfs API. + +Mount configfs as normal and the 'cs-syscfg' subsystem will appear:: + + $ ls /config + cs-syscfg stp-policy + +This has two sub-directories:: + + $ cd cs-syscfg/ + $ ls + configurations features + +The system has the configuration 'autofdo' built in. It may be examined as +follows:: + + $ cd configurations/ + $ ls + autofdo + $ cd autofdo/ + $ ls + description feature_refs preset1 preset3 preset5 preset7 preset9 + enable preset preset2 preset4 preset6 preset8 + $ cat description + Setup ETMs with strobing for autofdo + $ cat feature_refs + strobing + +Each preset declared has a 'preset<n>' subdirectory declared. The values for +the preset can be examined:: + + $ cat preset1/values + strobing.window = 0x1388 strobing.period = 0x2 + $ cat preset2/values + strobing.window = 0x1388 strobing.period = 0x4 + +The 'enable' and 'preset' files allow the control of a configuration when +using CoreSight with sysfs. + +The features referenced by the configuration can be examined in the features +directory:: + + $ cd ../../features/strobing/ + $ ls + description matches nr_params params + $ cat description + Generate periodic trace capture windows. + parameter 'window': a number of CPU cycles (W) + parameter 'period': trace enabled for W cycles every period x W cycles + $ cat matches + SRC_ETMV4 + $ cat nr_params + 2 + +Move to the params directory to examine and adjust parameters:: + + cd params + $ ls + period window + $ cd period + $ ls + value + $ cat value + 0x2710 + # echo 15000 > value + # cat value + 0x3a98 + +Parameters adjusted in this way are reflected in all device instances that have +loaded the feature. + + +Using Configurations in perf +============================ + +The configurations loaded into the CoreSight configuration management are +also declared in the perf 'cs_etm' event infrastructure so that they can +be selected when running trace under perf:: + + $ ls /sys/devices/cs_etm + cpu0 cpu2 events nr_addr_filters power subsystem uevent + cpu1 cpu3 format perf_event_mux_interval_ms sinks type + +The key directory here is 'events' - a generic perf directory which allows +selection on the perf command line. As with the sinks entries, this provides +a hash of the configuration name. + +The entry in the 'events' directory uses perfs built in syntax generator +to substitute the syntax for the name when evaluating the command:: + + $ ls events/ + autofdo + $ cat events/autofdo + configid=0xa7c3dddd + +The 'autofdo' configuration may be selected on the perf command line:: + + $ perf record -e cs_etm/autofdo/u --per-thread <application> + +A preset to override the current parameter values can also be selected:: + + $ perf record -e cs_etm/autofdo,preset=1/u --per-thread <application> + +When configurations are selected in this way, then the trace sink used is +automatically selected. + +Using Configurations in sysfs +============================= + +Coresight can be controlled using sysfs. When this is in use then a configuration +can be made active for the devices that are used in the sysfs session. + +In a configuration there are 'enable' and 'preset' files. + +To enable a configuration for use with sysfs:: + + $ cd configurations/autofdo + $ echo 1 > enable + +This will then use any default parameter values in the features - which can be +adjusted as described above. + +To use a preset<n> set of parameter values:: + + $ echo 3 > preset + +This will select preset3 for the configuration. +The valid values for preset are 0 - to deselect presets, and any value of +<n> where a preset<n> sub-directory is present. + +Note that the active sysfs configuration is a global parameter, therefore +only a single configuration can be active for sysfs at any one time. +Attempting to enable a second configuration will result in an error. +Additionally, attempting to disable the configuration while in use will +also result in an error. + +The use of the active configuration by sysfs is independent of the configuration +used in perf. + + +Creating and Loading Custom Configurations +========================================== + +Custom configurations and / or features can be dynamically loaded into the +system by using a loadable module. + +An example of a custom configuration is found in ./samples/coresight. + +This creates a new configuration that uses the existing built in +strobing feature, but provides a different set of presets. + +When the module is loaded, then the configuration appears in the configfs +file system and is selectable in the same way as the built in configuration +described above. + +Configurations can use previously loaded features. The system will ensure +that it is not possible to unload a feature that is currently in use, by +enforcing the unload order as the strict reverse of the load order. diff --git a/Documentation/trace/coresight/coresight-cpu-debug.rst b/Documentation/trace/coresight/coresight-cpu-debug.rst index 993dd294b81b..836b35532667 100644 --- a/Documentation/trace/coresight/coresight-cpu-debug.rst +++ b/Documentation/trace/coresight/coresight-cpu-debug.rst @@ -117,7 +117,8 @@ divide into below cases: Device Tree Bindings -------------------- -See Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt for details. +See Documentation/devicetree/bindings/arm/arm,coresight-cpu-debug.yaml for +details. How to use the module diff --git a/Documentation/trace/coresight/coresight-dummy.rst b/Documentation/trace/coresight/coresight-dummy.rst new file mode 100644 index 000000000000..eff7c553ee6c --- /dev/null +++ b/Documentation/trace/coresight/coresight-dummy.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================= +Coresight Dummy Trace Module +============================= + + :Author: Hao Zhang <quic_hazha@quicinc.com> + :Date: June 2023 + +Introduction +------------ + +The Coresight dummy trace module is for the specific devices that kernel don't +have permission to access or configure, e.g., CoreSight TPDMs on Qualcomm +platforms. For these devices, a dummy driver is needed to register them as +Coresight devices. The module may also be used to define components that may +not have any programming interfaces, so that paths can be created in the driver. +It provides Coresight API for operations on dummy devices, such as enabling and +disabling them. It also provides the Coresight dummy sink/source paths for +debugging. + +Config details +-------------- + +There are two types of nodes, dummy sink and dummy source. These nodes +are available at ``/sys/bus/coresight/devices``. + +Example output:: + + $ ls -l /sys/bus/coresight/devices | grep dummy + dummy_sink0 -> ../../../devices/platform/soc@0/soc@0:sink/dummy_sink0 + dummy_source0 -> ../../../devices/platform/soc@0/soc@0:source/dummy_source0 diff --git a/Documentation/trace/coresight/coresight-ect.rst b/Documentation/trace/coresight/coresight-ect.rst new file mode 100644 index 000000000000..a68732c5c6d6 --- /dev/null +++ b/Documentation/trace/coresight/coresight-ect.rst @@ -0,0 +1,226 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================= +CoreSight Embedded Cross Trigger (CTI & CTM). +============================================= + + :Author: Mike Leach <mike.leach@linaro.org> + :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. + +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> 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. + +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) + + +*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. + + +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 diff --git a/Documentation/trace/coresight/coresight-etm4x-reference.rst b/Documentation/trace/coresight/coresight-etm4x-reference.rst index b64d9a9c79df..89ac4e6fc96f 100644 --- a/Documentation/trace/coresight/coresight-etm4x-reference.rst +++ b/Documentation/trace/coresight/coresight-etm4x-reference.rst @@ -71,6 +71,20 @@ the ‘TRC’ prefix. ---- +:File: ``ts_source`` (ro) +:Trace Registers: None. +:Notes: + When FEAT_TRF is implemented, value of TRFCR_ELx.TS used for trace session. Otherwise -1 + indicates an unknown time source. Check trcidr0.tssize to see if a global timestamp is + available. + +:Example: + ``$> cat ts_source`` + + ``$> 1`` + +---- + :File: ``addr_idx`` (rw) :Trace Registers: None. :Notes: @@ -427,7 +441,7 @@ the ‘TRC’ prefix. :Syntax: ``echo idx > vmid_idx`` - Where idx < numvmidc + Where idx < numvmidc ---- @@ -650,13 +664,26 @@ Bit assignments shown below:- parameter is set this value is applied to the currently indexed address range. +.. _coresight-branch-broadcast: **bit (4):** ETM_MODE_BB **description:** - Set to enable branch broadcast if supported in hardware [IDR0]. + Set to enable branch broadcast if supported in hardware [IDR0]. The primary use for this feature + is when code is patched dynamically at run time and the full program flow may not be able to be + reconstructed using only conditional branches. + + There is currently no support in Perf for supplying modified binaries to the decoder, so this + feature is only intended to be used for debugging purposes or with a 3rd party tool. + + Choosing this option will result in a significant increase in the amount of trace generated - + possible danger of overflows, or fewer instructions covered. Note, that this option also + overrides any setting of :ref:`ETM_MODE_RETURNSTACK <coresight-return-stack>`, so where a branch + broadcast range overlaps a return stack range, return stacks will not be available for that + range. +.. _coresight-cycle-accurate: **bit (5):** ETMv4_MODE_CYCACC @@ -678,6 +705,7 @@ Bit assignments shown below:- **description:** Set to enable virtual machine ID tracing if supported [IDR2]. +.. _coresight-timestamp: **bit (11):** ETMv4_MODE_TIMESTAMP @@ -685,6 +713,7 @@ Bit assignments shown below:- **description:** Set to enable timestamp generation if supported [IDR0]. +.. _coresight-return-stack: **bit (12):** ETM_MODE_RETURNSTACK diff --git a/Documentation/trace/coresight/coresight-perf.rst b/Documentation/trace/coresight/coresight-perf.rst new file mode 100644 index 000000000000..d087aae7d492 --- /dev/null +++ b/Documentation/trace/coresight/coresight-perf.rst @@ -0,0 +1,158 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================ +CoreSight - Perf +================ + + :Author: Carsten Haitzler <carsten.haitzler@arm.com> + :Date: June 29th, 2022 + +Perf is able to locally access CoreSight trace data and store it to the +output perf data files. This data can then be later decoded to give the +instructions that were traced for debugging or profiling purposes. You +can log such data with a perf record command like:: + + perf record -e cs_etm//u testbinary + +This would run some test binary (testbinary) until it exits and record +a perf.data trace file. That file would have AUX sections if CoreSight +is working correctly. You can dump the content of this file as +readable text with a command like:: + + perf report --stdio --dump -i perf.data + +You should find some sections of this file have AUX data blocks like:: + + 0x1e78 [0x30]: PERF_RECORD_AUXTRACE size: 0x11dd0 offset: 0 ref: 0x1b614fc1061b0ad1 idx: 0 tid: 531230 cpu: -1 + + . ... CoreSight ETM Trace data: size 73168 bytes + Idx:0; ID:10; I_ASYNC : Alignment Synchronisation. + Idx:12; ID:10; I_TRACE_INFO : Trace Info.; INFO=0x0 { CC.0 } + Idx:17; ID:10; I_ADDR_L_64IS0 : Address, Long, 64 bit, IS0.; Addr=0x0000000000000000; + Idx:26; ID:10; I_TRACE_ON : Trace On. + Idx:27; ID:10; I_ADDR_CTXT_L_64IS0 : Address & Context, Long, 64 bit, IS0.; Addr=0x0000FFFFB6069140; Ctxt: AArch64,EL0, NS; + Idx:38; ID:10; I_ATOM_F6 : Atom format 6.; EEEEEEEEEEEEEEEEEEEEEEEE + Idx:39; ID:10; I_ATOM_F6 : Atom format 6.; EEEEEEEEEEEEEEEEEEEEEEEE + Idx:40; ID:10; I_ATOM_F6 : Atom format 6.; EEEEEEEEEEEEEEEEEEEEEEEE + Idx:41; ID:10; I_ATOM_F6 : Atom format 6.; EEEEEEEEEEEN + ... + +If you see these above, then your system is tracing CoreSight data +correctly. + +To compile perf with CoreSight support in the tools/perf directory do:: + + make CORESIGHT=1 + +This requires OpenCSD to build. You may install distribution packages +for the support such as libopencsd and libopencsd-dev or download it +and build yourself. Upstream OpenCSD is located at: + + https://github.com/Linaro/OpenCSD + +For complete information on building perf with CoreSight support and +more extensive usage look at: + + https://github.com/Linaro/OpenCSD/blob/master/HOWTO.md + + +Kernel CoreSight Support +------------------------ + +You will also want CoreSight support enabled in your kernel config. +Ensure it is enabled with:: + + CONFIG_CORESIGHT=y + +There are various other CoreSight options you probably also want +enabled like:: + + CONFIG_CORESIGHT_LINKS_AND_SINKS=y + CONFIG_CORESIGHT_LINK_AND_SINK_TMC=y + CONFIG_CORESIGHT_CATU=y + CONFIG_CORESIGHT_SINK_TPIU=y + CONFIG_CORESIGHT_SINK_ETBV10=y + CONFIG_CORESIGHT_SOURCE_ETM4X=y + CONFIG_CORESIGHT_CTI=y + CONFIG_CORESIGHT_CTI_INTEGRATION_REGS=y + +Please refer to the kernel configuration help for more information. + +Perf test - Verify kernel and userspace perf CoreSight work +----------------------------------------------------------- + +When you run perf test, it will do a lot of self tests. Some of those +tests will cover CoreSight (only if enabled and on ARM64). You +generally would run perf test from the tools/perf directory in the +kernel tree. Some tests will check some internal perf support like: + + Check Arm CoreSight trace data recording and synthesized samples + Check Arm SPE trace data recording and synthesized samples + +Some others will actually use perf record and some test binaries that +are in tests/shell/coresight and will collect traces to ensure a +minimum level of functionality is met. The scripts that launch these +tests are in the same directory. These will all look like: + + CoreSight / ASM Pure Loop + CoreSight / Memcpy 16k 10 Threads + CoreSight / Thread Loop 10 Threads - Check TID + etc. + +These perf record tests will not run if the tool binaries do not exist +in tests/shell/coresight/\*/ and will be skipped. If you do not have +CoreSight support in hardware then either do not build perf with +CoreSight support or remove these binaries in order to not have these +tests fail and have them skip instead. + +These tests will log historical results in the current working +directory (e.g. tools/perf) and will be named stats-\*.csv like: + + stats-asm_pure_loop-out.csv + stats-memcpy_thread-16k_10.csv + ... + +These statistic files log some aspects of the AUX data sections in +the perf data output counting some numbers of certain encodings (a +good way to know that it's working in a very simple way). One problem +with CoreSight is that given a large enough amount of data needing to +be logged, some of it can be lost due to the processor not waking up +in time to read out all the data from buffers etc.. You will notice +that the amount of data collected can vary a lot per run of perf test. +If you wish to see how this changes over time, simply run perf test +multiple times and all these csv files will have more and more data +appended to it that you can later examine, graph and otherwise use to +figure out if things have become worse or better. + +This means sometimes these tests fail as they don't capture all the +data needed. This is about tracking quality and amount of data +produced over time and to see when changes to the Linux kernel improve +quality of traces. + +Be aware that some of these tests take quite a while to run, specifically +in processing the perf data file and dumping contents to then examine what +is inside. + +You can change where these csv logs are stored by setting the +PERF_TEST_CORESIGHT_STATDIR environment variable before running perf +test like:: + + export PERF_TEST_CORESIGHT_STATDIR=/var/tmp + perf test + +They will also store resulting perf output data in the current +directory for later inspection like:: + + perf-asm_pure_loop-out.data + perf-memcpy_thread-16k_10.data + ... + +You can alter where the perf data files are stored by setting the +PERF_TEST_CORESIGHT_DATADIR environment variable such as:: + + PERF_TEST_CORESIGHT_DATADIR=/var/tmp + perf test + +You may wish to set these above environment variables if you wish to +keep the output of tests outside of the current working directory for +longer term storage and examination. diff --git a/Documentation/trace/coresight/coresight-tpda.rst b/Documentation/trace/coresight/coresight-tpda.rst new file mode 100644 index 000000000000..a37f387ceaea --- /dev/null +++ b/Documentation/trace/coresight/coresight-tpda.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================================================= +The trace performance monitoring and diagnostics aggregator(TPDA) +================================================================= + + :Author: Jinlong Mao <quic_jinlmao@quicinc.com> + :Date: January 2023 + +Hardware Description +-------------------- + +TPDA - The trace performance monitoring and diagnostics aggregator or +TPDA in short serves as an arbitration and packetization engine for the +performance monitoring and diagnostics network specification. +The primary use case of the TPDA is to provide packetization, funneling +and timestamping of Monitor data. + + +Sysfs files and directories +--------------------------- +Root: ``/sys/bus/coresight/devices/tpda<N>`` + +Config details +--------------------------- + +The tpdm and tpda nodes should be observed at the coresight path +"/sys/bus/coresight/devices". +e.g. +/sys/bus/coresight/devices # ls -l | grep tpd +tpda0 -> ../../../devices/platform/soc@0/6004000.tpda/tpda0 +tpdm0 -> ../../../devices/platform/soc@0/6c08000.mm.tpdm/tpdm0 + +We can use the commands are similar to the below to validate TPDMs. +Enable coresight sink first. The port of tpda which is connected to +the tpdm will be enabled after commands below. + +echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink +echo 1 > /sys/bus/coresight/devices/tpdm0/enable_source +echo 1 > /sys/bus/coresight/devices/tpdm0/integration_test +echo 2 > /sys/bus/coresight/devices/tpdm0/integration_test + +The test data will be collected in the coresight sink which is enabled. +If rwp register of the sink is keeping updating when do +integration_test (by cat tmc_etf0/mgmt/rwp), it means there is data +generated from TPDM to sink. + +There must be a tpda between tpdm and the sink. When there are some +other trace event hw components in the same HW block with tpdm, tpdm +and these hw components will connect to the coresight funnel. When +there is only tpdm trace hw in the HW block, tpdm will connect to +tpda directly. diff --git a/Documentation/trace/coresight/coresight-tpdm.rst b/Documentation/trace/coresight/coresight-tpdm.rst new file mode 100644 index 000000000000..72fd5c855d45 --- /dev/null +++ b/Documentation/trace/coresight/coresight-tpdm.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================================== +Trace performance monitoring and diagnostics monitor(TPDM) +========================================================== + + :Author: Jinlong Mao <quic_jinlmao@quicinc.com> + :Date: January 2023 + +Hardware Description +-------------------- +TPDM - The trace performance monitoring and diagnostics monitor or TPDM in +short serves as data collection component for various dataset types. +The primary use case of the TPDM is to collect data from different data +sources and send it to a TPDA for packetization, timestamping and funneling. + +Sysfs files and directories +--------------------------- +Root: ``/sys/bus/coresight/devices/tpdm<N>`` + +---- + +:File: ``enable_source`` (RW) +:Notes: + - > 0 : enable the datasets of TPDM. + + - = 0 : disable the datasets of TPDM. + +:Syntax: + ``echo 1 > enable_source`` + +---- + +:File: ``integration_test`` (wo) +:Notes: + Integration test will generate test data for tpdm. + +:Syntax: + ``echo value > integration_test`` + + value - 1 or 2. + +---- + +.. This text is intentionally added to make Sphinx happy. diff --git a/Documentation/trace/coresight/coresight-trbe.rst b/Documentation/trace/coresight/coresight-trbe.rst new file mode 100644 index 000000000000..b9928ef148da --- /dev/null +++ b/Documentation/trace/coresight/coresight-trbe.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Trace Buffer Extension (TRBE). +============================== + + :Author: Anshuman Khandual <anshuman.khandual@arm.com> + :Date: November 2020 + +Hardware Description +-------------------- + +Trace Buffer Extension (TRBE) is a percpu hardware which captures in system +memory, CPU traces generated from a corresponding percpu tracing unit. This +gets plugged in as a coresight sink device because the corresponding trace +generators (ETE), are plugged in as source device. + +The TRBE is not compliant to CoreSight architecture specifications, but is +driven via the CoreSight driver framework to support the ETE (which is +CoreSight compliant) integration. + +Sysfs files and directories +--------------------------- + +The TRBE devices appear on the existing coresight bus alongside the other +coresight devices:: + + >$ ls /sys/bus/coresight/devices + trbe0 trbe1 trbe2 trbe3 + +The ``trbe<N>`` named TRBEs are associated with a CPU.:: + + >$ ls /sys/bus/coresight/devices/trbe0/ + align flag + +*Key file items are:-* + * ``align``: TRBE write pointer alignment + * ``flag``: TRBE updates memory with access and dirty flags diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst index a566719f8e7e..d4f93d6a2d63 100644 --- a/Documentation/trace/coresight/coresight.rst +++ b/Documentation/trace/coresight/coresight.rst @@ -130,7 +130,7 @@ Misc: Device Tree Bindings -------------------- -See Documentation/devicetree/bindings/arm/coresight.txt for details. +See ``Documentation/devicetree/bindings/arm/arm,coresight-*.yaml`` for details. As of this writing drivers for ITM, STMs and CTIs are not provided but are expected to be added as the solution matures. @@ -241,6 +241,92 @@ to the newer scheme, to give a confirmation that what you see on your system is not unexpected. One must use the "names" as they appear on the system under specified locations. +Topology Representation +----------------------- + +Each CoreSight component has a ``connections`` directory which will contain +links to other CoreSight components. This allows the user to explore the trace +topology and for larger systems, determine the most appropriate sink for a +given source. The connection information can also be used to establish +which CTI devices are connected to a given component. This directory contains a +``nr_links`` attribute detailing the number of links in the directory. + +For an ETM source, in this case ``etm0`` on a Juno platform, a typical +arrangement will be:: + + linaro-developer:~# ls - l /sys/bus/coresight/devices/etm0/connections + <file details> cti_cpu0 -> ../../../23020000.cti/cti_cpu0 + <file details> nr_links + <file details> out:0 -> ../../../230c0000.funnel/funnel2 + +Following the out port to ``funnel2``:: + + linaro-developer:~# ls -l /sys/bus/coresight/devices/funnel2/connections + <file details> in:0 -> ../../../23040000.etm/etm0 + <file details> in:1 -> ../../../23140000.etm/etm3 + <file details> in:2 -> ../../../23240000.etm/etm4 + <file details> in:3 -> ../../../23340000.etm/etm5 + <file details> nr_links + <file details> out:0 -> ../../../20040000.funnel/funnel0 + +And again to ``funnel0``:: + + linaro-developer:~# ls -l /sys/bus/coresight/devices/funnel0/connections + <file details> in:0 -> ../../../220c0000.funnel/funnel1 + <file details> in:1 -> ../../../230c0000.funnel/funnel2 + <file details> nr_links + <file details> out:0 -> ../../../20010000.etf/tmc_etf0 + +Finding the first sink ``tmc_etf0``. This can be used to collect data +as a sink, or as a link to propagate further along the chain:: + + linaro-developer:~# ls -l /sys/bus/coresight/devices/tmc_etf0/connections + <file details> cti_sys0 -> ../../../20020000.cti/cti_sys0 + <file details> in:0 -> ../../../20040000.funnel/funnel0 + <file details> nr_links + <file details> out:0 -> ../../../20150000.funnel/funnel4 + +via ``funnel4``:: + + linaro-developer:~# ls -l /sys/bus/coresight/devices/funnel4/connections + <file details> in:0 -> ../../../20010000.etf/tmc_etf0 + <file details> in:1 -> ../../../20140000.etf/tmc_etf1 + <file details> nr_links + <file details> out:0 -> ../../../20120000.replicator/replicator0 + +and a ``replicator0``:: + + linaro-developer:~# ls -l /sys/bus/coresight/devices/replicator0/connections + <file details> in:0 -> ../../../20150000.funnel/funnel4 + <file details> nr_links + <file details> out:0 -> ../../../20030000.tpiu/tpiu0 + <file details> out:1 -> ../../../20070000.etr/tmc_etr0 + +Arriving at the final sink in the chain, ``tmc_etr0``:: + + linaro-developer:~# ls -l /sys/bus/coresight/devices/tmc_etr0/connections + <file details> cti_sys0 -> ../../../20020000.cti/cti_sys0 + <file details> in:0 -> ../../../20120000.replicator/replicator0 + <file details> nr_links + +As described below, when using sysfs it is sufficient to enable a sink and +a source for successful trace. The framework will correctly enable all +intermediate links as required. + +Note: ``cti_sys0`` appears in two of the connections lists above. +CTIs can connect to multiple devices and are arranged in a star topology +via the CTM. See (Documentation/trace/coresight/coresight-ect.rst) +[#fourth]_ for further details. +Looking at this device we see 4 connections:: + + linaro-developer:~# ls -l /sys/bus/coresight/devices/cti_sys0/connections + <file details> nr_links + <file details> stm0 -> ../../../20100000.stm/stm0 + <file details> tmc_etf0 -> ../../../20010000.etf/tmc_etf0 + <file details> tmc_etr0 -> ../../../20070000.etr/tmc_etr0 + <file details> tpiu0 -> ../../../20030000.tpiu/tpiu0 + + How to use the tracer modules ----------------------------- @@ -253,7 +339,8 @@ Preference is given to the former as using the sysFS interface requires a deep understanding of the Coresight HW. The following sections provide details on using both methods. -1) Using the sysFS interface: +Using the sysFS interface +~~~~~~~~~~~~~~~~~~~~~~~~~ Before trace collection can start, a coresight sink needs to be identified. There is no limit on the amount of sinks (nor sources) that can be enabled at @@ -360,7 +447,8 @@ wealth of possibilities that coresight provides. Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc} Timestamp Timestamp: 17107041535 -2) Using perf framework: +Using perf framework +~~~~~~~~~~~~~~~~~~~~ Coresight tracers are represented using the Perf framework's Performance Monitoring Unit (PMU) abstraction. As such the perf framework takes charge of @@ -409,7 +497,11 @@ More information on the above and other example on how to use Coresight with the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub repository [#third]_. -2.1) AutoFDO analysis using the perf tools: +Advanced perf framework usage +----------------------------- + +AutoFDO analysis using the perf tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ perf can be used to record and analyze trace of programs. @@ -427,9 +519,42 @@ The --itrace option controls the type and frequency of synthesized events Note that only 64-bit programs are currently supported - further work is required to support instruction decode of 32-bit Arm programs. +Tracing PID +~~~~~~~~~~~ + +The kernel can be built to write the PID value into the PE ContextID registers. +For a kernel running at EL1, the PID is stored in CONTEXTIDR_EL1. A PE may +implement Arm Virtualization Host Extensions (VHE), which the kernel can +run at EL2 as a virtualisation host; in this case, the PID value is stored in +CONTEXTIDR_EL2. + +perf provides PMU formats that program the ETM to insert these values into the +trace data; the PMU formats are defined as below: + + "contextid1": Available on both EL1 kernel and EL2 kernel. When the + kernel is running at EL1, "contextid1" enables the PID + tracing; when the kernel is running at EL2, this enables + tracing the PID of guest applications. + + "contextid2": Only usable when the kernel is running at EL2. When + selected, enables PID tracing on EL2 kernel. + + "contextid": Will be an alias for the option that enables PID + tracing. I.e, + contextid == contextid1, on EL1 kernel. + contextid == contextid2, on EL2 kernel. + +perf will always enable PID tracing at the relevant EL, this is accomplished by +automatically enable the "contextid" config - but for EL2 it is possible to make +specific adjustments using configs "contextid1" and "contextid2", E.g. if a user +wants to trace PIDs for both host and guest, the two configs "contextid1" and +"contextid2" can be set at the same time: + + perf record -e cs_etm/contextid1,contextid2/u -- vm + Generating coverage files for Feedback Directed Optimization: AutoFDO ---------------------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 'perf inject' accepts the --itrace option in which case tracing data is removed and replaced with the synthesized events. e.g. @@ -460,6 +585,49 @@ sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tuto Bubble sorting array of 30000 elements 5806 ms +Config option formats +~~~~~~~~~~~~~~~~~~~~~ + +The following strings can be provided between // on the perf command line to enable various options. +They are also listed in the folder /sys/bus/event_source/devices/cs_etm/format/ + +.. list-table:: + :header-rows: 1 + + * - Option + - Description + * - branch_broadcast + - Session local version of the system wide setting: + :ref:`ETM_MODE_BB <coresight-branch-broadcast>` + * - contextid + - See `Tracing PID`_ + * - contextid1 + - See `Tracing PID`_ + * - contextid2 + - See `Tracing PID`_ + * - configid + - Selection for a custom configuration. This is an implementation detail and not used directly, + see :ref:`trace/coresight/coresight-config:Using Configurations in perf` + * - preset + - Override for parameters in a custom configuration, see + :ref:`trace/coresight/coresight-config:Using Configurations in perf` + * - sinkid + - Hashed version of the string to select a sink, automatically set when using the @ notation. + This is an internal implementation detail and is not used directly, see `Using perf + framework`_. + * - cycacc + - Session local version of the system wide setting: :ref:`ETMv4_MODE_CYCACC + <coresight-cycle-accurate>` + * - retstack + - Session local version of the system wide setting: :ref:`ETM_MODE_RETURNSTACK + <coresight-return-stack>` + * - timestamp + - Session local version of the system wide setting: :ref:`ETMv4_MODE_TIMESTAMP + <coresight-timestamp>` + * - cc_threshold + - Cycle count threshold value. If nothing is provided here or the provided value is 0, then the + default value i.e 0x100 will be used. If provided value is less than minimum cycles threshold + value, as indicated via TRCIDR3.CCITMIN, then the minimum value will be used instead. How to use the STM module ------------------------- @@ -489,10 +657,39 @@ interface provided for that purpose by the generic STM API:: crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0 root@genericarmv8:~# -Details on how to use the generic STM API can be found here:- :doc:`../stm` [#second]_. +Details on how to use the generic STM API can be found here: +- Documentation/trace/stm.rst [#second]_. + +The CTI & CTM Modules +--------------------- + +The CTI (Cross Trigger Interface) provides a set of trigger signals between +individual CTIs and components, and can propagate these between all CTIs via +channels on the CTM (Cross Trigger Matrix). + +A separate documentation file is provided to explain the use of these devices. +(Documentation/trace/coresight/coresight-ect.rst) [#fourth]_. + +CoreSight System Configuration +------------------------------ + +CoreSight components can be complex devices with many programming options. +Furthermore, components can be programmed to interact with each other across the +complete system. + +A CoreSight System Configuration manager is provided to allow these complex programming +configurations to be selected and used easily from perf and sysfs. + +See the separate document for further information. +(Documentation/trace/coresight/coresight-config.rst) [#fifth]_. + .. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm .. [#second] Documentation/trace/stm.rst .. [#third] https://github.com/Linaro/perf-opencsd + +.. [#fourth] Documentation/trace/coresight/coresight-ect.rst + +.. [#fifth] Documentation/trace/coresight/coresight-config.rst diff --git a/Documentation/trace/coresight/ultrasoc-smb.rst b/Documentation/trace/coresight/ultrasoc-smb.rst new file mode 100644 index 000000000000..a05488a75ff0 --- /dev/null +++ b/Documentation/trace/coresight/ultrasoc-smb.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================== +UltraSoc - HW Assisted Tracing on SoC +====================================== + :Author: Qi Liu <liuqi115@huawei.com> + :Date: January 2023 + +Introduction +------------ + +UltraSoc SMB is a per SCCL (Super CPU Cluster) hardware. It provides a +way to buffer and store CPU trace messages in a region of shared system +memory. The device acts as a coresight sink device and the +corresponding trace generators (ETM) are attached as source devices. + +Sysfs files and directories +--------------------------- + +The SMB devices appear on the existing coresight bus alongside other +devices:: + + $# ls /sys/bus/coresight/devices/ + ultra_smb0 ultra_smb1 ultra_smb2 ultra_smb3 + +The ``ultra_smb<N>`` names SMB device associated with SCCL.:: + + $# ls /sys/bus/coresight/devices/ultra_smb0 + enable_sink mgmt + $# ls /sys/bus/coresight/devices/ultra_smb0/mgmt + buf_size buf_status read_pos write_pos + +Key file items are: + + * ``read_pos``: Shows the value on the read pointer register. + * ``write_pos``: Shows the value on the write pointer register. + * ``buf_status``: Shows the value on the status register. + BIT(0) is zero value which means the buffer is empty. + * ``buf_size``: Shows the buffer size of each device. + +Firmware Bindings +----------------- + +The device is only supported with ACPI. Its binding describes device +identifier, resource information and graph structure. + +The device is identified as ACPI HID "HISI03A1". Device resources are allocated +using the _CRS method. Each device must present two base address; the first one +is the configuration base address of the device, the second one is the 32-bit +base address of shared system memory. + +Example:: + + Device(USMB) { \ + Name(_HID, "HISI03A1") \ + Name(_CRS, ResourceTemplate() { \ + QWordMemory (ResourceConsumer, , MinFixed, MaxFixed, NonCacheable, \ + ReadWrite, 0x0, 0x95100000, 0x951FFFFF, 0x0, 0x100000) \ + QWordMemory (ResourceConsumer, , MinFixed, MaxFixed, Cacheable, \ + ReadWrite, 0x0, 0x50000000, 0x53FFFFFF, 0x0, 0x4000000) \ + }) \ + Name(_DSD, Package() { \ + ToUUID("ab02a46b-74c7-45a2-bd68-f7d344ef2153"), \ + /* Use CoreSight Graph ACPI bindings to describe connections topology */ + Package() { \ + 0, \ + 1, \ + Package() { \ + 1, \ + ToUUID("3ecbc8b6-1d0e-4fb3-8107-e627f805c6cd"), \ + 8, \ + Package() {0x8, 0, \_SB.S00.SL11.CL28.F008, 0}, \ + Package() {0x9, 0, \_SB.S00.SL11.CL29.F009, 0}, \ + Package() {0xa, 0, \_SB.S00.SL11.CL2A.F010, 0}, \ + Package() {0xb, 0, \_SB.S00.SL11.CL2B.F011, 0}, \ + Package() {0xc, 0, \_SB.S00.SL11.CL2C.F012, 0}, \ + Package() {0xd, 0, \_SB.S00.SL11.CL2D.F013, 0}, \ + Package() {0xe, 0, \_SB.S00.SL11.CL2E.F014, 0}, \ + Package() {0xf, 0, \_SB.S00.SL11.CL2F.F015, 0}, \ + } \ + } \ + }) \ + } |