0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ======================================
0004 CoreSight System Configuration Manager
0005 ======================================
0006
0007 :Author: Mike Leach <mike.leach@linaro.org>
0008 :Date: October 2020
0009
0010 Introduction
0011 ============
0012
0013 The CoreSight System Configuration manager is an API that allows the
0014 programming of the CoreSight system with pre-defined configurations that
0015 can then be easily enabled from sysfs or perf.
0016
0017 Many CoreSight components can be programmed in complex ways - especially ETMs.
0018 In addition, components can interact across the CoreSight system, often via
0019 the cross trigger components such as CTI and CTM. These system settings can
0020 be defined and enabled as named configurations.
0021
0022
0023 Basic Concepts
0024 ==============
0025
0026 This section introduces the basic concepts of a CoreSight system configuration.
0027
0028
0029 Features
0030 --------
0031
0032 A feature is a named set of programming for a CoreSight device. The programming
0033 is device dependent, and can be defined in terms of absolute register values,
0034 resource usage and parameter values.
0035
0036 The feature is defined using a descriptor. This descriptor is used to load onto
0037 a matching device, either when the feature is loaded into the system, or when the
0038 CoreSight device is registered with the configuration manager.
0039
0040 The load process involves interpreting the descriptor into a set of register
0041 accesses in the driver - the resource usage and parameter descriptions
0042 translated into appropriate register accesses. This interpretation makes it easy
0043 and efficient for the feature to be programmed onto the device when required.
0044
0045 The feature will not be active on the device until the feature is enabled, and
0046 the device itself is enabled. When the device is enabled then enabled features
0047 will be programmed into the device hardware.
0048
0049 A feature is enabled as part of a configuration being enabled on the system.
0050
0051
0052 Parameter Value
0053 ~~~~~~~~~~~~~~~
0054
0055 A parameter value is a named value that may be set by the user prior to the
0056 feature being enabled that can adjust the behaviour of the operation programmed
0057 by the feature.
0058
0059 For example, this could be a count value in a programmed operation that repeats
0060 at a given rate. When the feature is enabled then the current value of the
0061 parameter is used in programming the device.
0062
0063 The feature descriptor defines a default value for a parameter, which is used
0064 if the user does not supply a new value.
0065
0066 Users can update parameter values using the configfs API for the CoreSight
0067 system - which is described below.
0068
0069 The current value of the parameter is loaded into the device when the feature
0070 is enabled on that device.
0071
0072
0073 Configurations
0074 --------------
0075
0076 A configuration defines a set of features that are to be used in a trace
0077 session where the configuration is selected. For any trace session only one
0078 configuration may be selected.
0079
0080 The features defined may be on any type of device that is registered
0081 to support system configuration. A configuration may select features to be
0082 enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a
0083 specific CTI on the system.
0084
0085 As with the feature, a descriptor is used to define the configuration.
0086 This will define the features that must be enabled as part of the configuration
0087 as well as any preset values that can be used to override default parameter
0088 values.
0089
0090
0091 Preset Values
0092 ~~~~~~~~~~~~~
0093
0094 Preset values are easily selectable sets of parameter values for the features
0095 that the configuration uses. The number of values in a single preset set, equals
0096 the sum of parameter values in the features used by the configuration.
0097
0098 e.g. a configuration consists of 3 features, one has 2 parameters, one has
0099 a single parameter, and another has no parameters. A single preset set will
0100 therefore have 3 values.
0101
0102 Presets are optionally defined by the configuration, up to 15 can be defined.
0103 If no preset is selected, then the parameter values defined in the feature
0104 are used as normal.
0105
0106
0107 Operation
0108 ~~~~~~~~~
0109
0110 The following steps take place in the operation of a configuration.
0111
0112 1) In this example, the configuration is 'autofdo', which has an
0113 associated feature 'strobing' that works on ETMv4 CoreSight Devices.
0114
0115 2) The configuration is enabled. For example 'perf' may select the
0116 configuration as part of its command line::
0117
0118 perf record -e cs_etm/autofdo/ myapp
0119
0120 which will enable the 'autofdo' configuration.
0121
0122 3) perf starts tracing on the system. As each ETMv4 that perf uses for
0123 trace is enabled, the configuration manager will check if the ETMv4
0124 has a feature that relates to the currently active configuration.
0125 In this case 'strobing' is enabled & programmed into the ETMv4.
0126
0127 4) When the ETMv4 is disabled, any registers marked as needing to be
0128 saved will be read back.
0129
0130 5) At the end of the perf session, the configuration will be disabled.
0131
0132
0133 Viewing Configurations and Features
0134 ===================================
0135
0136 The set of configurations and features that are currently loaded into the
0137 system can be viewed using the configfs API.
0138
0139 Mount configfs as normal and the 'cs-syscfg' subsystem will appear::
0140
0141 $ ls /config
0142 cs-syscfg stp-policy
0143
0144 This has two sub-directories::
0145
0146 $ cd cs-syscfg/
0147 $ ls
0148 configurations features
0149
0150 The system has the configuration 'autofdo' built in. It may be examined as
0151 follows::
0152
0153 $ cd configurations/
0154 $ ls
0155 autofdo
0156 $ cd autofdo/
0157 $ ls
0158 description feature_refs preset1 preset3 preset5 preset7 preset9
0159 enable preset preset2 preset4 preset6 preset8
0160 $ cat description
0161 Setup ETMs with strobing for autofdo
0162 $ cat feature_refs
0163 strobing
0164
0165 Each preset declared has a 'preset<n>' subdirectory declared. The values for
0166 the preset can be examined::
0167
0168 $ cat preset1/values
0169 strobing.window = 0x1388 strobing.period = 0x2
0170 $ cat preset2/values
0171 strobing.window = 0x1388 strobing.period = 0x4
0172
0173 The 'enable' and 'preset' files allow the control of a configuration when
0174 using CoreSight with sysfs.
0175
0176 The features referenced by the configuration can be examined in the features
0177 directory::
0178
0179 $ cd ../../features/strobing/
0180 $ ls
0181 description matches nr_params params
0182 $ cat description
0183 Generate periodic trace capture windows.
0184 parameter 'window': a number of CPU cycles (W)
0185 parameter 'period': trace enabled for W cycles every period x W cycles
0186 $ cat matches
0187 SRC_ETMV4
0188 $ cat nr_params
0189 2
0190
0191 Move to the params directory to examine and adjust parameters::
0192
0193 cd params
0194 $ ls
0195 period window
0196 $ cd period
0197 $ ls
0198 value
0199 $ cat value
0200 0x2710
0201 # echo 15000 > value
0202 # cat value
0203 0x3a98
0204
0205 Parameters adjusted in this way are reflected in all device instances that have
0206 loaded the feature.
0207
0208
0209 Using Configurations in perf
0210 ============================
0211
0212 The configurations loaded into the CoreSight configuration management are
0213 also declared in the perf 'cs_etm' event infrastructure so that they can
0214 be selected when running trace under perf::
0215
0216 $ ls /sys/devices/cs_etm
0217 cpu0 cpu2 events nr_addr_filters power subsystem uevent
0218 cpu1 cpu3 format perf_event_mux_interval_ms sinks type
0219
0220 The key directory here is 'events' - a generic perf directory which allows
0221 selection on the perf command line. As with the sinks entries, this provides
0222 a hash of the configuration name.
0223
0224 The entry in the 'events' directory uses perfs built in syntax generator
0225 to substitute the syntax for the name when evaluating the command::
0226
0227 $ ls events/
0228 autofdo
0229 $ cat events/autofdo
0230 configid=0xa7c3dddd
0231
0232 The 'autofdo' configuration may be selected on the perf command line::
0233
0234 $ perf record -e cs_etm/autofdo/u --per-thread <application>
0235
0236 A preset to override the current parameter values can also be selected::
0237
0238 $ perf record -e cs_etm/autofdo,preset=1/u --per-thread <application>
0239
0240 When configurations are selected in this way, then the trace sink used is
0241 automatically selected.
0242
0243 Using Configurations in sysfs
0244 =============================
0245
0246 Coresight can be controlled using sysfs. When this is in use then a configuration
0247 can be made active for the devices that are used in the sysfs session.
0248
0249 In a configuration there are 'enable' and 'preset' files.
0250
0251 To enable a configuration for use with sysfs::
0252
0253 $ cd configurations/autofdo
0254 $ echo 1 > enable
0255
0256 This will then use any default parameter values in the features - which can be
0257 adjusted as described above.
0258
0259 To use a preset<n> set of parameter values::
0260
0261 $ echo 3 > preset
0262
0263 This will select preset3 for the configuration.
0264 The valid values for preset are 0 - to deselect presets, and any value of
0265 <n> where a preset<n> sub-directory is present.
0266
0267 Note that the active sysfs configuration is a global parameter, therefore
0268 only a single configuration can be active for sysfs at any one time.
0269 Attempting to enable a second configuration will result in an error.
0270 Additionally, attempting to disable the configuration while in use will
0271 also result in an error.
0272
0273 The use of the active configuration by sysfs is independent of the configuration
0274 used in perf.
0275
0276
0277 Creating and Loading Custom Configurations
0278 ==========================================
0279
0280 Custom configurations and / or features can be dynamically loaded into the
0281 system by using a loadable module.
0282
0283 An example of a custom configuration is found in ./samples/coresight.
0284
0285 This creates a new configuration that uses the existing built in
0286 strobing feature, but provides a different set of presets.
0287
0288 When the module is loaded, then the configuration appears in the configfs
0289 file system and is selectable in the same way as the built in configuration
0290 described above.
0291
0292 Configurations can use previously loaded features. The system will ensure
0293 that it is not possible to unload a feature that is currently in use, by
0294 enforcing the unload order as the strict reverse of the load order.
