Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 780a87f7 authored by Jeff Garzik's avatar Jeff Garzik
Browse files

libata: more doc updates 

Document recently-added ata_port_operations hooks.

Fill several doc stubs in libata-core.c.
parent 07dd39b9

Documentation/DocBook/libata.tmpl

+39 −19
Original line number Original line Diff line number Diff line
@@ -14,7 +14,7 @@ 
  </authorgroup>

  </authorgroup>





  <copyright>

  <copyright>

   <year>2003</year>

   <year>2003-2005</year>

   <holder>Jeff Garzik</holder>

   <holder>Jeff Garzik</holder>

  </copyright>

  </copyright>
@@ -144,15 +144,26 @@ void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); 
	->tf_load(), to be initiated in hardware.

	->tf_load(), to be initiated in hardware.

	</para>

	</para>





	<programlisting>

int (*check_atapi_dma) (struct ata_queued_cmd *qc);

	</programlisting>



	<para>

Allow low-level driver to filter ATA PACKET commands, returning a status

indicating whether or not it is OK to use DMA for the supplied PACKET

command.

	</para>



	<programlisting>

	<programlisting>

u8   (*check_status)(struct ata_port *ap);

u8   (*check_status)(struct ata_port *ap);

void (*dev_select)(struct ata_port *ap, unsigned int device);

u8   (*check_altstatus)(struct ata_port *ap);

u8   (*check_err)(struct ata_port *ap);

	</programlisting>

	</programlisting>





	<para>

	<para>

	Reads the Status ATA shadow register from hardware.  On some

	Reads the Status/AltStatus/Error ATA shadow register from

	hardware, this has the side effect of clearing the interrupt

	hardware.  On some hardware, reading the Status register has

	condition.

	the side effect of clearing the interrupt condition.

	</para>

	</para>





	<programlisting>

	<programlisting>
@@ -162,7 +173,8 @@ void (*dev_select)(struct ata_port *ap, unsigned int device); 
	<para>

	<para>

	Issues the low-level hardware command(s) that causes one of N

	Issues the low-level hardware command(s) that causes one of N

	hardware devices to be considered 'selected' (active and

	hardware devices to be considered 'selected' (active and

	available for use) on the ATA bus.

	available for use) on the ATA bus.  This generally has no

meaning on FIS-based devices.

	</para>

	</para>





	<programlisting>

	<programlisting>
@@ -180,12 +192,20 @@ void (*phy_reset) (struct ata_port *ap); 
	<programlisting>

	<programlisting>

void (*bmdma_setup) (struct ata_queued_cmd *qc);

void (*bmdma_setup) (struct ata_queued_cmd *qc);

void (*bmdma_start) (struct ata_queued_cmd *qc);

void (*bmdma_start) (struct ata_queued_cmd *qc);

void (*bmdma_stop) (struct ata_port *ap);

u8   (*bmdma_status) (struct ata_port *ap);

	</programlisting>

	</programlisting>





	<para>

	<para>

When setting up an IDE BMDMA transaction, these hooks arm

When setting up an IDE BMDMA transaction, these hooks arm

	(->bmdma_setup) and fire (->bmdma_start) the hardware's DMA

(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop)

	engine.

the hardware's DMA engine.  ->bmdma_status is used to read the standard

PCI IDE DMA Status register.

	</para>



	<para>

These hooks are typically either no-ops, or simply not implemented, in

FIS-based drivers.

	</para>

	</para>





	<programlisting>

	<programlisting>
@@ -205,9 +225,7 @@ int (*qc_issue) (struct ata_queued_cmd *qc); 
	->qc_issue is used to make a command active, once the hardware

	->qc_issue is used to make a command active, once the hardware

	and S/G tables have been prepared.  IDE BMDMA drivers use the

	and S/G tables have been prepared.  IDE BMDMA drivers use the

	helper function ata_qc_issue_prot() for taskfile protocol-based

	helper function ata_qc_issue_prot() for taskfile protocol-based

	dispatch.  More advanced drivers roll their own ->qc_issue

	dispatch.  More advanced drivers implement their own ->qc_issue.

	implementation, using this as the "issue new ATA command to

	hardware" hook.

	</para>

	</para>





	<programlisting>

	<programlisting>
