Linux-2.6.12-rc2
[linux-2.6.git] / Documentation / DocBook / libata.tmpl
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" []>
4
5 <book id="libataDevGuide">
6  <bookinfo>
7   <title>libATA Developer's Guide</title>
8   
9   <authorgroup>
10    <author>
11     <firstname>Jeff</firstname>
12     <surname>Garzik</surname>
13    </author>
14   </authorgroup>
15
16   <copyright>
17    <year>2003</year>
18    <holder>Jeff Garzik</holder>
19   </copyright>
20
21   <legalnotice>
22    <para>
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
26    by reference.
27    </para>
28
29    <para>
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.
40    </para>
41
42   </legalnotice>
43  </bookinfo>
44
45 <toc></toc>
46
47   <chapter id="libataThanks">
48      <title>Thanks</title>
49   <para>
50   The bulk of the ATA knowledge comes thanks to long conversations with
51   Andre Hedrick (www.linux-ide.org).
52   </para>
53   <para>
54   Thanks to Alan Cox for pointing out similarities 
55   between SATA and SCSI, and in general for motivation to hack on
56   libata.
57   </para>
58   <para>
59   libata's device detection
60   method, ata_pio_devchk, and in general all the early probing was
61   based on extensive study of Hale Landis's probe/reset code in his
62   ATADRVR driver (www.ata-atapi.com).
63   </para>
64   </chapter>
65
66   <chapter id="libataDriverApi">
67      <title>libata Driver API</title>
68      <sect1>
69         <title>struct ata_port_operations</title>
70
71         <programlisting>
72 void (*port_disable) (struct ata_port *);
73         </programlisting>
74
75         <para>
76         Called from ata_bus_probe() and ata_bus_reset() error paths,
77         as well as when unregistering from the SCSI module (rmmod, hot
78         unplug).
79         </para>
80
81         <programlisting>
82 void (*dev_config) (struct ata_port *, struct ata_device *);
83         </programlisting>
84
85         <para>
86         Called after IDENTIFY [PACKET] DEVICE is issued to each device
87         found.  Typically used to apply device-specific fixups prior to
88         issue of SET FEATURES - XFER MODE, and prior to operation.
89         </para>
90
91         <programlisting>
92 void (*set_piomode) (struct ata_port *, struct ata_device *);
93 void (*set_dmamode) (struct ata_port *, struct ata_device *);
94 void (*post_set_mode) (struct ata_port *ap);
95         </programlisting>
96
97         <para>
98         Hooks called prior to the issue of SET FEATURES - XFER MODE
99         command.  dev->pio_mode is guaranteed to be valid when
100         ->set_piomode() is called, and dev->dma_mode is guaranteed to be
101         valid when ->set_dmamode() is called.  ->post_set_mode() is
102         called unconditionally, after the SET FEATURES - XFER MODE
103         command completes successfully.
104         </para>
105
106         <para>
107         ->set_piomode() is always called (if present), but
108         ->set_dma_mode() is only called if DMA is possible.
109         </para>
110
111         <programlisting>
112 void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
113 void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
114         </programlisting>
115
116         <para>
117         ->tf_load() is called to load the given taskfile into hardware
118         registers / DMA buffers.  ->tf_read() is called to read the
119         hardware registers / DMA buffers, to obtain the current set of
120         taskfile register values.
121         </para>
122
123         <programlisting>
124 void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
125         </programlisting>
126
127         <para>
128         causes an ATA command, previously loaded with
129         ->tf_load(), to be initiated in hardware.
130         </para>
131
132         <programlisting>
133 u8   (*check_status)(struct ata_port *ap);
134 void (*dev_select)(struct ata_port *ap, unsigned int device);
135         </programlisting>
136
137         <para>
138         Reads the Status ATA shadow register from hardware.  On some
139         hardware, this has the side effect of clearing the interrupt
140         condition.
141         </para>
142
143         <programlisting>
144 void (*dev_select)(struct ata_port *ap, unsigned int device);
145         </programlisting>
146
147         <para>
148         Issues the low-level hardware command(s) that causes one of N
149         hardware devices to be considered 'selected' (active and
150         available for use) on the ATA bus.
151         </para>
152
153         <programlisting>
154 void (*phy_reset) (struct ata_port *ap);
155         </programlisting>
156
157         <para>
158         The very first step in the probe phase.  Actions vary depending
159         on the bus type, typically.  After waking up the device and probing
160         for device presence (PATA and SATA), typically a soft reset
161         (SRST) will be performed.  Drivers typically use the helper
162         functions ata_bus_reset() or sata_phy_reset() for this hook.
163         </para>
164
165         <programlisting>
166 void (*bmdma_setup) (struct ata_queued_cmd *qc);
167 void (*bmdma_start) (struct ata_queued_cmd *qc);
168         </programlisting>
169
170         <para>
171         When setting up an IDE BMDMA transaction, these hooks arm
172         (->bmdma_setup) and fire (->bmdma_start) the hardware's DMA
173         engine.
174         </para>
175
176         <programlisting>
177 void (*qc_prep) (struct ata_queued_cmd *qc);
178 int (*qc_issue) (struct ata_queued_cmd *qc);
179         </programlisting>
180
181         <para>
182         Higher-level hooks, these two hooks can potentially supercede
183         several of the above taskfile/DMA engine hooks.  ->qc_prep is
184         called after the buffers have been DMA-mapped, and is typically
185         used to populate the hardware's DMA scatter-gather table.
186         Most drivers use the standard ata_qc_prep() helper function, but
187         more advanced drivers roll their own.
188         </para>
189         <para>
190         ->qc_issue is used to make a command active, once the hardware
191         and S/G tables have been prepared.  IDE BMDMA drivers use the
192         helper function ata_qc_issue_prot() for taskfile protocol-based
193         dispatch.  More advanced drivers roll their own ->qc_issue
194         implementation, using this as the "issue new ATA command to
195         hardware" hook.
196         </para>
197
198         <programlisting>
199 void (*eng_timeout) (struct ata_port *ap);
200         </programlisting>
201
202         <para>
203         This is a high level error handling function, called from the
204         error handling thread, when a command times out.
205         </para>
206
207         <programlisting>
208 irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
209 void (*irq_clear) (struct ata_port *);
210         </programlisting>
211
212         <para>
213         ->irq_handler is the interrupt handling routine registered with
214         the system, by libata.  ->irq_clear is called during probe just
215         before the interrupt handler is registered, to be sure hardware
216         is quiet.
217         </para>
218
219         <programlisting>
220 u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
221 void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
222                    u32 val);
223         </programlisting>
224
225         <para>
226         Read and write standard SATA phy registers.  Currently only used
227         if ->phy_reset hook called the sata_phy_reset() helper function.
228         </para>
229
230         <programlisting>
231 int (*port_start) (struct ata_port *ap);
232 void (*port_stop) (struct ata_port *ap);
233 void (*host_stop) (struct ata_host_set *host_set);
234         </programlisting>
235
236         <para>
237         ->port_start() is called just after the data structures for each
238         port are initialized.  Typically this is used to alloc per-port
239         DMA buffers / tables / rings, enable DMA engines, and similar
240         tasks.  
241         </para>
242         <para>
243         ->host_stop() is called when the rmmod or hot unplug process
244         begins.  The hook must stop all hardware interrupts, DMA
245         engines, etc.
246         </para>
247         <para>
248         ->port_stop() is called after ->host_stop().  It's sole function
249         is to release DMA/memory resources, now that they are no longer
250         actively being used.
251         </para>
252
253      </sect1>
254   </chapter>
255
256   <chapter id="libataExt">
257      <title>libata Library</title>
258 !Edrivers/scsi/libata-core.c
259   </chapter>
260
261   <chapter id="libataInt">
262      <title>libata Core Internals</title>
263 !Idrivers/scsi/libata-core.c
264   </chapter>
265
266   <chapter id="libataScsiInt">
267      <title>libata SCSI translation/emulation</title>
268 !Edrivers/scsi/libata-scsi.c
269 !Idrivers/scsi/libata-scsi.c
270   </chapter>
271
272   <chapter id="PiixInt">
273      <title>ata_piix Internals</title>
274 !Idrivers/scsi/ata_piix.c
275   </chapter>
276
277   <chapter id="SILInt">
278      <title>sata_sil Internals</title>
279 !Idrivers/scsi/sata_sil.c
280   </chapter>
281
282 </book>