On Fri, Oct 30, 2020 at 05:56:55PM +0000, Mike Leach wrote:
Adds documentation for the CoreSight System configuration manager.
Signed-off-by: Mike Leach mike.leach@linaro.org
.../trace/coresight/coresight-config.rst | 230 ++++++++++++++++++ Documentation/trace/coresight/coresight.rst | 16 ++ 2 files changed, 246 insertions(+) create mode 100644 Documentation/trace/coresight/coresight-config.rst
diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst new file mode 100644 index 000000000000..8afcf18c090c --- /dev/null +++ b/Documentation/trace/coresight/coresight-config.rst @@ -0,0 +1,230 @@ +.. 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 complex 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 +device is registered with the configuration manager.
In the above paragraph I would explicitly write "coresight device" when referring to a device. That way there is no doubt as to what is happening.
+The load process involves interpreting the descriptor into a the set of register
s/into a the set/into a set/
+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.
If I understand correctly the above paragraph is for the sysfs and configfs interfaces. From perf enabling feature and devices doesn't apply.
+A feature can be enabled either as part of a configuration being enabled on the +system, or individually on a device instance using the configfs API.
+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.
+Virtual Device +--------------
+The CoreSight System Configuration manager also includes a virtual CoreSight +device. This provides the system with access to kernel objects and device +management to own elements such as the sysfs entries used to expose the +configurations into the cs_etm event in perf.
+This device 'system_cfg' appears on a custom bus - 'coresight-config' - +rather than the normal 'coresight' bus to avoid complications when the +coresight system is searching for real devices on the bus.
+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 'coresight-syscfg' subsystem will appear::
- $ ls /config
- coresight-syscfg stp-policy
+This has two sub-directories::
- $ cd coresight-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 nr_presets preset_values refs
- $ cat description
- Setup ETMs with strobing for autofdo
- $ cat refs
- references 1 features:-
- strobing
- $ cat nr_presets
- 2
- $ cat preset_values
- 2 presets, 2 parameters per preset
- preset[1]: strobing.window = 0x2710 strobing.period = 0x1388
- preset[2]: strobing.window = 0x1388 strobing.period = 0x1388
+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
- configurations format perf_event_mux_interval_ms sinks type
- events nr_addr_filters power
+Key directories here are 'configurations' - which lists the loaded +configurations, and 'events' - a generic perf directory which allows +selection on the perf command line.::
- $ ls configurations/
- autofdo
- $ cat configurations/autofdo
- 0xa7c3dddd
+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. diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst index 0b73acb44efa..0122d9bebf35 100644 --- a/Documentation/trace/coresight/coresight.rst +++ b/Documentation/trace/coresight/coresight.rst @@ -587,6 +587,20 @@ A separate documentation file is provided to explain the use of these devices. (:doc:`coresight-ect`) [#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. +(:doc:`coresight-config`) [#fifth]_.
.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm .. [#second] Documentation/trace/stm.rst @@ -594,3 +608,5 @@ A separate documentation file is provided to explain the use of these devices. .. [#third] https://github.com/Linaro/perf-opencsd .. [#fourth] Documentation/trace/coresight/coresight-ect.rst
+.. [#fifth] Documentation/trace/coresight/coresight-config.rst
2.17.1