linux/Documentation/PCI
Lukas Wunner 5e09895b40 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 <helgaas@kernel.org>
Closes: https://lore.kernel.org/r/20251113161556.GA2284238@bhelgaas/
Signed-off-by: Lukas Wunner <lukas@wunner.de>
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Acked-by: Rafael J. Wysocki (Intel) <rafael@kernel.org>
Link: https://patch.msgid.link/077596ba70202be0e43fdad3bb9b93d356cbe4ec.1763746079.git.lukas@wunner.de
2025-11-24 16:59:10 -06:00
..
controller PCI: rcar-gen4: Document how to obtain platform firmware 2025-05-21 12:02:59 +00:00
endpoint pci-v6.18-changes 2025-10-06 10:41:03 -07:00
acpi-info.rst docs: PCI: Replace non-breaking spaces to avoid PDF issues 2021-06-17 13:22:33 -06:00
boot-interrupts.rst docs: PCI: Fix typos 2023-12-28 17:37:36 -06:00
index.rst PCI: rcar-gen4: Document how to obtain platform firmware 2025-05-21 12:02:59 +00:00
msi-howto.rst Documentation: PCI: Use PCI_IRQ_INTX instead of PCI_IRQ_LEGACY 2024-04-25 12:53:29 -05:00
pci-error-recovery.rst Documentation: PCI: Amend error recovery doc with pci_save_state() rules 2025-11-24 16:59:10 -06:00
pci-iov-howto.rst PCI/doc: Convert examples to generic power management 2022-07-11 18:17:29 -05:00
pci.rst Documentation: PCI: fix typo in pci.rst 2024-09-10 15:30:42 -06:00
pcieaer-howto.rst Documentation: PCI: Fix typos 2025-09-18 17:23:22 -05:00
pciebus-howto.rst PCI: Protect Link Control 2 Register with RMW locking 2024-10-23 16:50:02 -05:00
sysfs-pci.rst PCI: Remove pci_mmap_page_range() wrapper 2022-07-29 12:08:44 -05:00
tph.rst PCI/TPH: Add TPH documentation 2024-10-21 16:19:32 -05:00