1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 2. libata Driver API</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="libATA Developer's Guide"><link rel="up" href="index.html" title="libATA Developer's Guide"><link rel="prev" href="libataIntroduction.html" title="Chapter 1. Introduction"><link rel="next" href="libataEH.html" title="Chapter 3. Error handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. libata Driver API</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="libataIntroduction.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="libataEH.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="libataDriverApi"></a>Chapter 2. libata Driver API</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="libataDriverApi.html#idp1120929892">struct ata_port_operations</a></span></dt><dd><dl><dt><span class="sect2"><a href="libataDriverApi.html#idp1120930260">Disable ATA port</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1122964388">Post-IDENTIFY device configuration</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1122965628">Set PIO/DMA mode</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120732908">Taskfile read/write</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120734212">PIO data read/write</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120735444">ATA command execute</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120736580">Per-cmd ATAPI DMA capabilities filter</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120737956">Read specific ATA shadow registers</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120739172">Write specific ATA shadow register</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120937172">Select ATA device on bus</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120938612">Private tuning method</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120940516">Control PCI IDE BMDMA engine</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120943540">High-level taskfile hooks</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120945644">Exception and probe handling (EH)</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120950892">Hardware interrupt handling</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120608052">SATA phy read/write</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120609308">Init and shutdown</a></span></dt></dl></dd></dl></div><p> 2 struct ata_port_operations is defined for every low-level libata 3 hardware driver, and it controls how the low-level driver 4 interfaces with the ATA and SCSI layers. 5 </p><p> 6 FIS-based drivers will hook into the system with ->qc_prep() and 7 ->qc_issue() high-level hooks. Hardware which behaves in a manner 8 similar to PCI IDE hardware may utilize several generic helpers, 9 defining at a bare minimum the bus I/O addresses of the ATA shadow 10 register blocks. 11 </p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1120929892"></a>struct ata_port_operations</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libataDriverApi.html#idp1120930260">Disable ATA port</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1122964388">Post-IDENTIFY device configuration</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1122965628">Set PIO/DMA mode</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120732908">Taskfile read/write</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120734212">PIO data read/write</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120735444">ATA command execute</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120736580">Per-cmd ATAPI DMA capabilities filter</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120737956">Read specific ATA shadow registers</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120739172">Write specific ATA shadow register</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120937172">Select ATA device on bus</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120938612">Private tuning method</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120940516">Control PCI IDE BMDMA engine</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120943540">High-level taskfile hooks</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120945644">Exception and probe handling (EH)</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120950892">Hardware interrupt handling</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120608052">SATA phy read/write</a></span></dt><dt><span class="sect2"><a href="libataDriverApi.html#idp1120609308">Init and shutdown</a></span></dt></dl></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120930260"></a>Disable ATA port</h3></div></div></div><pre class="programlisting"> 12void (*port_disable) (struct ata_port *); 13 </pre><p> 14 Called from ata_bus_probe() error path, as well as when 15 unregistering from the SCSI module (rmmod, hot unplug). 16 This function should do whatever needs to be done to take the 17 port out of use. In most cases, ata_port_disable() can be used 18 as this hook. 19 </p><p> 20 Called from ata_bus_probe() on a failed probe. 21 Called from ata_scsi_release(). 22 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1122964388"></a>Post-IDENTIFY device configuration</h3></div></div></div><pre class="programlisting"> 23void (*dev_config) (struct ata_port *, struct ata_device *); 24 </pre><p> 25 Called after IDENTIFY [PACKET] DEVICE is issued to each device 26 found. Typically used to apply device-specific fixups prior to 27 issue of SET FEATURES - XFER MODE, and prior to operation. 28 </p><p> 29 This entry may be specified as NULL in ata_port_operations. 30 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1122965628"></a>Set PIO/DMA mode</h3></div></div></div><pre class="programlisting"> 31void (*set_piomode) (struct ata_port *, struct ata_device *); 32void (*set_dmamode) (struct ata_port *, struct ata_device *); 33void (*post_set_mode) (struct ata_port *); 34unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int); 35 </pre><p> 36 Hooks called prior to the issue of SET FEATURES - XFER MODE 37 command. The optional ->mode_filter() hook is called when libata 38 has built a mask of the possible modes. This is passed to the 39 ->mode_filter() function which should return a mask of valid modes 40 after filtering those unsuitable due to hardware limits. It is not 41 valid to use this interface to add modes. 42 </p><p> 43 dev->pio_mode and dev->dma_mode are guaranteed to be valid when 44 ->set_piomode() and when ->set_dmamode() is called. The timings for 45 any other drive sharing the cable will also be valid at this point. 46 That is the library records the decisions for the modes of each 47 drive on a channel before it attempts to set any of them. 48 </p><p> 49 ->post_set_mode() is 50 called unconditionally, after the SET FEATURES - XFER MODE 51 command completes successfully. 52 </p><p> 53 ->set_piomode() is always called (if present), but 54 ->set_dma_mode() is only called if DMA is possible. 55 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120732908"></a>Taskfile read/write</h3></div></div></div><pre class="programlisting"> 56void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf); 57void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf); 58 </pre><p> 59 ->tf_load() is called to load the given taskfile into hardware 60 registers / DMA buffers. ->tf_read() is called to read the 61 hardware registers / DMA buffers, to obtain the current set of 62 taskfile register values. 63 Most drivers for taskfile-based hardware (PIO or MMIO) use 64 ata_sff_tf_load() and ata_sff_tf_read() for these hooks. 65 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120734212"></a>PIO data read/write</h3></div></div></div><pre class="programlisting"> 66void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int); 67 </pre><p> 68All bmdma-style drivers must implement this hook. This is the low-level 69operation that actually copies the data bytes during a PIO data 70transfer. 71Typically the driver will choose one of ata_sff_data_xfer_noirq(), 72ata_sff_data_xfer(), or ata_sff_data_xfer32(). 73 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120735444"></a>ATA command execute</h3></div></div></div><pre class="programlisting"> 74void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf); 75 </pre><p> 76 causes an ATA command, previously loaded with 77 ->tf_load(), to be initiated in hardware. 78 Most drivers for taskfile-based hardware use ata_sff_exec_command() 79 for this hook. 80 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120736580"></a>Per-cmd ATAPI DMA capabilities filter</h3></div></div></div><pre class="programlisting"> 81int (*check_atapi_dma) (struct ata_queued_cmd *qc); 82 </pre><p> 83Allow low-level driver to filter ATA PACKET commands, returning a status 84indicating whether or not it is OK to use DMA for the supplied PACKET 85command. 86 </p><p> 87 This hook may be specified as NULL, in which case libata will 88 assume that atapi dma can be supported. 89 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120737956"></a>Read specific ATA shadow registers</h3></div></div></div><pre class="programlisting"> 90u8 (*sff_check_status)(struct ata_port *ap); 91u8 (*sff_check_altstatus)(struct ata_port *ap); 92 </pre><p> 93 Reads the Status/AltStatus ATA shadow register from 94 hardware. On some hardware, reading the Status register has 95 the side effect of clearing the interrupt condition. 96 Most drivers for taskfile-based hardware use 97 ata_sff_check_status() for this hook. 98 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120739172"></a>Write specific ATA shadow register</h3></div></div></div><pre class="programlisting"> 99void (*sff_set_devctl)(struct ata_port *ap, u8 ctl); 100 </pre><p> 101 Write the device control ATA shadow register to the hardware. 102 Most drivers don't need to define this. 103 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120937172"></a>Select ATA device on bus</h3></div></div></div><pre class="programlisting"> 104void (*sff_dev_select)(struct ata_port *ap, unsigned int device); 105 </pre><p> 106 Issues the low-level hardware command(s) that causes one of N 107 hardware devices to be considered 'selected' (active and 108 available for use) on the ATA bus. This generally has no 109 meaning on FIS-based devices. 110 </p><p> 111 Most drivers for taskfile-based hardware use 112 ata_sff_dev_select() for this hook. 113 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120938612"></a>Private tuning method</h3></div></div></div><pre class="programlisting"> 114void (*set_mode) (struct ata_port *ap); 115 </pre><p> 116 By default libata performs drive and controller tuning in 117 accordance with the ATA timing rules and also applies blacklists 118 and cable limits. Some controllers need special handling and have 119 custom tuning rules, typically raid controllers that use ATA 120 commands but do not actually do drive timing. 121 </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p> 122 This hook should not be used to replace the standard controller 123 tuning logic when a controller has quirks. Replacing the default 124 tuning logic in that case would bypass handling for drive and 125 bridge quirks that may be important to data reliability. If a 126 controller needs to filter the mode selection it should use the 127 mode_filter hook instead. 128 </p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120940516"></a>Control PCI IDE BMDMA engine</h3></div></div></div><pre class="programlisting"> 129void (*bmdma_setup) (struct ata_queued_cmd *qc); 130void (*bmdma_start) (struct ata_queued_cmd *qc); 131void (*bmdma_stop) (struct ata_port *ap); 132u8 (*bmdma_status) (struct ata_port *ap); 133 </pre><p> 134When setting up an IDE BMDMA transaction, these hooks arm 135(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) 136the hardware's DMA engine. ->bmdma_status is used to read the standard 137PCI IDE DMA Status register. 138 </p><p> 139These hooks are typically either no-ops, or simply not implemented, in 140FIS-based drivers. 141 </p><p> 142Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup() 143hook. ata_bmdma_setup() will write the pointer to the PRD table to 144the IDE PRD Table Address register, enable DMA in the DMA Command 145register, and call exec_command() to begin the transfer. 146 </p><p> 147Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start() 148hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA 149Command register. 150 </p><p> 151Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop() 152hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA 153command register. 154 </p><p> 155Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook. 156 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120943540"></a>High-level taskfile hooks</h3></div></div></div><pre class="programlisting"> 157void (*qc_prep) (struct ata_queued_cmd *qc); 158int (*qc_issue) (struct ata_queued_cmd *qc); 159 </pre><p> 160 Higher-level hooks, these two hooks can potentially supercede 161 several of the above taskfile/DMA engine hooks. ->qc_prep is 162 called after the buffers have been DMA-mapped, and is typically 163 used to populate the hardware's DMA scatter-gather table. 164 Most drivers use the standard ata_qc_prep() helper function, but 165 more advanced drivers roll their own. 166 </p><p> 167 ->qc_issue is used to make a command active, once the hardware 168 and S/G tables have been prepared. IDE BMDMA drivers use the 169 helper function ata_qc_issue_prot() for taskfile protocol-based 170 dispatch. More advanced drivers implement their own ->qc_issue. 171 </p><p> 172 ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and 173 ->bmdma_start() as necessary to initiate a transfer. 174 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120945644"></a>Exception and probe handling (EH)</h3></div></div></div><pre class="programlisting"> 175void (*eng_timeout) (struct ata_port *ap); 176void (*phy_reset) (struct ata_port *ap); 177 </pre><p> 178Deprecated. Use ->error_handler() instead. 179 </p><pre class="programlisting"> 180void (*freeze) (struct ata_port *ap); 181void (*thaw) (struct ata_port *ap); 182 </pre><p> 183ata_port_freeze() is called when HSM violations or some other 184condition disrupts normal operation of the port. A frozen port 185is not allowed to perform any operation until the port is 186thawed, which usually follows a successful reset. 187 </p><p> 188The optional ->freeze() callback can be used for freezing the port 189hardware-wise (e.g. mask interrupt and stop DMA engine). If a 190port cannot be frozen hardware-wise, the interrupt handler 191must ack and clear interrupts unconditionally while the port 192is frozen. 193 </p><p> 194The optional ->thaw() callback is called to perform the opposite of ->freeze(): 195prepare the port for normal operation once again. Unmask interrupts, 196start DMA engine, etc. 197 </p><pre class="programlisting"> 198void (*error_handler) (struct ata_port *ap); 199 </pre><p> 200->error_handler() is a driver's hook into probe, hotplug, and recovery 201and other exceptional conditions. The primary responsibility of an 202implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with a set 203of EH hooks as arguments: 204 </p><p> 205'prereset' hook (may be NULL) is called during an EH reset, before any other actions 206are taken. 207 </p><p> 208'postreset' hook (may be NULL) is called after the EH reset is performed. Based on 209existing conditions, severity of the problem, and hardware capabilities, 210 </p><p> 211Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be 212called to perform the low-level EH reset. 213 </p><pre class="programlisting"> 214void (*post_internal_cmd) (struct ata_queued_cmd *qc); 215 </pre><p> 216Perform any hardware-specific actions necessary to finish processing 217after executing a probe-time or EH-time command via ata_exec_internal(). 218 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120950892"></a>Hardware interrupt handling</h3></div></div></div><pre class="programlisting"> 219irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); 220void (*irq_clear) (struct ata_port *); 221 </pre><p> 222 ->irq_handler is the interrupt handling routine registered with 223 the system, by libata. ->irq_clear is called during probe just 224 before the interrupt handler is registered, to be sure hardware 225 is quiet. 226 </p><p> 227 The second argument, dev_instance, should be cast to a pointer 228 to struct ata_host_set. 229 </p><p> 230 Most legacy IDE drivers use ata_sff_interrupt() for the 231 irq_handler hook, which scans all ports in the host_set, 232 determines which queued command was active (if any), and calls 233 ata_sff_host_intr(ap,qc). 234 </p><p> 235 Most legacy IDE drivers use ata_sff_irq_clear() for the 236 irq_clear() hook, which simply clears the interrupt and error 237 flags in the DMA status register. 238 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120608052"></a>SATA phy read/write</h3></div></div></div><pre class="programlisting"> 239int (*scr_read) (struct ata_port *ap, unsigned int sc_reg, 240 u32 *val); 241int (*scr_write) (struct ata_port *ap, unsigned int sc_reg, 242 u32 val); 243 </pre><p> 244 Read and write standard SATA phy registers. Currently only used 245 if ->phy_reset hook called the sata_phy_reset() helper function. 246 sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE. 247 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1120609308"></a>Init and shutdown</h3></div></div></div><pre class="programlisting"> 248int (*port_start) (struct ata_port *ap); 249void (*port_stop) (struct ata_port *ap); 250void (*host_stop) (struct ata_host_set *host_set); 251 </pre><p> 252 ->port_start() is called just after the data structures for each 253 port are initialized. Typically this is used to alloc per-port 254 DMA buffers / tables / rings, enable DMA engines, and similar 255 tasks. Some drivers also use this entry point as a chance to 256 allocate driver-private memory for ap->private_data. 257 </p><p> 258 Many drivers use ata_port_start() as this hook or call 259 it from their own port_start() hooks. ata_port_start() 260 allocates space for a legacy IDE PRD table and returns. 261 </p><p> 262 ->port_stop() is called after ->host_stop(). Its sole function 263 is to release DMA/memory resources, now that they are no longer 264 actively being used. Many drivers also free driver-private 265 data from port at this time. 266 </p><p> 267 ->host_stop() is called after all ->port_stop() calls 268have completed. The hook must finalize hardware shutdown, release DMA 269and other resources, etc. 270 This hook may be specified as NULL, in which case it is not called. 271 </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libataIntroduction.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="libataEH.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Error handling</td></tr></table></div></body></html> 272