path: root/Documentation/DocBook/libata.tmpl

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<book id="libataDevGuide">
 <bookinfo>
  <title>libATA Developer's Guide</title>
  
  <authorgroup>
   <author>
    <firstname>Jeff</firstname>
    <surname>Garzik</surname>
   </author>
  </authorgroup>

  <copyright>
   <year>2003-2005</year>
   <holder>Jeff Garzik</holder>
  </copyright>

  <legalnotice>
   <para>
   The contents of this file are subject to the Open
   Software License version 1.1 that can be found at
   <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
   by reference.
   </para>

   <para>
   Alternatively, the contents of this file may be used under the terms
   of the GNU General Public License version 2 (the "GPL") as distributed
   in the kernel source COPYING file, in which case the provisions of
   the GPL are applicable instead of the above.  If you wish to allow
   the use of your version of this file only under the terms of the
   GPL and not to allow others to use your version of this file under
   the OSL, indicate your decision by deleting the provisions above and
   replace them with the notice and other provisions required by the GPL.
   If you do not delete the provisions above, a recipient may use your
   version of this file under either the OSL or the GPL.
   </para>

  </legalnotice>
 </bookinfo>

<toc></toc>

  <chapter id="libataIntroduction">
     <title>Introduction</title>
  <para>
  libATA is a library used inside the Linux kernel to support ATA host
  controllers and devices.  libATA provides an ATA driver API, class
  transports for ATA and ATAPI devices, and SCSI&lt;-&gt;ATA translation
  for ATA devices according to the T10 SAT specification.
  </para>
  <para>
  This Guide documents the libATA driver API, library functions, library
  internals, and a couple sample ATA low-level drivers.
  </para>
  </chapter>

  <chapter id="libataDriverApi">
     <title>libata Driver API</title>
     <para>
     struct ata_port_operations is defined for every low-level libata
     hardware driver, and it controls how the low-level driver
     interfaces with the ATA and SCSI layers.
     </para>
     <para>
     FIS-based drivers will hook into the system with ->qc_prep() and
     ->qc_issue() high-level hooks.  Hardware which behaves in a manner
     similar to PCI IDE hardware may utilize several generic helpers,
     defining at a bare minimum the bus I/O addresses of the ATA shadow
     register blocks.
     </para>
     <sect1>
        <title>struct ata_port_operations</title>

	<sect2><title>Disable ATA port</title>
	<programlisting>
void (*port_disable) (struct ata_port *);
	</programlisting>

	<para>
	Called from ata_bus_probe() and ata_bus_reset() error paths,
	as well as when unregistering from the SCSI module (rmmod, hot
	unplug).
	This function should do whatever needs to be done to take the
	port out of use.  In most cases, ata_port_disable() can be used
	as this hook.
	</para>
	<para>
	Called from ata_bus_probe() on a failed probe.
	Called from ata_bus_reset() on a failed bus reset.
	Called from ata_scsi_release().
	</para>

	</sect2>

	<sect2><title>Post-IDENTIFY device configuration</title>
	<programlisting>
void (*dev_config) (struct ata_port *, struct ata_device *);
	</programlisting>

	<para>
	Called after IDENTIFY [PACKET] DEVICE is issued to each device
	found.  Typically used to apply device-specific fixups prior to
	issue of SET FEATURES - XFER MODE, and prior to operation.
	</para>
	<para>
	Called by ata_device_add() after ata_dev_identify() determines
	a device is present.
	</para>
	<para>
	This entry may be specified as NULL in ata_port_operations.
	</para>

	</sect2>

	<sect2><title>Set PIO/DMA mode</title>
	<programlisting>
void (*set_piomode) (struct ata_port *, struct ata_device *);
void (*set_dmamode) (struct ata_port *, struct ata_device *);
void (*post_set_mode) (struct ata_port *);
unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int);
	</programlisting>

	<para>
	Hooks called prior to the issue of SET FEATURES - XFER MODE
	command.  The optional ->mode_filter() hook is called when libata
	has built a mask of the possible modes. This is passed to the 
	->mode_filter() function which should return a mask of valid modes
	after filtering those unsuitable due to hardware limits. It is not
	valid to use this interface to add modes.
	</para>
	<para>
	dev->pio_mode and dev->dma_mode are guaranteed to be valid when
	->set_piomode() and when ->set_dmamode() is called. The timings for
	any other drive sharing the cable will also be valid at this point.
	That is the library records the decisions for the modes of each
	drive on a channel before it attempts to set any of them.
	</para>
	<para>
	->post_set_mode() is
	called unconditionally, after the SET FEATURES - XFER MODE
	command completes successfully.
	</para>

	<para>
	->set_piomode() is always called (if present), but
	->set_dma_mode() is only called if DMA is possible.
	</para>

	</sect2>

	<sect2><title>Taskfile read/write</title>
	<programlisting>
void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
	</programlisting>

	<para>
	->tf_load() is called to load the given taskfile into hardware
	registers / DMA buffers.  ->tf_read() is called to read the
	hardware registers / DMA buffers, to obtain the current set of
	taskfile register values.
	Most drivers for taskfile-based hardware (PIO or MMIO) use
	ata_t