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

["Halder, Ayan Kumar" <ayankuma@xxxxxxx>]

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.
harunobu.kurokawa.dn@xxxxxxxxxxx is investigating this for Xen.

- Ayan

> Jan