bk://gkernel.bkbits.net/libata-2.6 jgarzik@pobox.com|ChangeSet|20041117172158|21710 jgarzik # This is a BitKeeper generated diff -Nru style patch. # # ChangeSet # 2004/11/17 12:21:58-05:00 jgarzik@pobox.com # [libata docs] add chapter on libata driver API # # Documentation/DocBook/libata.tmpl # 2004/11/17 12:21:52-05:00 jgarzik@pobox.com +191 -1 # [libata docs] add chapter on libata driver API # # ChangeSet # 2004/11/16 19:01:52-05:00 jgarzik@pobox.com # [libata ahci] minor fixes # # Add support for ioctl handling. # Remove incorrect comment. # # drivers/scsi/ahci.c # 2004/11/16 19:01:47-05:00 jgarzik@pobox.com +1 -4 # [libata ahci] minor fixes # # Add support for ioctl handling. # Remove incorrect comment. # # ChangeSet # 2004/11/15 00:17:15-05:00 jgarzik@pobox.com # [libata] fix DocBook bugs # # drivers/scsi/libata-scsi.c # 2004/11/15 00:17:09-05:00 jgarzik@pobox.com +3 -1 # [libata] fix DocBook bugs # # drivers/scsi/libata-core.c # 2004/11/15 00:17:09-05:00 jgarzik@pobox.com +6 -4 # [libata] fix DocBook bugs # diff -Nru a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl --- a/Documentation/DocBook/libata.tmpl 2004-11-17 19:36:57 -08:00 +++ b/Documentation/DocBook/libata.tmpl 2004-11-17 19:36:57 -08:00 @@ -61,6 +61,196 @@ + + libata Driver API + + struct ata_port_operations + + +void (*port_disable) (struct ata_port *); + + + + Called from ata_bus_probe() and ata_bus_reset() error paths, + as well as when unregistering from the SCSI module (rmmod, hot + unplug). + + + +void (*dev_config) (struct ata_port *, struct ata_device *); + + + + Called after IDENTIFY [PACKET] DEVICE is issued to each device + found. Typically used to apply device-specific fixups prior to + issue of SET FEATURES - XFER MODE, and prior to operation. + + + +void (*set_piomode) (struct ata_port *, struct ata_device *); +void (*set_dmamode) (struct ata_port *, struct ata_device *); +void (*post_set_mode) (struct ata_port *ap); + + + + Hooks called prior to the issue of SET FEATURES - XFER MODE + command. dev->pio_mode is guaranteed to be valid when + ->set_piomode() is called, and dev->dma_mode is guaranteed to be + valid when ->set_dmamode() is called. ->post_set_mode() is + called unconditionally, after the SET FEATURES - XFER MODE + command completes successfully. + + + + ->set_piomode() is always called (if present), but + ->set_dma_mode() is only called if DMA is possible. + + + +void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf); +void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf); + + + + ->tf_load() is called to load the given taskfile into hardware + registers / DMA buffers. ->tf_read() is called to read the + hardware registers / DMA buffers, to obtain the current set of + taskfile register values. + + + +void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); + + + + causes an ATA command, previously loaded with + ->tf_load(), to be initiated in hardware. + + + +u8 (*check_status)(struct ata_port *ap); +void (*dev_select)(struct ata_port *ap, unsigned int device); + + + + Reads the Status ATA shadow register from hardware. On some + hardware, this has the side effect of clearing the interrupt + condition. + + + +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. + + + +void (*phy_reset) (struct ata_port *ap); + + + + The very first step in the probe phase. Actions vary depending + on the bus type, typically. After waking up the device and probing + for device presence (PATA and SATA), typically a soft reset + (SRST) will be performed. Drivers typically use the helper + functions ata_bus_reset() or sata_phy_reset() for this hook. + + + +void (*bmdma_setup) (struct ata_queued_cmd *qc); +void (*bmdma_start) (struct ata_queued_cmd *qc); + + + + When setting up an IDE BMDMA transaction, these hooks arm + (->bmdma_setup) and fire (->bmdma_start) the hardware's DMA + engine. + + + +void (*qc_prep) (struct ata_queued_cmd *qc); +int (*qc_issue) (struct ata_queued_cmd *qc); + + + + Higher-level hooks, these two hooks can potentially supercede + several of the above taskfile/DMA engine hooks. ->qc_prep is + called after the buffers have been DMA-mapped, and is typically + used to populate the hardware's DMA scatter-gather table. + Most drivers use the standard ata_qc_prep() helper function, but + more advanced drivers roll their own. + + + ->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. + + + +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. + + + +irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); +void (*irq_clear) (struct ata_port *); + + + + ->irq_handler is the interrupt handling routine registered with + the system, by libata. ->irq_clear is called during probe just + before the interrupt handler is registered, to be sure hardware + is quiet. + + + +u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg); +void (*scr_write) (struct ata_port *ap, unsigned int sc_reg, + u32 val); + + + + Read and write standard SATA phy registers. Currently only used + if ->phy_reset hook called the sata_phy_reset() helper function. + + + +int (*port_start) (struct ata_port *ap); +void (*port_stop) (struct ata_port *ap); +void (*host_stop) (struct ata_host_set *host_set); + + + + ->port_start() is called just after the data structures for each + port are initialized. Typically this is used to alloc per-port + DMA buffers / tables / rings, enable DMA engines, and similar + 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. + + + + + libata Library !Edrivers/scsi/libata-core.c @@ -83,7 +273,7 @@ - ata_sil Internals + sata_sil Internals !Idrivers/scsi/sata_sil.c diff -Nru a/drivers/scsi/ahci.c b/drivers/scsi/ahci.c --- a/drivers/scsi/ahci.c 2004-11-17 19:36:57 -08:00 +++ b/drivers/scsi/ahci.c 2004-11-17 19:36:57 -08:00 @@ -184,6 +184,7 @@ static Scsi_Host_Template ahci_sht = { .module = THIS_MODULE, .name = DRV_NAME, + .ioctl = ata_scsi_ioctl, .queuecommand = ata_scsi_queuecmd, .eh_strategy_handler = ata_scsi_error, .can_queue = ATA_DEF_QUEUE, @@ -944,10 +945,6 @@ if (!printed_version++) printk(KERN_DEBUG DRV_NAME " version " DRV_VERSION "\n"); - /* - * If this driver happens to only be useful on Apple's K2, then - * we should check that here as it has a normal Serverworks ID - */ rc = pci_enable_device(pdev); if (rc) return rc; diff -Nru a/drivers/scsi/libata-core.c b/drivers/scsi/libata-core.c --- a/drivers/scsi/libata-core.c 2004-11-17 19:36:57 -08:00 +++ b/drivers/scsi/libata-core.c 2004-11-17 19:36:57 -08:00 @@ -582,7 +582,7 @@ /** * ata_udma_string - convert UDMA bit offset to string - * @udma_mask: mask of bits supported; only highest bit counts. + * @mask: mask of bits supported; only highest bit counts. * * Determine string which represents the highest speed * (highest bit in @udma_mask). @@ -819,7 +819,7 @@ /** * ata_dev_id_string - Convert IDENTIFY DEVICE page into string - * @dev: Device whose IDENTIFY DEVICE results we will examine + * @id: IDENTIFY DEVICE results we will examine * @s: string into which data is output * @ofs: offset into identify device page * @len: length of string to return. must be an even number. @@ -1766,8 +1766,10 @@ } /** - * ata_choose_xfer_mode - - * @ap: + * ata_choose_xfer_mode - attempt to find best transfer mode + * @ap: Port for which an xfer mode will be selected + * @xfer_mode_out: (output) SET FEATURES - XFER MODE code + * @xfer_shift_out: (output) bit shift that selects this mode * * LOCKING: * diff -Nru a/drivers/scsi/libata-scsi.c b/drivers/scsi/libata-scsi.c --- a/drivers/scsi/libata-scsi.c 2004-11-17 19:36:57 -08:00 +++ b/drivers/scsi/libata-scsi.c 2004-11-17 19:36:57 -08:00 @@ -156,6 +156,7 @@ /** * ata_to_sense_error - convert ATA error to SCSI error * @qc: Command that we are erroring out + * @drv_stat: value contained in ATA status register * * Converts an ATA error into a SCSI error. While we are at it * we decode and dump the ATA error for the user so that they @@ -735,6 +736,7 @@ /** * ata_scsi_rbuf_put - Unmap response buffer. * @cmd: SCSI command containing buffer to be unmapped. + * @buf: buffer to unmap * * Unmaps response buffer contained within @cmd. * @@ -1334,7 +1336,7 @@ /** * ata_scsi_find_dev - lookup ata_device from scsi_cmnd * @ap: ATA port to which the device is attached - * @cmd: SCSI command to be sent to the device + * @scsidev: SCSI device from which we derive the ATA device * * Given various information provided in struct scsi_cmnd, * map that onto an ATA bus, and using that mapping