diff options
author | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-06-28 13:20:11 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-06-28 13:20:11 -0400 |
commit | 61998bcb4bf0efa0276e88c7853091e482a826f4 (patch) | |
tree | e01a1cbcc20ca013622fce45a1a056b89a11a40b /Documentation | |
parent | c36ad397a30fcf9369d82584324cc24189eb6b1c (diff) | |
parent | 0a139e79976b9eb60517edec63406236a789f812 (diff) |
Merge head 'upstream-20050628-1' of rsync://rsync.kernel.org/pub/scm/linux/kernel/git/jgarzik/libata-dev
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/DocBook/libata.tmpl | 96 |
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 | |||
161 | indicating whether or not it is OK to use DMA for the supplied PACKET | 180 | indicating whether or not it is OK to use DMA for the supplied PACKET |
162 | command. | 181 | command. |
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 |
191 | meaning 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. | |||
227 | These hooks are typically either no-ops, or simply not implemented, in | 266 | These hooks are typically either no-ops, or simply not implemented, in |
228 | FIS-based drivers. | 267 | FIS-based drivers. |
229 | </para> | 268 | </para> |
269 | <para> | ||
270 | Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup() | ||
271 | hook. ata_bmdma_setup() will write the pointer to the PRD table to | ||
272 | the IDE PRD Table Address register, enable DMA in the DMA Command | ||
273 | register, and call exec_command() to begin the transfer. | ||
274 | </para> | ||
275 | <para> | ||
276 | Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start() | ||
277 | hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA | ||
278 | Command register. | ||
279 | </para> | ||
280 | <para> | ||
281 | Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop() | ||
282 | hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA | ||
283 | command register. | ||
284 | </para> | ||
285 | <para> | ||
286 | Many 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 |
319 | have completed. The hook must finalize hardware shutdown, release DMA | 408 | have completed. The hook must finalize hardware shutdown, release DMA |
320 | and other resources, etc. | 409 | and 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> |