blob: 5bcbb6ee3bc03cf1632bd345a7b28bc2a610e033 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5<book id="libataDevGuide">
6 <bookinfo>
7 <title>libATA Developer's Guide</title>
8
9 <authorgroup>
10 <author>
11 <firstname>Jeff</firstname>
12 <surname>Garzik</surname>
13 </author>
14 </authorgroup>
15
16 <copyright>
Jeff Garzik780a87f2005-05-30 15:41:05 -040017 <year>2003-2005</year>
Linus Torvalds1da177e2005-04-16 15:20:36 -070018 <holder>Jeff Garzik</holder>
19 </copyright>
20
21 <legalnotice>
22 <para>
23 The contents of this file are subject to the Open
24 Software License version 1.1 that can be found at
25 <ulink url="http://www.opensource.org/licenses/osl-1.1.txt">http://www.opensource.org/licenses/osl-1.1.txt</ulink> and is included herein
26 by reference.
27 </para>
28
29 <para>
30 Alternatively, the contents of this file may be used under the terms
31 of the GNU General Public License version 2 (the "GPL") as distributed
32 in the kernel source COPYING file, in which case the provisions of
33 the GPL are applicable instead of the above. If you wish to allow
34 the use of your version of this file only under the terms of the
35 GPL and not to allow others to use your version of this file under
36 the OSL, indicate your decision by deleting the provisions above and
37 replace them with the notice and other provisions required by the GPL.
38 If you do not delete the provisions above, a recipient may use your
39 version of this file under either the OSL or the GPL.
40 </para>
41
42 </legalnotice>
43 </bookinfo>
44
45<toc></toc>
46
Jeff Garzik07dd39b2005-05-30 13:15:52 -040047 <chapter id="libataIntroduction">
48 <title>Introduction</title>
49 <para>
50 libATA is a library used inside the Linux kernel to support ATA host
51 controllers and devices. libATA provides an ATA driver API, class
52 transports for ATA and ATAPI devices, and SCSI&lt;-&gt;ATA translation
53 for ATA devices according to the T10 SAT specification.
54 </para>
55 <para>
56 This Guide documents the libATA driver API, library functions, library
57 internals, and a couple sample ATA low-level drivers.
58 </para>
59 </chapter>
60
Linus Torvalds1da177e2005-04-16 15:20:36 -070061 <chapter id="libataDriverApi">
62 <title>libata Driver API</title>
Jeff Garzik92bab262005-05-31 20:43:57 -040063 <para>
64 struct ata_port_operations is defined for every low-level libata
65 hardware driver, and it controls how the low-level driver
66 interfaces with the ATA and SCSI layers.
67 </para>
68 <para>
69 FIS-based drivers will hook into the system with ->qc_prep() and
70 ->qc_issue() high-level hooks. Hardware which behaves in a manner
71 similar to PCI IDE hardware may utilize several generic helpers,
72 defining at a bare minimum the bus I/O addresses of the ATA shadow
73 register blocks.
74 </para>
Linus Torvalds1da177e2005-04-16 15:20:36 -070075 <sect1>
76 <title>struct ata_port_operations</title>
77
Jeff Garzik92bab262005-05-31 20:43:57 -040078 <sect2><title>Disable ATA port</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -070079 <programlisting>
80void (*port_disable) (struct ata_port *);
81 </programlisting>
82
83 <para>
84 Called from ata_bus_probe() and ata_bus_reset() error paths,
85 as well as when unregistering from the SCSI module (rmmod, hot
86 unplug).
Edward Falk8b2af8f2005-06-15 14:26:39 -070087 This function should do whatever needs to be done to take the
88 port out of use. In most cases, ata_port_disable() can be used
89 as this hook.
90 </para>
91 <para>
92 Called from ata_bus_probe() on a failed probe.
93 Called from ata_bus_reset() on a failed bus reset.
94 Called from ata_scsi_release().
Linus Torvalds1da177e2005-04-16 15:20:36 -070095 </para>
96
Jeff Garzik92bab262005-05-31 20:43:57 -040097 </sect2>
98
99 <sect2><title>Post-IDENTIFY device configuration</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700100 <programlisting>
101void (*dev_config) (struct ata_port *, struct ata_device *);
102 </programlisting>
103
104 <para>
105 Called after IDENTIFY [PACKET] DEVICE is issued to each device
106 found. Typically used to apply device-specific fixups prior to
107 issue of SET FEATURES - XFER MODE, and prior to operation.
108 </para>
Edward Falk8b2af8f2005-06-15 14:26:39 -0700109 <para>
110 Called by ata_device_add() after ata_dev_identify() determines
111 a device is present.
112 </para>
113 <para>
114 This entry may be specified as NULL in ata_port_operations.
115 </para>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700116
Jeff Garzik92bab262005-05-31 20:43:57 -0400117 </sect2>
118
119 <sect2><title>Set PIO/DMA mode</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700120 <programlisting>
121void (*set_piomode) (struct ata_port *, struct ata_device *);
122void (*set_dmamode) (struct ata_port *, struct ata_device *);
Alan Cox5444a6f2006-03-27 18:58:20 +0100123void (*post_set_mode) (struct ata_port *);
124unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700125 </programlisting>
126
127 <para>
128 Hooks called prior to the issue of SET FEATURES - XFER MODE
Alan Cox5444a6f2006-03-27 18:58:20 +0100129 command. The optional ->mode_filter() hook is called when libata
130 has built a mask of the possible modes. This is passed to the
131 ->mode_filter() function which should return a mask of valid modes
132 after filtering those unsuitable due to hardware limits. It is not
133 valid to use this interface to add modes.
134 </para>
135 <para>
136 dev->pio_mode and dev->dma_mode are guaranteed to be valid when
137 ->set_piomode() and when ->set_dmamode() is called. The timings for
138 any other drive sharing the cable will also be valid at this point.
139 That is the library records the decisions for the modes of each
140 drive on a channel before it attempts to set any of them.
141 </para>
142 <para>
143 ->post_set_mode() is
Linus Torvalds1da177e2005-04-16 15:20:36 -0700144 called unconditionally, after the SET FEATURES - XFER MODE
145 command completes successfully.
146 </para>
147
148 <para>
149 ->set_piomode() is always called (if present), but
150 ->set_dma_mode() is only called if DMA is possible.
151 </para>
152
Jeff Garzik92bab262005-05-31 20:43:57 -0400153 </sect2>
154
155 <sect2><title>Taskfile read/write</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700156 <programlisting>
157void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
158void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
159 </programlisting>
160
161 <para>
162 ->tf_load() is called to load the given taskfile into hardware
163 registers / DMA buffers. ->tf_read() is called to read the
164 hardware registers / DMA buffers, to obtain the current set of
165 taskfile register values.
Edward Falk8b2af8f2005-06-15 14:26:39 -0700166 Most drivers for taskfile-based hardware (PIO or MMIO) use
167 ata_tf_load() and ata_tf_read() for these hooks.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700168 </para>
169
Jeff Garzik92bab262005-05-31 20:43:57 -0400170 </sect2>
171
172 <sect2><title>ATA command execute</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700173 <programlisting>
174void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
175 </programlisting>
176
177 <para>
178 causes an ATA command, previously loaded with
179 ->tf_load(), to be initiated in hardware.
Edward Falk8b2af8f2005-06-15 14:26:39 -0700180 Most drivers for taskfile-based hardware use ata_exec_command()
181 for this hook.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700182 </para>
183
Jeff Garzik92bab262005-05-31 20:43:57 -0400184 </sect2>
185
186 <sect2><title>Per-cmd ATAPI DMA capabilities filter</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700187 <programlisting>
Jeff Garzik780a87f2005-05-30 15:41:05 -0400188int (*check_atapi_dma) (struct ata_queued_cmd *qc);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700189 </programlisting>
190
191 <para>
Jeff Garzik780a87f2005-05-30 15:41:05 -0400192Allow low-level driver to filter ATA PACKET commands, returning a status
193indicating whether or not it is OK to use DMA for the supplied PACKET
194command.
195 </para>
Edward Falk8b2af8f2005-06-15 14:26:39 -0700196 <para>
197 This hook may be specified as NULL, in which case libata will
198 assume that atapi dma can be supported.
199 </para>
Jeff Garzik780a87f2005-05-30 15:41:05 -0400200
Jeff Garzik92bab262005-05-31 20:43:57 -0400201 </sect2>
202
203 <sect2><title>Read specific ATA shadow registers</title>
Jeff Garzik780a87f2005-05-30 15:41:05 -0400204 <programlisting>
205u8 (*check_status)(struct ata_port *ap);
206u8 (*check_altstatus)(struct ata_port *ap);
207u8 (*check_err)(struct ata_port *ap);
208 </programlisting>
209
210 <para>
211 Reads the Status/AltStatus/Error ATA shadow register from
212 hardware. On some hardware, reading the Status register has
213 the side effect of clearing the interrupt condition.
Edward Falk8b2af8f2005-06-15 14:26:39 -0700214 Most drivers for taskfile-based hardware use
215 ata_check_status() for this hook.
216 </para>
217 <para>
218 Note that because this is called from ata_device_add(), at
219 least a dummy function that clears device interrupts must be
220 provided for all drivers, even if the controller doesn't
221 actually have a taskfile status register.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700222 </para>
223
Jeff Garzik92bab262005-05-31 20:43:57 -0400224 </sect2>
225
226 <sect2><title>Select ATA device on bus</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700227 <programlisting>
228void (*dev_select)(struct ata_port *ap, unsigned int device);
229 </programlisting>
230
231 <para>
232 Issues the low-level hardware command(s) that causes one of N
233 hardware devices to be considered 'selected' (active and
Jeff Garzik780a87f2005-05-30 15:41:05 -0400234 available for use) on the ATA bus. This generally has no
Edward Falk8b2af8f2005-06-15 14:26:39 -0700235 meaning on FIS-based devices.
236 </para>
237 <para>
238 Most drivers for taskfile-based hardware use
239 ata_std_dev_select() for this hook. Controllers which do not
240 support second drives on a port (such as SATA contollers) will
241 use ata_noop_dev_select().
Linus Torvalds1da177e2005-04-16 15:20:36 -0700242 </para>
243
Jeff Garzik92bab262005-05-31 20:43:57 -0400244 </sect2>
245
Alan Cox5444a6f2006-03-27 18:58:20 +0100246 <sect2><title>Private tuning method</title>
247 <programlisting>
248void (*set_mode) (struct ata_port *ap);
249 </programlisting>
250
251 <para>
252 By default libata performs drive and controller tuning in
253 accordance with the ATA timing rules and also applies blacklists
254 and cable limits. Some controllers need special handling and have
255 custom tuning rules, typically raid controllers that use ATA
256 commands but do not actually do drive timing.
257 </para>
258
259 <warning>
260 <para>
261 This hook should not be used to replace the standard controller
262 tuning logic when a controller has quirks. Replacing the default
263 tuning logic in that case would bypass handling for drive and
264 bridge quirks that may be important to data reliability. If a
265 controller needs to filter the mode selection it should use the
266 mode_filter hook instead.
267 </para>
268 </warning>
269
270 </sect2>
271
Jeff Garzik92bab262005-05-31 20:43:57 -0400272 <sect2><title>Reset ATA bus</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700273 <programlisting>
274void (*phy_reset) (struct ata_port *ap);
275 </programlisting>
276
277 <para>
278 The very first step in the probe phase. Actions vary depending
279 on the bus type, typically. After waking up the device and probing
280 for device presence (PATA and SATA), typically a soft reset
281 (SRST) will be performed. Drivers typically use the helper
282 functions ata_bus_reset() or sata_phy_reset() for this hook.
Edward Falk8b2af8f2005-06-15 14:26:39 -0700283 Many SATA drivers use sata_phy_reset() or call it from within
284 their own phy_reset() functions.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700285 </para>
286
Jeff Garzik92bab262005-05-31 20:43:57 -0400287 </sect2>
288
289 <sect2><title>Control PCI IDE BMDMA engine</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700290 <programlisting>
291void (*bmdma_setup) (struct ata_queued_cmd *qc);
292void (*bmdma_start) (struct ata_queued_cmd *qc);
Jeff Garzik780a87f2005-05-30 15:41:05 -0400293void (*bmdma_stop) (struct ata_port *ap);
294u8 (*bmdma_status) (struct ata_port *ap);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700295 </programlisting>
296
297 <para>
Jeff Garzik780a87f2005-05-30 15:41:05 -0400298When setting up an IDE BMDMA transaction, these hooks arm
299(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop)
300the hardware's DMA engine. ->bmdma_status is used to read the standard
301PCI IDE DMA Status register.
302 </para>
303
304 <para>
305These hooks are typically either no-ops, or simply not implemented, in
306FIS-based drivers.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700307 </para>
Edward Falk8b2af8f2005-06-15 14:26:39 -0700308 <para>
309Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup()
310hook. ata_bmdma_setup() will write the pointer to the PRD table to
311the IDE PRD Table Address register, enable DMA in the DMA Command
312register, and call exec_command() to begin the transfer.
313 </para>
314 <para>
315Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start()
316hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA
317Command register.
318 </para>
319 <para>
320Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop()
321hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA
322command register.
323 </para>
324 <para>
325Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook.
326 </para>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700327
Jeff Garzik92bab262005-05-31 20:43:57 -0400328 </sect2>
329
330 <sect2><title>High-level taskfile hooks</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700331 <programlisting>
332void (*qc_prep) (struct ata_queued_cmd *qc);
333int (*qc_issue) (struct ata_queued_cmd *qc);
334 </programlisting>
335
336 <para>
337 Higher-level hooks, these two hooks can potentially supercede
338 several of the above taskfile/DMA engine hooks. ->qc_prep is
339 called after the buffers have been DMA-mapped, and is typically
340 used to populate the hardware's DMA scatter-gather table.
341 Most drivers use the standard ata_qc_prep() helper function, but
342 more advanced drivers roll their own.
343 </para>
344 <para>
345 ->qc_issue is used to make a command active, once the hardware
346 and S/G tables have been prepared. IDE BMDMA drivers use the
347 helper function ata_qc_issue_prot() for taskfile protocol-based
Jeff Garzik780a87f2005-05-30 15:41:05 -0400348 dispatch. More advanced drivers implement their own ->qc_issue.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700349 </para>
Edward Falk8b2af8f2005-06-15 14:26:39 -0700350 <para>
351 ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and
352 ->bmdma_start() as necessary to initiate a transfer.
353 </para>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700354
Jeff Garzik92bab262005-05-31 20:43:57 -0400355 </sect2>
356
357 <sect2><title>Timeout (error) handling</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700358 <programlisting>
359void (*eng_timeout) (struct ata_port *ap);
360 </programlisting>
361
362 <para>
Jeff Garzik780a87f2005-05-30 15:41:05 -0400363This is a high level error handling function, called from the
364error handling thread, when a command times out. Most newer
365hardware will implement its own error handling code here. IDE BMDMA
366drivers may use the helper function ata_eng_timeout().
Linus Torvalds1da177e2005-04-16 15:20:36 -0700367 </para>
368
Jeff Garzik92bab262005-05-31 20:43:57 -0400369 </sect2>
370
371 <sect2><title>Hardware interrupt handling</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700372 <programlisting>
373irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
374void (*irq_clear) (struct ata_port *);
375 </programlisting>
376
377 <para>
378 ->irq_handler is the interrupt handling routine registered with
379 the system, by libata. ->irq_clear is called during probe just
380 before the interrupt handler is registered, to be sure hardware
381 is quiet.
382 </para>
Edward Falk8b2af8f2005-06-15 14:26:39 -0700383 <para>
384 The second argument, dev_instance, should be cast to a pointer
385 to struct ata_host_set.
386 </para>
387 <para>
388 Most legacy IDE drivers use ata_interrupt() for the
389 irq_handler hook, which scans all ports in the host_set,
390 determines which queued command was active (if any), and calls
391 ata_host_intr(ap,qc).
392 </para>
393 <para>
394 Most legacy IDE drivers use ata_bmdma_irq_clear() for the
395 irq_clear() hook, which simply clears the interrupt and error
396 flags in the DMA status register.
397 </para>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700398
Jeff Garzik92bab262005-05-31 20:43:57 -0400399 </sect2>
400
401 <sect2><title>SATA phy read/write</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700402 <programlisting>
403u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
404void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
405 u32 val);
406 </programlisting>
407
408 <para>
409 Read and write standard SATA phy registers. Currently only used
410 if ->phy_reset hook called the sata_phy_reset() helper function.
Edward Falk8b2af8f2005-06-15 14:26:39 -0700411 sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700412 </para>
413
Jeff Garzik92bab262005-05-31 20:43:57 -0400414 </sect2>
415
416 <sect2><title>Init and shutdown</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700417 <programlisting>
418int (*port_start) (struct ata_port *ap);
419void (*port_stop) (struct ata_port *ap);
420void (*host_stop) (struct ata_host_set *host_set);
421 </programlisting>
422
423 <para>
424 ->port_start() is called just after the data structures for each
425 port are initialized. Typically this is used to alloc per-port
426 DMA buffers / tables / rings, enable DMA engines, and similar
Edward Falk8b2af8f2005-06-15 14:26:39 -0700427 tasks. Some drivers also use this entry point as a chance to
428 allocate driver-private memory for ap->private_data.
429 </para>
430 <para>
431 Many drivers use ata_port_start() as this hook or call
432 it from their own port_start() hooks. ata_port_start()
433 allocates space for a legacy IDE PRD table and returns.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700434 </para>
435 <para>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700436 ->port_stop() is called after ->host_stop(). It's sole function
437 is to release DMA/memory resources, now that they are no longer
Edward Falk8b2af8f2005-06-15 14:26:39 -0700438 actively being used. Many drivers also free driver-private
439 data from port at this time.
440 </para>
441 <para>
442 Many drivers use ata_port_stop() as this hook, which frees the
443 PRD table.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700444 </para>
Jeff Garzik780a87f2005-05-30 15:41:05 -0400445 <para>
446 ->host_stop() is called after all ->port_stop() calls
447have completed. The hook must finalize hardware shutdown, release DMA
448and other resources, etc.
Edward Falk8b2af8f2005-06-15 14:26:39 -0700449 This hook may be specified as NULL, in which case it is not called.
Jeff Garzik780a87f2005-05-30 15:41:05 -0400450 </para>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700451
Jeff Garzik92bab262005-05-31 20:43:57 -0400452 </sect2>
453
Linus Torvalds1da177e2005-04-16 15:20:36 -0700454 </sect1>
Jeff Garzika1213492005-09-28 13:26:47 -0400455 </chapter>
456
457 <chapter id="libataEH">
Tejun Heobfd00722005-09-26 11:28:47 +0900458 <title>Error handling</title>
459
460 <para>
461 This chapter describes how errors are handled under libata.
462 Readers are advised to read SCSI EH
463 (Documentation/scsi/scsi_eh.txt) and ATA exceptions doc first.
464 </para>
465
Jeff Garzika1213492005-09-28 13:26:47 -0400466 <sect1><title>Origins of commands</title>
Tejun Heobfd00722005-09-26 11:28:47 +0900467 <para>
468 In libata, a command is represented with struct ata_queued_cmd
469 or qc. qc's are preallocated during port initialization and
470 repetitively used for command executions. Currently only one
471 qc is allocated per port but yet-to-be-merged NCQ branch
472 allocates one for each tag and maps each qc to NCQ tag 1-to-1.
473 </para>
474 <para>
475 libata commands can originate from two sources - libata itself
476 and SCSI midlayer. libata internal commands are used for
477 initialization and error handling. All normal blk requests
478 and commands for SCSI emulation are passed as SCSI commands
479 through queuecommand callback of SCSI host template.
480 </para>
Jeff Garzika1213492005-09-28 13:26:47 -0400481 </sect1>
Tejun Heobfd00722005-09-26 11:28:47 +0900482
Jeff Garzika1213492005-09-28 13:26:47 -0400483 <sect1><title>How commands are issued</title>
Tejun Heobfd00722005-09-26 11:28:47 +0900484
485 <variablelist>
486
487 <varlistentry><term>Internal commands</term>
488 <listitem>
489 <para>
490 First, qc is allocated and initialized using
491 ata_qc_new_init(). Although ata_qc_new_init() doesn't
492 implement any wait or retry mechanism when qc is not
493 available, internal commands are currently issued only during
494 initialization and error recovery, so no other command is
495 active and allocation is guaranteed to succeed.
496 </para>
497 <para>
498 Once allocated qc's taskfile is initialized for the command to
499 be executed. qc currently has two mechanisms to notify
500 completion. One is via qc->complete_fn() callback and the
501 other is completion qc->waiting. qc->complete_fn() callback
502 is the asynchronous path used by normal SCSI translated
503 commands and qc->waiting is the synchronous (issuer sleeps in
504 process context) path used by internal commands.
505 </para>
506 <para>
507 Once initialization is complete, host_set lock is acquired
508 and the qc is issued.
509 </para>
510 </listitem>
511 </varlistentry>
512
513 <varlistentry><term>SCSI commands</term>
514 <listitem>
515 <para>
516 All libata drivers use ata_scsi_queuecmd() as
517 hostt->queuecommand callback. scmds can either be simulated
518 or translated. No qc is involved in processing a simulated
519 scmd. The result is computed right away and the scmd is
520 completed.
521 </para>
522 <para>
523 For a translated scmd, ata_qc_new_init() is invoked to
524 allocate a qc and the scmd is translated into the qc. SCSI
525 midlayer's completion notification function pointer is stored
526 into qc->scsidone.
527 </para>
528 <para>
529 qc->complete_fn() callback is used for completion
530 notification. ATA commands use ata_scsi_qc_complete() while
531 ATAPI commands use atapi_qc_complete(). Both functions end up
532 calling qc->scsidone to notify upper layer when the qc is
533 finished. After translation is completed, the qc is issued
534 with ata_qc_issue().
535 </para>
536 <para>
537 Note that SCSI midlayer invokes hostt->queuecommand while
538 holding host_set lock, so all above occur while holding
539 host_set lock.
540 </para>
541 </listitem>
542 </varlistentry>
543
544 </variablelist>
Jeff Garzika1213492005-09-28 13:26:47 -0400545 </sect1>
Tejun Heobfd00722005-09-26 11:28:47 +0900546
Jeff Garzika1213492005-09-28 13:26:47 -0400547 <sect1><title>How commands are processed</title>
Tejun Heobfd00722005-09-26 11:28:47 +0900548 <para>
549 Depending on which protocol and which controller are used,
550 commands are processed differently. For the purpose of
551 discussion, a controller which uses taskfile interface and all
552 standard callbacks is assumed.
553 </para>
554 <para>
555 Currently 6 ATA command protocols are used. They can be
556 sorted into the following four categories according to how
557 they are processed.
558 </para>
559
560 <variablelist>
561 <varlistentry><term>ATA NO DATA or DMA</term>
562 <listitem>
563 <para>
564 ATA_PROT_NODATA and ATA_PROT_DMA fall into this category.
565 These types of commands don't require any software
566 intervention once issued. Device will raise interrupt on
567 completion.
568 </para>
569 </listitem>
570 </varlistentry>
571
572 <varlistentry><term>ATA PIO</term>
573 <listitem>
574 <para>
575 ATA_PROT_PIO is in this category. libata currently
576 implements PIO with polling. ATA_NIEN bit is set to turn
577 off interrupt and pio_task on ata_wq performs polling and
578 IO.
579 </para>
580 </listitem>
581 </varlistentry>
582
583 <varlistentry><term>ATAPI NODATA or DMA</term>
584 <listitem>
585 <para>
586 ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this
587 category. packet_task is used to poll BSY bit after
588 issuing PACKET command. Once BSY is turned off by the
589 device, packet_task transfers CDB and hands off processing
590 to interrupt handler.
591 </para>
592 </listitem>
593 </varlistentry>
594
595 <varlistentry><term>ATAPI PIO</term>
596 <listitem>
597 <para>
598 ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set
599 and, as in ATAPI NODATA or DMA, packet_task submits cdb.
600 However, after submitting cdb, further processing (data
601 transfer) is handed off to pio_task.
602 </para>
603 </listitem>
604 </varlistentry>
605 </variablelist>
Jeff Garzika1213492005-09-28 13:26:47 -0400606 </sect1>
Tejun Heobfd00722005-09-26 11:28:47 +0900607
Jeff Garzika1213492005-09-28 13:26:47 -0400608 <sect1><title>How commands are completed</title>
Tejun Heobfd00722005-09-26 11:28:47 +0900609 <para>
610 Once issued, all qc's are either completed with
611 ata_qc_complete() or time out. For commands which are handled
612 by interrupts, ata_host_intr() invokes ata_qc_complete(), and,
613 for PIO tasks, pio_task invokes ata_qc_complete(). In error
614 cases, packet_task may also complete commands.
615 </para>
616 <para>
617 ata_qc_complete() does the following.
618 </para>
619
620 <orderedlist>
621
622 <listitem>
623 <para>
624 DMA memory is unmapped.
625 </para>
626 </listitem>
627
628 <listitem>
629 <para>
630 ATA_QCFLAG_ACTIVE is clared from qc->flags.
631 </para>
632 </listitem>
633
634 <listitem>
635 <para>
636 qc->complete_fn() callback is invoked. If the return value of
637 the callback is not zero. Completion is short circuited and
638 ata_qc_complete() returns.
639 </para>
640 </listitem>
641
642 <listitem>
643 <para>
644 __ata_qc_complete() is called, which does
645 <orderedlist>
646
647 <listitem>
648 <para>
649 qc->flags is cleared to zero.
650 </para>
651 </listitem>
652
653 <listitem>
654 <para>
655 ap->active_tag and qc->tag are poisoned.
656 </para>
657 </listitem>
658
659 <listitem>
660 <para>
661 qc->waiting is claread &amp; completed (in that order).
662 </para>
663 </listitem>
664
665 <listitem>
666 <para>
667 qc is deallocated by clearing appropriate bit in ap->qactive.
668 </para>
669 </listitem>
670
671 </orderedlist>
672 </para>
673 </listitem>
674
675 </orderedlist>
676
677 <para>
678 So, it basically notifies upper layer and deallocates qc. One
679 exception is short-circuit path in #3 which is used by
680 atapi_qc_complete().
681 </para>
682 <para>
683 For all non-ATAPI commands, whether it fails or not, almost
684 the same code path is taken and very little error handling
685 takes place. A qc is completed with success status if it
686 succeeded, with failed status otherwise.
687 </para>
688 <para>
689 However, failed ATAPI commands require more handling as
690 REQUEST SENSE is needed to acquire sense data. If an ATAPI
691 command fails, ata_qc_complete() is invoked with error status,
692 which in turn invokes atapi_qc_complete() via
693 qc->complete_fn() callback.
694 </para>
695 <para>
696 This makes atapi_qc_complete() set scmd->result to
697 SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As
698 the sense data is empty but scmd->result is CHECK CONDITION,
699 SCSI midlayer will invoke EH for the scmd, and returning 1
700 makes ata_qc_complete() to return without deallocating the qc.
701 This leads us to ata_scsi_error() with partially completed qc.
702 </para>
703
Jeff Garzika1213492005-09-28 13:26:47 -0400704 </sect1>
Tejun Heobfd00722005-09-26 11:28:47 +0900705
Jeff Garzika1213492005-09-28 13:26:47 -0400706 <sect1><title>ata_scsi_error()</title>
Tejun Heobfd00722005-09-26 11:28:47 +0900707 <para>
708 ata_scsi_error() is the current hostt->eh_strategy_handler()
709 for libata. As discussed above, this will be entered in two
710 cases - timeout and ATAPI error completion. This function
711 calls low level libata driver's eng_timeout() callback, the
712 standard callback for which is ata_eng_timeout(). It checks
713 if a qc is active and calls ata_qc_timeout() on the qc if so.
714 Actual error handling occurs in ata_qc_timeout().
715 </para>
716 <para>
717 If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and
718 completes the qc. Note that as we're currently in EH, we
719 cannot call scsi_done. As described in SCSI EH doc, a
720 recovered scmd should be either retried with
721 scsi_queue_insert() or finished with scsi_finish_command().
722 Here, we override qc->scsidone with scsi_finish_command() and
723 calls ata_qc_complete().
724 </para>
725 <para>
726 If EH is invoked due to a failed ATAPI qc, the qc here is
727 completed but not deallocated. The purpose of this
728 half-completion is to use the qc as place holder to make EH
729 code reach this place. This is a bit hackish, but it works.
730 </para>
731 <para>
732 Once control reaches here, the qc is deallocated by invoking
733 __ata_qc_complete() explicitly. Then, internal qc for REQUEST
734 SENSE is issued. Once sense data is acquired, scmd is
735 finished by directly invoking scsi_finish_command() on the
736 scmd. Note that as we already have completed and deallocated
737 the qc which was associated with the scmd, we don't need
738 to/cannot call ata_qc_complete() again.
739 </para>
740
Jeff Garzika1213492005-09-28 13:26:47 -0400741 </sect1>
Tejun Heobfd00722005-09-26 11:28:47 +0900742
Jeff Garzika1213492005-09-28 13:26:47 -0400743 <sect1><title>Problems with the current EH</title>
Tejun Heobfd00722005-09-26 11:28:47 +0900744
745 <itemizedlist>
746
747 <listitem>
748 <para>
749 Error representation is too crude. Currently any and all
750 error conditions are represented with ATA STATUS and ERROR
751 registers. Errors which aren't ATA device errors are treated
752 as ATA device errors by setting ATA_ERR bit. Better error
753 descriptor which can properly represent ATA and other
754 errors/exceptions is needed.
755 </para>
756 </listitem>
757
758 <listitem>
759 <para>
760 When handling timeouts, no action is taken to make device
761 forget about the timed out command and ready for new commands.
762 </para>
763 </listitem>
764
765 <listitem>
766 <para>
767 EH handling via ata_scsi_error() is not properly protected
768 from usual command processing. On EH entrance, the device is
769 not in quiescent state. Timed out commands may succeed or
770 fail any time. pio_task and atapi_task may still be running.
771 </para>
772 </listitem>
773
774 <listitem>
775 <para>
776 Too weak error recovery. Devices / controllers causing HSM
777 mismatch errors and other errors quite often require reset to
778 return to known state. Also, advanced error handling is
779 necessary to support features like NCQ and hotplug.
780 </para>
781 </listitem>
782
783 <listitem>
784 <para>
785 ATA errors are directly handled in the interrupt handler and
786 PIO errors in pio_task. This is problematic for advanced
787 error handling for the following reasons.
788 </para>
789 <para>
790 First, advanced error handling often requires context and
791 internal qc execution.
792 </para>
793 <para>
794 Second, even a simple failure (say, CRC error) needs
795 information gathering and could trigger complex error handling
796 (say, resetting &amp; reconfiguring). Having multiple code
797 paths to gather information, enter EH and trigger actions
798 makes life painful.
799 </para>
800 <para>
801 Third, scattered EH code makes implementing low level drivers
802 difficult. Low level drivers override libata callbacks. If
803 EH is scattered over several places, each affected callbacks
804 should perform its part of error handling. This can be error
805 prone and painful.
806 </para>
807 </listitem>
808
809 </itemizedlist>
Jeff Garzika1213492005-09-28 13:26:47 -0400810 </sect1>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700811 </chapter>
812
813 <chapter id="libataExt">
814 <title>libata Library</title>
815!Edrivers/scsi/libata-core.c
816 </chapter>
817
818 <chapter id="libataInt">
819 <title>libata Core Internals</title>
820!Idrivers/scsi/libata-core.c
821 </chapter>
822
823 <chapter id="libataScsiInt">
824 <title>libata SCSI translation/emulation</title>
825!Edrivers/scsi/libata-scsi.c
826!Idrivers/scsi/libata-scsi.c
827 </chapter>
828
Tejun Heofe998aa2005-10-02 11:54:29 +0900829 <chapter id="ataExceptions">
830 <title>ATA errors &amp; exceptions</title>
831
832 <para>
833 This chapter tries to identify what error/exception conditions exist
834 for ATA/ATAPI devices and describe how they should be handled in
835 implementation-neutral way.
836 </para>
837
838 <para>
839 The term 'error' is used to describe conditions where either an
840 explicit error condition is reported from device or a command has
841 timed out.
842 </para>
843
844 <para>
845 The term 'exception' is either used to describe exceptional
846 conditions which are not errors (say, power or hotplug events), or
847 to describe both errors and non-error exceptional conditions. Where
848 explicit distinction between error and exception is necessary, the
849 term 'non-error exception' is used.
850 </para>
851
852 <sect1 id="excat">
853 <title>Exception categories</title>
854 <para>
855 Exceptions are described primarily with respect to legacy
856 taskfile + bus master IDE interface. If a controller provides
857 other better mechanism for error reporting, mapping those into
858 categories described below shouldn't be difficult.
859 </para>
860
861 <para>
862 In the following sections, two recovery actions - reset and
863 reconfiguring transport - are mentioned. These are described
864 further in <xref linkend="exrec"/>.
865 </para>
866
867 <sect2 id="excatHSMviolation">
868 <title>HSM violation</title>
869 <para>
870 This error is indicated when STATUS value doesn't match HSM
871 requirement during issuing or excution any ATA/ATAPI command.
872 </para>
873
874 <itemizedlist>
875 <title>Examples</title>
876
877 <listitem>
878 <para>
879 ATA_STATUS doesn't contain !BSY &amp;&amp; DRDY &amp;&amp; !DRQ while trying
880 to issue a command.
881 </para>
882 </listitem>
883
884 <listitem>
885 <para>
886 !BSY &amp;&amp; !DRQ during PIO data transfer.
887 </para>
888 </listitem>
889
890 <listitem>
891 <para>
892 DRQ on command completion.
893 </para>
894 </listitem>
895
896 <listitem>
897 <para>
898 !BSY &amp;&amp; ERR after CDB tranfer starts but before the
899 last byte of CDB is transferred. ATA/ATAPI standard states
900 that &quot;The device shall not terminate the PACKET command
901 with an error before the last byte of the command packet has
902 been written&quot; in the error outputs description of PACKET
903 command and the state diagram doesn't include such
904 transitions.
905 </para>
906 </listitem>
907
908 </itemizedlist>
909
910 <para>
911 In these cases, HSM is violated and not much information
912 regarding the error can be acquired from STATUS or ERROR
913 register. IOW, this error can be anything - driver bug,
914 faulty device, controller and/or cable.
915 </para>
916
917 <para>
918 As HSM is violated, reset is necessary to restore known state.
919 Reconfiguring transport for lower speed might be helpful too
920 as transmission errors sometimes cause this kind of errors.
921 </para>
922 </sect2>
923
924 <sect2 id="excatDevErr">
925 <title>ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)</title>
926
927 <para>
928 These are errors detected and reported by ATA/ATAPI devices
929 indicating device problems. For this type of errors, STATUS
930 and ERROR register values are valid and describe error
931 condition. Note that some of ATA bus errors are detected by
932 ATA/ATAPI devices and reported using the same mechanism as
933 device errors. Those cases are described later in this
934 section.
935 </para>
936
937 <para>
938 For ATA commands, this type of errors are indicated by !BSY
939 &amp;&amp; ERR during command execution and on completion.
940 </para>
941
942 <para>For ATAPI commands,</para>
943
944 <itemizedlist>
945
946 <listitem>
947 <para>
948 !BSY &amp;&amp; ERR &amp;&amp; ABRT right after issuing PACKET
949 indicates that PACKET command is not supported and falls in
950 this category.
951 </para>
952 </listitem>
953
954 <listitem>
955 <para>
956 !BSY &amp;&amp; ERR(==CHK) &amp;&amp; !ABRT after the last
957 byte of CDB is transferred indicates CHECK CONDITION and
958 doesn't fall in this category.
959 </para>
960 </listitem>
961
962 <listitem>
963 <para>
964 !BSY &amp;&amp; ERR(==CHK) &amp;&amp; ABRT after the last byte
965 of CDB is transferred *probably* indicates CHECK CONDITION and
966 doesn't fall in this category.
967 </para>
968 </listitem>
969
970 </itemizedlist>
971
972 <para>
973 Of errors detected as above, the followings are not ATA/ATAPI
974 device errors but ATA bus errors and should be handled
975 according to <xref linkend="excatATAbusErr"/>.
976 </para>
977
978 <variablelist>
979
980 <varlistentry>
981 <term>CRC error during data transfer</term>
982 <listitem>
983 <para>
984 This is indicated by ICRC bit in the ERROR register and
985 means that corruption occurred during data transfer. Upto
986 ATA/ATAPI-7, the standard specifies that this bit is only
987 applicable to UDMA transfers but ATA/ATAPI-8 draft revision
988 1f says that the bit may be applicable to multiword DMA and
989 PIO.
990 </para>
991 </listitem>
992 </varlistentry>
993
994 <varlistentry>
995 <term>ABRT error during data transfer or on completion</term>
996 <listitem>
997 <para>
998 Upto ATA/ATAPI-7, the standard specifies that ABRT could be
999 set on ICRC errors and on cases where a device is not able
1000 to complete a command. Combined with the fact that MWDMA
1001 and PIO transfer errors aren't allowed to use ICRC bit upto
1002 ATA/ATAPI-7, it seems to imply that ABRT bit alone could
1003 indicate tranfer errors.
1004 </para>
1005 <para>
1006 However, ATA/ATAPI-8 draft revision 1f removes the part
1007 that ICRC errors can turn on ABRT. So, this is kind of
1008 gray area. Some heuristics are needed here.
1009 </para>
1010 </listitem>
1011 </varlistentry>
1012
1013 </variablelist>
1014
1015 <para>
1016 ATA/ATAPI device errors can be further categorized as follows.
1017 </para>
1018
1019 <variablelist>
1020
1021 <varlistentry>
1022 <term>Media errors</term>
1023 <listitem>
1024 <para>
1025 This is indicated by UNC bit in the ERROR register. ATA
1026 devices reports UNC error only after certain number of
1027 retries cannot recover the data, so there's nothing much
1028 else to do other than notifying upper layer.
1029 </para>
1030 <para>
1031 READ and WRITE commands report CHS or LBA of the first
1032 failed sector but ATA/ATAPI standard specifies that the
1033 amount of transferred data on error completion is
1034 indeterminate, so we cannot assume that sectors preceding
1035 the failed sector have been transferred and thus cannot
1036 complete those sectors successfully as SCSI does.
1037 </para>
1038 </listitem>
1039 </varlistentry>
1040
1041 <varlistentry>
1042 <term>Media changed / media change requested error</term>
1043 <listitem>
1044 <para>
1045 &lt;&lt;TODO: fill here&gt;&gt;
1046 </para>
1047 </listitem>
1048 </varlistentry>
1049
1050 <varlistentry><term>Address error</term>
1051 <listitem>
1052 <para>
1053 This is indicated by IDNF bit in the ERROR register.
1054 Report to upper layer.
1055 </para>
1056 </listitem>
1057 </varlistentry>
1058
1059 <varlistentry><term>Other errors</term>
1060 <listitem>
1061 <para>
1062 This can be invalid command or parameter indicated by ABRT
1063 ERROR bit or some other error condition. Note that ABRT
1064 bit can indicate a lot of things including ICRC and Address
1065 errors. Heuristics needed.
1066 </para>
1067 </listitem>
1068 </varlistentry>
1069
1070 </variablelist>
1071
1072 <para>
1073 Depending on commands, not all STATUS/ERROR bits are
1074 applicable. These non-applicable bits are marked with
1075 &quot;na&quot; in the output descriptions but upto ATA/ATAPI-7
1076 no definition of &quot;na&quot; can be found. However,
1077 ATA/ATAPI-8 draft revision 1f describes &quot;N/A&quot; as
1078 follows.
1079 </para>
1080
1081 <blockquote>
1082 <variablelist>
1083 <varlistentry><term>3.2.3.3a N/A</term>
1084 <listitem>
1085 <para>
1086 A keyword the indicates a field has no defined value in
1087 this standard and should not be checked by the host or
1088 device. N/A fields should be cleared to zero.
1089 </para>
1090 </listitem>
1091 </varlistentry>
1092 </variablelist>
1093 </blockquote>
1094
1095 <para>
1096 So, it seems reasonable to assume that &quot;na&quot; bits are
1097 cleared to zero by devices and thus need no explicit masking.
1098 </para>
1099
1100 </sect2>
1101
1102 <sect2 id="excatATAPIcc">
1103 <title>ATAPI device CHECK CONDITION</title>
1104
1105 <para>
1106 ATAPI device CHECK CONDITION error is indicated by set CHK bit
1107 (ERR bit) in the STATUS register after the last byte of CDB is
1108 transferred for a PACKET command. For this kind of errors,
1109 sense data should be acquired to gather information regarding
1110 the errors. REQUEST SENSE packet command should be used to
1111 acquire sense data.
1112 </para>
1113
1114 <para>
1115 Once sense data is acquired, this type of errors can be
1116 handled similary to other SCSI errors. Note that sense data
1117 may indicate ATA bus error (e.g. Sense Key 04h HARDWARE ERROR
1118 &amp;&amp; ASC/ASCQ 47h/00h SCSI PARITY ERROR). In such
1119 cases, the error should be considered as an ATA bus error and
1120 handled according to <xref linkend="excatATAbusErr"/>.
1121 </para>
1122
1123 </sect2>
1124
1125 <sect2 id="excatNCQerr">
1126 <title>ATA device error (NCQ)</title>
1127
1128 <para>
1129 NCQ command error is indicated by cleared BSY and set ERR bit
1130 during NCQ command phase (one or more NCQ commands
1131 outstanding). Although STATUS and ERROR registers will
1132 contain valid values describing the error, READ LOG EXT is
1133 required to clear the error condition, determine which command
1134 has failed and acquire more information.
1135 </para>
1136
1137 <para>
1138 READ LOG EXT Log Page 10h reports which tag has failed and
1139 taskfile register values describing the error. With this
1140 information the failed command can be handled as a normal ATA
1141 command error as in <xref linkend="excatDevErr"/> and all
1142 other in-flight commands must be retried. Note that this
1143 retry should not be counted - it's likely that commands
1144 retried this way would have completed normally if it were not
1145 for the failed command.
1146 </para>
1147
1148 <para>
1149 Note that ATA bus errors can be reported as ATA device NCQ
1150 errors. This should be handled as described in <xref
1151 linkend="excatATAbusErr"/>.
1152 </para>
1153
1154 <para>
1155 If READ LOG EXT Log Page 10h fails or reports NQ, we're
1156 thoroughly screwed. This condition should be treated
1157 according to <xref linkend="excatHSMviolation"/>.
1158 </para>
1159
1160 </sect2>
1161
1162 <sect2 id="excatATAbusErr">
1163 <title>ATA bus error</title>
1164
1165 <para>
1166 ATA bus error means that data corruption occurred during
1167 transmission over ATA bus (SATA or PATA). This type of errors
1168 can be indicated by
1169 </para>
1170
1171 <itemizedlist>
1172
1173 <listitem>
1174 <para>
1175 ICRC or ABRT error as described in <xref linkend="excatDevErr"/>.
1176 </para>
1177 </listitem>
1178
1179 <listitem>
1180 <para>
1181 Controller-specific error completion with error information
1182 indicating transmission error.
1183 </para>
1184 </listitem>
1185
1186 <listitem>
1187 <para>
1188 On some controllers, command timeout. In this case, there may
1189 be a mechanism to determine that the timeout is due to
1190 transmission error.
1191 </para>
1192 </listitem>
1193
1194 <listitem>
1195 <para>
1196 Unknown/random errors, timeouts and all sorts of weirdities.
1197 </para>
1198 </listitem>
1199
1200 </itemizedlist>
1201
1202 <para>
1203 As described above, transmission errors can cause wide variety
1204 of symptoms ranging from device ICRC error to random device
1205 lockup, and, for many cases, there is no way to tell if an
1206 error condition is due to transmission error or not;
1207 therefore, it's necessary to employ some kind of heuristic
1208 when dealing with errors and timeouts. For example,
1209 encountering repetitive ABRT errors for known supported
1210 command is likely to indicate ATA bus error.
1211 </para>
1212
1213 <para>
1214 Once it's determined that ATA bus errors have possibly
1215 occurred, lowering ATA bus transmission speed is one of
1216 actions which may alleviate the problem. See <xref
1217 linkend="exrecReconf"/> for more information.
1218 </para>
1219
1220 </sect2>
1221
1222 <sect2 id="excatPCIbusErr">
1223 <title>PCI bus error</title>
1224
1225 <para>
1226 Data corruption or other failures during transmission over PCI
1227 (or other system bus). For standard BMDMA, this is indicated
1228 by Error bit in the BMDMA Status register. This type of
1229 errors must be logged as it indicates something is very wrong
1230 with the system. Resetting host controller is recommended.
1231 </para>
1232
1233 </sect2>
1234
1235 <sect2 id="excatLateCompletion">
1236 <title>Late completion</title>
1237
1238 <para>
1239 This occurs when timeout occurs and the timeout handler finds
1240 out that the timed out command has completed successfully or
1241 with error. This is usually caused by lost interrupts. This
1242 type of errors must be logged. Resetting host controller is
1243 recommended.
1244 </para>
1245
1246 </sect2>
1247
1248 <sect2 id="excatUnknown">
1249 <title>Unknown error (timeout)</title>
1250
1251 <para>
1252 This is when timeout occurs and the command is still
1253 processing or the host and device are in unknown state. When
1254 this occurs, HSM could be in any valid or invalid state. To
1255 bring the device to known state and make it forget about the
1256 timed out command, resetting is necessary. The timed out
1257 command may be retried.
1258 </para>
1259
1260 <para>
1261 Timeouts can also be caused by transmission errors. Refer to
1262 <xref linkend="excatATAbusErr"/> for more details.
1263 </para>
1264
1265 </sect2>
1266
1267 <sect2 id="excatHoplugPM">
1268 <title>Hotplug and power management exceptions</title>
1269
1270 <para>
1271 &lt;&lt;TODO: fill here&gt;&gt;
1272 </para>
1273
1274 </sect2>
1275
1276 </sect1>
1277
1278 <sect1 id="exrec">
1279 <title>EH recovery actions</title>
1280
1281 <para>
1282 This section discusses several important recovery actions.
1283 </para>
1284
1285 <sect2 id="exrecClr">
1286 <title>Clearing error condition</title>
1287
1288 <para>
1289 Many controllers require its error registers to be cleared by
1290 error handler. Different controllers may have different
1291 requirements.
1292 </para>
1293
1294 <para>
1295 For SATA, it's strongly recommended to clear at least SError
1296 register during error handling.
1297 </para>
1298 </sect2>
1299
1300 <sect2 id="exrecRst">
1301 <title>Reset</title>
1302
1303 <para>
1304 During EH, resetting is necessary in the following cases.
1305 </para>
1306
1307 <itemizedlist>
1308
1309 <listitem>
1310 <para>
1311 HSM is in unknown or invalid state
1312 </para>
1313 </listitem>
1314
1315 <listitem>
1316 <para>
1317 HBA is in unknown or invalid state
1318 </para>
1319 </listitem>
1320
1321 <listitem>
1322 <para>
1323 EH needs to make HBA/device forget about in-flight commands
1324 </para>
1325 </listitem>
1326
1327 <listitem>
1328 <para>
1329 HBA/device behaves weirdly
1330 </para>
1331 </listitem>
1332
1333 </itemizedlist>
1334
1335 <para>
1336 Resetting during EH might be a good idea regardless of error
1337 condition to improve EH robustness. Whether to reset both or
1338 either one of HBA and device depends on situation but the
1339 following scheme is recommended.
1340 </para>
1341
1342 <itemizedlist>
1343
1344 <listitem>
1345 <para>
1346 When it's known that HBA is in ready state but ATA/ATAPI
1347 device in in unknown state, reset only device.
1348 </para>
1349 </listitem>
1350
1351 <listitem>
1352 <para>
1353 If HBA is in unknown state, reset both HBA and device.
1354 </para>
1355 </listitem>
1356
1357 </itemizedlist>
1358
1359 <para>
1360 HBA resetting is implementation specific. For a controller
1361 complying to taskfile/BMDMA PCI IDE, stopping active DMA
1362 transaction may be sufficient iff BMDMA state is the only HBA
1363 context. But even mostly taskfile/BMDMA PCI IDE complying
1364 controllers may have implementation specific requirements and
1365 mechanism to reset themselves. This must be addressed by
1366 specific drivers.
1367 </para>
1368
1369 <para>
1370 OTOH, ATA/ATAPI standard describes in detail ways to reset
1371 ATA/ATAPI devices.
1372 </para>
1373
1374 <variablelist>
1375
1376 <varlistentry><term>PATA hardware reset</term>
1377 <listitem>
1378 <para>
1379 This is hardware initiated device reset signalled with
1380 asserted PATA RESET- signal. There is no standard way to
1381 initiate hardware reset from software although some
1382 hardware provides registers that allow driver to directly
1383 tweak the RESET- signal.
1384 </para>
1385 </listitem>
1386 </varlistentry>
1387
1388 <varlistentry><term>Software reset</term>
1389 <listitem>
1390 <para>
1391 This is achieved by turning CONTROL SRST bit on for at
1392 least 5us. Both PATA and SATA support it but, in case of
1393 SATA, this may require controller-specific support as the
1394 second Register FIS to clear SRST should be transmitted
1395 while BSY bit is still set. Note that on PATA, this resets
1396 both master and slave devices on a channel.
1397 </para>
1398 </listitem>
1399 </varlistentry>
1400
1401 <varlistentry><term>EXECUTE DEVICE DIAGNOSTIC command</term>
1402 <listitem>
1403 <para>
1404 Although ATA/ATAPI standard doesn't describe exactly, EDD
1405 implies some level of resetting, possibly similar level
1406 with software reset. Host-side EDD protocol can be handled
1407 with normal command processing and most SATA controllers
1408 should be able to handle EDD's just like other commands.
1409 As in software reset, EDD affects both devices on a PATA
1410 bus.
1411 </para>
1412 <para>
1413 Although EDD does reset devices, this doesn't suit error
1414 handling as EDD cannot be issued while BSY is set and it's
1415 unclear how it will act when device is in unknown/weird
1416 state.
1417 </para>
1418 </listitem>
1419 </varlistentry>
1420
1421 <varlistentry><term>ATAPI DEVICE RESET command</term>
1422 <listitem>
1423 <para>
1424 This is very similar to software reset except that reset
1425 can be restricted to the selected device without affecting
1426 the other device sharing the cable.
1427 </para>
1428 </listitem>
1429 </varlistentry>
1430
1431 <varlistentry><term>SATA phy reset</term>
1432 <listitem>
1433 <para>
1434 This is the preferred way of resetting a SATA device. In
1435 effect, it's identical to PATA hardware reset. Note that
1436 this can be done with the standard SCR Control register.
1437 As such, it's usually easier to implement than software
1438 reset.
1439 </para>
1440 </listitem>
1441 </varlistentry>
1442
1443 </variablelist>
1444
1445 <para>
1446 One more thing to consider when resetting devices is that
1447 resetting clears certain configuration parameters and they
1448 need to be set to their previous or newly adjusted values
1449 after reset.
1450 </para>
1451
1452 <para>
1453 Parameters affected are.
1454 </para>
1455
1456 <itemizedlist>
1457
1458 <listitem>
1459 <para>
1460 CHS set up with INITIALIZE DEVICE PARAMETERS (seldomly used)
1461 </para>
1462 </listitem>
1463
1464 <listitem>
1465 <para>
1466 Parameters set with SET FEATURES including transfer mode setting
1467 </para>
1468 </listitem>
1469
1470 <listitem>
1471 <para>
1472 Block count set with SET MULTIPLE MODE
1473 </para>
1474 </listitem>
1475
1476 <listitem>
1477 <para>
1478 Other parameters (SET MAX, MEDIA LOCK...)
1479 </para>
1480 </listitem>
1481
1482 </itemizedlist>
1483
1484 <para>
1485 ATA/ATAPI standard specifies that some parameters must be
1486 maintained across hardware or software reset, but doesn't
1487 strictly specify all of them. Always reconfiguring needed
1488 parameters after reset is required for robustness. Note that
1489 this also applies when resuming from deep sleep (power-off).
1490 </para>
1491
1492 <para>
1493 Also, ATA/ATAPI standard requires that IDENTIFY DEVICE /
1494 IDENTIFY PACKET DEVICE is issued after any configuration
1495 parameter is updated or a hardware reset and the result used
1496 for further operation. OS driver is required to implement
1497 revalidation mechanism to support this.
1498 </para>
1499
1500 </sect2>
1501
1502 <sect2 id="exrecReconf">
1503 <title>Reconfigure transport</title>
1504
1505 <para>
1506 For both PATA and SATA, a lot of corners are cut for cheap
1507 connectors, cables or controllers and it's quite common to see
1508 high transmission error rate. This can be mitigated by
1509 lowering transmission speed.
1510 </para>
1511
1512 <para>
1513 The following is a possible scheme Jeff Garzik suggested.
1514 </para>
1515
1516 <blockquote>
1517 <para>
1518 If more than $N (3?) transmission errors happen in 15 minutes,
1519 </para>
1520 <itemizedlist>
1521 <listitem>
1522 <para>
1523 if SATA, decrease SATA PHY speed. if speed cannot be decreased,
1524 </para>
1525 </listitem>
1526 <listitem>
1527 <para>
1528 decrease UDMA xfer speed. if at UDMA0, switch to PIO4,
1529 </para>
1530 </listitem>
1531 <listitem>
1532 <para>
1533 decrease PIO xfer speed. if at PIO3, complain, but continue
1534 </para>
1535 </listitem>
1536 </itemizedlist>
1537 </blockquote>
1538
1539 </sect2>
1540
1541 </sect1>
1542
1543 </chapter>
1544
Linus Torvalds1da177e2005-04-16 15:20:36 -07001545 <chapter id="PiixInt">
1546 <title>ata_piix Internals</title>
1547!Idrivers/scsi/ata_piix.c
1548 </chapter>
1549
1550 <chapter id="SILInt">
1551 <title>sata_sil Internals</title>
1552!Idrivers/scsi/sata_sil.c
1553 </chapter>
1554
Jeff Garzik0cba6322005-05-30 19:49:12 -04001555 <chapter id="libataThanks">
1556 <title>Thanks</title>
1557 <para>
1558 The bulk of the ATA knowledge comes thanks to long conversations with
1559 Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA
1560 and SCSI specifications.
1561 </para>
1562 <para>
1563 Thanks to Alan Cox for pointing out similarities
1564 between SATA and SCSI, and in general for motivation to hack on
1565 libata.
1566 </para>
1567 <para>
1568 libata's device detection
1569 method, ata_pio_devchk, and in general all the early probing was
1570 based on extensive study of Hale Landis's probe/reset code in his
1571 ATADRVR driver (www.ata-atapi.com).
1572 </para>
1573 </chapter>
1574
Linus Torvalds1da177e2005-04-16 15:20:36 -07001575</book>