@@ -216,7 +234,9 @@ void (*eng_timeout) (struct ata_port *ap); 




	<para>

	<para>

This is a high level error handling function, called from the

This is a high level error handling function, called from the

	error handling thread, when a command times out.

error handling thread, when a command times out.  Most newer

hardware will implement its own error handling code here.  IDE BMDMA

drivers may use the helper function ata_eng_timeout().

	</para>

	</para>





	<programlisting>

	<programlisting>
@@ -255,15 +275,15 @@ void (*host_stop) (struct ata_host_set *host_set); 
	tasks.  

	tasks.  

	</para>

	</para>

	<para>

	<para>

	->host_stop() is called when the rmmod or hot unplug process

	begins.  The hook must stop all hardware interrupts, DMA

	engines, etc.

	</para>

	<para>

	->port_stop() is called after ->host_stop().  It's sole function

	->port_stop() is called after ->host_stop().  It's sole function

	is to release DMA/memory resources, now that they are no longer

	is to release DMA/memory resources, now that they are no longer

	actively being used.

	actively being used.

	</para>

	</para>

	<para>

	->host_stop() is called after all ->port_stop() calls

have completed.  The hook must finalize hardware shutdown, release DMA

and other resources, etc.

	</para>





     </sect1>

     </sect1>

  </chapter>

  </chapter>

drivers/scsi/libata-core.c

+44 −13
Original line number Original line Diff line number Diff line
@@ -1241,10 +1241,14 @@ void ata_port_probe(struct ata_port *ap) 
}

}





/**

/**

 *	__sata_phy_reset -

 *	__sata_phy_reset - Wake/reset a low-level SATA PHY

 *	@ap:

 *	@ap: SATA port associated with target SATA PHY.

 *

 *

 *	LOCKING:

 *	This function issues commands to standard SATA Sxxx

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

 *	clear any reset condition.

 *

 *	LOCKING: None.  Serialized during ata_bus_probe().

 *

 *

 */

 */

void __sata_phy_reset(struct ata_port *ap)

void __sata_phy_reset(struct ata_port *ap)
@@ -1289,10 +1293,13 @@ void __sata_phy_reset(struct ata_port *ap) 
}

}





/**

/**

 *	__sata_phy_reset -

 *	sata_phy_reset - Reset SATA bus.

 *	@ap:

 *	@ap: SATA port associated with target SATA PHY.

 *

 *

 *	LOCKING:

 *	This function resets the SATA bus, and then probes

 *	the bus for devices.

 *

 *	LOCKING: None.  Serialized during ata_bus_probe().

 *

 *

 */

 */

void sata_phy_reset(struct ata_port *ap)

void sata_phy_reset(struct ata_port *ap)
@@ -1304,10 +1311,16 @@ void sata_phy_reset(struct ata_port *ap) 
}

}





/**

/**

 *	ata_port_disable -

 *	ata_port_disable - Disable port.

 *	@ap:

 *	@ap: Port to be disabled.

 *

 *

 *	LOCKING:

 *	Modify @ap data structure such that the system

 *	thinks that the entire port is disabled, and should

 *	never attempt to probe or communicate with devices

 *	on this port.

 *

 *	LOCKING: host_set lock, or some other form of

 *	serialization.

 */

 */





void ata_port_disable(struct ata_port *ap)

