aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorEdward Falk <efalk@google.com>2005-06-15 17:26:39 -0400
committerJeff Garzik <jgarzik@pobox.com>2005-06-27 23:21:00 -0400
commit8b2af8f0ca807eb13b59dc5961d2e99fc2b1bd87 (patch)
tree51b67f13beeb31f018f933ae192e029ca886f26d /Documentation
parentc7b645f934e52a54af58142d91fb51f881f8ce26 (diff)
[PATCH] Minor libata documentation patch
I fleshed out libata.tmpl a bit while I was taking notes.
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DocBook/libata.tmpl96
1 files changed, 93 insertions, 3 deletions
diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl
index 6df1dfd18b65..375ae760dc1e 100644
--- a/Documentation/DocBook/libata.tmpl
+++ b/Documentation/DocBook/libata.tmpl
@@ -84,6 +84,14 @@ void (*port_disable) (struct ata_port *);
84 Called from ata_bus_probe() and ata_bus_reset() error paths, 84 Called from ata_bus_probe() and ata_bus_reset() error paths,
85 as well as when unregistering from the SCSI module (rmmod, hot 85 as well as when unregistering from the SCSI module (rmmod, hot
86 unplug). 86 unplug).
87 This function should do whatever needs to be done to take the
88 port out of use. In most cases, ata_port_disable() can be used
89 as this hook.
90 </para>
91 <para>
92 Called from ata_bus_probe() on a failed probe.
93 Called from ata_bus_reset() on a failed bus reset.
94 Called from ata_scsi_release().
87 </para> 95 </para>
88 96
89 </sect2> 97 </sect2>
@@ -98,6 +106,13 @@ void (*dev_config) (struct ata_port *, struct ata_device *);
98 found. Typically used to apply device-specific fixups prior to 106 found. Typically used to apply device-specific fixups prior to
99 issue of SET FEATURES - XFER MODE, and prior to operation. 107 issue of SET FEATURES - XFER MODE, and prior to operation.
100 </para> 108 </para>
109 <para>
110 Called by ata_device_add() after ata_dev_identify() determines
111 a device is present.
112 </para>
113 <para>
114 This entry may be specified as NULL in ata_port_operations.
115 </para>
101 116
102 </sect2> 117 </sect2>
103 118
@@ -135,6 +150,8 @@ void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
135 registers / DMA buffers. ->tf_read() is called to read the 150 registers / DMA buffers. ->tf_read() is called to read the
136 hardware registers / DMA buffers, to obtain the current set of 151 hardware registers / DMA buffers, to obtain the current set of
137 taskfile register values. 152 taskfile register values.
153 Most drivers for taskfile-based hardware (PIO or MMIO) use
154 ata_tf_load() and ata_tf_read() for these hooks.
138 </para> 155 </para>
139 156
140 </sect2> 157 </sect2>
@@ -147,6 +164,8 @@ void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
147 <para> 164 <para>
148 causes an ATA command, previously loaded with 165 causes an ATA command, previously loaded with
149 ->tf_load(), to be initiated in hardware. 166 ->tf_load(), to be initiated in hardware.
167 Most drivers for taskfile-based hardware use ata_exec_command()
168 for this hook.
150 </para> 169 </para>
151 170
152 </sect2> 171 </sect2>
@@ -161,6 +180,10 @@ Allow low-level driver to filter ATA PACKET commands, returning a status
161indicating whether or not it is OK to use DMA for the supplied PACKET 180indicating whether or not it is OK to use DMA for the supplied PACKET
162command. 181command.
163 </para> 182 </para>
183 <para>
184 This hook may be specified as NULL, in which case libata will
185 assume that atapi dma can be supported.
186 </para>
164 187
165 </sect2> 188 </sect2>
166 189
@@ -175,6 +198,14 @@ u8 (*check_err)(struct ata_port *ap);
175 Reads the Status/AltStatus/Error ATA shadow register from 198 Reads the Status/AltStatus/Error ATA shadow register from
176 hardware. On some hardware, reading the Status register has 199 hardware. On some hardware, reading the Status register has
177 the side effect of clearing the interrupt condition. 200 the side effect of clearing the interrupt condition.
201 Most drivers for taskfile-based hardware use
202 ata_check_status() for this hook.
203 </para>
204 <para>
205 Note that because this is called from ata_device_add(), at
206 least a dummy function that clears device interrupts must be
207 provided for all drivers, even if the controller doesn't
208 actually have a taskfile status register.
178 </para> 209 </para>
179 210
180 </sect2> 211 </sect2>
@@ -188,7 +219,13 @@ void (*dev_select)(struct ata_port *ap, unsigned int device);
188 Issues the low-level hardware command(s) that causes one of N 219 Issues the low-level hardware command(s) that causes one of N
189 hardware devices to be considered 'selected' (active and 220 hardware devices to be considered 'selected' (active and
190 available for use) on the ATA bus. This generally has no 221 available for use) on the ATA bus. This generally has no
191meaning on FIS-based devices. 222 meaning on FIS-based devices.
223 </para>
224 <para>
225 Most drivers for taskfile-based hardware use
226 ata_std_dev_select() for this hook. Controllers which do not
227 support second drives on a port (such as SATA contollers) will
228 use ata_noop_dev_select().
192 </para> 229 </para>
193 230
194 </sect2> 231 </sect2>
@@ -204,6 +241,8 @@ void (*phy_reset) (struct ata_port *ap);
204 for device presence (PATA and SATA), typically a soft reset 241 for device presence (PATA and SATA), typically a soft reset
205 (SRST) will be performed. Drivers typically use the helper 242 (SRST) will be performed. Drivers typically use the helper
206 functions ata_bus_reset() or sata_phy_reset() for this hook. 243 functions ata_bus_reset() or sata_phy_reset() for this hook.
244 Many SATA drivers use sata_phy_reset() or call it from within
245 their own phy_reset() functions.
207 </para> 246 </para>
208 247
209 </sect2> 248 </sect2>
@@ -227,6 +266,25 @@ PCI IDE DMA Status register.
227These hooks are typically either no-ops, or simply not implemented, in 266These hooks are typically either no-ops, or simply not implemented, in
228FIS-based drivers. 267FIS-based drivers.
229 </para> 268 </para>
269 <para>
270Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup()
271hook. ata_bmdma_setup() will write the pointer to the PRD table to
272the IDE PRD Table Address register, enable DMA in the DMA Command
273register, and call exec_command() to begin the transfer.
274 </para>
275 <para>
276Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start()
277hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA
278Command register.
279 </para>
280 <para>
281Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop()
282hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA
283command register.
284 </para>
285 <para>
286Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook.
287 </para>
230 288
231 </sect2> 289 </sect2>
232 290
@@ -250,6 +308,10 @@ int (*qc_issue) (struct ata_queued_cmd *qc);
250 helper function ata_qc_issue_prot() for taskfile protocol-based 308 helper function ata_qc_issue_prot() for taskfile protocol-based
251 dispatch. More advanced drivers implement their own ->qc_issue. 309 dispatch. More advanced drivers implement their own ->qc_issue.
252 </para> 310 </para>
311 <para>
312 ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and
313 ->bmdma_start() as necessary to initiate a transfer.
314 </para>
253 315
254 </sect2> 316 </sect2>
255 317
@@ -279,6 +341,21 @@ void (*irq_clear) (struct ata_port *);
279 before the interrupt handler is registered, to be sure hardware 341 before the interrupt handler is registered, to be sure hardware
280 is quiet. 342 is quiet.
281 </para> 343 </para>
344 <para>
345 The second argument, dev_instance, should be cast to a pointer
346 to struct ata_host_set.
347 </para>
348 <para>
349 Most legacy IDE drivers use ata_interrupt() for the
350 irq_handler hook, which scans all ports in the host_set,
351 determines which queued command was active (if any), and calls
352 ata_host_intr(ap,qc).
353 </para>
354 <para>
355 Most legacy IDE drivers use ata_bmdma_irq_clear() for the
356 irq_clear() hook, which simply clears the interrupt and error
357 flags in the DMA status register.
358 </para>
282 359
283 </sect2> 360 </sect2>
284 361
@@ -292,6 +369,7 @@ void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
292 <para> 369 <para>
293 Read and write standard SATA phy registers. Currently only used 370 Read and write standard SATA phy registers. Currently only used
294 if ->phy_reset hook called the sata_phy_reset() helper function. 371 if ->phy_reset hook called the sata_phy_reset() helper function.
372 sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.
295 </para> 373 </para>
296 374
297 </sect2> 375 </sect2>
@@ -307,17 +385,29 @@ void (*host_stop) (struct ata_host_set *host_set);
307 ->port_start() is called just after the data structures for each 385 ->port_start() is called just after the data structures for each
308 port are initialized. Typically this is used to alloc per-port 386 port are initialized. Typically this is used to alloc per-port
309 DMA buffers / tables / rings, enable DMA engines, and similar 387 DMA buffers / tables / rings, enable DMA engines, and similar
310 tasks. 388 tasks. Some drivers also use this entry point as a chance to
389 allocate driver-private memory for ap->private_data.
390 </para>
391 <para>
392 Many drivers use ata_port_start() as this hook or call
393 it from their own port_start() hooks. ata_port_start()
394 allocates space for a legacy IDE PRD table and returns.
311 </para> 395 </para>
312 <para> 396 <para>
313 ->port_stop() is called after ->host_stop(). It's sole function 397 ->port_stop() is called after ->host_stop(). It's sole function
314 is to release DMA/memory resources, now that they are no longer 398 is to release DMA/memory resources, now that they are no longer
315 actively being used. 399 actively being used. Many drivers also free driver-private
400 data from port at this time.
401 </para>
402 <para>
403 Many drivers use ata_port_stop() as this hook, which frees the
404 PRD table.
316 </para> 405 </para>
317 <para> 406 <para>
318 ->host_stop() is called after all ->port_stop() calls 407 ->host_stop() is called after all ->port_stop() calls
319have completed. The hook must finalize hardware shutdown, release DMA 408have completed. The hook must finalize hardware shutdown, release DMA
320and other resources, etc. 409and other resources, etc.
410 This hook may be specified as NULL, in which case it is not called.
321 </para> 411 </para>
322 412
323 </sect2> 413 </sect2>