[PATCH v4 31/63] Documentation: PCI: convert pci-error-recovery.txt to reST
Mauro Carvalho Chehab
mchehab+samsung at kernel.org
Thu Apr 25 01:45:05 AEST 2019
Em Wed, 24 Apr 2019 00:29:00 +0800
Changbin Du <changbin.du at gmail.com> escreveu:
> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
>
> Signed-off-by: Changbin Du <changbin.du at gmail.com>
> Acked-by: Bjorn Helgaas <bhelgaas at google.com>
> ---
> Documentation/PCI/index.rst | 1 +
> ...or-recovery.txt => pci-error-recovery.rst} | 178 +++++++++---------
> MAINTAINERS | 2 +-
> 3 files changed, 94 insertions(+), 87 deletions(-)
> rename Documentation/PCI/{pci-error-recovery.txt => pci-error-recovery.rst} (80%)
>
> diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
> index c877a369481d..5ee4dba07116 100644
> --- a/Documentation/PCI/index.rst
> +++ b/Documentation/PCI/index.rst
> @@ -13,3 +13,4 @@ Linux PCI Bus Subsystem
> pci-iov-howto
> MSI-HOWTO
> acpi-info
> + pci-error-recovery
> diff --git a/Documentation/PCI/pci-error-recovery.txt b/Documentation/PCI/pci-error-recovery.rst
> similarity index 80%
> rename from Documentation/PCI/pci-error-recovery.txt
> rename to Documentation/PCI/pci-error-recovery.rst
> index 0b6bb3ef449e..533ec4035bf5 100644
> --- a/Documentation/PCI/pci-error-recovery.txt
> +++ b/Documentation/PCI/pci-error-recovery.rst
> @@ -1,12 +1,13 @@
> +.. SPDX-License-Identifier: GPL-2.0
>
> - PCI Error Recovery
> - ------------------
> - February 2, 2006
> +==================
> +PCI Error Recovery
> +==================
>
> - Current document maintainer:
> - Linas Vepstas <linasvepstas at gmail.com>
> - updated by Richard Lary <rlary at us.ibm.com>
> - and Mike Mason <mmlnx at us.ibm.com> on 27-Jul-2009
Just wondering: wouldn't be good to preserve the date here?
> +
> +:Authors: - Linas Vepstas <linasvepstas at gmail.com>
> + - Richard Lary <rlary at us.ibm.com>
> + - Mike Mason <mmlnx at us.ibm.com>
>
>
> Many PCI bus controllers are able to detect a variety of hardware
> @@ -63,7 +64,8 @@ mechanisms for dealing with SCSI bus errors and SCSI bus resets.
>
>
> Detailed Design
> ----------------
> +===============
> +
> Design and implementation details below, based on a chain of
> public email discussions with Ben Herrenschmidt, circa 5 April 2005.
>
> @@ -73,30 +75,33 @@ pci_driver. A driver that fails to provide the structure is "non-aware",
> and the actual recovery steps taken are platform dependent. The
> arch/powerpc implementation will simulate a PCI hotplug remove/add.
>
> -This structure has the form:
> -struct pci_error_handlers
> -{
> - int (*error_detected)(struct pci_dev *dev, enum pci_channel_state);
> - int (*mmio_enabled)(struct pci_dev *dev);
> - int (*slot_reset)(struct pci_dev *dev);
> - void (*resume)(struct pci_dev *dev);
> -};
> -
> -The possible channel states are:
> -enum pci_channel_state {
> - pci_channel_io_normal, /* I/O channel is in normal state */
> - pci_channel_io_frozen, /* I/O to channel is blocked */
> - pci_channel_io_perm_failure, /* PCI card is dead */
> -};
> -
> -Possible return values are:
> -enum pci_ers_result {
> - PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */
> - PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */
> - PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */
> - PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */
> - PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */
> -};
> +This structure has the form::
> +
> + struct pci_error_handlers
> + {
> + int (*error_detected)(struct pci_dev *dev, enum pci_channel_state);
> + int (*mmio_enabled)(struct pci_dev *dev);
> + int (*slot_reset)(struct pci_dev *dev);
> + void (*resume)(struct pci_dev *dev);
> + };
> +
> +The possible channel states are::
> +
> + enum pci_channel_state {
> + pci_channel_io_normal, /* I/O channel is in normal state */
> + pci_channel_io_frozen, /* I/O to channel is blocked */
> + pci_channel_io_perm_failure, /* PCI card is dead */
> + };
> +
> +Possible return values are::
> +
> + enum pci_ers_result {
> + PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */
> + PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */
> + PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */
> + PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */
> + PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */
> + };
>
> A driver does not have to implement all of these callbacks; however,
> if it implements any, it must implement error_detected(). If a callback
> @@ -134,16 +139,17 @@ 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_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
> - a chance to extract some diagnostic information (see
> - mmio_enable, below).
> - - PCI_ERS_RESULT_NEED_RESET:
> - Driver returns this if it can't recover without a
> - slot reset.
> - - PCI_ERS_RESULT_DISCONNECT:
> - Driver returns this if it doesn't want to recover at all.
> +
> + - 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
> + a chance to extract some diagnostic information (see
> + mmio_enable, below).
> + - PCI_ERS_RESULT_NEED_RESET:
> + Driver returns this if it can't recover without a
> + slot reset.
> + - PCI_ERS_RESULT_DISCONNECT:
> + Driver returns this if it doesn't want to recover at all.
This would look better on both text and html if you format it as:
- 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
a chance to extract some diagnostic information (see
mmio_enable, below).
- PCI_ERS_RESULT_NEED_RESET:
Driver returns this if it can't recover without a
slot reset.
- PCI_ERS_RESULT_DISCONNECT:
Driver returns this if it doesn't want to recover at all.
>
> The next step taken will depend on the result codes returned by the
> drivers.
> @@ -177,7 +183,7 @@ is STEP 6 (Permanent Failure).
> >>> get the device working again.
>
> STEP 2: MMIO Enabled
> --------------------
> +--------------------
> The platform re-enables MMIO to the device (but typically not the
> DMA), and then calls the mmio_enabled() callback on all affected
> device drivers.
> @@ -203,23 +209,23 @@ instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset)
> >>> into one of the next states, that is, link reset or slot reset.
It sounds you forgot to reformat the note with ">>>", e. g.
something like:
.. note::
The current powerpc implementation assumes that a device driver will
*not* schedule or semaphore in this routine; the current powerpc
implementation uses one kernel thread to notify all devices;
thus, if one device sleeps/schedules, all devices are affected.
Doing better requires complex multi-threaded logic in the error
recovery implementation (e.g. waiting for all notification threads
to "join" before proceeding with recovery.) This seems excessively
complex and not worth implementing.
The current powerpc implementation doesn't much care if the device
attempts I/O at this point, or not. I/O's will fail, returning
a value of 0xff on read, and writes will be dropped. If more than
EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH
assumes that the device driver has gone into an infinite loop
and prints an error to syslog. A reboot is then required to
get the device working again.
>
> The driver should return one of the following result codes:
> - - PCI_ERS_RESULT_RECOVERED
> - Driver returns this if it thinks the device is fully
> - functional and thinks it is ready to start
> - normal driver operations again. There is no
> - guarantee that the driver will actually be
> - allowed to proceed, as another driver on the
> - same segment might have failed and thus triggered a
> - slot reset on platforms that support it.
> -
> - - PCI_ERS_RESULT_NEED_RESET
> - Driver returns this if it thinks the device is not
> - recoverable in its current state and it needs a slot
> - reset to proceed.
> -
> - - PCI_ERS_RESULT_DISCONNECT
> - Same as above. Total failure, no recovery even after
> - reset driver dead. (To be defined more precisely)
> + - PCI_ERS_RESULT_RECOVERED
> + Driver returns this if it thinks the device is fully
> + functional and thinks it is ready to start
> + normal driver operations again. There is no
> + guarantee that the driver will actually be
> + allowed to proceed, as another driver on the
> + same segment might have failed and thus triggered a
> + slot reset on platforms that support it.
> +
> + - PCI_ERS_RESULT_NEED_RESET
> + Driver returns this if it thinks the device is not
> + recoverable in its current state and it needs a slot
> + reset to proceed.
> +
> + - PCI_ERS_RESULT_DISCONNECT
> + Same as above. Total failure, no recovery even after
> + reset driver dead. (To be defined more precisely)
Same as above, this would look a way better if you format it as:
- PCI_ERS_RESULT_RECOVERED
Driver returns this if it thinks the device is fully
functional and thinks it is ready to start
normal driver operations again. There is no
guarantee that the driver will actually be
allowed to proceed, as another driver on the
same segment might have failed and thus triggered a
slot reset on platforms that support it.
- PCI_ERS_RESULT_NEED_RESET
Driver returns this if it thinks the device is not
recoverable in its current state and it needs a slot
reset to proceed.
- PCI_ERS_RESULT_DISCONNECT
Same as above. Total failure, no recovery even after
reset driver dead. (To be defined more precisely)
> The next step taken depends on the results returned by the drivers.
> If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform
> @@ -293,24 +299,24 @@ device will be considered "dead" in this case.
> 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
> -driver performs device init only from PCI function 0:
> +driver performs device init only from PCI function 0::
>
> -+ if (PCI_FUNC(pdev->devfn) == 0)
> -+ sym_reset_scsi_bus(np, 0);
> + + if (PCI_FUNC(pdev->devfn) == 0)
> + + sym_reset_scsi_bus(np, 0);
>
> - Result codes:
> - - PCI_ERS_RESULT_DISCONNECT
> - Same as above.
> +Result codes:
> + - PCI_ERS_RESULT_DISCONNECT
> + Same as above.
>
> Drivers for PCI Express cards that require a fundamental reset must
> set the needs_freset bit in the pci_dev structure in their probe function.
> For example, the QLogic qla2xxx driver sets the needs_freset bit for certain
> -PCI card types:
> +PCI card types::
>
> -+ /* Set EEH reset type to fundamental if required by hba */
> -+ if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha))
> -+ pdev->needs_freset = 1;
> -+
> + + /* Set EEH reset type to fundamental if required by hba */
> + + if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha))
> + + pdev->needs_freset = 1;
> + +
>
> Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent
> Failure).
Again, you forgot to convert one note there, just after the above
lines:
.. note::
The current powerpc implementation does not try a power-cycle
reset if the driver returned PCI_ERS_RESULT_DISCONNECT.
However, it probably should.
> @@ -370,23 +376,23 @@ The current policy is to turn this into a platform policy.
> That is, the recovery API only requires that:
>
> - There is no guarantee that interrupt delivery can proceed from any
> -device on the segment starting from the error detection and until the
> -slot_reset callback is called, at which point interrupts are expected
> -to be fully operational.
> + device on the segment starting from the error detection and until the
> + slot_reset callback is called, at which point interrupts are expected
> + to be fully operational.
>
> - There is no guarantee that interrupt delivery is stopped, that is,
> -a driver that gets an interrupt after detecting an error, or that detects
> -an error within the interrupt handler such that it prevents proper
> -ack'ing of the interrupt (and thus removal of the source) should just
> -return IRQ_NOTHANDLED. It's up to the platform to deal with that
> -condition, typically by masking the IRQ source during the duration of
> -the error handling. It is expected that the platform "knows" which
> -interrupts are routed to error-management capable slots and can deal
> -with temporarily disabling that IRQ number during error processing (this
> -isn't terribly complex). That means some IRQ latency for other devices
> -sharing the interrupt, but there is simply no other way. High end
> -platforms aren't supposed to share interrupts between many devices
> -anyway :)
> + a driver that gets an interrupt after detecting an error, or that detects
> + an error within the interrupt handler such that it prevents proper
> + ack'ing of the interrupt (and thus removal of the source) should just
> + return IRQ_NOTHANDLED. It's up to the platform to deal with that
> + condition, typically by masking the IRQ source during the duration of
> + the error handling. It is expected that the platform "knows" which
> + interrupts are routed to error-management capable slots and can deal
> + with temporarily disabling that IRQ number during error processing (this
> + isn't terribly complex). That means some IRQ latency for other devices
> + sharing the interrupt, but there is simply no other way. High end
> + platforms aren't supposed to share interrupts between many devices
> + anyway :)
>
> >>> Implementation details for the powerpc platform are discussed in
> >>> the file Documentation/powerpc/eeh-pci-error-recovery.txt
Another note to be converted:
.. note::
Implementation details for the powerpc platform are discussed in
the file Documentation/powerpc/eeh-pci-error-recovery.txt
As of this writing, there is a growing list of device drivers with
patches implementing error recovery. Not all of these patches are in
mainline yet. These may be used as "examples"::
drivers/scsi/ipr
drivers/scsi/sym53c8xx_2
...
drivers/net/qlge
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 87f930bf32ad..403178958b05 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -11965,7 +11965,7 @@ M: Sam Bobroff <sbobroff at linux.ibm.com>
> M: Oliver O'Halloran <oohall at gmail.com>
> L: linuxppc-dev at lists.ozlabs.org
> S: Supported
> -F: Documentation/PCI/pci-error-recovery.txt
> +F: Documentation/PCI/pci-error-recovery.rst
> F: drivers/pci/pcie/aer.c
> F: drivers/pci/pcie/dpc.c
> F: drivers/pci/pcie/err.c
Thanks,
Mauro
More information about the Linuxppc-dev
mailing list