path: root/Documentation/gpu/nova/core/interrupts.rst

.. SPDX-License-Identifier: GPL-2.0
.. SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.

=============================================
GPU interrupt handling: GIN and the GSP event
=============================================

This document describes how nova-core receives interrupts from the GPU on Turing
and later chipsets. It covers the GPU Interrupt and Notification unit (GIN),
which is the GPU's interrupt controller, and the GSP event, the interrupt that
nova-core services in normal operation.

Throughout, *CPU* means the CPU and the nova-core driver running on it. The GPU
also has on-chip processors that run their own firmware and receive their own
interrupts. The GSP (GPU System Processor) is one of them.

Register names are the names from the GPU hardware reference headers. The
pre-Hopper headers call the controller ``NV_CTRL`` and the Hopper-plus headers
call it ``NV_GIN``. This document calls it GIN throughout, because the tree that
nova-core services is the same on every supported chipset. OpenRM, NVIDIA's
open-source GPU kernel driver, is cited wherever nova-core follows it.

Terminology
===========

The three levels of the controller, innermost first:

leaf
    One ``LEAF`` register. Each of its 32 bits is the pending bit of one
    interrupt source. A Turing, Ampere, or Ada tree has 8 leaves. A Hopper or
    Blackwell tree has 16.

subtree
    Two consecutive leaves, summarized by one bit of ``TOP``. A subtree is the
    unit of enabling at ``TOP``, and under MSI-X it is the unit of delivery:
    every interrupt from one subtree arrives on one MSI-X entry.

tree
    One ``TOP`` register and the leaves under it. Every PCIe function has its
    own tree, and nova-core services the CPU tree of one function.

The hardware headers, OpenRM, and the Linux PCI API all use the word "vector",
each for a different number. This document gives each one its own name, and a
bare "vector" always means a GIN vector.

GIN vector
    The GPU-internal interrupt source number. It addresses one bit of one leaf.
    A 16-leaf tree holds vectors 0 through 511, and an 8-leaf tree holds 0
    through 255. The CPU doorbell is vector 129 and the GSP event is vector
    155.

MSI-X entry
    An index into the device's MSI-X table. One entry serves one subtree.

PCI vector
    One of the interrupts that ``pci_alloc_irq_vectors()`` allocates: an MSI-X
    entry, or the single MSI message.

Linux IRQ number
    What ``request_irq()`` takes, obtained from ``pci_irq_vector()`` for a PCI
    vector. Linux's ``struct msix_entry`` calls this number ``.vector`` as
    well.

The remaining terms, each named for the register or the specification that
defines it:

enable, disable a vector
    Writes to ``LEAF_EN_SET`` and ``LEAF_EN_CLEAR``.

enable, disable a subtree
    Writes to ``TOP_EN_SET`` and ``TOP_EN_CLEAR``.

serviced subtree
    A subtree that nova-core enables and has a handler for.

rearm
    Restoring PCI interrupt delivery after servicing an interrupt. See
    "Rearming PCI interrupt delivery".

mask
    Reserved for the two places where hardware and the PCI specification use
    the word: the MSI-X per-entry Vector Control mask bit, which Linux
    controls, and the falcon interrupt masks. It never names a GIN enable.

latched, pending
    Two names for one state, a set ``LEAF`` bit. The vector's source sets the
    bit whether or not the vector is enabled.

clear a vector
    Write a 1 to the vector's bit in ``LEAF``. OpenRM calls the same operation
    ``intrClearLeafVector_HAL``.

pending bits
    The plain 32-bit value read from a ``LEAF`` register.

notification
    An interrupt whose only content is that something happened, such as a
    posted message. Servicing a notification means reading what it announces.
    The unit that raised it needs no attention. The GSP event is one.

unit
    Any block that raises an interrupt. "Engine" is reserved for the blocks
    that do user work: GR, CE, NVDEC, and the like.

falcon
    One of the GPU's microcontrollers (see
    Documentation/gpu/nova/core/falcon.rst). The GSP runs on the RISC-V core
    inside its falcon. A falcon latches each of its interrupt causes and routes
    it either to the host, meaning the CPU, or to its own core.

The GIN controller
==================

A GPU has many interrupt sources: the GSP, the copy engines, the graphics
engine, video decode and encode, the MMU fault path, timers, and others. GIN
records which of them are pending and raises the PCI interrupt to the CPU.

Trees
-----

