[v5,6/6] Documentation: coresight: docs for config load via configfs

  Add documentation covering the configfs updates that allow
binary configuration files to be loaded and unloaded via configfs,
along with the demonstration programs in samples.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Mike Leach <mike.leach@linaro.org>
---
 .../trace/coresight/coresight-config.rst      | 202 +++++++++++++++++-
 1 file changed, 195 insertions(+), 7 deletions(-)
  

On Mon, Dec 19, 2022 at 11:46:38PM +0000, Mike Leach wrote:
> diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst
> index 6d5ffa6f7347..109053eb1b93 100644
> --- a/Documentation/trace/coresight/coresight-config.rst
> +++ b/Documentation/trace/coresight/coresight-config.rst
> @@ -141,11 +141,11 @@ Mount configfs as normal and the 'cs-syscfg' subsystem will appear::
>      $ ls /config
>      cs-syscfg  stp-policy
>  
> -This has two sub-directories::
> +This has two sub-directories, with the load and unload attribute files::
>  
>      $ cd cs-syscfg/
>      $ ls
> -    configurations  features
> +    configurations features load  unload
>  
>  The system has the configuration 'autofdo' built in. It may be examined as
>  follows::
> @@ -278,9 +278,16 @@ Creating and Loading Custom Configurations
>  ==========================================
>  
>  Custom configurations and / or features can be dynamically loaded into the
> -system by using a loadable module.
> +system by using a loadable module, or by loading a binary configuration
> +file in configfs.
>  
> -An example of a custom configuration is found in ./samples/coresight.
> +Loaded 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.
> +
> +
> +Using a Loadable Module
> +-----------------------
>  
>  This creates a new configuration that uses the existing built in
>  strobing feature, but provides a different set of presets.
> @@ -289,6 +296,187 @@ 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.
> +The file 'coresight-cfg-sample.c' contains the configuration and module
> +initialisation code needed to create the loadable module.
> +
> +This will be built alongside the kernel modules if select in KConfig.

What config options (CONFIG_) are required for above to work?

> +
> +An example of a custom configuration module is found in './samples/coresight'.
> +
> +Using a Binary Configuration File
> +---------------------------------
> +
> +The './tools/coresight' directory contains example programs to generate and
> +read and print binary configuration files.
> +
> +Building the tools creates the 'coresight-cfg-file-gen' program that will
> +generate a configuration binary 'example1.cscfg' that can be loaded into the
> +system using configfs. The configuration declared in the source file
> +'coresight-cfg-example1.c' is named 'autofdo3' - the name that will be used
> +once loaded.
> +
> +The source files 'coresight-cfg-bufw.h' and 'coresight-cfg-bufw.c' provide a
> +standard function to convert a configuration declared in 'C' into the correct
> +binary buffer format. These files can be re-used to create new custom
> +configurations. Alternatively, addition examples can be added to the

s/addition/additional/

> +'coresight-cfg-file-gen' program::
> +
> +    $ ./coresight-cfg-file-gen
> +    Coresight Configuration file Generator
> +
> +    Generating example1 example
> +    Generating example2 example
> +
> +The program 'coresight-cfg-file-read' can read back and print a configuration
> +binary. This is built using the file reader from the driver code
> +(coresight-config-file.c), which is copied over into './tools/coresight' at
> +build time.::
> +
> +    ./coresight-cfg-file-read example1.cscfg
> +    CoreSight Configuration file reader
> +    ============================================
> +
> +    Configuration 1
> +    Name:- autofdo3
> +    Description:-
> +    Setup ETMs with strobing for autofdo
> +    Supplied presets allow experimentation with mark-space ratio for various loads
> +
> +    Uses 1 features:-
> +    Feature-1: strobing
> +
> +    Provides 4 sets of preset values, 2 presets per set
> +    set[0]: 0x7d0, 0x64,
> +    set[1]: 0x7d0, 0x3e8,
> +    set[2]: 0x7d0, 0x1388,
> +    set[3]: 0x7d0, 0x2710,
> +
> +    ============================================
> +    File contains no features
> +
> +There are additional attributes in the cs-syscfg directory - load and
> +unload that can be used to load and unload configuration binary files. To
> +load, 'cat' the binary config into the load attribute::
> +
> +    $ ls /config/cs-syscfg
> +    configurations features  load  unload
> +    $ cat example1.cscfg > /config/cs-syscfg/load
> +    $ ls /config/cs-syscfg/configurations/
> +    autofdo  autofdo3
> +
> +To unload, use the same file in the unload attribute::
> +
> +    $ cat example1.cscfg > /config/cs-syscfg/unload
> +    ls /config/cs-syscfg/configurations/
> +    autofdo
> +
> +
> +
> +Binary Configuration File Format
> +--------------------------------
> +
> +The file format is defined in the source file **coresight-config-file.h**

