aboutsummaryrefslogtreecommitdiffstats
path: root/resources/tools/presentation/doc/pal_lld.rst
diff options
context:
space:
mode:
Diffstat (limited to 'resources/tools/presentation/doc/pal_lld.rst')
-rw-r--r--resources/tools/presentation/doc/pal_lld.rst116
1 files changed, 98 insertions, 18 deletions
diff --git a/resources/tools/presentation/doc/pal_lld.rst b/resources/tools/presentation/doc/pal_lld.rst
index 027d6b326a..64bde3e5fe 100644
--- a/resources/tools/presentation/doc/pal_lld.rst
+++ b/resources/tools/presentation/doc/pal_lld.rst
@@ -1109,8 +1109,9 @@ For example, the element which specification includes:
filter:
- "'64B' and 'BASE' and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
-will be constructed using data from the job "csit-vpp-perf-1707-all", for all listed
-builds and the tests with the list of tags matching the filter conditions.
+will be constructed using data from the job "csit-vpp-perf-1707-all", for all
+listed builds and the tests with the list of tags matching the filter
+conditions.
The output data structure for filtered test data is:
@@ -1189,6 +1190,83 @@ Subset of existing performance tests is covered by TSA graphs.
"plot-throughput-speedup-analysis"
+Comparison of results from two sets of the same test executions
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This algorithm enables comparison of results coming from two sets of the
+same test executions. It is used to quantify performance changes across
+all tests after test environment changes e.g. Operating System
+upgrades/patches, Hardware changes.
+
+It is assumed that each set of test executions includes multiple runs
+of the same tests, 10 or more, to verify test results repeatibility and
+to yield statistically meaningful results data.
+
+Comparison results are presented in a table with a specified number of
+the best and the worst relative changes between the two sets. Following table
+columns are defined:
+
+ - name of the test;
+ - throughput mean values of the reference set;
+ - throughput standard deviation of the reference set;
+ - throughput mean values of the set to compare;
+ - throughput standard deviation of the set to compare;
+ - relative change of the mean values.
+
+**The model**
+
+The model specifies:
+
+ - type: "table" - means this section defines a table.
+ - title: Title of the table.
+ - algorithm: Algorithm which is used to generate the table. The other
+ parameters in this section must provide all information needed by the used
+ algorithm.
+ - output-file-ext: Extension of the output file.
+ - output-file: File which the table will be written to.
+ - reference - the builds which are used as the reference for comparison.
+ - compare - the builds which are compared to the reference.
+ - data: Specify the sources, jobs and builds, providing data for generating
+ the table.
+ - filter: Filter based on tags applied on the input data, if "template" is
+ used, filtering is based on the template.
+ - parameters: Only these parameters will be put to the output data
+ structure.
+ - nr-of-tests-shown: Number of the best and the worst tests presented in the
+ table. Use 0 (zero) to present all tests.
+
+*Example:*
+
+::
+
+ -
+ type: "table"
+ title: "Performance comparison"
+ algorithm: "table_performance_comparison"
+ output-file-ext: ".csv"
+ output-file: "{DIR[DTR,PERF,VPP,IMPRV]}/vpp_performance_comparison"
+ reference:
+ title: "csit-vpp-perf-1801-all - 1"
+ data:
+ csit-vpp-perf-1801-all:
+ - 1
+ - 2
+ compare:
+ title: "csit-vpp-perf-1801-all - 2"
+ data:
+ csit-vpp-perf-1801-all:
+ - 1
+ - 2
+ data:
+ "vpp-perf-comparison"
+ filter: "all"
+ parameters:
+ - "name"
+ - "parent"
+ - "throughput"
+ nr-of-tests-shown: 20
+
+
Advanced data analytics
```````````````````````
@@ -1216,7 +1294,8 @@ Tables
- tables are generated by algorithms implemented in PAL, the model includes the
algorithm and all necessary information.
- output format: csv
- - generated tables are stored in specified directories and linked to .rst files.
+ - generated tables are stored in specified directories and linked to .rst
+ files.
Plots
@@ -1232,8 +1311,8 @@ Report generation
-----------------
Report is generated using Sphinx and Read_the_Docs template. PAL generates html
-and pdf formats. It is possible to define the content of the report by specifying
-the version (TODO: define the names and content of versions).
+and pdf formats. It is possible to define the content of the report by
+specifying the version (TODO: define the names and content of versions).
The process
@@ -1251,12 +1330,13 @@ The process
5. Generate the report.
6. Store the report (Nexus).
-The process is model driven. The elements’ models (tables, plots, files and
-report itself) are defined in the specification file. Script reads the elements’
-models from specification file and generates the elements.
+The process is model driven. The elements' models (tables, plots, files
+and report itself) are defined in the specification file. Script reads
+the elements' models from specification file and generates the elements.
-It is easy to add elements to be generated, if a new kind of element is
-required, only a new algorithm is implemented and integrated.
+It is easy to add elements to be generated in the report. If a new type
+of an element is required, only a new algorithm needs to be implemented
+and integrated.
API
@@ -1396,12 +1476,12 @@ PAL functional diagram
How to add an element
`````````````````````
-Element can be added by adding its model to the specification file. If the
-element will be generated by an existing algorithm, only its parameters must be
-set.
+Element can be added by adding it's model to the specification file. If
+the element is to be generated by an existing algorithm, only it's
+parameters must be set.
-If a brand new type of element will be added, also the algorithm must be
-implemented.
-The algorithms are implemented in the files which names start with "generator".
-The name of the function implementing the algorithm and the name of algorithm in
-the specification file had to be the same.
+If a brand new type of element needs to be added, also the algorithm
+must be implemented. Element generation algorithms are implemented in
+the files with names starting with "generator" prefix. The name of the
+function implementing the algorithm and the name of algorithm in the
+specification file have to be the same.