1 .. SPDX-License-Identifier: GPL-2.0
3 ======================================
4 CoreSight System Configuration Manager
5 ======================================
7 :Author: Mike Leach <mike.leach@linaro.org>
13 The CoreSight System Configuration manager is an API that allows the
14 programming of the CoreSight system with pre-defined configurations that
15 can then be easily enabled from sysfs or perf.
17 Many CoreSight components can be programmed in complex ways - especially ETMs.
18 In addition, components can interact across the CoreSight system, often via
19 the cross trigger components such as CTI and CTM. These system settings can
20 be defined and enabled as named configurations.
26 This section introduces the basic concepts of a CoreSight system configuration.
32 A feature is a named set of programming for a CoreSight device. The programming
33 is device dependent, and can be defined in terms of absolute register values,
34 resource usage and parameter values.
36 The feature is defined using a descriptor. This descriptor is used to load onto
37 a matching device, either when the feature is loaded into the system, or when the
38 CoreSight device is registered with the configuration manager.
40 The load process involves interpreting the descriptor into a set of register
41 accesses in the driver - the resource usage and parameter descriptions
42 translated into appropriate register accesses. This interpretation makes it easy
43 and efficient for the feature to be programmed onto the device when required.
45 The feature will not be active on the device until the feature is enabled, and
46 the device itself is enabled. When the device is enabled then enabled features
47 will be programmed into the device hardware.
49 A feature is enabled as part of a configuration being enabled on the system.
55 A parameter value is a named value that may be set by the user prior to the
56 feature being enabled that can adjust the behaviour of the operation programmed
59 For example, this could be a count value in a programmed operation that repeats
60 at a given rate. When the feature is enabled then the current value of the
61 parameter is used in programming the device.
63 The feature descriptor defines a default value for a parameter, which is used
64 if the user does not supply a new value.
66 Users can update parameter values using the configfs API for the CoreSight
67 system - which is described below.
69 The current value of the parameter is loaded into the device when the feature
70 is enabled on that device.
76 A configuration defines a set of features that are to be used in a trace
77 session where the configuration is selected. For any trace session only one
78 configuration may be selected.
80 The features defined may be on any type of device that is registered
81 to support system configuration. A configuration may select features to be
82 enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a
83 specific CTI on the system.
85 As with the feature, a descriptor is used to define the configuration.
86 This will define the features that must be enabled as part of the configuration
87 as well as any preset values that can be used to override default parameter
94 Preset values are easily selectable sets of parameter values for the features
95 that the configuration uses. The number of values in a single preset set, equals
96 the sum of parameter values in the features used by the configuration.
98 e.g. a configuration consists of 3 features, one has 2 parameters, one has
99 a single parameter, and another has no parameters. A single preset set will
100 therefore have 3 values.
102 Presets are optionally defined by the configuration, up to 15 can be defined.
103 If no preset is selected, then the parameter values defined in the feature
110 The following steps take place in the operation of a configuration.
112 1) In this example, the configuration is 'autofdo', which has an
113 associated feature 'strobing' that works on ETMv4 CoreSight Devices.
115 2) The configuration is enabled. For example 'perf' may select the
116 configuration as part of its command line::
118 perf record -e cs_etm/autofdo/ myapp
120 which will enable the 'autofdo' configuration.
122 3) perf starts tracing on the system. As each ETMv4 that perf uses for
123 trace is enabled, the configuration manager will check if the ETMv4
124 has a feature that relates to the currently active configuration.
125 In this case 'strobing' is enabled & programmed into the ETMv4.
127 4) When the ETMv4 is disabled, any registers marked as needing to be
128 saved will be read back.
130 5) At the end of the perf session, the configuration will be disabled.
133 Viewing Configurations and Features
134 ===================================
136 The set of configurations and features that are currently loaded into the
137 system can be viewed using the configfs API.
139 Mount configfs as normal and the 'cs-syscfg' subsystem will appear::
144 This has two sub-directories::
148 configurations features
150 The system has the configuration 'autofdo' built in. It may be examined as
158 description preset1 preset3 preset5 preset7 preset9
159 feature_refs preset2 preset4 preset6 preset8
161 Setup ETMs with strobing for autofdo
165 Each preset declared has a preset<n> subdirectory declared. The values for
166 the preset can be examined::
169 strobing.window = 0x1388 strobing.period = 0x2
171 strobing.window = 0x1388 strobing.period = 0x4
173 The features referenced by the configuration can be examined in the features
176 $ cd ../../features/strobing/
178 description matches nr_params params
180 Generate periodic trace capture windows.
181 parameter 'window': a number of CPU cycles (W)
182 parameter 'period': trace enabled for W cycles every period x W cycles
188 Move to the params directory to examine and adjust parameters::
202 Parameters adjusted in this way are reflected in all device instances that have
206 Using Configurations in perf
207 ============================
209 The configurations loaded into the CoreSight configuration management are
210 also declared in the perf 'cs_etm' event infrastructure so that they can
211 be selected when running trace under perf::
213 $ ls /sys/devices/cs_etm
214 cpu0 cpu2 events nr_addr_filters power subsystem uevent
215 cpu1 cpu3 format perf_event_mux_interval_ms sinks type
217 The key directory here is 'events' - a generic perf directory which allows
218 selection on the perf command line. As with the sinks entries, this provides
219 a hash of the configuration name.
221 The entry in the 'events' directory uses perfs built in syntax generator
222 to substitute the syntax for the name when evaluating the command::
229 The 'autofdo' configuration may be selected on the perf command line::
231 $ perf record -e cs_etm/autofdo/u --per-thread <application>
233 A preset to override the current parameter values can also be selected::
235 $ perf record -e cs_etm/autofdo,preset=1/u --per-thread <application>
237 When configurations are selected in this way, then the trace sink used is
238 automatically selected.