[PATCH v3 6/6] Documentation: coresight: Update coresight configuration docs

[Mathieu Poirier]

On Wed, Nov 24, 2021 at 08:00:38PM +0000, Mike Leach wrote:
> Update the CoreSight System Configuration document to cover the
> use of loadable modules to add configurations and features
> to the system.
> 
> Signed-off-by: Mike Leach <mike.leach at linaro.org>
> ---
>  .../trace/coresight/coresight-config.rst      | 62 ++++++++++++++++++-
>  1 file changed, 59 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst
> index 6ed13398ca2c..6d5ffa6f7347 100644
> --- a/Documentation/trace/coresight/coresight-config.rst
> +++ b/Documentation/trace/coresight/coresight-config.rst
> @@ -155,14 +155,14 @@ follows::
>      autofdo
>      $ cd autofdo/
>      $ ls
> -    description   preset1  preset3  preset5  preset7  preset9
> -    feature_refs  preset2  preset4  preset6  preset8
> +    description  feature_refs  preset1  preset3  preset5  preset7  preset9
> +    enable       preset        preset2  preset4  preset6  preset8
>      $ cat description
>      Setup ETMs with strobing for autofdo
>      $ cat feature_refs
>      strobing
>  
> -Each preset declared has a preset<n> subdirectory declared. The values for
> +Each preset declared has a 'preset<n>' subdirectory declared. The values for
>  the preset can be examined::
>  
>      $ cat preset1/values
> @@ -170,6 +170,9 @@ the preset can be examined::
>      $ cat preset2/values
>      strobing.window = 0x1388 strobing.period = 0x4
>  
> +The 'enable' and 'preset' files allow the control of a configuration when
> +using CoreSight with sysfs.
> +
>  The features referenced by the configuration can be examined in the features
>  directory::
>  
> @@ -236,3 +239,56 @@ A preset to override the current parameter values can also be selected::
>  
>  When configurations are selected in this way, then the trace sink used is
>  automatically selected.
> +
> +Using Configurations in sysfs
> +=============================
> +
> +Coresight can be controlled using sysfs. When this is in use then a configuration
> +can be made active for the devices that are used in the sysfs session.
> +
> +In a configuration there are 'enable' and 'preset' files.
> +
> +To enable a configuration for use with sysfs::
> +
> +    $ cd configurations/autofdo
> +    $ echo 1 > enable
> +
> +This will then use any default parameter values in the features - which can be
> +adjusted as described above.
> +
> +To use a preset<n> set of parameter values::
> +
> +    $ echo 3 > preset
> +
> +This will select preset3 for the configuration.
> +The valid values for preset are 0 - to deselect presets, and any value of
> +<n> where a preset<n> sub-directory is present.
> +
> +Note that the active sysfs configuration is a global parameter, therefore
> +only a single configuration can be active for sysfs at any one time.
> +Attempting to enable a second configuration will result in an error.
> +Additionally, attempting to disable the configuration while in use will
> +also result in an error.
> +
> +The use of the active configuration by sysfs is independent of the configuration
> +used in perf.
> +

Shouldn't all instances in the above section be configfs rather than sysfs?  If
so should I make the changes?

I have your patchset on stanby in my local coresight-next tree - just let me
know.

Thanks,
Mathieu

> +
> +Creating and Loading Custom Configurations
> +==========================================
> +
> +Custom configurations and / or features can be dynamically loaded into the
> +system by using a loadable module.
> +
> +An example of a custom configuration is found in ./samples/coresight.
> +
> +This creates a new configuration that uses the existing built in
> +strobing feature, but provides a different set of presets.
> +
> +When the module is loaded, then the configuration appears in the configfs
> +file system and is selectable in the same way as the built in configuration
> +described above.
> +
> +Configurations can use previously loaded features. The system will ensure
> +that it is not possible to unload a feature that is currently in use, by
> +enforcing the unload order as the strict reverse of the load order.
> -- 
> 2.17.1
>