[rtems-docs commit] user/testing: Add coverage analysis instructions

[Christian Mauderer]

Module:    rtems-docs
Branch:    master
Commit:    d45c51a95e401b6d20b4483eebf4c0d601d95f51
Changeset: http://git.rtems.org/rtems-docs/commit/?id=d45c51a95e401b6d20b4483eebf4c0d601d95f51

Author:    Vijay Kumar Banerjee <vijaykumar9597 at gmail.com>
Date:      Mon Feb  3 15:53:58 2020 +0530

user/testing: Add coverage analysis instructions

---

 user/testing/coverage.rst | 68 +++++++++++++++++++++++++++++++++++++++++++++++
 user/testing/index.rst    |  1 +
 2 files changed, 69 insertions(+)

diff --git a/user/testing/coverage.rst b/user/testing/coverage.rst
new file mode 100644
index 0000000..4f2266e
--- /dev/null
+++ b/user/testing/coverage.rst
@@ -0,0 +1,68 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2019 Vijay Kumar Banerjee <vijaykumar9597 at gmail.com>
+
+Coverage Analysis
+=================
+
+RTEMS is used in many critical systems. It is important that the RTEMS Project
+ensure that the RTEMS product is tested as thoroughly as possible. With this
+goal in mind, the RTEMS test suite was expanded with the goal that 100% of the
+RTEMS executive is tested.
+
+RTEMS-TESTER takes the following arguments to produce coverage reports:
+
+`--coverage :`
+    When the coverage option is enabled the tester produces coverage reports for
+    all the symbols in cpukit. To generate a coverage report for a specific
+    symbol-set ( e.g.: score) the symbol-set is passed as an argument to the
+    option, e.g.: --coverage=score.
+
+`--no-clean :`
+    Tells the script not to delete the .cov trace files generated while running
+    the coverage. These trace files are used for debugging purposes and will not
+    be needed for a normal user.
+
+For example: To generate a coverage report of hello.exe for leon3 on SIS, the
+following command is used:
+
+.. code-block:: none
+
+    rtems-test \
+    --rtems-tools=$HOME/development/rtems/5 \
+    --log=coverage_analysis.log \
+    --no-clean \
+    --coverage \
+    --rtems-bsp=leon3-sis-cov \
+    $HOME/development/rtems/kernel/leon3/sparc-rtems5/c/leon3/testsuites/samples/hello.exe
+
+The command will create the coverage report in the following tree structure:
+
+.. code-block:: none
+
+    ├── coverage_analysis.log
+    ├── leon3-sis-coverage
+    │   └── score
+    │       ├── annotated.html
+    │       ├── annotated.txt
+    │       ├── branch.html
+    │       ├── branch.txt
+    │       ├── covoar.css
+    │       ├── ExplanationsNotFound.txt
+    │       ├── index.html
+    │       ├── no_range_uncovered.html
+    │       ├── no_range_uncovered.txt
+    │       ├── NotReferenced.html
+    │       ├── sizes.html
+    │       ├── sizes.txt
+    │       ├── summary.txt
+    │       ├── symbolSummary.html
+    │       ├── symbolSummary.txt
+    │       ├── table.js
+    │       ├── uncovered.html
+    │       └── uncovered.txt
+    └── leon3-sis-report.html
+
+The html on top of the directory, i.e., leon3-sis-report.html is the top level
+navigation for the coverage analysis report and will let the user browse through
+all the generated reports from different subsystems.
diff --git a/user/testing/index.rst b/user/testing/index.rst
index a938af4..3d36fab 100644
--- a/user/testing/index.rst
+++ b/user/testing/index.rst
@@ -43,6 +43,7 @@ extension.
 
    tests
    configuration
+   coverage
    consoles
    simulation
    gdb-jtag