libata: doc updates

  </para>

  </chapter>

  <chapter id="libataThanks">

     <title>Thanks</title>

  <para>

  The bulk of the ATA knowledge comes thanks to long conversations with

  Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA

  and SCSI specifications.

  </para>

  <para>

  Thanks to Alan Cox for pointing out similarities 

  between SATA and SCSI, and in general for motivation to hack on

  libata.

  </para>

  <para>

  libata's device detection

  method, ata_pio_devchk, and in general all the early probing was

  based on extensive study of Hale Landis's probe/reset code in his

  ATADRVR driver (www.ata-atapi.com).

  </para>

  </chapter>

  <chapter id="libataDriverApi">

     <title>libata Driver API</title>

     <sect1>

!Idrivers/scsi/sata_sil.c

  </chapter>

  <chapter id="libataThanks">

     <title>Thanks</title>

  <para>

  The bulk of the ATA knowledge comes thanks to long conversations with

  Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA

  and SCSI specifications.

  </para>

  <para>

  Thanks to Alan Cox for pointing out similarities 

  between SATA and SCSI, and in general for motivation to hack on

  libata.

  </para>

  <para>

  libata's device detection

  method, ata_pio_devchk, and in general all the early probing was

  based on extensive study of Hale Landis's probe/reset code in his

  ATADRVR driver (www.ata-atapi.com).

  </para>

  </chapter>

</book>

	return ata_pci_init_one(pdev, port_info, n_ports);

}

/**

 *	piix_init -

 *

 *	LOCKING:

 *

 *	RETURNS:

 *

 */

static int __init piix_init(void)

{

	int rc;

	return 0;

}

/**

 *	piix_exit -

 *

 *	LOCKING:

 *

 */

static void __exit piix_exit(void)

{

	pci_unregister_driver(&piix_pci_driver);

 *	ata_bus_probe - Reset and probe ATA bus

 *	@ap: Bus to probe

 *

 *	Master ATA bus probing function.  Initiates a hardware-dependent

 *	bus reset, then attempts to identify any devices found on

 *	the bus.

 *

 *	LOCKING:

 *	PCI/etc. bus probe sem.

 *

 *	RETURNS:

 *	Zero on success, non-zero on error.

}

/**

 *	ata_port_probe -

 *	@ap:

 *	ata_port_probe - Mark port as enabled

 *	@ap: Port for which we indicate enablement

 *

 *	LOCKING:

 *	Modify @ap data structure such that the system

 *	thinks that the entire port is enabled.

 *

 *	LOCKING: host_set lock, or some other form of

 *	serialization.

 */

void ata_port_probe(struct ata_port *ap)

 *	PHY registers, to wake up the phy (and device), and

 *	clear any reset condition.

 *

 *	LOCKING: None.  Serialized during ata_bus_probe().

 *	LOCKING:

 *	PCI/etc. bus probe sem.

 *

 */

void __sata_phy_reset(struct ata_port *ap)

 *	This function resets the SATA bus, and then probes

 *	the bus for devices.

 *

 *	LOCKING: None.  Serialized during ata_bus_probe().

 *	LOCKING:

 *	PCI/etc. bus probe sem.

 *

 */

void sata_phy_reset(struct ata_port *ap)

 *

 *	Set ATA device disk transfer mode (PIO3, UDMA6, etc.).

 *

 *	LOCKING: None.  Serialized during ata_bus_probe().

 *	LOCKING:

 *	PCI/etc. bus probe sem.

 *

 */

static void ata_set_mode(struct ata_port *ap)

}

