X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=Documentation%2FDocBook%2Flibata.tmpl;h=e2e24b4778d447b8335e3f447f51883b618c306b;hb=97bf2856c6014879bd04983a3e9dfcdac1e7fe85;hp=d260d92089ade348879bda74b2bf9ae48714d110;hpb=76828883507a47dae78837ab5dec5a5b4513c667;p=linux-2.6.git
diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl
index d260d9208..e2e24b477 100644
--- a/Documentation/DocBook/libata.tmpl
+++ b/Documentation/DocBook/libata.tmpl
@@ -14,7 +14,7 @@
- 2003-2005
+ 2003-2006
Jeff Garzik
@@ -120,14 +120,27 @@ void (*dev_config) (struct ata_port *, struct ata_device *);
void (*set_piomode) (struct ata_port *, struct ata_device *);
void (*set_dmamode) (struct ata_port *, struct ata_device *);
-void (*post_set_mode) (struct ata_port *ap);
+void (*post_set_mode) (struct ata_port *);
+unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int);
Hooks called prior to the issue of SET FEATURES - XFER MODE
- command. dev->pio_mode is guaranteed to be valid when
- ->set_piomode() is called, and dev->dma_mode is guaranteed to be
- valid when ->set_dmamode() is called. ->post_set_mode() is
+ command. The optional ->mode_filter() hook is called when libata
+ has built a mask of the possible modes. This is passed to the
+ ->mode_filter() function which should return a mask of valid modes
+ after filtering those unsuitable due to hardware limits. It is not
+ valid to use this interface to add modes.
+
+
+ dev->pio_mode and dev->dma_mode are guaranteed to be valid when
+ ->set_piomode() and when ->set_dmamode() is called. The timings for
+ any other drive sharing the cable will also be valid at this point.
+ That is the library records the decisions for the modes of each
+ drive on a channel before it attempts to set any of them.
+
+
+ ->post_set_mode() is
called unconditionally, after the SET FEATURES - XFER MODE
command completes successfully.
@@ -156,6 +169,22 @@ void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
+ PIO data read/write
+
+void (*data_xfer) (struct ata_device *, unsigned char *, unsigned int, int);
+
+
+
+All bmdma-style drivers must implement this hook. This is the low-level
+operation that actually copies the data bytes during a PIO data
+transfer.
+Typically the driver
+will choose one of ata_pio_data_xfer_noirq(), ata_pio_data_xfer(), or
+ata_mmio_data_xfer().
+
+
+
+
ATA command execute
void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
@@ -191,11 +220,10 @@ command.
u8 (*check_status)(struct ata_port *ap);
u8 (*check_altstatus)(struct ata_port *ap);
-u8 (*check_err)(struct ata_port *ap);
- Reads the Status/AltStatus/Error ATA shadow register from
+ Reads the Status/AltStatus ATA shadow register from
hardware. On some hardware, reading the Status register has
the side effect of clearing the interrupt condition.
Most drivers for taskfile-based hardware use
@@ -230,21 +258,30 @@ void (*dev_select)(struct ata_port *ap, unsigned int device);
- Reset ATA bus
+ Private tuning method
-void (*phy_reset) (struct ata_port *ap);
+void (*set_mode) (struct ata_port *ap);
- The very first step in the probe phase. Actions vary depending
- on the bus type, typically. After waking up the device and probing
- for device presence (PATA and SATA), typically a soft reset
- (SRST) will be performed. Drivers typically use the helper
- functions ata_bus_reset() or sata_phy_reset() for this hook.
- Many SATA drivers use sata_phy_reset() or call it from within
- their own phy_reset() functions.
+ By default libata performs drive and controller tuning in
+ accordance with the ATA timing rules and also applies blacklists
+ and cable limits. Some controllers need special handling and have
+ custom tuning rules, typically raid controllers that use ATA
+ commands but do not actually do drive timing.
+
+
+ This hook should not be used to replace the standard controller
+ tuning logic when a controller has quirks. Replacing the default
+ tuning logic in that case would bypass handling for drive and
+ bridge quirks that may be important to data reliability. If a
+ controller needs to filter the mode selection it should use the
+ mode_filter hook instead.
+
+
+
Control PCI IDE BMDMA engine
@@ -315,16 +352,74 @@ int (*qc_issue) (struct ata_queued_cmd *qc);
- Timeout (error) handling
+ Exception and probe handling (EH)
void (*eng_timeout) (struct ata_port *ap);
+void (*phy_reset) (struct ata_port *ap);
+
+
+
+Deprecated. Use ->error_handler() instead.
+
+
+
+void (*freeze) (struct ata_port *ap);
+void (*thaw) (struct ata_port *ap);
+
+
+
+ata_port_freeze() is called when HSM violations or some other
+condition disrupts normal operation of the port. A frozen port
+is not allowed to perform any operation until the port is
+thawed, which usually follows a successful reset.
+
+
+
+The optional ->freeze() callback can be used for freezing the port
+hardware-wise (e.g. mask interrupt and stop DMA engine). If a
+port cannot be frozen hardware-wise, the interrupt handler
+must ack and clear interrupts unconditionally while the port
+is frozen.
+
+
+The optional ->thaw() callback is called to perform the opposite of ->freeze():
+prepare the port for normal operation once again. Unmask interrupts,
+start DMA engine, etc.
+
+
+
+void (*error_handler) (struct ata_port *ap);
+
+
+
+->error_handler() is a driver's hook into probe, hotplug, and recovery
+and other exceptional conditions. The primary responsibility of an
+implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with a set
+of EH hooks as arguments:
+
+
+
+'prereset' hook (may be NULL) is called during an EH reset, before any other actions
+are taken.
+
+
+
+'postreset' hook (may be NULL) is called after the EH reset is performed. Based on
+existing conditions, severity of the problem, and hardware capabilities,
+
+
+
+Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be
+called to perform the low-level EH reset.
+
+
+
+void (*post_internal_cmd) (struct ata_queued_cmd *qc);
-This is a high level error handling function, called from the
-error handling thread, when a command times out. Most newer
-hardware will implement its own error handling code here. IDE BMDMA
-drivers may use the helper function ata_eng_timeout().
+Perform any hardware-specific actions necessary to finish processing
+after executing a probe-time or EH-time command via ata_exec_internal().
@@ -666,7 +761,7 @@ and other resources, etc.
ata_scsi_error()
- ata_scsi_error() is the current hostt->eh_strategy_handler()
+ ata_scsi_error() is the current transportt->eh_strategy_handler()
for libata. As discussed above, this will be entered in two
cases - timeout and ATAPI error completion. This function
calls low level libata driver's eng_timeout() callback, the
@@ -773,22 +868,22 @@ and other resources, etc.
libata Library
-!Edrivers/scsi/libata-core.c
+!Edrivers/ata/libata-core.c
libata Core Internals
-!Idrivers/scsi/libata-core.c
+!Idrivers/ata/libata-core.c
libata SCSI translation/emulation
-!Edrivers/scsi/libata-scsi.c
-!Idrivers/scsi/libata-scsi.c
+!Edrivers/ata/libata-scsi.c
+!Idrivers/ata/libata-scsi.c
- ATA errors & exceptions
+ ATA errors and exceptions
This chapter tries to identify what error/exception conditions exist
@@ -1305,7 +1400,7 @@ and other resources, etc.
When it's known that HBA is in ready state but ATA/ATAPI
- device in in unknown state, reset only device.
+ device is in unknown state, reset only device.
@@ -1505,12 +1600,12 @@ and other resources, etc.
ata_piix Internals
-!Idrivers/scsi/ata_piix.c
+!Idrivers/ata/ata_piix.c
sata_sil Internals
-!Idrivers/scsi/sata_sil.c
+!Idrivers/ata/sata_sil.c