Contents of /alx-src/trunk/kernel26-alx/linux/Documentation/DocBook/libata.tmpl
Parent Directory | Revision Log
Revision 628 -
(show annotations)
(download)
Wed Mar 4 10:48:58 2009 UTC (15 years, 6 months ago) by niro
File size: 11159 byte(s)
Wed Mar 4 10:48:58 2009 UTC (15 years, 6 months ago) by niro
File size: 11159 byte(s)
import linux sources based on 2.6.12-alx-r9: -using linux-2.6.12.6 -using 2.6.12-ck6 patch set -using fbsplash-0.9.2-r3 -using vesafb-tng-0.9-rc7 -using squashfs-2.2 -added cddvd-cmdfilter-drop.patch as ck dropped it -added via-epia-dri (cle266) patch -added zd1211-svn-32 wlan driver (http://zd1211.ath.cx/download/) -added debian patches to zd1211 for wep256 etc
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-2005</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<->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="libataDriverApi"> |
62 | <title>libata Driver API</title> |
63 | <para> |
64 | struct ata_port_operations is defined for every low-level libata |
65 | hardware driver, and it controls how the low-level driver |
66 | interfaces with the ATA and SCSI layers. |
67 | </para> |
68 | <para> |
69 | FIS-based drivers will hook into the system with ->qc_prep() and |
70 | ->qc_issue() high-level hooks. Hardware which behaves in a manner |
71 | similar to PCI IDE hardware may utilize several generic helpers, |
72 | defining at a bare minimum the bus I/O addresses of the ATA shadow |
73 | register blocks. |
74 | </para> |
75 | <sect1> |
76 | <title>struct ata_port_operations</title> |
77 | |
78 | <sect2><title>Disable ATA port</title> |
79 | <programlisting> |
80 | void (*port_disable) (struct ata_port *); |
81 | </programlisting> |
82 | |
83 | <para> |
84 | Called from ata_bus_probe() and ata_bus_reset() error paths, |
85 | as well as when unregistering from the SCSI module (rmmod, hot |
86 | unplug). |
87 | </para> |
88 | |
89 | </sect2> |
90 | |
91 | <sect2><title>Post-IDENTIFY device configuration</title> |
92 | <programlisting> |
93 | void (*dev_config) (struct ata_port *, struct ata_device *); |
94 | </programlisting> |
95 | |
96 | <para> |
97 | Called after IDENTIFY [PACKET] DEVICE is issued to each device |
98 | found. Typically used to apply device-specific fixups prior to |
99 | issue of SET FEATURES - XFER MODE, and prior to operation. |
100 | </para> |
101 | |
102 | </sect2> |
103 | |
104 | <sect2><title>Set PIO/DMA mode</title> |
105 | <programlisting> |
106 | void (*set_piomode) (struct ata_port *, struct ata_device *); |
107 | void (*set_dmamode) (struct ata_port *, struct ata_device *); |
108 | void (*post_set_mode) (struct ata_port *ap); |
109 | </programlisting> |
110 | |
111 | <para> |
112 | Hooks called prior to the issue of SET FEATURES - XFER MODE |
113 | command. dev->pio_mode is guaranteed to be valid when |
114 | ->set_piomode() is called, and dev->dma_mode is guaranteed to be |
115 | valid when ->set_dmamode() is called. ->post_set_mode() is |
116 | called unconditionally, after the SET FEATURES - XFER MODE |
117 | command completes successfully. |
118 | </para> |
119 | |
120 | <para> |
121 | ->set_piomode() is always called (if present), but |
122 | ->set_dma_mode() is only called if DMA is possible. |
123 | </para> |
124 | |
125 | </sect2> |
126 | |
127 | <sect2><title>Taskfile read/write</title> |
128 | <programlisting> |
129 | void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf); |
130 | void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf); |
131 | </programlisting> |
132 | |
133 | <para> |
134 | ->tf_load() is called to load the given taskfile into hardware |
135 | registers / DMA buffers. ->tf_read() is called to read the |
136 | hardware registers / DMA buffers, to obtain the current set of |
137 | taskfile register values. |
138 | </para> |
139 | |
140 | </sect2> |
141 | |
142 | <sect2><title>ATA command execute</title> |
143 | <programlisting> |
144 | void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); |
145 | </programlisting> |
146 | |
147 | <para> |
148 | causes an ATA command, previously loaded with |
149 | ->tf_load(), to be initiated in hardware. |
150 | </para> |
151 | |
152 | </sect2> |
153 | |
154 | <sect2><title>Per-cmd ATAPI DMA capabilities filter</title> |
155 | <programlisting> |
156 | int (*check_atapi_dma) (struct ata_queued_cmd *qc); |
157 | </programlisting> |
158 | |
159 | <para> |
160 | Allow low-level driver to filter ATA PACKET commands, returning a status |
161 | indicating whether or not it is OK to use DMA for the supplied PACKET |
162 | command. |
163 | </para> |
164 | |
165 | </sect2> |
166 | |
167 | <sect2><title>Read specific ATA shadow registers</title> |
168 | <programlisting> |
169 | u8 (*check_status)(struct ata_port *ap); |
170 | u8 (*check_altstatus)(struct ata_port *ap); |
171 | u8 (*check_err)(struct ata_port *ap); |
172 | </programlisting> |
173 | |
174 | <para> |
175 | Reads the Status/AltStatus/Error ATA shadow register from |
176 | hardware. On some hardware, reading the Status register has |
177 | the side effect of clearing the interrupt condition. |
178 | </para> |
179 | |
180 | </sect2> |
181 | |
182 | <sect2><title>Select ATA device on bus</title> |
183 | <programlisting> |
184 | void (*dev_select)(struct ata_port *ap, unsigned int device); |
185 | </programlisting> |
186 | |
187 | <para> |
188 | Issues the low-level hardware command(s) that causes one of N |
189 | hardware devices to be considered 'selected' (active and |
190 | available for use) on the ATA bus. This generally has no |
191 | meaning on FIS-based devices. |
192 | </para> |
193 | |
194 | </sect2> |
195 | |
196 | <sect2><title>Reset ATA bus</title> |
197 | <programlisting> |
198 | void (*phy_reset) (struct ata_port *ap); |
199 | </programlisting> |
200 | |
201 | <para> |
202 | The very first step in the probe phase. Actions vary depending |
203 | on the bus type, typically. After waking up the device and probing |
204 | for device presence (PATA and SATA), typically a soft reset |
205 | (SRST) will be performed. Drivers typically use the helper |
206 | functions ata_bus_reset() or sata_phy_reset() for this hook. |
207 | </para> |
208 | |
209 | </sect2> |
210 | |
211 | <sect2><title>Control PCI IDE BMDMA engine</title> |
212 | <programlisting> |
213 | void (*bmdma_setup) (struct ata_queued_cmd *qc); |
214 | void (*bmdma_start) (struct ata_queued_cmd *qc); |
215 | void (*bmdma_stop) (struct ata_port *ap); |
216 | u8 (*bmdma_status) (struct ata_port *ap); |
217 | </programlisting> |
218 | |
219 | <para> |
220 | When setting up an IDE BMDMA transaction, these hooks arm |
221 | (->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) |
222 | the hardware's DMA engine. ->bmdma_status is used to read the standard |
223 | PCI IDE DMA Status register. |
224 | </para> |
225 | |
226 | <para> |
227 | These hooks are typically either no-ops, or simply not implemented, in |
228 | FIS-based drivers. |
229 | </para> |
230 | |
231 | </sect2> |
232 | |
233 | <sect2><title>High-level taskfile hooks</title> |
234 | <programlisting> |
235 | void (*qc_prep) (struct ata_queued_cmd *qc); |
236 | int (*qc_issue) (struct ata_queued_cmd *qc); |
237 | </programlisting> |
238 | |
239 | <para> |
240 | Higher-level hooks, these two hooks can potentially supercede |
241 | several of the above taskfile/DMA engine hooks. ->qc_prep is |
242 | called after the buffers have been DMA-mapped, and is typically |
243 | used to populate the hardware's DMA scatter-gather table. |
244 | Most drivers use the standard ata_qc_prep() helper function, but |
245 | more advanced drivers roll their own. |
246 | </para> |
247 | <para> |
248 | ->qc_issue is used to make a command active, once the hardware |
249 | and S/G tables have been prepared. IDE BMDMA drivers use the |
250 | helper function ata_qc_issue_prot() for taskfile protocol-based |
251 | dispatch. More advanced drivers implement their own ->qc_issue. |
252 | </para> |
253 | |
254 | </sect2> |
255 | |
256 | <sect2><title>Timeout (error) handling</title> |
257 | <programlisting> |
258 | void (*eng_timeout) (struct ata_port *ap); |
259 | </programlisting> |
260 | |
261 | <para> |
262 | This is a high level error handling function, called from the |
263 | error handling thread, when a command times out. Most newer |
264 | hardware will implement its own error handling code here. IDE BMDMA |
265 | drivers may use the helper function ata_eng_timeout(). |
266 | </para> |
267 | |
268 | </sect2> |
269 | |
270 | <sect2><title>Hardware interrupt handling</title> |
271 | <programlisting> |
272 | irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); |
273 | void (*irq_clear) (struct ata_port *); |
274 | </programlisting> |
275 | |
276 | <para> |
277 | ->irq_handler is the interrupt handling routine registered with |
278 | the system, by libata. ->irq_clear is called during probe just |
279 | before the interrupt handler is registered, to be sure hardware |
280 | is quiet. |
281 | </para> |
282 | |
283 | </sect2> |
284 | |
285 | <sect2><title>SATA phy read/write</title> |
286 | <programlisting> |
287 | u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg); |
288 | void (*scr_write) (struct ata_port *ap, unsigned int sc_reg, |
289 | u32 val); |
290 | </programlisting> |
291 | |
292 | <para> |
293 | Read and write standard SATA phy registers. Currently only used |
294 | if ->phy_reset hook called the sata_phy_reset() helper function. |
295 | </para> |
296 | |
297 | </sect2> |
298 | |
299 | <sect2><title>Init and shutdown</title> |
300 | <programlisting> |
301 | int (*port_start) (struct ata_port *ap); |
302 | void (*port_stop) (struct ata_port *ap); |
303 | void (*host_stop) (struct ata_host_set *host_set); |
304 | </programlisting> |
305 | |
306 | <para> |
307 | ->port_start() is called just after the data structures for each |
308 | port are initialized. Typically this is used to alloc per-port |
309 | DMA buffers / tables / rings, enable DMA engines, and similar |
310 | tasks. |
311 | </para> |
312 | <para> |
313 | ->port_stop() is called after ->host_stop(). It's sole function |
314 | is to release DMA/memory resources, now that they are no longer |
315 | actively being used. |
316 | </para> |
317 | <para> |
318 | ->host_stop() is called after all ->port_stop() calls |
319 | have completed. The hook must finalize hardware shutdown, release DMA |
320 | and other resources, etc. |
321 | </para> |
322 | |
323 | </sect2> |
324 | |
325 | </sect1> |
326 | </chapter> |
327 | |
328 | <chapter id="libataExt"> |
329 | <title>libata Library</title> |
330 | !Edrivers/scsi/libata-core.c |
331 | </chapter> |
332 | |
333 | <chapter id="libataInt"> |
334 | <title>libata Core Internals</title> |
335 | !Idrivers/scsi/libata-core.c |
336 | </chapter> |
337 | |
338 | <chapter id="libataScsiInt"> |
339 | <title>libata SCSI translation/emulation</title> |
340 | !Edrivers/scsi/libata-scsi.c |
341 | !Idrivers/scsi/libata-scsi.c |
342 | </chapter> |
343 | |
344 | <chapter id="PiixInt"> |
345 | <title>ata_piix Internals</title> |
346 | !Idrivers/scsi/ata_piix.c |
347 | </chapter> |
348 | |
349 | <chapter id="SILInt"> |
350 | <title>sata_sil Internals</title> |
351 | !Idrivers/scsi/sata_sil.c |
352 | </chapter> |
353 | |
354 | <chapter id="libataThanks"> |
355 | <title>Thanks</title> |
356 | <para> |
357 | The bulk of the ATA knowledge comes thanks to long conversations with |
358 | Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA |
359 | and SCSI specifications. |
360 | </para> |
361 | <para> |
362 | Thanks to Alan Cox for pointing out similarities |
363 | between SATA and SCSI, and in general for motivation to hack on |
364 | libata. |
365 | </para> |
366 | <para> |
367 | libata's device detection |
368 | method, ata_pio_devchk, and in general all the early probing was |
369 | based on extensive study of Hale Landis's probe/reset code in his |
370 | ATADRVR driver (www.ata-atapi.com). |
371 | </para> |
372 | </chapter> |
373 | |
374 | </book> |