On Fri, Nov 21, 2025 at 6:31 PM Lukas Wunner <[email protected]> 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 <[email protected]> > Closes: https://lore.kernel.org/r/20251113161556.GA2284238@bhelgaas/ > Signed-off-by: Lukas Wunner <[email protected]>
It looks good to me, so Acked-by: Rafael J. Wysocki (Intel) <[email protected]> > --- > 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 >
