</authorgroup>
<copyright>
- <year>2003-2005</year>
+ <year>2003-2006</year>
<holder>Jeff Garzik</holder>
</copyright>
</programlisting>
<para>
- Called from ata_bus_probe() and ata_bus_reset() error paths,
- as well as when unregistering from the SCSI module (rmmod, hot
- unplug).
+ Called from ata_bus_probe() error path, as well as when
+ unregistering from the SCSI module (rmmod, hot unplug).
This function should do whatever needs to be done to take the
port out of use. In most cases, ata_port_disable() can be used
as this hook.
</para>
<para>
Called from ata_bus_probe() on a failed probe.
- Called from ata_bus_reset() on a failed bus reset.
Called from ata_scsi_release().
</para>
issue of SET FEATURES - XFER MODE, and prior to operation.
</para>
<para>
- Called by ata_device_add() after ata_dev_identify() determines
- a device is present.
- </para>
- <para>
This entry may be specified as NULL in ata_port_operations.
</para>
<sect2><title>Taskfile read/write</title>
<programlisting>
-void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
-void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
+void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
+void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
</programlisting>
<para>
hardware registers / DMA buffers, to obtain the current set of
taskfile register values.
Most drivers for taskfile-based hardware (PIO or MMIO) use
- ata_tf_load() and ata_tf_read() for these hooks.
+ ata_sff_tf_load() and ata_sff_tf_read() for these hooks.
+ </para>
+
+ </sect2>
+
+ <sect2><title>PIO data read/write</title>
+ <programlisting>
+void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int);
+ </programlisting>
+
+ <para>
+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_sff_data_xfer_noirq(),
+ata_sff_data_xfer(), or ata_sff_data_xfer32().
</para>
</sect2>
<sect2><title>ATA command execute</title>
<programlisting>
-void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
+void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
</programlisting>
<para>
causes an ATA command, previously loaded with
->tf_load(), to be initiated in hardware.
- Most drivers for taskfile-based hardware use ata_exec_command()
+ Most drivers for taskfile-based hardware use ata_sff_exec_command()
for this hook.
</para>
<sect2><title>Read specific ATA shadow registers</title>
<programlisting>
-u8 (*check_status)(struct ata_port *ap);
-u8 (*check_altstatus)(struct ata_port *ap);
-u8 (*check_err)(struct ata_port *ap);
+u8 (*sff_check_status)(struct ata_port *ap);
+u8 (*sff_check_altstatus)(struct ata_port *ap);
</programlisting>
<para>
- 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
- ata_check_status() for this hook.
+ ata_sff_check_status() for this hook.
</para>
+
+ </sect2>
+
+ <sect2><title>Write specific ATA shadow register</title>
+ <programlisting>
+void (*sff_set_devctl)(struct ata_port *ap, u8 ctl);
+ </programlisting>
+
<para>
- Note that because this is called from ata_device_add(), at
- least a dummy function that clears device interrupts must be
- provided for all drivers, even if the controller doesn't
- actually have a taskfile status register.
+ Write the device control ATA shadow register to the hardware.
+ Most drivers don't need to define this.
</para>
</sect2>
<sect2><title>Select ATA device on bus</title>
<programlisting>
-void (*dev_select)(struct ata_port *ap, unsigned int device);
+void (*sff_dev_select)(struct ata_port *ap, unsigned int device);
</programlisting>
<para>
</para>
<para>
Most drivers for taskfile-based hardware use
- ata_std_dev_select() for this hook. Controllers which do not
- support second drives on a port (such as SATA contollers) will
- use ata_noop_dev_select().
+ ata_sff_dev_select() for this hook.
</para>
</sect2>
</sect2>
- <sect2><title>Reset ATA bus</title>
- <programlisting>
-void (*phy_reset) (struct ata_port *ap);
- </programlisting>
-
- <para>
- 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.
- </para>
-
- </sect2>
-
<sect2><title>Control PCI IDE BMDMA engine</title>
<programlisting>
void (*bmdma_setup) (struct ata_queued_cmd *qc);
</sect2>
- <sect2><title>Timeout (error) handling</title>
+ <sect2><title>Exception and probe handling (EH)</title>
<programlisting>
void (*eng_timeout) (struct ata_port *ap);
+void (*phy_reset) (struct ata_port *ap);
+ </programlisting>
+
+ <para>
+Deprecated. Use ->error_handler() instead.
+ </para>
+
+ <programlisting>
+void (*freeze) (struct ata_port *ap);
+void (*thaw) (struct ata_port *ap);
+ </programlisting>
+
+ <para>
+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.
+ </para>
+
+ <para>
+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.
+ </para>
+ <para>
+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.
+ </para>
+
+ <programlisting>
+void (*error_handler) (struct ata_port *ap);
+ </programlisting>
+
+ <para>
+->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:
+ </para>
+
+ <para>
+'prereset' hook (may be NULL) is called during an EH reset, before any other actions
+are taken.
+ </para>
+
+ <para>
+'postreset' hook (may be NULL) is called after the EH reset is performed. Based on
+existing conditions, severity of the problem, and hardware capabilities,
+ </para>
+
+ <para>
+Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be
+called to perform the low-level EH reset.
+ </para>
+
+ <programlisting>
+void (*post_internal_cmd) (struct ata_queued_cmd *qc);
</programlisting>
<para>
-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().
</para>
</sect2>
to struct ata_host_set.
</para>
<para>
- Most legacy IDE drivers use ata_interrupt() for the
+ Most legacy IDE drivers use ata_sff_interrupt() for the
irq_handler hook, which scans all ports in the host_set,
determines which queued command was active (if any), and calls
- ata_host_intr(ap,qc).
+ ata_sff_host_intr(ap,qc).
</para>
<para>
- Most legacy IDE drivers use ata_bmdma_irq_clear() for the
+ Most legacy IDE drivers use ata_sff_irq_clear() for the
irq_clear() hook, which simply clears the interrupt and error
flags in the DMA status register.
</para>
<sect2><title>SATA phy read/write</title>
<programlisting>
-u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
-void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
+int (*scr_read) (struct ata_port *ap, unsigned int sc_reg,
+ u32 *val);
+int (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
u32 val);
</programlisting>
allocates space for a legacy IDE PRD table and returns.
</para>
<para>
- ->port_stop() is called after ->host_stop(). It's sole function
+ ->port_stop() is called after ->host_stop(). Its sole function
is to release DMA/memory resources, now that they are no longer
actively being used. Many drivers also free driver-private
data from port at this time.
</para>
<para>
- Many drivers use ata_port_stop() as this hook, which frees the
- PRD table.
- </para>
- <para>
->host_stop() is called after all ->port_stop() calls
have completed. The hook must finalize hardware shutdown, release DMA
and other resources, etc.
<chapter id="libataExt">
<title>libata Library</title>
-!Edrivers/scsi/libata-core.c
+!Edrivers/ata/libata-core.c
</chapter>
<chapter id="libataInt">
<title>libata Core Internals</title>
-!Idrivers/scsi/libata-core.c
+!Idrivers/ata/libata-core.c
</chapter>
<chapter id="libataScsiInt">
<title>libata SCSI translation/emulation</title>
-!Edrivers/scsi/libata-scsi.c
-!Idrivers/scsi/libata-scsi.c
+!Edrivers/ata/libata-scsi.c
+!Idrivers/ata/libata-scsi.c
</chapter>
<chapter id="ataExceptions">
- <title>ATA errors & exceptions</title>
+ <title>ATA errors and exceptions</title>
<para>
This chapter tries to identify what error/exception conditions exist
<listitem>
<para>
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.
</para>
</listitem>
<chapter id="PiixInt">
<title>ata_piix Internals</title>
-!Idrivers/scsi/ata_piix.c
+!Idrivers/ata/ata_piix.c
</chapter>
<chapter id="SILInt">
<title>sata_sil Internals</title>
-!Idrivers/scsi/sata_sil.c
+!Idrivers/ata/sata_sil.c
</chapter>
<chapter id="libataThanks">
git://ftp.safe.ca / safe / jmp / linux-2.6 / blobdiff