Skip to content

Backport srv03-style SCSIPORT shutdown plumbing into NT 3.5 SCSIPORT #1

Description

@HarryR

Context

NT 3.5's SCSIPORT (src/NT/PRIVATE/NTOS/DD/SCSIPORT/) has zero shutdown
notification machinery for miniports — no IoRegisterShutdownNotification,
no IRP_MJ_SHUTDOWN dispatch, no HwAdapterControl(ScsiStopAdapter)
plumbing. Miniports that implement HwAdapterControl (e.g. nvme2k) wire
the entry point but it is never invoked on this kernel.

Symptom we already mitigated

nvme2k reported ERROR - Got NULL SRB for CID=N deterministically at
kernel halt. Root cause is the latent race: NVMe controller continues
to post CQ entries while the FS layer has given up on those tags, the
miniport's FallbackTimer fires, ScsiPortGetSrb returns NULL.

Quick fix in 934188d (this tree) and techomancer/nvme2k#28 (upstream):
demote the "NULL SRB" log to an _EXTRA trace — the driver already
handles NULL gracefully (consume CQ, advance head). Resolves the visible
symptom on a kernel without shutdown notification.

What the proper backport would add

Port the shutdown core from W2003-vintage SCSIPORT
(drivers/storage/scsiport/{enable.c,control.c}):

  • SpShutdownAdapter — sets PD_SHUTDOWN_IN_PROGRESS, cancels the
    per-adapter miniport timer (KeCancelTimer), runs
    SpShutdownAdapterSynchronized under ISR sync.
  • SpShutdownAdapterSynchronized — calls
    HwAdapterControl(ScsiStopAdapter, NULL), then masks IRQs.
    (Ordering matches NVMe 1.4c §7.6.2: controller stays interrupt-live
    through the shutdown notification.)
  • SpCallAdapterControl + SpIsAdapterControlTypeSupported +
    SpGetSupportedAdapterControlFunctions — dispatch helpers.

W2003 triggers this from PnP/Power callbacks, which NT 3.5 doesn't have.
We'd wire from the NT-3.5-appropriate path instead:

  • IoRegisterShutdownNotification(adapterDevObj) per adapter at init.
  • MajorFunction[IRP_MJ_SHUTDOWN] dispatch entry → calls
    SpShutdownAdapter.

Cost estimate

~120 LOC ported + ~20 LOC of init/dispatch glue. Mostly in
SCSIPORT/PORT.C and INTERNAL.C. Half a day.

What we'd gain

  • Architectural correctness — devices get to quiesce gracefully before
    HAL hands back to firmware.
  • NvmeShutdownController (body completed in 934188d but currently
    dormant) becomes live: NVMe 1.4c §7.6.2 sequence actually runs.
  • The ShuttingDown flag plumbed through 934188d becomes load-bearing
    (currently set/unset but no reader).
  • Future hardware-targeting miniports get the hook for free.

Why this is deferred

For our current target (QEMU TCG NVMe), the device-side cache is
in-memory anyway — there's no data-persistence implication, no
behavioural change. The demote already fixed the visible symptom.

Worth pursuing if/when:

  • MicroNT targets real hardware with on-board write caches.
  • A new miniport with non-trivial shutdown semantics is added (real
    AHCI driver, anything with persistent device-side state).
  • A standalone "modernise NT 3.5 SCSIPORT to ~W2K-equivalent" arc is
    scoped.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions