295 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3======================================4CoreSight System Configuration Manager5======================================6 7 :Author: Mike Leach <mike.leach@linaro.org>8 :Date: October 20209 10Introduction11============12 13The CoreSight System Configuration manager is an API that allows the14programming of the CoreSight system with pre-defined configurations that15can then be easily enabled from sysfs or perf.16 17Many CoreSight components can be programmed in complex ways - especially ETMs.18In addition, components can interact across the CoreSight system, often via19the cross trigger components such as CTI and CTM. These system settings can20be defined and enabled as named configurations.21 22 23Basic Concepts24==============25 26This section introduces the basic concepts of a CoreSight system configuration.27 28 29Features30--------31 32A feature is a named set of programming for a CoreSight device. The programming33is device dependent, and can be defined in terms of absolute register values,34resource usage and parameter values.35 36The feature is defined using a descriptor. This descriptor is used to load onto37a matching device, either when the feature is loaded into the system, or when the38CoreSight device is registered with the configuration manager.39 40The load process involves interpreting the descriptor into a set of register41accesses in the driver - the resource usage and parameter descriptions42translated into appropriate register accesses. This interpretation makes it easy43and efficient for the feature to be programmed onto the device when required.44 45The feature will not be active on the device until the feature is enabled, and46the device itself is enabled. When the device is enabled then enabled features47will be programmed into the device hardware.48 49A feature is enabled as part of a configuration being enabled on the system.50 51 52Parameter Value53~~~~~~~~~~~~~~~54 55A parameter value is a named value that may be set by the user prior to the56feature being enabled that can adjust the behaviour of the operation programmed57by the feature.58 59For example, this could be a count value in a programmed operation that repeats60at a given rate. When the feature is enabled then the current value of the61parameter is used in programming the device.62 63The feature descriptor defines a default value for a parameter, which is used64if the user does not supply a new value.65 66Users can update parameter values using the configfs API for the CoreSight67system - which is described below.68 69The current value of the parameter is loaded into the device when the feature70is enabled on that device.71 72 73Configurations74--------------75 76A configuration defines a set of features that are to be used in a trace77session where the configuration is selected. For any trace session only one78configuration may be selected.79 80The features defined may be on any type of device that is registered81to support system configuration. A configuration may select features to be82enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a83specific CTI on the system.84 85As with the feature, a descriptor is used to define the configuration.86This will define the features that must be enabled as part of the configuration87as well as any preset values that can be used to override default parameter88values.89 90 91Preset Values92~~~~~~~~~~~~~93 94Preset values are easily selectable sets of parameter values for the features95that the configuration uses. The number of values in a single preset set, equals96the sum of parameter values in the features used by the configuration.97 98e.g. a configuration consists of 3 features, one has 2 parameters, one has99a single parameter, and another has no parameters. A single preset set will100therefore have 3 values.101 102Presets are optionally defined by the configuration, up to 15 can be defined.103If no preset is selected, then the parameter values defined in the feature104are used as normal.105 106 107Operation108~~~~~~~~~109 110The following steps take place in the operation of a configuration.111 1121) In this example, the configuration is 'autofdo', which has an113 associated feature 'strobing' that works on ETMv4 CoreSight Devices.114 1152) The configuration is enabled. For example 'perf' may select the116 configuration as part of its command line::117 118 perf record -e cs_etm/autofdo/ myapp119 120 which will enable the 'autofdo' configuration.121 1223) perf starts tracing on the system. As each ETMv4 that perf uses for123 trace is enabled, the configuration manager will check if the ETMv4124 has a feature that relates to the currently active configuration.125 In this case 'strobing' is enabled & programmed into the ETMv4.126 1274) When the ETMv4 is disabled, any registers marked as needing to be128 saved will be read back.129 1305) At the end of the perf session, the configuration will be disabled.131 132 133Viewing Configurations and Features134===================================135 136The set of configurations and features that are currently loaded into the137system can be viewed using the configfs API.138 139Mount configfs as normal and the 'cs-syscfg' subsystem will appear::140 141 $ ls /config142 cs-syscfg stp-policy143 144This has two sub-directories::145 146 $ cd cs-syscfg/147 $ ls148 configurations features149 150The system has the configuration 'autofdo' built in. It may be examined as151follows::152 153 $ cd configurations/154 $ ls155 autofdo156 $ cd autofdo/157 $ ls158 description feature_refs preset1 preset3 preset5 preset7 preset9159 enable preset preset2 preset4 preset6 preset8160 $ cat description161 Setup ETMs with strobing for autofdo162 $ cat feature_refs163 strobing164 165Each preset declared has a 'preset<n>' subdirectory declared. The values for166the preset can be examined::167 168 $ cat preset1/values169 strobing.window = 0x1388 strobing.period = 0x2170 $ cat preset2/values171 strobing.window = 0x1388 strobing.period = 0x4172 173The 'enable' and 'preset' files allow the control of a configuration when174using CoreSight with sysfs.175 176The features referenced by the configuration can be examined in the features177directory::178 179 $ cd ../../features/strobing/180 $ ls181 description matches nr_params params182 $ cat description183 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 cycles186 $ cat matches187 SRC_ETMV4188 $ cat nr_params189 2190 191Move to the params directory to examine and adjust parameters::192 193 cd params194 $ ls195 period window196 $ cd period197 $ ls198 value199 $ cat value200 0x2710201 # echo 15000 > value202 # cat value203 0x3a98204 205Parameters adjusted in this way are reflected in all device instances that have206loaded the feature.207 208 209Using Configurations in perf210============================211 212The configurations loaded into the CoreSight configuration management are213also declared in the perf 'cs_etm' event infrastructure so that they can214be selected when running trace under perf::215 216 $ ls /sys/devices/cs_etm217 cpu0 cpu2 events nr_addr_filters power subsystem uevent218 cpu1 cpu3 format perf_event_mux_interval_ms sinks type219 220The key directory here is 'events' - a generic perf directory which allows221selection on the perf command line. As with the sinks entries, this provides222a hash of the configuration name.223 224The entry in the 'events' directory uses perfs built in syntax generator225to substitute the syntax for the name when evaluating the command::226 227 $ ls events/228 autofdo229 $ cat events/autofdo230 configid=0xa7c3dddd231 232The 'autofdo' configuration may be selected on the perf command line::233 234 $ perf record -e cs_etm/autofdo/u --per-thread <application>235 236A 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 240When configurations are selected in this way, then the trace sink used is241automatically selected.242 243Using Configurations in sysfs244=============================245 246Coresight can be controlled using sysfs. When this is in use then a configuration247can be made active for the devices that are used in the sysfs session.248 249In a configuration there are 'enable' and 'preset' files.250 251To enable a configuration for use with sysfs::252 253 $ cd configurations/autofdo254 $ echo 1 > enable255 256This will then use any default parameter values in the features - which can be257adjusted as described above.258 259To use a preset<n> set of parameter values::260 261 $ echo 3 > preset262 263This will select preset3 for the configuration.264The valid values for preset are 0 - to deselect presets, and any value of265<n> where a preset<n> sub-directory is present.266 267Note that the active sysfs configuration is a global parameter, therefore268only a single configuration can be active for sysfs at any one time.269Attempting to enable a second configuration will result in an error.270Additionally, attempting to disable the configuration while in use will271also result in an error.272 273The use of the active configuration by sysfs is independent of the configuration274used in perf.275 276 277Creating and Loading Custom Configurations278==========================================279 280Custom configurations and / or features can be dynamically loaded into the281system by using a loadable module.282 283An example of a custom configuration is found in ./samples/coresight.284 285This creates a new configuration that uses the existing built in286strobing feature, but provides a different set of presets.287 288When the module is loaded, then the configuration appears in the configfs289file system and is selectable in the same way as the built in configuration290described above.291 292Configurations can use previously loaded features. The system will ensure293that it is not possible to unload a feature that is currently in use, by294enforcing the unload order as the strict reverse of the load order.295