kgdb,docs: Update the kgdb docs to include kdb
[safe/jmp/linux-2.6] / Documentation / DocBook / libata.tmpl
index f9a7c06..8c5411c 100644 (file)
@@ -81,16 +81,14 @@ void (*port_disable) (struct ata_port *);
        </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>
 
@@ -107,10 +105,6 @@ void (*dev_config) (struct ata_port *, struct ata_device *);
        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>
 
@@ -154,8 +148,8 @@ unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned in
 
        <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>
@@ -164,36 +158,35 @@ void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
        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 (*data_xfer) (struct ata_device *, unsigned char *, unsigned int, int);
+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_pio_data_xfer_noirq(), ata_pio_data_xfer(), or
-ata_mmio_data_xfer().
+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>
 
@@ -218,8 +211,8 @@ command.
 
        <sect2><title>Read specific ATA shadow registers</title>
        <programlisting>
-u8   (*check_status)(struct ata_port *ap);
-u8   (*check_altstatus)(struct ata_port *ap);
+u8   (*sff_check_status)(struct ata_port *ap);
+u8   (*sff_check_altstatus)(struct ata_port *ap);
        </programlisting>
 
        <para>
@@ -227,20 +220,26 @@ u8   (*check_altstatus)(struct ata_port *ap);
        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>
@@ -251,9 +250,7 @@ void (*dev_select)(struct ata_port *ap, unsigned int device);
        </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>
@@ -441,13 +438,13 @@ void (*irq_clear) (struct ata_port *);
        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>
@@ -456,8 +453,9 @@ void (*irq_clear) (struct ata_port *);
 
        <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>
 
@@ -489,16 +487,12 @@ void (*host_stop) (struct ata_host_set *host_set);
        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.
@@ -883,7 +877,7 @@ and other resources, etc.
   </chapter>
 
   <chapter id="ataExceptions">
-     <title>ATA errors &amp; exceptions</title>
+     <title>ATA errors and exceptions</title>
 
   <para>
   This chapter tries to identify what error/exception conditions exist
@@ -1400,7 +1394,7 @@ and other resources, etc.
        <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>