Hi Mathieu,
On Thu, 13 Jan 2022 at 18:16, Mathieu Poirier mathieu.poirier@linaro.org wrote:
More comments...
On Tue, Nov 30, 2021 at 10:01:00PM +0000, Mike Leach wrote:
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.
Signed-off-by: Mike Leach mike.leach@linaro.org
.../trace/coresight/coresight-config.rst | 151 +++++++++++++++++- 1 file changed, 145 insertions(+), 6 deletions(-)
diff --git a/Documentation/trace/coresight/coresight-config.rst b/Documentation/trace/coresight/coresight-config.rst index 6d5ffa6f7347..f11def230fab 100644 --- a/Documentation/trace/coresight/coresight-config.rst +++ b/Documentation/trace/coresight/coresight-config.rst @@ -152,7 +152,7 @@ follows::
$ cd configurations/ $ ls
- autofdo
- autofdo last_load_status load unload $ cd autofdo/ $ ls description feature_refs preset1 preset3 preset5 preset7 preset9
@@ -278,9 +278,19 @@ 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.
+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.
+An example of a custom configuration module, and generators for binary +configuration files are found in './samples/coresight'.
-An example of a custom configuration is found in ./samples/coresight.
+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 +299,135 @@ 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.
+Using a Binary Configuration File +---------------------------------
+Building the samples creates the 'coresight-cfg-filegen' 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-filegen.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.
+The program 'coresight-cfg-file-read' can read back and print a configuration +binary. This is built using the reader from the driver code.
+There are additional attributes in the configurations directory - load, unload +and last_load_status 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/
- autofdo last_load_status load unload
- $ cat example1.cscfg > /config/cs-syscfg/configurations/load
- $ ls /config/cs-syscfg/configurations/
- autofdo autofdo3 last_load_status load unload
- $ cat /config/cs-syscfg/configurations/last_load_status
- OK: configuration file loaded (autofdo3).
+To unload, use the same file in the unload attribute::
- $ cat example1.cscfg > /config/cs-syscfg/configurations/unload
- $ cat /config/cs-syscfg/configurations/last_load_status
- OK: configuration file unloaded (autofdo3).
- ls /config/cs-syscfg/configurations/
- autofdo last_load_status load unload
I'm not certain that "last_load_status" is needed. To me seeing the name of a newly added configuration should be enough to confirm a successful status. The same applies to unload.
Again - this makes more sense after the next ETM patchset that uses resource management - this status is more useful when features or configurations fail to load - as this can be due to insufficient resources on the system. When we have portable binary configuration files, loading via configfs, then this information is important to users.
Thanks
Mike
Thanks, Mathieu
+The generator and reader programs can also be built directly, separately from +the kernel build by using the 'Makefile.host' file. This allows native binaries +to be created on the host machine rather than cross compiled version for the +target.
+Binary Configuration File Format +--------------------------------
+The file format is defined in the source file **coresight-config-file.h**
+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 - one per file, if present, first element in file.
- [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.
+Where [CONFIG_ELEM] is present, then **cscfg_file_header.nr_features** and +**CONFIG_ELEM.nr_feat_refs** must have the same value.
+CONFIG_ELEM element +~~~~~~~~~~~~~~~~~~~
+::
- [cscfg_file_elem_header] // header length value to end of feature strings.
- [cscfg_file_elem_str] // name of the configuration.
- [cscfg_file_elem_str] // description of configuration.
- [u16 value](nr_presets) // number of defined presets.
- [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) // the 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. +~~~~~~~~~~~~~~~~~~~~~~~
+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 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.
+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.
-- 2.17.1