void ata_port_disable(struct ata_port *ap)
@@ -1416,7 +1429,9 @@ static void ata_host_set_dma(struct ata_port *ap, u8 xfer_mode, 
 *	ata_set_mode - Program timings and issue SET FEATURES - XFER

 *	ata_set_mode - Program timings and issue SET FEATURES - XFER

 *	@ap: port on which timings will be programmed

 *	@ap: port on which timings will be programmed

 *

 *

 *	LOCKING:

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

 *

 *	LOCKING: None.  Serialized during ata_bus_probe().

 *

 *

 */

 */

static void ata_set_mode(struct ata_port *ap)

static void ata_set_mode(struct ata_port *ap)
@@ -1467,7 +1482,10 @@ err_out: 
 *	@tmout_pat: impatience timeout

 *	@tmout_pat: impatience timeout

 *	@tmout: overall timeout

 *	@tmout: overall timeout

 *

 *

 *	LOCKING:

 *	Sleep until ATA Status register bit BSY clears,

 *	or a timeout occurs.

 *

 *	LOCKING: None.

 *

 *

 */

 */
@@ -1556,7 +1574,7 @@ static void ata_bus_post_reset(struct ata_port *ap, unsigned int devmask) 
 *	ata_bus_edd -

 *	ata_bus_edd -

 *	@ap:

 *	@ap:

 *

 *

 *	LOCKING:

 *	LOCKING: None.  Serialized during ata_bus_probe().

 *

 *

 */

 */
@@ -1909,7 +1927,10 @@ static int ata_choose_xfer_mode(struct ata_port *ap, 
 *	@ap: Port associated with device @dev

 *	@ap: Port associated with device @dev

 *	@dev: Device to which command will be sent

 *	@dev: Device to which command will be sent

 *

 *

 *	LOCKING:

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

 *	on port @ap.

 *

 *	LOCKING: None.  Serialized during ata_bus_probe().

 */

 */





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

static void ata_dev_set_xfermode(struct ata_port *ap, struct ata_device *dev)
@@ -1981,7 +2002,11 @@ static void ata_sg_clean(struct ata_queued_cmd *qc) 
 *	ata_fill_sg - Fill PCI IDE PRD table

 *	ata_fill_sg - Fill PCI IDE PRD table

 *	@qc: Metadata associated with taskfile to be transferred

 *	@qc: Metadata associated with taskfile to be transferred

 *

 *

 *	Fill PCI IDE PRD (scatter-gather) table with segments

 *	associated with the current disk command.

 *

 *	LOCKING:

 *	LOCKING:

 *	spin_lock_irqsave(host_set lock)

 *

 *

 */

 */

static void ata_fill_sg(struct ata_queued_cmd *qc)

static void ata_fill_sg(struct ata_queued_cmd *qc)
@@ -2028,6 +2053,10 @@ static void ata_fill_sg(struct ata_queued_cmd *qc) 
 *	ata_check_atapi_dma - Check whether ATAPI DMA can be supported

 *	ata_check_atapi_dma - Check whether ATAPI DMA can be supported

 *	@qc: Metadata associated with taskfile to check

 *	@qc: Metadata associated with taskfile to check

 *

 *

 *	Allow low-level driver to filter ATA PACKET commands, returning

 *	a status indicating whether or not it is OK to use DMA for the

 *	supplied PACKET command.

 *

 *	LOCKING:

 *	LOCKING:

 *	RETURNS: 0 when ATAPI DMA can be used

 *	RETURNS: 0 when ATAPI DMA can be used

 *               nonzero otherwise

 *               nonzero otherwise
@@ -2046,6 +2075,8 @@ int ata_check_atapi_dma(struct ata_queued_cmd *qc) 
 *	ata_qc_prep - Prepare taskfile for submission

 *	ata_qc_prep - Prepare taskfile for submission

 *	@qc: Metadata associated with taskfile to be prepared

 *	@qc: Metadata associated with taskfile to be prepared

 *

 *

 *	Prepare ATA taskfile for submission.

 *

 *	LOCKING:

 *	LOCKING:

 *	spin_lock_irqsave(host_set lock)

 *	spin_lock_irqsave(host_set lock)

 */

 */