Add basic documentation of skiboot gcov

Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

1 files changed, 62 insertions, 0 deletions

diff --git a/doc/gcov.txt b/doc/gcov.txt
new file mode 100644
index 00000000..c5944d04
--- /dev/null
+++ b/doc/gcov.txt
@@ -0,0 +1,62 @@
+GCOV for skiboot
+----------------
+
+Unit tests
+----------
+All unit tests are built+run with gcov enabled.
+
+make coverage-report
+
+will generate a unit test coverage report like:
+http://open-power.github.io/skiboot/coverage-report/
+
+Skiboot
+-------
+You can now build Skiboot itself with gcov support, boot it on a machine,
+do things, and then extract out gcda files to generate coverage reports
+from real hardware (or a simulator).
+
+Building Skiboot with GCOV
+--------------------------
+
+SKIBOOT_GCOV=1 make
+
+You may need to "make clean" first.
+
+This will build a skiboot lid roughly *twice* the size.
+
+Flash/Install the skiboot.lid and boot.
+
+Extracting GCOV data
+--------------------
+The way we extract the gcov data from a system is by dumping the contents
+of skiboot memory and then parsing the data structures in user space with
+the extract-gcov utility in the skiboot repo.
+
+mambo:
+  mysim memory fwrite 0x30000000 0x240000 skiboot.dump
+FSP:
+  getmemproc 30000000 3407872 -fb skiboot.dump
+linux (e.g. petitboot environment):
+  dd if=/proc/kcore skip=1572864 count=6656  of=skiboot.dump
+
+You basically need to dump out the 2MB of skiboot.
+
+You will need to find the following message in the skiboot log:
+[2822590,5] GCOV: gcov_info_list at 0x3010a350
+
+That address needs to be supplied to the extract-gcov utility:
+./extract-gcov skiboot.dump 0x3010a350
+
+Once you've run extract-gcov, it will have extracted the gcda files
+from the skiboot memory image.
+
+You can then run lcov:
+lcov -b . -q -c -d . -o skiboot-boot.info \
+--gcov-tool
+/opt/cross/gcc-4.8.0-nolibc/powerpc64-linux/bin/powerpc64-linux-gcov
+
+*IMPORTANT* you should point lcov to the gcov for the compiler you used
+to build skiboot, otherwise you're likely to get errors.
+
+