/**

 *	ata_bus_edd -

 *	@ap:

 *	ata_bus_edd - Issue EXECUTE DEVICE DIAGNOSTIC command.

 *	@ap: Port to reset and probe

 *

 *	Use the EXECUTE DEVICE DIAGNOSTIC command to reset and

 *	probe the bus.  Not often used these days.

 *

 *	LOCKING: None.  Serialized during ata_bus_probe().

 *	LOCKING:

 *	PCI/etc. bus probe sem.

 *

 */

 *	the device is ATA or ATAPI.

 *

 *	LOCKING:

 *	Inherited from caller.  Some functions called by this function

 *	obtain the host_set lock.

 *	PCI/etc. bus probe sem.

 *	Obtains host_set lock.

 *

 *	SIDE EFFECTS:

 *	Sets ATA_FLAG_PORT_DISABLED if bus reset fails.

 *	@xfer_mode_out: (output) SET FEATURES - XFER MODE code

 *	@xfer_shift_out: (output) bit shift that selects this mode

 *

 *	Based on host and device capabilities, determine the

 *	maximum transfer mode that is amenable to all.

 *

 *	LOCKING:

 *	PCI/etc. bus probe sem.

 *

 *	RETURNS:

 *	Zero on success, negative on error.

 *	Issue SET FEATURES - XFER MODE command to device @dev

 *	on port @ap.

 *

 *	LOCKING: None.  Serialized during ata_bus_probe().

 *	LOCKING:

 *	PCI/etc. bus probe sem.

 */

static void ata_dev_set_xfermode(struct ata_port *ap, struct ata_device *dev)

}

/**

 *	ata_sg_clean -

 *	@qc:

 *	ata_sg_clean - Unmap DMA memory associated with command

 *	@qc: Command containing DMA memory to be released

 *

 *	Unmap all mapped DMA memory associated with this command.

 *

 *	LOCKING:

 *	spin_lock_irqsave(host_set lock)

 */

static void ata_sg_clean(struct ata_queued_cmd *qc)

 *	supplied PACKET command.

 *

 *	LOCKING:

 *	spin_lock_irqsave(host_set lock)

 *

 *	RETURNS: 0 when ATAPI DMA can be used

 *               nonzero otherwise

 */

	ata_fill_sg(qc);

}

/**

 *	ata_sg_init_one - Associate command with memory buffer

 *	@qc: Command to be associated

 *	@buf: Memory buffer

 *	@buflen: Length of memory buffer, in bytes.

 *

 *	Initialize the data-related elements of queued_cmd @qc

 *	to point to a single memory buffer, @buf of byte length @buflen.

 *

 *	LOCKING:

 *	spin_lock_irqsave(host_set lock)

 */

void ata_sg_init_one(struct ata_queued_cmd *qc, void *buf, unsigned int buflen)

{

	struct scatterlist *sg;

	sg->length = buflen;

}

/**

 *	ata_sg_init - Associate command with scatter-gather table.

 *	@qc: Command to be associated

 *	@sg: Scatter-gather table.

 *	@n_elem: Number of elements in s/g table.

 *

 *	Initialize the data-related elements of queued_cmd @qc

 *	to point to a scatter-gather table @sg, containing @n_elem

 *	elements.

 *

 *	LOCKING:

 *	spin_lock_irqsave(host_set lock)

 */

void ata_sg_init(struct ata_queued_cmd *qc, struct scatterlist *sg,

		 unsigned int n_elem)

{

}

/**

 *	ata_sg_setup_one -

 *	@qc:

 *	ata_sg_setup_one - DMA-map the memory buffer associated with a command.

 *	@qc: Command with memory buffer to be mapped.

 *

 *	DMA-map the memory buffer associated with queued_cmd @qc.

 *

 *	LOCKING:

 *	spin_lock_irqsave(host_set lock)

 *

 *	RETURNS:

 *

 *	Zero on success, negative on error.

 */

static int ata_sg_setup_one(struct ata_queued_cmd *qc)

}

/**

 *	ata_sg_setup -

 *	@qc:

 *	ata_sg_setup - DMA-map the scatter-gather table associated with a command.

 *	@qc: Command with scatter-gather table to be mapped.

 *

 *	DMA-map the scatter-gather table associated with queued_cmd @qc.

 *

 *	LOCKING:

 *	spin_lock_irqsave(host_set lock)

 *

 *	RETURNS:

 *	Zero on success, negative on error.

 *

 */

 *	@ap:

 *

 *	LOCKING:

 *	None.  (executing in kernel thread context)

 *

 *	RETURNS:

 *

 *	@ap:

 *

 *	LOCKING:

 *	None.  (executing in kernel thread context)

 */