Use single-quote for identifier names for consistency here.

> +
> +The source reader and generator examples produce a binary of this format.
> +
> +This arrangement is reproduced below:-
> +
> +Overall File structure
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +::
> +
> +   [cscfg_file_header]   // Mandatory
> +   [CONFIG_ELEM]*        // Optional - multiple, defined by cscfg_file_header.nr_configs
> +   [FEATURE_ELEM]*       // Optional - multiple, defined by cscfg_file_header.nr_features
> +
> +File is invalid if both [CONFIG_ELEM] and [FEATURE_ELEM] are omitted.
> +
> +A file that contains only [FEATURE_ELEM] may be loaded, and the features used
> +by subsequently loaded files with [CONFIG_ELEM] elements.
> +
> +Element Name Strings
> +~~~~~~~~~~~~~~~~~~~~
> +
> +Configuration name strings are required to consist of alphanumeric characters and '_' only. Other special characters are not permitted.
> +
> +::
> +   my_config_2          // is a valid name.
> +   this-bad-config#5    // this will not work

Instead of using code-block for name examples, what about "... For
example, foo_bar is a valid name where as foo-bar# is not."?

> +
> +This is in order to comply with the requirements of the perf command line.
> +
> +It is recommended that Feature and Parameter names use the same convention to allow for future enhancements to the command line syntax.
> +
> +CONFIG_ELEM element
> +~~~~~~~~~~~~~~~~~~~
> +
> +::
> +
> +   [cscfg_file_elem_header]                // header length value to end of feature strings.
> +   [cscfg_file_elem_str]                   // name of the configuration.
> +                                           // (see element string name requirements)
> +   [cscfg_file_elem_str]                   // description of configuration.
> +   [u16 value](nr_presets)                 // number of defined sets presets values.
> +   [u32 value](nr_total_params)            // total parameters defined by all used features.
> +   [u16 value](nr_feat_refs)               // number of features referenced by the configuration
> +   [u64 values] * (nr_presets * nr_total_params)     // the preset values.
> +   [cscfg_file_elem_str] * (nr_feat_refs)  // names of features used in the configurations.
> +
> +FEATURE_ELEM element
> +~~~~~~~~~~~~~~~~~~~~
> +
> +::
> +
> +   [cscfg_file_elem_header]                // header length is total bytes to end of param structures.
> +   [cscfg_file_elem_str]                   // feature name.
> +   [cscfg_file_elem_str]                   // feature description.
> +   [u32 value](match_flags)                // flags to associate the feature with a device.
> +   [u16 value](nr_regs)                    // number of registers.
> +   [u16 value](nr_params)                  // number of parameters.
> +   [cscfg_regval_desc struct] * (nr_regs)  // register definitions
> +   [PARAM_ELEM] * (nr_params)              // parameters definitions
> +
> +PARAM_ELEM element
> +~~~~~~~~~~~~~~~~~~
> +
> +::
> +
> +   [cscfg_file_elem_str]         // parameter name.
> +   [u64 value](param_value)      // initial value.
> +
> +Additional definitions.
> +~~~~~~~~~~~~~~~~~~~~~~~

Trim trailing period for section names

