aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/cputopology.txt41
-rw-r--r--Documentation/driver-model/overview.txt57
-rw-r--r--Documentation/parport-lowlevel.txt8
-rw-r--r--Documentation/pci-error-recovery.txt472
4 files changed, 381 insertions, 197 deletions
diff --git a/Documentation/cputopology.txt b/Documentation/cputopology.txt
new file mode 100644
index 000000000000..ff280e2e1613
--- /dev/null
+++ b/Documentation/cputopology.txt
@@ -0,0 +1,41 @@
1
2Export cpu topology info by sysfs. Items (attributes) are similar
3to /proc/cpuinfo.
4
51) /sys/devices/system/cpu/cpuX/topology/physical_package_id:
6represent the physical package id of cpu X;
72) /sys/devices/system/cpu/cpuX/topology/core_id:
8represent the cpu core id to cpu X;
93) /sys/devices/system/cpu/cpuX/topology/thread_siblings:
10represent the thread siblings to cpu X in the same core;
114) /sys/devices/system/cpu/cpuX/topology/core_siblings:
12represent the thread siblings to cpu X in the same physical package;
13
14To implement it in an architecture-neutral way, a new source file,
15driver/base/topology.c, is to export the 5 attributes.
16
17If one architecture wants to support this feature, it just needs to
18implement 4 defines, typically in file include/asm-XXX/topology.h.
19The 4 defines are:
20#define topology_physical_package_id(cpu)
21#define topology_core_id(cpu)
22#define topology_thread_siblings(cpu)
23#define topology_core_siblings(cpu)
24
25The type of **_id is int.
26The type of siblings is cpumask_t.
27
28To be consistent on all architectures, the 4 attributes should have
29deafult values if their values are unavailable. Below is the rule.
301) physical_package_id: If cpu has no physical package id, -1 is the
31default value.
322) core_id: If cpu doesn't support multi-core, its core id is 0.
333) thread_siblings: Just include itself, if the cpu doesn't support
34HT/multi-thread.
354) core_siblings: Just include itself, if the cpu doesn't support
36multi-core and HT/Multi-thread.
37
38So be careful when declaring the 4 defines in include/asm-XXX/topology.h.
39
40If an attribute isn't defined on an architecture, it won't be exported.
41
diff --git a/Documentation/driver-model/overview.txt b/Documentation/driver-model/overview.txt
index 44662735cf81..ac4a7a737e43 100644
--- a/Documentation/driver-model/overview.txt
+++ b/Documentation/driver-model/overview.txt
@@ -1,50 +1,43 @@
1The Linux Kernel Device Model 1The Linux Kernel Device Model
2 2
3Patrick Mochel <mochel@osdl.org> 3Patrick Mochel <mochel@digitalimplant.org>
4 4
526 August 2002 5Drafted 26 August 2002
6Updated 31 January 2006
6 7
7 8
8Overview 9Overview
9~~~~~~~~ 10~~~~~~~~
10 11
11This driver model is a unification of all the current, disparate driver models 12The Linux Kernel Driver Model is a unification of all the disparate driver
12that are currently in the kernel. It is intended to augment the 13models that were previously used in the kernel. It is intended to augment the
13bus-specific drivers for bridges and devices by consolidating a set of data 14bus-specific drivers for bridges and devices by consolidating a set of data
14and operations into globally accessible data structures. 15and operations into globally accessible data structures.
15 16
16Current driver models implement some sort of tree-like structure (sometimes 17Traditional driver models implemented some sort of tree-like structure
17just a list) for the devices they control. But, there is no linkage between 18(sometimes just a list) for the devices they control. There wasn't any
18the different bus types. 19uniformity across the different bus types.
19 20
20A common data structure can provide this linkage with little overhead: when a 21The current driver model provides a comon, uniform data model for describing
21bus driver discovers a particular device, it can insert it into the global 22a bus and the devices that can appear under the bus. The unified bus
22tree as well as its local tree. In fact, the local tree becomes just a subset 23model includes a set of common attributes which all busses carry, and a set
23of the global tree. 24of common callbacks, such as device discovery during bus probing, bus
24 25shutdown, bus power management, etc.
25Common data fields can also be moved out of the local bus models into the
26global model. Some of the manipulations of these fields can also be
27consolidated. Most likely, manipulation functions will become a set
28of helper functions, which the bus drivers wrap around to include any
29bus-specific items.
30
31The common device and bridge interface currently reflects the goals of the
32modern PC: namely the ability to do seamless Plug and Play, power management,
33and hot plug. (The model dictated by Intel and Microsoft (read: ACPI) ensures
34us that any device in the system may fit any of these criteria.)
35
36In reality, not every bus will be able to support such operations. But, most
37buses will support a majority of those operations, and all future buses will.
38In other words, a bus that doesn't support an operation is the exception,
39instead of the other way around.
40 26
27The common device and bridge interface reflects the goals of the modern
28computer: namely the ability to do seamless device "plug and play", power
29management, and hot plug. In particular, the model dictated by Intel and
30Microsoft (namely ACPI) ensures that almost every device on almost any bus
31on an x86-compatible system can work within this paradigm. Of course,
32not every bus is able to support all such operations, although most
33buses support a most of those operations.
41 34
42 35
43Downstream Access 36Downstream Access
44~~~~~~~~~~~~~~~~~ 37~~~~~~~~~~~~~~~~~
45 38
46Common data fields have been moved out of individual bus layers into a common 39Common data fields have been moved out of individual bus layers into a common
47data structure. But, these fields must still be accessed by the bus layers, 40data structure. These fields must still be accessed by the bus layers,
48and sometimes by the device-specific drivers. 41and sometimes by the device-specific drivers.
49 42
50Other bus layers are encouraged to do what has been done for the PCI layer. 43Other bus layers are encouraged to do what has been done for the PCI layer.
@@ -53,7 +46,7 @@ struct pci_dev now looks like this:
53struct pci_dev { 46struct pci_dev {
54 ... 47 ...
55 48
56 struct device device; 49 struct device dev;
57}; 50};
58 51
59Note first that it is statically allocated. This means only one allocation on 52Note first that it is statically allocated. This means only one allocation on
@@ -64,9 +57,9 @@ the two.
64 57
65The PCI bus layer freely accesses the fields of struct device. It knows about 58The PCI bus layer freely accesses the fields of struct device. It knows about
66the structure of struct pci_dev, and it should know the structure of struct 59the structure of struct pci_dev, and it should know the structure of struct
67device. PCI devices that have been converted generally do not touch the fields 60device. Individual PCI device drivers that have been converted the the current
68of struct device. More precisely, device-specific drivers should not touch 61driver model generally do not and should not touch the fields of struct device,
69fields of struct device unless there is a strong compelling reason to do so. 62unless there is a strong compelling reason to do so.
70 63
71This abstraction is prevention of unnecessary pain during transitional phases. 64This abstraction is prevention of unnecessary pain during transitional phases.
72If the name of the field changes or is removed, then every downstream driver 65If the name of the field changes or is removed, then every downstream driver
diff --git a/Documentation/parport-lowlevel.txt b/Documentation/parport-lowlevel.txt
index 1d40008a1926..8f2302415eff 100644
--- a/Documentation/parport-lowlevel.txt
+++ b/Documentation/parport-lowlevel.txt
@@ -1068,7 +1068,7 @@ SYNOPSIS
1068 1068
1069struct parport_operations { 1069struct parport_operations {
1070 ... 1070 ...
1071 void (*write_status) (struct parport *port, unsigned char s); 1071 void (*write_control) (struct parport *port, unsigned char s);
1072 ... 1072 ...
1073}; 1073};
1074 1074
@@ -1097,9 +1097,9 @@ SYNOPSIS
1097 1097
1098struct parport_operations { 1098struct parport_operations {
1099 ... 1099 ...
1100 void (*frob_control) (struct parport *port, 1100 unsigned char (*frob_control) (struct parport *port,
1101 unsigned char mask, 1101 unsigned char mask,
1102 unsigned char val); 1102 unsigned char val);
1103 ... 1103 ...
1104}; 1104};
1105 1105
diff --git a/Documentation/pci-error-recovery.txt b/Documentation/pci-error-recovery.txt
index d089967e4948..634d3e5b5756 100644
--- a/Documentation/pci-error-recovery.txt
+++ b/Documentation/pci-error-recovery.txt
@@ -1,246 +1,396 @@
1 1
2 PCI Error Recovery 2 PCI Error Recovery
3 ------------------ 3 ------------------
4 May 31, 2005 4 February 2, 2006
5 5
6 Current document maintainer: 6 Current document maintainer:
7 Linas Vepstas <linas@austin.ibm.com> 7 Linas Vepstas <linas@austin.ibm.com>
8 8
9 9
10Some PCI bus controllers are able to detect certain "hard" PCI errors 10Many PCI bus controllers are able to detect a variety of hardware
11on the bus, such as parity errors on the data and address busses, as 11PCI errors on the bus, such as parity errors on the data and address
12well as SERR and PERR errors. These chipsets are then able to disable 12busses, as well as SERR and PERR errors. Some of the more advanced
13I/O to/from the affected device, so that, for example, a bad DMA 13chipsets are able to deal with these errors; these include PCI-E chipsets,
14address doesn't end up corrupting system memory. These same chipsets 14and the PCI-host bridges found on IBM Power4 and Power5-based pSeries
15are also able to reset the affected PCI device, and return it to 15boxes. A typical action taken is to disconnect the affected device,
16working condition. This document describes a generic API form 16halting all I/O to it. The goal of a disconnection is to avoid system
17performing error recovery. 17corruption; for example, to halt system memory corruption due to DMA's
18 18to "wild" addresses. Typically, a reconnection mechanism is also
19The core idea is that after a PCI error has been detected, there must 19offered, so that the affected PCI device(s) are reset and put back
20be a way for the kernel to coordinate with all affected device drivers 20into working condition. The reset phase requires coordination
21so that the pci card can be made operational again, possibly after 21between the affected device drivers and the PCI controller chip.
22performing a full electrical #RST of the PCI card. The API below 22This document describes a generic API for notifying device drivers
23provides a generic API for device drivers to be notified of PCI 23of a bus disconnection, and then performing error recovery.
24errors, and to be notified of, and respond to, a reset sequence. 24This API is currently implemented in the 2.6.16 and later kernels.
25 25
26Preliminary sketch of API, cut-n-pasted-n-modified email from 26Reporting and recovery is performed in several steps. First, when
27Ben Herrenschmidt, circa 5 april 2005 27a PCI hardware error has resulted in a bus disconnect, that event
28is reported as soon as possible to all affected device drivers,
29including multiple instances of a device driver on multi-function
30cards. This allows device drivers to avoid deadlocking in spinloops,
31waiting for some i/o-space register to change, when it never will.
32It also gives the drivers a chance to defer incoming I/O as
33needed.
34
35Next, recovery is performed in several stages. Most of the complexity
36is forced by the need to handle multi-function devices, that is,
37devices that have multiple device drivers associated with them.
38In the first stage, each driver is allowed to indicate what type
39of reset it desires, the choices being a simple re-enabling of I/O
40or requesting a hard reset (a full electrical #RST of the PCI card).
41If any driver requests a full reset, that is what will be done.
42
43After a full reset and/or a re-enabling of I/O, all drivers are
44again notified, so that they may then perform any device setup/config
45that may be required. After these have all completed, a final
46"resume normal operations" event is sent out.
47
48The biggest reason for choosing a kernel-based implementation rather
49than a user-space implementation was the need to deal with bus
50disconnects of PCI devices attached to storage media, and, in particular,
51disconnects from devices holding the root file system. If the root
52file system is disconnected, a user-space mechanism would have to go
53through a large number of contortions to complete recovery. Almost all
54of the current Linux file systems are not tolerant of disconnection
55from/reconnection to their underlying block device. By contrast,
56bus errors are easy to manage in the device driver. Indeed, most
57device drivers already handle very similar recovery procedures;
58for example, the SCSI-generic layer already provides significant
59mechanisms for dealing with SCSI bus errors and SCSI bus resets.
60
61
62Detailed Design
63---------------
64Design and implementation details below, based on a chain of
65public email discussions with Ben Herrenschmidt, circa 5 April 2005.
28 66
29The error recovery API support is exposed to the driver in the form of 67The error recovery API support is exposed to the driver in the form of
30a structure of function pointers pointed to by a new field in struct 68a structure of function pointers pointed to by a new field in struct
31pci_driver. The absence of this pointer in pci_driver denotes an 69pci_driver. A driver that fails to provide the structure is "non-aware",
32"non-aware" driver, behaviour on these is platform dependant. 70and the actual recovery steps taken are platform dependent. The
33Platforms like ppc64 can try to simulate pci hotplug remove/add. 71arch/powerpc implementation will simulate a PCI hotplug remove/add.
34
35The definition of "pci_error_token" is not covered here. It is based on
36Seto's work on the synchronous error detection. We still need to define
37functions for extracting infos out of an opaque error token. This is
38separate from this API.
39 72
40This structure has the form: 73This structure has the form:
41
42struct pci_error_handlers 74struct pci_error_handlers
43{ 75{
44 int (*error_detected)(struct pci_dev *dev, pci_error_token error); 76 int (*error_detected)(struct pci_dev *dev, enum pci_channel_state);
45 int (*mmio_enabled)(struct pci_dev *dev); 77 int (*mmio_enabled)(struct pci_dev *dev);
46 int (*resume)(struct pci_dev *dev);
47 int (*link_reset)(struct pci_dev *dev); 78 int (*link_reset)(struct pci_dev *dev);
48 int (*slot_reset)(struct pci_dev *dev); 79 int (*slot_reset)(struct pci_dev *dev);
80 void (*resume)(struct pci_dev *dev);
49}; 81};
50 82
51A driver doesn't have to implement all of these callbacks. The 83The possible channel states are:
52only mandatory one is error_detected(). If a callback is not 84enum pci_channel_state {
53implemented, the corresponding feature is considered unsupported. 85 pci_channel_io_normal, /* I/O channel is in normal state */
54For example, if mmio_enabled() and resume() aren't there, then the 86 pci_channel_io_frozen, /* I/O to channel is blocked */
55driver is assumed as not doing any direct recovery and requires 87 pci_channel_io_perm_failure, /* PCI card is dead */
88};
89
90Possible return values are:
91enum pci_ers_result {
92 PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */
93 PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */
94 PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */
95 PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */
96 PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */
97};
98
99A driver does not have to implement all of these callbacks; however,
100if it implements any, it must implement error_detected(). If a callback
101is not implemented, the corresponding feature is considered unsupported.
102For example, if mmio_enabled() and resume() aren't there, then it
103is assumed that the driver is not doing any direct recovery and requires
56a reset. If link_reset() is not implemented, the card is assumed as 104a reset. If link_reset() is not implemented, the card is assumed as
57not caring about link resets, in which case, if recover is supported, 105not care about link resets. Typically a driver will want to know about
58the core can try recover (but not slot_reset() unless it really did 106a slot_reset().
59reset the slot). If slot_reset() is not supported, link_reset() can 107
60be called instead on a slot reset. 108The actual steps taken by a platform to recover from a PCI error
61 109event will be platform-dependent, but will follow the general
62At first, the call will always be : 110sequence described below.
63 111
64 1) error_detected() 112STEP 0: Error Event
65 113-------------------
66 Error detected. This is sent once after an error has been detected. At 114PCI bus error is detect by the PCI hardware. On powerpc, the slot
67this point, the device might not be accessible anymore depending on the 115is isolated, in that all I/O is blocked: all reads return 0xffffffff,
68platform (the slot will be isolated on ppc64). The driver may already 116all writes are ignored.
69have "noticed" the error because of a failing IO, but this is the proper 117
70"synchronisation point", that is, it gives a chance to the driver to 118
71cleanup, waiting for pending stuff (timers, whatever, etc...) to 119STEP 1: Notification
72complete; it can take semaphores, schedule, etc... everything but touch 120--------------------
73the device. Within this function and after it returns, the driver 121Platform calls the error_detected() callback on every instance of
122every driver affected by the error.
123
124At this point, the device might not be accessible anymore, depending on
125the platform (the slot will be isolated on powerpc). The driver may
126already have "noticed" the error because of a failing I/O, but this
127is the proper "synchronization point", that is, it gives the driver
128a chance to cleanup, waiting for pending stuff (timers, whatever, etc...)
129to complete; it can take semaphores, schedule, etc... everything but
130touch the device. Within this function and after it returns, the driver
74shouldn't do any new IOs. Called in task context. This is sort of a 131shouldn't do any new IOs. Called in task context. This is sort of a
75"quiesce" point. See note about interrupts at the end of this doc. 132"quiesce" point. See note about interrupts at the end of this doc.
76 133
77 Result codes: 134All drivers participating in this system must implement this call.
78 - PCIERR_RESULT_CAN_RECOVER: 135The driver must return one of the following result codes:
79 Driever returns this if it thinks it might be able to recover 136 - PCI_ERS_RESULT_CAN_RECOVER:
137 Driver returns this if it thinks it might be able to recover
80 the HW by just banging IOs or if it wants to be given 138 the HW by just banging IOs or if it wants to be given
81 a chance to extract some diagnostic informations (see 139 a chance to extract some diagnostic information (see
82 below). 140 mmio_enable, below).
83 - PCIERR_RESULT_NEED_RESET: 141 - PCI_ERS_RESULT_NEED_RESET:
84 Driver returns this if it thinks it can't recover unless the 142 Driver returns this if it can't recover without a hard
85 slot is reset. 143 slot reset.
86 - PCIERR_RESULT_DISCONNECT: 144 - PCI_ERS_RESULT_DISCONNECT:
87 Return this if driver thinks it won't recover at all, 145 Driver returns this if it doesn't want to recover at all.
88 (this will detach the driver ? or just leave it 146
89 dangling ? to be decided) 147The next step taken will depend on the result codes returned by the
90 148drivers.
91So at this point, we have called error_detected() for all drivers 149
92on the segment that had the error. On ppc64, the slot is isolated. What 150If all drivers on the segment/slot return PCI_ERS_RESULT_CAN_RECOVER,
93happens now typically depends on the result from the drivers. If all 151then the platform should re-enable IOs on the slot (or do nothing in
94drivers on the segment/slot return PCIERR_RESULT_CAN_RECOVER, we would 152particular, if the platform doesn't isolate slots), and recovery
95re-enable IOs on the slot (or do nothing special if the platform doesn't 153proceeds to STEP 2 (MMIO Enable).
96isolate slots) and call 2). If not and we can reset slots, we go to 4), 154
97if neither, we have a dead slot. If it's an hotplug slot, we might 155If any driver requested a slot reset (by returning PCI_ERS_RESULT_NEED_RESET),
98"simulate" reset by triggering HW unplug/replug though. 156then recovery proceeds to STEP 4 (Slot Reset).
99 157
100>>> Current ppc64 implementation assumes that a device driver will 158If the platform is unable to recover the slot, the next step
101>>> *not* schedule or semaphore in this routine; the current ppc64 159is STEP 6 (Permanent Failure).
160
161>>> The current powerpc implementation assumes that a device driver will
162>>> *not* schedule or semaphore in this routine; the current powerpc
102>>> implementation uses one kernel thread to notify all devices; 163>>> implementation uses one kernel thread to notify all devices;
103>>> thus, of one device sleeps/schedules, all devices are affected. 164>>> thus, if one device sleeps/schedules, all devices are affected.
104>>> Doing better requires complex multi-threaded logic in the error 165>>> Doing better requires complex multi-threaded logic in the error
105>>> recovery implementation (e.g. waiting for all notification threads 166>>> recovery implementation (e.g. waiting for all notification threads
106>>> to "join" before proceeding with recovery.) This seems excessively 167>>> to "join" before proceeding with recovery.) This seems excessively
107>>> complex and not worth implementing. 168>>> complex and not worth implementing.
108 169
109>>> The current ppc64 implementation doesn't much care if the device 170>>> The current powerpc implementation doesn't much care if the device
110>>> attempts i/o at this point, or not. I/O's will fail, returning 171>>> attempts I/O at this point, or not. I/O's will fail, returning
111>>> a value of 0xff on read, and writes will be dropped. If the device 172>>> a value of 0xff on read, and writes will be dropped. If the device
112>>> driver attempts more than 10K I/O's to a frozen adapter, it will 173>>> driver attempts more than 10K I/O's to a frozen adapter, it will
113>>> assume that the device driver has gone into an infinite loop, and 174>>> assume that the device driver has gone into an infinite loop, and
114>>> it will panic the the kernel. 175>>> it will panic the the kernel. There doesn't seem to be any other
176>>> way of stopping a device driver that insists on spinning on I/O.
115 177
116 2) mmio_enabled() 178STEP 2: MMIO Enabled
179-------------------
180The platform re-enables MMIO to the device (but typically not the
181DMA), and then calls the mmio_enabled() callback on all affected
182device drivers.
117 183
118 This is the "early recovery" call. IOs are allowed again, but DMA is 184This is the "early recovery" call. IOs are allowed again, but DMA is
119not (hrm... to be discussed, I prefer not), with some restrictions. This 185not (hrm... to be discussed, I prefer not), with some restrictions. This
120is NOT a callback for the driver to start operations again, only to 186is NOT a callback for the driver to start operations again, only to
121peek/poke at the device, extract diagnostic information, if any, and 187peek/poke at the device, extract diagnostic information, if any, and
122eventually do things like trigger a device local reset or some such, 188eventually do things like trigger a device local reset or some such,
123but not restart operations. This is sent if all drivers on a segment 189but not restart operations. This is callback is made if all drivers on
124agree that they can try to recover and no automatic link reset was 190a segment agree that they can try to recover and if no automatic link reset
125performed by the HW. If the platform can't just re-enable IOs without 191was performed by the HW. If the platform can't just re-enable IOs without
126a slot reset or a link reset, it doesn't call this callback and goes 192a slot reset or a link reset, it wont call this callback, and instead
127directly to 3) or 4). All IOs should be done _synchronously_ from 193will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset)
128within this callback, errors triggered by them will be returned via 194
129the normal pci_check_whatever() api, no new error_detected() callback 195>>> The following is proposed; no platform implements this yet:
130will be issued due to an error happening here. However, such an error 196>>> Proposal: All I/O's should be done _synchronously_ from within
131might cause IOs to be re-blocked for the whole segment, and thus 197>>> this callback, errors triggered by them will be returned via
132invalidate the recovery that other devices on the same segment might 198>>> the normal pci_check_whatever() API, no new error_detected()
133have done, forcing the whole segment into one of the next states, 199>>> callback will be issued due to an error happening here. However,
134that is link reset or slot reset. 200>>> such an error might cause IOs to be re-blocked for the whole
135 201>>> segment, and thus invalidate the recovery that other devices
136 Result codes: 202>>> on the same segment might have done, forcing the whole segment
137 - PCIERR_RESULT_RECOVERED 203>>> into one of the next states, that is, link reset or slot reset.
204
205The driver should return one of the following result codes:
206 - PCI_ERS_RESULT_RECOVERED
138 Driver returns this if it thinks the device is fully 207 Driver returns this if it thinks the device is fully
139 functionnal and thinks it is ready to start 208 functional and thinks it is ready to start
140 normal driver operations again. There is no 209 normal driver operations again. There is no
141 guarantee that the driver will actually be 210 guarantee that the driver will actually be
142 allowed to proceed, as another driver on the 211 allowed to proceed, as another driver on the
143 same segment might have failed and thus triggered a 212 same segment might have failed and thus triggered a
144 slot reset on platforms that support it. 213 slot reset on platforms that support it.
145 214
146 - PCIERR_RESULT_NEED_RESET 215 - PCI_ERS_RESULT_NEED_RESET
147 Driver returns this if it thinks the device is not 216 Driver returns this if it thinks the device is not
148 recoverable in it's current state and it needs a slot 217 recoverable in it's current state and it needs a slot
149 reset to proceed. 218 reset to proceed.
150 219
151 - PCIERR_RESULT_DISCONNECT 220 - PCI_ERS_RESULT_DISCONNECT
152 Same as above. Total failure, no recovery even after 221 Same as above. Total failure, no recovery even after
153 reset driver dead. (To be defined more precisely) 222 reset driver dead. (To be defined more precisely)
154 223
155>>> The current ppc64 implementation does not implement this callback. 224The next step taken depends on the results returned by the drivers.
225If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform
226proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations).
227
228If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform
229proceeds to STEP 4 (Slot Reset)
156 230
157 3) link_reset() 231>>> The current powerpc implementation does not implement this callback.
158 232
159 This is called after the link has been reset. This is typically 233
160a PCI Express specific state at this point and is done whenever a 234STEP 3: Link Reset
161non-fatal error has been detected that can be "solved" by resetting 235------------------
162the link. This call informs the driver of the reset and the driver 236The platform resets the link, and then calls the link_reset() callback
163should check if the device appears to be in working condition. 237on all affected device drivers. This is a PCI-Express specific state
164This function acts a bit like 2) mmio_enabled(), in that the driver 238and is done whenever a non-fatal error has been detected that can be
165is not supposed to restart normal driver I/O operations right away. 239"solved" by resetting the link. This call informs the driver of the
166Instead, it should just "probe" the device to check it's recoverability 240reset and the driver should check to see if the device appears to be
167status. If all is right, then the core will call resume() once all 241in working condition.
168drivers have ack'd link_reset(). 242
243The driver is not supposed to restart normal driver I/O operations
244at this point. It should limit itself to "probing" the device to
245check it's recoverability status. If all is right, then the platform
246will call resume() once all drivers have ack'd link_reset().
169 247
170 Result codes: 248 Result codes:
171 (identical to mmio_enabled) 249 (identical to STEP 3 (MMIO Enabled)
250
251The platform then proceeds to either STEP 4 (Slot Reset) or STEP 5
252(Resume Operations).
253
254>>> The current powerpc implementation does not implement this callback.
255
256
257STEP 4: Slot Reset
258------------------
259The platform performs a soft or hard reset of the device, and then
260calls the slot_reset() callback.
261
262A soft reset consists of asserting the adapter #RST line and then
263restoring the PCI BAR's and PCI configuration header to a state
264that is equivalent to what it would be after a fresh system
265power-on followed by power-on BIOS/system firmware initialization.
266If the platform supports PCI hotplug, then the reset might be
267performed by toggling the slot electrical power off/on.
172 268
173>>> The current ppc64 implementation does not implement this callback. 269It is important for the platform to restore the PCI config space
270to the "fresh poweron" state, rather than the "last state". After
271a slot reset, the device driver will almost always use its standard
272device initialization routines, and an unusual config space setup
273may result in hung devices, kernel panics, or silent data corruption.
174 274
175 4) slot_reset() 275This call gives drivers the chance to re-initialize the hardware
276(re-download firmware, etc.). At this point, the driver may assume
277that he card is in a fresh state and is fully functional. In
278particular, interrupt generation should work normally.
176 279
177 This is called after the slot has been soft or hard reset by the 280Drivers should not yet restart normal I/O processing operations
178platform. A soft reset consists of asserting the adapter #RST line 281at this point. If all device drivers report success on this
179and then restoring the PCI BARs and PCI configuration header. If the 282callback, the platform will call resume() to complete the sequence,
180platform supports PCI hotplug, then it might instead perform a hard 283and let the driver restart normal I/O processing.
181reset by toggling power on the slot off/on. This call gives drivers
182the chance to re-initialize the hardware (re-download firmware, etc.),
183but drivers shouldn't restart normal I/O processing operations at
184this point. (See note about interrupts; interrupts aren't guaranteed
185to be delivered until the resume() callback has been called). If all
186device drivers report success on this callback, the patform will call
187resume() to complete the error handling and let the driver restart
188normal I/O processing.
189 284
190A driver can still return a critical failure for this function if 285A driver can still return a critical failure for this function if
191it can't get the device operational after reset. If the platform 286it can't get the device operational after reset. If the platform
192previously tried a soft reset, it migh now try a hard reset (power 287previously tried a soft reset, it might now try a hard reset (power
193cycle) and then call slot_reset() again. It the device still can't 288cycle) and then call slot_reset() again. It the device still can't
194be recovered, there is nothing more that can be done; the platform 289be recovered, there is nothing more that can be done; the platform
195will typically report a "permanent failure" in such a case. The 290will typically report a "permanent failure" in such a case. The
196device will be considered "dead" in this case. 291device will be considered "dead" in this case.
197 292
198 Result codes: 293Drivers for multi-function cards will need to coordinate among
199 - PCIERR_RESULT_DISCONNECT 294themselves as to which driver instance will perform any "one-shot"
200 Same as above. 295or global device initialization. For example, the Symbios sym53cxx2
296driver performs device init only from PCI function 0:
201 297
202>>> The current ppc64 implementation does not try a power-cycle reset 298+ if (PCI_FUNC(pdev->devfn) == 0)
203>>> if the driver returned PCIERR_RESULT_DISCONNECT. However, it should. 299+ sym_reset_scsi_bus(np, 0);
204 300
205 5) resume() 301 Result codes:
206 302 - PCI_ERS_RESULT_DISCONNECT
207 This is called if all drivers on the segment have returned 303 Same as above.
208PCIERR_RESULT_RECOVERED from one of the 3 prevous callbacks.
209That basically tells the driver to restart activity, tht everything
210is back and running. No result code is taken into account here. If
211a new error happens, it will restart a new error handling process.
212 304
213That's it. I think this covers all the possibilities. The way those 305Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent
214callbacks are called is platform policy. A platform with no slot reset 306Failure).
215capability for example may want to just "ignore" drivers that can't 307
308>>> The current powerpc implementation does not currently try a
309>>> power-cycle reset if the driver returned PCI_ERS_RESULT_DISCONNECT.
310>>> However, it probably should.
311
312
313STEP 5: Resume Operations
314-------------------------
315The platform will call the resume() callback on all affected device
316drivers if all drivers on the segment have returned
317PCI_ERS_RESULT_RECOVERED from one of the 3 previous callbacks.
318The goal of this callback is to tell the driver to restart activity,
319that everything is back and running. This callback does not return
320a result code.
321
322At this point, if a new error happens, the platform will restart
323a new error recovery sequence.
324
325STEP 6: Permanent Failure
326-------------------------
327A "permanent failure" has occurred, and the platform cannot recover
328the device. The platform will call error_detected() with a
329pci_channel_state value of pci_channel_io_perm_failure.
330
331The device driver should, at this point, assume the worst. It should
332cancel all pending I/O, refuse all new I/O, returning -EIO to
333higher layers. The device driver should then clean up all of its
334memory and remove itself from kernel operations, much as it would
335during system shutdown.
336
337The platform will typically notify the system operator of the
338permanent failure in some way. If the device is hotplug-capable,
339the operator will probably want to remove and replace the device.
340Note, however, not all failures are truly "permanent". Some are
341caused by over-heating, some by a poorly seated card. Many
342PCI error events are caused by software bugs, e.g. DMA's to
343wild addresses or bogus split transactions due to programming
344errors. See the discussion in powerpc/eeh-pci-error-recovery.txt
345for additional detail on real-life experience of the causes of
346software errors.
347
348
349Conclusion; General Remarks
350---------------------------
351The way those callbacks are called is platform policy. A platform with
352no slot reset capability may want to just "ignore" drivers that can't
216recover (disconnect them) and try to let other cards on the same segment 353recover (disconnect them) and try to let other cards on the same segment
217recover. Keep in mind that in most real life cases, though, there will 354recover. Keep in mind that in most real life cases, though, there will
218be only one driver per segment. 355be only one driver per segment.
219 356
220Now, there is a note about interrupts. If you get an interrupt and your 357Now, a note about interrupts. If you get an interrupt and your
221device is dead or has been isolated, there is a problem :) 358device is dead or has been isolated, there is a problem :)
222 359The current policy is to turn this into a platform policy.
223After much thinking, I decided to leave that to the platform. That is, 360That is, the recovery API only requires that:
224the recovery API only precies that:
225 361
226 - There is no guarantee that interrupt delivery can proceed from any 362 - There is no guarantee that interrupt delivery can proceed from any
227device on the segment starting from the error detection and until the 363device on the segment starting from the error detection and until the
228restart callback is sent, at which point interrupts are expected to be 364resume callback is sent, at which point interrupts are expected to be
229fully operational. 365fully operational.
230 366
231 - There is no guarantee that interrupt delivery is stopped, that is, ad 367 - There is no guarantee that interrupt delivery is stopped, that is,
232river that gets an interrupts after detecting an error, or that detects 368a driver that gets an interrupt after detecting an error, or that detects
233and error within the interrupt handler such that it prevents proper 369an error within the interrupt handler such that it prevents proper
234ack'ing of the interrupt (and thus removal of the source) should just 370ack'ing of the interrupt (and thus removal of the source) should just
235return IRQ_NOTHANDLED. It's up to the platform to deal with taht 371return IRQ_NOTHANDLED. It's up to the platform to deal with that
236condition, typically by masking the irq source during the duration of 372condition, typically by masking the IRQ source during the duration of
237the error handling. It is expected that the platform "knows" which 373the error handling. It is expected that the platform "knows" which
238interrupts are routed to error-management capable slots and can deal 374interrupts are routed to error-management capable slots and can deal
239with temporarily disabling that irq number during error processing (this 375with temporarily disabling that IRQ number during error processing (this
240isn't terribly complex). That means some IRQ latency for other devices 376isn't terribly complex). That means some IRQ latency for other devices
241sharing the interrupt, but there is simply no other way. High end 377sharing the interrupt, but there is simply no other way. High end
242platforms aren't supposed to share interrupts between many devices 378platforms aren't supposed to share interrupts between many devices
243anyway :) 379anyway :)
244 380
245 381>>> Implementation details for the powerpc platform are discussed in
246Revised: 31 May 2005 Linas Vepstas <linas@austin.ibm.com> 382>>> the file Documentation/powerpc/eeh-pci-error-recovery.txt
383
384>>> As of this writing, there are six device drivers with patches
385>>> implementing error recovery. Not all of these patches are in
386>>> mainline yet. These may be used as "examples":
387>>>
388>>> drivers/scsi/ipr.c
389>>> drivers/scsi/sym53cxx_2
390>>> drivers/next/e100.c
391>>> drivers/net/e1000
392>>> drivers/net/ixgb
393>>> drivers/net/s2io.c
394
395The End
396-------