]>
Commit | Line | Data |
---|---|---|
0ec88413 MCC |
1 | ======================== |
2 | libATA Developer's Guide | |
3 | ======================== | |
4 | ||
5 | :Author: Jeff Garzik | |
6 | ||
7 | Introduction | |
8 | ============ | |
9 | ||
10 | libATA is a library used inside the Linux kernel to support ATA host | |
11 | controllers and devices. libATA provides an ATA driver API, class | |
12 | transports for ATA and ATAPI devices, and SCSI<->ATA translation for ATA | |
13 | devices according to the T10 SAT specification. | |
14 | ||
15 | This Guide documents the libATA driver API, library functions, library | |
16 | internals, and a couple sample ATA low-level drivers. | |
17 | ||
18 | libata Driver API | |
19 | ================= | |
20 | ||
6b46c2b1 MCC |
21 | :c:type:`struct ata_port_operations <ata_port_operations>` |
22 | is defined for every low-level libata | |
0ec88413 MCC |
23 | hardware driver, and it controls how the low-level driver interfaces |
24 | with the ATA and SCSI layers. | |
25 | ||
6b46c2b1 MCC |
26 | FIS-based drivers will hook into the system with ``->qc_prep()`` and |
27 | ``->qc_issue()`` high-level hooks. Hardware which behaves in a manner | |
0ec88413 MCC |
28 | similar to PCI IDE hardware may utilize several generic helpers, |
29 | defining at a bare minimum the bus I/O addresses of the ATA shadow | |
30 | register blocks. | |
31 | ||
6b46c2b1 MCC |
32 | :c:type:`struct ata_port_operations <ata_port_operations>` |
33 | ---------------------------------------------------------- | |
0ec88413 MCC |
34 | |
35 | Disable ATA port | |
36 | ~~~~~~~~~~~~~~~~ | |
37 | ||
38 | :: | |
39 | ||
40 | void (*port_disable) (struct ata_port *); | |
41 | ||
42 | ||
6b46c2b1 | 43 | Called from :c:func:`ata_bus_probe` error path, as well as when unregistering |
0ec88413 MCC |
44 | from the SCSI module (rmmod, hot unplug). This function should do |
45 | whatever needs to be done to take the port out of use. In most cases, | |
6b46c2b1 | 46 | :c:func:`ata_port_disable` can be used as this hook. |
0ec88413 | 47 | |
6b46c2b1 MCC |
48 | Called from :c:func:`ata_bus_probe` on a failed probe. Called from |
49 | :c:func:`ata_scsi_release`. | |
0ec88413 MCC |
50 | |
51 | Post-IDENTIFY device configuration | |
52 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
53 | ||
54 | :: | |
55 | ||
56 | void (*dev_config) (struct ata_port *, struct ata_device *); | |
57 | ||
58 | ||
59 | Called after IDENTIFY [PACKET] DEVICE is issued to each device found. | |
60 | Typically used to apply device-specific fixups prior to issue of SET | |
61 | FEATURES - XFER MODE, and prior to operation. | |
62 | ||
63 | This entry may be specified as NULL in ata_port_operations. | |
64 | ||
65 | Set PIO/DMA mode | |
66 | ~~~~~~~~~~~~~~~~ | |
67 | ||
68 | :: | |
69 | ||
70 | void (*set_piomode) (struct ata_port *, struct ata_device *); | |
71 | void (*set_dmamode) (struct ata_port *, struct ata_device *); | |
72 | void (*post_set_mode) (struct ata_port *); | |
73 | unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int); | |
74 | ||
75 | ||
76 | Hooks called prior to the issue of SET FEATURES - XFER MODE command. The | |
6b46c2b1 MCC |
77 | optional ``->mode_filter()`` hook is called when libata has built a mask of |
78 | the possible modes. This is passed to the ``->mode_filter()`` function | |
0ec88413 MCC |
79 | which should return a mask of valid modes after filtering those |
80 | unsuitable due to hardware limits. It is not valid to use this interface | |
81 | to add modes. | |
82 | ||
6b46c2b1 MCC |
83 | ``dev->pio_mode`` and ``dev->dma_mode`` are guaranteed to be valid when |
84 | ``->set_piomode()`` and when ``->set_dmamode()`` is called. The timings for | |
0ec88413 MCC |
85 | any other drive sharing the cable will also be valid at this point. That |
86 | is the library records the decisions for the modes of each drive on a | |
87 | channel before it attempts to set any of them. | |
88 | ||
6b46c2b1 | 89 | ``->post_set_mode()`` is called unconditionally, after the SET FEATURES - |
0ec88413 MCC |
90 | XFER MODE command completes successfully. |
91 | ||
6b46c2b1 | 92 | ``->set_piomode()`` is always called (if present), but ``->set_dma_mode()`` |
0ec88413 MCC |
93 | is only called if DMA is possible. |
94 | ||
95 | Taskfile read/write | |
96 | ~~~~~~~~~~~~~~~~~~~ | |
97 | ||
98 | :: | |
99 | ||
100 | void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf); | |
101 | void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf); | |
102 | ||
103 | ||
6b46c2b1 MCC |
104 | ``->tf_load()`` is called to load the given taskfile into hardware |
105 | registers / DMA buffers. ``->tf_read()`` is called to read the hardware | |
0ec88413 MCC |
106 | registers / DMA buffers, to obtain the current set of taskfile register |
107 | values. Most drivers for taskfile-based hardware (PIO or MMIO) use | |
6b46c2b1 | 108 | :c:func:`ata_sff_tf_load` and :c:func:`ata_sff_tf_read` for these hooks. |
0ec88413 MCC |
109 | |
110 | PIO data read/write | |
111 | ~~~~~~~~~~~~~~~~~~~ | |
112 | ||
113 | :: | |
114 | ||
115 | void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int); | |
116 | ||
117 | ||
118 | All bmdma-style drivers must implement this hook. This is the low-level | |
119 | operation that actually copies the data bytes during a PIO data | |
120 | transfer. Typically the driver will choose one of | |
6b46c2b1 MCC |
121 | :c:func:`ata_sff_data_xfer_noirq`, :c:func:`ata_sff_data_xfer`, or |
122 | :c:func:`ata_sff_data_xfer32`. | |
0ec88413 MCC |
123 | |
124 | ATA command execute | |
125 | ~~~~~~~~~~~~~~~~~~~ | |
126 | ||
127 | :: | |
128 | ||
129 | void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf); | |
130 | ||
131 | ||
6b46c2b1 | 132 | causes an ATA command, previously loaded with ``->tf_load()``, to be |
0ec88413 | 133 | initiated in hardware. Most drivers for taskfile-based hardware use |
6b46c2b1 | 134 | :c:func:`ata_sff_exec_command` for this hook. |
0ec88413 MCC |
135 | |
136 | Per-cmd ATAPI DMA capabilities filter | |
137 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
138 | ||
139 | :: | |
140 | ||
141 | int (*check_atapi_dma) (struct ata_queued_cmd *qc); | |
142 | ||
143 | ||
144 | Allow low-level driver to filter ATA PACKET commands, returning a status | |
145 | indicating whether or not it is OK to use DMA for the supplied PACKET | |
146 | command. | |
147 | ||
148 | This hook may be specified as NULL, in which case libata will assume | |
149 | that atapi dma can be supported. | |
150 | ||
151 | Read specific ATA shadow registers | |
152 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
153 | ||
154 | :: | |
155 | ||
156 | u8 (*sff_check_status)(struct ata_port *ap); | |
157 | u8 (*sff_check_altstatus)(struct ata_port *ap); | |
158 | ||
159 | ||
160 | Reads the Status/AltStatus ATA shadow register from hardware. On some | |
161 | hardware, reading the Status register has the side effect of clearing | |
162 | the interrupt condition. Most drivers for taskfile-based hardware use | |
6b46c2b1 | 163 | :c:func:`ata_sff_check_status` for this hook. |
0ec88413 MCC |
164 | |
165 | Write specific ATA shadow register | |
166 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
167 | ||
168 | :: | |
169 | ||
170 | void (*sff_set_devctl)(struct ata_port *ap, u8 ctl); | |
171 | ||
172 | ||
173 | Write the device control ATA shadow register to the hardware. Most | |
174 | drivers don't need to define this. | |
175 | ||
176 | Select ATA device on bus | |
177 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
178 | ||
179 | :: | |
180 | ||
181 | void (*sff_dev_select)(struct ata_port *ap, unsigned int device); | |
182 | ||
183 | ||
184 | Issues the low-level hardware command(s) that causes one of N hardware | |
185 | devices to be considered 'selected' (active and available for use) on | |
186 | the ATA bus. This generally has no meaning on FIS-based devices. | |
187 | ||
6b46c2b1 | 188 | Most drivers for taskfile-based hardware use :c:func:`ata_sff_dev_select` for |
0ec88413 MCC |
189 | this hook. |
190 | ||
191 | Private tuning method | |
192 | ~~~~~~~~~~~~~~~~~~~~~ | |
193 | ||
194 | :: | |
195 | ||
196 | void (*set_mode) (struct ata_port *ap); | |
197 | ||
198 | ||
199 | By default libata performs drive and controller tuning in accordance | |
200 | with the ATA timing rules and also applies blacklists and cable limits. | |
201 | Some controllers need special handling and have custom tuning rules, | |
202 | typically raid controllers that use ATA commands but do not actually do | |
203 | drive timing. | |
204 | ||
205 | **Warning** | |
206 | ||
207 | This hook should not be used to replace the standard controller | |
208 | tuning logic when a controller has quirks. Replacing the default | |
209 | tuning logic in that case would bypass handling for drive and bridge | |
210 | quirks that may be important to data reliability. If a controller | |
211 | needs to filter the mode selection it should use the mode_filter | |
212 | hook instead. | |
213 | ||
214 | Control PCI IDE BMDMA engine | |
215 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
216 | ||
217 | :: | |
218 | ||
219 | void (*bmdma_setup) (struct ata_queued_cmd *qc); | |
220 | void (*bmdma_start) (struct ata_queued_cmd *qc); | |
221 | void (*bmdma_stop) (struct ata_port *ap); | |
222 | u8 (*bmdma_status) (struct ata_port *ap); | |
223 | ||
224 | ||
225 | When setting up an IDE BMDMA transaction, these hooks arm | |
6b46c2b1 MCC |
226 | (``->bmdma_setup``), fire (``->bmdma_start``), and halt (``->bmdma_stop``) the |
227 | hardware's DMA engine. ``->bmdma_status`` is used to read the standard PCI | |
0ec88413 MCC |
228 | IDE DMA Status register. |
229 | ||
230 | These hooks are typically either no-ops, or simply not implemented, in | |
231 | FIS-based drivers. | |
232 | ||
6b46c2b1 MCC |
233 | Most legacy IDE drivers use :c:func:`ata_bmdma_setup` for the |
234 | :c:func:`bmdma_setup` hook. :c:func:`ata_bmdma_setup` will write the pointer | |
235 | to the PRD table to the IDE PRD Table Address register, enable DMA in the DMA | |
236 | Command register, and call :c:func:`exec_command` to begin the transfer. | |
0ec88413 | 237 | |
6b46c2b1 MCC |
238 | Most legacy IDE drivers use :c:func:`ata_bmdma_start` for the |
239 | :c:func:`bmdma_start` hook. :c:func:`ata_bmdma_start` will write the | |
240 | ATA_DMA_START flag to the DMA Command register. | |
0ec88413 | 241 | |
6b46c2b1 MCC |
242 | Many legacy IDE drivers use :c:func:`ata_bmdma_stop` for the |
243 | :c:func:`bmdma_stop` hook. :c:func:`ata_bmdma_stop` clears the ATA_DMA_START | |
244 | flag in the DMA command register. | |
0ec88413 | 245 | |
6b46c2b1 MCC |
246 | Many legacy IDE drivers use :c:func:`ata_bmdma_status` as the |
247 | :c:func:`bmdma_status` hook. | |
0ec88413 MCC |
248 | |
249 | High-level taskfile hooks | |
250 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
251 | ||
252 | :: | |
253 | ||
254 | void (*qc_prep) (struct ata_queued_cmd *qc); | |
255 | int (*qc_issue) (struct ata_queued_cmd *qc); | |
256 | ||
257 | ||
258 | Higher-level hooks, these two hooks can potentially supercede several of | |
6b46c2b1 | 259 | the above taskfile/DMA engine hooks. ``->qc_prep`` is called after the |
0ec88413 MCC |
260 | buffers have been DMA-mapped, and is typically used to populate the |
261 | hardware's DMA scatter-gather table. Most drivers use the standard | |
6b46c2b1 | 262 | :c:func:`ata_qc_prep` helper function, but more advanced drivers roll their |
0ec88413 MCC |
263 | own. |
264 | ||
6b46c2b1 | 265 | ``->qc_issue`` is used to make a command active, once the hardware and S/G |
0ec88413 | 266 | tables have been prepared. IDE BMDMA drivers use the helper function |
6b46c2b1 MCC |
267 | :c:func:`ata_qc_issue_prot` for taskfile protocol-based dispatch. More |
268 | advanced drivers implement their own ``->qc_issue``. | |
0ec88413 | 269 | |
6b46c2b1 MCC |
270 | :c:func:`ata_qc_issue_prot` calls ``->tf_load()``, ``->bmdma_setup()``, and |
271 | ``->bmdma_start()`` as necessary to initiate a transfer. | |
0ec88413 MCC |
272 | |
273 | Exception and probe handling (EH) | |
274 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
275 | ||
276 | :: | |
277 | ||
278 | void (*eng_timeout) (struct ata_port *ap); | |
279 | void (*phy_reset) (struct ata_port *ap); | |
280 | ||
281 | ||
6b46c2b1 | 282 | Deprecated. Use ``->error_handler()`` instead. |
0ec88413 MCC |
283 | |
284 | :: | |
285 | ||
286 | void (*freeze) (struct ata_port *ap); | |
287 | void (*thaw) (struct ata_port *ap); | |
288 | ||
289 | ||
6b46c2b1 | 290 | :c:func:`ata_port_freeze` is called when HSM violations or some other |
0ec88413 MCC |
291 | condition disrupts normal operation of the port. A frozen port is not |
292 | allowed to perform any operation until the port is thawed, which usually | |
293 | follows a successful reset. | |
294 | ||
6b46c2b1 | 295 | The optional ``->freeze()`` callback can be used for freezing the port |
0ec88413 MCC |
296 | hardware-wise (e.g. mask interrupt and stop DMA engine). If a port |
297 | cannot be frozen hardware-wise, the interrupt handler must ack and clear | |
298 | interrupts unconditionally while the port is frozen. | |
299 | ||
6b46c2b1 MCC |
300 | The optional ``->thaw()`` callback is called to perform the opposite of |
301 | ``->freeze()``: prepare the port for normal operation once again. Unmask | |
0ec88413 MCC |
302 | interrupts, start DMA engine, etc. |
303 | ||
304 | :: | |
305 | ||
306 | void (*error_handler) (struct ata_port *ap); | |
307 | ||
308 | ||
6b46c2b1 | 309 | ``->error_handler()`` is a driver's hook into probe, hotplug, and recovery |
0ec88413 | 310 | and other exceptional conditions. The primary responsibility of an |
6b46c2b1 MCC |
311 | implementation is to call :c:func:`ata_do_eh` or :c:func:`ata_bmdma_drive_eh` |
312 | with a set of EH hooks as arguments: | |
0ec88413 MCC |
313 | |
314 | 'prereset' hook (may be NULL) is called during an EH reset, before any | |
315 | other actions are taken. | |
316 | ||
317 | 'postreset' hook (may be NULL) is called after the EH reset is | |
318 | performed. Based on existing conditions, severity of the problem, and | |
319 | hardware capabilities, | |
320 | ||
321 | Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be | |
322 | called to perform the low-level EH reset. | |
323 | ||
324 | :: | |
325 | ||
326 | void (*post_internal_cmd) (struct ata_queued_cmd *qc); | |
327 | ||
328 | ||
329 | Perform any hardware-specific actions necessary to finish processing | |
330 | after executing a probe-time or EH-time command via | |
6b46c2b1 | 331 | :c:func:`ata_exec_internal`. |
0ec88413 MCC |
332 | |
333 | Hardware interrupt handling | |
334 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
335 | ||
336 | :: | |
337 | ||
338 | irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); | |
339 | void (*irq_clear) (struct ata_port *); | |
340 | ||
341 | ||
6b46c2b1 MCC |
342 | ``->irq_handler`` is the interrupt handling routine registered with the |
343 | system, by libata. ``->irq_clear`` is called during probe just before the | |
0ec88413 MCC |
344 | interrupt handler is registered, to be sure hardware is quiet. |
345 | ||
346 | The second argument, dev_instance, should be cast to a pointer to | |
6b46c2b1 | 347 | :c:type:`struct ata_host_set <ata_host_set>`. |
0ec88413 | 348 | |
6b46c2b1 | 349 | Most legacy IDE drivers use :c:func:`ata_sff_interrupt` for the irq_handler |
0ec88413 MCC |
350 | hook, which scans all ports in the host_set, determines which queued |
351 | command was active (if any), and calls ata_sff_host_intr(ap,qc). | |
352 | ||
6b46c2b1 MCC |
353 | Most legacy IDE drivers use :c:func:`ata_sff_irq_clear` for the |
354 | :c:func:`irq_clear` hook, which simply clears the interrupt and error flags | |
355 | in the DMA status register. | |
0ec88413 MCC |
356 | |
357 | SATA phy read/write | |
358 | ~~~~~~~~~~~~~~~~~~~ | |
359 | ||
360 | :: | |
361 | ||
362 | int (*scr_read) (struct ata_port *ap, unsigned int sc_reg, | |
363 | u32 *val); | |
364 | int (*scr_write) (struct ata_port *ap, unsigned int sc_reg, | |
365 | u32 val); | |
366 | ||
367 | ||
368 | Read and write standard SATA phy registers. Currently only used if | |
6b46c2b1 MCC |
369 | ``->phy_reset`` hook called the :c:func:`sata_phy_reset` helper function. |
370 | sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE. | |
0ec88413 MCC |
371 | |
372 | Init and shutdown | |
373 | ~~~~~~~~~~~~~~~~~ | |
374 | ||
375 | :: | |
376 | ||
377 | int (*port_start) (struct ata_port *ap); | |
378 | void (*port_stop) (struct ata_port *ap); | |
379 | void (*host_stop) (struct ata_host_set *host_set); | |
380 | ||
381 | ||
6b46c2b1 | 382 | ``->port_start()`` is called just after the data structures for each port |
0ec88413 MCC |
383 | are initialized. Typically this is used to alloc per-port DMA buffers / |
384 | tables / rings, enable DMA engines, and similar tasks. Some drivers also | |
385 | use this entry point as a chance to allocate driver-private memory for | |
6b46c2b1 | 386 | ``ap->private_data``. |
0ec88413 | 387 | |
6b46c2b1 MCC |
388 | Many drivers use :c:func:`ata_port_start` as this hook or call it from their |
389 | own :c:func:`port_start` hooks. :c:func:`ata_port_start` allocates space for | |
390 | a legacy IDE PRD table and returns. | |
0ec88413 | 391 | |
6b46c2b1 | 392 | ``->port_stop()`` is called after ``->host_stop()``. Its sole function is to |
0ec88413 MCC |
393 | release DMA/memory resources, now that they are no longer actively being |
394 | used. Many drivers also free driver-private data from port at this time. | |
395 | ||
6b46c2b1 | 396 | ``->host_stop()`` is called after all ``->port_stop()`` calls have completed. |
0ec88413 MCC |
397 | The hook must finalize hardware shutdown, release DMA and other |
398 | resources, etc. This hook may be specified as NULL, in which case it is | |
399 | not called. | |
400 | ||
401 | Error handling | |
402 | ============== | |
403 | ||
404 | This chapter describes how errors are handled under libata. Readers are | |
405 | advised to read SCSI EH (Documentation/scsi/scsi_eh.txt) and ATA | |
406 | exceptions doc first. | |
407 | ||
408 | Origins of commands | |
409 | ------------------- | |
410 | ||
6b46c2b1 MCC |
411 | In libata, a command is represented with |
412 | :c:type:`struct ata_queued_cmd <ata_queued_cmd>` or qc. | |
0ec88413 MCC |
413 | qc's are preallocated during port initialization and repetitively used |
414 | for command executions. Currently only one qc is allocated per port but | |
415 | yet-to-be-merged NCQ branch allocates one for each tag and maps each qc | |
416 | to NCQ tag 1-to-1. | |
417 | ||
418 | libata commands can originate from two sources - libata itself and SCSI | |
419 | midlayer. libata internal commands are used for initialization and error | |
420 | handling. All normal blk requests and commands for SCSI emulation are | |
421 | passed as SCSI commands through queuecommand callback of SCSI host | |
422 | template. | |
423 | ||
424 | How commands are issued | |
425 | ----------------------- | |
426 | ||
427 | Internal commands | |
6b46c2b1 MCC |
428 | First, qc is allocated and initialized using :c:func:`ata_qc_new_init`. |
429 | Although :c:func:`ata_qc_new_init` doesn't implement any wait or retry | |
0ec88413 MCC |
430 | mechanism when qc is not available, internal commands are currently |
431 | issued only during initialization and error recovery, so no other | |
432 | command is active and allocation is guaranteed to succeed. | |
433 | ||
434 | Once allocated qc's taskfile is initialized for the command to be | |
435 | executed. qc currently has two mechanisms to notify completion. One | |
6b46c2b1 MCC |
436 | is via ``qc->complete_fn()`` callback and the other is completion |
437 | ``qc->waiting``. ``qc->complete_fn()`` callback is the asynchronous path | |
438 | used by normal SCSI translated commands and ``qc->waiting`` is the | |
0ec88413 MCC |
439 | synchronous (issuer sleeps in process context) path used by internal |
440 | commands. | |
441 | ||
442 | Once initialization is complete, host_set lock is acquired and the | |
443 | qc is issued. | |
444 | ||
445 | SCSI commands | |
6b46c2b1 MCC |
446 | All libata drivers use :c:func:`ata_scsi_queuecmd` as |
447 | ``hostt->queuecommand`` callback. scmds can either be simulated or | |
448 | translated. No qc is involved in processing a simulated scmd. The | |
449 | result is computed right away and the scmd is completed. | |
0ec88413 | 450 | |
6b46c2b1 | 451 | For a translated scmd, :c:func:`ata_qc_new_init` is invoked to allocate a |
0ec88413 MCC |
452 | qc and the scmd is translated into the qc. SCSI midlayer's |
453 | completion notification function pointer is stored into | |
6b46c2b1 | 454 | ``qc->scsidone``. |
0ec88413 | 455 | |
6b46c2b1 MCC |
456 | ``qc->complete_fn()`` callback is used for completion notification. ATA |
457 | commands use :c:func:`ata_scsi_qc_complete` while ATAPI commands use | |
458 | :c:func:`atapi_qc_complete`. Both functions end up calling ``qc->scsidone`` | |
459 | to notify upper layer when the qc is finished. After translation is | |
460 | completed, the qc is issued with :c:func:`ata_qc_issue`. | |
0ec88413 MCC |
461 | |
462 | Note that SCSI midlayer invokes hostt->queuecommand while holding | |
463 | host_set lock, so all above occur while holding host_set lock. | |
464 | ||
465 | How commands are processed | |
466 | -------------------------- | |
467 | ||
468 | Depending on which protocol and which controller are used, commands are | |
469 | processed differently. For the purpose of discussion, a controller which | |
470 | uses taskfile interface and all standard callbacks is assumed. | |
471 | ||
472 | Currently 6 ATA command protocols are used. They can be sorted into the | |
473 | following four categories according to how they are processed. | |
474 | ||
475 | ATA NO DATA or DMA | |
476 | ATA_PROT_NODATA and ATA_PROT_DMA fall into this category. These | |
477 | types of commands don't require any software intervention once | |
478 | issued. Device will raise interrupt on completion. | |
479 | ||
480 | ATA PIO | |
481 | ATA_PROT_PIO is in this category. libata currently implements PIO | |
482 | with polling. ATA_NIEN bit is set to turn off interrupt and | |
483 | pio_task on ata_wq performs polling and IO. | |
484 | ||
485 | ATAPI NODATA or DMA | |
486 | ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this | |
487 | category. packet_task is used to poll BSY bit after issuing PACKET | |
488 | command. Once BSY is turned off by the device, packet_task | |
489 | transfers CDB and hands off processing to interrupt handler. | |
490 | ||
491 | ATAPI PIO | |
492 | ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set and, as | |
493 | in ATAPI NODATA or DMA, packet_task submits cdb. However, after | |
494 | submitting cdb, further processing (data transfer) is handed off to | |
495 | pio_task. | |
496 | ||
497 | How commands are completed | |
498 | -------------------------- | |
499 | ||
6b46c2b1 | 500 | Once issued, all qc's are either completed with :c:func:`ata_qc_complete` or |
0ec88413 | 501 | time out. For commands which are handled by interrupts, |
6b46c2b1 MCC |
502 | :c:func:`ata_host_intr` invokes :c:func:`ata_qc_complete`, and, for PIO tasks, |
503 | pio_task invokes :c:func:`ata_qc_complete`. In error cases, packet_task may | |
0ec88413 MCC |
504 | also complete commands. |
505 | ||
6b46c2b1 | 506 | :c:func:`ata_qc_complete` does the following. |
0ec88413 MCC |
507 | |
508 | 1. DMA memory is unmapped. | |
509 | ||
510 | 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags. | |
511 | ||
6b46c2b1 | 512 | 3. :c:func:`qc->complete_fn` callback is invoked. If the return value of the |
0ec88413 | 513 | callback is not zero. Completion is short circuited and |
6b46c2b1 | 514 | :c:func:`ata_qc_complete` returns. |
0ec88413 | 515 | |
6b46c2b1 | 516 | 4. :c:func:`__ata_qc_complete` is called, which does |
0ec88413 | 517 | |
6b46c2b1 | 518 | 1. ``qc->flags`` is cleared to zero. |
0ec88413 | 519 | |
6b46c2b1 | 520 | 2. ``ap->active_tag`` and ``qc->tag`` are poisoned. |
0ec88413 | 521 | |
6b46c2b1 | 522 | 3. ``qc->waiting`` is cleared & completed (in that order). |
0ec88413 | 523 | |
6b46c2b1 | 524 | 4. qc is deallocated by clearing appropriate bit in ``ap->qactive``. |
0ec88413 MCC |
525 | |
526 | So, it basically notifies upper layer and deallocates qc. One exception | |
6b46c2b1 | 527 | is short-circuit path in #3 which is used by :c:func:`atapi_qc_complete`. |
0ec88413 MCC |
528 | |
529 | For all non-ATAPI commands, whether it fails or not, almost the same | |
530 | code path is taken and very little error handling takes place. A qc is | |
531 | completed with success status if it succeeded, with failed status | |
532 | otherwise. | |
533 | ||
534 | However, failed ATAPI commands require more handling as REQUEST SENSE is | |
535 | needed to acquire sense data. If an ATAPI command fails, | |
6b46c2b1 MCC |
536 | :c:func:`ata_qc_complete` is invoked with error status, which in turn invokes |
537 | :c:func:`atapi_qc_complete` via ``qc->complete_fn()`` callback. | |
0ec88413 | 538 | |
6b46c2b1 | 539 | This makes :c:func:`atapi_qc_complete` set ``scmd->result`` to |
0ec88413 | 540 | SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As the |
6b46c2b1 MCC |
541 | sense data is empty but ``scmd->result`` is CHECK CONDITION, SCSI midlayer |
542 | will invoke EH for the scmd, and returning 1 makes :c:func:`ata_qc_complete` | |
0ec88413 | 543 | to return without deallocating the qc. This leads us to |
6b46c2b1 | 544 | :c:func:`ata_scsi_error` with partially completed qc. |
0ec88413 | 545 | |
6b46c2b1 MCC |
546 | :c:func:`ata_scsi_error` |
547 | ------------------------ | |
0ec88413 | 548 | |
6b46c2b1 | 549 | :c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()`` |
0ec88413 MCC |
550 | for libata. As discussed above, this will be entered in two cases - |
551 | timeout and ATAPI error completion. This function calls low level libata | |
6b46c2b1 MCC |
552 | driver's :c:func:`eng_timeout` callback, the standard callback for which is |
553 | :c:func:`ata_eng_timeout`. It checks if a qc is active and calls | |
554 | :c:func:`ata_qc_timeout` on the qc if so. Actual error handling occurs in | |
555 | :c:func:`ata_qc_timeout`. | |
0ec88413 | 556 | |
6b46c2b1 | 557 | If EH is invoked for timeout, :c:func:`ata_qc_timeout` stops BMDMA and |
0ec88413 MCC |
558 | completes the qc. Note that as we're currently in EH, we cannot call |
559 | scsi_done. As described in SCSI EH doc, a recovered scmd should be | |
6b46c2b1 MCC |
560 | either retried with :c:func:`scsi_queue_insert` or finished with |
561 | :c:func:`scsi_finish_command`. Here, we override ``qc->scsidone`` with | |
562 | :c:func:`scsi_finish_command` and calls :c:func:`ata_qc_complete`. | |
0ec88413 MCC |
563 | |
564 | If EH is invoked due to a failed ATAPI qc, the qc here is completed but | |
565 | not deallocated. The purpose of this half-completion is to use the qc as | |
566 | place holder to make EH code reach this place. This is a bit hackish, | |
567 | but it works. | |
568 | ||
569 | Once control reaches here, the qc is deallocated by invoking | |
6b46c2b1 | 570 | :c:func:`__ata_qc_complete` explicitly. Then, internal qc for REQUEST SENSE |
0ec88413 | 571 | is issued. Once sense data is acquired, scmd is finished by directly |
6b46c2b1 | 572 | invoking :c:func:`scsi_finish_command` on the scmd. Note that as we already |
0ec88413 | 573 | have completed and deallocated the qc which was associated with the |
6b46c2b1 | 574 | scmd, we don't need to/cannot call :c:func:`ata_qc_complete` again. |
0ec88413 MCC |
575 | |
576 | Problems with the current EH | |
577 | ---------------------------- | |
578 | ||
579 | - Error representation is too crude. Currently any and all error | |
580 | conditions are represented with ATA STATUS and ERROR registers. | |
581 | Errors which aren't ATA device errors are treated as ATA device | |
582 | errors by setting ATA_ERR bit. Better error descriptor which can | |
583 | properly represent ATA and other errors/exceptions is needed. | |
584 | ||
585 | - When handling timeouts, no action is taken to make device forget | |
586 | about the timed out command and ready for new commands. | |
587 | ||
6b46c2b1 | 588 | - EH handling via :c:func:`ata_scsi_error` is not properly protected from |
0ec88413 MCC |
589 | usual command processing. On EH entrance, the device is not in |
590 | quiescent state. Timed out commands may succeed or fail any time. | |
591 | pio_task and atapi_task may still be running. | |
592 | ||
593 | - Too weak error recovery. Devices / controllers causing HSM mismatch | |
594 | errors and other errors quite often require reset to return to known | |
595 | state. Also, advanced error handling is necessary to support features | |
596 | like NCQ and hotplug. | |
597 | ||
598 | - ATA errors are directly handled in the interrupt handler and PIO | |
599 | errors in pio_task. This is problematic for advanced error handling | |
600 | for the following reasons. | |
601 | ||
602 | First, advanced error handling often requires context and internal qc | |
603 | execution. | |
604 | ||
605 | Second, even a simple failure (say, CRC error) needs information | |
606 | gathering and could trigger complex error handling (say, resetting & | |
607 | reconfiguring). Having multiple code paths to gather information, | |
608 | enter EH and trigger actions makes life painful. | |
609 | ||
610 | Third, scattered EH code makes implementing low level drivers | |
611 | difficult. Low level drivers override libata callbacks. If EH is | |
612 | scattered over several places, each affected callbacks should perform | |
613 | its part of error handling. This can be error prone and painful. | |
614 | ||
615 | libata Library | |
616 | ============== | |
617 | ||
618 | .. kernel-doc:: drivers/ata/libata-core.c | |
619 | :export: | |
620 | ||
621 | libata Core Internals | |
622 | ===================== | |
623 | ||
624 | .. kernel-doc:: drivers/ata/libata-core.c | |
625 | :internal: | |
626 | ||
6b46c2b1 MCC |
627 | .. kernel-doc:: drivers/ata/libata-eh.c |
628 | ||
0ec88413 MCC |
629 | libata SCSI translation/emulation |
630 | ================================= | |
631 | ||
632 | .. kernel-doc:: drivers/ata/libata-scsi.c | |
633 | :export: | |
634 | ||
635 | .. kernel-doc:: drivers/ata/libata-scsi.c | |
636 | :internal: | |
637 | ||
638 | ATA errors and exceptions | |
639 | ========================= | |
640 | ||
641 | This chapter tries to identify what error/exception conditions exist for | |
642 | ATA/ATAPI devices and describe how they should be handled in | |
643 | implementation-neutral way. | |
644 | ||
645 | The term 'error' is used to describe conditions where either an explicit | |
646 | error condition is reported from device or a command has timed out. | |
647 | ||
648 | The term 'exception' is either used to describe exceptional conditions | |
649 | which are not errors (say, power or hotplug events), or to describe both | |
650 | errors and non-error exceptional conditions. Where explicit distinction | |
651 | between error and exception is necessary, the term 'non-error exception' | |
652 | is used. | |
653 | ||
654 | Exception categories | |
655 | -------------------- | |
656 | ||
657 | Exceptions are described primarily with respect to legacy taskfile + bus | |
658 | master IDE interface. If a controller provides other better mechanism | |
659 | for error reporting, mapping those into categories described below | |
660 | shouldn't be difficult. | |
661 | ||
662 | In the following sections, two recovery actions - reset and | |
663 | reconfiguring transport - are mentioned. These are described further in | |
664 | `EH recovery actions <#exrec>`__. | |
665 | ||
666 | HSM violation | |
667 | ~~~~~~~~~~~~~ | |
668 | ||
669 | This error is indicated when STATUS value doesn't match HSM requirement | |
670 | during issuing or execution any ATA/ATAPI command. | |
671 | ||
672 | - ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying to | |
673 | issue a command. | |
674 | ||
675 | - !BSY && !DRQ during PIO data transfer. | |
676 | ||
677 | - DRQ on command completion. | |
678 | ||
679 | - !BSY && ERR after CDB transfer starts but before the last byte of CDB | |
680 | is transferred. ATA/ATAPI standard states that "The device shall not | |
681 | terminate the PACKET command with an error before the last byte of | |
682 | the command packet has been written" in the error outputs description | |
683 | of PACKET command and the state diagram doesn't include such | |
684 | transitions. | |
685 | ||
686 | In these cases, HSM is violated and not much information regarding the | |
687 | error can be acquired from STATUS or ERROR register. IOW, this error can | |
688 | be anything - driver bug, faulty device, controller and/or cable. | |
689 | ||
690 | As HSM is violated, reset is necessary to restore known state. | |
691 | Reconfiguring transport for lower speed might be helpful too as | |
692 | transmission errors sometimes cause this kind of errors. | |
693 | ||
694 | ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) | |
695 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
696 | ||
697 | These are errors detected and reported by ATA/ATAPI devices indicating | |
698 | device problems. For this type of errors, STATUS and ERROR register | |
699 | values are valid and describe error condition. Note that some of ATA bus | |
700 | errors are detected by ATA/ATAPI devices and reported using the same | |
701 | mechanism as device errors. Those cases are described later in this | |
702 | section. | |
703 | ||
704 | For ATA commands, this type of errors are indicated by !BSY && ERR | |
705 | during command execution and on completion. | |
706 | ||
707 | For ATAPI commands, | |
708 | ||
709 | - !BSY && ERR && ABRT right after issuing PACKET indicates that PACKET | |
710 | command is not supported and falls in this category. | |
711 | ||
712 | - !BSY && ERR(==CHK) && !ABRT after the last byte of CDB is transferred | |
713 | indicates CHECK CONDITION and doesn't fall in this category. | |
714 | ||
715 | - !BSY && ERR(==CHK) && ABRT after the last byte of CDB is transferred | |
716 | \*probably\* indicates CHECK CONDITION and doesn't fall in this | |
717 | category. | |
718 | ||
719 | Of errors detected as above, the following are not ATA/ATAPI device | |
720 | errors but ATA bus errors and should be handled according to | |
721 | `ATA bus error <#excatATAbusErr>`__. | |
722 | ||
723 | CRC error during data transfer | |
724 | This is indicated by ICRC bit in the ERROR register and means that | |
725 | corruption occurred during data transfer. Up to ATA/ATAPI-7, the | |
726 | standard specifies that this bit is only applicable to UDMA | |
727 | transfers but ATA/ATAPI-8 draft revision 1f says that the bit may be | |
728 | applicable to multiword DMA and PIO. | |
729 | ||
730 | ABRT error during data transfer or on completion | |
731 | Up to ATA/ATAPI-7, the standard specifies that ABRT could be set on | |
732 | ICRC errors and on cases where a device is not able to complete a | |
733 | command. Combined with the fact that MWDMA and PIO transfer errors | |
734 | aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply | |
735 | that ABRT bit alone could indicate transfer errors. | |
736 | ||
737 | However, ATA/ATAPI-8 draft revision 1f removes the part that ICRC | |
738 | errors can turn on ABRT. So, this is kind of gray area. Some | |
739 | heuristics are needed here. | |
740 | ||
741 | ATA/ATAPI device errors can be further categorized as follows. | |
742 | ||
743 | Media errors | |
744 | This is indicated by UNC bit in the ERROR register. ATA devices | |
745 | reports UNC error only after certain number of retries cannot | |
746 | recover the data, so there's nothing much else to do other than | |
747 | notifying upper layer. | |
748 | ||
749 | READ and WRITE commands report CHS or LBA of the first failed sector | |
750 | but ATA/ATAPI standard specifies that the amount of transferred data | |
751 | on error completion is indeterminate, so we cannot assume that | |
752 | sectors preceding the failed sector have been transferred and thus | |
753 | cannot complete those sectors successfully as SCSI does. | |
754 | ||
755 | Media changed / media change requested error | |
756 | <<TODO: fill here>> | |
757 | ||
758 | Address error | |
759 | This is indicated by IDNF bit in the ERROR register. Report to upper | |
760 | layer. | |
761 | ||
762 | Other errors | |
763 | This can be invalid command or parameter indicated by ABRT ERROR bit | |
764 | or some other error condition. Note that ABRT bit can indicate a lot | |
765 | of things including ICRC and Address errors. Heuristics needed. | |
766 | ||
767 | Depending on commands, not all STATUS/ERROR bits are applicable. These | |
768 | non-applicable bits are marked with "na" in the output descriptions but | |
769 | up to ATA/ATAPI-7 no definition of "na" can be found. However, | |
770 | ATA/ATAPI-8 draft revision 1f describes "N/A" as follows. | |
771 | ||
772 | 3.2.3.3a N/A | |
773 | A keyword the indicates a field has no defined value in this | |
774 | standard and should not be checked by the host or device. N/A | |
775 | fields should be cleared to zero. | |
776 | ||
777 | So, it seems reasonable to assume that "na" bits are cleared to zero by | |
778 | devices and thus need no explicit masking. | |
779 | ||
780 | ATAPI device CHECK CONDITION | |
781 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
782 | ||
783 | ATAPI device CHECK CONDITION error is indicated by set CHK bit (ERR bit) | |
784 | in the STATUS register after the last byte of CDB is transferred for a | |
785 | PACKET command. For this kind of errors, sense data should be acquired | |
786 | to gather information regarding the errors. REQUEST SENSE packet command | |
787 | should be used to acquire sense data. | |
788 | ||
789 | Once sense data is acquired, this type of errors can be handled | |
790 | similarly to other SCSI errors. Note that sense data may indicate ATA | |
791 | bus error (e.g. Sense Key 04h HARDWARE ERROR && ASC/ASCQ 47h/00h SCSI | |
792 | PARITY ERROR). In such cases, the error should be considered as an ATA | |
793 | bus error and handled according to `ATA bus error <#excatATAbusErr>`__. | |
794 | ||
795 | ATA device error (NCQ) | |
796 | ~~~~~~~~~~~~~~~~~~~~~~ | |
797 | ||
798 | NCQ command error is indicated by cleared BSY and set ERR bit during NCQ | |
799 | command phase (one or more NCQ commands outstanding). Although STATUS | |
800 | and ERROR registers will contain valid values describing the error, READ | |
801 | LOG EXT is required to clear the error condition, determine which | |
802 | command has failed and acquire more information. | |
803 | ||
804 | READ LOG EXT Log Page 10h reports which tag has failed and taskfile | |
805 | register values describing the error. With this information the failed | |
806 | command can be handled as a normal ATA command error as in | |
807 | `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__ | |
808 | and all other in-flight commands must be retried. Note that this retry | |
809 | should not be counted - it's likely that commands retried this way would | |
810 | have completed normally if it were not for the failed command. | |
811 | ||
812 | Note that ATA bus errors can be reported as ATA device NCQ errors. This | |
813 | should be handled as described in `ATA bus error <#excatATAbusErr>`__. | |
814 | ||
815 | If READ LOG EXT Log Page 10h fails or reports NQ, we're thoroughly | |
816 | screwed. This condition should be treated according to | |
817 | `HSM violation <#excatHSMviolation>`__. | |
818 | ||
819 | ATA bus error | |
820 | ~~~~~~~~~~~~~ | |
821 | ||
822 | ATA bus error means that data corruption occurred during transmission | |
823 | over ATA bus (SATA or PATA). This type of errors can be indicated by | |
824 | ||
825 | - ICRC or ABRT error as described in | |
826 | `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__. | |
827 | ||
828 | - Controller-specific error completion with error information | |
829 | indicating transmission error. | |
830 | ||
831 | - On some controllers, command timeout. In this case, there may be a | |
832 | mechanism to determine that the timeout is due to transmission error. | |
833 | ||
834 | - Unknown/random errors, timeouts and all sorts of weirdities. | |
835 | ||
836 | As described above, transmission errors can cause wide variety of | |
837 | symptoms ranging from device ICRC error to random device lockup, and, | |
838 | for many cases, there is no way to tell if an error condition is due to | |
839 | transmission error or not; therefore, it's necessary to employ some kind | |
840 | of heuristic when dealing with errors and timeouts. For example, | |
841 | encountering repetitive ABRT errors for known supported command is | |
842 | likely to indicate ATA bus error. | |
843 | ||
844 | Once it's determined that ATA bus errors have possibly occurred, | |
845 | lowering ATA bus transmission speed is one of actions which may | |
846 | alleviate the problem. See `Reconfigure transport <#exrecReconf>`__ for | |
847 | more information. | |
848 | ||
849 | PCI bus error | |
850 | ~~~~~~~~~~~~~ | |
851 | ||
852 | Data corruption or other failures during transmission over PCI (or other | |
853 | system bus). For standard BMDMA, this is indicated by Error bit in the | |
854 | BMDMA Status register. This type of errors must be logged as it | |
855 | indicates something is very wrong with the system. Resetting host | |
856 | controller is recommended. | |
857 | ||
858 | Late completion | |
859 | ~~~~~~~~~~~~~~~ | |
860 | ||
861 | This occurs when timeout occurs and the timeout handler finds out that | |
862 | the timed out command has completed successfully or with error. This is | |
863 | usually caused by lost interrupts. This type of errors must be logged. | |
864 | Resetting host controller is recommended. | |
865 | ||
866 | Unknown error (timeout) | |
867 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
868 | ||
869 | This is when timeout occurs and the command is still processing or the | |
870 | host and device are in unknown state. When this occurs, HSM could be in | |
871 | any valid or invalid state. To bring the device to known state and make | |
872 | it forget about the timed out command, resetting is necessary. The timed | |
873 | out command may be retried. | |
874 | ||
875 | Timeouts can also be caused by transmission errors. Refer to | |
876 | `ATA bus error <#excatATAbusErr>`__ for more details. | |
877 | ||
878 | Hotplug and power management exceptions | |
879 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
880 | ||
881 | <<TODO: fill here>> | |
882 | ||
883 | EH recovery actions | |
884 | ------------------- | |
885 | ||
886 | This section discusses several important recovery actions. | |
887 | ||
888 | Clearing error condition | |
889 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
890 | ||
891 | Many controllers require its error registers to be cleared by error | |
892 | handler. Different controllers may have different requirements. | |
893 | ||
894 | For SATA, it's strongly recommended to clear at least SError register | |
895 | during error handling. | |
896 | ||
897 | Reset | |
898 | ~~~~~ | |
899 | ||
900 | During EH, resetting is necessary in the following cases. | |
901 | ||
902 | - HSM is in unknown or invalid state | |
903 | ||
904 | - HBA is in unknown or invalid state | |
905 | ||
906 | - EH needs to make HBA/device forget about in-flight commands | |
907 | ||
908 | - HBA/device behaves weirdly | |
909 | ||
910 | Resetting during EH might be a good idea regardless of error condition | |
911 | to improve EH robustness. Whether to reset both or either one of HBA and | |
912 | device depends on situation but the following scheme is recommended. | |
913 | ||
914 | - When it's known that HBA is in ready state but ATA/ATAPI device is in | |
915 | unknown state, reset only device. | |
916 | ||
917 | - If HBA is in unknown state, reset both HBA and device. | |
918 | ||
919 | HBA resetting is implementation specific. For a controller complying to | |
920 | taskfile/BMDMA PCI IDE, stopping active DMA transaction may be | |
921 | sufficient iff BMDMA state is the only HBA context. But even mostly | |
922 | taskfile/BMDMA PCI IDE complying controllers may have implementation | |
923 | specific requirements and mechanism to reset themselves. This must be | |
924 | addressed by specific drivers. | |
925 | ||
926 | OTOH, ATA/ATAPI standard describes in detail ways to reset ATA/ATAPI | |
927 | devices. | |
928 | ||
929 | PATA hardware reset | |
930 | This is hardware initiated device reset signalled with asserted PATA | |
931 | RESET- signal. There is no standard way to initiate hardware reset | |
932 | from software although some hardware provides registers that allow | |
933 | driver to directly tweak the RESET- signal. | |
934 | ||
935 | Software reset | |
936 | This is achieved by turning CONTROL SRST bit on for at least 5us. | |
937 | Both PATA and SATA support it but, in case of SATA, this may require | |
938 | controller-specific support as the second Register FIS to clear SRST | |
939 | should be transmitted while BSY bit is still set. Note that on PATA, | |
940 | this resets both master and slave devices on a channel. | |
941 | ||
942 | EXECUTE DEVICE DIAGNOSTIC command | |
943 | Although ATA/ATAPI standard doesn't describe exactly, EDD implies | |
944 | some level of resetting, possibly similar level with software reset. | |
945 | Host-side EDD protocol can be handled with normal command processing | |
946 | and most SATA controllers should be able to handle EDD's just like | |
947 | other commands. As in software reset, EDD affects both devices on a | |
948 | PATA bus. | |
949 | ||
950 | Although EDD does reset devices, this doesn't suit error handling as | |
951 | EDD cannot be issued while BSY is set and it's unclear how it will | |
952 | act when device is in unknown/weird state. | |
953 | ||
954 | ATAPI DEVICE RESET command | |
955 | This is very similar to software reset except that reset can be | |
956 | restricted to the selected device without affecting the other device | |
957 | sharing the cable. | |
958 | ||
959 | SATA phy reset | |
960 | This is the preferred way of resetting a SATA device. In effect, | |
961 | it's identical to PATA hardware reset. Note that this can be done | |
962 | with the standard SCR Control register. As such, it's usually easier | |
963 | to implement than software reset. | |
964 | ||
965 | One more thing to consider when resetting devices is that resetting | |
966 | clears certain configuration parameters and they need to be set to their | |
967 | previous or newly adjusted values after reset. | |
968 | ||
969 | Parameters affected are. | |
970 | ||
971 | - CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used) | |
972 | ||
973 | - Parameters set with SET FEATURES including transfer mode setting | |
974 | ||
975 | - Block count set with SET MULTIPLE MODE | |
976 | ||
977 | - Other parameters (SET MAX, MEDIA LOCK...) | |
978 | ||
979 | ATA/ATAPI standard specifies that some parameters must be maintained | |
980 | across hardware or software reset, but doesn't strictly specify all of | |
981 | them. Always reconfiguring needed parameters after reset is required for | |
982 | robustness. Note that this also applies when resuming from deep sleep | |
983 | (power-off). | |
984 | ||
985 | Also, ATA/ATAPI standard requires that IDENTIFY DEVICE / IDENTIFY PACKET | |
986 | DEVICE is issued after any configuration parameter is updated or a | |
987 | hardware reset and the result used for further operation. OS driver is | |
988 | required to implement revalidation mechanism to support this. | |
989 | ||
990 | Reconfigure transport | |
991 | ~~~~~~~~~~~~~~~~~~~~~ | |
992 | ||
993 | For both PATA and SATA, a lot of corners are cut for cheap connectors, | |
994 | cables or controllers and it's quite common to see high transmission | |
995 | error rate. This can be mitigated by lowering transmission speed. | |
996 | ||
997 | The following is a possible scheme Jeff Garzik suggested. | |
998 | ||
999 | If more than $N (3?) transmission errors happen in 15 minutes, | |
1000 | ||
1001 | - if SATA, decrease SATA PHY speed. if speed cannot be decreased, | |
1002 | ||
1003 | - decrease UDMA xfer speed. if at UDMA0, switch to PIO4, | |
1004 | ||
1005 | - decrease PIO xfer speed. if at PIO3, complain, but continue | |
1006 | ||
1007 | ata_piix Internals | |
1008 | =================== | |
1009 | ||
1010 | .. kernel-doc:: drivers/ata/ata_piix.c | |
1011 | :internal: | |
1012 | ||
1013 | sata_sil Internals | |
1014 | =================== | |
1015 | ||
1016 | .. kernel-doc:: drivers/ata/sata_sil.c | |
1017 | :internal: | |
1018 | ||
1019 | Thanks | |
1020 | ====== | |
1021 | ||
1022 | The bulk of the ATA knowledge comes thanks to long conversations with | |
1023 | Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA and | |
1024 | SCSI specifications. | |
1025 | ||
1026 | Thanks to Alan Cox for pointing out similarities between SATA and SCSI, | |
1027 | and in general for motivation to hack on libata. | |
1028 | ||
1029 | libata's device detection method, ata_pio_devchk, and in general all | |
1030 | the early probing was based on extensive study of Hale Landis's | |
1031 | probe/reset code in his ATADRVR driver (www.ata-atapi.com). |