libata: minor DocBook update
[linux-3.10.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="libataIntroduction">
48      <title>Introduction</title>
49   <para>
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&lt;-&gt;ATA translation
53   for ATA devices according to the T10 SAT specification.
54   </para>
55   <para>
56   This Guide documents the libATA driver API, library functions, library
57   internals, and a couple sample ATA low-level drivers.
58   </para>
59   </chapter>
60
61   <chapter id="libataThanks">
62      <title>Thanks</title>
63   <para>
64   The bulk of the ATA knowledge comes thanks to long conversations with
65   Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA
66   and SCSI specifications.
67   </para>
68   <para>
69   Thanks to Alan Cox for pointing out similarities 
70   between SATA and SCSI, and in general for motivation to hack on
71   libata.
72   </para>
73   <para>
74   libata's device detection
75   method, ata_pio_devchk, and in general all the early probing was
76   based on extensive study of Hale Landis's probe/reset code in his
77   ATADRVR driver (www.ata-atapi.com).
78   </para>
79   </chapter>
80
81   <chapter id="libataDriverApi">
82      <title>libata Driver API</title>
83      <sect1>
84         <title>struct ata_port_operations</title>
85
86         <programlisting>
87 void (*port_disable) (struct ata_port *);
88         </programlisting>
89
90         <para>
91         Called from ata_bus_probe() and ata_bus_reset() error paths,
92         as well as when unregistering from the SCSI module (rmmod, hot
93         unplug).
94         </para>
95
96         <programlisting>
97 void (*dev_config) (struct ata_port *, struct ata_device *);
98         </programlisting>
99
100         <para>
101         Called after IDENTIFY [PACKET] DEVICE is issued to each device
102         found.  Typically used to apply device-specific fixups prior to
103         issue of SET FEATURES - XFER MODE, and prior to operation.
104         </para>
105
106         <programlisting>
107 void (*set_piomode) (struct ata_port *, struct ata_device *);
108 void (*set_dmamode) (struct ata_port *, struct ata_device *);
109 void (*post_set_mode) (struct ata_port *ap);
110         </programlisting>
111
112         <para>
113         Hooks called prior to the issue of SET FEATURES - XFER MODE
114         command.  dev->pio_mode is guaranteed to be valid when
115         ->set_piomode() is called, and dev->dma_mode is guaranteed to be
116         valid when ->set_dmamode() is called.  ->post_set_mode() is
117         called unconditionally, after the SET FEATURES - XFER MODE
118         command completes successfully.
119         </para>
120
121         <para>
122         ->set_piomode() is always called (if present), but
123         ->set_dma_mode() is only called if DMA is possible.
124         </para>
125
126         <programlisting>
127 void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
128 void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
129         </programlisting>
130
131         <para>
132         ->tf_load() is called to load the given taskfile into hardware
133         registers / DMA buffers.  ->tf_read() is called to read the
134         hardware registers / DMA buffers, to obtain the current set of
135         taskfile register values.
136         </para>
137
138         <programlisting>
139 void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
140         </programlisting>
141
142         <para>
143         causes an ATA command, previously loaded with
144         ->tf_load(), to be initiated in hardware.
145         </para>
146
147         <programlisting>
148 u8   (*check_status)(struct ata_port *ap);
149 void (*dev_select)(struct ata_port *ap, unsigned int device);
150         </programlisting>
151
152         <para>
153         Reads the Status ATA shadow register from hardware.  On some
154         hardware, this has the side effect of clearing the interrupt
155         condition.
156         </para>
157
158         <programlisting>
159 void (*dev_select)(struct ata_port *ap, unsigned int device);
160         </programlisting>
161
162         <para>
163         Issues the low-level hardware command(s) that causes one of N
164         hardware devices to be considered 'selected' (active and
165         available for use) on the ATA bus.
166         </para>
167
168         <programlisting>
169 void (*phy_reset) (struct ata_port *ap);
170         </programlisting>
171
172         <para>
173         The very first step in the probe phase.  Actions vary depending
174         on the bus type, typically.  After waking up the device and probing
175         for device presence (PATA and SATA), typically a soft reset
176         (SRST) will be performed.  Drivers typically use the helper
177         functions ata_bus_reset() or sata_phy_reset() for this hook.
178         </para>
179
180         <programlisting>
181 void (*bmdma_setup) (struct ata_queued_cmd *qc);
182 void (*bmdma_start) (struct ata_queued_cmd *qc);
183         </programlisting>
184
185         <para>
186         When setting up an IDE BMDMA transaction, these hooks arm
187         (->bmdma_setup) and fire (->bmdma_start) the hardware's DMA
188         engine.
189         </para>
190
191         <programlisting>
192 void (*qc_prep) (struct ata_queued_cmd *qc);
193 int (*qc_issue) (struct ata_queued_cmd *qc);
194         </programlisting>
195
196         <para>
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.
203         </para>
204         <para>
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 roll their own ->qc_issue
209         implementation, using this as the "issue new ATA command to
210         hardware" hook.
211         </para>
212
213         <programlisting>
214 void (*eng_timeout) (struct ata_port *ap);
215         </programlisting>
216
217         <para>
218         This is a high level error handling function, called from the
219         error handling thread, when a command times out.
220         </para>
221
222         <programlisting>
223 irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
224 void (*irq_clear) (struct ata_port *);
225         </programlisting>
226
227         <para>
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
231         is quiet.
232         </para>
233
234         <programlisting>
235 u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
236 void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
237                    u32 val);
238         </programlisting>
239
240         <para>
241         Read and write standard SATA phy registers.  Currently only used
242         if ->phy_reset hook called the sata_phy_reset() helper function.
243         </para>
244
245         <programlisting>
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);
249         </programlisting>
250
251         <para>
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
255         tasks.  
256         </para>
257         <para>
258         ->host_stop() is called when the rmmod or hot unplug process
259         begins.  The hook must stop all hardware interrupts, DMA
260         engines, etc.
261         </para>
262         <para>
263         ->port_stop() is called after ->host_stop().  It's sole function
264         is to release DMA/memory resources, now that they are no longer
265         actively being used.
266         </para>
267
268      </sect1>
269   </chapter>
270
271   <chapter id="libataExt">
272      <title>libata Library</title>
273 !Edrivers/scsi/libata-core.c
274   </chapter>
275
276   <chapter id="libataInt">
277      <title>libata Core Internals</title>
278 !Idrivers/scsi/libata-core.c
279   </chapter>
280
281   <chapter id="libataScsiInt">
282      <title>libata SCSI translation/emulation</title>
283 !Edrivers/scsi/libata-scsi.c
284 !Idrivers/scsi/libata-scsi.c
285   </chapter>
286
287   <chapter id="PiixInt">
288      <title>ata_piix Internals</title>
289 !Idrivers/scsi/ata_piix.c
290   </chapter>
291
292   <chapter id="SILInt">
293      <title>sata_sil Internals</title>
294 !Idrivers/scsi/sata_sil.c
295   </chapter>
296
297 </book>