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 210ec88413SMauro Carvalho Chehabstruct ata_port_operations is defined for every low-level libata 220ec88413SMauro Carvalho Chehabhardware driver, and it controls how the low-level driver interfaces 230ec88413SMauro Carvalho Chehabwith the ATA and SCSI layers. 240ec88413SMauro Carvalho Chehab 250ec88413SMauro Carvalho ChehabFIS-based drivers will hook into the system with ->qc_prep() and 260ec88413SMauro Carvalho Chehab->qc_issue() high-level hooks. Hardware which behaves in a manner 270ec88413SMauro Carvalho Chehabsimilar to PCI IDE hardware may utilize several generic helpers, 280ec88413SMauro Carvalho Chehabdefining at a bare minimum the bus I/O addresses of the ATA shadow 290ec88413SMauro Carvalho Chehabregister blocks. 300ec88413SMauro Carvalho Chehab 310ec88413SMauro Carvalho Chehabstruct ata_port_operations 320ec88413SMauro Carvalho Chehab---------------------------- 330ec88413SMauro Carvalho Chehab 340ec88413SMauro Carvalho ChehabDisable ATA port 350ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~ 360ec88413SMauro Carvalho Chehab 370ec88413SMauro Carvalho Chehab:: 380ec88413SMauro Carvalho Chehab 390ec88413SMauro Carvalho Chehab void (*port_disable) (struct ata_port *); 400ec88413SMauro Carvalho Chehab 410ec88413SMauro Carvalho Chehab 420ec88413SMauro Carvalho ChehabCalled from ata_bus_probe() error path, as well as when unregistering 430ec88413SMauro Carvalho Chehabfrom the SCSI module (rmmod, hot unplug). This function should do 440ec88413SMauro Carvalho Chehabwhatever needs to be done to take the port out of use. In most cases, 450ec88413SMauro Carvalho Chehabata_port_disable() can be used as this hook. 460ec88413SMauro Carvalho Chehab 470ec88413SMauro Carvalho ChehabCalled from ata_bus_probe() on a failed probe. Called from 480ec88413SMauro Carvalho Chehabata_scsi_release(). 490ec88413SMauro Carvalho Chehab 500ec88413SMauro Carvalho ChehabPost-IDENTIFY device configuration 510ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 520ec88413SMauro Carvalho Chehab 530ec88413SMauro Carvalho Chehab:: 540ec88413SMauro Carvalho Chehab 550ec88413SMauro Carvalho Chehab void (*dev_config) (struct ata_port *, struct ata_device *); 560ec88413SMauro Carvalho Chehab 570ec88413SMauro Carvalho Chehab 580ec88413SMauro Carvalho ChehabCalled after IDENTIFY [PACKET] DEVICE is issued to each device found. 590ec88413SMauro Carvalho ChehabTypically used to apply device-specific fixups prior to issue of SET 600ec88413SMauro Carvalho ChehabFEATURES - XFER MODE, and prior to operation. 610ec88413SMauro Carvalho Chehab 620ec88413SMauro Carvalho ChehabThis entry may be specified as NULL in ata_port_operations. 630ec88413SMauro Carvalho Chehab 640ec88413SMauro Carvalho ChehabSet PIO/DMA mode 650ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~ 660ec88413SMauro Carvalho Chehab 670ec88413SMauro Carvalho Chehab:: 680ec88413SMauro Carvalho Chehab 690ec88413SMauro Carvalho Chehab void (*set_piomode) (struct ata_port *, struct ata_device *); 700ec88413SMauro Carvalho Chehab void (*set_dmamode) (struct ata_port *, struct ata_device *); 710ec88413SMauro Carvalho Chehab void (*post_set_mode) (struct ata_port *); 720ec88413SMauro Carvalho Chehab unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int); 730ec88413SMauro Carvalho Chehab 740ec88413SMauro Carvalho Chehab 750ec88413SMauro Carvalho ChehabHooks called prior to the issue of SET FEATURES - XFER MODE command. The 760ec88413SMauro Carvalho Chehaboptional ->mode_filter() hook is called when libata has built a mask of 770ec88413SMauro Carvalho Chehabthe possible modes. This is passed to the ->mode_filter() function 780ec88413SMauro Carvalho Chehabwhich should return a mask of valid modes after filtering those 790ec88413SMauro Carvalho Chehabunsuitable due to hardware limits. It is not valid to use this interface 800ec88413SMauro Carvalho Chehabto add modes. 810ec88413SMauro Carvalho Chehab 820ec88413SMauro Carvalho Chehabdev->pio_mode and dev->dma_mode are guaranteed to be valid when 830ec88413SMauro Carvalho Chehab->set_piomode() and when ->set_dmamode() is called. The timings for 840ec88413SMauro Carvalho Chehabany other drive sharing the cable will also be valid at this point. That 850ec88413SMauro Carvalho Chehabis the library records the decisions for the modes of each drive on a 860ec88413SMauro Carvalho Chehabchannel before it attempts to set any of them. 870ec88413SMauro Carvalho Chehab 880ec88413SMauro Carvalho Chehab->post_set_mode() is called unconditionally, after the SET FEATURES - 890ec88413SMauro Carvalho ChehabXFER MODE command completes successfully. 900ec88413SMauro Carvalho Chehab 910ec88413SMauro Carvalho Chehab->set_piomode() is always called (if present), but ->set_dma_mode() 920ec88413SMauro Carvalho Chehabis only called if DMA is possible. 930ec88413SMauro Carvalho Chehab 940ec88413SMauro Carvalho ChehabTaskfile read/write 950ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~ 960ec88413SMauro Carvalho Chehab 970ec88413SMauro Carvalho Chehab:: 980ec88413SMauro Carvalho Chehab 990ec88413SMauro Carvalho Chehab void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf); 1000ec88413SMauro Carvalho Chehab void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf); 1010ec88413SMauro Carvalho Chehab 1020ec88413SMauro Carvalho Chehab 1030ec88413SMauro Carvalho Chehab->tf_load() is called to load the given taskfile into hardware 1040ec88413SMauro Carvalho Chehabregisters / DMA buffers. ->tf_read() is called to read the hardware 1050ec88413SMauro Carvalho Chehabregisters / DMA buffers, to obtain the current set of taskfile register 1060ec88413SMauro Carvalho Chehabvalues. Most drivers for taskfile-based hardware (PIO or MMIO) use 1070ec88413SMauro Carvalho Chehabata_sff_tf_load() and ata_sff_tf_read() for these hooks. 1080ec88413SMauro Carvalho Chehab 1090ec88413SMauro Carvalho ChehabPIO data read/write 1100ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~ 1110ec88413SMauro Carvalho Chehab 1120ec88413SMauro Carvalho Chehab:: 1130ec88413SMauro Carvalho Chehab 1140ec88413SMauro Carvalho Chehab void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int); 1150ec88413SMauro Carvalho Chehab 1160ec88413SMauro Carvalho Chehab 1170ec88413SMauro Carvalho ChehabAll bmdma-style drivers must implement this hook. This is the low-level 1180ec88413SMauro Carvalho Chehaboperation that actually copies the data bytes during a PIO data 1190ec88413SMauro Carvalho Chehabtransfer. Typically the driver will choose one of 1200ec88413SMauro Carvalho Chehabata_sff_data_xfer_noirq(), ata_sff_data_xfer(), or 1210ec88413SMauro Carvalho Chehabata_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 1310ec88413SMauro Carvalho Chehabcauses an ATA command, previously loaded with ->tf_load(), to be 1320ec88413SMauro Carvalho Chehabinitiated in hardware. Most drivers for taskfile-based hardware use 1330ec88413SMauro Carvalho Chehabata_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 1620ec88413SMauro Carvalho Chehabata_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 1870ec88413SMauro Carvalho ChehabMost drivers for taskfile-based hardware use 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 2250ec88413SMauro Carvalho Chehab(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) the 2260ec88413SMauro 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 2320ec88413SMauro Carvalho ChehabMost legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup() 2330ec88413SMauro Carvalho Chehabhook. ata_bmdma_setup() will write the pointer to the PRD table to the 2340ec88413SMauro Carvalho ChehabIDE PRD Table Address register, enable DMA in the DMA Command register, 2350ec88413SMauro Carvalho Chehaband call exec_command() to begin the transfer. 2360ec88413SMauro Carvalho Chehab 2370ec88413SMauro Carvalho ChehabMost legacy IDE drivers use ata_bmdma_start() for the bmdma_start() 2380ec88413SMauro Carvalho Chehabhook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA 2390ec88413SMauro Carvalho ChehabCommand register. 2400ec88413SMauro Carvalho Chehab 2410ec88413SMauro Carvalho ChehabMany legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop() 2420ec88413SMauro Carvalho Chehabhook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA 2430ec88413SMauro Carvalho Chehabcommand register. 2440ec88413SMauro Carvalho Chehab 2450ec88413SMauro Carvalho ChehabMany legacy IDE drivers use ata_bmdma_status() as the bmdma_status() 2460ec88413SMauro Carvalho Chehabhook. 2470ec88413SMauro Carvalho Chehab 2480ec88413SMauro Carvalho ChehabHigh-level taskfile hooks 2490ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~ 2500ec88413SMauro Carvalho Chehab 2510ec88413SMauro Carvalho Chehab:: 2520ec88413SMauro Carvalho Chehab 2530ec88413SMauro Carvalho Chehab void (*qc_prep) (struct ata_queued_cmd *qc); 2540ec88413SMauro Carvalho Chehab int (*qc_issue) (struct ata_queued_cmd *qc); 2550ec88413SMauro Carvalho Chehab 2560ec88413SMauro Carvalho Chehab 2570ec88413SMauro Carvalho ChehabHigher-level hooks, these two hooks can potentially supercede several of 2580ec88413SMauro 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 2600ec88413SMauro Carvalho Chehabhardware's DMA scatter-gather table. Most drivers use the standard 2610ec88413SMauro Carvalho Chehabata_qc_prep() helper function, but more advanced drivers roll their 2620ec88413SMauro Carvalho Chehabown. 2630ec88413SMauro Carvalho Chehab 2640ec88413SMauro 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 2660ec88413SMauro Carvalho Chehabata_qc_issue_prot() for taskfile protocol-based dispatch. More 2670ec88413SMauro Carvalho Chehabadvanced drivers implement their own ->qc_issue. 2680ec88413SMauro Carvalho Chehab 2690ec88413SMauro Carvalho Chehabata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and 2700ec88413SMauro 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 2810ec88413SMauro 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 2890ec88413SMauro Carvalho Chehabata_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 2940ec88413SMauro 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 2990ec88413SMauro Carvalho ChehabThe optional ->thaw() callback is called to perform the opposite of 3000ec88413SMauro 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 3080ec88413SMauro 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 3100ec88413SMauro Carvalho Chehabimplementation is to call ata_do_eh() or ata_bmdma_drive_eh() with 3110ec88413SMauro Carvalho Chehaba 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 3300ec88413SMauro Carvalho Chehabata_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 3410ec88413SMauro Carvalho Chehab->irq_handler is the interrupt handling routine registered with the 3420ec88413SMauro 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 3460ec88413SMauro Carvalho Chehabstruct ata_host_set. 3470ec88413SMauro Carvalho Chehab 3480ec88413SMauro Carvalho ChehabMost legacy IDE drivers use 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 3520ec88413SMauro Carvalho ChehabMost legacy IDE drivers use ata_sff_irq_clear() for the irq_clear() 3530ec88413SMauro Carvalho Chehabhook, which simply clears the interrupt and error flags in the DMA 3540ec88413SMauro Carvalho Chehabstatus 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 3680ec88413SMauro Carvalho Chehab->phy_reset hook called the sata_phy_reset() helper function. sc_reg 3690ec88413SMauro Carvalho Chehabis 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 3810ec88413SMauro 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 3850ec88413SMauro Carvalho Chehabap->private_data. 3860ec88413SMauro Carvalho Chehab 3870ec88413SMauro Carvalho ChehabMany drivers use ata_port_start() as this hook or call it from their 3880ec88413SMauro Carvalho Chehabown port_start() hooks. ata_port_start() allocates space for a legacy 3890ec88413SMauro Carvalho ChehabIDE PRD table and returns. 3900ec88413SMauro Carvalho Chehab 3910ec88413SMauro 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 3950ec88413SMauro 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 4100ec88413SMauro Carvalho ChehabIn libata, a command is represented with struct ata_queued_cmd or qc. 4110ec88413SMauro Carvalho Chehabqc's are preallocated during port initialization and repetitively used 4120ec88413SMauro Carvalho Chehabfor command executions. Currently only one qc is allocated per port but 4130ec88413SMauro Carvalho Chehabyet-to-be-merged NCQ branch allocates one for each tag and maps each qc 4140ec88413SMauro Carvalho Chehabto NCQ tag 1-to-1. 4150ec88413SMauro Carvalho Chehab 4160ec88413SMauro Carvalho Chehablibata commands can originate from two sources - libata itself and SCSI 4170ec88413SMauro Carvalho Chehabmidlayer. libata internal commands are used for initialization and error 4180ec88413SMauro Carvalho Chehabhandling. All normal blk requests and commands for SCSI emulation are 4190ec88413SMauro Carvalho Chehabpassed as SCSI commands through queuecommand callback of SCSI host 4200ec88413SMauro Carvalho Chehabtemplate. 4210ec88413SMauro Carvalho Chehab 4220ec88413SMauro Carvalho ChehabHow commands are issued 4230ec88413SMauro Carvalho Chehab----------------------- 4240ec88413SMauro Carvalho Chehab 4250ec88413SMauro Carvalho ChehabInternal commands 4260ec88413SMauro Carvalho Chehab First, qc is allocated and initialized using ata_qc_new_init(). 4270ec88413SMauro Carvalho Chehab Although ata_qc_new_init() doesn't implement any wait or retry 4280ec88413SMauro Carvalho Chehab mechanism when qc is not available, internal commands are currently 4290ec88413SMauro Carvalho Chehab issued only during initialization and error recovery, so no other 4300ec88413SMauro Carvalho Chehab command is active and allocation is guaranteed to succeed. 4310ec88413SMauro Carvalho Chehab 4320ec88413SMauro Carvalho Chehab Once allocated qc's taskfile is initialized for the command to be 4330ec88413SMauro Carvalho Chehab executed. qc currently has two mechanisms to notify completion. One 4340ec88413SMauro Carvalho Chehab is via qc->complete_fn() callback and the other is completion 4350ec88413SMauro Carvalho Chehab qc->waiting. qc->complete_fn() callback is the asynchronous path 4360ec88413SMauro Carvalho Chehab used by normal SCSI translated commands and qc->waiting is the 4370ec88413SMauro Carvalho Chehab synchronous (issuer sleeps in process context) path used by internal 4380ec88413SMauro Carvalho Chehab commands. 4390ec88413SMauro Carvalho Chehab 4400ec88413SMauro Carvalho Chehab Once initialization is complete, host_set lock is acquired and the 4410ec88413SMauro Carvalho Chehab qc is issued. 4420ec88413SMauro Carvalho Chehab 4430ec88413SMauro Carvalho ChehabSCSI commands 4440ec88413SMauro Carvalho Chehab All libata drivers use ata_scsi_queuecmd() as hostt->queuecommand 4450ec88413SMauro Carvalho Chehab callback. scmds can either be simulated or translated. No qc is 4460ec88413SMauro Carvalho Chehab involved in processing a simulated scmd. The result is computed 4470ec88413SMauro Carvalho Chehab right away and the scmd is completed. 4480ec88413SMauro Carvalho Chehab 4490ec88413SMauro Carvalho Chehab For a translated scmd, ata_qc_new_init() is invoked to allocate a 4500ec88413SMauro Carvalho Chehab qc and the scmd is translated into the qc. SCSI midlayer's 4510ec88413SMauro Carvalho Chehab completion notification function pointer is stored into 4520ec88413SMauro Carvalho Chehab qc->scsidone. 4530ec88413SMauro Carvalho Chehab 4540ec88413SMauro Carvalho Chehab qc->complete_fn() callback is used for completion notification. ATA 4550ec88413SMauro Carvalho Chehab commands use ata_scsi_qc_complete() while ATAPI commands use 4560ec88413SMauro Carvalho Chehab atapi_qc_complete(). Both functions end up calling qc->scsidone to 4570ec88413SMauro Carvalho Chehab notify upper layer when the qc is finished. After translation is 4580ec88413SMauro Carvalho Chehab completed, the qc is issued with ata_qc_issue(). 4590ec88413SMauro Carvalho Chehab 4600ec88413SMauro Carvalho Chehab Note that SCSI midlayer invokes hostt->queuecommand while holding 4610ec88413SMauro Carvalho Chehab host_set lock, so all above occur while holding host_set lock. 4620ec88413SMauro Carvalho Chehab 4630ec88413SMauro Carvalho ChehabHow commands are processed 4640ec88413SMauro Carvalho Chehab-------------------------- 4650ec88413SMauro Carvalho Chehab 4660ec88413SMauro Carvalho ChehabDepending on which protocol and which controller are used, commands are 4670ec88413SMauro Carvalho Chehabprocessed differently. For the purpose of discussion, a controller which 4680ec88413SMauro Carvalho Chehabuses taskfile interface and all standard callbacks is assumed. 4690ec88413SMauro Carvalho Chehab 4700ec88413SMauro Carvalho ChehabCurrently 6 ATA command protocols are used. They can be sorted into the 4710ec88413SMauro Carvalho Chehabfollowing four categories according to how they are processed. 4720ec88413SMauro Carvalho Chehab 4730ec88413SMauro Carvalho ChehabATA NO DATA or DMA 4740ec88413SMauro Carvalho Chehab ATA_PROT_NODATA and ATA_PROT_DMA fall into this category. These 4750ec88413SMauro Carvalho Chehab types of commands don't require any software intervention once 4760ec88413SMauro Carvalho Chehab issued. Device will raise interrupt on completion. 4770ec88413SMauro Carvalho Chehab 4780ec88413SMauro Carvalho ChehabATA PIO 4790ec88413SMauro Carvalho Chehab ATA_PROT_PIO is in this category. libata currently implements PIO 4800ec88413SMauro Carvalho Chehab with polling. ATA_NIEN bit is set to turn off interrupt and 4810ec88413SMauro Carvalho Chehab pio_task on ata_wq performs polling and IO. 4820ec88413SMauro Carvalho Chehab 4830ec88413SMauro Carvalho ChehabATAPI NODATA or DMA 4840ec88413SMauro Carvalho Chehab ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this 4850ec88413SMauro Carvalho Chehab category. packet_task is used to poll BSY bit after issuing PACKET 4860ec88413SMauro Carvalho Chehab command. Once BSY is turned off by the device, packet_task 4870ec88413SMauro Carvalho Chehab transfers CDB and hands off processing to interrupt handler. 4880ec88413SMauro Carvalho Chehab 4890ec88413SMauro Carvalho ChehabATAPI PIO 4900ec88413SMauro Carvalho Chehab ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set and, as 4910ec88413SMauro Carvalho Chehab in ATAPI NODATA or DMA, packet_task submits cdb. However, after 4920ec88413SMauro Carvalho Chehab submitting cdb, further processing (data transfer) is handed off to 4930ec88413SMauro Carvalho Chehab pio_task. 4940ec88413SMauro Carvalho Chehab 4950ec88413SMauro Carvalho ChehabHow commands are completed 4960ec88413SMauro Carvalho Chehab-------------------------- 4970ec88413SMauro Carvalho Chehab 4980ec88413SMauro Carvalho ChehabOnce issued, all qc's are either completed with ata_qc_complete() or 4990ec88413SMauro Carvalho Chehabtime out. For commands which are handled by interrupts, 5000ec88413SMauro Carvalho Chehabata_host_intr() invokes ata_qc_complete(), and, for PIO tasks, 5010ec88413SMauro Carvalho Chehabpio_task invokes ata_qc_complete(). In error cases, packet_task may 5020ec88413SMauro Carvalho Chehabalso complete commands. 5030ec88413SMauro Carvalho Chehab 5040ec88413SMauro Carvalho Chehabata_qc_complete() does the following. 5050ec88413SMauro Carvalho Chehab 5060ec88413SMauro Carvalho Chehab1. DMA memory is unmapped. 5070ec88413SMauro Carvalho Chehab 5080ec88413SMauro Carvalho Chehab2. ATA_QCFLAG_ACTIVE is cleared from qc->flags. 5090ec88413SMauro Carvalho Chehab 5100ec88413SMauro Carvalho Chehab3. qc->complete_fn() callback is invoked. If the return value of the 5110ec88413SMauro Carvalho Chehab callback is not zero. Completion is short circuited and 5120ec88413SMauro Carvalho Chehab ata_qc_complete() returns. 5130ec88413SMauro Carvalho Chehab 5140ec88413SMauro Carvalho Chehab4. __ata_qc_complete() is called, which does 5150ec88413SMauro Carvalho Chehab 5160ec88413SMauro Carvalho Chehab 1. qc->flags is cleared to zero. 5170ec88413SMauro Carvalho Chehab 5180ec88413SMauro Carvalho Chehab 2. ap->active_tag and qc->tag are poisoned. 5190ec88413SMauro Carvalho Chehab 5200ec88413SMauro Carvalho Chehab 3. qc->waiting is cleared & completed (in that order). 5210ec88413SMauro Carvalho Chehab 5220ec88413SMauro Carvalho Chehab 4. qc is deallocated by clearing appropriate bit in ap->qactive. 5230ec88413SMauro Carvalho Chehab 5240ec88413SMauro Carvalho ChehabSo, it basically notifies upper layer and deallocates qc. One exception 5250ec88413SMauro Carvalho Chehabis short-circuit path in #3 which is used by atapi_qc_complete(). 5260ec88413SMauro Carvalho Chehab 5270ec88413SMauro Carvalho ChehabFor all non-ATAPI commands, whether it fails or not, almost the same 5280ec88413SMauro Carvalho Chehabcode path is taken and very little error handling takes place. A qc is 5290ec88413SMauro Carvalho Chehabcompleted with success status if it succeeded, with failed status 5300ec88413SMauro Carvalho Chehabotherwise. 5310ec88413SMauro Carvalho Chehab 5320ec88413SMauro Carvalho ChehabHowever, failed ATAPI commands require more handling as REQUEST SENSE is 5330ec88413SMauro Carvalho Chehabneeded to acquire sense data. If an ATAPI command fails, 5340ec88413SMauro Carvalho Chehabata_qc_complete() is invoked with error status, which in turn invokes 5350ec88413SMauro Carvalho Chehabatapi_qc_complete() via qc->complete_fn() callback. 5360ec88413SMauro Carvalho Chehab 5370ec88413SMauro Carvalho ChehabThis makes atapi_qc_complete() set scmd->result to 5380ec88413SMauro Carvalho ChehabSAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As the 5390ec88413SMauro Carvalho Chehabsense data is empty but scmd->result is CHECK CONDITION, SCSI midlayer 5400ec88413SMauro Carvalho Chehabwill invoke EH for the scmd, and returning 1 makes ata_qc_complete() 5410ec88413SMauro Carvalho Chehabto return without deallocating the qc. This leads us to 5420ec88413SMauro Carvalho Chehabata_scsi_error() with partially completed qc. 5430ec88413SMauro Carvalho Chehab 5440ec88413SMauro Carvalho Chehabata_scsi_error() 5450ec88413SMauro Carvalho Chehab------------------ 5460ec88413SMauro Carvalho Chehab 5470ec88413SMauro Carvalho Chehabata_scsi_error() is the current transportt->eh_strategy_handler() 5480ec88413SMauro Carvalho Chehabfor libata. As discussed above, this will be entered in two cases - 5490ec88413SMauro Carvalho Chehabtimeout and ATAPI error completion. This function calls low level libata 5500ec88413SMauro Carvalho Chehabdriver's eng_timeout() callback, the standard callback for which is 5510ec88413SMauro Carvalho Chehabata_eng_timeout(). It checks if a qc is active and calls 5520ec88413SMauro Carvalho Chehabata_qc_timeout() on the qc if so. Actual error handling occurs in 5530ec88413SMauro Carvalho Chehabata_qc_timeout(). 5540ec88413SMauro Carvalho Chehab 5550ec88413SMauro Carvalho ChehabIf EH is invoked for timeout, ata_qc_timeout() stops BMDMA and 5560ec88413SMauro Carvalho Chehabcompletes the qc. Note that as we're currently in EH, we cannot call 5570ec88413SMauro Carvalho Chehabscsi_done. As described in SCSI EH doc, a recovered scmd should be 5580ec88413SMauro Carvalho Chehabeither retried with scsi_queue_insert() or finished with 5590ec88413SMauro Carvalho Chehabscsi_finish_command(). Here, we override qc->scsidone with 5600ec88413SMauro Carvalho Chehabscsi_finish_command() and calls ata_qc_complete(). 5610ec88413SMauro Carvalho Chehab 5620ec88413SMauro Carvalho ChehabIf EH is invoked due to a failed ATAPI qc, the qc here is completed but 5630ec88413SMauro Carvalho Chehabnot deallocated. The purpose of this half-completion is to use the qc as 5640ec88413SMauro Carvalho Chehabplace holder to make EH code reach this place. This is a bit hackish, 5650ec88413SMauro Carvalho Chehabbut it works. 5660ec88413SMauro Carvalho Chehab 5670ec88413SMauro Carvalho ChehabOnce control reaches here, the qc is deallocated by invoking 5680ec88413SMauro Carvalho Chehab__ata_qc_complete() explicitly. Then, internal qc for REQUEST SENSE 5690ec88413SMauro Carvalho Chehabis issued. Once sense data is acquired, scmd is finished by directly 5700ec88413SMauro Carvalho Chehabinvoking scsi_finish_command() on the scmd. Note that as we already 5710ec88413SMauro Carvalho Chehabhave completed and deallocated the qc which was associated with the 5720ec88413SMauro Carvalho Chehabscmd, we don't need to/cannot call ata_qc_complete() again. 5730ec88413SMauro Carvalho Chehab 5740ec88413SMauro Carvalho ChehabProblems with the current EH 5750ec88413SMauro Carvalho Chehab---------------------------- 5760ec88413SMauro Carvalho Chehab 5770ec88413SMauro Carvalho Chehab- Error representation is too crude. Currently any and all error 5780ec88413SMauro Carvalho Chehab conditions are represented with ATA STATUS and ERROR registers. 5790ec88413SMauro Carvalho Chehab Errors which aren't ATA device errors are treated as ATA device 5800ec88413SMauro Carvalho Chehab errors by setting ATA_ERR bit. Better error descriptor which can 5810ec88413SMauro Carvalho Chehab properly represent ATA and other errors/exceptions is needed. 5820ec88413SMauro Carvalho Chehab 5830ec88413SMauro Carvalho Chehab- When handling timeouts, no action is taken to make device forget 5840ec88413SMauro Carvalho Chehab about the timed out command and ready for new commands. 5850ec88413SMauro Carvalho Chehab 5860ec88413SMauro Carvalho Chehab- EH handling via ata_scsi_error() is not properly protected from 5870ec88413SMauro Carvalho Chehab usual command processing. On EH entrance, the device is not in 5880ec88413SMauro Carvalho Chehab quiescent state. Timed out commands may succeed or fail any time. 5890ec88413SMauro Carvalho Chehab pio_task and atapi_task may still be running. 5900ec88413SMauro Carvalho Chehab 5910ec88413SMauro Carvalho Chehab- Too weak error recovery. Devices / controllers causing HSM mismatch 5920ec88413SMauro Carvalho Chehab errors and other errors quite often require reset to return to known 5930ec88413SMauro Carvalho Chehab state. Also, advanced error handling is necessary to support features 5940ec88413SMauro Carvalho Chehab like NCQ and hotplug. 5950ec88413SMauro Carvalho Chehab 5960ec88413SMauro Carvalho Chehab- ATA errors are directly handled in the interrupt handler and PIO 5970ec88413SMauro Carvalho Chehab errors in pio_task. This is problematic for advanced error handling 5980ec88413SMauro Carvalho Chehab for the following reasons. 5990ec88413SMauro Carvalho Chehab 6000ec88413SMauro Carvalho Chehab First, advanced error handling often requires context and internal qc 6010ec88413SMauro Carvalho Chehab execution. 6020ec88413SMauro Carvalho Chehab 6030ec88413SMauro Carvalho Chehab Second, even a simple failure (say, CRC error) needs information 6040ec88413SMauro Carvalho Chehab gathering and could trigger complex error handling (say, resetting & 6050ec88413SMauro Carvalho Chehab reconfiguring). Having multiple code paths to gather information, 6060ec88413SMauro Carvalho Chehab enter EH and trigger actions makes life painful. 6070ec88413SMauro Carvalho Chehab 6080ec88413SMauro Carvalho Chehab Third, scattered EH code makes implementing low level drivers 6090ec88413SMauro Carvalho Chehab difficult. Low level drivers override libata callbacks. If EH is 6100ec88413SMauro Carvalho Chehab scattered over several places, each affected callbacks should perform 6110ec88413SMauro Carvalho Chehab its part of error handling. This can be error prone and painful. 6120ec88413SMauro Carvalho Chehab 6130ec88413SMauro Carvalho Chehablibata Library 6140ec88413SMauro Carvalho Chehab============== 6150ec88413SMauro Carvalho Chehab 6160ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/libata-core.c 6170ec88413SMauro Carvalho Chehab :export: 6180ec88413SMauro Carvalho Chehab 6190ec88413SMauro Carvalho Chehablibata Core Internals 6200ec88413SMauro Carvalho Chehab===================== 6210ec88413SMauro Carvalho Chehab 6220ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/libata-core.c 6230ec88413SMauro Carvalho Chehab :internal: 6240ec88413SMauro Carvalho Chehab 6250ec88413SMauro Carvalho Chehablibata SCSI translation/emulation 6260ec88413SMauro Carvalho Chehab================================= 6270ec88413SMauro Carvalho Chehab 6280ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/libata-scsi.c 6290ec88413SMauro Carvalho Chehab :export: 6300ec88413SMauro Carvalho Chehab 6310ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/libata-scsi.c 6320ec88413SMauro Carvalho Chehab :internal: 6330ec88413SMauro Carvalho Chehab 6340ec88413SMauro Carvalho ChehabATA errors and exceptions 6350ec88413SMauro Carvalho Chehab========================= 6360ec88413SMauro Carvalho Chehab 6370ec88413SMauro Carvalho ChehabThis chapter tries to identify what error/exception conditions exist for 6380ec88413SMauro Carvalho ChehabATA/ATAPI devices and describe how they should be handled in 6390ec88413SMauro Carvalho Chehabimplementation-neutral way. 6400ec88413SMauro Carvalho Chehab 6410ec88413SMauro Carvalho ChehabThe term 'error' is used to describe conditions where either an explicit 6420ec88413SMauro Carvalho Chehaberror condition is reported from device or a command has timed out. 6430ec88413SMauro Carvalho Chehab 6440ec88413SMauro Carvalho ChehabThe term 'exception' is either used to describe exceptional conditions 6450ec88413SMauro Carvalho Chehabwhich are not errors (say, power or hotplug events), or to describe both 6460ec88413SMauro Carvalho Chehaberrors and non-error exceptional conditions. Where explicit distinction 6470ec88413SMauro Carvalho Chehabbetween error and exception is necessary, the term 'non-error exception' 6480ec88413SMauro Carvalho Chehabis used. 6490ec88413SMauro Carvalho Chehab 6500ec88413SMauro Carvalho ChehabException categories 6510ec88413SMauro Carvalho Chehab-------------------- 6520ec88413SMauro Carvalho Chehab 6530ec88413SMauro Carvalho ChehabExceptions are described primarily with respect to legacy taskfile + bus 6540ec88413SMauro Carvalho Chehabmaster IDE interface. If a controller provides other better mechanism 6550ec88413SMauro Carvalho Chehabfor error reporting, mapping those into categories described below 6560ec88413SMauro Carvalho Chehabshouldn't be difficult. 6570ec88413SMauro Carvalho Chehab 6580ec88413SMauro Carvalho ChehabIn the following sections, two recovery actions - reset and 6590ec88413SMauro Carvalho Chehabreconfiguring transport - are mentioned. These are described further in 6600ec88413SMauro Carvalho Chehab`EH recovery actions <#exrec>`__. 6610ec88413SMauro Carvalho Chehab 6620ec88413SMauro Carvalho ChehabHSM violation 6630ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~ 6640ec88413SMauro Carvalho Chehab 6650ec88413SMauro Carvalho ChehabThis error is indicated when STATUS value doesn't match HSM requirement 6660ec88413SMauro Carvalho Chehabduring issuing or execution any ATA/ATAPI command. 6670ec88413SMauro Carvalho Chehab 6680ec88413SMauro Carvalho Chehab- ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying to 6690ec88413SMauro Carvalho Chehab issue a command. 6700ec88413SMauro Carvalho Chehab 6710ec88413SMauro Carvalho Chehab- !BSY && !DRQ during PIO data transfer. 6720ec88413SMauro Carvalho Chehab 6730ec88413SMauro Carvalho Chehab- DRQ on command completion. 6740ec88413SMauro Carvalho Chehab 6750ec88413SMauro Carvalho Chehab- !BSY && ERR after CDB transfer starts but before the last byte of CDB 6760ec88413SMauro Carvalho Chehab is transferred. ATA/ATAPI standard states that "The device shall not 6770ec88413SMauro Carvalho Chehab terminate the PACKET command with an error before the last byte of 6780ec88413SMauro Carvalho Chehab the command packet has been written" in the error outputs description 6790ec88413SMauro Carvalho Chehab of PACKET command and the state diagram doesn't include such 6800ec88413SMauro Carvalho Chehab transitions. 6810ec88413SMauro Carvalho Chehab 6820ec88413SMauro Carvalho ChehabIn these cases, HSM is violated and not much information regarding the 6830ec88413SMauro Carvalho Chehaberror can be acquired from STATUS or ERROR register. IOW, this error can 6840ec88413SMauro Carvalho Chehabbe anything - driver bug, faulty device, controller and/or cable. 6850ec88413SMauro Carvalho Chehab 6860ec88413SMauro Carvalho ChehabAs HSM is violated, reset is necessary to restore known state. 6870ec88413SMauro Carvalho ChehabReconfiguring transport for lower speed might be helpful too as 6880ec88413SMauro Carvalho Chehabtransmission errors sometimes cause this kind of errors. 6890ec88413SMauro Carvalho Chehab 6900ec88413SMauro Carvalho ChehabATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) 6910ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 6920ec88413SMauro Carvalho Chehab 6930ec88413SMauro Carvalho ChehabThese are errors detected and reported by ATA/ATAPI devices indicating 6940ec88413SMauro Carvalho Chehabdevice problems. For this type of errors, STATUS and ERROR register 6950ec88413SMauro Carvalho Chehabvalues are valid and describe error condition. Note that some of ATA bus 6960ec88413SMauro Carvalho Chehaberrors are detected by ATA/ATAPI devices and reported using the same 6970ec88413SMauro Carvalho Chehabmechanism as device errors. Those cases are described later in this 6980ec88413SMauro Carvalho Chehabsection. 6990ec88413SMauro Carvalho Chehab 7000ec88413SMauro Carvalho ChehabFor ATA commands, this type of errors are indicated by !BSY && ERR 7010ec88413SMauro Carvalho Chehabduring command execution and on completion. 7020ec88413SMauro Carvalho Chehab 7030ec88413SMauro Carvalho ChehabFor ATAPI commands, 7040ec88413SMauro Carvalho Chehab 7050ec88413SMauro Carvalho Chehab- !BSY && ERR && ABRT right after issuing PACKET indicates that PACKET 7060ec88413SMauro Carvalho Chehab command is not supported and falls in this category. 7070ec88413SMauro Carvalho Chehab 7080ec88413SMauro Carvalho Chehab- !BSY && ERR(==CHK) && !ABRT after the last byte of CDB is transferred 7090ec88413SMauro Carvalho Chehab indicates CHECK CONDITION and doesn't fall in this category. 7100ec88413SMauro Carvalho Chehab 7110ec88413SMauro Carvalho Chehab- !BSY && ERR(==CHK) && ABRT after the last byte of CDB is transferred 7120ec88413SMauro Carvalho Chehab \*probably\* indicates CHECK CONDITION and doesn't fall in this 7130ec88413SMauro Carvalho Chehab category. 7140ec88413SMauro Carvalho Chehab 7150ec88413SMauro Carvalho ChehabOf errors detected as above, the following are not ATA/ATAPI device 7160ec88413SMauro Carvalho Chehaberrors but ATA bus errors and should be handled according to 7170ec88413SMauro Carvalho Chehab`ATA bus error <#excatATAbusErr>`__. 7180ec88413SMauro Carvalho Chehab 7190ec88413SMauro Carvalho ChehabCRC error during data transfer 7200ec88413SMauro Carvalho Chehab This is indicated by ICRC bit in the ERROR register and means that 7210ec88413SMauro Carvalho Chehab corruption occurred during data transfer. Up to ATA/ATAPI-7, the 7220ec88413SMauro Carvalho Chehab standard specifies that this bit is only applicable to UDMA 7230ec88413SMauro Carvalho Chehab transfers but ATA/ATAPI-8 draft revision 1f says that the bit may be 7240ec88413SMauro Carvalho Chehab applicable to multiword DMA and PIO. 7250ec88413SMauro Carvalho Chehab 7260ec88413SMauro Carvalho ChehabABRT error during data transfer or on completion 7270ec88413SMauro Carvalho Chehab Up to ATA/ATAPI-7, the standard specifies that ABRT could be set on 7280ec88413SMauro Carvalho Chehab ICRC errors and on cases where a device is not able to complete a 7290ec88413SMauro Carvalho Chehab command. Combined with the fact that MWDMA and PIO transfer errors 7300ec88413SMauro Carvalho Chehab aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply 7310ec88413SMauro Carvalho Chehab that ABRT bit alone could indicate transfer errors. 7320ec88413SMauro Carvalho Chehab 7330ec88413SMauro Carvalho Chehab However, ATA/ATAPI-8 draft revision 1f removes the part that ICRC 7340ec88413SMauro Carvalho Chehab errors can turn on ABRT. So, this is kind of gray area. Some 7350ec88413SMauro Carvalho Chehab heuristics are needed here. 7360ec88413SMauro Carvalho Chehab 7370ec88413SMauro Carvalho ChehabATA/ATAPI device errors can be further categorized as follows. 7380ec88413SMauro Carvalho Chehab 7390ec88413SMauro Carvalho ChehabMedia errors 7400ec88413SMauro Carvalho Chehab This is indicated by UNC bit in the ERROR register. ATA devices 7410ec88413SMauro Carvalho Chehab reports UNC error only after certain number of retries cannot 7420ec88413SMauro Carvalho Chehab recover the data, so there's nothing much else to do other than 7430ec88413SMauro Carvalho Chehab notifying upper layer. 7440ec88413SMauro Carvalho Chehab 7450ec88413SMauro Carvalho Chehab READ and WRITE commands report CHS or LBA of the first failed sector 7460ec88413SMauro Carvalho Chehab but ATA/ATAPI standard specifies that the amount of transferred data 7470ec88413SMauro Carvalho Chehab on error completion is indeterminate, so we cannot assume that 7480ec88413SMauro Carvalho Chehab sectors preceding the failed sector have been transferred and thus 7490ec88413SMauro Carvalho Chehab cannot complete those sectors successfully as SCSI does. 7500ec88413SMauro Carvalho Chehab 7510ec88413SMauro Carvalho ChehabMedia changed / media change requested error 7520ec88413SMauro Carvalho Chehab <<TODO: fill here>> 7530ec88413SMauro Carvalho Chehab 7540ec88413SMauro Carvalho ChehabAddress error 7550ec88413SMauro Carvalho Chehab This is indicated by IDNF bit in the ERROR register. Report to upper 7560ec88413SMauro Carvalho Chehab layer. 7570ec88413SMauro Carvalho Chehab 7580ec88413SMauro Carvalho ChehabOther errors 7590ec88413SMauro Carvalho Chehab This can be invalid command or parameter indicated by ABRT ERROR bit 7600ec88413SMauro Carvalho Chehab or some other error condition. Note that ABRT bit can indicate a lot 7610ec88413SMauro Carvalho Chehab of things including ICRC and Address errors. Heuristics needed. 7620ec88413SMauro Carvalho Chehab 7630ec88413SMauro Carvalho ChehabDepending on commands, not all STATUS/ERROR bits are applicable. These 7640ec88413SMauro Carvalho Chehabnon-applicable bits are marked with "na" in the output descriptions but 7650ec88413SMauro Carvalho Chehabup to ATA/ATAPI-7 no definition of "na" can be found. However, 7660ec88413SMauro Carvalho ChehabATA/ATAPI-8 draft revision 1f describes "N/A" as follows. 7670ec88413SMauro Carvalho Chehab 7680ec88413SMauro Carvalho Chehab 3.2.3.3a N/A 7690ec88413SMauro Carvalho Chehab A keyword the indicates a field has no defined value in this 7700ec88413SMauro Carvalho Chehab standard and should not be checked by the host or device. N/A 7710ec88413SMauro Carvalho Chehab fields should be cleared to zero. 7720ec88413SMauro Carvalho Chehab 7730ec88413SMauro Carvalho ChehabSo, it seems reasonable to assume that "na" bits are cleared to zero by 7740ec88413SMauro Carvalho Chehabdevices and thus need no explicit masking. 7750ec88413SMauro Carvalho Chehab 7760ec88413SMauro Carvalho ChehabATAPI device CHECK CONDITION 7770ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 7780ec88413SMauro Carvalho Chehab 7790ec88413SMauro Carvalho ChehabATAPI device CHECK CONDITION error is indicated by set CHK bit (ERR bit) 7800ec88413SMauro Carvalho Chehabin the STATUS register after the last byte of CDB is transferred for a 7810ec88413SMauro Carvalho ChehabPACKET command. For this kind of errors, sense data should be acquired 7820ec88413SMauro Carvalho Chehabto gather information regarding the errors. REQUEST SENSE packet command 7830ec88413SMauro Carvalho Chehabshould be used to acquire sense data. 7840ec88413SMauro Carvalho Chehab 7850ec88413SMauro Carvalho ChehabOnce sense data is acquired, this type of errors can be handled 7860ec88413SMauro Carvalho Chehabsimilarly to other SCSI errors. Note that sense data may indicate ATA 7870ec88413SMauro Carvalho Chehabbus error (e.g. Sense Key 04h HARDWARE ERROR && ASC/ASCQ 47h/00h SCSI 7880ec88413SMauro Carvalho ChehabPARITY ERROR). In such cases, the error should be considered as an ATA 7890ec88413SMauro Carvalho Chehabbus error and handled according to `ATA bus error <#excatATAbusErr>`__. 7900ec88413SMauro Carvalho Chehab 7910ec88413SMauro Carvalho ChehabATA device error (NCQ) 7920ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~ 7930ec88413SMauro Carvalho Chehab 7940ec88413SMauro Carvalho ChehabNCQ command error is indicated by cleared BSY and set ERR bit during NCQ 7950ec88413SMauro Carvalho Chehabcommand phase (one or more NCQ commands outstanding). Although STATUS 7960ec88413SMauro Carvalho Chehaband ERROR registers will contain valid values describing the error, READ 7970ec88413SMauro Carvalho ChehabLOG EXT is required to clear the error condition, determine which 7980ec88413SMauro Carvalho Chehabcommand has failed and acquire more information. 7990ec88413SMauro Carvalho Chehab 8000ec88413SMauro Carvalho ChehabREAD LOG EXT Log Page 10h reports which tag has failed and taskfile 8010ec88413SMauro Carvalho Chehabregister values describing the error. With this information the failed 8020ec88413SMauro Carvalho Chehabcommand can be handled as a normal ATA command error as in 8030ec88413SMauro Carvalho Chehab`ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__ 8040ec88413SMauro Carvalho Chehaband all other in-flight commands must be retried. Note that this retry 8050ec88413SMauro Carvalho Chehabshould not be counted - it's likely that commands retried this way would 8060ec88413SMauro Carvalho Chehabhave completed normally if it were not for the failed command. 8070ec88413SMauro Carvalho Chehab 8080ec88413SMauro Carvalho ChehabNote that ATA bus errors can be reported as ATA device NCQ errors. This 8090ec88413SMauro Carvalho Chehabshould be handled as described in `ATA bus error <#excatATAbusErr>`__. 8100ec88413SMauro Carvalho Chehab 8110ec88413SMauro Carvalho ChehabIf READ LOG EXT Log Page 10h fails or reports NQ, we're thoroughly 8120ec88413SMauro Carvalho Chehabscrewed. This condition should be treated according to 8130ec88413SMauro Carvalho Chehab`HSM violation <#excatHSMviolation>`__. 8140ec88413SMauro Carvalho Chehab 8150ec88413SMauro Carvalho ChehabATA bus error 8160ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~ 8170ec88413SMauro Carvalho Chehab 8180ec88413SMauro Carvalho ChehabATA bus error means that data corruption occurred during transmission 8190ec88413SMauro Carvalho Chehabover ATA bus (SATA or PATA). This type of errors can be indicated by 8200ec88413SMauro Carvalho Chehab 8210ec88413SMauro Carvalho Chehab- ICRC or ABRT error as described in 8220ec88413SMauro Carvalho Chehab `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__. 8230ec88413SMauro Carvalho Chehab 8240ec88413SMauro Carvalho Chehab- Controller-specific error completion with error information 8250ec88413SMauro Carvalho Chehab indicating transmission error. 8260ec88413SMauro Carvalho Chehab 8270ec88413SMauro Carvalho Chehab- On some controllers, command timeout. In this case, there may be a 8280ec88413SMauro Carvalho Chehab mechanism to determine that the timeout is due to transmission error. 8290ec88413SMauro Carvalho Chehab 8300ec88413SMauro Carvalho Chehab- Unknown/random errors, timeouts and all sorts of weirdities. 8310ec88413SMauro Carvalho Chehab 8320ec88413SMauro Carvalho ChehabAs described above, transmission errors can cause wide variety of 8330ec88413SMauro Carvalho Chehabsymptoms ranging from device ICRC error to random device lockup, and, 8340ec88413SMauro Carvalho Chehabfor many cases, there is no way to tell if an error condition is due to 8350ec88413SMauro Carvalho Chehabtransmission error or not; therefore, it's necessary to employ some kind 8360ec88413SMauro Carvalho Chehabof heuristic when dealing with errors and timeouts. For example, 8370ec88413SMauro Carvalho Chehabencountering repetitive ABRT errors for known supported command is 8380ec88413SMauro Carvalho Chehablikely to indicate ATA bus error. 8390ec88413SMauro Carvalho Chehab 8400ec88413SMauro Carvalho ChehabOnce it's determined that ATA bus errors have possibly occurred, 8410ec88413SMauro Carvalho Chehablowering ATA bus transmission speed is one of actions which may 8420ec88413SMauro Carvalho Chehaballeviate the problem. See `Reconfigure transport <#exrecReconf>`__ for 8430ec88413SMauro Carvalho Chehabmore information. 8440ec88413SMauro Carvalho Chehab 8450ec88413SMauro Carvalho ChehabPCI bus error 8460ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~ 8470ec88413SMauro Carvalho Chehab 8480ec88413SMauro Carvalho ChehabData corruption or other failures during transmission over PCI (or other 8490ec88413SMauro Carvalho Chehabsystem bus). For standard BMDMA, this is indicated by Error bit in the 8500ec88413SMauro Carvalho ChehabBMDMA Status register. This type of errors must be logged as it 8510ec88413SMauro Carvalho Chehabindicates something is very wrong with the system. Resetting host 8520ec88413SMauro Carvalho Chehabcontroller is recommended. 8530ec88413SMauro Carvalho Chehab 8540ec88413SMauro Carvalho ChehabLate completion 8550ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~ 8560ec88413SMauro Carvalho Chehab 8570ec88413SMauro Carvalho ChehabThis occurs when timeout occurs and the timeout handler finds out that 8580ec88413SMauro Carvalho Chehabthe timed out command has completed successfully or with error. This is 8590ec88413SMauro Carvalho Chehabusually caused by lost interrupts. This type of errors must be logged. 8600ec88413SMauro Carvalho ChehabResetting host controller is recommended. 8610ec88413SMauro Carvalho Chehab 8620ec88413SMauro Carvalho ChehabUnknown error (timeout) 8630ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~ 8640ec88413SMauro Carvalho Chehab 8650ec88413SMauro Carvalho ChehabThis is when timeout occurs and the command is still processing or the 8660ec88413SMauro Carvalho Chehabhost and device are in unknown state. When this occurs, HSM could be in 8670ec88413SMauro Carvalho Chehabany valid or invalid state. To bring the device to known state and make 8680ec88413SMauro Carvalho Chehabit forget about the timed out command, resetting is necessary. The timed 8690ec88413SMauro Carvalho Chehabout command may be retried. 8700ec88413SMauro Carvalho Chehab 8710ec88413SMauro Carvalho ChehabTimeouts can also be caused by transmission errors. Refer to 8720ec88413SMauro Carvalho Chehab`ATA bus error <#excatATAbusErr>`__ for more details. 8730ec88413SMauro Carvalho Chehab 8740ec88413SMauro Carvalho ChehabHotplug and power management exceptions 8750ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 8760ec88413SMauro Carvalho Chehab 8770ec88413SMauro Carvalho Chehab<<TODO: fill here>> 8780ec88413SMauro Carvalho Chehab 8790ec88413SMauro Carvalho ChehabEH recovery actions 8800ec88413SMauro Carvalho Chehab------------------- 8810ec88413SMauro Carvalho Chehab 8820ec88413SMauro Carvalho ChehabThis section discusses several important recovery actions. 8830ec88413SMauro Carvalho Chehab 8840ec88413SMauro Carvalho ChehabClearing error condition 8850ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~ 8860ec88413SMauro Carvalho Chehab 8870ec88413SMauro Carvalho ChehabMany controllers require its error registers to be cleared by error 8880ec88413SMauro Carvalho Chehabhandler. Different controllers may have different requirements. 8890ec88413SMauro Carvalho Chehab 8900ec88413SMauro Carvalho ChehabFor SATA, it's strongly recommended to clear at least SError register 8910ec88413SMauro Carvalho Chehabduring error handling. 8920ec88413SMauro Carvalho Chehab 8930ec88413SMauro Carvalho ChehabReset 8940ec88413SMauro Carvalho Chehab~~~~~ 8950ec88413SMauro Carvalho Chehab 8960ec88413SMauro Carvalho ChehabDuring EH, resetting is necessary in the following cases. 8970ec88413SMauro Carvalho Chehab 8980ec88413SMauro Carvalho Chehab- HSM is in unknown or invalid state 8990ec88413SMauro Carvalho Chehab 9000ec88413SMauro Carvalho Chehab- HBA is in unknown or invalid state 9010ec88413SMauro Carvalho Chehab 9020ec88413SMauro Carvalho Chehab- EH needs to make HBA/device forget about in-flight commands 9030ec88413SMauro Carvalho Chehab 9040ec88413SMauro Carvalho Chehab- HBA/device behaves weirdly 9050ec88413SMauro Carvalho Chehab 9060ec88413SMauro Carvalho ChehabResetting during EH might be a good idea regardless of error condition 9070ec88413SMauro Carvalho Chehabto improve EH robustness. Whether to reset both or either one of HBA and 9080ec88413SMauro Carvalho Chehabdevice depends on situation but the following scheme is recommended. 9090ec88413SMauro Carvalho Chehab 9100ec88413SMauro Carvalho Chehab- When it's known that HBA is in ready state but ATA/ATAPI device is in 9110ec88413SMauro Carvalho Chehab unknown state, reset only device. 9120ec88413SMauro Carvalho Chehab 9130ec88413SMauro Carvalho Chehab- If HBA is in unknown state, reset both HBA and device. 9140ec88413SMauro Carvalho Chehab 9150ec88413SMauro Carvalho ChehabHBA resetting is implementation specific. For a controller complying to 9160ec88413SMauro Carvalho Chehabtaskfile/BMDMA PCI IDE, stopping active DMA transaction may be 9170ec88413SMauro Carvalho Chehabsufficient iff BMDMA state is the only HBA context. But even mostly 9180ec88413SMauro Carvalho Chehabtaskfile/BMDMA PCI IDE complying controllers may have implementation 9190ec88413SMauro Carvalho Chehabspecific requirements and mechanism to reset themselves. This must be 9200ec88413SMauro Carvalho Chehabaddressed by specific drivers. 9210ec88413SMauro Carvalho Chehab 9220ec88413SMauro Carvalho ChehabOTOH, ATA/ATAPI standard describes in detail ways to reset ATA/ATAPI 9230ec88413SMauro Carvalho Chehabdevices. 9240ec88413SMauro Carvalho Chehab 9250ec88413SMauro Carvalho ChehabPATA hardware reset 9260ec88413SMauro Carvalho Chehab This is hardware initiated device reset signalled with asserted PATA 9270ec88413SMauro Carvalho Chehab RESET- signal. There is no standard way to initiate hardware reset 9280ec88413SMauro Carvalho Chehab from software although some hardware provides registers that allow 9290ec88413SMauro Carvalho Chehab driver to directly tweak the RESET- signal. 9300ec88413SMauro Carvalho Chehab 9310ec88413SMauro Carvalho ChehabSoftware reset 9320ec88413SMauro Carvalho Chehab This is achieved by turning CONTROL SRST bit on for at least 5us. 9330ec88413SMauro Carvalho Chehab Both PATA and SATA support it but, in case of SATA, this may require 9340ec88413SMauro Carvalho Chehab controller-specific support as the second Register FIS to clear SRST 9350ec88413SMauro Carvalho Chehab should be transmitted while BSY bit is still set. Note that on PATA, 9360ec88413SMauro Carvalho Chehab this resets both master and slave devices on a channel. 9370ec88413SMauro Carvalho Chehab 9380ec88413SMauro Carvalho ChehabEXECUTE DEVICE DIAGNOSTIC command 9390ec88413SMauro Carvalho Chehab Although ATA/ATAPI standard doesn't describe exactly, EDD implies 9400ec88413SMauro Carvalho Chehab some level of resetting, possibly similar level with software reset. 9410ec88413SMauro Carvalho Chehab Host-side EDD protocol can be handled with normal command processing 9420ec88413SMauro Carvalho Chehab and most SATA controllers should be able to handle EDD's just like 9430ec88413SMauro Carvalho Chehab other commands. As in software reset, EDD affects both devices on a 9440ec88413SMauro Carvalho Chehab PATA bus. 9450ec88413SMauro Carvalho Chehab 9460ec88413SMauro Carvalho Chehab Although EDD does reset devices, this doesn't suit error handling as 9470ec88413SMauro Carvalho Chehab EDD cannot be issued while BSY is set and it's unclear how it will 9480ec88413SMauro Carvalho Chehab act when device is in unknown/weird state. 9490ec88413SMauro Carvalho Chehab 9500ec88413SMauro Carvalho ChehabATAPI DEVICE RESET command 9510ec88413SMauro Carvalho Chehab This is very similar to software reset except that reset can be 9520ec88413SMauro Carvalho Chehab restricted to the selected device without affecting the other device 9530ec88413SMauro Carvalho Chehab sharing the cable. 9540ec88413SMauro Carvalho Chehab 9550ec88413SMauro Carvalho ChehabSATA phy reset 9560ec88413SMauro Carvalho Chehab This is the preferred way of resetting a SATA device. In effect, 9570ec88413SMauro Carvalho Chehab it's identical to PATA hardware reset. Note that this can be done 9580ec88413SMauro Carvalho Chehab with the standard SCR Control register. As such, it's usually easier 9590ec88413SMauro Carvalho Chehab to implement than software reset. 9600ec88413SMauro Carvalho Chehab 9610ec88413SMauro Carvalho ChehabOne more thing to consider when resetting devices is that resetting 9620ec88413SMauro Carvalho Chehabclears certain configuration parameters and they need to be set to their 9630ec88413SMauro Carvalho Chehabprevious or newly adjusted values after reset. 9640ec88413SMauro Carvalho Chehab 9650ec88413SMauro Carvalho ChehabParameters affected are. 9660ec88413SMauro Carvalho Chehab 9670ec88413SMauro Carvalho Chehab- CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used) 9680ec88413SMauro Carvalho Chehab 9690ec88413SMauro Carvalho Chehab- Parameters set with SET FEATURES including transfer mode setting 9700ec88413SMauro Carvalho Chehab 9710ec88413SMauro Carvalho Chehab- Block count set with SET MULTIPLE MODE 9720ec88413SMauro Carvalho Chehab 9730ec88413SMauro Carvalho Chehab- Other parameters (SET MAX, MEDIA LOCK...) 9740ec88413SMauro Carvalho Chehab 9750ec88413SMauro Carvalho ChehabATA/ATAPI standard specifies that some parameters must be maintained 9760ec88413SMauro Carvalho Chehabacross hardware or software reset, but doesn't strictly specify all of 9770ec88413SMauro Carvalho Chehabthem. Always reconfiguring needed parameters after reset is required for 9780ec88413SMauro Carvalho Chehabrobustness. Note that this also applies when resuming from deep sleep 9790ec88413SMauro Carvalho Chehab(power-off). 9800ec88413SMauro Carvalho Chehab 9810ec88413SMauro Carvalho ChehabAlso, ATA/ATAPI standard requires that IDENTIFY DEVICE / IDENTIFY PACKET 9820ec88413SMauro Carvalho ChehabDEVICE is issued after any configuration parameter is updated or a 9830ec88413SMauro Carvalho Chehabhardware reset and the result used for further operation. OS driver is 9840ec88413SMauro Carvalho Chehabrequired to implement revalidation mechanism to support this. 9850ec88413SMauro Carvalho Chehab 9860ec88413SMauro Carvalho ChehabReconfigure transport 9870ec88413SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~ 9880ec88413SMauro Carvalho Chehab 9890ec88413SMauro Carvalho ChehabFor both PATA and SATA, a lot of corners are cut for cheap connectors, 9900ec88413SMauro Carvalho Chehabcables or controllers and it's quite common to see high transmission 9910ec88413SMauro Carvalho Chehaberror rate. This can be mitigated by lowering transmission speed. 9920ec88413SMauro Carvalho Chehab 9930ec88413SMauro Carvalho ChehabThe following is a possible scheme Jeff Garzik suggested. 9940ec88413SMauro Carvalho Chehab 9950ec88413SMauro Carvalho Chehab If more than $N (3?) transmission errors happen in 15 minutes, 9960ec88413SMauro Carvalho Chehab 9970ec88413SMauro Carvalho Chehab - if SATA, decrease SATA PHY speed. if speed cannot be decreased, 9980ec88413SMauro Carvalho Chehab 9990ec88413SMauro Carvalho Chehab - decrease UDMA xfer speed. if at UDMA0, switch to PIO4, 10000ec88413SMauro Carvalho Chehab 10010ec88413SMauro Carvalho Chehab - decrease PIO xfer speed. if at PIO3, complain, but continue 10020ec88413SMauro Carvalho Chehab 10030ec88413SMauro Carvalho Chehabata_piix Internals 10040ec88413SMauro Carvalho Chehab=================== 10050ec88413SMauro Carvalho Chehab 10060ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/ata_piix.c 10070ec88413SMauro Carvalho Chehab :internal: 10080ec88413SMauro Carvalho Chehab 10090ec88413SMauro Carvalho Chehabsata_sil Internals 10100ec88413SMauro Carvalho Chehab=================== 10110ec88413SMauro Carvalho Chehab 10120ec88413SMauro Carvalho Chehab.. kernel-doc:: drivers/ata/sata_sil.c 10130ec88413SMauro Carvalho Chehab :internal: 10140ec88413SMauro Carvalho Chehab 10150ec88413SMauro Carvalho ChehabThanks 10160ec88413SMauro Carvalho Chehab====== 10170ec88413SMauro Carvalho Chehab 10180ec88413SMauro Carvalho ChehabThe bulk of the ATA knowledge comes thanks to long conversations with 10190ec88413SMauro Carvalho ChehabAndre Hedrick (www.linux-ide.org), and long hours pondering the ATA and 10200ec88413SMauro Carvalho ChehabSCSI specifications. 10210ec88413SMauro Carvalho Chehab 10220ec88413SMauro Carvalho ChehabThanks to Alan Cox for pointing out similarities between SATA and SCSI, 10230ec88413SMauro Carvalho Chehaband in general for motivation to hack on libata. 10240ec88413SMauro Carvalho Chehab 10250ec88413SMauro Carvalho Chehablibata's device detection method, ata_pio_devchk, and in general all 10260ec88413SMauro Carvalho Chehabthe early probing was based on extensive study of Hale Landis's 10270ec88413SMauro Carvalho Chehabprobe/reset code in his ATADRVR driver (www.ata-atapi.com). 1028