From c893a3ae49279a4ab6aa6cf594a2ec6d286e1187 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sat, 28 Jan 2006 13:15:32 -0500 Subject: [PATCH] Various libata documentation updates. This is a merger of libata docs + cleanups from Martin Waitz and me. From: Randy Dunlap From: Martin Waitz Fix libata kernel-doc comments to match code. Add some function parameters to kernel-doc. Fix some typos/spellos. Put comments in <= 80 columns. Make one DPRINTK string unique. Fix sparse cast warnings. Signed-off-by: Randy Dunlap Signed-off-by: Jeff Garzik --- drivers/scsi/ata_piix.c | 1 + drivers/scsi/libata-core.c | 60 +++++++++++++++++++------------------- drivers/scsi/libata-scsi.c | 9 +++--- 3 files changed, 36 insertions(+), 34 deletions(-) diff --git a/drivers/scsi/ata_piix.c b/drivers/scsi/ata_piix.c index 2d984b090b23..49cc4209fe16 100644 --- a/drivers/scsi/ata_piix.c +++ b/drivers/scsi/ata_piix.c @@ -630,6 +630,7 @@ static int piix_disable_ahci(struct pci_dev *pdev) /** * piix_check_450nx_errata - Check for problem 450NX setup + * @ata_dev: the PCI device to check * * Check for the present of 450NX errata #19 and errata #25. If * they are found return an error code so we can turn off DMA diff --git a/drivers/scsi/libata-core.c b/drivers/scsi/libata-core.c index b369dbd7cb23..249e67fab81f 100644 --- a/drivers/scsi/libata-core.c +++ b/drivers/scsi/libata-core.c @@ -1442,12 +1442,11 @@ static inline u8 ata_dev_knobble(const struct ata_port *ap) } /** - * ata_dev_config - Run device specific handlers and check for - * SATA->PATA bridges - * @ap: Bus - * @i: Device + * ata_dev_config - Run device specific handlers & check for SATA->PATA bridges + * @ap: Bus + * @i: Device * - * LOCKING: + * LOCKING: */ void ata_dev_config(struct ata_port *ap, unsigned int i) @@ -1794,9 +1793,9 @@ int ata_timing_compute(struct ata_device *adev, unsigned short speed, ata_timing_quantize(t, t, T, UT); /* - * Even in DMA/UDMA modes we still use PIO access for IDENTIFY, S.M.A.R.T - * and some other commands. We have to ensure that the DMA cycle timing is - * slower/equal than the fastest PIO timing. + * Even in DMA/UDMA modes we still use PIO access for IDENTIFY, + * S.M.A.R.T * and some other commands. We have to ensure that the + * DMA cycle timing is slower/equal than the fastest PIO timing. */ if (speed > XFER_PIO_4) { @@ -1805,7 +1804,7 @@ int ata_timing_compute(struct ata_device *adev, unsigned short speed, } /* - * Lenghten active & recovery time so that cycle time is correct. + * Lengthen active & recovery time so that cycle time is correct. */ if (t->act8b + t->rec8b < t->cyc8b) { @@ -1924,7 +1923,6 @@ static void ata_host_set_dma(struct ata_port *ap, u8 xfer_mode, * * LOCKING: * PCI/etc. bus probe sem. - * */ static void ata_set_mode(struct ata_port *ap) { @@ -1973,7 +1971,6 @@ static void ata_set_mode(struct ata_port *ap) * or a timeout occurs. * * LOCKING: None. - * */ unsigned int ata_busy_sleep (struct ata_port *ap, @@ -3200,7 +3197,7 @@ void ata_poll_qc_complete(struct ata_queued_cmd *qc) } /** - * ata_pio_poll - + * ata_pio_poll - poll using PIO, depending on current state * @ap: the target ata_port * * LOCKING: @@ -3307,7 +3304,7 @@ static int ata_pio_complete (struct ata_port *ap) /** - * swap_buf_le16 - swap halves of 16-words in place + * swap_buf_le16 - swap halves of 16-bit words in place * @buf: Buffer to swap * @buf_words: Number of 16-bit words in buffer. * @@ -4520,19 +4517,6 @@ static void atapi_packet_task(void *_data) } -/** - * ata_port_start - Set port up for dma. - * @ap: Port to initialize - * - * Called just after data structures for each port are - * initialized. Allocates space for PRD table. - * - * May be used as the port_start() entry in ata_port_operations. - * - * LOCKING: - * Inherited from caller. - */ - /* * Execute a 'simple' command, that only consists of the opcode 'cmd' itself, * without filling any other registers @@ -4584,6 +4568,8 @@ static int ata_start_drive(struct ata_port *ap, struct ata_device *dev) /** * ata_device_resume - wakeup a previously suspended devices + * @ap: port the device is connected to + * @dev: the device to resume * * Kick the drive back into action, by sending it an idle immediate * command and making sure its transfer mode matches between drive @@ -4606,10 +4592,11 @@ int ata_device_resume(struct ata_port *ap, struct ata_device *dev) /** * ata_device_suspend - prepare a device for suspend + * @ap: port the device is connected to + * @dev: the device to suspend * * Flush the cache on the drive, if appropriate, then issue a * standbynow command. - * */ int ata_device_suspend(struct ata_port *ap, struct ata_device *dev) { @@ -4623,6 +4610,19 @@ int ata_device_suspend(struct ata_port *ap, struct ata_device *dev) return 0; } +/** + * ata_port_start - Set port up for dma. + * @ap: Port to initialize + * + * Called just after data structures for each port are + * initialized. Allocates space for PRD table. + * + * May be used as the port_start() entry in ata_port_operations. + * + * LOCKING: + * Inherited from caller. + */ + int ata_port_start (struct ata_port *ap) { struct device *dev = ap->host_set->dev; @@ -4880,9 +4880,9 @@ int ata_device_add(const struct ata_probe_ent *ent) ap = host_set->ports[i]; - DPRINTK("ata%u: probe begin\n", ap->id); + DPRINTK("ata%u: bus probe begin\n", ap->id); rc = ata_bus_probe(ap); - DPRINTK("ata%u: probe end\n", ap->id); + DPRINTK("ata%u: bus probe end\n", ap->id); if (rc) { /* FIXME: do something useful here? @@ -4906,7 +4906,7 @@ int ata_device_add(const struct ata_probe_ent *ent) } /* probes are done, now scan each port's disk(s) */ - DPRINTK("probe begin\n"); + DPRINTK("host probe begin\n"); for (i = 0; i < count; i++) { struct ata_port *ap = host_set->ports[i]; diff --git a/drivers/scsi/libata-scsi.c b/drivers/scsi/libata-scsi.c index ab6b53349d6f..6df82934d2d6 100644 --- a/drivers/scsi/libata-scsi.c +++ b/drivers/scsi/libata-scsi.c @@ -151,7 +151,7 @@ int ata_cmd_ioctl(struct scsi_device *scsidev, void __user *arg) struct scsi_sense_hdr sshdr; enum dma_data_direction data_dir; - if (NULL == (void *)arg) + if (arg == NULL) return -EINVAL; if (copy_from_user(args, arg, sizeof(args))) @@ -201,7 +201,7 @@ int ata_cmd_ioctl(struct scsi_device *scsidev, void __user *arg) /* Need code to retrieve data from check condition? */ if ((argbuf) - && copy_to_user((void *)(arg + sizeof(args)), argbuf, argsize)) + && copy_to_user(arg + sizeof(args), argbuf, argsize)) rc = -EFAULT; error: if (argbuf) @@ -228,7 +228,7 @@ int ata_task_ioctl(struct scsi_device *scsidev, void __user *arg) u8 args[7]; struct scsi_sense_hdr sshdr; - if (NULL == (void *)arg) + if (arg == NULL) return -EINVAL; if (copy_from_user(args, arg, sizeof(args))) @@ -2533,7 +2533,8 @@ int ata_scsi_queuecmd(struct scsi_cmnd *cmd, void (*done)(struct scsi_cmnd *)) /** * ata_scsi_simulate - simulate SCSI command on ATA device - * @id: current IDENTIFY data for target device. + * @ap: port the device is connected to + * @dev: the target device * @cmd: SCSI command being sent to device. * @done: SCSI command completion function. * -- GitLab