aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/libata.tmpl104
1 files changed, 80 insertions, 24 deletions
diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl
index f869b03929db..e97c32314541 100644
--- a/Documentation/DocBook/libata.tmpl
+++ b/Documentation/DocBook/libata.tmpl
@@ -169,6 +169,22 @@ void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
169 169
170 </sect2> 170 </sect2>
171 171
172 <sect2><title>PIO data read/write</title>
173 <programlisting>
174void (*data_xfer) (struct ata_device *, unsigned char *, unsigned int, int);
175 </programlisting>
176
177 <para>
178All bmdma-style drivers must implement this hook. This is the low-level
179operation that actually copies the data bytes during a PIO data
180transfer.
181Typically the driver
182will choose one of ata_pio_data_xfer_noirq(), ata_pio_data_xfer(), or
183ata_mmio_data_xfer().
184 </para>
185
186 </sect2>
187
172 <sect2><title>ATA command execute</title> 188 <sect2><title>ATA command execute</title>
173 <programlisting> 189 <programlisting>
174void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); 190void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
@@ -204,11 +220,10 @@ command.
204 <programlisting> 220 <programlisting>
205u8 (*check_status)(struct ata_port *ap); 221u8 (*check_status)(struct ata_port *ap);
206u8 (*check_altstatus)(struct ata_port *ap); 222u8 (*check_altstatus)(struct ata_port *ap);
207u8 (*check_err)(struct ata_port *ap);
208 </programlisting> 223 </programlisting>
209 224
210 <para> 225 <para>
211 Reads the Status/AltStatus/Error ATA shadow register from 226 Reads the Status/AltStatus ATA shadow register from
212 hardware. On some hardware, reading the Status register has 227 hardware. On some hardware, reading the Status register has
213 the side effect of clearing the interrupt condition. 228 the side effect of clearing the interrupt condition.
214 Most drivers for taskfile-based hardware use 229 Most drivers for taskfile-based hardware use
@@ -269,23 +284,6 @@ void (*set_mode) (struct ata_port *ap);
269 284
270 </sect2> 285 </sect2>
271 286
272 <sect2><title>Reset ATA bus</title>
273 <programlisting>
274void (*phy_reset) (struct ata_port *ap);
275 </programlisting>
276
277 <para>
278 The very first step in the probe phase. Actions vary depending
279 on the bus type, typically. After waking up the device and probing
280 for device presence (PATA and SATA), typically a soft reset
281 (SRST) will be performed. Drivers typically use the helper
282 functions ata_bus_reset() or sata_phy_reset() for this hook.
283 Many SATA drivers use sata_phy_reset() or call it from within
284 their own phy_reset() functions.
285 </para>
286
287 </sect2>
288
289 <sect2><title>Control PCI IDE BMDMA engine</title> 287 <sect2><title>Control PCI IDE BMDMA engine</title>
290 <programlisting> 288 <programlisting>
291void (*bmdma_setup) (struct ata_queued_cmd *qc); 289void (*bmdma_setup) (struct ata_queued_cmd *qc);
@@ -354,16 +352,74 @@ int (*qc_issue) (struct ata_queued_cmd *qc);
354 352
355 </sect2> 353 </sect2>
356 354
357 <sect2><title>Timeout (error) handling</title> 355 <sect2><title>Exception and probe handling (EH)</title>
358 <programlisting> 356 <programlisting>
359void (*eng_timeout) (struct ata_port *ap); 357void (*eng_timeout) (struct ata_port *ap);
358void (*phy_reset) (struct ata_port *ap);
359 </programlisting>
360
361 <para>
362Deprecated. Use ->error_handler() instead.
363 </para>
364
365 <programlisting>
366void (*freeze) (struct ata_port *ap);
367void (*thaw) (struct ata_port *ap);
368 </programlisting>
369
370 <para>
371ata_port_freeze() is called when HSM violations or some other
372condition disrupts normal operation of the port. A frozen port
373is not allowed to perform any operation until the port is
374thawed, which usually follows a successful reset.
375 </para>
376
377 <para>
378The optional ->freeze() callback can be used for freezing the port
379hardware-wise (e.g. mask interrupt and stop DMA engine). If a
380port cannot be frozen hardware-wise, the interrupt handler
381must ack and clear interrupts unconditionally while the port
382is frozen.
383 </para>
384 <para>
385The optional ->thaw() callback is called to perform the opposite of ->freeze():
386prepare the port for normal operation once again. Unmask interrupts,
387start DMA engine, etc.
388 </para>
389
390 <programlisting>
391void (*error_handler) (struct ata_port *ap);
392 </programlisting>
393
394 <para>
395->error_handler() is a driver's hook into probe, hotplug, and recovery
396and other exceptional conditions. The primary responsibility of an
397implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with a set
398of EH hooks as arguments:
399 </para>
400
401 <para>
402'prereset' hook (may be NULL) is called during an EH reset, before any other actions
403are taken.
404 </para>
405
406 <para>
407'postreset' hook (may be NULL) is called after the EH reset is performed. Based on
408existing conditions, severity of the problem, and hardware capabilities,
409 </para>
410
411 <para>
412Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be
413called to perform the low-level EH reset.
414 </para>
415
416 <programlisting>
417void (*post_internal_cmd) (struct ata_queued_cmd *qc);
360 </programlisting> 418 </programlisting>
361 419
362 <para> 420 <para>
363This is a high level error handling function, called from the 421Perform any hardware-specific actions necessary to finish processing
364error handling thread, when a command times out. Most newer 422after executing a probe-time or EH-time command via ata_exec_internal().
365hardware will implement its own error handling code here. IDE BMDMA
366drivers may use the helper function ata_eng_timeout().
367 </para> 423 </para>
368 424
369 </sect2> 425 </sect2>