On Mon, 2025-09-15 at 15:50 +0200, Lukas Wunner wrote: > Amend the documentation on PCI error recovery to fix minor inaccuracies > vis-à-vis the actual code: > > * The documentation claims that a missing ->resume() or ->mmio_enabled() > callback always leads to recovery through reset. But none of the > implementations do this (pcie_do_recovery(), eeh_handle_normal_event(), > zpci_event_do_error_state_clear()). > > Drop the claim to align the documentation with the code. > > * The documentation does not list PCI_ERS_RESULT_RECOVERED as a valid > return value from ->error_detected(). But none of the implementations > forbid this and some drivers are returning it, e.g.: > drivers/bus/mhi/host/pci_generic.c > drivers/infiniband/hw/hfi1/pcie.c > > Further down in the documentation it is implied that the return value is > in fact allowed: > "The platform will call the resume() callback on all affected device > drivers if all drivers on the segment have returned > PCI_ERS_RESULT_RECOVERED from one of the 3 previous callbacks." > > The "3 previous callbacks" being ->error_detected(), ->mmio_enabled() > and ->slot_reset(). > > Add it to the valid return values for consistency. > > Signed-off-by: Lukas Wunner <[email protected]> > Reviewed-by: Brian Norris <[email protected]> > --- > Documentation/PCI/pci-error-recovery.rst | 7 +++++-- > 1 file changed, 5 insertions(+), 2 deletions(-) > > diff --git a/Documentation/PCI/pci-error-recovery.rst > b/Documentation/PCI/pci-error-recovery.rst > index 42e1e78353f3..d5c661baa87f 100644 > --- a/Documentation/PCI/pci-error-recovery.rst > +++ b/Documentation/PCI/pci-error-recovery.rst > @@ -108,8 +108,8 @@ A driver does not have to implement all of these > callbacks; however, > if it implements any, it must implement error_detected(). If a callback > is not implemented, the corresponding feature is considered unsupported. > For example, if mmio_enabled() and resume() aren't there, then it > -is assumed that the driver is not doing any direct recovery and requires > -a slot reset. Typically a driver will want to know about > +is assumed that the driver does not need these callbacks > +for recovery. Typically a driver will want to know about > a slot_reset(). > > The actual steps taken by a platform to recover from a PCI error > @@ -141,6 +141,9 @@ shouldn't do any new IOs. Called in task context. This is > sort of a > All drivers participating in this system must implement this call. > The driver must return one of the following result codes: > > + - PCI_ERS_RESULT_RECOVERED > + Driver returns this if it thinks the device is usable despite > + the error and does not need further intervention. > - PCI_ERS_RESULT_CAN_RECOVER > Driver returns this if it thinks it might be able to recover > the HW by just banging IOs or if it wants to be given
Thanks and good catch on these inaccuracies. Reviewed-by: Niklas Schnelle <[email protected]>