> +
> +The following structures are defined in **coresight-config-file.h**
> +
> + * **struct cscfg_file_header** : This structure contains an initial magic number, the total
> +   length of the file, and the number of configurations and features in the file.
> + * **struct cscfg_file_elem_header**: This defines the total length and type of a CONFIG_ELEM
> +   or a FEATURE_ELEM.
> + * **struct cscfg_file_elem_str**: This defines a string and its length.

Again, for consistency, wrap identifier names in single-quotes.

> +
> +The magic number in cscfg_file_header is defined as two bitfields::
> +
> +   [31:8] Fixed magic number to identify file type.
> +   [7:0]  Current file format version.
> +
> +The following defines determine the maximum overall file size and maximum individual
> +string size::
> +
> +   CSCFG_FILE_MAXSIZE       // maximum overall file size.
> +   CSCFG_FILE_STR_MAXSIZE   // maximum individual string size.

For parameter lists in elements, use bullet lists instead.

> +
> +Load Dependencies.
> +~~~~~~~~~~~~~~~~~~

Trim trailing period for section names.
> +
> +Files may be unloaded only in the strict reverse order of loading. This is enforced by the
> +configuration system.
> +
> +This is to ensure that any load dependencies are maintained.
> +
> +A configuration file that contains a CONFIG_ELEM that references named features "feat_A" and "feat_B" will load only if either:-
> +a) "feat_A" and/or "feat_B" has been loaded previously, or are present as built-in / module loaded features.
> +b) "feat_A" and/or "feat_B" are declared as FEAT_ELEM in the same file as the CONFIG_ELEM.

Separate the preceding paragraph and the list with a blank line in order
for the list to be rendered as list.

Thanks.
  

Hi Bagas,

