Documentation/DocBook/libata.tmpl

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