[RFC,v3,9/9] coresight: docs: Add documentation for CoreSight config.

Commit Message

Mike Leach Oct. 30, 2020, 5:56 p.m. UTC

Adds documentation for the CoreSight System configuration manager.

Signed-off-by: Mike Leach <[e-mail]>
---
 .../trace/coresight/coresight-config.rst      | 230 ++++++++++++++++++
 Documentation/trace/coresight/coresight.rst   |  16 ++
 2 files changed, 246 insertions(+)
 create mode 100644 Documentation/trace/coresight/coresight-config.rst

Comments

Mathieu Poirier Nov. 26, 2020, 5:52 p.m. UTC | #1

On Fri, Oct 30, 2020 at 05:56:55PM +0000, Mike Leach wrote:
> Adds documentation for the CoreSight System configuration manager.
> 
> Signed-off-by: Mike Leach <[e-mail]>
> ---
>  .../trace/coresight/coresight-config.rst      | 230 ++++++++++++++++++
>  Documentation/trace/coresight/coresight.rst   |  16 ++
>  2 files changed, 246 insertions(+)
>  create mode 100644 Documentation/trace/coresight/coresight-config.rst
> 
> diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst
> new file mode 100644
> index 000000000000..8afcf18c090c
> --- /dev/null
> +++ b/Documentation/trace/coresight/coresight-config.rst
> @@ -0,0 +1,230 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +======================================
> +CoreSight System Configuration Manager
> +======================================
> +
> +    :Author:   Mike Leach <[e-mail]>
> +    :Date:     October 2020
> +
> +Introduction
> +============
> +
> +The CoreSight System Configuration manager is an API that allows the
> +programming of the CoreSight system with pre-defined configurations that
> +can then be easily enabled from sysfs or perf.
> +
> +Many CoreSight components can be programmed in complex ways - especially ETMs.
> +In addition, components can interact across the CoreSight system, often via
> +the cross trigger components such as CTI and CTM. These system settings can
> +be defined and enabled as named configurations.
> +
> +
> +Basic Concepts
> +==============
> +
> +This section introduces the basic concepts of a complex system configuration.
> +
> +
> +Features
> +--------
> +
> +A feature is a named set of programming for a CoreSight device. The programming
> +is device dependent, and can be defined in terms of absolute register values,
> +resource usage and parameter values.
> +
> +The feature is defined using a descriptor. This descriptor is used to load onto
> +a matching device, either when the feature is loaded into the system, or when the
> +device is registered with the configuration manager.

In the above paragraph I would explicitly write "coresight device" when
referring to a device.  That way there is no doubt as to what is happening.

> +
> +The load process involves interpreting the descriptor into a the set of register

s/into a the set/into a set/

> +accesses in the driver - the resource usage and parameter descriptions
> +translated into appropriate register accesses. This interpretation makes it easy
> +and efficient for the feature to be programmed onto the device when required.
> +
> +The feature will not be active on the device until the feature is enabled, and
> +the device itself is enabled. When the device is enabled then enabled features
> +will be programmed into the device hardware.

If I understand correctly the above paragraph is for the sysfs and configfs
interfaces.  From perf enabling feature and devices doesn't apply.

