err.no Git - linux-2.6/blob - 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-2005</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="libataIntroduction">
  48      <title>Introduction</title>
  49   <para>
  50   libATA is a library used inside the Linux kernel to support ATA host
  51   controllers and devices.  libATA provides an ATA driver API, class
  52   transports for ATA and ATAPI devices, and SCSI&lt;-&gt;ATA translation
  53   for ATA devices according to the T10 SAT specification.
  54   </para>
  55   <para>
  56   This Guide documents the libATA driver API, library functions, library
  57   internals, and a couple sample ATA low-level drivers.
  58   </para>
  59   </chapter>
  60
  61   <chapter id="libataThanks">
  62      <title>Thanks</title>
  63   <para>
  64   The bulk of the ATA knowledge comes thanks to long conversations with
  65   Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA
  66   and SCSI specifications.
  67   </para>
  68   <para>
  69   Thanks to Alan Cox for pointing out similarities
  70   between SATA and SCSI, and in general for motivation to hack on
  71   libata.
  72   </para>
  73   <para>
  74   libata's device detection
  75   method, ata_pio_devchk, and in general all the early probing was
  76   based on extensive study of Hale Landis's probe/reset code in his
  77   ATADRVR driver (www.ata-atapi.com).
  78   </para>
  79   </chapter>
  80
  81   <chapter id="libataDriverApi">
  82      <title>libata Driver API</title>
  83      <sect1>
  84         <title>struct ata_port_operations</title>
  85
  86         <programlisting>
  87 void (*port_disable) (struct ata_port *);
  88         </programlisting>
  89
  90         <para>
  91         Called from ata_bus_probe() and ata_bus_reset() error paths,
  92         as well as when unregistering from the SCSI module (rmmod, hot
  93         unplug).
  94         </para>
  95
  96         <programlisting>
  97 void (*dev_config) (struct ata_port *, struct ata_device *);
  98         </programlisting>
  99
 100         <para>
 101         Called after IDENTIFY [PACKET] DEVICE is issued to each device
 102         found.  Typically used to apply device-specific fixups prior to
 103         issue of SET FEATURES - XFER MODE, and prior to operation.
 104         </para>
 105
 106         <programlisting>
 107 void (*set_piomode) (struct ata_port *, struct ata_device *);
 108 void (*set_dmamode) (struct ata_port *, struct ata_device *);
 109 void (*post_set_mode) (struct ata_port *ap);
 110         </programlisting>
 111
 112         <para>
 113         Hooks called prior to the issue of SET FEATURES - XFER MODE
 114         command.  dev->pio_mode is guaranteed to be valid when
 115         ->set_piomode() is called, and dev->dma_mode is guaranteed to be
 116         valid when ->set_dmamode() is called.  ->post_set_mode() is
 117         called unconditionally, after the SET FEATURES - XFER MODE
 118         command completes successfully.
 119         </para>
 120
 121         <para>
 122         ->set_piomode() is always called (if present), but
 123         ->set_dma_mode() is only called if DMA is possible.
 124         </para>
 125
 126         <programlisting>
 127 void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
 128 void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
 129         </programlisting>
 130
 131         <para>
 132         ->tf_load() is called to load the given taskfile into hardware
 133         registers / DMA buffers.  ->tf_read() is called to read the
 134         hardware registers / DMA buffers, to obtain the current set of
 135         taskfile register values.
 136         </para>
 137
 138         <programlisting>
 139 void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
 140         </programlisting>
 141
 142         <para>
 143         causes an ATA command, previously loaded with
 144         ->tf_load(), to be initiated in hardware.
 145         </para>
 146
 147         <programlisting>
 148 int (*check_atapi_dma) (struct ata_queued_cmd *qc);
 149         </programlisting>
 150
 151         <para>
 152 Allow low-level driver to filter ATA PACKET commands, returning a status
 153 indicating whether or not it is OK to use DMA for the supplied PACKET
 154 command.
 155         </para>
 156
 157         <programlisting>
 158 u8   (*check_status)(struct ata_port *ap);
 159 u8   (*check_altstatus)(struct ata_port *ap);
 160 u8   (*check_err)(struct ata_port *ap);
 161         </programlisting>
 162
 163         <para>
 164         Reads the Status/AltStatus/Error ATA shadow register from
 165         hardware.  On some hardware, reading the Status register has
 166         the side effect of clearing the interrupt condition.
 167         </para>
 168
 169         <programlisting>
 170 void (*dev_select)(struct ata_port *ap, unsigned int device);
 171         </programlisting>
 172
 173         <para>
 174         Issues the low-level hardware command(s) that causes one of N
 175         hardware devices to be considered 'selected' (active and
 176         available for use) on the ATA bus.  This generally has no
 177 meaning on FIS-based devices.
 178         </para>
 179
 180         <programlisting>
 181 void (*phy_reset) (struct ata_port *ap);
 182         </programlisting>
 183
 184         <para>
 185         The very first step in the probe phase.  Actions vary depending
 186         on the bus type, typically.  After waking up the device and probing
 187         for device presence (PATA and SATA), typically a soft reset
 188         (SRST) will be performed.  Drivers typically use the helper
 189         functions ata_bus_reset() or sata_phy_reset() for this hook.
 190         </para>
 191
 192         <programlisting>
 193 void (*bmdma_setup) (struct ata_queued_cmd *qc);
 194 void (*bmdma_start) (struct ata_queued_cmd *qc);
 195 void (*bmdma_stop) (struct ata_port *ap);
 196 u8   (*bmdma_status) (struct ata_port *ap);
 197         </programlisting>
 198
 199         <para>
 200 When setting up an IDE BMDMA transaction, these hooks arm
 201 (->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop)
 202 the hardware's DMA engine.  ->bmdma_status is used to read the standard
 203 PCI IDE DMA Status register.
 204         </para>
 205
 206         <para>
 207 These hooks are typically either no-ops, or simply not implemented, in
 208 FIS-based drivers.
 209         </para>
 210
 211         <programlisting>
 212 void (*qc_prep) (struct ata_queued_cmd *qc);
 213 int (*qc_issue) (struct ata_queued_cmd *qc);
 214         </programlisting>
 215
 216         <para>
 217         Higher-level hooks, these two hooks can potentially supercede
 218         several of the above taskfile/DMA engine hooks.  ->qc_prep is
 219         called after the buffers have been DMA-mapped, and is typically
 220         used to populate the hardware's DMA scatter-gather table.
 221         Most drivers use the standard ata_qc_prep() helper function, but
 222         more advanced drivers roll their own.
 223         </para>
 224         <para>
 225         ->qc_issue is used to make a command active, once the hardware
 226         and S/G tables have been prepared.  IDE BMDMA drivers use the
 227         helper function ata_qc_issue_prot() for taskfile protocol-based
 228         dispatch.  More advanced drivers implement their own ->qc_issue.
 229         </para>
 230
 231         <programlisting>
 232 void (*eng_timeout) (struct ata_port *ap);
 233         </programlisting>
 234
 235         <para>
 236 This is a high level error handling function, called from the
 237 error handling thread, when a command times out.  Most newer
 238 hardware will implement its own error handling code here.  IDE BMDMA
 239 drivers may use the helper function ata_eng_timeout().
 240         </para>
 241
 242         <programlisting>
 243 irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
 244 void (*irq_clear) (struct ata_port *);
 245         </programlisting>
 246
 247         <para>
 248         ->irq_handler is the interrupt handling routine registered with
 249         the system, by libata.  ->irq_clear is called during probe just
 250         before the interrupt handler is registered, to be sure hardware
 251         is quiet.
 252         </para>
 253
 254         <programlisting>
 255 u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
 256 void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
 257                    u32 val);
 258         </programlisting>
 259
 260         <para>
 261         Read and write standard SATA phy registers.  Currently only used
 262         if ->phy_reset hook called the sata_phy_reset() helper function.
 263         </para>
 264
 265         <programlisting>
 266 int (*port_start) (struct ata_port *ap);
 267 void (*port_stop) (struct ata_port *ap);
 268 void (*host_stop) (struct ata_host_set *host_set);
 269         </programlisting>
 270
 271         <para>
 272         ->port_start() is called just after the data structures for each
 273         port are initialized.  Typically this is used to alloc per-port
 274         DMA buffers / tables / rings, enable DMA engines, and similar
 275         tasks.
 276         </para>
 277         <para>
 278         ->port_stop() is called after ->host_stop().  It's sole function
 279         is to release DMA/memory resources, now that they are no longer
 280         actively being used.
 281         </para>
 282         <para>
 283         ->host_stop() is called after all ->port_stop() calls
 284 have completed.  The hook must finalize hardware shutdown, release DMA
 285 and other resources, etc.
 286         </para>
 287
 288      </sect1>
 289   </chapter>
 290
 291   <chapter id="libataExt">
 292      <title>libata Library</title>
 293 !Edrivers/scsi/libata-core.c
 294   </chapter>
 295
 296   <chapter id="libataInt">
 297      <title>libata Core Internals</title>
 298 !Idrivers/scsi/libata-core.c
 299   </chapter>
 300
 301   <chapter id="libataScsiInt">
 302      <title>libata SCSI translation/emulation</title>
 303 !Edrivers/scsi/libata-scsi.c
 304 !Idrivers/scsi/libata-scsi.c
 305   </chapter>
 306
 307   <chapter id="PiixInt">
 308      <title>ata_piix Internals</title>
 309 !Idrivers/scsi/ata_piix.c
 310   </chapter>
 311
 312   <chapter id="SILInt">
 313      <title>sata_sil Internals</title>
 314 !Idrivers/scsi/sata_sil.c
 315   </chapter>
 316
 317 </book>