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