Re: [XEN PATCH v1 1/2] docs/fusa: add coverage_gap.rst tabulating vGICv3 LCOV exclusions

Hi Jan,

On 21/07/2026 14:00, Jan Beulich wrote:
> On 21.07.2026 14:47, Ayan Kumar Halder wrote:
>> --- /dev/null
>> +++ b/docs/fusa/coverage_gap.rst
>> @@ -0,0 +1,41 @@
>> +.. SPDX-License-Identifier: CC-BY-4.0
>> +
>> +Coverage gaps
>> +=============
>> +
>> +This table documents the ``LCOV_EXCL`` regions in the Xen source. Each excluded
>> +region is tagged in the source with a ``COV-GAP-<COMPONENT>-NNN`` marker that
>> +matches an entry below. A region is excluded from the coverage report only when
>> +it is unreachable by design, so it can never be reported as covered.
>> +
>> +.. list-table::
>> +   :header-rows: 1
>> +   :widths: 15 25 10 12 38
>> +
>> +   * - coverage_gap_id
>> +     - file
>> +     - line numbers
>> +     - SHA
> What specific algorithm? Or wait, this isn't a hash of the file, but a commit
> hash. This imo wants clarifying.
It is a commit hash.
>
>> +     - justification
>> +   * - COV-GAP-VGICV3-001
>> +     - xen/arch/arm/vgic-v3.c
>> +     - L796-L800
>> +     - 351d41e8aecc3f7566a0baa7b4066d06dedd7113
>> +     - Both callers select the register offset with their own ``switch`` and
>> +       forward only offsets the handler has an explicit ``case`` for, so no
>> +       forwarded offset can fall through to ``default:``. (The SGI_base-frame
>> +       ``GICR_*`` offsets one caller forwards are numerically equal to the
>> +       ``GICD_*`` offsets the handler cases on.) The ``default:`` is kept as
>> +       defensive programming; it becomes reachable only if a caller is
>> +       modified to forward an offset the handler has no ``case`` for, at
>> +       which point this exclusion must be removed.
> All of this is liable to go stale. Once it has gone stale, this information
> is pretty much useless aiui. And it may well be worse than that, if the
> "must be removed" isn't actually followed (perhaps simply because there's
> no link from the source to here). How's all of this going to be helpful
> longer term?

Using SPDX SBOM, you can link a document to a piece of code to a commit 
SHA. This was something that linux kernel has recently developed and 
upstreamed.

https://docs.kernel.org/tools/sbom/sbom.html . Zephyr project has 
developed this as well.

[email protected] is investigating this for Xen.

- Ayan

>
> Jan