From 5e09895b4063e9f57c6fc416cf30cd0c6ca7ec74 Mon Sep 17 00:00:00 2001 From: Lukas Wunner Date: Fri, 21 Nov 2025 18:31:17 +0100 Subject: [PATCH] Documentation: PCI: Amend error recovery doc with pci_save_state() rules After recovering from a PCI error through reset, affected devices are in D0_uninitialized state and need to be brought into D0_active state by re-initializing their Config Space registers (PCIe r7.0 sec 5.3.1.1). To facilitate that, the PCI core provides pci_restore_state() and pci_save_state() helpers. Document rules governing their usage. As Bjorn notes, so far no file in "Documentation/ includes anything about the idea of a driver using pci_save_state() to capture the state it wants to restore after an error", even though it is a common pattern in drivers. So that's obviously a gap that should be closed. Reported-by: Bjorn Helgaas Closes: https://lore.kernel.org/r/20251113161556.GA2284238@bhelgaas/ Signed-off-by: Lukas Wunner Signed-off-by: Bjorn Helgaas Acked-by: Rafael J. Wysocki (Intel) Link: https://patch.msgid.link/077596ba70202be0e43fdad3bb9b93d356cbe4ec.1763746079.git.lukas@wunner.de --- Documentation/PCI/pci-error-recovery.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst index 5df481ac6193..43bc4e3665b4 100644 --- a/Documentation/PCI/pci-error-recovery.rst +++ b/Documentation/PCI/pci-error-recovery.rst @@ -326,6 +326,21 @@ be recovered, there is nothing more that can be done; the platform will typically report a "permanent failure" in such a case. The device will be considered "dead" in this case. +Drivers typically need to call pci_restore_state() after reset to +re-initialize the device's config space registers and thereby +bring it from D0\ :sub:`uninitialized` into D0\ :sub:`active` state +(PCIe r7.0 sec 5.3.1.1). The PCI core invokes pci_save_state() +on enumeration after initializing config space to ensure that a +saved state is available for subsequent error recovery. +Drivers which modify config space on probe may need to invoke +pci_save_state() afterwards to record those changes for later +error recovery. When going into system suspend, pci_save_state() +is called for every PCI device and that state will be restored +not only on resume, but also on any subsequent error recovery. +In the unlikely event that the saved state recorded on suspend +is unsuitable for error recovery, drivers should call +pci_save_state() on resume. + Drivers for multi-function cards will need to coordinate among themselves as to which driver instance will perform any "one-shot" or global device initialization. For example, the Symbios sym53cxx2