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   preset1  preset3  preset5  preset7  preset9
 159     feature_refs  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 features referenced by the configuration can be examined in the features
 174 directory::
 175
 176     $ cd ../../features/strobing/
 177     $ ls
 178     description  matches  nr_params  params
 179     $ cat description
 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
 183     $ cat matches
 184     SRC_ETMV4
 185     $ cat nr_params
 186     2
 187
 188 Move to the params directory to examine and adjust parameters::
 189
 190     cd params
 191     $ ls
 192     period  window
 193     $ cd period
 194     $ ls
 195     value
 196     $ cat value
 197     0x2710
 198     # echo 15000 > value
 199     # cat value
 200     0x3a98
 201
 202 Parameters adjusted in this way are reflected in all device instances that have
 203 loaded the feature.
 204
 205
 206 Using Configurations in perf
 207 ============================
 208
 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::
 212
 213     $ ls /sys/devices/cs_etm
 214     configurations  format  perf_event_mux_interval_ms  sinks  type
 215     events  nr_addr_filters  power
 216
 217 Key directories here are 'configurations' - which lists the loaded
 218 configurations, and 'events' - a generic perf directory which allows
 219 selection on the perf command line.::
 220
 221     $ ls configurations/
 222     autofdo
 223     $ cat configurations/autofdo
 224     0xa7c3dddd
 225
 226 As with the sinks entries, this provides a hash of the configuration name.
 227 The entry in the 'events' directory uses perfs built in syntax generator
 228 to substitute the syntax for the name when evaluating the command::
 229
 230     $ ls events/
 231     autofdo
 232     $ cat events/autofdo
 233     configid=0xa7c3dddd
 234
 235 The 'autofdo' configuration may be selected on the perf command line::
 236
 237     $ perf record -e cs_etm/autofdo/u --per-thread <application>
 238
 239 A preset to override the current parameter values can also be selected::
 240
 241     $ perf record -e cs_etm/autofdo,preset=1/u --per-thread <application>
 242
 243 When configurations are selected in this way, then the trace sink used is
 244 automatically selected.