Documentation/PCI/pcieaer-howto.txt

   1    The PCI Express Advanced Error Reporting Driver Guide HOWTO
   2                 T. Long Nguyen  <tom.l.nguyen@intel.com>
   3                 Yanmin Zhang    <yanmin.zhang@intel.com>
   4                                 07/29/2006
   5
   6
   7 1. Overview
   8
   9 1.1 About this guide
  10
  11 This guide describes the basics of the PCI Express Advanced Error
  12 Reporting (AER) driver and provides information on how to use it, as
  13 well as how to enable the drivers of endpoint devices to conform with
  14 PCI Express AER driver.
  15
  16 1.2 Copyright (C) Intel Corporation 2006.
  17
  18 1.3 What is the PCI Express AER Driver?
  19
  20 PCI Express error signaling can occur on the PCI Express link itself
  21 or on behalf of transactions initiated on the link. PCI Express
  22 defines two error reporting paradigms: the baseline capability and
  23 the Advanced Error Reporting capability. The baseline capability is
  24 required of all PCI Express components providing a minimum defined
  25 set of error reporting requirements. Advanced Error Reporting
  26 capability is implemented with a PCI Express advanced error reporting
  27 extended capability structure providing more robust error reporting.
  28
  29 The PCI Express AER driver provides the infrastructure to support PCI
  30 Express Advanced Error Reporting capability. The PCI Express AER
  31 driver provides three basic functions:
  32
  33 -       Gathers the comprehensive error information if errors occurred.
  34 -       Reports error to the users.
  35 -       Performs error recovery actions.
  36
  37 AER driver only attaches root ports which support PCI-Express AER
  38 capability.
  39
  40
  41 2. User Guide
  42
  43 2.1 Include the PCI Express AER Root Driver into the Linux Kernel
  44
  45 The PCI Express AER Root driver is a Root Port service driver attached
  46 to the PCI Express Port Bus driver. If a user wants to use it, the driver
  47 has to be compiled. Option CONFIG_PCIEAER supports this capability. It
  48 depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and
  49 CONFIG_PCIEAER = y.
  50
  51 2.2 Load PCI Express AER Root Driver
  52 There is a case where a system has AER support in BIOS. Enabling the AER
  53 Root driver and having AER support in BIOS may result unpredictable
  54 behavior. To avoid this conflict, a successful load of the AER Root driver
  55 requires ACPI _OSC support in the BIOS to allow the AER Root driver to
  56 request for native control of AER. See the PCI FW 3.0 Specification for
  57 details regarding OSC usage. Currently, lots of firmwares don't provide
  58 _OSC support while they use PCI Express. To support such firmwares,
  59 forceload, a parameter of type bool, could enable AER to continue to
  60 be initiated although firmwares have no _OSC support. To enable the
  61 walkaround, pls. add aerdriver.forceload=y to kernel boot parameter line
  62 when booting kernel. Note that forceload=n by default.
  63
  64 2.3 AER error output
  65 When a PCI-E AER error is captured, an error message will be outputted to
  66 console. If it's a correctable error, it is outputted as a warning.
  67 Otherwise, it is printed as an error. So users could choose different
  68 log level to filter out correctable error messages.
  69
  70 Below shows an example:
  71 0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID)
  72 0000:50:00.0:   device [8086:0329] error status/mask=00100000/00000000
  73 0000:50:00.0:    [20] Unsupported Request    (First)
  74 0000:50:00.0:   TLP Header: 04000001 00200a03 05010000 00050100
  75
  76 In the example, 'Requester ID' means the ID of the device who sends
  77 the error message to root port. Pls. refer to pci express specs for
  78 other fields.
  79
  80
  81 3. Developer Guide
  82
  83 To enable AER aware support requires a software driver to configure
  84 the AER capability structure within its device and to provide callbacks.
  85
  86 To support AER better, developers need understand how AER does work
  87 firstly.
  88
  89 PCI Express errors are classified into two types: correctable errors
  90 and uncorrectable errors. This classification is based on the impacts
  91 of those errors, which may result in degraded performance or function
  92 failure.
  93
  94 Correctable errors pose no impacts on the functionality of the
  95 interface. The PCI Express protocol can recover without any software
  96 intervention or any loss of data. These errors are detected and
  97 corrected by hardware. Unlike correctable errors, uncorrectable
  98 errors impact functionality of the interface. Uncorrectable errors
  99 can cause a particular transaction or a particular PCI Express link
 100 to be unreliable. Depending on those error conditions, uncorrectable
 101 errors are further classified into non-fatal errors and fatal errors.
 102 Non-fatal errors cause the particular transaction to be unreliable,
 103 but the PCI Express link itself is fully functional. Fatal errors, on
 104 the other hand, cause the link to be unreliable.
 105
 106 When AER is enabled, a PCI Express device will automatically send an
 107 error message to the PCIe root port above it when the device captures
 108 an error. The Root Port, upon receiving an error reporting message,
 109 internally processes and logs the error message in its PCI Express
 110 capability structure. Error information being logged includes storing
 111 the error reporting agent's requestor ID into the Error Source
 112 Identification Registers and setting the error bits of the Root Error
 113 Status Register accordingly. If AER error reporting is enabled in Root
 114 Error Command Register, the Root Port generates an interrupt if an
 115 error is detected.
 116
 117 Note that the errors as described above are related to the PCI Express
 118 hierarchy and links. These errors do not include any device specific
 119 errors because device specific errors will still get sent directly to
 120 the device driver.
 121
 122 3.1 Configure the AER capability structure
 123
 124 AER aware drivers of PCI Express component need change the device
 125 control registers to enable AER. They also could change AER registers,
 126 including mask and severity registers. Helper function
 127 pci_enable_pcie_error_reporting could be used to enable AER. See
 128 section 3.3.
 129
 130 3.2. Provide callbacks
 131
 132 3.2.1 callback reset_link to reset pci express link
 133
 134 This callback is used to reset the pci express physical link when a
 135 fatal error happens. The root port aer service driver provides a
 136 default reset_link function, but different upstream ports might
 137 have different specifications to reset pci express link, so all
 138 upstream ports should provide their own reset_link functions.
 139
 140 In struct pcie_port_service_driver, a new pointer, reset_link, is
 141 added.
 142
 143 pci_ers_result_t (*reset_link) (struct pci_dev *dev);
 144
 145 Section 3.2.2.2 provides more detailed info on when to call
 146 reset_link.
 147
 148 3.2.2 PCI error-recovery callbacks
 149
 150 The PCI Express AER Root driver uses error callbacks to coordinate
 151 with downstream device drivers associated with a hierarchy in question
 152 when performing error recovery actions.
 153
 154 Data struct pci_driver has a pointer, err_handler, to point to
 155 pci_error_handlers who consists of a couple of callback function
 156 pointers. AER driver follows the rules defined in
 157 pci-error-recovery.txt except pci express specific parts (e.g.
 158 reset_link). Pls. refer to pci-error-recovery.txt for detailed
 159 definitions of the callbacks.
 160
 161 Below sections specify when to call the error callback functions.
 162
 163 3.2.2.1 Correctable errors
 164
 165 Correctable errors pose no impacts on the functionality of
 166 the interface. The PCI Express protocol can recover without any
 167 software intervention or any loss of data. These errors do not
 168 require any recovery actions. The AER driver clears the device's
 169 correctable error status register accordingly and logs these errors.
 170
 171 3.2.2.2 Non-correctable (non-fatal and fatal) errors
 172
 173 If an error message indicates a non-fatal error, performing link reset
 174 at upstream is not required. The AER driver calls error_detected(dev,
 175 pci_channel_io_normal) to all drivers associated within a hierarchy in
 176 question. for example,
 177 EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort.
 178 If Upstream port A captures an AER error, the hierarchy consists of
 179 Downstream port B and EndPoint.
 180
 181 A driver may return PCI_ERS_RESULT_CAN_RECOVER,
 182 PCI_ERS_RESULT_DISCONNECT, or PCI_ERS_RESULT_NEED_RESET, depending on
 183 whether it can recover or the AER driver calls mmio_enabled as next.
 184
 185 If an error message indicates a fatal error, kernel will broadcast
 186 error_detected(dev, pci_channel_io_frozen) to all drivers within
 187 a hierarchy in question. Then, performing link reset at upstream is
 188 necessary. As different kinds of devices might use different approaches
 189 to reset link, AER port service driver is required to provide the
 190 function to reset link. Firstly, kernel looks for if the upstream
 191 component has an aer driver. If it has, kernel uses the reset_link
 192 callback of the aer driver. If the upstream component has no aer driver
 193 and the port is downstream port, we will perform a hot reset as the
 194 default by setting the Secondary Bus Reset bit of the Bridge Control
 195 register associated with the downstream port. As for upstream ports,
 196 they should provide their own aer service drivers with reset_link
 197 function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and
 198 reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes
 199 to mmio_enabled.
 200
 201 3.3 helper functions
 202
 203 3.3.1 int pci_enable_pcie_error_reporting(struct pci_dev *dev);
 204 pci_enable_pcie_error_reporting enables the device to send error
 205 messages to root port when an error is detected. Note that devices
 206 don't enable the error reporting by default, so device drivers need
 207 call this function to enable it.
 208
 209 3.3.2 int pci_disable_pcie_error_reporting(struct pci_dev *dev);
 210 pci_disable_pcie_error_reporting disables the device to send error
 211 messages to root port when an error is detected.
 212
 213 3.3.3 int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev);
 214 pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable
 215 error status register.
 216
 217 3.4 Frequent Asked Questions
 218
 219 Q: What happens if a PCI Express device driver does not provide an
 220 error recovery handler (pci_driver->err_handler is equal to NULL)?
 221
 222 A: The devices attached with the driver won't be recovered. If the
 223 error is fatal, kernel will print out warning messages. Please refer
 224 to section 3 for more information.
 225
 226 Q: What happens if an upstream port service driver does not provide
 227 callback reset_link?
 228
 229 A: Fatal error recovery will fail if the errors are reported by the
 230 upstream ports who are attached by the service driver.
 231
 232 Q: How does this infrastructure deal with driver that is not PCI
 233 Express aware?
 234
 235 A: This infrastructure calls the error callback functions of the
 236 driver when an error happens. But if the driver is not aware of
 237 PCI Express, the device might not report its own errors to root
 238 port.
 239
 240 Q: What modifications will that driver need to make it compatible
 241 with the PCI Express AER Root driver?
 242
 243 A: It could call the helper functions to enable AER in devices and
 244 cleanup uncorrectable status register. Pls. refer to section 3.3.
 245
 246
 247 4. Software error injection
 248
 249 Debugging PCIe AER error recovery code is quite difficult because it
 250 is hard to trigger real hardware errors. Software based error
 251 injection can be used to fake various kinds of PCIe errors.
 252
 253 First you should enable PCIe AER software error injection in kernel
 254 configuration, that is, following item should be in your .config.
 255
 256 CONFIG_PCIEAER_INJECT=y or CONFIG_PCIEAER_INJECT=m
 257
 258 After reboot with new kernel or insert the module, a device file named
 259 /dev/aer_inject should be created.
 260
 261 Then, you need a user space tool named aer-inject, which can be gotten
 262 from:
 263     http://www.kernel.org/pub/linux/utils/pci/aer-inject/
 264
 265 More information about aer-inject can be found in the document comes
 266 with its source code.