1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>
3 <book id="libataDevGuide">
5 <title>libATA Developer's Guide</title>
9 <firstname>Jeff</firstname>
10 <surname>Garzik</surname>
16 <holder>Jeff Garzik</holder>
21 The contents of this file are subject to the Open
22 Software License version 1.1 that can be found at
23 <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
28 Alternatively, the contents of this file may be used under the terms
29 of the GNU General Public License version 2 (the "GPL") as distributed
30 in the kernel source COPYING file, in which case the provisions of
31 the GPL are applicable instead of the above. If you wish to allow
32 the use of your version of this file only under the terms of the
33 GPL and not to allow others to use your version of this file under
34 the OSL, indicate your decision by deleting the provisions above and
35 replace them with the notice and other provisions required by the GPL.
36 If you do not delete the provisions above, a recipient may use your
37 version of this file under either the OSL or the GPL.
45 <chapter id="libataThanks">
48 The bulk of the ATA knowledge comes thanks to long conversations with
49 Andre Hedrick (www.linux-ide.org).
52 Thanks to Alan Cox for pointing out similarities
53 between SATA and SCSI, and in general for motivation to hack on
57 libata's device detection
58 method, ata_pio_devchk, and in general all the early probing was
59 based on extensive study of Hale Landis's probe/reset code in his
60 ATADRVR driver (www.ata-atapi.com).
64 <chapter id="libataDriverApi">
65 <title>libata Driver API</title>
67 <title>struct ata_port_operations</title>
70 void (*port_disable) (struct ata_port *);
74 Called from ata_bus_probe() and ata_bus_reset() error paths,
75 as well as when unregistering from the SCSI module (rmmod, hot
80 void (*dev_config) (struct ata_port *, struct ata_device *);
84 Called after IDENTIFY [PACKET] DEVICE is issued to each device
85 found. Typically used to apply device-specific fixups prior to
86 issue of SET FEATURES - XFER MODE, and prior to operation.
90 void (*set_piomode) (struct ata_port *, struct ata_device *);
91 void (*set_dmamode) (struct ata_port *, struct ata_device *);
92 void (*post_set_mode) (struct ata_port *ap);
96 Hooks called prior to the issue of SET FEATURES - XFER MODE
97 command. dev->pio_mode is guaranteed to be valid when
98 ->set_piomode() is called, and dev->dma_mode is guaranteed to be
99 valid when ->set_dmamode() is called. ->post_set_mode() is
100 called unconditionally, after the SET FEATURES - XFER MODE
101 command completes successfully.
105 ->set_piomode() is always called (if present), but
106 ->set_dma_mode() is only called if DMA is possible.
110 void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
111 void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
115 ->tf_load() is called to load the given taskfile into hardware
116 registers / DMA buffers. ->tf_read() is called to read the
117 hardware registers / DMA buffers, to obtain the current set of
118 taskfile register values.
122 void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
126 causes an ATA command, previously loaded with
127 ->tf_load(), to be initiated in hardware.
131 u8 (*check_status)(struct ata_port *ap);
132 void (*dev_select)(struct ata_port *ap, unsigned int device);
136 Reads the Status ATA shadow register from hardware. On some
137 hardware, this has the side effect of clearing the interrupt
142 void (*dev_select)(struct ata_port *ap, unsigned int device);
146 Issues the low-level hardware command(s) that causes one of N
147 hardware devices to be considered 'selected' (active and
148 available for use) on the ATA bus.
152 void (*phy_reset) (struct ata_port *ap);
156 The very first step in the probe phase. Actions vary depending
157 on the bus type, typically. After waking up the device and probing
158 for device presence (PATA and SATA), typically a soft reset
159 (SRST) will be performed. Drivers typically use the helper
160 functions ata_bus_reset() or sata_phy_reset() for this hook.
164 void (*bmdma_setup) (struct ata_queued_cmd *qc);
165 void (*bmdma_start) (struct ata_queued_cmd *qc);
169 When setting up an IDE BMDMA transaction, these hooks arm
170 (->bmdma_setup) and fire (->bmdma_start) the hardware's DMA
175 void (*qc_prep) (struct ata_queued_cmd *qc);
176 int (*qc_issue) (struct ata_queued_cmd *qc);
180 Higher-level hooks, these two hooks can potentially supercede
181 several of the above taskfile/DMA engine hooks. ->qc_prep is
182 called after the buffers have been DMA-mapped, and is typically
183 used to populate the hardware's DMA scatter-gather table.
184 Most drivers use the standard ata_qc_prep() helper function, but
185 more advanced drivers roll their own.
188 ->qc_issue is used to make a command active, once the hardware
189 and S/G tables have been prepared. IDE BMDMA drivers use the
190 helper function ata_qc_issue_prot() for taskfile protocol-based
191 dispatch. More advanced drivers roll their own ->qc_issue
192 implementation, using this as the "issue new ATA command to
197 void (*eng_timeout) (struct ata_port *ap);
201 This is a high level error handling function, called from the
202 error handling thread, when a command times out.
206 irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
207 void (*irq_clear) (struct ata_port *);
211 ->irq_handler is the interrupt handling routine registered with
212 the system, by libata. ->irq_clear is called during probe just
213 before the interrupt handler is registered, to be sure hardware
218 u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
219 void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
224 Read and write standard SATA phy registers. Currently only used
225 if ->phy_reset hook called the sata_phy_reset() helper function.
229 int (*port_start) (struct ata_port *ap);
230 void (*port_stop) (struct ata_port *ap);
231 void (*host_stop) (struct ata_host_set *host_set);
235 ->port_start() is called just after the data structures for each
236 port are initialized. Typically this is used to alloc per-port
237 DMA buffers / tables / rings, enable DMA engines, and similar
241 ->host_stop() is called when the rmmod or hot unplug process
242 begins. The hook must stop all hardware interrupts, DMA
246 ->port_stop() is called after ->host_stop(). It's sole function
247 is to release DMA/memory resources, now that they are no longer
254 <chapter id="libataExt">
255 <title>libata Library</title>
256 !Edrivers/scsi/libata-core.c
259 <chapter id="libataInt">
260 <title>libata Core Internals</title>
261 !Idrivers/scsi/libata-core.c
264 <chapter id="libataScsiInt">
265 <title>libata SCSI translation/emulation</title>
266 !Edrivers/scsi/libata-scsi.c
267 !Idrivers/scsi/libata-scsi.c
270 <chapter id="PiixInt">
271 <title>ata_piix Internals</title>
272 !Idrivers/scsi/ata_piix.c
275 <chapter id="SILInt">
276 <title>sata_sil Internals</title>
277 !Idrivers/scsi/sata_sil.c