Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 1 | <?xml version="1.0" encoding="UTF-8"?> |
| 2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
| 3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> |
| 4 | |
| 5 | <book id="libataDevGuide"> |
| 6 | <bookinfo> |
| 7 | <title>libATA Developer's Guide</title> |
| 8 | |
| 9 | <authorgroup> |
| 10 | <author> |
| 11 | <firstname>Jeff</firstname> |
| 12 | <surname>Garzik</surname> |
| 13 | </author> |
| 14 | </authorgroup> |
| 15 | |
| 16 | <copyright> |
| 17 | <year>2003</year> |
| 18 | <holder>Jeff Garzik</holder> |
| 19 | </copyright> |
| 20 | |
| 21 | <legalnotice> |
| 22 | <para> |
| 23 | The contents of this file are subject to the Open |
| 24 | Software License version 1.1 that can be found at |
| 25 | <ulink url="http://www.opensource.org/licenses/osl-1.1.txt">http://www.opensource.org/licenses/osl-1.1.txt</ulink> and is included herein |
| 26 | by reference. |
| 27 | </para> |
| 28 | |
| 29 | <para> |
| 30 | Alternatively, the contents of this file may be used under the terms |
| 31 | of the GNU General Public License version 2 (the "GPL") as distributed |
| 32 | in the kernel source COPYING file, in which case the provisions of |
| 33 | the GPL are applicable instead of the above. If you wish to allow |
| 34 | the use of your version of this file only under the terms of the |
| 35 | GPL and not to allow others to use your version of this file under |
| 36 | the OSL, indicate your decision by deleting the provisions above and |
| 37 | replace them with the notice and other provisions required by the GPL. |
| 38 | If you do not delete the provisions above, a recipient may use your |
| 39 | version of this file under either the OSL or the GPL. |
| 40 | </para> |
| 41 | |
| 42 | </legalnotice> |
| 43 | </bookinfo> |
| 44 | |
| 45 | <toc></toc> |
| 46 | |
| 47 | <chapter id="libataThanks"> |
| 48 | <title>Thanks</title> |
| 49 | <para> |
| 50 | The bulk of the ATA knowledge comes thanks to long conversations with |
| 51 | Andre Hedrick (www.linux-ide.org). |
| 52 | </para> |
| 53 | <para> |
| 54 | Thanks to Alan Cox for pointing out similarities |
| 55 | between SATA and SCSI, and in general for motivation to hack on |
| 56 | libata. |
| 57 | </para> |
| 58 | <para> |
| 59 | libata's device detection |
| 60 | method, ata_pio_devchk, and in general all the early probing was |
| 61 | based on extensive study of Hale Landis's probe/reset code in his |
| 62 | ATADRVR driver (www.ata-atapi.com). |
| 63 | </para> |
| 64 | </chapter> |
| 65 | |
| 66 | <chapter id="libataDriverApi"> |
| 67 | <title>libata Driver API</title> |
| 68 | <sect1> |
| 69 | <title>struct ata_port_operations</title> |
| 70 | |
| 71 | <programlisting> |
| 72 | void (*port_disable) (struct ata_port *); |
| 73 | </programlisting> |
| 74 | |
| 75 | <para> |
| 76 | Called from ata_bus_probe() and ata_bus_reset() error paths, |
| 77 | as well as when unregistering from the SCSI module (rmmod, hot |
| 78 | unplug). |
| 79 | </para> |
| 80 | |
| 81 | <programlisting> |
| 82 | void (*dev_config) (struct ata_port *, struct ata_device *); |
| 83 | </programlisting> |
| 84 | |
| 85 | <para> |
| 86 | Called after IDENTIFY [PACKET] DEVICE is issued to each device |
| 87 | found. Typically used to apply device-specific fixups prior to |
| 88 | issue of SET FEATURES - XFER MODE, and prior to operation. |
| 89 | </para> |
| 90 | |
| 91 | <programlisting> |
| 92 | void (*set_piomode) (struct ata_port *, struct ata_device *); |
| 93 | void (*set_dmamode) (struct ata_port *, struct ata_device *); |
| 94 | void (*post_set_mode) (struct ata_port *ap); |
| 95 | </programlisting> |
| 96 | |
| 97 | <para> |
| 98 | Hooks called prior to the issue of SET FEATURES - XFER MODE |
| 99 | command. dev->pio_mode is guaranteed to be valid when |
| 100 | ->set_piomode() is called, and dev->dma_mode is guaranteed to be |
| 101 | valid when ->set_dmamode() is called. ->post_set_mode() is |
| 102 | called unconditionally, after the SET FEATURES - XFER MODE |
| 103 | command completes successfully. |
| 104 | </para> |
| 105 | |
| 106 | <para> |
| 107 | ->set_piomode() is always called (if present), but |
| 108 | ->set_dma_mode() is only called if DMA is possible. |
| 109 | </para> |
| 110 | |
| 111 | <programlisting> |
| 112 | void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf); |
| 113 | void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf); |
| 114 | </programlisting> |
| 115 | |
| 116 | <para> |
| 117 | ->tf_load() is called to load the given taskfile into hardware |
| 118 | registers / DMA buffers. ->tf_read() is called to read the |
| 119 | hardware registers / DMA buffers, to obtain the current set of |
| 120 | taskfile register values. |
| 121 | </para> |
| 122 | |
| 123 | <programlisting> |
| 124 | void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); |
| 125 | </programlisting> |
| 126 | |
| 127 | <para> |
| 128 | causes an ATA command, previously loaded with |
| 129 | ->tf_load(), to be initiated in hardware. |
| 130 | </para> |
| 131 | |
| 132 | <programlisting> |
| 133 | u8 (*check_status)(struct ata_port *ap); |
| 134 | void (*dev_select)(struct ata_port *ap, unsigned int device); |
| 135 | </programlisting> |
| 136 | |
| 137 | <para> |
| 138 | Reads the Status ATA shadow register from hardware. On some |
| 139 | hardware, this has the side effect of clearing the interrupt |
| 140 | condition. |
| 141 | </para> |
| 142 | |
| 143 | <programlisting> |
| 144 | void (*dev_select)(struct ata_port *ap, unsigned int device); |
| 145 | </programlisting> |
| 146 | |
| 147 | <para> |
| 148 | Issues the low-level hardware command(s) that causes one of N |
| 149 | hardware devices to be considered 'selected' (active and |
| 150 | available for use) on the ATA bus. |
| 151 | </para> |
| 152 | |
| 153 | <programlisting> |
| 154 | void (*phy_reset) (struct ata_port *ap); |
| 155 | </programlisting> |
| 156 | |
| 157 | <para> |
| 158 | The very first step in the probe phase. Actions vary depending |
| 159 | on the bus type, typically. After waking up the device and probing |
| 160 | for device presence (PATA and SATA), typically a soft reset |
| 161 | (SRST) will be performed. Drivers typically use the helper |
| 162 | functions ata_bus_reset() or sata_phy_reset() for this hook. |
| 163 | </para> |
| 164 | |
| 165 | <programlisting> |
| 166 | void (*bmdma_setup) (struct ata_queued_cmd *qc); |
| 167 | void (*bmdma_start) (struct ata_queued_cmd *qc); |
| 168 | </programlisting> |
| 169 | |
| 170 | <para> |
| 171 | When setting up an IDE BMDMA transaction, these hooks arm |
| 172 | (->bmdma_setup) and fire (->bmdma_start) the hardware's DMA |
| 173 | engine. |
| 174 | </para> |
| 175 | |
| 176 | <programlisting> |
| 177 | void (*qc_prep) (struct ata_queued_cmd *qc); |
| 178 | int (*qc_issue) (struct ata_queued_cmd *qc); |
| 179 | </programlisting> |
| 180 | |
| 181 | <para> |
| 182 | Higher-level hooks, these two hooks can potentially supercede |
| 183 | several of the above taskfile/DMA engine hooks. ->qc_prep is |
| 184 | called after the buffers have been DMA-mapped, and is typically |
| 185 | used to populate the hardware's DMA scatter-gather table. |
| 186 | Most drivers use the standard ata_qc_prep() helper function, but |
| 187 | more advanced drivers roll their own. |
| 188 | </para> |
| 189 | <para> |
| 190 | ->qc_issue is used to make a command active, once the hardware |
| 191 | and S/G tables have been prepared. IDE BMDMA drivers use the |
| 192 | helper function ata_qc_issue_prot() for taskfile protocol-based |
| 193 | dispatch. More advanced drivers roll their own ->qc_issue |
| 194 | implementation, using this as the "issue new ATA command to |
| 195 | hardware" hook. |
| 196 | </para> |
| 197 | |
| 198 | <programlisting> |
| 199 | void (*eng_timeout) (struct ata_port *ap); |
| 200 | </programlisting> |
| 201 | |
| 202 | <para> |
| 203 | This is a high level error handling function, called from the |
| 204 | error handling thread, when a command times out. |
| 205 | </para> |
| 206 | |
| 207 | <programlisting> |
| 208 | irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); |
| 209 | void (*irq_clear) (struct ata_port *); |
| 210 | </programlisting> |
| 211 | |
| 212 | <para> |
| 213 | ->irq_handler is the interrupt handling routine registered with |
| 214 | the system, by libata. ->irq_clear is called during probe just |
| 215 | before the interrupt handler is registered, to be sure hardware |
| 216 | is quiet. |
| 217 | </para> |
| 218 | |
| 219 | <programlisting> |
| 220 | u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg); |
| 221 | void (*scr_write) (struct ata_port *ap, unsigned int sc_reg, |
| 222 | u32 val); |
| 223 | </programlisting> |
| 224 | |
| 225 | <para> |
| 226 | Read and write standard SATA phy registers. Currently only used |
| 227 | if ->phy_reset hook called the sata_phy_reset() helper function. |
| 228 | </para> |
| 229 | |
| 230 | <programlisting> |
| 231 | int (*port_start) (struct ata_port *ap); |
| 232 | void (*port_stop) (struct ata_port *ap); |
| 233 | void (*host_stop) (struct ata_host_set *host_set); |
| 234 | </programlisting> |
| 235 | |
| 236 | <para> |
| 237 | ->port_start() is called just after the data structures for each |
| 238 | port are initialized. Typically this is used to alloc per-port |
| 239 | DMA buffers / tables / rings, enable DMA engines, and similar |
| 240 | tasks. |
| 241 | </para> |
| 242 | <para> |
| 243 | ->host_stop() is called when the rmmod or hot unplug process |
| 244 | begins. The hook must stop all hardware interrupts, DMA |
| 245 | engines, etc. |
| 246 | </para> |
| 247 | <para> |
| 248 | ->port_stop() is called after ->host_stop(). It's sole function |
| 249 | is to release DMA/memory resources, now that they are no longer |
| 250 | actively being used. |
| 251 | </para> |
| 252 | |
| 253 | </sect1> |
| 254 | </chapter> |
| 255 | |
| 256 | <chapter id="libataExt"> |
| 257 | <title>libata Library</title> |
| 258 | !Edrivers/scsi/libata-core.c |
| 259 | </chapter> |
| 260 | |
| 261 | <chapter id="libataInt"> |
| 262 | <title>libata Core Internals</title> |
| 263 | !Idrivers/scsi/libata-core.c |
| 264 | </chapter> |
| 265 | |
| 266 | <chapter id="libataScsiInt"> |
| 267 | <title>libata SCSI translation/emulation</title> |
| 268 | !Edrivers/scsi/libata-scsi.c |
| 269 | !Idrivers/scsi/libata-scsi.c |
| 270 | </chapter> |
| 271 | |
| 272 | <chapter id="PiixInt"> |
| 273 | <title>ata_piix Internals</title> |
| 274 | !Idrivers/scsi/ata_piix.c |
| 275 | </chapter> |
| 276 | |
| 277 | <chapter id="SILInt"> |
| 278 | <title>sata_sil Internals</title> |
| 279 | !Idrivers/scsi/sata_sil.c |
| 280 | </chapter> |
| 281 | |
| 282 | </book> |