On Wed, 21 Dec 2022 at 03:55, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> On Mon, Dec 19, 2022 at 11:46:38PM +0000, Mike Leach wrote:
> > diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst
> > index 6d5ffa6f7347..109053eb1b93 100644
> > --- a/Documentation/trace/coresight/coresight-config.rst
> > +++ b/Documentation/trace/coresight/coresight-config.rst
> > @@ -141,11 +141,11 @@ Mount configfs as normal and the 'cs-syscfg' subsystem will appear::
> >      $ ls /config
> >      cs-syscfg  stp-policy
> >
> > -This has two sub-directories::
> > +This has two sub-directories, with the load and unload attribute files::
> >
> >      $ cd cs-syscfg/
> >      $ ls
> > -    configurations  features
> > +    configurations features load  unload
> >
> >  The system has the configuration 'autofdo' built in. It may be examined as
> >  follows::
> > @@ -278,9 +278,16 @@ Creating and Loading Custom Configurations
> >  ==========================================
> >
> >  Custom configurations and / or features can be dynamically loaded into the
> > -system by using a loadable module.
> > +system by using a loadable module, or by loading a binary configuration
> > +file in configfs.
> >
> > -An example of a custom configuration is found in ./samples/coresight.
> > +Loaded 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.
> > +
> > +
> > +Using a Loadable Module
> > +-----------------------
> >
> >  This creates a new configuration that uses the existing built in
> >  strobing feature, but provides a different set of presets.
> > @@ -289,6 +296,187 @@ 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.
> > +The file 'coresight-cfg-sample.c' contains the configuration and module
> > +initialisation code needed to create the loadable module.
> > +
> > +This will be built alongside the kernel modules if select in KConfig.
>
> What config options (CONFIG_) are required for above to work?
>
> > +
> > +An example of a custom configuration module is found in './samples/coresight'.
> > +
> > +Using a Binary Configuration File
> > +---------------------------------
> > +
> > +The './tools/coresight' directory contains example programs to generate and
> > +read and print binary configuration files.
> > +
> > +Building the tools creates the 'coresight-cfg-file-gen' program that will
> > +generate a configuration binary 'example1.cscfg' that can be loaded into the
> > +system using configfs. The configuration declared in the source file
> > +'coresight-cfg-example1.c' is named 'autofdo3' - the name that will be used
> > +once loaded.
> > +
> > +The source files 'coresight-cfg-bufw.h' and 'coresight-cfg-bufw.c' provide a
> > +standard function to convert a configuration declared in 'C' into the correct
> > +binary buffer format. These files can be re-used to create new custom
> > +configurations. Alternatively, addition examples can be added to the
>
> s/addition/additional/
>
> > +'coresight-cfg-file-gen' program::
> > +
> > +    $ ./coresight-cfg-file-gen
> > +    Coresight Configuration file Generator
> > +
> > +    Generating example1 example
> > +    Generating example2 example
> > +
> > +The program 'coresight-cfg-file-read' can read back and print a configuration
> > +binary. This is built using the file reader from the driver code
> > +(coresight-config-file.c), which is copied over into './tools/coresight' at
> > +build time.::
> > +
> > +    ./coresight-cfg-file-read example1.cscfg
> > +    CoreSight Configuration file reader
> > +    ============================================
> > +
> > +    Configuration 1
> > +    Name:- autofdo3
> > +    Description:-
> > +    Setup ETMs with strobing for autofdo
> > +    Supplied presets allow experimentation with mark-space ratio for various loads
> > +
> > +    Uses 1 features:-
> > +    Feature-1: strobing
> > +
> > +    Provides 4 sets of preset values, 2 presets per set
> > +    set[0]: 0x7d0, 0x64,
> > +    set[1]: 0x7d0, 0x3e8,
> > +    set[2]: 0x7d0, 0x1388,
> > +    set[3]: 0x7d0, 0x2710,
> > +
> > +    ============================================
> > +    File contains no features
> > +
> > +There are additional attributes in the cs-syscfg directory - load and
> > +unload that can be used to load and unload configuration binary files. To
> > +load, 'cat' the binary config into the load attribute::
> > +
> > +    $ ls /config/cs-syscfg
> > +    configurations features  load  unload
> > +    $ cat example1.cscfg > /config/cs-syscfg/load
> > +    $ ls /config/cs-syscfg/configurations/
> > +    autofdo  autofdo3
> > +
> > +To unload, use the same file in the unload attribute::
> > +
> > +    $ cat example1.cscfg > /config/cs-syscfg/unload
> > +    ls /config/cs-syscfg/configurations/
> > +    autofdo
> > +
> > +
> > +
> > +Binary Configuration File Format
> > +--------------------------------
> > +
> > +The file format is defined in the source file **coresight-config-file.h**
>
> Use single-quote for identifier names for consistency here.
>
> > +
> > +The source reader and generator examples produce a binary of this format.
> > +
> > +This arrangement is reproduced below:-
> > +
> > +Overall File structure
> > +~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +::
> > +
> > +   [cscfg_file_header]   // Mandatory
> > +   [CONFIG_ELEM]*        // Optional - multiple, defined by cscfg_file_header.nr_configs
> > +   [FEATURE_ELEM]*       // Optional - multiple, defined by cscfg_file_header.nr_features
> > +
> > +File is invalid if both [CONFIG_ELEM] and [FEATURE_ELEM] are omitted.
> > +
> > +A file that contains only [FEATURE_ELEM] may be loaded, and the features used
> > +by subsequently loaded files with [CONFIG_ELEM] elements.
> > +
> > +Element Name Strings
> > +~~~~~~~~~~~~~~~~~~~~
> > +
> > +Configuration name strings are required to consist of alphanumeric characters and '_' only. Other special characters are not permitted.
> > +
> > +::
> > +   my_config_2          // is a valid name.
> > +   this-bad-config#5    // this will not work
>
> Instead of using code-block for name examples, what about "... For
> example, foo_bar is a valid name where as foo-bar# is not."?
>
> > +
> > +This is in order to comply with the requirements of the perf command line.
> > +
> > +It is recommended that Feature and Parameter names use the same convention to allow for future enhancements to the command line syntax.
> > +
> > +CONFIG_ELEM element
> > +~~~~~~~~~~~~~~~~~~~
> > +
> > +::
> > +
> > +   [cscfg_file_elem_header]                // header length value to end of feature strings.
> > +   [cscfg_file_elem_str]                   // name of the configuration.
> > +                                           // (see element string name requirements)
> > +   [cscfg_file_elem_str]                   // description of configuration.
> > +   [u16 value](nr_presets)                 // number of defined sets presets values.
> > +   [u32 value](nr_total_params)            // total parameters defined by all used features.
> > +   [u16 value](nr_feat_refs)               // number of features referenced by the configuration
> > +   [u64 values] * (nr_presets * nr_total_params)     // the preset values.
> > +   [cscfg_file_elem_str] * (nr_feat_refs)  // names of features used in the configurations.
> > +
> > +FEATURE_ELEM element
> > +~~~~~~~~~~~~~~~~~~~~
> > +
> > +::
> > +
> > +   [cscfg_file_elem_header]                // header length is total bytes to end of param structures.
> > +   [cscfg_file_elem_str]                   // feature name.
> > +   [cscfg_file_elem_str]                   // feature description.
> > +   [u32 value](match_flags)                // flags to associate the feature with a device.
> > +   [u16 value](nr_regs)                    // number of registers.
> > +   [u16 value](nr_params)                  // number of parameters.
> > +   [cscfg_regval_desc struct] * (nr_regs)  // register definitions
> > +   [PARAM_ELEM] * (nr_params)              // parameters definitions
> > +
> > +PARAM_ELEM element
> > +~~~~~~~~~~~~~~~~~~
> > +
> > +::
> > +
> > +   [cscfg_file_elem_str]         // parameter name.
> > +   [u64 value](param_value)      // initial value.
> > +
> > +Additional definitions.
> > +~~~~~~~~~~~~~~~~~~~~~~~
>
> Trim trailing period for section names
>
> > +
> > +The following structures are defined in **coresight-config-file.h**
> > +
> > + * **struct cscfg_file_header** : This structure contains an initial magic number, the total
> > +   length of the file, and the number of configurations and features in the file.
> > + * **struct cscfg_file_elem_header**: This defines the total length and type of a CONFIG_ELEM
> > +   or a FEATURE_ELEM.
> > + * **struct cscfg_file_elem_str**: This defines a string and its length.
>
> Again, for consistency, wrap identifier names in single-quotes.
>
> > +
> > +The magic number in cscfg_file_header is defined as two bitfields::
> > +
> > +   [31:8] Fixed magic number to identify file type.
> > +   [7:0]  Current file format version.
> > +
> > +The following defines determine the maximum overall file size and maximum individual
> > +string size::
> > +
> > +   CSCFG_FILE_MAXSIZE       // maximum overall file size.
> > +   CSCFG_FILE_STR_MAXSIZE   // maximum individual string size.
>
> For parameter lists in elements, use bullet lists instead.
>
> > +
> > +Load Dependencies.
> > +~~~~~~~~~~~~~~~~~~
>
> Trim trailing period for section names.
> > +
> > +Files may be unloaded only in the strict reverse order of loading. This is enforced by the
> > +configuration system.
> > +
> > +This is to ensure that any load dependencies are maintained.
> > +
> > +A configuration file that contains a CONFIG_ELEM that references named features "feat_A" and "feat_B" will load only if either:-
> > +a) "feat_A" and/or "feat_B" has been loaded previously, or are present as built-in / module loaded features.
> > +b) "feat_A" and/or "feat_B" are declared as FEAT_ELEM in the same file as the CONFIG_ELEM.
>
> Separate the preceding paragraph and the list with a blank line in order
> for the list to be rendered as list.
>

The next version will contain all the adjustments that you suggested,
though rather than using single quotes, I have changed all the
occurrences to consistently the double back tick to make the filenames
etc fixed width font.

Thanks for the review

Mike


> Thanks.
>
> --
> An old man doll... just what I always wanted! - Clara



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