aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/libata.tmpl
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 18:20:36 -0400
committerLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 18:20:36 -0400
commit1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch)
tree0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/DocBook/libata.tmpl
Linux-2.6.12-rc2v2.6.12-rc2
Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
Diffstat (limited to 'Documentation/DocBook/libata.tmpl')
-rw-r--r--Documentation/DocBook/libata.tmpl282
1 files changed, 282 insertions, 0 deletions
diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl
new file mode 100644
index 000000000000..cf2fce7707da
--- /dev/null
+++ b/Documentation/DocBook/libata.tmpl
@@ -0,0 +1,282 @@
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>
72void (*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>
82void (*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>
92void (*set_piomode) (struct ata_port *, struct ata_device *);
93void (*set_dmamode) (struct ata_port *, struct ata_device *);
94void (*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>
112void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
113void (*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>
124void (*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>
133u8 (*check_status)(struct ata_port *ap);
134void (*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>
144void (*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>
154void (*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>
166void (*bmdma_setup) (struct ata_queued_cmd *qc);
167void (*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>
177void (*qc_prep) (struct ata_queued_cmd *qc);
178int (*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>
199void (*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>
208irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
209void (*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>
220u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
221void (*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>
231int (*port_start) (struct ata_port *ap);
232void (*port_stop) (struct ata_port *ap);
233void (*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>