Re: [PATCH] Documentation: PCI: Amend error recovery doc with pci_save_state() rules
From: "Rafael J. Wysocki" <rafael@kernel.org>
Date: 2025-11-24 18:23:43
Also in:
linux-doc, linux-pci, linux-pm
On Fri, Nov 21, 2025 at 6:31 PM Lukas Wunner [off-list ref] wrote:
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 <helgaas@kernel.org> Closes: https://lore.kernel.org/r/20251113161556.GA2284238@bhelgaas/ (local) Signed-off-by: Lukas Wunner <lukas@wunner.de>
It looks good to me, so Acked-by: Rafael J. Wysocki (Intel) <rafael@kernel.org>
quoted hunk ↗ jump to hunk
--- 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 5df481a..43bc4e3 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 --2.51.0