From 780a87f71841932db8dbb0f1eb9daf3a973a6bd6 Mon Sep 17 00:00:00 2001 From: Jeff Garzik Date: Mon, 30 May 2005 15:41:05 -0400 Subject: [PATCH] libata: more doc updates Document recently-added ata_port_operations hooks. Fill several doc stubs in libata-core.c. --- Documentation/DocBook/libata.tmpl | 60 ++++++++++++++++++++----------- drivers/scsi/libata-core.c | 57 ++++++++++++++++++++++------- 2 files changed, 84 insertions(+), 33 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 @@ - 2003 + 2003-2005 Jeff Garzik @@ -145,14 +145,25 @@ void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); -u8 (*check_status)(struct ata_port *ap); -void (*dev_select)(struct ata_port *ap, unsigned int device); +int (*check_atapi_dma) (struct ata_queued_cmd *qc); - Reads the Status ATA shadow register from hardware. On some - hardware, this has the side effect of clearing the interrupt - condition. +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. + + + +u8 (*check_status)(struct ata_port *ap); +u8 (*check_altstatus)(struct ata_port *ap); +u8 (*check_err)(struct ata_port *ap); + + + + 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. @@ -162,7 +173,8 @@ void (*dev_select)(struct ata_port *ap, unsigned int device); 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. @@ -180,12 +192,20 @@ void (*phy_reset) (struct ata_port *ap); 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); - 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. + + + +These hooks are typically either no-ops, or simply not implemented, in +FIS-based drivers. @@ -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. @@ -215,8 +233,10 @@ void (*eng_timeout) (struct ata_port *ap); - 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(). @@ -255,15 +275,15 @@ void (*host_stop) (struct ata_host_set *host_set); tasks. - ->host_stop() is called when the rmmod or hot unplug process - begins. The hook must stop all hardware interrupts, DMA - engines, etc. - - ->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. + + ->host_stop() is called after all ->port_stop() calls +have completed. The hook must finalize hardware shutdown, release DMA +and other resources, etc. + 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 @@ static void ata_set_mode(struct ata_port *ap) * @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) */