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   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
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 features referenced by the configuration can be examined in the features
174directory::
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
188Move 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
202Parameters adjusted in this way are reflected in all device instances that have
203loaded the feature.
204
205
206Using Configurations in perf
207============================
208
209The configurations loaded into the CoreSight configuration management are
210also declared in the perf 'cs_etm' event infrastructure so that they can
211be 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
217Key directories here are 'configurations' - which lists the loaded
218configurations, and 'events' - a generic perf directory which allows
219selection on the perf command line.::
220
221    $ ls configurations/
222    autofdo
223    $ cat configurations/autofdo
224    0xa7c3dddd
225
226As with the sinks entries, this provides a hash of the configuration name.
227The entry in the 'events' directory uses perfs built in syntax generator
228to substitute the syntax for the name when evaluating the command::
229
230    $ ls events/
231    autofdo
232    $ cat events/autofdo
233    configid=0xa7c3dddd
234
235The 'autofdo' configuration may be selected on the perf command line::
236
237    $ perf record -e cs_etm/autofdo/u --per-thread <application>
238
239A 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
243When configurations are selected in this way, then the trace sink used is
244automatically selected.
245