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