10ec88413SMauro Carvalho Chehab======================== 20ec88413SMauro Carvalho ChehablibATA Developer's Guide 30ec88413SMauro Carvalho Chehab======================== 40ec88413SMauro Carvalho Chehab 50ec88413SMauro Carvalho Chehab:Author: Jeff Garzik 60ec88413SMauro Carvalho Chehab 70ec88413SMauro Carvalho ChehabIntroduction 80ec88413SMauro Carvalho Chehab============ 90ec88413SMauro Carvalho Chehab 100ec88413SMauro Carvalho ChehablibATA is a library used inside the Linux kernel to support ATA host 110ec88413SMauro Carvalho Chehabcontrollers and devices. libATA provides an ATA driver API, class 120ec88413SMauro Carvalho Chehabtransports for ATA and ATAPI devices, and SCSI<->ATA translation for ATA 130ec88413SMauro Carvalho Chehabdevices according to the T10 SAT specification. 140ec88413SMauro Carvalho Chehab 150ec88413SMauro Carvalho ChehabThis Guide documents the libATA driver API, library functions, library 160ec88413SMauro Carvalho Chehabinternals, and a couple sample ATA low-level drivers. 170ec88413SMauro Carvalho Chehab 180ec88413SMauro Carvalho Chehablibata Driver API 190ec88413SMauro Carvalho Chehab================= 200ec88413SMauro Carvalho Chehab 216b46c2b1SMauro Carvalho Chehab:c:type:`struct ata_port_operations <ata_port_operations>` 226b46c2b1SMauro Carvalho Chehabis defined for every low-level libata 230ec88413SMauro Carvalho Chehabhardware driver, and it controls how the low-level driver interfaces 240ec88413SMauro Carvalho Chehabwith the ATA and SCSI layers. 250ec88413SMauro Carvalho Chehab 266b46c2b1SMauro Carvalho ChehabFIS-based drivers will hook into the system with ``->qc_prep()`` and 276b46c2b1SMauro Carvalho Chehab``->qc_issue()`` high-level hooks. Hardware which behaves in a manner 280ec88413SMauro Carvalho Chehabsimilar to PCI IDE hardware may utilize several generic helpers, 290ec88413SMauro Carvalho Chehabdefining at a bare minimum the bus I/O addresses of the ATA shadow 300ec88413SMauro Carvalho Chehabregister blocks. 310ec88413SMauro Carvalho Chehab 326b46c2b1SMauro Carvalho Chehab:c:type:`struct ata_port_operations <ata_port_operations>` 336b46c2b1SMauro Carvalho Chehab---------------------------------------------------------- 340ec88413SMauro Carvalho Chehab 350ec88413SMauro Carvalho ChehabDisable ATA port 360ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~ 370ec88413SMauro Carvalho Chehab 380ec88413SMauro Carvalho Chehab:: 390ec88413SMauro Carvalho Chehab 400ec88413SMauro Carvalho Chehab void (*port_disable) (struct ata_port *); 410ec88413SMauro Carvalho Chehab 420ec88413SMauro Carvalho Chehab 436b46c2b1SMauro Carvalho ChehabCalled from :c:func:`ata_bus_probe` error path, as well as when unregistering 440ec88413SMauro Carvalho Chehabfrom the SCSI module (rmmod, hot unplug). This function should do 450ec88413SMauro Carvalho Chehabwhatever needs to be done to take the port out of use. In most cases, 466b46c2b1SMauro Carvalho Chehab:c:func:`ata_port_disable` can be used as this hook. 470ec88413SMauro Carvalho Chehab 486b46c2b1SMauro Carvalho ChehabCalled from :c:func:`ata_bus_probe` on a failed probe. Called from 496b46c2b1SMauro Carvalho Chehab:c:func:`ata_scsi_release`. 500ec88413SMauro Carvalho Chehab 510ec88413SMauro Carvalho ChehabPost-IDENTIFY device configuration 520ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 530ec88413SMauro Carvalho Chehab 540ec88413SMauro Carvalho Chehab:: 550ec88413SMauro Carvalho Chehab 560ec88413SMauro Carvalho Chehab void (*dev_config) (struct ata_port *, struct ata_device *); 570ec88413SMauro Carvalho Chehab 580ec88413SMauro Carvalho Chehab 590ec88413SMauro Carvalho ChehabCalled after IDENTIFY [PACKET] DEVICE is issued to each device found. 600ec88413SMauro Carvalho ChehabTypically used to apply device-specific fixups prior to issue of SET 610ec88413SMauro Carvalho ChehabFEATURES - XFER MODE, and prior to operation. 620ec88413SMauro Carvalho Chehab 630ec88413SMauro Carvalho ChehabThis entry may be specified as NULL in ata_port_operations. 640ec88413SMauro Carvalho Chehab 650ec88413SMauro Carvalho ChehabSet PIO/DMA mode 660ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~ 670ec88413SMauro Carvalho Chehab 680ec88413SMauro Carvalho Chehab:: 690ec88413SMauro Carvalho Chehab 700ec88413SMauro Carvalho Chehab void (*set_piomode) (struct ata_port *, struct ata_device *); 710ec88413SMauro Carvalho Chehab void (*set_dmamode) (struct ata_port *, struct ata_device *); 720ec88413SMauro Carvalho Chehab void (*post_set_mode) (struct ata_port *); 730ec88413SMauro Carvalho Chehab unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int); 740ec88413SMauro Carvalho Chehab 750ec88413SMauro Carvalho Chehab 760ec88413SMauro Carvalho ChehabHooks called prior to the issue of SET FEATURES - XFER MODE command. The 776b46c2b1SMauro Carvalho Chehaboptional ``->mode_filter()`` hook is called when libata has built a mask of 786b46c2b1SMauro Carvalho Chehabthe possible modes. This is passed to the ``->mode_filter()`` function 790ec88413SMauro Carvalho Chehabwhich should return a mask of valid modes after filtering those 800ec88413SMauro Carvalho Chehabunsuitable due to hardware limits. It is not valid to use this interface 810ec88413SMauro Carvalho Chehabto add modes. 820ec88413SMauro Carvalho Chehab 836b46c2b1SMauro Carvalho Chehab``dev->pio_mode`` and ``dev->dma_mode`` are guaranteed to be valid when 846b46c2b1SMauro Carvalho Chehab``->set_piomode()`` and when ``->set_dmamode()`` is called. The timings for 850ec88413SMauro Carvalho Chehabany other drive sharing the cable will also be valid at this point. That 860ec88413SMauro Carvalho Chehabis the library records the decisions for the modes of each drive on a 870ec88413SMauro Carvalho Chehabchannel before it attempts to set any of them. 880ec88413SMauro Carvalho Chehab 896b46c2b1SMauro Carvalho Chehab``->post_set_mode()`` is called unconditionally, after the SET FEATURES - 900ec88413SMauro Carvalho ChehabXFER MODE command completes successfully. 910ec88413SMauro Carvalho Chehab 926b46c2b1SMauro Carvalho Chehab``->set_piomode()`` is always called (if present), but ``->set_dma_mode()`` 930ec88413SMauro Carvalho Chehabis only called if DMA is possible. 940ec88413SMauro Carvalho Chehab 950ec88413SMauro Carvalho ChehabTaskfile read/write 960ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~ 970ec88413SMauro Carvalho Chehab 980ec88413SMauro Carvalho Chehab:: 990ec88413SMauro Carvalho Chehab 1000ec88413SMauro Carvalho Chehab void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf); 1010ec88413SMauro Carvalho Chehab void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf); 1020ec88413SMauro Carvalho Chehab 1030ec88413SMauro Carvalho Chehab 1046b46c2b1SMauro Carvalho Chehab``->tf_load()`` is called to load the given taskfile into hardware 1056b46c2b1SMauro Carvalho Chehabregisters / DMA buffers. ``->tf_read()`` is called to read the hardware 1060ec88413SMauro Carvalho Chehabregisters / DMA buffers, to obtain the current set of taskfile register 1070ec88413SMauro Carvalho Chehabvalues. Most drivers for taskfile-based hardware (PIO or MMIO) use 1086b46c2b1SMauro Carvalho Chehab:c:func:`ata_sff_tf_load` and :c:func:`ata_sff_tf_read` for these hooks. 1090ec88413SMauro Carvalho Chehab 1100ec88413SMauro Carvalho ChehabPIO data read/write 1110ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~ 1120ec88413SMauro Carvalho Chehab 1130ec88413SMauro Carvalho Chehab:: 1140ec88413SMauro Carvalho Chehab 1150ec88413SMauro Carvalho Chehab void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int); 1160ec88413SMauro Carvalho Chehab 1170ec88413SMauro Carvalho Chehab 1180ec88413SMauro Carvalho ChehabAll bmdma-style drivers must implement this hook. This is the low-level 1190ec88413SMauro Carvalho Chehaboperation that actually copies the data bytes during a PIO data 1200ec88413SMauro Carvalho Chehabtransfer. Typically the driver will choose one of 12123ebda2fSSebastian Andrzej Siewior:c:func:`ata_sff_data_xfer`, or :c:func:`ata_sff_data_xfer32`. 1220ec88413SMauro Carvalho Chehab 1230ec88413SMauro Carvalho ChehabATA command execute 1240ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~ 1250ec88413SMauro Carvalho Chehab 1260ec88413SMauro Carvalho Chehab:: 1270ec88413SMauro Carvalho Chehab 1280ec88413SMauro Carvalho Chehab void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf); 1290ec88413SMauro Carvalho Chehab 1300ec88413SMauro Carvalho Chehab 1316b46c2b1SMauro Carvalho Chehabcauses an ATA command, previously loaded with ``->tf_load()``, to be 1320ec88413SMauro Carvalho Chehabinitiated in hardware. Most drivers for taskfile-based hardware use 1336b46c2b1SMauro Carvalho Chehab:c:func:`ata_sff_exec_command` for this hook. 1340ec88413SMauro Carvalho Chehab 1350ec88413SMauro Carvalho ChehabPer-cmd ATAPI DMA capabilities filter 1360ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1370ec88413SMauro Carvalho Chehab 1380ec88413SMauro Carvalho Chehab:: 1390ec88413SMauro Carvalho Chehab 1400ec88413SMauro Carvalho Chehab int (*check_atapi_dma) (struct ata_queued_cmd *qc); 1410ec88413SMauro Carvalho Chehab 1420ec88413SMauro Carvalho Chehab 1430ec88413SMauro Carvalho ChehabAllow low-level driver to filter ATA PACKET commands, returning a status 1440ec88413SMauro Carvalho Chehabindicating whether or not it is OK to use DMA for the supplied PACKET 1450ec88413SMauro Carvalho Chehabcommand. 1460ec88413SMauro Carvalho Chehab 1470ec88413SMauro Carvalho ChehabThis hook may be specified as NULL, in which case libata will assume 1480ec88413SMauro Carvalho Chehabthat atapi dma can be supported. 1490ec88413SMauro Carvalho Chehab 1500ec88413SMauro Carvalho ChehabRead specific ATA shadow registers 1510ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1520ec88413SMauro Carvalho Chehab 1530ec88413SMauro Carvalho Chehab:: 1540ec88413SMauro Carvalho Chehab 1550ec88413SMauro Carvalho Chehab u8 (*sff_check_status)(struct ata_port *ap); 1560ec88413SMauro Carvalho Chehab u8 (*sff_check_altstatus)(struct ata_port *ap); 1570ec88413SMauro Carvalho Chehab 1580ec88413SMauro Carvalho Chehab 1590ec88413SMauro Carvalho ChehabReads the Status/AltStatus ATA shadow register from hardware. On some 1600ec88413SMauro Carvalho Chehabhardware, reading the Status register has the side effect of clearing 1610ec88413SMauro Carvalho Chehabthe interrupt condition. Most drivers for taskfile-based hardware use 1626b46c2b1SMauro Carvalho Chehab:c:func:`ata_sff_check_status` for this hook. 1630ec88413SMauro Carvalho Chehab 1640ec88413SMauro Carvalho ChehabWrite specific ATA shadow register 1650ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1660ec88413SMauro Carvalho Chehab 1670ec88413SMauro Carvalho Chehab:: 1680ec88413SMauro Carvalho Chehab 1690ec88413SMauro Carvalho Chehab void (*sff_set_devctl)(struct ata_port *ap, u8 ctl); 1700ec88413SMauro Carvalho Chehab 1710ec88413SMauro Carvalho Chehab 1720ec88413SMauro Carvalho ChehabWrite the device control ATA shadow register to the hardware. Most 1730ec88413SMauro Carvalho Chehabdrivers don't need to define this. 1740ec88413SMauro Carvalho Chehab 1750ec88413SMauro Carvalho ChehabSelect ATA device on bus 1760ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~ 1770ec88413SMauro Carvalho Chehab 1780ec88413SMauro Carvalho Chehab:: 1790ec88413SMauro Carvalho Chehab 1800ec88413SMauro Carvalho Chehab void (*sff_dev_select)(struct ata_port *ap, unsigned int device); 1810ec88413SMauro Carvalho Chehab 1820ec88413SMauro Carvalho Chehab 1830ec88413SMauro Carvalho ChehabIssues the low-level hardware command(s) that causes one of N hardware 1840ec88413SMauro Carvalho Chehabdevices to be considered 'selected' (active and available for use) on 1850ec88413SMauro Carvalho Chehabthe ATA bus. This generally has no meaning on FIS-based devices. 1860ec88413SMauro Carvalho Chehab 1876b46c2b1SMauro Carvalho ChehabMost drivers for taskfile-based hardware use :c:func:`ata_sff_dev_select` for 1880ec88413SMauro Carvalho Chehabthis hook. 1890ec88413SMauro Carvalho Chehab 1900ec88413SMauro Carvalho ChehabPrivate tuning method 1910ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~ 1920ec88413SMauro Carvalho Chehab 1930ec88413SMauro Carvalho Chehab:: 1940ec88413SMauro Carvalho Chehab 1950ec88413SMauro Carvalho Chehab void (*set_mode) (struct ata_port *ap); 1960ec88413SMauro Carvalho Chehab 1970ec88413SMauro Carvalho Chehab 1980ec88413SMauro Carvalho ChehabBy default libata performs drive and controller tuning in accordance 1990ec88413SMauro Carvalho Chehabwith the ATA timing rules and also applies blacklists and cable limits. 2000ec88413SMauro Carvalho ChehabSome controllers need special handling and have custom tuning rules, 2010ec88413SMauro Carvalho Chehabtypically raid controllers that use ATA commands but do not actually do 2020ec88413SMauro Carvalho Chehabdrive timing. 2030ec88413SMauro Carvalho Chehab 2040ec88413SMauro Carvalho Chehab **Warning** 2050ec88413SMauro Carvalho Chehab 2060ec88413SMauro Carvalho Chehab This hook should not be used to replace the standard controller 2070ec88413SMauro Carvalho Chehab tuning logic when a controller has quirks. Replacing the default 2080ec88413SMauro Carvalho Chehab tuning logic in that case would bypass handling for drive and bridge 2090ec88413SMauro Carvalho Chehab quirks that may be important to data reliability. If a controller 2100ec88413SMauro Carvalho Chehab needs to filter the mode selection it should use the mode_filter 2110ec88413SMauro Carvalho Chehab hook instead. 2120ec88413SMauro Carvalho Chehab 2130ec88413SMauro Carvalho ChehabControl PCI IDE BMDMA engine 2140ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2150ec88413SMauro Carvalho Chehab 2160ec88413SMauro Carvalho Chehab:: 2170ec88413SMauro Carvalho Chehab 2180ec88413SMauro Carvalho Chehab void (*bmdma_setup) (struct ata_queued_cmd *qc); 2190ec88413SMauro Carvalho Chehab void (*bmdma_start) (struct ata_queued_cmd *qc); 2200ec88413SMauro Carvalho Chehab void (*bmdma_stop) (struct ata_port *ap); 2210ec88413SMauro Carvalho Chehab u8 (*bmdma_status) (struct ata_port *ap); 2220ec88413SMauro Carvalho Chehab 2230ec88413SMauro Carvalho Chehab 2240ec88413SMauro Carvalho ChehabWhen setting up an IDE BMDMA transaction, these hooks arm 2256b46c2b1SMauro Carvalho Chehab(``->bmdma_setup``), fire (``->bmdma_start``), and halt (``->bmdma_stop``) the 2266b46c2b1SMauro Carvalho Chehabhardware's DMA engine. ``->bmdma_status`` is used to read the standard PCI 2270ec88413SMauro Carvalho ChehabIDE DMA Status register. 2280ec88413SMauro Carvalho Chehab 2290ec88413SMauro Carvalho ChehabThese hooks are typically either no-ops, or simply not implemented, in 2300ec88413SMauro Carvalho ChehabFIS-based drivers. 2310ec88413SMauro Carvalho Chehab 2326b46c2b1SMauro Carvalho ChehabMost legacy IDE drivers use :c:func:`ata_bmdma_setup` for the 2336b46c2b1SMauro Carvalho Chehab:c:func:`bmdma_setup` hook. :c:func:`ata_bmdma_setup` will write the pointer 2346b46c2b1SMauro Carvalho Chehabto the PRD table to the IDE PRD Table Address register, enable DMA in the DMA 2356b46c2b1SMauro Carvalho ChehabCommand register, and call :c:func:`exec_command` to begin the transfer. 2360ec88413SMauro Carvalho Chehab 2376b46c2b1SMauro Carvalho ChehabMost legacy IDE drivers use :c:func:`ata_bmdma_start` for the 2386b46c2b1SMauro Carvalho Chehab:c:func:`bmdma_start` hook. :c:func:`ata_bmdma_start` will write the 2396b46c2b1SMauro Carvalho ChehabATA_DMA_START flag to the DMA Command register. 2400ec88413SMauro Carvalho Chehab 2416b46c2b1SMauro Carvalho ChehabMany legacy IDE drivers use :c:func:`ata_bmdma_stop` for the 2426b46c2b1SMauro Carvalho Chehab:c:func:`bmdma_stop` hook. :c:func:`ata_bmdma_stop` clears the ATA_DMA_START 2436b46c2b1SMauro Carvalho Chehabflag in the DMA command register. 2440ec88413SMauro Carvalho Chehab 2456b46c2b1SMauro Carvalho ChehabMany legacy IDE drivers use :c:func:`ata_bmdma_status` as the 2466b46c2b1SMauro Carvalho Chehab:c:func:`bmdma_status` hook. 2470ec88413SMauro Carvalho Chehab 2480ec88413SMauro Carvalho ChehabHigh-level taskfile hooks 2490ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~ 2500ec88413SMauro Carvalho Chehab 2510ec88413SMauro Carvalho Chehab:: 2520ec88413SMauro Carvalho Chehab 25395364f36SJiri Slaby enum ata_completion_errors (*qc_prep) (struct ata_queued_cmd *qc); 2540ec88413SMauro Carvalho Chehab int (*qc_issue) (struct ata_queued_cmd *qc); 2550ec88413SMauro Carvalho Chehab 2560ec88413SMauro Carvalho Chehab 2570fb596edSJiri SlabyHigher-level hooks, these two hooks can potentially supersede several of 2586b46c2b1SMauro Carvalho Chehabthe above taskfile/DMA engine hooks. ``->qc_prep`` is called after the 2590ec88413SMauro Carvalho Chehabbuffers have been DMA-mapped, and is typically used to populate the 2600fb596edSJiri Slabyhardware's DMA scatter-gather table. Some drivers use the standard 2610fb596edSJiri Slaby:c:func:`ata_bmdma_qc_prep` and :c:func:`ata_bmdma_dumb_qc_prep` helper 2620fb596edSJiri Slabyfunctions, but more advanced drivers roll their own. 2630ec88413SMauro Carvalho Chehab 2646b46c2b1SMauro Carvalho Chehab``->qc_issue`` is used to make a command active, once the hardware and S/G 2650ec88413SMauro Carvalho Chehabtables have been prepared. IDE BMDMA drivers use the helper function 2660fb596edSJiri Slaby:c:func:`ata_sff_qc_issue` for taskfile protocol-based dispatch. More 2676b46c2b1SMauro Carvalho Chehabadvanced drivers implement their own ``->qc_issue``. 2680ec88413SMauro Carvalho Chehab 2690fb596edSJiri Slaby:c:func:`ata_sff_qc_issue` calls ``->sff_tf_load()``, ``->bmdma_setup()``, and 2706b46c2b1SMauro Carvalho Chehab``->bmdma_start()`` as necessary to initiate a transfer. 2710ec88413SMauro Carvalho Chehab 2720ec88413SMauro Carvalho ChehabException and probe handling (EH) 2730ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2740ec88413SMauro Carvalho Chehab 2750ec88413SMauro Carvalho Chehab:: 2760ec88413SMauro Carvalho Chehab 2770ec88413SMauro Carvalho Chehab void (*eng_timeout) (struct ata_port *ap); 2780ec88413SMauro Carvalho Chehab void (*phy_reset) (struct ata_port *ap); 2790ec88413SMauro Carvalho Chehab 2800ec88413SMauro Carvalho Chehab 2816b46c2b1SMauro Carvalho ChehabDeprecated. Use ``->error_handler()`` instead. 2820ec88413SMauro Carvalho Chehab 2830ec88413SMauro Carvalho Chehab:: 2840ec88413SMauro Carvalho Chehab 2850ec88413SMauro Carvalho Chehab void (*freeze) (struct ata_port *ap); 2860ec88413SMauro Carvalho Chehab void (*thaw) (struct ata_port *ap); 2870ec88413SMauro Carvalho Chehab 2880ec88413SMauro Carvalho Chehab 2896b46c2b1SMauro Carvalho Chehab:c:func:`ata_port_freeze` is called when HSM violations or some other 2900ec88413SMauro Carvalho Chehabcondition disrupts normal operation of the port. A frozen port is not 2910ec88413SMauro Carvalho Chehaballowed to perform any operation until the port is thawed, which usually 2920ec88413SMauro Carvalho Chehabfollows a successful reset. 2930ec88413SMauro Carvalho Chehab 2946b46c2b1SMauro Carvalho ChehabThe optional ``->freeze()`` callback can be used for freezing the port 2950ec88413SMauro Carvalho Chehabhardware-wise (e.g. mask interrupt and stop DMA engine). If a port 2960ec88413SMauro Carvalho Chehabcannot be frozen hardware-wise, the interrupt handler must ack and clear 2970ec88413SMauro Carvalho Chehabinterrupts unconditionally while the port is frozen. 2980ec88413SMauro Carvalho Chehab 2996b46c2b1SMauro Carvalho ChehabThe optional ``->thaw()`` callback is called to perform the opposite of 3006b46c2b1SMauro Carvalho Chehab``->freeze()``: prepare the port for normal operation once again. Unmask 3010ec88413SMauro Carvalho Chehabinterrupts, start DMA engine, etc. 3020ec88413SMauro Carvalho Chehab 3030ec88413SMauro Carvalho Chehab:: 3040ec88413SMauro Carvalho Chehab 3050ec88413SMauro Carvalho Chehab void (*error_handler) (struct ata_port *ap); 3060ec88413SMauro Carvalho Chehab 3070ec88413SMauro Carvalho Chehab 3086b46c2b1SMauro Carvalho Chehab``->error_handler()`` is a driver's hook into probe, hotplug, and recovery 3090ec88413SMauro Carvalho Chehaband other exceptional conditions. The primary responsibility of an 3106b46c2b1SMauro Carvalho Chehabimplementation is to call :c:func:`ata_do_eh` or :c:func:`ata_bmdma_drive_eh` 3116b46c2b1SMauro Carvalho Chehabwith a set of EH hooks as arguments: 3120ec88413SMauro Carvalho Chehab 3130ec88413SMauro Carvalho Chehab'prereset' hook (may be NULL) is called during an EH reset, before any 3140ec88413SMauro Carvalho Chehabother actions are taken. 3150ec88413SMauro Carvalho Chehab 3160ec88413SMauro Carvalho Chehab'postreset' hook (may be NULL) is called after the EH reset is 3170ec88413SMauro Carvalho Chehabperformed. Based on existing conditions, severity of the problem, and 3180ec88413SMauro Carvalho Chehabhardware capabilities, 3190ec88413SMauro Carvalho Chehab 3200ec88413SMauro Carvalho ChehabEither 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be 3210ec88413SMauro Carvalho Chehabcalled to perform the low-level EH reset. 3220ec88413SMauro Carvalho Chehab 3230ec88413SMauro Carvalho Chehab:: 3240ec88413SMauro Carvalho Chehab 3250ec88413SMauro Carvalho Chehab void (*post_internal_cmd) (struct ata_queued_cmd *qc); 3260ec88413SMauro Carvalho Chehab 3270ec88413SMauro Carvalho Chehab 3280ec88413SMauro Carvalho ChehabPerform any hardware-specific actions necessary to finish processing 3290ec88413SMauro Carvalho Chehabafter executing a probe-time or EH-time command via 3306b46c2b1SMauro Carvalho Chehab:c:func:`ata_exec_internal`. 3310ec88413SMauro Carvalho Chehab 3320ec88413SMauro Carvalho ChehabHardware interrupt handling 3330ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3340ec88413SMauro Carvalho Chehab 3350ec88413SMauro Carvalho Chehab:: 3360ec88413SMauro Carvalho Chehab 3370ec88413SMauro Carvalho Chehab irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); 3380ec88413SMauro Carvalho Chehab void (*irq_clear) (struct ata_port *); 3390ec88413SMauro Carvalho Chehab 3400ec88413SMauro Carvalho Chehab 3416b46c2b1SMauro Carvalho Chehab``->irq_handler`` is the interrupt handling routine registered with the 3426b46c2b1SMauro Carvalho Chehabsystem, by libata. ``->irq_clear`` is called during probe just before the 3430ec88413SMauro Carvalho Chehabinterrupt handler is registered, to be sure hardware is quiet. 3440ec88413SMauro Carvalho Chehab 3450ec88413SMauro Carvalho ChehabThe second argument, dev_instance, should be cast to a pointer to 3466b46c2b1SMauro Carvalho Chehab:c:type:`struct ata_host_set <ata_host_set>`. 3470ec88413SMauro Carvalho Chehab 3486b46c2b1SMauro Carvalho ChehabMost legacy IDE drivers use :c:func:`ata_sff_interrupt` for the irq_handler 3490ec88413SMauro Carvalho Chehabhook, which scans all ports in the host_set, determines which queued 3500ec88413SMauro Carvalho Chehabcommand was active (if any), and calls ata_sff_host_intr(ap,qc). 3510ec88413SMauro Carvalho Chehab 3526b46c2b1SMauro Carvalho ChehabMost legacy IDE drivers use :c:func:`ata_sff_irq_clear` for the 3536b46c2b1SMauro Carvalho Chehab:c:func:`irq_clear` hook, which simply clears the interrupt and error flags 3546b46c2b1SMauro Carvalho Chehabin the DMA status register. 3550ec88413SMauro Carvalho Chehab 3560ec88413SMauro Carvalho ChehabSATA phy read/write 3570ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~ 3580ec88413SMauro Carvalho Chehab 3590ec88413SMauro Carvalho Chehab:: 3600ec88413SMauro Carvalho Chehab 3610ec88413SMauro Carvalho Chehab int (*scr_read) (struct ata_port *ap, unsigned int sc_reg, 3620ec88413SMauro Carvalho Chehab u32 *val); 3630ec88413SMauro Carvalho Chehab int (*scr_write) (struct ata_port *ap, unsigned int sc_reg, 3640ec88413SMauro Carvalho Chehab u32 val); 3650ec88413SMauro Carvalho Chehab 3660ec88413SMauro Carvalho Chehab 3670ec88413SMauro Carvalho ChehabRead and write standard SATA phy registers. Currently only used if 3686b46c2b1SMauro Carvalho Chehab``->phy_reset`` hook called the :c:func:`sata_phy_reset` helper function. 3696b46c2b1SMauro Carvalho Chehabsc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE. 3700ec88413SMauro Carvalho Chehab 3710ec88413SMauro Carvalho ChehabInit and shutdown 3720ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~ 3730ec88413SMauro Carvalho Chehab 3740ec88413SMauro Carvalho Chehab:: 3750ec88413SMauro Carvalho Chehab 3760ec88413SMauro Carvalho Chehab int (*port_start) (struct ata_port *ap); 3770ec88413SMauro Carvalho Chehab void (*port_stop) (struct ata_port *ap); 3780ec88413SMauro Carvalho Chehab void (*host_stop) (struct ata_host_set *host_set); 3790ec88413SMauro Carvalho Chehab 3800ec88413SMauro Carvalho Chehab 3816b46c2b1SMauro Carvalho Chehab``->port_start()`` is called just after the data structures for each port 3820ec88413SMauro Carvalho Chehabare initialized. Typically this is used to alloc per-port DMA buffers / 3830ec88413SMauro Carvalho Chehabtables / rings, enable DMA engines, and similar tasks. Some drivers also 3840ec88413SMauro Carvalho Chehabuse this entry point as a chance to allocate driver-private memory for 3856b46c2b1SMauro Carvalho Chehab``ap->private_data``. 3860ec88413SMauro Carvalho Chehab 3876b46c2b1SMauro Carvalho ChehabMany drivers use :c:func:`ata_port_start` as this hook or call it from their 3886b46c2b1SMauro Carvalho Chehabown :c:func:`port_start` hooks. :c:func:`ata_port_start` allocates space for 3896b46c2b1SMauro Carvalho Chehaba legacy IDE PRD table and returns. 3900ec88413SMauro Carvalho Chehab 3916b46c2b1SMauro Carvalho Chehab``->port_stop()`` is called after ``->host_stop()``. Its sole function is to 3920ec88413SMauro Carvalho Chehabrelease DMA/memory resources, now that they are no longer actively being 3930ec88413SMauro Carvalho Chehabused. Many drivers also free driver-private data from port at this time. 3940ec88413SMauro Carvalho Chehab 3956b46c2b1SMauro Carvalho Chehab``->host_stop()`` is called after all ``->port_stop()`` calls have completed. 3960ec88413SMauro Carvalho ChehabThe hook must finalize hardware shutdown, release DMA and other 3970ec88413SMauro Carvalho Chehabresources, etc. This hook may be specified as NULL, in which case it is 3980ec88413SMauro Carvalho Chehabnot called. 3990ec88413SMauro Carvalho Chehab 4000ec88413SMauro Carvalho ChehabError handling 4010ec88413SMauro Carvalho Chehab============== 4020ec88413SMauro Carvalho Chehab 4030ec88413SMauro Carvalho ChehabThis chapter describes how errors are handled under libata. Readers are 4040ec88413SMauro Carvalho Chehabadvised to read SCSI EH (Documentation/scsi/scsi_eh.txt) and ATA 4050ec88413SMauro Carvalho Chehabexceptions doc first. 4060ec88413SMauro Carvalho Chehab 4070ec88413SMauro Carvalho ChehabOrigins of commands 4080ec88413SMauro Carvalho Chehab------------------- 4090ec88413SMauro Carvalho Chehab 4106b46c2b1SMauro Carvalho ChehabIn libata, a command is represented with 4116b46c2b1SMauro Carvalho Chehab:c:type:`struct ata_queued_cmd <ata_queued_cmd>` or qc. 4120ec88413SMauro Carvalho Chehabqc's are preallocated during port initialization and repetitively used 4130ec88413SMauro Carvalho Chehabfor command executions. Currently only one qc is allocated per port but 4140ec88413SMauro Carvalho Chehabyet-to-be-merged NCQ branch allocates one for each tag and maps each qc 4150ec88413SMauro Carvalho Chehabto NCQ tag 1-to-1. 4160ec88413SMauro Carvalho Chehab 4170ec88413SMauro Carvalho Chehablibata commands can originate from two sources - libata itself and SCSI 4180ec88413SMauro Carvalho Chehabmidlayer. libata internal commands are used for initialization and error 4190ec88413SMauro Carvalho Chehabhandling. All normal blk requests and commands for SCSI emulation are 4200ec88413SMauro Carvalho Chehabpassed as SCSI commands through queuecommand callback of SCSI host 4210ec88413SMauro Carvalho Chehabtemplate. 4220ec88413SMauro Carvalho Chehab 4230ec88413SMauro Carvalho ChehabHow commands are issued 4240ec88413SMauro Carvalho Chehab----------------------- 4250ec88413SMauro Carvalho Chehab 4260ec88413SMauro Carvalho ChehabInternal commands 4276b46c2b1SMauro Carvalho Chehab First, qc is allocated and initialized using :c:func:`ata_qc_new_init`. 4286b46c2b1SMauro Carvalho Chehab Although :c:func:`ata_qc_new_init` doesn't implement any wait or retry 4290ec88413SMauro Carvalho Chehab mechanism when qc is not available, internal commands are currently 4300ec88413SMauro Carvalho Chehab issued only during initialization and error recovery, so no other 4310ec88413SMauro Carvalho Chehab command is active and allocation is guaranteed to succeed. 4320ec88413SMauro Carvalho Chehab 4330ec88413SMauro Carvalho Chehab Once allocated qc's taskfile is initialized for the command to be 4340ec88413SMauro Carvalho Chehab executed. qc currently has two mechanisms to notify completion. One 4356b46c2b1SMauro Carvalho Chehab is via ``qc->complete_fn()`` callback and the other is completion 4366b46c2b1SMauro Carvalho Chehab ``qc->waiting``. ``qc->complete_fn()`` callback is the asynchronous path 4376b46c2b1SMauro Carvalho Chehab used by normal SCSI translated commands and ``qc->waiting`` is the 4380ec88413SMauro Carvalho Chehab synchronous (issuer sleeps in process context) path used by internal 4390ec88413SMauro Carvalho Chehab commands. 4400ec88413SMauro Carvalho Chehab 4410ec88413SMauro Carvalho Chehab Once initialization is complete, host_set lock is acquired and the 4420ec88413SMauro Carvalho Chehab qc is issued. 4430ec88413SMauro Carvalho Chehab 4440ec88413SMauro Carvalho ChehabSCSI commands 4456b46c2b1SMauro Carvalho Chehab All libata drivers use :c:func:`ata_scsi_queuecmd` as 4466b46c2b1SMauro Carvalho Chehab ``hostt->queuecommand`` callback. scmds can either be simulated or 4476b46c2b1SMauro Carvalho Chehab translated. No qc is involved in processing a simulated scmd. The 4486b46c2b1SMauro Carvalho Chehab result is computed right away and the scmd is completed. 4490ec88413SMauro Carvalho Chehab 4506b46c2b1SMauro Carvalho Chehab For a translated scmd, :c:func:`ata_qc_new_init` is invoked to allocate a 4510ec88413SMauro Carvalho Chehab qc and the scmd is translated into the qc. SCSI midlayer's 4520ec88413SMauro Carvalho Chehab completion notification function pointer is stored into 4536b46c2b1SMauro Carvalho Chehab ``qc->scsidone``. 4540ec88413SMauro Carvalho Chehab 4556b46c2b1SMauro Carvalho Chehab ``qc->complete_fn()`` callback is used for completion notification. ATA 4566b46c2b1SMauro Carvalho Chehab commands use :c:func:`ata_scsi_qc_complete` while ATAPI commands use 4576b46c2b1SMauro Carvalho Chehab :c:func:`atapi_qc_complete`. Both functions end up calling ``qc->scsidone`` 4586b46c2b1SMauro Carvalho Chehab to notify upper layer when the qc is finished. After translation is 4596b46c2b1SMauro Carvalho Chehab completed, the qc is issued with :c:func:`ata_qc_issue`. 4600ec88413SMauro Carvalho Chehab 4610ec88413SMauro Carvalho Chehab Note that SCSI midlayer invokes hostt->queuecommand while holding 4620ec88413SMauro Carvalho Chehab host_set lock, so all above occur while holding host_set lock. 4630ec88413SMauro Carvalho Chehab 4640ec88413SMauro Carvalho ChehabHow commands are processed 4650ec88413SMauro Carvalho Chehab-------------------------- 4660ec88413SMauro Carvalho Chehab 4670ec88413SMauro Carvalho ChehabDepending on which protocol and which controller are used, commands are 4680ec88413SMauro Carvalho Chehabprocessed differently. For the purpose of discussion, a controller which 4690ec88413SMauro Carvalho Chehabuses taskfile interface and all standard callbacks is assumed. 4700ec88413SMauro Carvalho Chehab 4710ec88413SMauro Carvalho ChehabCurrently 6 ATA command protocols are used. They can be sorted into the 4720ec88413SMauro Carvalho Chehabfollowing four categories according to how they are processed. 4730ec88413SMauro Carvalho Chehab 4740ec88413SMauro Carvalho ChehabATA NO DATA or DMA 4750ec88413SMauro Carvalho Chehab ATA_PROT_NODATA and ATA_PROT_DMA fall into this category. These 4760ec88413SMauro Carvalho Chehab types of commands don't require any software intervention once 4770ec88413SMauro Carvalho Chehab issued. Device will raise interrupt on completion. 4780ec88413SMauro Carvalho Chehab 4790ec88413SMauro Carvalho ChehabATA PIO 4800ec88413SMauro Carvalho Chehab ATA_PROT_PIO is in this category. libata currently implements PIO 4810ec88413SMauro Carvalho Chehab with polling. ATA_NIEN bit is set to turn off interrupt and 4820ec88413SMauro Carvalho Chehab pio_task on ata_wq performs polling and IO. 4830ec88413SMauro Carvalho Chehab 4840ec88413SMauro Carvalho ChehabATAPI NODATA or DMA 4850ec88413SMauro Carvalho Chehab ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this 4860ec88413SMauro Carvalho Chehab category. packet_task is used to poll BSY bit after issuing PACKET 4870ec88413SMauro Carvalho Chehab command. Once BSY is turned off by the device, packet_task 4880ec88413SMauro Carvalho Chehab transfers CDB and hands off processing to interrupt handler. 4890ec88413SMauro Carvalho Chehab 4900ec88413SMauro Carvalho ChehabATAPI PIO 4910ec88413SMauro Carvalho Chehab ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set and, as 4920ec88413SMauro Carvalho Chehab in ATAPI NODATA or DMA, packet_task submits cdb. However, after 4930ec88413SMauro Carvalho Chehab submitting cdb, further processing (data transfer) is handed off to 4940ec88413SMauro Carvalho Chehab pio_task. 4950ec88413SMauro Carvalho Chehab 4960ec88413SMauro Carvalho ChehabHow commands are completed 4970ec88413SMauro Carvalho Chehab-------------------------- 4980ec88413SMauro Carvalho Chehab 4996b46c2b1SMauro Carvalho ChehabOnce issued, all qc's are either completed with :c:func:`ata_qc_complete` or 5000ec88413SMauro Carvalho Chehabtime out. For commands which are handled by interrupts, 5016b46c2b1SMauro Carvalho Chehab:c:func:`ata_host_intr` invokes :c:func:`ata_qc_complete`, and, for PIO tasks, 5026b46c2b1SMauro Carvalho Chehabpio_task invokes :c:func:`ata_qc_complete`. In error cases, packet_task may 5030ec88413SMauro Carvalho Chehabalso complete commands. 5040ec88413SMauro Carvalho Chehab 5056b46c2b1SMauro Carvalho Chehab:c:func:`ata_qc_complete` does the following. 5060ec88413SMauro Carvalho Chehab 5070ec88413SMauro Carvalho Chehab1. DMA memory is unmapped. 5080ec88413SMauro Carvalho Chehab 5090ec88413SMauro Carvalho Chehab2. ATA_QCFLAG_ACTIVE is cleared from qc->flags. 5100ec88413SMauro Carvalho Chehab 5116b46c2b1SMauro Carvalho Chehab3. :c:func:`qc->complete_fn` callback is invoked. If the return value of the 5120ec88413SMauro Carvalho Chehab callback is not zero. Completion is short circuited and 5136b46c2b1SMauro Carvalho Chehab :c:func:`ata_qc_complete` returns. 5140ec88413SMauro Carvalho Chehab 5156b46c2b1SMauro Carvalho Chehab4. :c:func:`__ata_qc_complete` is called, which does 5160ec88413SMauro Carvalho Chehab 5176b46c2b1SMauro Carvalho Chehab 1. ``qc->flags`` is cleared to zero. 5180ec88413SMauro Carvalho Chehab 5196b46c2b1SMauro Carvalho Chehab 2. ``ap->active_tag`` and ``qc->tag`` are poisoned. 5200ec88413SMauro Carvalho Chehab 5216b46c2b1SMauro Carvalho Chehab 3. ``qc->waiting`` is cleared & completed (in that order). 5220ec88413SMauro Carvalho Chehab 5236b46c2b1SMauro Carvalho Chehab 4. qc is deallocated by clearing appropriate bit in ``ap->qactive``. 5240ec88413SMauro Carvalho Chehab 5250ec88413SMauro Carvalho ChehabSo, it basically notifies upper layer and deallocates qc. One exception 5266b46c2b1SMauro Carvalho Chehabis short-circuit path in #3 which is used by :c:func:`atapi_qc_complete`. 5270ec88413SMauro Carvalho Chehab 5280ec88413SMauro Carvalho ChehabFor all non-ATAPI commands, whether it fails or not, almost the same 5290ec88413SMauro Carvalho Chehabcode path is taken and very little error handling takes place. A qc is 5300ec88413SMauro Carvalho Chehabcompleted with success status if it succeeded, with failed status 5310ec88413SMauro Carvalho Chehabotherwise. 5320ec88413SMauro Carvalho Chehab 5330ec88413SMauro Carvalho ChehabHowever, failed ATAPI commands require more handling as REQUEST SENSE is 5340ec88413SMauro Carvalho Chehabneeded to acquire sense data. If an ATAPI command fails, 5356b46c2b1SMauro Carvalho Chehab:c:func:`ata_qc_complete` is invoked with error status, which in turn invokes 5366b46c2b1SMauro Carvalho Chehab:c:func:`atapi_qc_complete` via ``qc->complete_fn()`` callback. 5370ec88413SMauro Carvalho Chehab 5386b46c2b1SMauro Carvalho ChehabThis makes :c:func:`atapi_qc_complete` set ``scmd->result`` to 5390ec88413SMauro Carvalho ChehabSAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As the 5406b46c2b1SMauro Carvalho Chehabsense data is empty but ``scmd->result`` is CHECK CONDITION, SCSI midlayer 5416b46c2b1SMauro Carvalho Chehabwill invoke EH for the scmd, and returning 1 makes :c:func:`ata_qc_complete` 5420ec88413SMauro Carvalho Chehabto return without deallocating the qc. This leads us to 5436b46c2b1SMauro Carvalho Chehab:c:func:`ata_scsi_error` with partially completed qc. 5440ec88413SMauro Carvalho Chehab 5456b46c2b1SMauro Carvalho Chehab:c:func:`ata_scsi_error` 5466b46c2b1SMauro Carvalho Chehab------------------------ 5470ec88413SMauro Carvalho Chehab 5486b46c2b1SMauro Carvalho Chehab:c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()`` 5490ec88413SMauro Carvalho Chehabfor libata. As discussed above, this will be entered in two cases - 5500ec88413SMauro Carvalho Chehabtimeout and ATAPI error completion. This function calls low level libata 5516b46c2b1SMauro Carvalho Chehabdriver's :c:func:`eng_timeout` callback, the standard callback for which is 5526b46c2b1SMauro Carvalho Chehab:c:func:`ata_eng_timeout`. It checks if a qc is active and calls 5536b46c2b1SMauro Carvalho Chehab:c:func:`ata_qc_timeout` on the qc if so. Actual error handling occurs in 5546b46c2b1SMauro Carvalho Chehab:c:func:`ata_qc_timeout`. 5550ec88413SMauro Carvalho Chehab 5566b46c2b1SMauro Carvalho ChehabIf EH is invoked for timeout, :c:func:`ata_qc_timeout` stops BMDMA and 5570ec88413SMauro Carvalho Chehabcompletes the qc. Note that as we're currently in EH, we cannot call 5580ec88413SMauro Carvalho Chehabscsi_done. As described in SCSI EH doc, a recovered scmd should be 5596b46c2b1SMauro Carvalho Chehabeither retried with :c:func:`scsi_queue_insert` or finished with 5606b46c2b1SMauro Carvalho Chehab:c:func:`scsi_finish_command`. Here, we override ``qc->scsidone`` with 5616b46c2b1SMauro Carvalho Chehab:c:func:`scsi_finish_command` and calls :c:func:`ata_qc_complete`. 5620ec88413SMauro Carvalho Chehab 5630ec88413SMauro Carvalho ChehabIf EH is invoked due to a failed ATAPI qc, the qc here is completed but 5640ec88413SMauro Carvalho Chehabnot deallocated. The purpose of this half-completion is to use the qc as 5650ec88413SMauro Carvalho Chehabplace holder to make EH code reach this place. This is a bit hackish, 5660ec88413SMauro Carvalho Chehabbut it works. 5670ec88413SMauro Carvalho Chehab 5680ec88413SMauro Carvalho ChehabOnce control reaches here, the qc is deallocated by invoking 5696b46c2b1SMauro Carvalho Chehab:c:func:`__ata_qc_complete` explicitly. Then, internal qc for REQUEST SENSE 5700ec88413SMauro Carvalho Chehabis issued. Once sense data is acquired, scmd is finished by directly 5716b46c2b1SMauro Carvalho Chehabinvoking :c:func:`scsi_finish_command` on the scmd. Note that as we already 5720ec88413SMauro Carvalho Chehabhave completed and deallocated the qc which was associated with the 5736b46c2b1SMauro Carvalho Chehabscmd, we don't need to/cannot call :c:func:`ata_qc_complete` again. 5740ec88413SMauro Carvalho Chehab 5750ec88413SMauro Carvalho ChehabProblems with the current EH 5760ec88413SMauro Carvalho Chehab---------------------------- 5770ec88413SMauro Carvalho Chehab 5780ec88413SMauro Carvalho Chehab- Error representation is too crude. Currently any and all error 5790ec88413SMauro Carvalho Chehab conditions are represented with ATA STATUS and ERROR registers. 5800ec88413SMauro Carvalho Chehab Errors which aren't ATA device errors are treated as ATA device 5810ec88413SMauro Carvalho Chehab errors by setting ATA_ERR bit. Better error descriptor which can 5820ec88413SMauro Carvalho Chehab properly represent ATA and other errors/exceptions is needed. 5830ec88413SMauro Carvalho Chehab 5840ec88413SMauro Carvalho Chehab- When handling timeouts, no action is taken to make device forget 5850ec88413SMauro Carvalho Chehab about the timed out command and ready for new commands. 5860ec88413SMauro Carvalho Chehab 5876b46c2b1SMauro Carvalho Chehab- EH handling via :c:func:`ata_scsi_error` is not properly protected from 5880ec88413SMauro Carvalho Chehab usual command processing. On EH entrance, the device is not in 5890ec88413SMauro Carvalho Chehab quiescent state. Timed out commands may succeed or fail any time. 5900ec88413SMauro Carvalho Chehab pio_task and atapi_task may still be running. 5910ec88413SMauro Carvalho Chehab 5920ec88413SMauro Carvalho Chehab- Too weak error recovery. Devices / controllers causing HSM mismatch 5930ec88413SMauro Carvalho Chehab errors and other errors quite often require reset to return to known 5940ec88413SMauro Carvalho Chehab state. Also, advanced error handling is necessary to support features 5950ec88413SMauro Carvalho Chehab like NCQ and hotplug. 5960ec88413SMauro Carvalho Chehab 5970ec88413SMauro Carvalho Chehab- ATA errors are directly handled in the interrupt handler and PIO 5980ec88413SMauro Carvalho Chehab errors in pio_task. This is problematic for advanced error handling 5990ec88413SMauro Carvalho Chehab for the following reasons. 6000ec88413SMauro Carvalho Chehab 6010ec88413SMauro Carvalho Chehab First, advanced error handling often requires context and internal qc 6020ec88413SMauro Carvalho Chehab execution. 6030ec88413SMauro Carvalho Chehab 6040ec88413SMauro Carvalho Chehab Second, even a simple failure (say, CRC error) needs information 6050ec88413SMauro Carvalho Chehab gathering and could trigger complex error handling (say, resetting & 6060ec88413SMauro Carvalho Chehab reconfiguring). Having multiple code paths to gather information, 6070ec88413SMauro Carvalho Chehab enter EH and trigger actions makes life painful. 6080ec88413SMauro Carvalho Chehab 6090ec88413SMauro Carvalho Chehab Third, scattered EH code makes implementing low level drivers 6100ec88413SMauro Carvalho Chehab difficult. Low level drivers override libata callbacks. If EH is 6110ec88413SMauro Carvalho Chehab scattered over several places, each affected callbacks should perform 6120ec88413SMauro Carvalho Chehab its part of error handling. This can be error prone and painful. 6130ec88413SMauro Carvalho Chehab 6140ec88413SMauro Carvalho Chehablibata Library 6150ec88413SMauro Carvalho Chehab============== 6160ec88413SMauro Carvalho Chehab 6170ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/libata-core.c 6180ec88413SMauro Carvalho Chehab :export: 6190ec88413SMauro Carvalho Chehab 6200ec88413SMauro Carvalho Chehablibata Core Internals 6210ec88413SMauro Carvalho Chehab===================== 6220ec88413SMauro Carvalho Chehab 6230ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/libata-core.c 6240ec88413SMauro Carvalho Chehab :internal: 6250ec88413SMauro Carvalho Chehab 6266b46c2b1SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/libata-eh.c 6276b46c2b1SMauro Carvalho Chehab 6280ec88413SMauro Carvalho Chehablibata SCSI translation/emulation 6290ec88413SMauro Carvalho Chehab================================= 6300ec88413SMauro Carvalho Chehab 6310ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/libata-scsi.c 6320ec88413SMauro Carvalho Chehab :export: 6330ec88413SMauro Carvalho Chehab 6340ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/libata-scsi.c 6350ec88413SMauro Carvalho Chehab :internal: 6360ec88413SMauro Carvalho Chehab 6370ec88413SMauro Carvalho ChehabATA errors and exceptions 6380ec88413SMauro Carvalho Chehab========================= 6390ec88413SMauro Carvalho Chehab 6400ec88413SMauro Carvalho ChehabThis chapter tries to identify what error/exception conditions exist for 6410ec88413SMauro Carvalho ChehabATA/ATAPI devices and describe how they should be handled in 6420ec88413SMauro Carvalho Chehabimplementation-neutral way. 6430ec88413SMauro Carvalho Chehab 6440ec88413SMauro Carvalho ChehabThe term 'error' is used to describe conditions where either an explicit 6450ec88413SMauro Carvalho Chehaberror condition is reported from device or a command has timed out. 6460ec88413SMauro Carvalho Chehab 6470ec88413SMauro Carvalho ChehabThe term 'exception' is either used to describe exceptional conditions 6480ec88413SMauro Carvalho Chehabwhich are not errors (say, power or hotplug events), or to describe both 6490ec88413SMauro Carvalho Chehaberrors and non-error exceptional conditions. Where explicit distinction 6500ec88413SMauro Carvalho Chehabbetween error and exception is necessary, the term 'non-error exception' 6510ec88413SMauro Carvalho Chehabis used. 6520ec88413SMauro Carvalho Chehab 6530ec88413SMauro Carvalho ChehabException categories 6540ec88413SMauro Carvalho Chehab-------------------- 6550ec88413SMauro Carvalho Chehab 6560ec88413SMauro Carvalho ChehabExceptions are described primarily with respect to legacy taskfile + bus 6570ec88413SMauro Carvalho Chehabmaster IDE interface. If a controller provides other better mechanism 6580ec88413SMauro Carvalho Chehabfor error reporting, mapping those into categories described below 6590ec88413SMauro Carvalho Chehabshouldn't be difficult. 6600ec88413SMauro Carvalho Chehab 6610ec88413SMauro Carvalho ChehabIn the following sections, two recovery actions - reset and 6620ec88413SMauro Carvalho Chehabreconfiguring transport - are mentioned. These are described further in 6630ec88413SMauro Carvalho Chehab`EH recovery actions <#exrec>`__. 6640ec88413SMauro Carvalho Chehab 6650ec88413SMauro Carvalho ChehabHSM violation 6660ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~ 6670ec88413SMauro Carvalho Chehab 6680ec88413SMauro Carvalho ChehabThis error is indicated when STATUS value doesn't match HSM requirement 6690ec88413SMauro Carvalho Chehabduring issuing or execution any ATA/ATAPI command. 6700ec88413SMauro Carvalho Chehab 6710ec88413SMauro Carvalho Chehab- ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying to 6720ec88413SMauro Carvalho Chehab issue a command. 6730ec88413SMauro Carvalho Chehab 6740ec88413SMauro Carvalho Chehab- !BSY && !DRQ during PIO data transfer. 6750ec88413SMauro Carvalho Chehab 6760ec88413SMauro Carvalho Chehab- DRQ on command completion. 6770ec88413SMauro Carvalho Chehab 6780ec88413SMauro Carvalho Chehab- !BSY && ERR after CDB transfer starts but before the last byte of CDB 6790ec88413SMauro Carvalho Chehab is transferred. ATA/ATAPI standard states that "The device shall not 6800ec88413SMauro Carvalho Chehab terminate the PACKET command with an error before the last byte of 6810ec88413SMauro Carvalho Chehab the command packet has been written" in the error outputs description 6820ec88413SMauro Carvalho Chehab of PACKET command and the state diagram doesn't include such 6830ec88413SMauro Carvalho Chehab transitions. 6840ec88413SMauro Carvalho Chehab 6850ec88413SMauro Carvalho ChehabIn these cases, HSM is violated and not much information regarding the 6860ec88413SMauro Carvalho Chehaberror can be acquired from STATUS or ERROR register. IOW, this error can 6870ec88413SMauro Carvalho Chehabbe anything - driver bug, faulty device, controller and/or cable. 6880ec88413SMauro Carvalho Chehab 6890ec88413SMauro Carvalho ChehabAs HSM is violated, reset is necessary to restore known state. 6900ec88413SMauro Carvalho ChehabReconfiguring transport for lower speed might be helpful too as 6910ec88413SMauro Carvalho Chehabtransmission errors sometimes cause this kind of errors. 6920ec88413SMauro Carvalho Chehab 6930ec88413SMauro Carvalho ChehabATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) 6940ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 6950ec88413SMauro Carvalho Chehab 6960ec88413SMauro Carvalho ChehabThese are errors detected and reported by ATA/ATAPI devices indicating 6970ec88413SMauro Carvalho Chehabdevice problems. For this type of errors, STATUS and ERROR register 6980ec88413SMauro Carvalho Chehabvalues are valid and describe error condition. Note that some of ATA bus 6990ec88413SMauro Carvalho Chehaberrors are detected by ATA/ATAPI devices and reported using the same 7000ec88413SMauro Carvalho Chehabmechanism as device errors. Those cases are described later in this 7010ec88413SMauro Carvalho Chehabsection. 7020ec88413SMauro Carvalho Chehab 7030ec88413SMauro Carvalho ChehabFor ATA commands, this type of errors are indicated by !BSY && ERR 7040ec88413SMauro Carvalho Chehabduring command execution and on completion. 7050ec88413SMauro Carvalho Chehab 7060ec88413SMauro Carvalho ChehabFor ATAPI commands, 7070ec88413SMauro Carvalho Chehab 7080ec88413SMauro Carvalho Chehab- !BSY && ERR && ABRT right after issuing PACKET indicates that PACKET 7090ec88413SMauro Carvalho Chehab command is not supported and falls in this category. 7100ec88413SMauro Carvalho Chehab 7110ec88413SMauro Carvalho Chehab- !BSY && ERR(==CHK) && !ABRT after the last byte of CDB is transferred 7120ec88413SMauro Carvalho Chehab indicates CHECK CONDITION and doesn't fall in this category. 7130ec88413SMauro Carvalho Chehab 7140ec88413SMauro Carvalho Chehab- !BSY && ERR(==CHK) && ABRT after the last byte of CDB is transferred 7150ec88413SMauro Carvalho Chehab \*probably\* indicates CHECK CONDITION and doesn't fall in this 7160ec88413SMauro Carvalho Chehab category. 7170ec88413SMauro Carvalho Chehab 7180ec88413SMauro Carvalho ChehabOf errors detected as above, the following are not ATA/ATAPI device 7190ec88413SMauro Carvalho Chehaberrors but ATA bus errors and should be handled according to 7200ec88413SMauro Carvalho Chehab`ATA bus error <#excatATAbusErr>`__. 7210ec88413SMauro Carvalho Chehab 7220ec88413SMauro Carvalho ChehabCRC error during data transfer 7230ec88413SMauro Carvalho Chehab This is indicated by ICRC bit in the ERROR register and means that 7240ec88413SMauro Carvalho Chehab corruption occurred during data transfer. Up to ATA/ATAPI-7, the 7250ec88413SMauro Carvalho Chehab standard specifies that this bit is only applicable to UDMA 7260ec88413SMauro Carvalho Chehab transfers but ATA/ATAPI-8 draft revision 1f says that the bit may be 7270ec88413SMauro Carvalho Chehab applicable to multiword DMA and PIO. 7280ec88413SMauro Carvalho Chehab 7290ec88413SMauro Carvalho ChehabABRT error during data transfer or on completion 7300ec88413SMauro Carvalho Chehab Up to ATA/ATAPI-7, the standard specifies that ABRT could be set on 7310ec88413SMauro Carvalho Chehab ICRC errors and on cases where a device is not able to complete a 7320ec88413SMauro Carvalho Chehab command. Combined with the fact that MWDMA and PIO transfer errors 7330ec88413SMauro Carvalho Chehab aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply 7340ec88413SMauro Carvalho Chehab that ABRT bit alone could indicate transfer errors. 7350ec88413SMauro Carvalho Chehab 7360ec88413SMauro Carvalho Chehab However, ATA/ATAPI-8 draft revision 1f removes the part that ICRC 7370ec88413SMauro Carvalho Chehab errors can turn on ABRT. So, this is kind of gray area. Some 7380ec88413SMauro Carvalho Chehab heuristics are needed here. 7390ec88413SMauro Carvalho Chehab 7400ec88413SMauro Carvalho ChehabATA/ATAPI device errors can be further categorized as follows. 7410ec88413SMauro Carvalho Chehab 7420ec88413SMauro Carvalho ChehabMedia errors 7430ec88413SMauro Carvalho Chehab This is indicated by UNC bit in the ERROR register. ATA devices 7440ec88413SMauro Carvalho Chehab reports UNC error only after certain number of retries cannot 7450ec88413SMauro Carvalho Chehab recover the data, so there's nothing much else to do other than 7460ec88413SMauro Carvalho Chehab notifying upper layer. 7470ec88413SMauro Carvalho Chehab 7480ec88413SMauro Carvalho Chehab READ and WRITE commands report CHS or LBA of the first failed sector 7490ec88413SMauro Carvalho Chehab but ATA/ATAPI standard specifies that the amount of transferred data 7500ec88413SMauro Carvalho Chehab on error completion is indeterminate, so we cannot assume that 7510ec88413SMauro Carvalho Chehab sectors preceding the failed sector have been transferred and thus 7520ec88413SMauro Carvalho Chehab cannot complete those sectors successfully as SCSI does. 7530ec88413SMauro Carvalho Chehab 7540ec88413SMauro Carvalho ChehabMedia changed / media change requested error 7550ec88413SMauro Carvalho Chehab <<TODO: fill here>> 7560ec88413SMauro Carvalho Chehab 7570ec88413SMauro Carvalho ChehabAddress error 7580ec88413SMauro Carvalho Chehab This is indicated by IDNF bit in the ERROR register. Report to upper 7590ec88413SMauro Carvalho Chehab layer. 7600ec88413SMauro Carvalho Chehab 7610ec88413SMauro Carvalho ChehabOther errors 7620ec88413SMauro Carvalho Chehab This can be invalid command or parameter indicated by ABRT ERROR bit 7630ec88413SMauro Carvalho Chehab or some other error condition. Note that ABRT bit can indicate a lot 7640ec88413SMauro Carvalho Chehab of things including ICRC and Address errors. Heuristics needed. 7650ec88413SMauro Carvalho Chehab 7660ec88413SMauro Carvalho ChehabDepending on commands, not all STATUS/ERROR bits are applicable. These 7670ec88413SMauro Carvalho Chehabnon-applicable bits are marked with "na" in the output descriptions but 7680ec88413SMauro Carvalho Chehabup to ATA/ATAPI-7 no definition of "na" can be found. However, 7690ec88413SMauro Carvalho ChehabATA/ATAPI-8 draft revision 1f describes "N/A" as follows. 7700ec88413SMauro Carvalho Chehab 7710ec88413SMauro Carvalho Chehab 3.2.3.3a N/A 7720ec88413SMauro Carvalho Chehab A keyword the indicates a field has no defined value in this 7730ec88413SMauro Carvalho Chehab standard and should not be checked by the host or device. N/A 7740ec88413SMauro Carvalho Chehab fields should be cleared to zero. 7750ec88413SMauro Carvalho Chehab 7760ec88413SMauro Carvalho ChehabSo, it seems reasonable to assume that "na" bits are cleared to zero by 7770ec88413SMauro Carvalho Chehabdevices and thus need no explicit masking. 7780ec88413SMauro Carvalho Chehab 7790ec88413SMauro Carvalho ChehabATAPI device CHECK CONDITION 7800ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 7810ec88413SMauro Carvalho Chehab 7820ec88413SMauro Carvalho ChehabATAPI device CHECK CONDITION error is indicated by set CHK bit (ERR bit) 7830ec88413SMauro Carvalho Chehabin the STATUS register after the last byte of CDB is transferred for a 7840ec88413SMauro Carvalho ChehabPACKET command. For this kind of errors, sense data should be acquired 7850ec88413SMauro Carvalho Chehabto gather information regarding the errors. REQUEST SENSE packet command 7860ec88413SMauro Carvalho Chehabshould be used to acquire sense data. 7870ec88413SMauro Carvalho Chehab 7880ec88413SMauro Carvalho ChehabOnce sense data is acquired, this type of errors can be handled 7890ec88413SMauro Carvalho Chehabsimilarly to other SCSI errors. Note that sense data may indicate ATA 7900ec88413SMauro Carvalho Chehabbus error (e.g. Sense Key 04h HARDWARE ERROR && ASC/ASCQ 47h/00h SCSI 7910ec88413SMauro Carvalho ChehabPARITY ERROR). In such cases, the error should be considered as an ATA 7920ec88413SMauro Carvalho Chehabbus error and handled according to `ATA bus error <#excatATAbusErr>`__. 7930ec88413SMauro Carvalho Chehab 7940ec88413SMauro Carvalho ChehabATA device error (NCQ) 7950ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~ 7960ec88413SMauro Carvalho Chehab 7970ec88413SMauro Carvalho ChehabNCQ command error is indicated by cleared BSY and set ERR bit during NCQ 7980ec88413SMauro Carvalho Chehabcommand phase (one or more NCQ commands outstanding). Although STATUS 7990ec88413SMauro Carvalho Chehaband ERROR registers will contain valid values describing the error, READ 8000ec88413SMauro Carvalho ChehabLOG EXT is required to clear the error condition, determine which 8010ec88413SMauro Carvalho Chehabcommand has failed and acquire more information. 8020ec88413SMauro Carvalho Chehab 8030ec88413SMauro Carvalho ChehabREAD LOG EXT Log Page 10h reports which tag has failed and taskfile 8040ec88413SMauro Carvalho Chehabregister values describing the error. With this information the failed 8050ec88413SMauro Carvalho Chehabcommand can be handled as a normal ATA command error as in 8060ec88413SMauro Carvalho Chehab`ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__ 8070ec88413SMauro Carvalho Chehaband all other in-flight commands must be retried. Note that this retry 8080ec88413SMauro Carvalho Chehabshould not be counted - it's likely that commands retried this way would 8090ec88413SMauro Carvalho Chehabhave completed normally if it were not for the failed command. 8100ec88413SMauro Carvalho Chehab 8110ec88413SMauro Carvalho ChehabNote that ATA bus errors can be reported as ATA device NCQ errors. This 8120ec88413SMauro Carvalho Chehabshould be handled as described in `ATA bus error <#excatATAbusErr>`__. 8130ec88413SMauro Carvalho Chehab 8140ec88413SMauro Carvalho ChehabIf READ LOG EXT Log Page 10h fails or reports NQ, we're thoroughly 8150ec88413SMauro Carvalho Chehabscrewed. This condition should be treated according to 8160ec88413SMauro Carvalho Chehab`HSM violation <#excatHSMviolation>`__. 8170ec88413SMauro Carvalho Chehab 8180ec88413SMauro Carvalho ChehabATA bus error 8190ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~ 8200ec88413SMauro Carvalho Chehab 8210ec88413SMauro Carvalho ChehabATA bus error means that data corruption occurred during transmission 8220ec88413SMauro Carvalho Chehabover ATA bus (SATA or PATA). This type of errors can be indicated by 8230ec88413SMauro Carvalho Chehab 8240ec88413SMauro Carvalho Chehab- ICRC or ABRT error as described in 8250ec88413SMauro Carvalho Chehab `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__. 8260ec88413SMauro Carvalho Chehab 8270ec88413SMauro Carvalho Chehab- Controller-specific error completion with error information 8280ec88413SMauro Carvalho Chehab indicating transmission error. 8290ec88413SMauro Carvalho Chehab 8300ec88413SMauro Carvalho Chehab- On some controllers, command timeout. In this case, there may be a 8310ec88413SMauro Carvalho Chehab mechanism to determine that the timeout is due to transmission error. 8320ec88413SMauro Carvalho Chehab 8330ec88413SMauro Carvalho Chehab- Unknown/random errors, timeouts and all sorts of weirdities. 8340ec88413SMauro Carvalho Chehab 8350ec88413SMauro Carvalho ChehabAs described above, transmission errors can cause wide variety of 8360ec88413SMauro Carvalho Chehabsymptoms ranging from device ICRC error to random device lockup, and, 8370ec88413SMauro Carvalho Chehabfor many cases, there is no way to tell if an error condition is due to 8380ec88413SMauro Carvalho Chehabtransmission error or not; therefore, it's necessary to employ some kind 8390ec88413SMauro Carvalho Chehabof heuristic when dealing with errors and timeouts. For example, 8400ec88413SMauro Carvalho Chehabencountering repetitive ABRT errors for known supported command is 8410ec88413SMauro Carvalho Chehablikely to indicate ATA bus error. 8420ec88413SMauro Carvalho Chehab 8430ec88413SMauro Carvalho ChehabOnce it's determined that ATA bus errors have possibly occurred, 8440ec88413SMauro Carvalho Chehablowering ATA bus transmission speed is one of actions which may 8450ec88413SMauro Carvalho Chehaballeviate the problem. See `Reconfigure transport <#exrecReconf>`__ for 8460ec88413SMauro Carvalho Chehabmore information. 8470ec88413SMauro Carvalho Chehab 8480ec88413SMauro Carvalho ChehabPCI bus error 8490ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~ 8500ec88413SMauro Carvalho Chehab 8510ec88413SMauro Carvalho ChehabData corruption or other failures during transmission over PCI (or other 8520ec88413SMauro Carvalho Chehabsystem bus). For standard BMDMA, this is indicated by Error bit in the 8530ec88413SMauro Carvalho ChehabBMDMA Status register. This type of errors must be logged as it 8540ec88413SMauro Carvalho Chehabindicates something is very wrong with the system. Resetting host 8550ec88413SMauro Carvalho Chehabcontroller is recommended. 8560ec88413SMauro Carvalho Chehab 8570ec88413SMauro Carvalho ChehabLate completion 8580ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~ 8590ec88413SMauro Carvalho Chehab 8600ec88413SMauro Carvalho ChehabThis occurs when timeout occurs and the timeout handler finds out that 8610ec88413SMauro Carvalho Chehabthe timed out command has completed successfully or with error. This is 8620ec88413SMauro Carvalho Chehabusually caused by lost interrupts. This type of errors must be logged. 8630ec88413SMauro Carvalho ChehabResetting host controller is recommended. 8640ec88413SMauro Carvalho Chehab 8650ec88413SMauro Carvalho ChehabUnknown error (timeout) 8660ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~ 8670ec88413SMauro Carvalho Chehab 8680ec88413SMauro Carvalho ChehabThis is when timeout occurs and the command is still processing or the 8690ec88413SMauro Carvalho Chehabhost and device are in unknown state. When this occurs, HSM could be in 8700ec88413SMauro Carvalho Chehabany valid or invalid state. To bring the device to known state and make 8710ec88413SMauro Carvalho Chehabit forget about the timed out command, resetting is necessary. The timed 8720ec88413SMauro Carvalho Chehabout command may be retried. 8730ec88413SMauro Carvalho Chehab 8740ec88413SMauro Carvalho ChehabTimeouts can also be caused by transmission errors. Refer to 8750ec88413SMauro Carvalho Chehab`ATA bus error <#excatATAbusErr>`__ for more details. 8760ec88413SMauro Carvalho Chehab 8770ec88413SMauro Carvalho ChehabHotplug and power management exceptions 8780ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 8790ec88413SMauro Carvalho Chehab 8800ec88413SMauro Carvalho Chehab<<TODO: fill here>> 8810ec88413SMauro Carvalho Chehab 8820ec88413SMauro Carvalho ChehabEH recovery actions 8830ec88413SMauro Carvalho Chehab------------------- 8840ec88413SMauro Carvalho Chehab 8850ec88413SMauro Carvalho ChehabThis section discusses several important recovery actions. 8860ec88413SMauro Carvalho Chehab 8870ec88413SMauro Carvalho ChehabClearing error condition 8880ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~ 8890ec88413SMauro Carvalho Chehab 8900ec88413SMauro Carvalho ChehabMany controllers require its error registers to be cleared by error 8910ec88413SMauro Carvalho Chehabhandler. Different controllers may have different requirements. 8920ec88413SMauro Carvalho Chehab 8930ec88413SMauro Carvalho ChehabFor SATA, it's strongly recommended to clear at least SError register 8940ec88413SMauro Carvalho Chehabduring error handling. 8950ec88413SMauro Carvalho Chehab 8960ec88413SMauro Carvalho ChehabReset 8970ec88413SMauro Carvalho Chehab~~~~~ 8980ec88413SMauro Carvalho Chehab 8990ec88413SMauro Carvalho ChehabDuring EH, resetting is necessary in the following cases. 9000ec88413SMauro Carvalho Chehab 9010ec88413SMauro Carvalho Chehab- HSM is in unknown or invalid state 9020ec88413SMauro Carvalho Chehab 9030ec88413SMauro Carvalho Chehab- HBA is in unknown or invalid state 9040ec88413SMauro Carvalho Chehab 9050ec88413SMauro Carvalho Chehab- EH needs to make HBA/device forget about in-flight commands 9060ec88413SMauro Carvalho Chehab 9070ec88413SMauro Carvalho Chehab- HBA/device behaves weirdly 9080ec88413SMauro Carvalho Chehab 9090ec88413SMauro Carvalho ChehabResetting during EH might be a good idea regardless of error condition 9100ec88413SMauro Carvalho Chehabto improve EH robustness. Whether to reset both or either one of HBA and 9110ec88413SMauro Carvalho Chehabdevice depends on situation but the following scheme is recommended. 9120ec88413SMauro Carvalho Chehab 9130ec88413SMauro Carvalho Chehab- When it's known that HBA is in ready state but ATA/ATAPI device is in 9140ec88413SMauro Carvalho Chehab unknown state, reset only device. 9150ec88413SMauro Carvalho Chehab 9160ec88413SMauro Carvalho Chehab- If HBA is in unknown state, reset both HBA and device. 9170ec88413SMauro Carvalho Chehab 9180ec88413SMauro Carvalho ChehabHBA resetting is implementation specific. For a controller complying to 9190ec88413SMauro Carvalho Chehabtaskfile/BMDMA PCI IDE, stopping active DMA transaction may be 9200ec88413SMauro Carvalho Chehabsufficient iff BMDMA state is the only HBA context. But even mostly 9210ec88413SMauro Carvalho Chehabtaskfile/BMDMA PCI IDE complying controllers may have implementation 9220ec88413SMauro Carvalho Chehabspecific requirements and mechanism to reset themselves. This must be 9230ec88413SMauro Carvalho Chehabaddressed by specific drivers. 9240ec88413SMauro Carvalho Chehab 9250ec88413SMauro Carvalho ChehabOTOH, ATA/ATAPI standard describes in detail ways to reset ATA/ATAPI 9260ec88413SMauro Carvalho Chehabdevices. 9270ec88413SMauro Carvalho Chehab 9280ec88413SMauro Carvalho ChehabPATA hardware reset 9290ec88413SMauro Carvalho Chehab This is hardware initiated device reset signalled with asserted PATA 9300ec88413SMauro Carvalho Chehab RESET- signal. There is no standard way to initiate hardware reset 9310ec88413SMauro Carvalho Chehab from software although some hardware provides registers that allow 9320ec88413SMauro Carvalho Chehab driver to directly tweak the RESET- signal. 9330ec88413SMauro Carvalho Chehab 9340ec88413SMauro Carvalho ChehabSoftware reset 9350ec88413SMauro Carvalho Chehab This is achieved by turning CONTROL SRST bit on for at least 5us. 9360ec88413SMauro Carvalho Chehab Both PATA and SATA support it but, in case of SATA, this may require 9370ec88413SMauro Carvalho Chehab controller-specific support as the second Register FIS to clear SRST 9380ec88413SMauro Carvalho Chehab should be transmitted while BSY bit is still set. Note that on PATA, 9390ec88413SMauro Carvalho Chehab this resets both master and slave devices on a channel. 9400ec88413SMauro Carvalho Chehab 9410ec88413SMauro Carvalho ChehabEXECUTE DEVICE DIAGNOSTIC command 9420ec88413SMauro Carvalho Chehab Although ATA/ATAPI standard doesn't describe exactly, EDD implies 9430ec88413SMauro Carvalho Chehab some level of resetting, possibly similar level with software reset. 9440ec88413SMauro Carvalho Chehab Host-side EDD protocol can be handled with normal command processing 9450ec88413SMauro Carvalho Chehab and most SATA controllers should be able to handle EDD's just like 9460ec88413SMauro Carvalho Chehab other commands. As in software reset, EDD affects both devices on a 9470ec88413SMauro Carvalho Chehab PATA bus. 9480ec88413SMauro Carvalho Chehab 9490ec88413SMauro Carvalho Chehab Although EDD does reset devices, this doesn't suit error handling as 9500ec88413SMauro Carvalho Chehab EDD cannot be issued while BSY is set and it's unclear how it will 9510ec88413SMauro Carvalho Chehab act when device is in unknown/weird state. 9520ec88413SMauro Carvalho Chehab 9530ec88413SMauro Carvalho ChehabATAPI DEVICE RESET command 9540ec88413SMauro Carvalho Chehab This is very similar to software reset except that reset can be 9550ec88413SMauro Carvalho Chehab restricted to the selected device without affecting the other device 9560ec88413SMauro Carvalho Chehab sharing the cable. 9570ec88413SMauro Carvalho Chehab 9580ec88413SMauro Carvalho ChehabSATA phy reset 9590ec88413SMauro Carvalho Chehab This is the preferred way of resetting a SATA device. In effect, 9600ec88413SMauro Carvalho Chehab it's identical to PATA hardware reset. Note that this can be done 9610ec88413SMauro Carvalho Chehab with the standard SCR Control register. As such, it's usually easier 9620ec88413SMauro Carvalho Chehab to implement than software reset. 9630ec88413SMauro Carvalho Chehab 9640ec88413SMauro Carvalho ChehabOne more thing to consider when resetting devices is that resetting 9650ec88413SMauro Carvalho Chehabclears certain configuration parameters and they need to be set to their 9660ec88413SMauro Carvalho Chehabprevious or newly adjusted values after reset. 9670ec88413SMauro Carvalho Chehab 9680ec88413SMauro Carvalho ChehabParameters affected are. 9690ec88413SMauro Carvalho Chehab 9700ec88413SMauro Carvalho Chehab- CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used) 9710ec88413SMauro Carvalho Chehab 9720ec88413SMauro Carvalho Chehab- Parameters set with SET FEATURES including transfer mode setting 9730ec88413SMauro Carvalho Chehab 9740ec88413SMauro Carvalho Chehab- Block count set with SET MULTIPLE MODE 9750ec88413SMauro Carvalho Chehab 9760ec88413SMauro Carvalho Chehab- Other parameters (SET MAX, MEDIA LOCK...) 9770ec88413SMauro Carvalho Chehab 9780ec88413SMauro Carvalho ChehabATA/ATAPI standard specifies that some parameters must be maintained 9790ec88413SMauro Carvalho Chehabacross hardware or software reset, but doesn't strictly specify all of 9800ec88413SMauro Carvalho Chehabthem. Always reconfiguring needed parameters after reset is required for 9810ec88413SMauro Carvalho Chehabrobustness. Note that this also applies when resuming from deep sleep 9820ec88413SMauro Carvalho Chehab(power-off). 9830ec88413SMauro Carvalho Chehab 9840ec88413SMauro Carvalho ChehabAlso, ATA/ATAPI standard requires that IDENTIFY DEVICE / IDENTIFY PACKET 9850ec88413SMauro Carvalho ChehabDEVICE is issued after any configuration parameter is updated or a 9860ec88413SMauro Carvalho Chehabhardware reset and the result used for further operation. OS driver is 9870ec88413SMauro Carvalho Chehabrequired to implement revalidation mechanism to support this. 9880ec88413SMauro Carvalho Chehab 9890ec88413SMauro Carvalho ChehabReconfigure transport 9900ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~ 9910ec88413SMauro Carvalho Chehab 9920ec88413SMauro Carvalho ChehabFor both PATA and SATA, a lot of corners are cut for cheap connectors, 9930ec88413SMauro Carvalho Chehabcables or controllers and it's quite common to see high transmission 9940ec88413SMauro Carvalho Chehaberror rate. This can be mitigated by lowering transmission speed. 9950ec88413SMauro Carvalho Chehab 9960ec88413SMauro Carvalho ChehabThe following is a possible scheme Jeff Garzik suggested. 9970ec88413SMauro Carvalho Chehab 9980ec88413SMauro Carvalho Chehab If more than $N (3?) transmission errors happen in 15 minutes, 9990ec88413SMauro Carvalho Chehab 10000ec88413SMauro Carvalho Chehab - if SATA, decrease SATA PHY speed. if speed cannot be decreased, 10010ec88413SMauro Carvalho Chehab 10020ec88413SMauro Carvalho Chehab - decrease UDMA xfer speed. if at UDMA0, switch to PIO4, 10030ec88413SMauro Carvalho Chehab 10040ec88413SMauro Carvalho Chehab - decrease PIO xfer speed. if at PIO3, complain, but continue 10050ec88413SMauro Carvalho Chehab 10060ec88413SMauro Carvalho Chehabata_piix Internals 10070ec88413SMauro Carvalho Chehab=================== 10080ec88413SMauro Carvalho Chehab 10090ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/ata_piix.c 10100ec88413SMauro Carvalho Chehab :internal: 10110ec88413SMauro Carvalho Chehab 10120ec88413SMauro Carvalho Chehabsata_sil Internals 10130ec88413SMauro Carvalho Chehab=================== 10140ec88413SMauro Carvalho Chehab 10150ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/sata_sil.c 10160ec88413SMauro Carvalho Chehab :internal: 10170ec88413SMauro Carvalho Chehab 10180ec88413SMauro Carvalho ChehabThanks 10190ec88413SMauro Carvalho Chehab====== 10200ec88413SMauro Carvalho Chehab 10210ec88413SMauro Carvalho ChehabThe bulk of the ATA knowledge comes thanks to long conversations with 10220ec88413SMauro Carvalho ChehabAndre Hedrick (www.linux-ide.org), and long hours pondering the ATA and 10230ec88413SMauro Carvalho ChehabSCSI specifications. 10240ec88413SMauro Carvalho Chehab 10250ec88413SMauro Carvalho ChehabThanks to Alan Cox for pointing out similarities between SATA and SCSI, 10260ec88413SMauro Carvalho Chehaband in general for motivation to hack on libata. 10270ec88413SMauro Carvalho Chehab 10280ec88413SMauro Carvalho Chehablibata's device detection method, ata_pio_devchk, and in general all 10290ec88413SMauro Carvalho Chehabthe early probing was based on extensive study of Hale Landis's 10300ec88413SMauro Carvalho Chehabprobe/reset code in his ATADRVR driver (www.ata-atapi.com). 1031