| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> |
| |
| <book id="libataDevGuide"> |
| <bookinfo> |
| <title>libATA Developer's Guide</title> |
| |
| <authorgroup> |
| <author> |
| <firstname>Jeff</firstname> |
| <surname>Garzik</surname> |
| </author> |
| </authorgroup> |
| |
| <copyright> |
| <year>2003-2005</year> |
| <holder>Jeff Garzik</holder> |
| </copyright> |
| |
| <legalnotice> |
| <para> |
| The contents of this file are subject to the Open |
| Software License version 1.1 that can be found at |
| <ulink url="http://www.opensource.org/licenses/osl-1.1.txt">http://www.opensource.org/licenses/osl-1.1.txt</ulink> and is included herein |
| by reference. |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| |
| </legalnotice> |
| </bookinfo> |
| |
| <toc></toc> |
| |
| <chapter id="libataIntroduction"> |
| <title>Introduction</title> |
| <para> |
| 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. |
| </para> |
| <para> |
| This Guide documents the libATA driver API, library functions, library |
| internals, and a couple sample ATA low-level drivers. |
| </para> |
| </chapter> |
| |
| <chapter id="libataDriverApi"> |
| <title>libata Driver API</title> |
| <para> |
| 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. |
| </para> |
| <para> |
| 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. |
| </para> |
| <sect1> |
| <title>struct ata_port_operations</title> |
| |
| <sect2><title>Disable ATA port</title> |
| <programlisting> |
| void (*port_disable) (struct ata_port *); |
| </programlisting> |
| |
| <para> |
| 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. |
| </para> |
| <para> |
| Called from ata_bus_probe() on a failed probe. |
| Called from ata_bus_reset() on a failed bus reset. |
| Called from ata_scsi_release(). |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>Post-IDENTIFY device configuration</title> |
| <programlisting> |
| void (*dev_config) (struct ata_port *, struct ata_device *); |
| </programlisting> |
| |
| <para> |
| 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. |
| </para> |
| <para> |
| Called by ata_device_add() after ata_dev_identify() determines |
| a device is present. |
| </para> |
| <para> |
| This entry may be specified as NULL in ata_port_operations. |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>Set PIO/DMA mode</title> |
| <programlisting> |
| 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 *ap); |
| </programlisting> |
| |
| <para> |
| Hooks called prior to the issue of SET FEATURES - XFER MODE |
| command. dev->pio_mode is guaranteed to be valid when |
| ->set_piomode() is called, and dev->dma_mode is guaranteed to be |
| valid when ->set_dmamode() is called. ->post_set_mode() is |
| called unconditionally, after the SET FEATURES - XFER MODE |
| command completes successfully. |
| </para> |
| |
| <para> |
| ->set_piomode() is always called (if present), but |
| ->set_dma_mode() is only called if DMA is possible. |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>Taskfile read/write</title> |
| <programlisting> |
| void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf); |
| void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf); |
| </programlisting> |
| |
| <para> |
| ->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. |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>ATA command execute</title> |
| <programlisting> |
| void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); |
| </programlisting> |
| |
| <para> |
| 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. |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>Per-cmd ATAPI DMA capabilities filter</title> |
| <programlisting> |
| int (*check_atapi_dma) (struct ata_queued_cmd *qc); |
| </programlisting> |
| |
| <para> |
| 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. |
| </para> |
| <para> |
| This hook may be specified as NULL, in which case libata will |
| assume that atapi dma can be supported. |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>Read specific ATA shadow registers</title> |
| <programlisting> |
| u8 (*check_status)(struct ata_port *ap); |
| u8 (*check_altstatus)(struct ata_port *ap); |
| u8 (*check_err)(struct ata_port *ap); |
| </programlisting> |
| |
| <para> |
| 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. |
| </para> |
| <para> |
| 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. |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>Select ATA device on bus</title> |
| <programlisting> |
| void (*dev_select)(struct ata_port *ap, unsigned int device); |
| </programlisting> |
| |
| <para> |
| 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. |
| </para> |
| <para> |
| 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(). |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>Reset ATA bus</title> |
| <programlisting> |
| void (*phy_reset) (struct ata_port *ap); |
| </programlisting> |
| |
| <para> |
| 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. |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>Control PCI IDE BMDMA engine</title> |
| <programlisting> |
| 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); |
| </programlisting> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| These hooks are typically either no-ops, or simply not implemented, in |
| FIS-based drivers. |
| </para> |
| <para> |
| 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. |
| </para> |
| <para> |
| 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. |
| </para> |
| <para> |
| 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. |
| </para> |
| <para> |
| Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook. |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>High-level taskfile hooks</title> |
| <programlisting> |
| void (*qc_prep) (struct ata_queued_cmd *qc); |
| int (*qc_issue) (struct ata_queued_cmd *qc); |
| </programlisting> |
| |
| <para> |
| 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. |
| </para> |
| <para> |
| ->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. |
| </para> |
| <para> |
| ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and |
| ->bmdma_start() as necessary to initiate a transfer. |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>Timeout (error) handling</title> |
| <programlisting> |
| void (*eng_timeout) (struct ata_port *ap); |
| </programlisting> |
| |
| <para> |
| 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(). |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>Hardware interrupt handling</title> |
| <programlisting> |
| irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); |
| void (*irq_clear) (struct ata_port *); |
| </programlisting> |
| |
| <para> |
| ->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. |
| </para> |
| <para> |
| The second argument, dev_instance, should be cast to a pointer |
| to struct ata_host_set. |
| </para> |
| <para> |
| 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). |
| </para> |
| <para> |
| 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. |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>SATA phy read/write</title> |
| <programlisting> |
| u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg); |
| void (*scr_write) (struct ata_port *ap, unsigned int sc_reg, |
| u32 val); |
| </programlisting> |
| |
| <para> |
| 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. |
| </para> |
| |
| </sect2> |
| |
| <sect2><title>Init and shutdown</title> |
| <programlisting> |
| int (*port_start) (struct ata_port *ap); |
| void (*port_stop) (struct ata_port *ap); |
| void (*host_stop) (struct ata_host_set *host_set); |
| </programlisting> |
| |
| <para> |
| ->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. |
| </para> |
| <para> |
| 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. |
| </para> |
| <para> |
| ->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. |
| </para> |
| <para> |
| Many drivers use ata_port_stop() as this hook, which frees the |
| PRD table. |
| </para> |
| <para> |
| ->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. |
| </para> |
| |
| </sect2> |
| |
| </sect1> |
| </chapter> |
| |
| <chapter id="libataExt"> |
| <title>libata Library</title> |
| !Edrivers/scsi/libata-core.c |
| </chapter> |
| |
| <chapter id="libataInt"> |
| <title>libata Core Internals</title> |
| !Idrivers/scsi/libata-core.c |
| </chapter> |
| |
| <chapter id="libataScsiInt"> |
| <title>libata SCSI translation/emulation</title> |
| !Edrivers/scsi/libata-scsi.c |
| !Idrivers/scsi/libata-scsi.c |
| </chapter> |
| |
| <chapter id="PiixInt"> |
| <title>ata_piix Internals</title> |
| !Idrivers/scsi/ata_piix.c |
| </chapter> |
| |
| <chapter id="SILInt"> |
| <title>sata_sil Internals</title> |
| !Idrivers/scsi/sata_sil.c |
| </chapter> |
| |
| <chapter id="libataThanks"> |
| <title>Thanks</title> |
| <para> |
| The bulk of the ATA knowledge comes thanks to long conversations with |
| Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA |
| and SCSI specifications. |
| </para> |
| <para> |
| Thanks to Alan Cox for pointing out similarities |
| between SATA and SCSI, and in general for motivation to hack on |
| libata. |
| </para> |
| <para> |
| libata's device detection |
| method, ata_pio_devchk, and in general all the early probing was |
| based on extensive study of Hale Landis's probe/reset code in his |
| ATADRVR driver (www.ata-atapi.com). |
| </para> |
| </chapter> |
| |
| </book> |