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