GIN keeps one tree for each destination it can deliver an interrupt to. The CPU
has one tree per PCIe function, so the physical function and each virtual
function have their own. The GSP has a tree, and so do the other on-chip
processors that receive interrupts. Every tree has the same two-level layout,
and a function reaches its own tree through the per-function register aperture.

nova-core services the CPU tree of one function. A virtual function's tree
belongs to that function's driver, and a processor's tree belongs to the
firmware running on that processor.

The two-level tree
------------------

A tree is a set of ``LEAF`` registers and one ``TOP`` register.

* ``LEAF(i)`` is a 32-bit register that holds the pending bits of vectors
  ``32i`` through ``32i + 31``. A set bit is a pending vector.
* ``TOP`` is a 32-bit read-only register. Bit ``N`` summarizes subtree ``N``,
  which is ``LEAF(2N)`` and ``LEAF(2N + 1)``. The bit is set when an enabled
  vector is pending in either leaf.

A tree with L leaves has L / 2 subtrees and uses TOP bits 0 through L / 2 - 1.
The other TOP bits read 0. The leaves and subtrees that a chipset has are its
implemented leaves and subtrees, and "Per-architecture differences" gives the
counts. For an 8-leaf tree::

    TOP bit 0  ->  subtree 0  ->  LEAF(0), LEAF(1)   vectors   0..63
    TOP bit 1  ->  subtree 1  ->  LEAF(2), LEAF(3)   vectors  64..127
    TOP bit 2  ->  subtree 2  ->  LEAF(4), LEAF(5)   vectors 128..191
    TOP bit 3  ->  subtree 3  ->  LEAF(6), LEAF(7)   vectors 192..255

    LEAF(4), one bit per vector, holds vectors 128..159:

      bit 1  = vector 129  (CPU doorbell)
      bit 27 = vector 155  (GSP event)

A vector's number fixes its place in the tree::

    leaf    = vector / 32
    bit     = vector % 32
    subtree = leaf / 2

Registers
---------

nova-core defines the tree's registers in the ``irq`` module's ``regs.rs``. The
leaf registers are arrays indexed by leaf number.

* ``LEAF(i)`` reads as the pending bits of leaf ``i``. Writing a 1 to a bit
  clears that vector, and a 0 leaves the bit as it was.
* ``LEAF_EN_SET(i)`` and ``LEAF_EN_CLEAR(i)`` enable and disable the vectors
  of leaf ``i``, one bit per vector.
* ``TOP_EN_SET`` and ``TOP_EN_CLEAR`` enable and disable subtrees, one bit per
  subtree.
* ``LEAF_TRIGGER`` takes a vector number and latches that vector, exactly as
  the vector's own source would. It is write-only. The self-test uses it.

nova-core does not read ``TOP``. "Servicing the tree" says why.

Every set and clear register acts per bit: a 1 performs the action for that
bit, and a 0 leaves the bit alone. No register needs a read-modify-write.

GIN delivers a vector to the CPU only when its leaf enable bit and its
subtree's TOP enable bit are both set. The enables do not affect the latch. The
source of a disabled vector still sets its ``LEAF`` bit. ``TOP`` does not show
that bit, so reading the leaf is the only way to see it.

How a unit interrupt reaches the CPU
------------------------------------

A unit does not write a ``LEAF`` register. Each unit has an interrupt control
register that GSP firmware programs. The control register holds the unit's
vector, the GFID that identifies the PCIe function whose tree receives the
interrupt, and one enable bit per destination: the CPU, the GSP, and the other
on-chip processors. When the unit has an event::

    1. The unit sends GIN an interrupt message carrying the vector, the GFID,
       and the destination enables from its control register.
    2. In the tree of each destination that the message selects, GIN sets bit
       (vector % 32) of LEAF(vector / 32).
    3. If the vector and its subtree are enabled in the CPU tree, GIN raises
       the PCI interrupt.

Because firmware assigns the vectors, nova-core does not hardcode which vector
belongs to which unit, with two exceptions. The hardware headers of every
supported chipset define the GSP event as vector 155, and GSP firmware's own
interrupt table uses that definition. The CPU doorbell is vector 129. Pre-Hopper
hardware fixes that number, and GSP firmware keeps it on Hopper and later.
nova-core names both by number. A driver can fetch the full unit-to-vector
table from the GSP by RPC, and nouveau does. nova-core does not, because a
fixed vector needs no lookup.

Edge-triggered delivery
-----------------------

