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