1.. SPDX-License-Identifier: GPL-2.0 2 3====================================== 4CoreSight System Configuration Manager 5====================================== 6 7 :Author: Mike Leach <mike.leach@linaro.org> 8 :Date: October 2020 9 10Introduction 11============ 12 13The CoreSight System Configuration manager is an API that allows the 14programming of the CoreSight system with pre-defined configurations that 15can 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 via 19the cross trigger components such as CTI and CTM. These system settings can 20be defined and enabled as named configurations. 21 22 23Basic Concepts 24============== 25 26This section introduces the basic concepts of a CoreSight system configuration. 27 28 29Features 30-------- 31 32A feature is a named set of programming for a CoreSight device. The programming 33is 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 onto 37a matching device, either when the feature is loaded into the system, or when the 38CoreSight device is registered with the configuration manager. 39 40The load process involves interpreting the descriptor into a set of register 41accesses in the driver - the resource usage and parameter descriptions 42translated into appropriate register accesses. This interpretation makes it easy 43and 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, and 46the device itself is enabled. When the device is enabled then enabled features 47will be programmed into the device hardware. 48 49A feature is enabled as part of a configuration being enabled on the system. 50 51 52Parameter Value 53~~~~~~~~~~~~~~~ 54 55A parameter value is a named value that may be set by the user prior to the 56feature being enabled that can adjust the behaviour of the operation programmed 57by the feature. 58 59For example, this could be a count value in a programmed operation that repeats 60at a given rate. When the feature is enabled then the current value of the 61parameter is used in programming the device. 62 63The feature descriptor defines a default value for a parameter, which is used 64if the user does not supply a new value. 65 66Users can update parameter values using the configfs API for the CoreSight 67system - which is described below. 68 69The current value of the parameter is loaded into the device when the feature 70is enabled on that device. 71 72 73Configurations 74-------------- 75 76A configuration defines a set of features that are to be used in a trace 77session where the configuration is selected. For any trace session only one 78configuration may be selected. 79 80The features defined may be on any type of device that is registered 81to support system configuration. A configuration may select features to be 82enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a 83specific 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 configuration 87as well as any preset values that can be used to override default parameter 88values. 89 90 91Preset Values 92~~~~~~~~~~~~~ 93 94Preset values are easily selectable sets of parameter values for the features 95that the configuration uses. The number of values in a single preset set, equals 96the 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 has 99a single parameter, and another has no parameters. A single preset set will 100therefore 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 feature 104are used as normal. 105 106 107Operation 108~~~~~~~~~ 109 110The following steps take place in the operation of a configuration. 111 1121) In this example, the configuration is 'autofdo', which has an 113 associated feature 'strobing' that works on ETMv4 CoreSight Devices. 114 1152) 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 1223) 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 1274) When the ETMv4 is disabled, any registers marked as needing to be 128 saved will be read back. 129 1305) At the end of the perf session, the configuration will be disabled. 131 132 133Viewing Configurations and Features 134=================================== 135 136The set of configurations and features that are currently loaded into the 137system can be viewed using the configfs API. 138 139Mount configfs as normal and the 'cs-syscfg' subsystem will appear:: 140 141 $ ls /config 142 cs-syscfg stp-policy 143 144This has two sub-directories:: 145 146 $ cd cs-syscfg/ 147 $ ls 148 configurations features 149 150The system has the configuration 'autofdo' built in. It may be examined as 151follows:: 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 165Each preset declared has a 'preset<n>' subdirectory declared. The values for 166the 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 173The 'enable' and 'preset' files allow the control of a configuration when 174using CoreSight with sysfs. 175 176The features referenced by the configuration can be examined in the features 177directory:: 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 191Move 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 205Parameters adjusted in this way are reflected in all device instances that have 206loaded the feature. 207 208 209Using Configurations in perf 210============================ 211 212The configurations loaded into the CoreSight configuration management are 213also declared in the perf 'cs_etm' event infrastructure so that they can 214be 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 220The key directory here is 'events' - a generic perf directory which allows 221selection on the perf command line. As with the sinks entries, this provides 222a hash of the configuration name. 223 224The entry in the 'events' directory uses perfs built in syntax generator 225to substitute the syntax for the name when evaluating the command:: 226 227 $ ls events/ 228 autofdo 229 $ cat events/autofdo 230 configid=0xa7c3dddd 231 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 is 241automatically selected. 242 243Using Configurations in sysfs 244============================= 245 246Coresight can be controlled using sysfs. When this is in use then a configuration 247can 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/autofdo 254 $ echo 1 > enable 255 256This will then use any default parameter values in the features - which can be 257adjusted as described above. 258 259To use a preset<n> set of parameter values:: 260 261 $ echo 3 > preset 262 263This will select preset3 for the configuration. 264The valid values for preset are 0 - to deselect presets, and any value of 265<n> where a preset<n> sub-directory is present. 266 267Note that the active sysfs configuration is a global parameter, therefore 268only 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 will 271also result in an error. 272 273The use of the active configuration by sysfs is independent of the configuration 274used in perf. 275 276 277Creating and Loading Custom Configurations 278========================================== 279 280Custom configurations and / or features can be dynamically loaded into the 281system 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 in 286strobing feature, but provides a different set of presets. 287 288When the module is loaded, then the configuration appears in the configfs 289file system and is selectable in the same way as the built in configuration 290described above. 291 292Configurations can use previously loaded features. The system will ensure 293that it is not possible to unload a feature that is currently in use, by 294enforcing the unload order as the strict reverse of the load order. 295