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