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

[Jan Beulich <jbeulich@xxxxxxxx>]

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.

> +     - 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?

Jan