Documentation/trace/coresight/coresight-config.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ======================================
   4 CoreSight System Configuration Manager
   5 ======================================
   6
   7     :Author:   Mike Leach <mike.leach@linaro.org>
   8     :Date:     October 2020
   9
  10 Introduction
  11 ============
  12
  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.
  16
  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.
  21
  22
  23 Basic Concepts
  24 ==============
  25
  26 This section introduces the basic concepts of a CoreSight system configuration.
  27
  28
  29 Features
  30 --------
  31
  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.
  35
  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.
  39
  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.
  44
  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.
  48
  49 A feature is enabled as part of a configuration being enabled on the system.
  50
  51
  52 Parameter Value
  53 ~~~~~~~~~~~~~~~
  54
  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
  57 by the feature.
  58
  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.
  62
  63 The feature descriptor defines a default value for a parameter, which is used
  64 if the user does not supply a new value.
  65
  66 Users can update parameter values using the configfs API for the CoreSight
  67 system - which is described below.
  68
  69 The current value of the parameter is loaded into the device when the feature
  70 is enabled on that device.
  71
  72
  73 Configurations
  74 --------------
  75
  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.
  79
  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.
  84
  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
  88 values.
  89
  90
  91 Preset Values
  92 ~~~~~~~~~~~~~
  93
  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.
  97
  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.
 101
 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
 104 are used as normal.
 105
 106
 107 Operation
 108 ~~~~~~~~~
 109
 110 The following steps take place in the operation of a configuration.
 111
 112 1) In this example, the configuration is 'autofdo', which has an
 113    associated feature 'strobing' that works on ETMv4 CoreSight Devices.
 114
 115 2) The configuration is enabled. For example 'perf' may select the
 116    configuration as part of its command line::
 117
 118     perf record -e cs_etm/autofdo/ myapp
 119
 120    which will enable the 'autofdo' configuration.
 121
 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.
 126
 127 4) When the ETMv4 is disabled, any registers marked as needing to be
 128    saved will be read back.
 129
 130 5) At the end of the perf session, the configuration will be disabled.
 131
 132
 133 Viewing Configurations and Features
 134 ===================================
 135
 136 The set of configurations and features that are currently loaded into the
 137 system can be viewed using the configfs API.
 138
 139 Mount configfs as normal and the 'cs-syscfg' subsystem will appear::
 140
 141     $ ls /config
 142     cs-syscfg  stp-policy
 143
 144 This has two sub-directories::
 145
 146     $ cd cs-syscfg/
 147     $ ls
 148     configurations  features
 149
 150 The system has the configuration 'autofdo' built in. It may be examined as
 151 follows::
 152
 153     $ cd configurations/
 154     $ ls
 155     autofdo
 156     $ cd autofdo/
 157     $ ls
 158     description  feature_refs  preset1  preset3  preset5  preset7  preset9
 159     enable       preset        preset2  preset4  preset6  preset8
 160     $ cat description
 161     Setup ETMs with strobing for autofdo
 162     $ cat feature_refs
 163     strobing
 164
 165 Each preset declared has a 'preset<n>' subdirectory declared. The values for
 166 the preset can be examined::
 167
 168     $ cat preset1/values
 169     strobing.window = 0x1388 strobing.period = 0x2
 170     $ cat preset2/values
 171     strobing.window = 0x1388 strobing.period = 0x4
 172
 173 The 'enable' and 'preset' files allow the control of a configuration when
 174 using CoreSight with sysfs.
 175
 176 The features referenced by the configuration can be examined in the features
 177 directory::
 178
 179     $ cd ../../features/strobing/
 180     $ ls
 181     description  matches  nr_params  params
 182     $ cat description
 183     Generate periodic trace capture windows.
 184     parameter 'window': a number of CPU cycles (W)
 185     parameter 'period': trace enabled for W cycles every period x W cycles
 186     $ cat matches
 187     SRC_ETMV4
 188     $ cat nr_params
 189     2
 190
 191 Move to the params directory to examine and adjust parameters::
 192
 193     cd params
 194     $ ls
 195     period  window
 196     $ cd period
 197     $ ls
 198     value
 199     $ cat value
 200     0x2710
 201     # echo 15000 > value
 202     # cat value
 203     0x3a98
 204
 205 Parameters adjusted in this way are reflected in all device instances that have
 206 loaded the feature.
 207
 208
 209 Using Configurations in perf
 210 ============================
 211
 212 The configurations loaded into the CoreSight configuration management are
 213 also declared in the perf 'cs_etm' event infrastructure so that they can
 214 be selected when running trace under perf::
 215
 216     $ ls /sys/devices/cs_etm
 217     cpu0  cpu2  events  nr_addr_filters         power  subsystem  uevent
 218     cpu1  cpu3  format  perf_event_mux_interval_ms      sinks  type
 219
 220 The key directory here is 'events' - a generic perf directory which allows
 221 selection on the perf command line. As with the sinks entries, this provides
 222 a hash of the configuration name.
 223
 224 The entry in the 'events' directory uses perfs built in syntax generator
 225 to substitute the syntax for the name when evaluating the command::
 226
 227     $ ls events/
 228     autofdo
 229     $ cat events/autofdo
 230     configid=0xa7c3dddd
 231
 232 The 'autofdo' configuration may be selected on the perf command line::
 233
 234     $ perf record -e cs_etm/autofdo/u --per-thread <application>
 235
 236 A preset to override the current parameter values can also be selected::
 237
 238     $ perf record -e cs_etm/autofdo,preset=1/u --per-thread <application>
 239
 240 When configurations are selected in this way, then the trace sink used is
 241 automatically selected.
 242
 243 Using Configurations in sysfs
 244 =============================
 245
 246 Coresight can be controlled using sysfs. When this is in use then a configuration
 247 can be made active for the devices that are used in the sysfs session.
 248
 249 In a configuration there are 'enable' and 'preset' files.
 250
 251 To enable a configuration for use with sysfs::
 252
 253     $ cd configurations/autofdo
 254     $ echo 1 > enable
 255
 256 This will then use any default parameter values in the features - which can be
 257 adjusted as described above.
 258
 259 To use a preset<n> set of parameter values::
 260
 261     $ echo 3 > preset
 262
 263 This will select preset3 for the configuration.
 264 The valid values for preset are 0 - to deselect presets, and any value of
 265 <n> where a preset<n> sub-directory is present.
 266
 267 Note that the active sysfs configuration is a global parameter, therefore
 268 only a single configuration can be active for sysfs at any one time.
 269 Attempting to enable a second configuration will result in an error.
 270 Additionally, attempting to disable the configuration while in use will
 271 also result in an error.
 272
 273 The use of the active configuration by sysfs is independent of the configuration
 274 used in perf.
 275
 276
 277 Creating and Loading Custom Configurations
 278 ==========================================
 279
 280 Custom configurations and / or features can be dynamically loaded into the
 281 system by using a loadable module.
 282
 283 An example of a custom configuration is found in ./samples/coresight.
 284
 285 This creates a new configuration that uses the existing built in
 286 strobing feature, but provides a different set of presets.
 287
 288 When the module is loaded, then the configuration appears in the configfs
 289 file system and is selectable in the same way as the built in configuration
 290 described above.
 291
 292 Configurations can use previously loaded features. The system will ensure
 293 that it is not possible to unload a feature that is currently in use, by
 294 enforcing the unload order as the strict reverse of the load order.