A ``LEAF`` bit is a latch. Its source sets it on a rising edge, and it stays set
until the CPU clears it. A source that stays high does not set the bit again.

GIN raises the PCI interrupt for a subtree when the subtree's enabled pending
state goes from low to high::

    Per vector, in leaf i at bit b:
        LEAF(i)[b] AND LEAF_EN(i)[b]

    Per subtree N, across leaves 2N and 2N + 1:
        OR of every enabled pending bit  ->  TOP[N]

    Delivery for subtree N:
        TOP[N] AND TOP_EN[N]  ->  rising edge  ->  PCI interrupt

``TOP_EN`` applies after the summary, so disabling a subtree stops delivery
without changing what ``TOP`` reports.

Three consequences:

* Code that must find every pending vector reads the leaves. A vector that
  latched while disabled is not in ``TOP``.
* Writing ``TOP_EN_SET`` for a subtree with an enabled pending bit produces a
  new edge. GIN delivers an interrupt for a pending bit left uncleared as soon
  as its subtree is enabled again.
* A source that holds its signal high produces no new edge after the CPU
  clears the leaf bit. Such a source has to re-emit its interrupt. The falcons
  do that through ``INTR_RETRIGGER`` (see "Retriggering a falcon").

Delivery over PCI
=================

GIN delivers the tree's interrupts to the CPU as MSI or MSI-X, whichever Linux
grants. nova-core requests MSI-X first and falls back to MSI, and never uses
INTx.

MSI has a single message, and every subtree raises that one message, so one
Linux IRQ serves the whole tree.

MSI-X gives each subtree its own table entry, at the index equal to the subtree
number. Linux masks every entry until a driver requests its Linux IRQ number,
and a masked entry sends no message: the GPU records the interrupt in the MSI-X
pending bit array, where it stays until Linux unmasks the entry. An entry that
the driver never requests is never unmasked. A driver that enables a subtree
without requesting that subtree's entry loses every interrupt from that
subtree, with nothing reported: the leaf and TOP registers show the vector
pending and enabled while no handler runs.

The serviced-subtree invariant
------------------------------

Every subtree enabled at ``TOP`` has an allocated PCI vector with a registered
handler.

MSI satisfies this with its single message. MSI-X needs one allocated entry per
serviced subtree, and a PCI allocation cannot be sparse, so nova-core requests
entries 0 through the highest serviced subtree::

    MSI-X, with subtree 2 serviced:

      subtree 0  ->  entry 0   allocated, no handler, stays masked
      subtree 1  ->  entry 1   allocated, no handler, stays masked
      subtree 2  ->  entry 2   handler here, and its rearm covers subtree 2

    MSI, with any serviced set:

      every serviced subtree  ->  the one allocated PCI vector, whose
                                  handler's rearm covers the whole serviced set

An allocated entry whose subtree nova-core does not service costs nothing. The
entry stays masked, and a disabled subtree raises no interrupt.

nova-core services one subtree. The GSP event, vector 155, is in leaf 4, which
is in subtree 2. OpenRM's headers place its UVM_SHARED interrupt category in
subtree 2 on every chipset that nova-core supports. The self-test doorbell,
vector 129, is in the same leaf, and the test allocates its own vectors for it.

Rearming PCI interrupt delivery
-------------------------------

A message-signaled interrupt is delivered once per edge, and the PCI side
delivers no further interrupt until the CPU rearms it. The rearm operation
depends on the GPU family and on the interrupt type that Linux granted:

==================  =====  ===========================================
Architecture        Type   Rearm operation
==================  =====  ===========================================
Turing through Ada  MSI    write the configuration-mirror EOI register
Hopper and later    MSI    clear then set the serviced TOP enables
Any                 MSI-X  clear then set the handler's own TOP enable
==================  =====  ===========================================

The end-of-interrupt register is ``NV_XVE_CYA_2`` in the BAR0 mirror of PCI
configuration space, and the value written does not matter. The ``TOP_EN``
cycle produces a new delivery edge. The MSI forms cover every serviced subtree,
because one message serves all of them. The MSI-X form covers one subtree,
because each serviced subtree has its own entry and its own handler.

A handler rearms once per delivered interrupt, on every path, including the
path where it finds its vector not pending. A handler that skips the rearm
receives no further interrupts.

OpenRM makes the same split. It writes the configuration-space EOI for MSI on
pre-Hopper chipsets, and cycles the TOP enables of the subtrees that it
services for Hopper-plus MSI and for MSI-X.

