diff options
| -rw-r--r-- | Documentation/DocBook/libata.tmpl | 58 | ||||
| -rw-r--r-- | drivers/scsi/libata-core.c | 57 |
2 files changed, 83 insertions, 32 deletions
diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index 773ae9fd99dc..41053aed41f4 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -14,7 +14,7 @@ </authorgroup> <copyright> - <year>2003</year> + <year>2003-2005</year> <holder>Jeff Garzik</holder> </copyright> @@ -145,14 +145,25 @@ void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); </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> 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> <para> - Reads the Status ATA shadow register from hardware. On some - hardware, this has the side effect of clearing the interrupt - condition. + Reads the Status/AltStatus/Error ATA shadow register from + hardware. On some hardware, reading the Status register has + the side effect of clearing the interrupt condition. </para> <programlisting> @@ -162,7 +173,8 @@ void (*dev_select)(struct ata_port *ap, unsigned int device); <para> Issues the low-level hardware command(s) that causes one of N 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> <programlisting> @@ -180,12 +192,20 @@ void (*phy_reset) (struct ata_port *ap); <programlisting> void (*bmdma_setup) (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> <para> - When setting up an IDE BMDMA transaction, these hooks arm - (->bmdma_setup) and fire (->bmdma_start) the hardware's DMA - engine. +When setting up an IDE BMDMA transaction, these hooks arm +(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) +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> <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 and S/G tables have been prepared. IDE BMDMA drivers use the helper function ata_qc_issue_prot() for taskfile protocol-based - dispatch. More advanced drivers roll their own ->qc_issue - implementation, using this as the "issue new ATA command to - hardware" hook. + dispatch. More advanced drivers implement their own ->qc_issue. </para> <programlisting> @@ -215,8 +233,10 @@ void (*eng_timeout) (struct ata_port *ap); </programlisting> <para> - This is a high level error handling function, called from the - error handling thread, when a command times out. +This is a high level error handling function, called from the +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> <programlisting> @@ -255,15 +275,15 @@ void (*host_stop) (struct ata_host_set *host_set); tasks. </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 is to release DMA/memory resources, now that they are no longer actively being used. </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> </chapter> diff --git a/drivers/scsi/libata-core.c b/drivers/scsi/libata-core.c index 63d3f70d06e1..4d707d06a5d1 100644 --- a/drivers/scsi/libata-core.c +++ b/drivers/scsi/libata-core.c @@ -1241,10 +1241,14 @@ void ata_port_probe(struct ata_port *ap) } /** - * __sata_phy_reset - - * @ap: + * __sata_phy_reset - Wake/reset a low-level SATA PHY + * @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) @@ -1289,10 +1293,13 @@ void __sata_phy_reset(struct ata_port *ap) } /** - * __sata_phy_reset - - * @ap: + * sata_phy_reset - Reset SATA bus. + * @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) @@ -1304,10 +1311,16 @@ void sata_phy_reset(struct ata_port *ap) } /** - * ata_port_disable - - * @ap: + * ata_port_disable - Disable port. + * @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) @@ -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 * @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) @@ -1467,7 +1482,10 @@ err_out: * @tmout_pat: impatience 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 - * @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 * @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) @@ -1981,7 +2002,11 @@ static void ata_sg_clean(struct ata_queued_cmd *qc) * ata_fill_sg - Fill PCI IDE PRD table * @qc: Metadata associated with taskfile to be transferred * + * Fill PCI IDE PRD (scatter-gather) table with segments + * associated with the current disk command. + * * LOCKING: + * spin_lock_irqsave(host_set lock) * */ 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 * @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: * RETURNS: 0 when ATAPI DMA can be used * nonzero otherwise @@ -2046,6 +2075,8 @@ int ata_check_atapi_dma(struct ata_queued_cmd *qc) * ata_qc_prep - Prepare taskfile for submission * @qc: Metadata associated with taskfile to be prepared * + * Prepare ATA taskfile for submission. + * * LOCKING: * spin_lock_irqsave(host_set lock) */ |