[PATCH] Coverage: Documentation for the coverage mapping format

[Alex Lorenz]

================
Comment at: docs/CoverageMappingFormat.rst:51
@@ +50,3 @@
+
+  ``llvm-cov show test -instr-profile=test.profdata test.c``
+
----------------
Sean Silva wrote:
> Tiny nit: please use `./test` here instead of just `test` so that it is clear that `test` is not a subcommand of `llvm-cov show`. (I personally got tripped up by this) Also move the `./test` after `-instr-profile=test.profdata` (unless the syntax of llvm-cov doesn't allow it? which would be weird)
Currently, llvm-cov requires that the object file name is the first argument after the command, thus `./test` has to be before `-instr-profile=test.profdata`. This might be changed in the future though.

================
Comment at: docs/CoverageMappingFormat.rst:325-326
@@ +324,4 @@
+    counter expressions.
+  * The fourth byte has a value of 1. It stores the number of mapping
+    regions that are stored in an array for file id #0.
+  * The fifth byte stores the coverage mapping counter for the
----------------
Sean Silva wrote:
> Why is the total number of mapping regions for the whole file (which could contain many functions) encoded in the per-function data?
Those coverage mapping file ids are only meaningful in a context of a single function.
The new description says:
  The number of mapping regions that are stored in an array for the function's file id #0.
Which hopefully makes it more clear.

================
Comment at: docs/CoverageMappingFormat.rst:397-405
@@ +396,11 @@
+
+A `coverage mapping counter`_ is stored in a single `LEB value <LEB128_>`_.
+The value uses the following encoding:
+
+``[tag : 2, data : 30]``
+
+This value contains
+2 bit fields --- the `tag <counter-tag_>`_
+which is stored in the lowest 2 bits,
+and the `counter data`_ which is stored in the remaining bits.
+
----------------
Sean Silva wrote:
> This isn't clear to me. What exactly does a fixed-size bit field in a LEB128 mean? Is this after it is supposedly interpreted into a 32-bit int? What endianness? Please clarify.
I've got rid of the 
    `[tag : 2, data : 30]`
part, but still kept the description. There is no real fixed size limit here, it's just that the implementation assumes that the counter fits in a 32 bit integer.
The updated description reads:

    A `coverage mapping counter`_ is stored in a single `LEB value <LEB128_>`_.
    It is composed of two things --- the `tag <counter-tag_>`_
    which is stored in the lowest 2 bits, and the `counter data`_ which is stored
    in the remaining bits.

I think it's clear that the extraction of 2 integers of widths 2 bits and remaining bits happens after the LEB value is decoded. As far as I understand, the endianness here doesn't matter as the LEB values are always encoded in little endian, and the 2 host endian integers are extracted from the decoded LEB integer which is already host endian.

================
Comment at: docs/CoverageMappingFormat.rst:493
@@ +492,3 @@
+
+The value of the counter's tag distinguishes between the pseudo-counters and
+counters --- if the tag is zero, than this header contains a
----------------
Sean Silva wrote:
> By pseudo-counter do you mean "expression counter"?
No, It's pseudo-counter from line 503.

================
Comment at: docs/CoverageMappingFormat.rst:332-333
@@ +331,4 @@
+
+Counter expressions consist of two counters as they
+represent binary arithmetic operations.
+
----------------
Sean Silva wrote:
> How do you know which operation to apply? There seems to be a LHS and a RHS but no "opcode".
The opcode is derived from the actual counter that uses this expression, I've added a mention for this in the updated patch.

http://reviews.llvm.org/D4729