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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.