1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>
2
3<book id="libataDevGuide">
4 <bookinfo>
5  <title>libATA Developer's Guide</title>
6
7  <authorgroup>
8   <author>
9    <firstname>Jeff</firstname>
10    <surname>Garzik</surname>
11   </author>
12  </authorgroup>
13
14  <copyright>
15   <year>2003</year>
16   <holder>Jeff Garzik</holder>
17  </copyright>
18
19  <legalnotice>
20   <para>
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
24   by reference.
25   </para>
26
27   <para>
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.
38   </para>
39
40  </legalnotice>
41 </bookinfo>
42
43<toc></toc>
44
45  <chapter id="libataThanks">
46     <title>Thanks</title>
47  <para>
48  The bulk of the ATA knowledge comes thanks to long conversations with
49  Andre Hedrick (www.linux-ide.org).
50  </para>
51  <para>
52  Thanks to Alan Cox for pointing out similarities
53  between SATA and SCSI, and in general for motivation to hack on
54  libata.
55  </para>
56  <para>
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).
61  </para>
62  </chapter>
63
64  <chapter id="libataDriverApi">
65     <title>libata Driver API</title>
66     <sect1>
67        <title>struct ata_port_operations</title>
68
69	<programlisting>
70void (*port_disable) (struct ata_port *);
71	</programlisting>
72
73	<para>
74	Called from ata_bus_probe() and ata_bus_reset() error paths,
75	as well as when unregistering from the SCSI module (rmmod, hot
76	unplug).
77	</para>
78
79	<programlisting>
80void (*dev_config) (struct ata_port *, struct ata_device *);
81	</programlisting>
82
83	<para>
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.
87	</para>
88
89	<programlisting>
90void (*set_piomode) (struct ata_port *, struct ata_device *);
91void (*set_dmamode) (struct ata_port *, struct ata_device *);
92void (*post_set_mode) (struct ata_port *ap);
93	</programlisting>
94
95	<para>
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.
102	</para>
103
104	<para>
105	->set_piomode() is always called (if present), but
106	->set_dma_mode() is only called if DMA is possible.
107	</para>
108
109	<programlisting>
110void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
111void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
112	</programlisting>
113
114	<para>
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.
119	</para>
120
121	<programlisting>
122void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
123	</programlisting>
124
125	<para>
126	causes an ATA command, previously loaded with
127	->tf_load(), to be initiated in hardware.
128	</para>
129
130	<programlisting>
131u8   (*check_status)(struct ata_port *ap);
132void (*dev_select)(struct ata_port *ap, unsigned int device);
133	</programlisting>
134
135	<para>
136	Reads the Status ATA shadow register from hardware.  On some
137	hardware, this has the side effect of clearing the interrupt
138	condition.
139	</para>
140
141	<programlisting>
142void (*dev_select)(struct ata_port *ap, unsigned int device);
143	</programlisting>
144
145	<para>
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.
149	</para>
150
151	<programlisting>
152void (*phy_reset) (struct ata_port *ap);
153	</programlisting>
154
155	<para>
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.
161	</para>
162
163	<programlisting>
164void (*bmdma_setup) (struct ata_queued_cmd *qc);
165void (*bmdma_start) (struct ata_queued_cmd *qc);
166	</programlisting>
167
168	<para>
169	When setting up an IDE BMDMA transaction, these hooks arm
170	(->bmdma_setup) and fire (->bmdma_start) the hardware's DMA
171	engine.
172	</para>
173
174	<programlisting>
175void (*qc_prep) (struct ata_queued_cmd *qc);
176int (*qc_issue) (struct ata_queued_cmd *qc);
177	</programlisting>
178
179	<para>
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.
186	</para>
187	<para>
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
193	hardware" hook.
194	</para>
195
196	<programlisting>
197void (*eng_timeout) (struct ata_port *ap);
198	</programlisting>
199
200	<para>
201	This is a high level error handling function, called from the
202	error handling thread, when a command times out.
203	</para>
204
205	<programlisting>
206irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
207void (*irq_clear) (struct ata_port *);
208	</programlisting>
209
210	<para>
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
214	is quiet.
215	</para>
216
217	<programlisting>
218u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
219void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
220                   u32 val);
221	</programlisting>
222
223	<para>
224	Read and write standard SATA phy registers.  Currently only used
225	if ->phy_reset hook called the sata_phy_reset() helper function.
226	</para>
227
228	<programlisting>
229int (*port_start) (struct ata_port *ap);
230void (*port_stop) (struct ata_port *ap);
231void (*host_stop) (struct ata_host_set *host_set);
232	</programlisting>
233
234	<para>
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
238	tasks.
239	</para>
240	<para>
241	->host_stop() is called when the rmmod or hot unplug process
242	begins.  The hook must stop all hardware interrupts, DMA
243	engines, etc.
244	</para>
245	<para>
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
248	actively being used.
249	</para>
250
251     </sect1>
252  </chapter>
253
254  <chapter id="libataExt">
255     <title>libata Library</title>
256!Edrivers/scsi/libata-core.c
257  </chapter>
258
259  <chapter id="libataInt">
260     <title>libata Core Internals</title>
261!Idrivers/scsi/libata-core.c
262  </chapter>
263
264  <chapter id="libataScsiInt">
265     <title>libata SCSI translation/emulation</title>
266!Edrivers/scsi/libata-scsi.c
267!Idrivers/scsi/libata-scsi.c
268  </chapter>
269
270  <chapter id="SILInt">
271     <title>sata_sil Internals</title>
272!Idrivers/scsi/sata_sil.c
273  </chapter>
274
275</book>
276