> +
> +A feature can be enabled either as part of a configuration being enabled on the
> +system, or individually on a device instance using the configfs API.
> +
> +
> +Parameter Value
> +~~~~~~~~~~~~~~~
> +
> +A parameter value is a named value that may be set by the user prior to the
> +feature being enabled that can adjust the behaviour of the operation programmed
> +by the feature.
> +
> +For example, this could be a count value in a programmed operation that repeats
> +at a given rate. When the feature is enabled then the current value of the
> +parameter is used in programming the device.
> +
> +The feature descriptor defines a default value for a parameter, which is used
> +if the user does not supply a new value.
> +
> +Users can update parameter values using the configfs API for the CoreSight
> +system - which is described below.
> +
> +The current value of the parameter is loaded into the device when the feature
> +is enabled on that device.
> +
> +
> +Configurations
> +--------------
> +
> +A configuration defines a set of features that are to be used in a trace
> +session where the configuration is selected. For any trace session only one
> +configuration may be selected.
> +
> +The features defined may be on any type of device that is registered
> +to support system configuration. A configuration may select features to be
> +enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a
> +specific CTI on the system.
> +
> +As with the feature, a descriptor is used to define the configuration.
> +This will define the features that must be enabled as part of the configuration
> +as well as any preset values that can be used to override default parameter
> +values.
> +
> +
> +Preset Values
> +~~~~~~~~~~~~~
> +
> +Preset values are easily selectable sets of parameter values for the features
> +that the configuration uses. The number of values in a single preset set, equals
> +the sum of parameter values in the features used by the configuration.
> +
> +e.g. a configuration consists of 3 features, one has 2 parameters, one has
> +a single parameter, and another has no parameters. A single preset set will
> +therefore have 3 values.
> +
> +Presets are optionally defined by the configuration, up to 15 can be defined.
> +If no preset is selected, then the parameter values defined in the feature
> +are used as normal.
> +
> +
> +Virtual Device
> +--------------
> +
> +The CoreSight System Configuration manager also includes a virtual CoreSight
> +device. This provides the system with access to kernel objects and device
> +management to own elements such as the sysfs entries used to expose the
> +configurations into the cs_etm event in perf.
> +
> +This device 'system_cfg'  appears on a custom bus - 'coresight-config' -
> +rather than the normal 'coresight' bus to avoid complications when the
> +coresight system is searching for real devices on the bus.
> +
> +
> +Viewing Configurations and Features
> +===================================
> +
> +The set of configurations and features that are currently loaded into the
> +system can be viewed using the configfs API.
> +
> +Mount configfs as normal and the 'coresight-syscfg' subsystem will appear::
> +
> +    $ ls /config
> +    coresight-syscfg  stp-policy
> +
> +This has two sub-directories::
> +
> +    $ cd coresight-syscfg/
> +    $ ls
> +    configurations  features
> +
> +The system has the configuration 'autofdo' built in. It may be examined as
> +follows::
> +
> +    $ cd configurations/
> +    $ ls
> +    autofdo
> +    $ cd autofdo/
> +    $ ls
> +    description  nr_presets  preset_values  refs
> +    $ cat description
> +    Setup ETMs with strobing for autofdo
> +    $ cat refs
> +    references 1 features:-
> +    strobing
> +    $ cat nr_presets
> +    2
> +    $ cat preset_values
> +    2 presets, 2 parameters per preset
> +    preset[1]: strobing.window = 0x2710 strobing.period = 0x1388
> +    preset[2]: strobing.window = 0x1388 strobing.period = 0x1388
> +
> +The features referenced by the configuration can be examined in the features
> +directory::
> +
> +    $ cd ../../features/strobing/
> +    $ ls
> +    description  matches  nr_params  params
> +    $ cat description
> +    Generate periodic trace capture windows.
> +    parameter 'window': a number of CPU cycles (W)
> +    parameter 'period': trace enabled for W cycles every period x W cycles
> +    $ cat matches
> +    SRC_ETMV4
> +    $ cat nr_params
> +    2
> +
> +Move to the params directory to examine and adjust parameters::
> +
> +    cd params
> +    $ ls
> +    period  window
> +    $ cd period
> +    $ ls
> +    value
> +    $ cat value
> +    0x2710
> +    # echo 15000 > value
> +    # cat value
> +    0x3a98
> +
> +Parameters adjusted in this way are reflected in all device instances that have
> +loaded the feature.
> +
> +
> +Using Configurations in perf
> +============================
> +
> +The configurations loaded into the CoreSight configuration management are
> +also declared in the perf 'cs_etm' event infrastructure so that they can
> +be selected when running trace under perf::
> +
> +    $ ls /sys/devices/cs_etm
> +    configurations  format  perf_event_mux_interval_ms  sinks  type
> +    events  nr_addr_filters  power
> +
> +Key directories here are 'configurations' - which lists the loaded
> +configurations, and 'events' - a generic perf directory which allows
> +selection on the perf command line.::
> +
> +    $ ls configurations/
> +    autofdo
> +    $ cat configurations/autofdo
> +    0xa7c3dddd
> +
> +As with the sinks entries, this provides a hash of the configuration name.
> +The entry in the 'events' directory uses perfs built in syntax generator
> +to substitute the syntax for the name when evaluating the command::
> +
> +    $ ls events/
> +    autofdo
> +    $ cat events/autofdo
> +    configid=0xa7c3dddd
> +
> +The 'autofdo' configuration may be selected on the perf command line::
> +
> +    $ perf record -e cs_etm/autofdo/u --per-thread <application>
> +
> +A preset to override the current parameter values can also be selected::
> +
> +    $ perf record -e cs_etm/autofdo,preset=1/u --per-thread <application>
> +
> +When configurations are selected in this way, then the trace sink used is
> +automatically selected.
> diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
> index 0b73acb44efa..0122d9bebf35 100644
> --- a/Documentation/trace/coresight/coresight.rst
> +++ b/Documentation/trace/coresight/coresight.rst
> @@ -587,6 +587,20 @@ A separate documentation file is provided to explain the use of these devices.
>  (:doc:`coresight-ect`) [#fourth]_.
>  
>  
> +CoreSight System Configuration
> +------------------------------
> +
> +CoreSight components can be complex devices with many programming options.
> +Furthermore, components can be programmed to interact with each other across the
> +complete system.
> +
> +A CoreSight System Configuration manager is provided to allow these complex programming
> +configurations to be selected and used easily from perf and sysfs.
> +
> +See the separate document for further information.
> +(:doc:`coresight-config`) [#fifth]_.
> +
> +
>  .. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
>  
>  .. [#second] Documentation/trace/stm.rst
> @@ -594,3 +608,5 @@ A separate documentation file is provided to explain the use of these devices.
>  .. [#third] https://github.com/Linaro/perf-opencsd
>  
>  .. [#fourth] Documentation/trace/coresight/coresight-ect.rst
> +
> +.. [#fifth] Documentation/trace/coresight/coresight-config.rst
> -- 
> 2.17.1
>

Mike Leach Dec. 24, 2020, 7:21 p.m. UTC | #2

Hi Mathieu,

On Thu, 26 Nov 2020 at 17:52, Mathieu Poirier
<[e-mail]> wrote:
>
> On Fri, Oct 30, 2020 at 05:56:55PM +0000, Mike Leach wrote:
> > Adds documentation for the CoreSight System configuration manager.
> >
> > Signed-off-by: Mike Leach <[e-mail]>
> > ---
> >  .../trace/coresight/coresight-config.rst      | 230 ++++++++++++++++++
> >  Documentation/trace/coresight/coresight.rst   |  16 ++
> >  2 files changed, 246 insertions(+)
> >  create mode 100644 Documentation/trace/coresight/coresight-config.rst
> >
> > diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst
> > new file mode 100644
> > index 000000000000..8afcf18c090c
> > --- /dev/null
> > +++ b/Documentation/trace/coresight/coresight-config.rst
> > @@ -0,0 +1,230 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +======================================
> > +CoreSight System Configuration Manager
> > +======================================
> > +
> > +    :Author:   Mike Leach <[e-mail]>
> > +    :Date:     October 2020
> > +
> > +Introduction
> > +============
> > +
> > +The CoreSight System Configuration manager is an API that allows the
> > +programming of the CoreSight system with pre-defined configurations that
> > +can then be easily enabled from sysfs or perf.
> > +
> > +Many CoreSight components can be programmed in complex ways - especially ETMs.
> > +In addition, components can interact across the CoreSight system, often via
> > +the cross trigger components such as CTI and CTM. These system settings can
> > +be defined and enabled as named configurations.
> > +
> > +
> > +Basic Concepts
> > +==============
> > +
> > +This section introduces the basic concepts of a complex system configuration.
> > +
> > +
> > +Features
> > +--------
> > +
> > +A feature is a named set of programming for a CoreSight device. The programming
> > +is device dependent, and can be defined in terms of absolute register values,
> > +resource usage and parameter values.
> > +
> > +The feature is defined using a descriptor. This descriptor is used to load onto
> > +a matching device, either when the feature is loaded into the system, or when the
> > +device is registered with the configuration manager.
>
> In the above paragraph I would explicitly write "coresight device" when
> referring to a device.  That way there is no doubt as to what is happening.
>
> > +
> > +The load process involves interpreting the descriptor into a the set of register
>
> s/into a the set/into a set/
>
> > +accesses in the driver - the resource usage and parameter descriptions
> > +translated into appropriate register accesses. This interpretation makes it easy
> > +and efficient for the feature to be programmed onto the device when required.
> > +
> > +The feature will not be active on the device until the feature is enabled, and
> > +the device itself is enabled. When the device is enabled then enabled features
> > +will be programmed into the device hardware.
>
> If I understand correctly the above paragraph is for the sysfs and configfs
> interfaces.  From perf enabling feature and devices doesn't apply.
>

No - this also applies to perf. The principle is that perf will enable
a config. But it will only be programmed on to the devices that the
perf event is enabled on.

Thanks

Mike


> > +
> > +A feature can be enabled either as part of a configuration being enabled on the
> > +system, or individually on a device instance using the configfs API.
> > +
> > +
> > +Parameter Value
> > +~~~~~~~~~~~~~~~
> > +
> > +A parameter value is a named value that may be set by the user prior to the
> > +feature being enabled that can adjust the behaviour of the operation programmed
> > +by the feature.
> > +
> > +For example, this could be a count value in a programmed operation that repeats
> > +at a given rate. When the feature is enabled then the current value of the
> > +parameter is used in programming the device.
> > +
> > +The feature descriptor defines a default value for a parameter, which is used
> > +if the user does not supply a new value.
> > +
> > +Users can update parameter values using the configfs API for the CoreSight
> > +system - which is described below.
> > +
> > +The current value of the parameter is loaded into the device when the feature
> > +is enabled on that device.
> > +
> > +
> > +Configurations
> > +--------------
> > +
> > +A configuration defines a set of features that are to be used in a trace
> > +session where the configuration is selected. For any trace session only one
> > +configuration may be selected.
> > +
> > +The features defined may be on any type of device that is registered
> > +to support system configuration. A configuration may select features to be
> > +enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a
> > +specific CTI on the system.
> > +
> > +As with the feature, a descriptor is used to define the configuration.
> > +This will define the features that must be enabled as part of the configuration
> > +as well as any preset values that can be used to override default parameter
> > +values.
> > +
> > +
> > +Preset Values
> > +~~~~~~~~~~~~~
> > +
> > +Preset values are easily selectable sets of parameter values for the features
> > +that the configuration uses. The number of values in a single preset set, equals
> > +the sum of parameter values in the features used by the configuration.
> > +
> > +e.g. a configuration consists of 3 features, one has 2 parameters, one has
> > +a single parameter, and another has no parameters. A single preset set will
> > +therefore have 3 values.
> > +
> > +Presets are optionally defined by the configuration, up to 15 can be defined.
> > +If no preset is selected, then the parameter values defined in the feature
> > +are used as normal.
> > +
> > +
> > +Virtual Device
> > +--------------
> > +
> > +The CoreSight System Configuration manager also includes a virtual CoreSight
> > +device. This provides the system with access to kernel objects and device
> > +management to own elements such as the sysfs entries used to expose the
> > +configurations into the cs_etm event in perf.
> > +
> > +This device 'system_cfg'  appears on a custom bus - 'coresight-config' -
> > +rather than the normal 'coresight' bus to avoid complications when the
> > +coresight system is searching for real devices on the bus.
> > +
> > +
> > +Viewing Configurations and Features
> > +===================================
> > +
> > +The set of configurations and features that are currently loaded into the
> > +system can be viewed using the configfs API.
> > +
> > +Mount configfs as normal and the 'coresight-syscfg' subsystem will appear::
> > +
> > +    $ ls /config
> > +    coresight-syscfg  stp-policy
> > +
> > +This has two sub-directories::
> > +
> > +    $ cd coresight-syscfg/
> > +    $ ls
> > +    configurations  features
> > +
> > +The system has the configuration 'autofdo' built in. It may be examined as
> > +follows::
> > +
> > +    $ cd configurations/
> > +    $ ls
> > +    autofdo
> > +    $ cd autofdo/
> > +    $ ls
> > +    description  nr_presets  preset_values  refs
> > +    $ cat description
> > +    Setup ETMs with strobing for autofdo
> > +    $ cat refs
> > +    references 1 features:-
> > +    strobing
> > +    $ cat nr_presets
> > +    2
> > +    $ cat preset_values
> > +    2 presets, 2 parameters per preset
> > +    preset[1]: strobing.window = 0x2710 strobing.period = 0x1388
> > +    preset[2]: strobing.window = 0x1388 strobing.period = 0x1388
> > +
> > +The features referenced by the configuration can be examined in the features
> > +directory::
> > +
> > +    $ cd ../../features/strobing/
> > +    $ ls
> > +    description  matches  nr_params  params
> > +    $ cat description
> > +    Generate periodic trace capture windows.
> > +    parameter 'window': a number of CPU cycles (W)
> > +    parameter 'period': trace enabled for W cycles every period x W cycles
> > +    $ cat matches
> > +    SRC_ETMV4
> > +    $ cat nr_params
> > +    2
> > +
> > +Move to the params directory to examine and adjust parameters::
> > +
> > +    cd params
> > +    $ ls
> > +    period  window
> > +    $ cd period
> > +    $ ls
> > +    value
> > +    $ cat value
> > +    0x2710
> > +    # echo 15000 > value
> > +    # cat value
> > +    0x3a98
> > +
> > +Parameters adjusted in this way are reflected in all device instances that have
> > +loaded the feature.
> > +
> > +
> > +Using Configurations in perf
> > +============================
> > +
> > +The configurations loaded into the CoreSight configuration management are
> > +also declared in the perf 'cs_etm' event infrastructure so that they can
> > +be selected when running trace under perf::
> > +
> > +    $ ls /sys/devices/cs_etm
> > +    configurations  format  perf_event_mux_interval_ms  sinks  type
> > +    events  nr_addr_filters  power
> > +
> > +Key directories here are 'configurations' - which lists the loaded
> > +configurations, and 'events' - a generic perf directory which allows
> > +selection on the perf command line.::
> > +
> > +    $ ls configurations/
> > +    autofdo
> > +    $ cat configurations/autofdo
> > +    0xa7c3dddd
> > +
> > +As with the sinks entries, this provides a hash of the configuration name.
> > +The entry in the 'events' directory uses perfs built in syntax generator
> > +to substitute the syntax for the name when evaluating the command::
> > +
> > +    $ ls events/
> > +    autofdo
> > +    $ cat events/autofdo
> > +    configid=0xa7c3dddd
> > +
> > +The 'autofdo' configuration may be selected on the perf command line::
> > +
> > +    $ perf record -e cs_etm/autofdo/u --per-thread <application>
> > +
> > +A preset to override the current parameter values can also be selected::
> > +
> > +    $ perf record -e cs_etm/autofdo,preset=1/u --per-thread <application>
> > +
> > +When configurations are selected in this way, then the trace sink used is
> > +automatically selected.
> > diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
> > index 0b73acb44efa..0122d9bebf35 100644
> > --- a/Documentation/trace/coresight/coresight.rst
> > +++ b/Documentation/trace/coresight/coresight.rst
> > @@ -587,6 +587,20 @@ A separate documentation file is provided to explain the use of these devices.
> >  (:doc:`coresight-ect`) [#fourth]_.
> >
> >
> > +CoreSight System Configuration
> > +------------------------------
> > +
> > +CoreSight components can be complex devices with many programming options.
> > +Furthermore, components can be programmed to interact with each other across the
> > +complete system.
> > +
> > +A CoreSight System Configuration manager is provided to allow these complex programming
> > +configurations to be selected and used easily from perf and sysfs.
> > +
> > +See the separate document for further information.
> > +(:doc:`coresight-config`) [#fifth]_.
> > +
> > +
> >  .. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
> >
> >  .. [#second] Documentation/trace/stm.rst
> > @@ -594,3 +608,5 @@ A separate documentation file is provided to explain the use of these devices.
> >  .. [#third] https://github.com/Linaro/perf-opencsd
> >
> >  .. [#fourth] Documentation/trace/coresight/coresight-ect.rst
> > +
> > +.. [#fifth] Documentation/trace/coresight/coresight-config.rst
> > --
> > 2.17.1
> >



--
Mike Leach
Principal Engineer, ARM Ltd.
Manchester Design Centre. UK

Patch

diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst
new file mode 100644
index 000000000000..8afcf18c090c
--- /dev/null
+++ b/Documentation/trace/coresight/coresight-config.rst
@@ -0,0 +1,230 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+======================================
+CoreSight System Configuration Manager
+======================================
+
+    :Author:   Mike Leach <[e-mail]>
+    :Date:     October 2020
+
+Introduction
+============
+
+The CoreSight System Configuration manager is an API that allows the
+programming of the CoreSight system with pre-defined configurations that
+can then be easily enabled from sysfs or perf.
+
+Many CoreSight components can be programmed in complex ways - especially ETMs.
+In addition, components can interact across the CoreSight system, often via
+the cross trigger components such as CTI and CTM. These system settings can
+be defined and enabled as named configurations.
+
+
+Basic Concepts
+==============
+
+This section introduces the basic concepts of a complex system configuration.
+
+
+Features
+--------
+
+A feature is a named set of programming for a CoreSight device. The programming
+is device dependent, and can be defined in terms of absolute register values,
+resource usage and parameter values.
+
+The feature is defined using a descriptor. This descriptor is used to load onto
+a matching device, either when the feature is loaded into the system, or when the
+device is registered with the configuration manager.
+
+The load process involves interpreting the descriptor into a the set of register
+accesses in the driver - the resource usage and parameter descriptions
+translated into appropriate register accesses. This interpretation makes it easy
+and efficient for the feature to be programmed onto the device when required.
+
+The feature will not be active on the device until the feature is enabled, and
+the device itself is enabled. When the device is enabled then enabled features
+will be programmed into the device hardware.
+
+A feature can be enabled either as part of a configuration being enabled on the
+system, or individually on a device instance using the configfs API.
+
+
+Parameter Value
+~~~~~~~~~~~~~~~
+
+A parameter value is a named value that may be set by the user prior to the
+feature being enabled that can adjust the behaviour of the operation programmed
+by the feature.
+
+For example, this could be a count value in a programmed operation that repeats
+at a given rate. When the feature is enabled then the current value of the
+parameter is used in programming the device.
+
+The feature descriptor defines a default value for a parameter, which is used
+if the user does not supply a new value.
+
+Users can update parameter values using the configfs API for the CoreSight
+system - which is described below.
+
+The current value of the parameter is loaded into the device when the feature
+is enabled on that device.
+
+
+Configurations
+--------------
+
+A configuration defines a set of features that are to be used in a trace
+session where the configuration is selected. For any trace session only one
+configuration may be selected.
+
+The features defined may be on any type of device that is registered
+to support system configuration. A configuration may select features to be
+enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a
+specific CTI on the system.
+
+As with the feature, a descriptor is used to define the configuration.
+This will define the features that must be enabled as part of the configuration
+as well as any preset values that can be used to override default parameter
+values.
+
+
+Preset Values
+~~~~~~~~~~~~~
+
+Preset values are easily selectable sets of parameter values for the features
+that the configuration uses. The number of values in a single preset set, equals
+the sum of parameter values in the features used by the configuration.
+
+e.g. a configuration consists of 3 features, one has 2 parameters, one has
+a single parameter, and another has no parameters. A single preset set will
+therefore have 3 values.
+
+Presets are optionally defined by the configuration, up to 15 can be defined.
+If no preset is selected, then the parameter values defined in the feature
+are used as normal.
+
+
+Virtual Device
+--------------
+
+The CoreSight System Configuration manager also includes a virtual CoreSight
+device. This provides the system with access to kernel objects and device
+management to own elements such as the sysfs entries used to expose the
+configurations into the cs_etm event in perf.
+
+This device 'system_cfg'  appears on a custom bus - 'coresight-config' -
+rather than the normal 'coresight' bus to avoid complications when the
+coresight system is searching for real devices on the bus.
+
+
+Viewing Configurations and Features
+===================================
+
+The set of configurations and features that are currently loaded into the
+system can be viewed using the configfs API.
+
+Mount configfs as normal and the 'coresight-syscfg' subsystem will appear::
+
+    $ ls /config
+    coresight-syscfg  stp-policy
+
+This has two sub-directories::
+
+    $ cd coresight-syscfg/
+    $ ls
+    configurations  features
+
+The system has the configuration 'autofdo' built in. It may be examined as
+follows::
+
+    $ cd configurations/
+    $ ls
+    autofdo
+    $ cd autofdo/
+    $ ls
+    description  nr_presets  preset_values  refs
+    $ cat description
+    Setup ETMs with strobing for autofdo
+    $ cat refs
+    references 1 features:-
+    strobing
+    $ cat nr_presets
+    2
+    $ cat preset_values
+    2 presets, 2 parameters per preset
+    preset[1]: strobing.window = 0x2710 strobing.period = 0x1388
+    preset[2]: strobing.window = 0x1388 strobing.period = 0x1388
+
+The features referenced by the configuration can be examined in the features
+directory::
+
+    $ cd ../../features/strobing/
+    $ ls
+    description  matches  nr_params  params
+    $ cat description
+    Generate periodic trace capture windows.
+    parameter 'window': a number of CPU cycles (W)
+    parameter 'period': trace enabled for W cycles every period x W cycles
+    $ cat matches
+    SRC_ETMV4
+    $ cat nr_params
+    2
+
+Move to the params directory to examine and adjust parameters::
+
+    cd params
+    $ ls
+    period  window
+    $ cd period
+    $ ls
+    value
+    $ cat value
+    0x2710
+    # echo 15000 > value
+    # cat value
+    0x3a98
+
+Parameters adjusted in this way are reflected in all device instances that have
+loaded the feature.
+
+
+Using Configurations in perf
+============================
+
+The configurations loaded into the CoreSight configuration management are
+also declared in the perf 'cs_etm' event infrastructure so that they can
+be selected when running trace under perf::
+
+    $ ls /sys/devices/cs_etm
+    configurations  format  perf_event_mux_interval_ms  sinks  type
+    events  nr_addr_filters  power
+
+Key directories here are 'configurations' - which lists the loaded
+configurations, and 'events' - a generic perf directory which allows
+selection on the perf command line.::
+
+    $ ls configurations/
+    autofdo
+    $ cat configurations/autofdo
+    0xa7c3dddd
+
+As with the sinks entries, this provides a hash of the configuration name.
+The entry in the 'events' directory uses perfs built in syntax generator
+to substitute the syntax for the name when evaluating the command::
+
+    $ ls events/
+    autofdo
+    $ cat events/autofdo
+    configid=0xa7c3dddd
+
+The 'autofdo' configuration may be selected on the perf command line::
+
+    $ perf record -e cs_etm/autofdo/u --per-thread <application>
+
+A preset to override the current parameter values can also be selected::
+
+    $ perf record -e cs_etm/autofdo,preset=1/u --per-thread <application>
+
+When configurations are selected in this way, then the trace sink used is
+automatically selected.
diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
index 0b73acb44efa..0122d9bebf35 100644
--- a/Documentation/trace/coresight/coresight.rst
+++ b/Documentation/trace/coresight/coresight.rst
@@ -587,6 +587,20 @@  A separate documentation file is provided to explain the use of these devices.
 (:doc:`coresight-ect`) [#fourth]_.
 
 
+CoreSight System Configuration
+------------------------------
+
+CoreSight components can be complex devices with many programming options.
+Furthermore, components can be programmed to interact with each other across the
+complete system.
+
+A CoreSight System Configuration manager is provided to allow these complex programming
+configurations to be selected and used easily from perf and sysfs.
+
+See the separate document for further information.
+(:doc:`coresight-config`) [#fifth]_.
+
+
 .. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
 
 .. [#second] Documentation/trace/stm.rst
@@ -594,3 +608,5 @@  A separate documentation file is provided to explain the use of these devices.
 .. [#third] https://github.com/Linaro/perf-opencsd
 
 .. [#fourth] Documentation/trace/coresight/coresight-ect.rst
+
+.. [#fifth] Documentation/trace/coresight/coresight-config.rst