Commit 9bcb1f9f authored by Jeff Garzik's avatar Jeff Garzik

Merge pobox.com:/garz/repo/linux-2.6

into pobox.com:/garz/repo/libata-2.6
parents 37e19a48 a4a24039
...@@ -61,6 +61,196 @@ ...@@ -61,6 +61,196 @@
</para> </para>
</chapter> </chapter>
<chapter id="libataDriverApi">
<title>libata Driver API</title>
<sect1>
<title>struct ata_port_operations</title>
<programlisting>
void (*port_disable) (struct ata_port *);
</programlisting>
<para>
Called from ata_bus_probe() and ata_bus_reset() error paths,
as well as when unregistering from the SCSI module (rmmod, hot
unplug).
</para>
<programlisting>
void (*dev_config) (struct ata_port *, struct ata_device *);
</programlisting>
<para>
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.
</para>
<programlisting>
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);
</programlisting>
<para>
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.
</para>
<para>
->set_piomode() is always called (if present), but
->set_dma_mode() is only called if DMA is possible.
</para>
<programlisting>
void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
</programlisting>
<para>
->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.
</para>
<programlisting>
void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
</programlisting>
<para>
causes an ATA command, previously loaded with
->tf_load(), to be initiated in hardware.
</para>
<programlisting>
u8 (*check_status)(struct ata_port *ap);
void (*dev_select)(struct ata_port *ap, unsigned int device);
</programlisting>
<para>
Reads the Status ATA shadow register from hardware. On some
hardware, this has the side effect of clearing the interrupt
condition.
</para>
<programlisting>
void (*dev_select)(struct ata_port *ap, unsigned int device);
</programlisting>
<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.
</para>
<programlisting>
void (*phy_reset) (struct ata_port *ap);
</programlisting>
<para>
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.
</para>
<programlisting>
void (*bmdma_setup) (struct ata_queued_cmd *qc);
void (*bmdma_start) (struct ata_queued_cmd *qc);
</programlisting>
<para>
When setting up an IDE BMDMA transaction, these hooks arm
(->bmdma_setup) and fire (->bmdma_start) the hardware's DMA
engine.
</para>
<programlisting>
void (*qc_prep) (struct ata_queued_cmd *qc);
int (*qc_issue) (struct ata_queued_cmd *qc);
</programlisting>
<para>
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.
</para>
<para>
->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.
</para>
<programlisting>
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.
</para>
<programlisting>
irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
void (*irq_clear) (struct ata_port *);
</programlisting>
<para>
->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.
</para>
<programlisting>
u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
u32 val);
</programlisting>
<para>
Read and write standard SATA phy registers. Currently only used
if ->phy_reset hook called the sata_phy_reset() helper function.
</para>
<programlisting>
int (*port_start) (struct ata_port *ap);
void (*port_stop) (struct ata_port *ap);
void (*host_stop) (struct ata_host_set *host_set);
</programlisting>
<para>
->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.
</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>
</sect1>
</chapter>
<chapter id="libataExt"> <chapter id="libataExt">
<title>libata Library</title> <title>libata Library</title>
!Edrivers/scsi/libata-core.c !Edrivers/scsi/libata-core.c
...@@ -83,7 +273,7 @@ ...@@ -83,7 +273,7 @@
</chapter> </chapter>
<chapter id="SILInt"> <chapter id="SILInt">
<title>ata_sil Internals</title> <title>sata_sil Internals</title>
!Idrivers/scsi/sata_sil.c !Idrivers/scsi/sata_sil.c
</chapter> </chapter>
......
...@@ -184,6 +184,7 @@ static inline int ahci_host_intr(struct ata_port *ap, struct ata_queued_cmd *qc) ...@@ -184,6 +184,7 @@ static inline int ahci_host_intr(struct ata_port *ap, struct ata_queued_cmd *qc)
static Scsi_Host_Template ahci_sht = { static Scsi_Host_Template ahci_sht = {
.module = THIS_MODULE, .module = THIS_MODULE,
.name = DRV_NAME, .name = DRV_NAME,
.ioctl = ata_scsi_ioctl,
.queuecommand = ata_scsi_queuecmd, .queuecommand = ata_scsi_queuecmd,
.eh_strategy_handler = ata_scsi_error, .eh_strategy_handler = ata_scsi_error,
.can_queue = ATA_DEF_QUEUE, .can_queue = ATA_DEF_QUEUE,
...@@ -944,10 +945,6 @@ static int ahci_init_one (struct pci_dev *pdev, const struct pci_device_id *ent) ...@@ -944,10 +945,6 @@ static int ahci_init_one (struct pci_dev *pdev, const struct pci_device_id *ent)
if (!printed_version++) if (!printed_version++)
printk(KERN_DEBUG DRV_NAME " version " DRV_VERSION "\n"); 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); rc = pci_enable_device(pdev);
if (rc) if (rc)
return rc; return rc;
......
...@@ -582,7 +582,7 @@ static const char * xfer_mode_str[] = { ...@@ -582,7 +582,7 @@ static const char * xfer_mode_str[] = {
/** /**
* ata_udma_string - convert UDMA bit offset to string * 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 * Determine string which represents the highest speed
* (highest bit in @udma_mask). * (highest bit in @udma_mask).
...@@ -819,7 +819,7 @@ static u8 ata_dev_try_classify(struct ata_port *ap, unsigned int device) ...@@ -819,7 +819,7 @@ static u8 ata_dev_try_classify(struct ata_port *ap, unsigned int device)
/** /**
* ata_dev_id_string - Convert IDENTIFY DEVICE page into string * 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 * @s: string into which data is output
* @ofs: offset into identify device page * @ofs: offset into identify device page
* @len: length of string to return. must be an even number. * @len: length of string to return. must be an even number.
...@@ -1766,8 +1766,10 @@ static int fgb(u32 bitmap) ...@@ -1766,8 +1766,10 @@ static int fgb(u32 bitmap)
} }
/** /**
* ata_choose_xfer_mode - * ata_choose_xfer_mode - attempt to find best transfer mode
* @ap: * @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: * LOCKING:
* *
......
...@@ -156,6 +156,7 @@ struct ata_queued_cmd *ata_scsi_qc_new(struct ata_port *ap, ...@@ -156,6 +156,7 @@ struct ata_queued_cmd *ata_scsi_qc_new(struct ata_port *ap,
/** /**
* ata_to_sense_error - convert ATA error to SCSI error * ata_to_sense_error - convert ATA error to SCSI error
* @qc: Command that we are erroring out * @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 * 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 * we decode and dump the ATA error for the user so that they
...@@ -735,6 +736,7 @@ static unsigned int ata_scsi_rbuf_get(struct scsi_cmnd *cmd, u8 **buf_out) ...@@ -735,6 +736,7 @@ static unsigned int ata_scsi_rbuf_get(struct scsi_cmnd *cmd, u8 **buf_out)
/** /**
* ata_scsi_rbuf_put - Unmap response buffer. * ata_scsi_rbuf_put - Unmap response buffer.
* @cmd: SCSI command containing buffer to be unmapped. * @cmd: SCSI command containing buffer to be unmapped.
* @buf: buffer to unmap
* *
* Unmaps response buffer contained within @cmd. * Unmaps response buffer contained within @cmd.
* *
...@@ -1334,7 +1336,7 @@ static unsigned int atapi_xlat(struct ata_queued_cmd *qc, u8 *scsicmd) ...@@ -1334,7 +1336,7 @@ static unsigned int atapi_xlat(struct ata_queued_cmd *qc, u8 *scsicmd)
/** /**
* ata_scsi_find_dev - lookup ata_device from scsi_cmnd * ata_scsi_find_dev - lookup ata_device from scsi_cmnd
* @ap: ATA port to which the device is attached * @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, * Given various information provided in struct scsi_cmnd,
* map that onto an ATA bus, and using that mapping * map that onto an ATA bus, and using that mapping
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment