Documentation/DocBook/libata.tmpl

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
   4
   5 <book id="libataDevGuide">
   6  <bookinfo>
   7   <title>libATA Developer's Guide</title>
   8
   9   <authorgroup>
  10    <author>
  11     <firstname>Jeff</firstname>
  12     <surname>Garzik</surname>
  13    </author>
  14   </authorgroup>
  15
  16   <copyright>
  17    <year>2003</year>
  18    <holder>Jeff Garzik</holder>
  19   </copyright>
  20
  21   <legalnotice>
  22    <para>
  23    The contents of this file are subject to the Open
  24    Software License version 1.1 that can be found at
  25    <ulink url="http://www.opensource.org/licenses/osl-1.1.txt">http://www.opensource.org/licenses/osl-1.1.txt</ulink> and is included herein
  26    by reference.
  27    </para>
  28
  29    <para>
  30    Alternatively, the contents of this file may be used under the terms
  31    of the GNU General Public License version 2 (the "GPL") as distributed
  32    in the kernel source COPYING file, in which case the provisions of
  33    the GPL are applicable instead of the above.  If you wish to allow
  34    the use of your version of this file only under the terms of the
  35    GPL and not to allow others to use your version of this file under
  36    the OSL, indicate your decision by deleting the provisions above and
  37    replace them with the notice and other provisions required by the GPL.
  38    If you do not delete the provisions above, a recipient may use your
  39    version of this file under either the OSL or the GPL.
  40    </para>
  41
  42   </legalnotice>
  43  </bookinfo>
  44
  45 <toc></toc>
  46
  47   <chapter id="libataThanks">
  48      <title>Thanks</title>
  49   <para>
  50   The bulk of the ATA knowledge comes thanks to long conversations with
  51   Andre Hedrick (www.linux-ide.org).
  52   </para>
  53   <para>
  54   Thanks to Alan Cox for pointing out similarities
  55   between SATA and SCSI, and in general for motivation to hack on
  56   libata.
  57   </para>
  58   <para>
  59   libata's device detection
  60   method, ata_pio_devchk, and in general all the early probing was
  61   based on extensive study of Hale Landis's probe/reset code in his
  62   ATADRVR driver (www.ata-atapi.com).
  63   </para>
  64   </chapter>
  65
  66   <chapter id="libataDriverApi">
  67      <title>libata Driver API</title>
  68      <sect1>
  69         <title>struct ata_port_operations</title>
  70
  71         <programlisting>
  72 void (*port_disable) (struct ata_port *);
  73         </programlisting>
  74
  75         <para>
  76         Called from ata_bus_probe() and ata_bus_reset() error paths,
  77         as well as when unregistering from the SCSI module (rmmod, hot
  78         unplug).
  79         </para>
  80
  81         <programlisting>
  82 void (*dev_config) (struct ata_port *, struct ata_device *);
  83         </programlisting>
  84
  85         <para>
  86         Called after IDENTIFY [PACKET] DEVICE is issued to each device
  87         found.  Typically used to apply device-specific fixups prior to
  88         issue of SET FEATURES - XFER MODE, and prior to operation.
  89         </para>
  90
  91         <programlisting>
  92 void (*set_piomode) (struct ata_port *, struct ata_device *);
  93 void (*set_dmamode) (struct ata_port *, struct ata_device *);
  94 void (*post_set_mode) (struct ata_port *ap);
  95         </programlisting>
  96
  97         <para>
  98         Hooks called prior to the issue of SET FEATURES - XFER MODE
  99         command.  dev->pio_mode is guaranteed to be valid when
 100         ->set_piomode() is called, and dev->dma_mode is guaranteed to be
 101         valid when ->set_dmamode() is called.  ->post_set_mode() is
 102         called unconditionally, after the SET FEATURES - XFER MODE
 103         command completes successfully.
 104         </para>
 105
 106         <para>
 107         ->set_piomode() is always called (if present), but
 108         ->set_dma_mode() is only called if DMA is possible.
 109         </para>
 110
 111         <programlisting>
 112 void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
 113 void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
 114         </programlisting>
 115
 116         <para>
 117         ->tf_load() is called to load the given taskfile into hardware
 118         registers / DMA buffers.  ->tf_read() is called to read the
 119         hardware registers / DMA buffers, to obtain the current set of
 120         taskfile register values.
 121         </para>
 122
 123         <programlisting>
 124 void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
 125         </programlisting>
 126
 127         <para>
 128         causes an ATA command, previously loaded with
 129         ->tf_load(), to be initiated in hardware.
 130         </para>
 131
 132         <programlisting>
 133 u8   (*check_status)(struct ata_port *ap);
 134 void (*dev_select)(struct ata_port *ap, unsigned int device);
 135         </programlisting>
 136
 137         <para>
 138         Reads the Status ATA shadow register from hardware.  On some
 139         hardware, this has the side effect of clearing the interrupt
 140         condition.
 141         </para>
 142
 143         <programlisting>
 144 void (*dev_select)(struct ata_port *ap, unsigned int device);
 145         </programlisting>
 146
 147         <para>
 148         Issues the low-level hardware command(s) that causes one of N
 149         hardware devices to be considered 'selected' (active and
 150         available for use) on the ATA bus.
 151         </para>
 152
 153         <programlisting>
 154 void (*phy_reset) (struct ata_port *ap);
 155         </programlisting>
 156
 157         <para>
 158         The very first step in the probe phase.  Actions vary depending
 159         on the bus type, typically.  After waking up the device and probing
 160         for device presence (PATA and SATA), typically a soft reset
 161         (SRST) will be performed.  Drivers typically use the helper
 162         functions ata_bus_reset() or sata_phy_reset() for this hook.
 163         </para>
 164
 165         <programlisting>
 166 void (*bmdma_setup) (struct ata_queued_cmd *qc);
 167 void (*bmdma_start) (struct ata_queued_cmd *qc);
 168         </programlisting>
 169
 170         <para>
 171         When setting up an IDE BMDMA transaction, these hooks arm
 172         (->bmdma_setup) and fire (->bmdma_start) the hardware's DMA
 173         engine.
 174         </para>
 175
 176         <programlisting>
 177 void (*qc_prep) (struct ata_queued_cmd *qc);
 178 int (*qc_issue) (struct ata_queued_cmd *qc);
 179         </programlisting>
 180
 181         <para>
 182         Higher-level hooks, these two hooks can potentially supercede
 183         several of the above taskfile/DMA engine hooks.  ->qc_prep is
 184         called after the buffers have been DMA-mapped, and is typically
 185         used to populate the hardware's DMA scatter-gather table.
 186         Most drivers use the standard ata_qc_prep() helper function, but
 187         more advanced drivers roll their own.
 188         </para>
 189         <para>
 190         ->qc_issue is used to make a command active, once the hardware
 191         and S/G tables have been prepared.  IDE BMDMA drivers use the
 192         helper function ata_qc_issue_prot() for taskfile protocol-based
 193         dispatch.  More advanced drivers roll their own ->qc_issue
 194         implementation, using this as the "issue new ATA command to
 195         hardware" hook.
 196         </para>
 197
 198         <programlisting>
 199 void (*eng_timeout) (struct ata_port *ap);
 200         </programlisting>
 201
 202         <para>
 203         This is a high level error handling function, called from the
 204         error handling thread, when a command times out.
 205         </para>
 206
 207         <programlisting>
 208 irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
 209 void (*irq_clear) (struct ata_port *);
 210         </programlisting>
 211
 212         <para>
 213         ->irq_handler is the interrupt handling routine registered with
 214         the system, by libata.  ->irq_clear is called during probe just
 215         before the interrupt handler is registered, to be sure hardware
 216         is quiet.
 217         </para>
 218
 219         <programlisting>
 220 u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
 221 void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
 222                    u32 val);
 223         </programlisting>
 224
 225         <para>
 226         Read and write standard SATA phy registers.  Currently only used
 227         if ->phy_reset hook called the sata_phy_reset() helper function.
 228         </para>
 229
 230         <programlisting>
 231 int (*port_start) (struct ata_port *ap);
 232 void (*port_stop) (struct ata_port *ap);
 233 void (*host_stop) (struct ata_host_set *host_set);
 234         </programlisting>
 235
 236         <para>
 237         ->port_start() is called just after the data structures for each
 238         port are initialized.  Typically this is used to alloc per-port
 239         DMA buffers / tables / rings, enable DMA engines, and similar
 240         tasks.
 241         </para>
 242         <para>
 243         ->host_stop() is called when the rmmod or hot unplug process
 244         begins.  The hook must stop all hardware interrupts, DMA
 245         engines, etc.
 246         </para>
 247         <para>
 248         ->port_stop() is called after ->host_stop().  It's sole function
 249         is to release DMA/memory resources, now that they are no longer
 250         actively being used.
 251         </para>
 252
 253      </sect1>
 254   </chapter>
 255
 256   <chapter id="libataExt">
 257      <title>libata Library</title>
 258 !Edrivers/scsi/libata-core.c
 259   </chapter>
 260
 261   <chapter id="libataInt">
 262      <title>libata Core Internals</title>
 263 !Idrivers/scsi/libata-core.c
 264   </chapter>
 265
 266   <chapter id="libataScsiInt">
 267      <title>libata SCSI translation/emulation</title>
 268 !Edrivers/scsi/libata-scsi.c
 269 !Idrivers/scsi/libata-scsi.c
 270   </chapter>
 271
 272   <chapter id="PiixInt">
 273      <title>ata_piix Internals</title>
 274 !Idrivers/scsi/ata_piix.c
 275   </chapter>
 276
 277   <chapter id="SILInt">
 278      <title>sata_sil Internals</title>
 279 !Idrivers/scsi/sata_sil.c
 280   </chapter>
 281
 282 </book>