1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
5 <book id="libataDevGuide">
7 <title>libATA Developer's Guide</title>
11 <firstname>Jeff</firstname>
12 <surname>Garzik</surname>
17 <year>2003-2005</year>
18 <holder>Jeff Garzik</holder>
23 The contents of this file are subject to the Open
24 Software License version 1.1 that can be found at
25 <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
30 Alternatively, the contents of this file may be used under the terms
31 of the GNU General Public License version 2 (the "GPL") as distributed
32 in the kernel source COPYING file, in which case the provisions of
33 the GPL are applicable instead of the above. If you wish to allow
34 the use of your version of this file only under the terms of the
35 GPL and not to allow others to use your version of this file under
36 the OSL, indicate your decision by deleting the provisions above and
37 replace them with the notice and other provisions required by the GPL.
38 If you do not delete the provisions above, a recipient may use your
39 version of this file under either the OSL or the GPL.
47 <chapter id="libataIntroduction">
48 <title>Introduction</title>
50 libATA is a library used inside the Linux kernel to support ATA host
51 controllers and devices. libATA provides an ATA driver API, class
52 transports for ATA and ATAPI devices, and SCSI<->ATA translation
53 for ATA devices according to the T10 SAT specification.
56 This Guide documents the libATA driver API, library functions, library
57 internals, and a couple sample ATA low-level drivers.
61 <chapter id="libataDriverApi">
62 <title>libata Driver API</title>
64 <title>struct ata_port_operations</title>
67 void (*port_disable) (struct ata_port *);
71 Called from ata_bus_probe() and ata_bus_reset() error paths,
72 as well as when unregistering from the SCSI module (rmmod, hot
77 void (*dev_config) (struct ata_port *, struct ata_device *);
81 Called after IDENTIFY [PACKET] DEVICE is issued to each device
82 found. Typically used to apply device-specific fixups prior to
83 issue of SET FEATURES - XFER MODE, and prior to operation.
87 void (*set_piomode) (struct ata_port *, struct ata_device *);
88 void (*set_dmamode) (struct ata_port *, struct ata_device *);
89 void (*post_set_mode) (struct ata_port *ap);
93 Hooks called prior to the issue of SET FEATURES - XFER MODE
94 command. dev->pio_mode is guaranteed to be valid when
95 ->set_piomode() is called, and dev->dma_mode is guaranteed to be
96 valid when ->set_dmamode() is called. ->post_set_mode() is
97 called unconditionally, after the SET FEATURES - XFER MODE
98 command completes successfully.
102 ->set_piomode() is always called (if present), but
103 ->set_dma_mode() is only called if DMA is possible.
107 void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
108 void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
112 ->tf_load() is called to load the given taskfile into hardware
113 registers / DMA buffers. ->tf_read() is called to read the
114 hardware registers / DMA buffers, to obtain the current set of
115 taskfile register values.
119 void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
123 causes an ATA command, previously loaded with
124 ->tf_load(), to be initiated in hardware.
128 int (*check_atapi_dma) (struct ata_queued_cmd *qc);
132 Allow low-level driver to filter ATA PACKET commands, returning a status
133 indicating whether or not it is OK to use DMA for the supplied PACKET
138 u8 (*check_status)(struct ata_port *ap);
139 u8 (*check_altstatus)(struct ata_port *ap);
140 u8 (*check_err)(struct ata_port *ap);
144 Reads the Status/AltStatus/Error ATA shadow register from
145 hardware. On some hardware, reading the Status register has
146 the side effect of clearing the interrupt condition.
150 void (*dev_select)(struct ata_port *ap, unsigned int device);
154 Issues the low-level hardware command(s) that causes one of N
155 hardware devices to be considered 'selected' (active and
156 available for use) on the ATA bus. This generally has no
157 meaning on FIS-based devices.
161 void (*phy_reset) (struct ata_port *ap);
165 The very first step in the probe phase. Actions vary depending
166 on the bus type, typically. After waking up the device and probing
167 for device presence (PATA and SATA), typically a soft reset
168 (SRST) will be performed. Drivers typically use the helper
169 functions ata_bus_reset() or sata_phy_reset() for this hook.
173 void (*bmdma_setup) (struct ata_queued_cmd *qc);
174 void (*bmdma_start) (struct ata_queued_cmd *qc);
175 void (*bmdma_stop) (struct ata_port *ap);
176 u8 (*bmdma_status) (struct ata_port *ap);
180 When setting up an IDE BMDMA transaction, these hooks arm
181 (->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop)
182 the hardware's DMA engine. ->bmdma_status is used to read the standard
183 PCI IDE DMA Status register.
187 These hooks are typically either no-ops, or simply not implemented, in
192 void (*qc_prep) (struct ata_queued_cmd *qc);
193 int (*qc_issue) (struct ata_queued_cmd *qc);
197 Higher-level hooks, these two hooks can potentially supercede
198 several of the above taskfile/DMA engine hooks. ->qc_prep is
199 called after the buffers have been DMA-mapped, and is typically
200 used to populate the hardware's DMA scatter-gather table.
201 Most drivers use the standard ata_qc_prep() helper function, but
202 more advanced drivers roll their own.
205 ->qc_issue is used to make a command active, once the hardware
206 and S/G tables have been prepared. IDE BMDMA drivers use the
207 helper function ata_qc_issue_prot() for taskfile protocol-based
208 dispatch. More advanced drivers implement their own ->qc_issue.
212 void (*eng_timeout) (struct ata_port *ap);
216 This is a high level error handling function, called from the
217 error handling thread, when a command times out. Most newer
218 hardware will implement its own error handling code here. IDE BMDMA
219 drivers may use the helper function ata_eng_timeout().
223 irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
224 void (*irq_clear) (struct ata_port *);
228 ->irq_handler is the interrupt handling routine registered with
229 the system, by libata. ->irq_clear is called during probe just
230 before the interrupt handler is registered, to be sure hardware
235 u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
236 void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
241 Read and write standard SATA phy registers. Currently only used
242 if ->phy_reset hook called the sata_phy_reset() helper function.
246 int (*port_start) (struct ata_port *ap);
247 void (*port_stop) (struct ata_port *ap);
248 void (*host_stop) (struct ata_host_set *host_set);
252 ->port_start() is called just after the data structures for each
253 port are initialized. Typically this is used to alloc per-port
254 DMA buffers / tables / rings, enable DMA engines, and similar
258 ->port_stop() is called after ->host_stop(). It's sole function
259 is to release DMA/memory resources, now that they are no longer
263 ->host_stop() is called after all ->port_stop() calls
264 have completed. The hook must finalize hardware shutdown, release DMA
265 and other resources, etc.
271 <chapter id="libataExt">
272 <title>libata Library</title>
273 !Edrivers/scsi/libata-core.c
276 <chapter id="libataInt">
277 <title>libata Core Internals</title>
278 !Idrivers/scsi/libata-core.c
281 <chapter id="libataScsiInt">
282 <title>libata SCSI translation/emulation</title>
283 !Edrivers/scsi/libata-scsi.c
284 !Idrivers/scsi/libata-scsi.c
287 <chapter id="PiixInt">
288 <title>ata_piix Internals</title>
289 !Idrivers/scsi/ata_piix.c
292 <chapter id="SILInt">
293 <title>sata_sil Internals</title>
294 !Idrivers/scsi/sata_sil.c
297 <chapter id="libataThanks">
298 <title>Thanks</title>
300 The bulk of the ATA knowledge comes thanks to long conversations with
301 Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA
302 and SCSI specifications.
305 Thanks to Alan Cox for pointing out similarities
306 between SATA and SCSI, and in general for motivation to hack on
310 libata's device detection
311 method, ata_pio_devchk, and in general all the early probing was
312 based on extensive study of Hale Landis's probe/reset code in his
313 ATADRVR driver (www.ata-atapi.com).