Jeff Garzik 2003-2005 Jeff Garzik The contents of this file are subject to the Open Software License version 1.1 that can be found at http://www.opensource.org/licenses/osl-1.1.txt and is included herein by reference. Alternatively, the contents of this file may be used under the terms of the GNU General Public License version 2 (the "GPL") as distributed in the kernel source COPYING file, in which case the provisions of the GPL are applicable instead of the above. If you wish to allow the use of your version of this file only under the terms of the GPL and not to allow others to use your version of this file under the OSL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the GPL. If you do not delete the provisions above, a recipient may use your version of this file under either the OSL or the GPL. libATA is a library used inside the Linux kernel to support ATA host controllers and devices. libATA provides an ATA driver API, class transports for ATA and ATAPI devices, and SCSI<->ATA translation for ATA devices according to the T10 SAT specification. This Guide documents the libATA driver API, library functions, library internals, and a couple sample ATA low-level drivers. struct ata_port_operations is defined for every low-level libata hardware driver, and it controls how the low-level driver interfaces with the ATA and SCSI layers. FIS-based drivers will hook into the system with ->qc_prep() and ->qc_issue() high-level hooks. Hardware which behaves in a manner similar to PCI IDE hardware may utilize several generic helpers, defining at a bare minimum the bus I/O addresses of the ATA shadow register blocks. void (*port_disable) (struct ata_port *); Called from ata_bus_probe() and ata_bus_reset() error paths, as well as when unregistering from the SCSI module (rmmod, hot unplug). This function should do whatever needs to be done to take the port out of use. In most cases, ata_port_disable() can be used as this hook. Called from ata_bus_probe() on a failed probe. Called from ata_bus_reset() on a failed bus reset. Called from ata_scsi_release(). void (*dev_config) (struct ata_port *, struct ata_device *); Called after IDENTIFY [PACKET] DEVICE is issued to each device found. Typically used to apply device-specific fixups prior to issue of SET FEATURES - XFER MODE, and prior to operation. Called by ata_device_add() after ata_dev_identify() determines a device is present. This entry may be specified as NULL in ata_port_operations. void (*set_piomode) (struct ata_port *, struct ata_device *); void (*set_dmamode) (struct ata_port *, struct ata_device *); void (*post_set_mode) (struct ata_port *); unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int); Hooks called prior to the issue of SET FEATURES - XFER MODE command. The optional ->mode_filter() hook is called when libata has built a mask of the possible modes. This is passed to the ->mode_filter() function which should return a mask of valid modes after filtering those unsuitable due to hardware limits. It is not valid to use this interface to add modes. dev->pio_mode and dev->dma_mode are guaranteed to be valid when ->set_piomode() and when ->set_dmamode() is called. The timings for any other drive sharing the cable will also be valid at this point. That is the library records the decisions for the modes of each drive on a channel before it attempts to set any of them. ->post_set_mode() is called unconditionally, after the SET FEATURES - XFER MODE command completes successfully. ->set_piomode() is always called (if present), but ->set_dma_mode() is only called if DMA is possible. void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf); void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf); ->tf_load() is called to load the given taskfile into hardware registers / DMA buffers. ->tf_read() is called to read the hardware registers / DMA buffers, to obtain the current set of taskfile register values. Most drivers for taskfile-based hardware (PIO or MMIO) use ata_tf_load() and ata_tf_read() for these hooks. void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); causes an ATA command, previously loaded with ->tf_load(), to be initiated in hardware. Most drivers for taskfile-based hardware use ata_exec_command() for this hook. int (*check_atapi_dma) (struct ata_queued_cmd *qc); Allow low-level driver to filter ATA PACKET commands, returning a status indicating whether or not it is OK to use DMA for the supplied PACKET command. This hook may be specified as NULL, in which case libata will assume that atapi dma can be supported. u8 (*check_status)(struct ata_port *ap); u8 (*check_altstatus)(struct ata_port *ap); u8 (*check_err)(struct ata_port *ap); Reads the Status/AltStatus/Error ATA shadow register from hardware. On some hardware, reading the Status register has the side effect of clearing the interrupt condition. Most drivers for taskfile-based hardware use ata_check_status() for this hook. Note that because this is called from ata_device_add(), at least a dummy function that clears device interrupts must be provided for all drivers, even if the controller doesn't actually have a taskfile status register. void (*dev_select)(struct ata_port *ap, unsigned int device); Issues the low-level hardware command(s) that causes one of N hardware devices to be considered 'selected' (active and available for use) on the ATA bus. This generally has no meaning on FIS-based devices. Most drivers for taskfile-based hardware use ata_std_dev_select() for this hook. Controllers which do not support second drives on a port (such as SATA contollers) will use ata_noop_dev_select(). void (*set_mode) (struct ata_port *ap); By default libata performs drive and controller tuning in accordance with the ATA timing rules and also applies blacklists and cable limits. Some controllers need special handling and have custom tuning rules, typically raid controllers that use ATA commands but do not actually do drive timing. This hook should not be used to replace the standard controller tuning logic when a controller has quirks. Replacing the default tuning logic in that case would bypass handling for drive and bridge quirks that may be important to data reliability. If a controller needs to filter the mode selection it should use the mode_filter hook instead. void (*phy_reset) (struct ata_port *ap); The very first step in the probe phase. Actions vary depending on the bus type, typically. After waking up the device and probing for device presence (PATA and SATA), typically a soft reset (SRST) will be performed. Drivers typically use the helper functions ata_bus_reset() or sata_phy_reset() for this hook. Many SATA drivers use sata_phy_reset() or call it from within their own phy_reset() functions. void (*bmdma_setup) (struct ata_queued_cmd *qc); void (*bmdma_start) (struct ata_queued_cmd *qc); void (*bmdma_stop) (struct ata_port *ap); u8 (*bmdma_status) (struct ata_port *ap); When setting up an IDE BMDMA transaction, these hooks arm (->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) the hardware's DMA engine. ->bmdma_status is used to read the standard PCI IDE DMA Status register. These hooks are typically either no-ops, or simply not implemented, in FIS-based drivers. Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup() hook. ata_bmdma_setup() will write the pointer to the PRD table to the IDE PRD Table Address register, enable DMA in the DMA Command register, and call exec_command() to begin the transfer. Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start() hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA Command register. Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop() hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA command register. Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook. void (*qc_prep) (struct ata_queued_cmd *qc); int (*qc_issue) (struct ata_queued_cmd *qc); Higher-level hooks, these two hooks can potentially supercede several of the above taskfile/DMA engine hooks. ->qc_prep is called after the buffers have been DMA-mapped, and is typically used to populate the hardware's DMA scatter-gather table. Most drivers use the standard ata_qc_prep() helper function, but more advanced drivers roll their own. ->qc_issue is used to make a command active, once the hardware and S/G tables have been prepared. IDE BMDMA drivers use the helper function ata_qc_issue_prot() for taskfile protocol-based dispatch. More advanced drivers implement their own ->qc_issue. ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and ->bmdma_start() as necessary to initiate a transfer. void (*eng_timeout) (struct ata_port *ap); This is a high level error handling function, called from the error handling thread, when a command times out. Most newer hardware will implement its own error handling code here. IDE BMDMA drivers may use the helper function ata_eng_timeout(). irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); void (*irq_clear) (struct ata_port *); ->irq_handler is the interrupt handling routine registered with the system, by libata. ->irq_clear is called during probe just before the interrupt handler is registered, to be sure hardware is quiet. The second argument, dev_instance, should be cast to a pointer to struct ata_host_set. Most legacy IDE drivers use ata_interrupt() for the irq_handler hook, which scans all ports in the host_set, determines which queued command was active (if any), and calls ata_host_intr(ap,qc). Most legacy IDE drivers use ata_bmdma_irq_clear() for the irq_clear() hook, which simply clears the interrupt and error flags in the DMA status register. u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg); void (*scr_write) (struct ata_port *ap, unsigned int sc_reg, u32 val); Read and write standard SATA phy registers. Currently only used if ->phy_reset hook called the sata_phy_reset() helper function. sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE. int (*port_start) (struct ata_port *ap); void (*port_stop) (struct ata_port *ap); void (*host_stop) (struct ata_host_set *host_set); ->port_start() is called just after the data structures for each port are initialized. Typically this is used to alloc per-port DMA buffers / tables / rings, enable DMA engines, and similar tasks. Some drivers also use this entry point as a chance to allocate driver-private memory for ap->private_data. Many drivers use ata_port_start() as this hook or call it from their own port_start() hooks. ata_port_start() allocates space for a legacy IDE PRD table and returns. ->port_stop() is called after ->host_stop(). It's sole function is to release DMA/memory resources, now that they are no longer actively being used. Many drivers also free driver-private data from port at this time. Many drivers use ata_port_stop() as this hook, which frees the PRD table. ->host_stop() is called after all ->port_stop() calls have completed. The hook must finalize hardware shutdown, release DMA and other resources, etc. This hook may be specified as NULL, in which case it is not called. This chapter describes how errors are handled under libata. Readers are advised to read SCSI EH (Documentation/scsi/scsi_eh.txt) and ATA exceptions doc first. In libata, a command is represented with struct ata_queued_cmd or qc. qc's are preallocated during port initialization and repetitively used for command executions. Currently only one qc is allocated per port but yet-to-be-merged NCQ branch allocates one for each tag and maps each qc to NCQ tag 1-to-1. libata commands can originate from two sources - libata itself and SCSI midlayer. libata internal commands are used for initialization and error handling. All normal blk requests and commands for SCSI emulation are passed as SCSI commands through queuecommand callback of SCSI host template. Internal commands First, qc is allocated and initialized using ata_qc_new_init(). Although ata_qc_new_init() doesn't implement any wait or retry mechanism when qc is not available, internal commands are currently issued only during initialization and error recovery, so no other command is active and allocation is guaranteed to succeed. Once allocated qc's taskfile is initialized for the command to be executed. qc currently has two mechanisms to notify completion. One is via qc->complete_fn() callback and the other is completion qc->waiting. qc->complete_fn() callback is the asynchronous path used by normal SCSI translated commands and qc->waiting is the synchronous (issuer sleeps in process context) path used by internal commands. Once initialization is complete, host_set lock is acquired and the qc is issued. SCSI commands All libata drivers use ata_scsi_queuecmd() as hostt->queuecommand callback. scmds can either be simulated or translated. No qc is involved in processing a simulated scmd. The result is computed right away and the scmd is completed. For a translated scmd, ata_qc_new_init() is invoked to allocate a qc and the scmd is translated into the qc. SCSI midlayer's completion notification function pointer is stored into qc->scsidone. qc->complete_fn() callback is used for completion notification. ATA commands use ata_scsi_qc_complete() while ATAPI commands use atapi_qc_complete(). Both functions end up calling qc->scsidone to notify upper layer when the qc is finished. After translation is completed, the qc is issued with ata_qc_issue(). Note that SCSI midlayer invokes hostt->queuecommand while holding host_set lock, so all above occur while holding host_set lock. Depending on which protocol and which controller are used, commands are processed differently. For the purpose of discussion, a controller which uses taskfile interface and all standard callbacks is assumed. Currently 6 ATA command protocols are used. They can be sorted into the following four categories according to how they are processed. ATA NO DATA or DMA ATA_PROT_NODATA and ATA_PROT_DMA fall into this category. These types of commands don't require any software intervention once issued. Device will raise interrupt on completion. ATA PIO ATA_PROT_PIO is in this category. libata currently implements PIO with polling. ATA_NIEN bit is set to turn off interrupt and pio_task on ata_wq performs polling and IO. ATAPI NODATA or DMA ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this category. packet_task is used to poll BSY bit after issuing PACKET command. Once BSY is turned off by the device, packet_task transfers CDB and hands off processing to interrupt handler. ATAPI PIO ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set and, as in ATAPI NODATA or DMA, packet_task submits cdb. However, after submitting cdb, further processing (data transfer) is handed off to pio_task. Once issued, all qc's are either completed with ata_qc_complete() or time out. For commands which are handled by interrupts, ata_host_intr() invokes ata_qc_complete(), and, for PIO tasks, pio_task invokes ata_qc_complete(). In error cases, packet_task may also complete commands. ata_qc_complete() does the following. DMA memory is unmapped. ATA_QCFLAG_ACTIVE is clared from qc->flags. qc->complete_fn() callback is invoked. If the return value of the callback is not zero. Completion is short circuited and ata_qc_complete() returns. __ata_qc_complete() is called, which does qc->flags is cleared to zero. ap->active_tag and qc->tag are poisoned. qc->waiting is claread & completed (in that order). qc is deallocated by clearing appropriate bit in ap->qactive. So, it basically notifies upper layer and deallocates qc. One exception is short-circuit path in #3 which is used by atapi_qc_complete(). For all non-ATAPI commands, whether it fails or not, almost the same code path is taken and very little error handling takes place. A qc is completed with success status if it succeeded, with failed status otherwise. However, failed ATAPI commands require more handling as REQUEST SENSE is needed to acquire sense data. If an ATAPI command fails, ata_qc_complete() is invoked with error status, which in turn invokes atapi_qc_complete() via qc->complete_fn() callback. This makes atapi_qc_complete() set scmd->result to SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As the sense data is empty but scmd->result is CHECK CONDITION, SCSI midlayer will invoke EH for the scmd, and returning 1 makes ata_qc_complete() to return without deallocating the qc. This leads us to ata_scsi_error() with partially completed qc. ata_scsi_error() is the current transportt->eh_strategy_handler() for libata. As discussed above, this will be entered in two cases - timeout and ATAPI error completion. This function calls low level libata driver's eng_timeout() callback, the standard callback for which is ata_eng_timeout(). It checks if a qc is active and calls ata_qc_timeout() on the qc if so. Actual error handling occurs in ata_qc_timeout(). If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and completes the qc. Note that as we're currently in EH, we cannot call scsi_done. As described in SCSI EH doc, a recovered scmd should be either retried with scsi_queue_insert() or finished with scsi_finish_command(). Here, we override qc->scsidone with scsi_finish_command() and calls ata_qc_complete(). If EH is invoked due to a failed ATAPI qc, the qc here is completed but not deallocated. The purpose of this half-completion is to use the qc as place holder to make EH code reach this place. This is a bit hackish, but it works. Once control reaches here, the qc is deallocated by invoking __ata_qc_complete() explicitly. Then, internal qc for REQUEST SENSE is issued. Once sense data is acquired, scmd is finished by directly invoking scsi_finish_command() on the scmd. Note that as we already have completed and deallocated the qc which was associated with the scmd, we don't need to/cannot call ata_qc_complete() again. Error representation is too crude. Currently any and all error conditions are represented with ATA STATUS and ERROR registers. Errors which aren't ATA device errors are treated as ATA device errors by setting ATA_ERR bit. Better error descriptor which can properly represent ATA and other errors/exceptions is needed. When handling timeouts, no action is taken to make device forget about the timed out command and ready for new commands. EH handling via ata_scsi_error() is not properly protected from usual command processing. On EH entrance, the device is not in quiescent state. Timed out commands may succeed or fail any time. pio_task and atapi_task may still be running. Too weak error recovery. Devices / controllers causing HSM mismatch errors and other errors quite often require reset to return to known state. Also, advanced error handling is necessary to support features like NCQ and hotplug. ATA errors are directly handled in the interrupt handler and PIO errors in pio_task. This is problematic for advanced error handling for the following reasons. First, advanced error handling often requires context and internal qc execution. Second, even a simple failure (say, CRC error) needs information gathering and could trigger complex error handling (say, resetting & reconfiguring). Having multiple code paths to gather information, enter EH and trigger actions makes life painful. Third, scattered EH code makes implementing low level drivers difficult. Low level drivers override libata callbacks. If EH is scattered over several places, each affected callbacks should perform its part of error handling. This can be error prone and painful. Kernel Hackers Manual November 2007 ata_tf_to_fis 9 ata_tf_to_fis Convert ATA taskfile to SATA FIS structure void ata_tf_to_fis const struct ata_taskfile * tf u8 * fis u8 pmp tf Taskfile to convert fis Buffer into which data will output pmp Port multiplier port Converts a standard ATA taskfile to a Serial ATA FIS structure (Register - Host to Device). Inherited from caller. Kernel Hackers Manual November 2007 ata_tf_from_fis 9 ata_tf_from_fis Convert SATA FIS to ATA taskfile void ata_tf_from_fis const u8 * fis struct ata_taskfile * tf fis Buffer from which data will be input tf Taskfile to output Converts a serial ATA FIS structure to a standard ATA taskfile. Inherited from caller. Kernel Hackers Manual November 2007 ata_dev_classify 9 ata_dev_classify determine device type based on ATA-spec signature unsigned int ata_dev_classify const struct ata_taskfile * tf tf ATA taskfile register set for device to be identified Determine from taskfile register contents whether a device is ATA or ATAPI, as per Signature and persistence section of ATA/PI spec (volume 1, sect 5.14). None. Device type, ATA_DEV_ATA, ATA_DEV_ATAPI, or ATA_DEV_UNKNOWN the event of failure. Kernel Hackers Manual November 2007 ata_id_string 9 ata_id_string Convert IDENTIFY DEVICE page into string void ata_id_string const u16 * id unsigned char * s unsigned int ofs unsigned int len id IDENTIFY DEVICE results we will examine s string into which data is output ofs offset into identify device page len length of string to return. must be an even number. The strings in the IDENTIFY DEVICE page are broken up into 16-bit chunks. Run through the string, and output each 8-bit chunk linearly, regardless of platform. caller. Kernel Hackers Manual November 2007 ata_id_c_string 9 ata_id_c_string Convert IDENTIFY DEVICE page into C string void ata_id_c_string const u16 * id unsigned char * s unsigned int ofs unsigned int len id IDENTIFY DEVICE results we will examine s string into which data is output ofs offset into identify device page len length of string to return. must be an odd number. This function is identical to ata_id_string except that it trims trailing spaces and terminates the resulting string with null. len must be actual maximum length (even number) + 1. caller. Kernel Hackers Manual November 2007 ata_noop_dev_select 9 ata_noop_dev_select Select device 0/1 on ATA bus void ata_noop_dev_select struct ata_port * ap unsigned int device ap ATA channel to manipulate device ATA device (numbered from zero) to select This function performs no actual function. May be used as the dev_select entry in ata_port_operations. caller. Kernel Hackers Manual November 2007 ata_std_dev_select 9 ata_std_dev_select Select device 0/1 on ATA bus void ata_std_dev_select struct ata_port * ap unsigned int device ap ATA channel to manipulate device ATA device (numbered from zero) to select Use the method defined in the ATA specification to make either device 0, or device 1, active on the ATA channel. Works with both PIO and MMIO. May be used as the dev_select entry in ata_port_operations. caller. Kernel Hackers Manual November 2007 ata_port_queue_task 9 ata_port_queue_task Queue port_task void ata_port_queue_task struct ata_port * ap void (*fn) void * void * data unsigned long delay ap The ata_port to queue port_task for fn -- undescribed -- data -- undescribed -- delay -- undescribed -- Schedule fn(data) for execution after delay jiffies using port_task. There is one port_task per port and it's the user(low level driver)'s responsibility to make sure that only one task is active at any given time. libata core layer takes care of synchronization between port_task and EH. ata_port_queue_task may be ignored for EH synchronization. Inherited from caller. Kernel Hackers Manual November 2007 ata_pio_need_iordy 9 ata_pio_need_iordy check if iordy needed unsigned int ata_pio_need_iordy const struct ata_device * adev adev ATA device Check if the current speed of the device requires IORDY. Used by various controllers for chip configuration. Kernel Hackers Manual November 2007 ata_port_probe 9 ata_port_probe Mark port as enabled void ata_port_probe struct ata_port * ap ap Port for which we indicate enablement Modify ap data structure such that the system thinks that the entire port is enabled. host_set lock, or some other form of serialization. Kernel Hackers Manual November 2007 __sata_phy_reset 9 __sata_phy_reset Wake/reset a low-level SATA PHY void __sata_phy_reset struct ata_port * ap ap SATA port associated with target SATA PHY. This function issues commands to standard SATA Sxxx PHY registers, to wake up the phy (and device), and clear any reset condition. PCI/etc. bus probe sem. Kernel Hackers Manual November 2007 sata_phy_reset 9 sata_phy_reset Reset SATA bus. void sata_phy_reset struct ata_port * ap ap SATA port associated with target SATA PHY. This function resets the SATA bus, and then probes the bus for devices. PCI/etc. bus probe sem. Kernel Hackers Manual November 2007 ata_dev_pair 9 ata_dev_pair return other device on cable struct ata_device * ata_dev_pair struct ata_port * ap struct ata_device * adev ap port adev device Obtain the other device on the same cable, or if none is present NULL is returned Kernel Hackers Manual November 2007 ata_port_disable 9 ata_port_disable Disable port. void ata_port_disable struct ata_port * ap ap Port to be disabled. Modify ap data structure such that the system thinks that the entire port is disabled, and should never attempt to probe or communicate with devices on this port. host_set lock, or some other form of serialization. Kernel Hackers Manual November 2007 ata_busy_sleep 9 ata_busy_sleep sleep until BSY clears, or timeout unsigned int ata_busy_sleep struct ata_port * ap unsigned long tmout_pat unsigned long tmout ap port containing status register to be polled tmout_pat impatience timeout tmout overall timeout Sleep until ATA Status register bit BSY clears, or a timeout occurs. None. Kernel Hackers Manual November 2007 ata_bus_reset 9 ata_bus_reset reset host port and associated ATA channel void ata_bus_reset struct ata_port * ap ap port to reset This is typically the first time we actually start issuing commands to the ATA channel. We wait for BSY to clear, then issue EXECUTE DEVICE DIAGNOSTIC command, polling for its result. Determine what devices, if any, are on the channel by looking at the device 0/1 error register. Look at the signature stored in each device's taskfile registers, to determine if the device is ATA or ATAPI. PCI/etc. bus probe sem. Obtains host_set lock. Sets ATA_FLAG_PORT_DISABLED if bus reset fails. Kernel Hackers Manual November 2007 ata_std_probeinit 9 ata_std_probeinit initialize probing void ata_std_probeinit struct ata_port * ap ap port to be probed ap is about to be probed. Initialize it. This function is to be used as standard callback for ata_drive_probe_reset. NOTE!!! Do not use this function as probeinit if a low level driver implements only hardreset. Just pass NULL as probeinit in that case. Using this function is probably okay but doing so makes reset sequence different from the original ->phy_reset implementation and Jeff nervous. :-P Kernel Hackers Manual November 2007 ata_std_softreset 9 ata_std_softreset reset host port via ATA SRST int ata_std_softreset struct ata_port * ap int verbose unsigned int * classes ap port to reset verbose fail verbosely classes resulting classes of attached devices Reset host port using ATA SRST. This function is to be used as standard callback for ata_drive_*_reset functions. Kernel thread context (may sleep) 0 on success, -errno otherwise. Kernel Hackers Manual November 2007 sata_std_hardreset 9 sata_std_hardreset reset host port via SATA phy reset int sata_std_hardreset struct ata_port * ap int verbose unsigned int * class ap port to reset verbose fail verbosely class resulting class of attached device SATA phy-reset host port using DET bits of SControl register. This function is to be used as standard callback for ata_drive_*_reset. Kernel thread context (may sleep) 0 on success, -errno otherwise. Kernel Hackers Manual November 2007 ata_std_postreset 9 ata_std_postreset standard postreset callback void ata_std_postreset struct ata_port * ap unsigned int * classes ap the target ata_port classes classes of attached devices This function is invoked after a successful reset. Note that the device might have been reset more than once using different reset methods before postreset is invoked. This function is to be used as standard callback for ata_drive_*_reset. Kernel thread context (may sleep) Kernel Hackers Manual November 2007 ata_std_probe_reset 9 ata_std_probe_reset standard probe reset method int ata_std_probe_reset struct ata_port * ap unsigned int * classes ap prot to perform probe-reset classes resulting classes of attached devices The stock off-the-shelf ->probe_reset method. Kernel thread context (may sleep) 0 on success, -errno otherwise. Kernel Hackers Manual November 2007 ata_drive_probe_reset 9 ata_drive_probe_reset Perform probe reset with given methods int ata_drive_probe_reset struct ata_port * ap ata_probeinit_fn_t probeinit ata_reset_fn_t softreset ata_reset_fn_t hardreset ata_postreset_fn_t postreset unsigned int * classes ap port to reset probeinit probeinit method (can be NULL) softreset softreset method (can be NULL) hardreset hardreset method (can be NULL) postreset postreset method (can be NULL) classes resulting classes of attached devices Reset the specified port and classify attached devices using given methods. This function prefers softreset but tries all possible reset sequences to reset and classify devices. This function is intended to be used for constructing ->probe_reset callback by low level drivers. Reset methods should follow the following rules. - Return 0 on sucess, -errno on failure. - If classification is supported, fill classes[] with recognized class codes. - If classification is not supported, leave classes[] alone. - If verbose is non-zero, print error message on failure; otherwise, shut up. Kernel thread context (may sleep) 0 on success, -EINVAL if no reset method is avaliable, -ENODEV if classification fails, and any error code from reset methods. Kernel Hackers Manual November 2007 ata_dev_revalidate 9 ata_dev_revalidate Revalidate ATA device int ata_dev_revalidate struct ata_port * ap struct ata_device * dev int post_reset ap port on which the device to revalidate resides dev device to revalidate post_reset is this revalidation after reset? Re-read IDENTIFY page and make sure dev is still attached to the port. Kernel thread context (may sleep) 0 on success, negative errno otherwise Kernel Hackers Manual November 2007 ata_qc_prep 9 ata_qc_prep Prepare taskfile for submission void ata_qc_prep struct ata_queued_cmd * qc qc Metadata associated with taskfile to be prepared Prepare ATA taskfile for submission. spin_lock_irqsave(host_set lock) Kernel Hackers Manual November 2007 ata_sg_init_one 9 ata_sg_init_one Associate command with memory buffer void ata_sg_init_one struct ata_queued_cmd * qc void * buf unsigned int buflen qc Command to be associated buf Memory buffer buflen Length of memory buffer, in bytes. Initialize the data-related elements of queued_cmd qc to point to a single memory buffer, buf of byte length buflen. spin_lock_irqsave(host_set lock) Kernel Hackers Manual November 2007 ata_sg_init 9 ata_sg_init Associate command with scatter-gather table. void ata_sg_init struct ata_queued_cmd * qc struct scatterlist * sg unsigned int n_elem qc Command to be associated sg Scatter-gather table. n_elem Number of elements in s/g table. Initialize the data-related elements of queued_cmd qc to point to a scatter-gather table sg, containing n_elem elements. spin_lock_irqsave(host_set lock) Kernel Hackers Manual November 2007 ata_eng_timeout 9 ata_eng_timeout Handle timeout of queued command void ata_eng_timeout struct ata_port * ap ap Port on which timed-out command is active Some part of the kernel (currently, only the SCSI layer) has noticed that the active command on port ap has not completed after a specified length of time. Handle this condition by disabling DMA (if necessary) and completing transactions, with error if necessary. This also handles the case of the lost interrupt, where for some reason (possibly hardware bug, possibly driver bug) an interrupt was not delivered to the driver, even though the transaction completed successfully. Inherited from SCSI layer (none, can sleep) Kernel Hackers Manual November 2007 ata_qc_issue_prot 9 ata_qc_issue_prot issue taskfile to device in proto-dependent manner unsigned int ata_qc_issue_prot struct ata_queued_cmd * qc qc command to issue to device Using various libata functions and hooks, this function starts an ATA command. ATA commands are grouped into classes called protocols, and issuing each type of protocol is slightly different. May be used as the qc_issue entry in ata_port_operations. spin_lock_irqsave(host_set lock) Zero on success, AC_ERR_* mask on failure Kernel Hackers Manual November 2007 ata_host_intr 9 ata_host_intr Handle host interrupt for given (port, task) unsigned int ata_host_intr struct ata_port * ap struct ata_queued_cmd * qc ap Port on which interrupt arrived (possibly...) qc Taskfile currently active in engine Handle host interrupt for given queued command. Currently, only DMA interrupts are handled. All other commands are handled via polling with interrupts disabled (nIEN bit). spin_lock_irqsave(host_set lock) One if interrupt was handled, zero if not (shared irq). Kernel Hackers Manual November 2007 ata_interrupt 9 ata_interrupt Default ATA host interrupt handler irqreturn_t ata_interrupt int irq void * dev_instance struct pt_regs * regs irq irq line (unused) dev_instance pointer to our ata_host_set information structure regs unused Default interrupt handler for PCI IDE devices. Calls ata_host_intr for each port that is not disabled. Obtains host_set lock during operation. IRQ_NONE or IRQ_HANDLED. Kernel Hackers Manual November 2007 ata_device_resume 9 ata_device_resume wakeup a previously suspended devices int ata_device_resume struct ata_port * ap struct ata_device * dev ap port the device is connected to dev the device to resume Kick the drive back into action, by sending it an idle immediate command and making sure its transfer mode matches between drive and host. Kernel Hackers Manual November 2007 ata_device_suspend 9 ata_device_suspend prepare a device for suspend int ata_device_suspend struct ata_port * ap struct ata_device * dev pm_message_t state ap port the device is connected to dev the device to suspend state -- undescribed -- Flush the cache on the drive, if appropriate, then issue a standbynow command. Kernel Hackers Manual November 2007 ata_port_start 9 ata_port_start Set port up for dma. int ata_port_start struct ata_port * ap ap Port to initialize Called just after data structures for each port are initialized. Allocates space for PRD table. May be used as the port_start entry in ata_port_operations. Inherited from caller. Kernel Hackers Manual November 2007 ata_port_stop 9 ata_port_stop Undo ata_port_start void ata_port_stop struct ata_port * ap ap Port to shut down Frees the PRD table. May be used as the port_stop entry in ata_port_operations. Inherited from caller. Kernel Hackers Manual November 2007 ata_device_add 9 ata_device_add Register hardware device with ATA and SCSI layers int ata_device_add const struct ata_probe_ent * ent ent Probe information describing hardware device to be registered This function processes the information provided in the probe information struct ent, allocates the necessary ATA and SCSI host information structures, initializes them, and registers everything with requisite kernel subsystems. This function requests irqs, probes the ATA bus, and probes the SCSI bus. PCI/etc. bus probe sem. Number of ports registered. Zero on error (no ports registered). Kernel Hackers Manual November 2007 ata_host_set_remove 9 ata_host_set_remove PCI layer callback for device removal void ata_host_set_remove struct ata_host_set * host_set host_set ATA host set that was removed Unregister all objects associated with this host set. Free those objects. Inherited from calling layer (may sleep). Kernel Hackers Manual November 2007 ata_scsi_release 9 ata_scsi_release SCSI layer callback hook for host unload int ata_scsi_release struct Scsi_Host * host host libata host to be unloaded Performs all duties necessary to shut down a libata port... Kill port kthread, disable port, and release resources. Inherited from SCSI layer. One. Kernel Hackers Manual November 2007 ata_std_ports 9 ata_std_ports initialize ioaddr with standard port offsets. void ata_std_ports struct ata_ioports * ioaddr ioaddr IO address structure to be initialized Utility function which initializes data_addr, error_addr, feature_addr, nsect_addr, lbal_addr, lbam_addr, lbah_addr, device_addr, status_addr, and command_addr to standard offsets relative to cmd_addr. Does not set ctl_addr, altstatus_addr, bmdma_addr, or scr_addr. Kernel Hackers Manual November 2007 ata_pci_remove_one 9 ata_pci_remove_one PCI layer callback for device removal void ata_pci_remove_one struct pci_dev * pdev pdev PCI device that was removed PCI layer indicates to libata via this hook that hot-unplug or module unload event has occurred. Handle this by unregistering all objects associated with this PCI device. Free those objects. Then finally release PCI resources and disable device. Inherited from PCI layer (may sleep). Kernel Hackers Manual November 2007 ata_rwcmd_protocol 9 ata_rwcmd_protocol set taskfile r/w commands and protocol int ata_rwcmd_protocol struct ata_queued_cmd * qc qc command to examine and configure Examine the device configuration and tf->flags to calculate the proper read/write commands and protocol to use. caller. Kernel Hackers Manual November 2007 ata_pack_xfermask 9 ata_pack_xfermask Pack pio, mwdma and udma masks into xfer_mask unsigned int ata_pack_xfermask unsigned int pio_mask unsigned int mwdma_mask unsigned int udma_mask pio_mask pio_mask mwdma_mask mwdma_mask udma_mask udma_mask Pack pio_mask, mwdma_mask and udma_mask into a single unsigned int xfer_mask. None. Packed xfer_mask. Kernel Hackers Manual November 2007 ata_unpack_xfermask 9 ata_unpack_xfermask Unpack xfer_mask into pio, mwdma and udma masks void ata_unpack_xfermask unsigned int xfer_mask unsigned int * pio_mask unsigned int * mwdma_mask unsigned int * udma_mask xfer_mask xfer_mask to unpack pio_mask resulting pio_mask mwdma_mask resulting mwdma_mask udma_mask resulting udma_mask Unpack xfer_mask into pio_mask, mwdma_mask and udma_mask. Any NULL distination masks will be ignored. Kernel Hackers Manual November 2007 ata_xfer_mask2mode 9 ata_xfer_mask2mode Find matching XFER_* for the given xfer_mask u8 ata_xfer_mask2mode unsigned int xfer_mask xfer_mask xfer_mask of interest Return matching XFER_* value for xfer_mask. Only the highest bit of xfer_mask is considered. None. Matching XFER_* value, 0 if no match found. Kernel Hackers Manual November 2007 ata_xfer_mode2mask 9 ata_xfer_mode2mask Find matching xfer_mask for XFER_* unsigned int ata_xfer_mode2mask u8 xfer_mode xfer_mode XFER_* of interest Return matching xfer_mask for xfer_mode. None. Matching xfer_mask, 0 if no match found. Kernel Hackers Manual November 2007 ata_xfer_mode2shift 9 ata_xfer_mode2shift Find matching xfer_shift for XFER_* int ata_xfer_mode2shift unsigned int xfer_mode xfer_mode XFER_* of interest Return matching xfer_shift for xfer_mode. None. Matching xfer_shift, -1 if no match found. Kernel Hackers Manual November 2007 ata_mode_string 9 ata_mode_string convert xfer_mask to string const char * ata_mode_string unsigned int xfer_mask xfer_mask mask of bits supported; only highest bit counts. Determine string which represents the highest speed (highest bit in modemask). None. Constant C string representing highest speed listed in mode_mask, or the constant C string <n/a>. Kernel Hackers Manual November 2007 ata_pio_devchk 9 ata_pio_devchk PATA device presence detection unsigned int ata_pio_devchk struct ata_port * ap unsigned int device ap ATA channel to examine device Device to examine (starting at zero) This technique was originally described in Hale Landis's ATADRVR (www.ata-atapi.com), and later found its way into the ATA/ATAPI spec. Write a pattern to the ATA shadow registers, and if a device is present, it will respond by correctly storing and echoing back the ATA shadow register contents. caller. Kernel Hackers Manual November 2007 ata_mmio_devchk 9 ata_mmio_devchk PATA device presence detection unsigned int ata_mmio_devchk struct ata_port * ap unsigned int device ap ATA channel to examine device Device to examine (starting at zero) This technique was originally described in Hale Landis's ATADRVR (www.ata-atapi.com), and later found its way into the ATA/ATAPI spec. Write a pattern to the ATA shadow registers, and if a device is present, it will respond by correctly storing and echoing back the ATA shadow register contents. caller. Kernel Hackers Manual November 2007 ata_devchk 9 ata_devchk PATA device presence detection unsigned int ata_devchk struct ata_port * ap unsigned int device ap ATA channel to examine device Device to examine (starting at zero) Dispatch ATA device presence detection, depending on whether we are using PIO or MMIO to talk to the ATA shadow registers. caller. Kernel Hackers Manual November 2007 ata_dev_try_classify 9 ata_dev_try_classify Parse returned ATA device signature unsigned int ata_dev_try_classify struct ata_port * ap unsigned int device u8 * r_err ap ATA channel to examine device Device to examine (starting at zero) r_err Value of error register on completion After an event -- SRST, E.D.D., or SATA COMRESET -- occurs, an ATA/ATAPI-defined set of values is placed in the ATA shadow registers, indicating the results of device detection and diagnostics. Select the ATA device, and read the values from the ATA shadow registers. Then parse according to the Error register value, and the spec-defined values examined by ata_dev_classify. caller. Device type - ATA_DEV_ATA, ATA_DEV_ATAPI or ATA_DEV_NONE. Kernel Hackers Manual November 2007 ata_dev_select 9 ata_dev_select Select device 0/1 on ATA bus void ata_dev_select struct ata_port * ap unsigned int device unsigned int wait unsigned int can_sleep ap ATA channel to manipulate device ATA device (numbered from zero) to select wait non-zero to wait for Status register BSY bit to clear can_sleep non-zero if context allows sleeping Use the method defined in the ATA specification to make either device 0, or device 1, active on the ATA channel. This is a high-level version of ata_std_dev_select, which additionally provides the services of inserting the proper pauses and status polling, where needed. caller. Kernel Hackers Manual November 2007 ata_dump_id 9 ata_dump_id IDENTIFY DEVICE info debugging output void ata_dump_id const u16 * id id IDENTIFY DEVICE page to dump Dump selected 16-bit words from the given IDENTIFY DEVICE page. caller. Kernel Hackers Manual November 2007 ata_id_xfermask 9 ata_id_xfermask Compute xfermask from the given IDENTIFY data unsigned int ata_id_xfermask const u16 * id id IDENTIFY data to compute xfer mask from Compute the xfermask for this device. This is not as trivial as it seems if we must consider early devices correctly. pre IDE drive timing (do we care ?). None. Computed xfermask Kernel Hackers Manual November 2007 ata_port_flush_task 9 ata_port_flush_task Flush port_task void ata_port_flush_task struct ata_port * ap ap The ata_port to flush port_task for After this function completes, port_task is guranteed not to be running or scheduled. Kernel thread context (may sleep) Kernel Hackers Manual November 2007 ata_exec_internal 9 ata_exec_internal execute libata internal command unsigned ata_exec_internal struct ata_port * ap struct ata_device * dev struct ata_taskfile * tf int dma_dir void * buf unsigned int buflen ap Port to which the command is sent dev Device to which the command is sent tf Taskfile registers for the command and the result dma_dir Data tranfer direction of the command buf Data buffer of the command buflen Length of data buffer Executes libata internal command with timeout. tf contains command on entry and result on return. Timeout and error conditions are reported via return value. No recovery action is taken after a command times out. It's caller's duty to clean up after timeout. None. Should be called with kernel context, might sleep. Kernel Hackers Manual November 2007 ata_dev_read_id 9 ata_dev_read_id Read ID data from the specified device int ata_dev_read_id struct ata_port * ap struct ata_device * dev unsigned int * p_class int post_reset u16 ** p_id ap port on which target device resides dev target device p_class pointer to class of the target device (may be changed) post_reset is this read ID post-reset? p_id read IDENTIFY page (newly allocated) Read ID data from the specified device. ATA_CMD_ID_ATA is performed on ATA devices and ATA_CMD_ID_ATAPI on ATAPI devices. This function also issues ATA_CMD_INIT_DEV_PARAMS for pre-ATA4 drives. Kernel thread context (may sleep) 0 on success, -errno otherwise. Kernel Hackers Manual November 2007 ata_dev_configure 9 ata_dev_configure Configure the specified ATA/ATAPI device int ata_dev_configure struct ata_port * ap struct ata_device * dev int print_info ap Port on which target device resides dev Target device to configure print_info Enable device info printout Configure dev according to dev->id. Generic and low-level driver specific fixups are also applied. Kernel thread context (may sleep) 0 on success, -errno otherwise Kernel Hackers Manual November 2007 ata_bus_probe 9 ata_bus_probe Reset and probe ATA bus int ata_bus_probe struct ata_port * ap ap Bus to probe Master ATA bus probing function. Initiates a hardware-dependent bus reset, then attempts to identify any devices found on the bus. PCI/etc. bus probe sem. Zero on success, non-zero on error. Kernel Hackers Manual November 2007 sata_print_link_status 9 sata_print_link_status Print SATA link status void sata_print_link_status struct ata_port * ap ap SATA port to printk link status about This function prints link speed and status of a SATA link. None. Kernel Hackers Manual November 2007 ata_set_mode 9 ata_set_mode Program timings and issue SET FEATURES - XFER void ata_set_mode struct ata_port * ap ap port on which timings will be programmed Set ATA device disk transfer mode (PIO3, UDMA6, etc.). PCI/etc. bus probe sem. Kernel Hackers Manual November 2007 ata_tf_to_host 9 ata_tf_to_host issue ATA taskfile to host controller void ata_tf_to_host struct ata_port * ap const struct ata_taskfile * tf ap port to which command is being issued tf ATA taskfile register set Issues ATA taskfile register set to ATA host controller, with proper synchronization with interrupt handler and other threads. spin_lock_irqsave(host_set lock) Kernel Hackers Manual November 2007 ata_dev_same_device 9 ata_dev_same_device Determine whether new ID matches configured device int ata_dev_same_device struct ata_port * ap struct ata_device * dev unsigned int new_class const u16 * new_id ap port on which the device to compare against resides dev device to compare against new_class class of the new device new_id IDENTIFY page of the new device Compare new_class and new_id against dev and determine whether dev is the device indicated by new_class and new_id. None. 1 if dev matches new_class and new_id, 0 otherwise. Kernel Hackers Manual November 2007 ata_dev_xfermask 9 ata_dev_xfermask Compute supported xfermask of the given device void ata_dev_xfermask struct ata_port * ap struct ata_device * dev ap Port on which the device to compute xfermask for resides dev Device to compute xfermask for Compute supported xfermask of dev and store it in dev->*_mask. This function is responsible for applying all known limits including host controller limits, device blacklist, etc... The current implementation limits all transfer modes to the fastest of the lowested device on the port. This is not required on most controllers. None. Kernel Hackers Manual November 2007 ata_dev_set_xfermode 9 ata_dev_set_xfermode Issue SET FEATURES - XFER MODE command unsigned int ata_dev_set_xfermode struct ata_port * ap struct ata_device * dev ap Port associated with device dev dev Device to which command will be sent Issue SET FEATURES - XFER MODE command to device dev on port ap. PCI/etc. bus probe sem. 0 on success, AC_ERR_* mask otherwise. Kernel Hackers Manual November 2007 ata_dev_init_params 9 ata_dev_init_params Issue INIT DEV PARAMS command unsigned int ata_dev_init_params struct ata_port * ap struct ata_device * dev u16 heads u16 sectors ap Port associated with device dev dev Device to which command will be sent heads -- undescribed -- sectors -- undescribed -- Kernel thread context (may sleep) 0 on success, AC_ERR_* mask otherwise. Kernel Hackers Manual November 2007 ata_sg_clean 9 ata_sg_clean Unmap DMA memory associated with command void ata_sg_clean struct ata_queued_cmd * qc qc Command containing DMA memory to be released Unmap all mapped DMA memory associated with this command. spin_lock_irqsave(host_set lock) Kernel Hackers Manual November 2007 ata_fill_sg 9 ata_fill_sg Fill PCI IDE PRD table void ata_fill_sg struct ata_queued_cmd * qc