[RFC PATCH v3 9/9] coresight: docs: Add documentation for CoreSight config.
Mike Leach
mike.leach at linaro.org
Thu Dec 24 14:21:59 EST 2020
Hi Mathieu,
On Thu, 26 Nov 2020 at 17:52, Mathieu Poirier
<mathieu.poirier at linaro.org> 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 <mike.leach at linaro.org>
> > ---
> > .../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 <mike.leach at linaro.org>
> > + :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
More information about the linux-arm-kernel
mailing list