Servicing the tree
==================

Servicing a leaf has a required order: read its pending bits, then clear them.
Clearing a leaf before reading it discards every vector latched in it, and no
register reports the loss. In nova-core, reading a leaf produces the handle that
clears it, so that the wrong order does not compile. The handle clears exactly
the bits that it read, so a vector that latched after the read stays pending.

A handler clears its bit before it services the vector. Clearing afterwards
would discard an interrupt that the source raised while the handler ran.

nova-core services the tree in two ways.

The notification path services one vector. It reads the vector's leaf, clears
only the vector's bit, and rearms. The subtree stays enabled, and a vector
pending beside it in the same leaf keeps its bit set for the code that services
that vector. The GSP event handler takes this path, and so does the self-test
handler.

The startup drain walks the whole tree, because it must clear whatever is
pending across every subtree rather than one known vector. It disables the
serviced subtrees at ``TOP``, reads and clears every implemented leaf, and
leaves the subtrees disabled for its caller to enable once the caller is ready
for deliveries. The drain reads every leaf rather than descending from ``TOP``,
because sources latch vectors during boot while those vectors are disabled, and
``TOP`` does not show them. OpenRM's stall-interrupt path reads every leaf for
the same reason.

The two paths as register operations::

    Startup drain, run once during probe:
        write TOP_EN_CLEAR = serviced        stop new deliveries
        for each implemented leaf i:
            pending = read LEAF(i)
            write LEAF(i) = pending          clear what was read
        (returns with TOP_EN still clear)

    Notification, the subtree stays enabled:
        pending = read LEAF(leaf)            is the handler's bit set?
        write LEAF(leaf) = bit               clear that one bit
        rearm PCI interrupt delivery

The drain clears every pending bit, including bits that nova-core never
services. An uncleared bit holds its subtree in the pending state, and enabling
that subtree again would deliver an interrupt for a vector that no handler
services.

The drain's ``TOP_EN_CLEAR`` is not a rearm, and pre-Hopper MSI rearms through
the configuration mirror, which the drain never writes. An interrupt delivered
before probe had no handler to rearm it, so the tree reset rearms explicitly
after the drain. A TOP-enable rearm leaves the serviced subtrees enabled, so
the reset then disables them again.

nova-core does not serialize access to the tree. The GSP event handler
touches only its own leaf, and the drain runs during probe, before that handler
is registered.

Per-architecture differences
============================

The tree is the same on every supported GPU except for its size, which changes
at Hopper:

===================  ======  ========  ====================
GPUs                 Leaves  Subtrees  Implemented subtrees
===================  ======  ========  ====================
Turing, Ampere, Ada  8       4         ``0x0f``
Hopper, Blackwell    16      8         ``0xff``
===================  ======  ========  ====================

The interrupt HAL provides the leaf count, and the subtree count and the
implemented-subtree set derive from it. A subtree that the chipset does not
implement has no TOP bit, so building a tree that services one fails with
``EINVAL``. Vectors 129 and 155 are in the 8-leaf tree, so every supported
chipset has them.

OpenRM's headers assign every interrupt category of a 16-leaf tree to leaves 0
through 11. The drain reads all 16, because a vector can be latched in any
implemented leaf.

The HAL performs the rearm as well (see "Rearming PCI interrupt delivery"). Two
falcon properties also differ by family, and the falcon HAL carries them:
Turing falcons have no ``INTR_RETRIGGER``, and the RISC-V routing registers
moved at GA102 (see "Retriggering a falcon").

The GSP event
=============

When the GSP has output for the CPU, it writes messages into the GSP-to-CPU
queue in shared memory and raises SWGEN0, one of the software-generated
interrupt causes of the GSP falcon. SWGEN0 is routed to the host, at vector
155, leaf 4 bit 27, in subtree 2.

