[PATCH v2 2/4] Documentation: PCI: Sync error recovery doc with code

[Niklas Schnelle]

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 <lukas at wunner.de>
> Reviewed-by: Brian Norris <briannorris at chromium.org>
> ---
>  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 <schnelle at linux.ibm.com>