static void ata_pio_complete (struct ata_port *ap)

 *	@ap:

 *

 *	LOCKING:

 *	None.  (executing in kernel thread context)

 */

static void ata_pio_block(struct ata_port *ap)

 *	transaction completed successfully.

 *

 *	LOCKING:

 *	Inherited from SCSI layer (none, can sleep)

 */

static void ata_qc_timeout(struct ata_queued_cmd *qc)

 *	@dev: Device from whom we request an available command structure

 *

 *	LOCKING:

 *	None.

 */

static struct ata_queued_cmd *ata_qc_new(struct ata_port *ap)

 *	@dev: Device from whom we request an available command structure

 *

 *	LOCKING:

 *	None.

 */

struct ata_queued_cmd *ata_qc_new_init(struct ata_port *ap,

 *	in case something prevents using it.

 *

 *	LOCKING:

 *	spin_lock_irqsave(host_set lock)

 *

 */

void ata_qc_free(struct ata_queued_cmd *qc)

/**

 *	ata_qc_complete - Complete an active ATA command

 *	@qc: Command to complete

 *	@drv_stat: ATA status register contents

 *	@drv_stat: ATA Status register contents

 *

 *	Indicate to the mid and upper layers that an ATA

 *	command has completed, with either an ok or not-ok status.

 *

 *	LOCKING:

 *	spin_lock_irqsave(host_set lock)

 *

 */

/**

 *	ata_interrupt - Default ATA host interrupt handler

 *	@irq: irq line

 *	@dev_instance: pointer to our host information structure

 *	@irq: irq line (unused)

 *	@dev_instance: pointer to our ata_host_set information structure

 *	@regs: unused

 *

 *	Default interrupt handler for PCI IDE devices.  Calls

 *	ata_host_intr() for each port that is not disabled.

 *

 *	LOCKING:

 *	Obtains host_set lock during operation.

 *

 *	RETURNS:

 *	IRQ_NONE or IRQ_HANDLED.

 *

 */

 *	@ent: Probe information provided by low-level driver

 *	@port_no: Port number associated with this ata_port

 *

 *	Initialize a new ata_port structure, and its associated

 *	scsi_host.

 *

 *	LOCKING:

 *	Inherited from caller.

 *

 */

 *	@host_set: Collections of ports to which we add

 *	@port_no: Port number associated with this host

 *

 *	Attach low-level ATA driver to system.

 *

 *	LOCKING:

 *	PCI/etc. bus probe sem.

 *

 *	RETURNS:

 *	New ata_port on success, for NULL on error.

 *

 */

}

/**

 *	ata_device_add -

 *	@ent:

 *	ata_device_add - Register hardware device with ATA and SCSI layers

 *	@ent: Probe information describing hardware device to be registered

 *

 *	This function processes the information provided in the probe

 *	information struct @ent, allocates the necessary ATA and SCSI

 *	host information structures, initializes them, and registers

 *	everything with requisite kernel subsystems.

 *

 *	This function requests irqs, probes the ATA bus, and probes

 *	the SCSI bus.

 *

 *	LOCKING:

 *	PCI/etc. bus probe sem.

 *

 *	RETURNS:

 *	Number of ports registered.  Zero on error (no ports registered).

 *

 */

 *	Inherited from PCI layer (may sleep).

 *

 *	RETURNS:

 *	Zero on success, negative on errno-based value on error.

 *

 */

#endif /* CONFIG_PCI */

/**

 *	ata_init -

 *

 *	LOCKING:

 *

 *	RETURNS:

 *

 */

static int __init ata_init(void)

{

	ata_wq = create_workqueue("ata");

}

/**

 *	ata_scsiop_noop -

 *	ata_scsiop_noop - Command handler that simply returns success.

 *	@args: device IDENTIFY data / SCSI command of interest.

 *	@rbuf: Response buffer, to which simulated SCSI cmd output is sent.

 *	@buflen: Response buffer length.