The queue carries notifications (log records, error records, lifecycle events)
and command replies. A thread waiting for a reply reads the queue itself, so
the interrupt is only the trigger to drain the queue (see "Draining the
GSP-to-CPU queue").

The falcon latches every cause that it raises, SWGEN0 among them, in its
``IRQSTAT`` register. The handler services the host-routed causes and clears
their latches, and then it writes ``INTR_RETRIGGER`` so that the falcon re-emits
any cause that latched in the meantime. "Retriggering a falcon" has the details.

Draining the queue takes the command-queue mutex and walks shared memory, so it
cannot run in hard interrupt context. nova-core registers a threaded handler,
under the name ``nova-core`` in ``/proc/interrupts``. The top half runs in hard
interrupt context and reads and writes only registers, and it wakes the IRQ
thread to drain the queue::

    GSP writes messages into the GSP-to-CPU queue
    GSP raises SWGEN0
    GIN sets bit 27 of LEAF(4), and subtree 2 becomes pending
    PCI interrupt -> Linux IRQ -> top half, in hard interrupt context:
        read LEAF(4), and if bit 27 is clear, rearm and return
        clear bit 27 (the subtree stays enabled)
        read the falcon causes routed to the host, clearing SWGEN0 if set
        for every other host cause: log it, clear its latch, and read the
            host causes back
        if the clear ended all of them: retrigger the falcon
        otherwise: disable vector 155 at its leaf and skip the retrigger
        rearm PCI interrupt delivery
        wake the IRQ thread if SWGEN0 was set
    IRQ thread, which may sleep:
        take the command-queue mutex and drain the GSP-to-CPU queue

A halt and a posted message can be pending together, so the top half services
every cause that the status reports.

A drain fails when a message's framing or checksum is bad (see "Draining the
GSP-to-CPU queue"). The message stays at the queue head, so every later drain
would fail the same way, and the IRQ thread disables vector 155 and logs the
failure, which leaves the queue unserviced until the device is reset.

The handler, the self-test, and the rest of the driver read BAR0 through one
shared mapping. nova-core unregisters an interrupt handler when the device
unbinds, so a handler runs only while the mapping exists.

Retriggering a falcon
---------------------

A falcon signals the tree when its set of host-routed causes goes from empty to
non-empty. A cause left latched keeps the set non-empty, so no later cause
signals the tree, and the vector is lost. For a cause that stays latched, the
handler can clear the tree leaf first or the falcon latch first, and the loss
is the same.

``IRQSTAT`` latches every cause in the falcon, including the causes routed to
the falcon's own RISC-V core and owned by the firmware running on it. A host
handler owns only the causes that ``PRISCV_RISCV_IRQMASK`` and
``PRISCV_RISCV_IRQDEST`` both select, so it intersects ``IRQSTAT`` with both
before it reads or clears a cause. OpenRM computes the same intersection in
``kflcnRiscvReadIntrStatus``. GA100 keeps the Turing offsets of the two routing
registers and GA102 moves them, so the offsets change at GA102 rather than at
the Ampere boundary. The handler masks no cause: ``PRISCV_RISCV_IRQMASK`` is
read-only to the host, and ``FALCON_IRQMASK`` has no effect on host routing on
a RISC-V falcon.

``INTR_RETRIGGER`` makes the falcon re-emit its host-routed causes into the
tree, which supplies the transition that clearing the leaf lost. The handler
writes ``INTR_RETRIGGER`` only on a path where it ended every cause that it
read, because a re-emitted cause that stays set arrives again at once and
on every pass after that.

``IRQSCLR`` ends a latch and does not end the source behind it, so a cause
driven from outside the falcon stays set after the write. On Blackwell the
fault-containment and ECC causes are driven that way: they appear in
``IRQSTAT`` but come from ``PRISCV_RISCV_FAULT_CONTAINMENT_SRCSTAT`` and
``PGSP_ECC_INTR_STATUS``, and only a device reset ends them. So the handler
clears the latch of every host cause other than SWGEN0, reads the host causes
back, and retriggers only when the read-back is empty. When a cause is still
set, the handler disables vector 155 instead and reports that the device needs
a reset. Disabling loses no notification: the cause that is still set holds the
host-routed set non-empty, so the falcon would signal nothing further either
way. OpenRM makes the same choice, and ``kgspService_TU102`` skips
``kflcnIntrRetrigger`` once it has recorded a fatal error.

The handler cannot distinguish a fault cause that arrives after the clear from
one that the clear failed to end, so it disables the vector in that case too.
Both mean that the GSP has faulted.

Turing falcons have no ``INTR_RETRIGGER``, so a Turing handler cannot re-create
a transition that it has lost. It must leave no host cause latched: it reads the
host-routed status once and takes every cause that the status reports, rather
than stopping at the first one that it recognizes. One window stays open. A
cause that arrives after the handler has read the status is not in the value
that the handler clears, so it stays latched after the leaf has been cleared,
and no later cause from that falcon signals the tree. OpenRM has the same window
on Turing, where ``kflcnIntrRetrigger`` does nothing.

Enabling the GSP event
----------------------

SWGEN0 is a latch, and the GSP drives no new edge into the tree while it stays
set. nova-core's GSP boot code consumes the GSP's notifications by polling the
queue, which leaves the latch set and leaves pending bits in the tree. The
handoff from polling to interrupts has a required order::

    disable every implemented vector    drop enables left by boot, or by a
                                        driver that ran before this one
    drain the tree                      clear stale pending bits
    rearm PCI interrupt delivery        required under pre-Hopper MSI, which
                                        no later step rearms
    disable subtree 2 at TOP            a TOP-enable rearm enabled it again
    clear the SWGEN0 latch              so the next message makes an edge
    register the threaded handler       no delivery can reach it yet
    enable vector 155 at LEAF(4)        the subtree is still disabled
    enable subtree 2 at TOP             deliveries become possible here
    drain the GSP-to-CPU queue          messages posted before the clear

The first four steps are the tree reset. nova-core runs them, and clears the
latch, before it registers the handler. Registering unmasks the PCI interrupt,
and GIN would then deliver a vector that boot left enabled to a handler that
services one vector and has no way to service any other. OpenRM clears every
leaf enable at the same point for the same reason.

nova-core clears the latch after the drain. If nova-core cleared the latch
first, a message posted before the drain could set it again, along with bit 27
of LEAF(4). The drain would then clear the leaf bit while the latch stays set,
and no later message would signal the tree. Clearing after the drain can
instead leave the leaf bit pending with the latch already clear. Enabling the
subtree then delivers one interrupt whose ``IRQSTAT`` reads zero. The top half
clears the leaf bit, rearms, and does not wake the IRQ thread, and the queue
drain that follows reads the message.

Clearing the latch makes the first interrupt possible. A message that the GSP
posted before that clear produces no interrupt, so the sequence ends by
draining the queue.

The subtree is enabled at ``TOP`` only once the handler is registered. A
TOP-enable rearm sets the enables that it cycles, so the reset disables the
serviced subtrees again after its rearm, and the tree reaches the registration
with subtree 2 disabled under every rearm method. On teardown nova-core disables
the vector at its leaf, so that no vector in the subtree can be delivered, then
calls ``free_irq()``, and disables the subtree last. Disabling the subtree
earlier would let a handler still in flight enable it again through the
``TOP_EN`` cycle of its rearm, which would leave the subtree enabled with no
handler registered. The driver's ``Gpu`` object, which owns the tree, holds the
subtree enable, and a handler's registration holds only the enable of its own
vector, so that tearing down one handler does not disable a subtree that another
handler shares. nova-core tears down the registration before it frees the queue
that the handler drains and the falcon that the handler reads, and before it
unloads the GSP.

Draining the GSP-to-CPU queue
-----------------------------

The queue carries command replies and unsolicited events, and a message's
function code says which it is.

* A function code that matches the awaited reply: the message is decoded and
  returned to the caller that sent the command.
* Anything else is an event. An OS error record and a robust-channel record
  are logged at error level, and an unrecognized function code at warning
  level. The other known events (GSP logs, libos prints, assertion records,
  lifecycle notices) need no action and get no line of their own, because the
  receive trace at debug level already records every message's arrival with
  its sequence number, function code, and length.

The sequence number takes no part in the match, because the GSP does not echo
the command's sequence number on every reply. On r570 the reply to
``UnloadingGuestDriver`` carries sequence 0.

The read pointer advances past every message that passes framing and checksum
validation, whether it matched or was an event. A matched message that is too
short to decode is the exception, and it stays at the queue head.

A message's length is inside the region that the checksum covers, so once the
framing or the checksum fails there is no trustworthy length with which to skip
the message. Such a message also stays at the queue head, and every later
receive fails on it with ``EIO`` until the device is reset.

The polling path and the IRQ thread both read the queue under the command-queue
mutex. Replies and events share one queue and one read pointer, so one lock is
held across the whole drain. A thread waiting for a reply logs each event that
arrives before the reply and keeps waiting. One deadline of 5 seconds applies to
the whole wait, rather than a fresh timeout after each message, and the thread
holds the mutex for the whole wait, so that no other caller consumes the message
that it waits for.

With one lock, a drain waits for an in-flight command's receive to finish or
time out. For log and error records that delay does not matter.