Re: [PATCH v2 15/15] gpu: nova-core: document the GIN interrupt controller and GSP events

[Alexandre Courbot]

On Sat Aug 29, 2026 at 10:33 AM JST, John Hubbard wrote:
<...>
> +Terminology
> +===========
> +
> +Three different numbers are all called a "vector" in the surrounding material.
> +This document gives each one its own name and never uses "vector" on its own.
> +
> +GIN vector
> +    The GPU-internal interrupt source number, 0 through 511 on Hopper. It is a
> +    bit address within the tree: leaf ``vector / 32``, bit ``vector % 32``. The
> +    CPU doorbell is GIN vector 129 and the GSP event is GIN vector 155.
> +
> +MSI-X entry
> +    An index into the device's MSI-X table, 0 through 7 on Hopper. Linux's
> +    ``struct msix_entry`` names its Linux IRQ number ``.vector``, which is a
> +    third meaning.
> +
> +Linux IRQ number
> +    What ``request_irq()`` takes, obtained from ``pci_irq_vector()``.
> +
> +The remaining terms, each named for the register or the specification that owns
> +it:

Coming to this patch series without any preliminary knowledge of
interrupts handling on NVIDIA GPUs, I would have found it useful if
leaf, subtree, and tree were also defined here.

> +
> +enable / disable a GIN vector
> +    ``LEAF_EN_SET`` and ``LEAF_EN_CLEAR``.
> +
> +enable / disable a subtree
> +    ``TOP_EN_SET`` and ``TOP_EN_CLEAR``.
> +
> +serviced subtree
> +    A subtree nova-core enables and has a handler for.
> +
> +rearm
> +    Restoring PCI interrupt delivery after servicing an interrupt. It is a
> +    ``TOP_EN`` disable-then-enable cycle everywhere except under pre-Hopper
> +    MSI, where it is a write to the end-of-interrupt (EOI) register in the BAR0
> +    configuration-space mirror (see "Rearming PCI interrupt delivery").
> +
> +mask
> +    Reserved for the two places hardware and the PCI specification use the
> +    word: the MSI-X per-entry Vector Control mask bit, which Linux owns, and
> +    the falcon cause masks. It never names a GIN enable.
> +
> +latched, pending
> +    A ``LEAF`` bit records its source whether or not the GIN vector is enabled.
> +    A disabled vector's pending bit never appears in ``TOP``.

IIUC a disabled vector's pending bits doesn't contribute to its
subtree's `TOP` bit. Something like "A disabled vector's pending bit
doesn't signal its leaf in ``TOP``" sounds more accurate to me.