Merge of 'docs' branch from · tjh.dev/kernel@3176046

+125 -33

Documentation/DocBook/libata.tmpl

··· 14 14 </authorgroup> 15 15 16 16 <copyright> 17 - <year>2003</year> 17 + <year>2003-2005</year> 18 18 <holder>Jeff Garzik</holder> 19 19 </copyright> 20 20 ··· 44 44 45 45 <toc></toc> 46 46 47 - <chapter id="libataThanks"> 48 - <title>Thanks</title> 47 + <chapter id="libataIntroduction"> 48 + <title>Introduction</title> 49 49 <para> 50 - The bulk of the ATA knowledge comes thanks to long conversations with 51 - Andre Hedrick (www.linux-ide.org). 50 + libATA is a library used inside the Linux kernel to support ATA host 51 + controllers and devices. libATA provides an ATA driver API, class 52 + transports for ATA and ATAPI devices, and SCSI<->ATA translation 53 + for ATA devices according to the T10 SAT specification. 52 54 </para> 53 55 <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). 56 + This Guide documents the libATA driver API, library functions, library 57 + internals, and a couple sample ATA low-level drivers. 63 58 </para> 64 59 </chapter> 65 60 66 61 <chapter id="libataDriverApi"> 67 62 <title>libata Driver API</title> 63 + <para> 64 + struct ata_port_operations is defined for every low-level libata 65 + hardware driver, and it controls how the low-level driver 66 + interfaces with the ATA and SCSI layers. 67 + </para> 68 + <para> 69 + FIS-based drivers will hook into the system with ->qc_prep() and 70 + ->qc_issue() high-level hooks. Hardware which behaves in a manner 71 + similar to PCI IDE hardware may utilize several generic helpers, 72 + defining at a bare minimum the bus I/O addresses of the ATA shadow 73 + register blocks. 74 + </para> 68 75 <sect1> 69 76 <title>struct ata_port_operations</title> 70 77 78 + <sect2><title>Disable ATA port</title> 71 79 <programlisting> 72 80 void (*port_disable) (struct ata_port *); 73 81 </programlisting> ··· 86 78 unplug). 87 79 </para> 88 80 81 + </sect2> 82 + 83 + <sect2><title>Post-IDENTIFY device configuration</title> 89 84 <programlisting> 90 85 void (*dev_config) (struct ata_port *, struct ata_device *); 91 86 </programlisting> ··· 99 88 issue of SET FEATURES - XFER MODE, and prior to operation. 100 89 </para> 101 90 91 + </sect2> 92 + 93 + <sect2><title>Set PIO/DMA mode</title> 102 94 <programlisting> 103 95 void (*set_piomode) (struct ata_port *, struct ata_device *); 104 96 void (*set_dmamode) (struct ata_port *, struct ata_device *); ··· 122 108 ->set_dma_mode() is only called if DMA is possible. 123 109 </para> 124 110 111 + </sect2> 112 + 113 + <sect2><title>Taskfile read/write</title> 125 114 <programlisting> 126 115 void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf); 127 116 void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf); ··· 137 120 taskfile register values. 138 121 </para> 139 122 123 + </sect2> 124 + 125 + <sect2><title>ATA command execute</title> 140 126 <programlisting> 141 127 void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); 142 128 </programlisting> ··· 149 129 ->tf_load(), to be initiated in hardware. 150 130 </para> 151 131 132 + </sect2> 133 + 134 + <sect2><title>Per-cmd ATAPI DMA capabilities filter</title> 152 135 <programlisting> 153 - u8 (*check_status)(struct ata_port *ap); 154 - void (*dev_select)(struct ata_port *ap, unsigned int device); 136 + int (*check_atapi_dma) (struct ata_queued_cmd *qc); 155 137 </programlisting> 156 138 157 139 <para> 158 - Reads the Status ATA shadow register from hardware. On some 159 - hardware, this has the side effect of clearing the interrupt 160 - condition. 140 + Allow low-level driver to filter ATA PACKET commands, returning a status 141 + indicating whether or not it is OK to use DMA for the supplied PACKET 142 + command. 161 143 </para> 162 144 145 + </sect2> 146 + 147 + <sect2><title>Read specific ATA shadow registers</title> 148 + <programlisting> 149 + u8 (*check_status)(struct ata_port *ap); 150 + u8 (*check_altstatus)(struct ata_port *ap); 151 + u8 (*check_err)(struct ata_port *ap); 152 + </programlisting> 153 + 154 + <para> 155 + Reads the Status/AltStatus/Error ATA shadow register from 156 + hardware. On some hardware, reading the Status register has 157 + the side effect of clearing the interrupt condition. 158 + </para> 159 + 160 + </sect2> 161 + 162 + <sect2><title>Select ATA device on bus</title> 163 163 <programlisting> 164 164 void (*dev_select)(struct ata_port *ap, unsigned int device); 165 165 </programlisting> ··· 187 147 <para> 188 148 Issues the low-level hardware command(s) that causes one of N 189 149 hardware devices to be considered 'selected' (active and 190 - available for use) on the ATA bus. 150 + available for use) on the ATA bus. This generally has no 151 + meaning on FIS-based devices. 191 152 </para> 192 153 154 + </sect2> 155 + 156 + <sect2><title>Reset ATA bus</title> 193 157 <programlisting> 194 158 void (*phy_reset) (struct ata_port *ap); 195 159 </programlisting> ··· 206 162 functions ata_bus_reset() or sata_phy_reset() for this hook. 207 163 </para> 208 164 165 + </sect2> 166 + 167 + <sect2><title>Control PCI IDE BMDMA engine</title> 209 168 <programlisting> 210 169 void (*bmdma_setup) (struct ata_queued_cmd *qc); 211 170 void (*bmdma_start) (struct ata_queued_cmd *qc); 171 + void (*bmdma_stop) (struct ata_port *ap); 172 + u8 (*bmdma_status) (struct ata_port *ap); 212 173 </programlisting> 213 174 214 175 <para> 215 - When setting up an IDE BMDMA transaction, these hooks arm 216 - (->bmdma_setup) and fire (->bmdma_start) the hardware's DMA 217 - engine. 176 + When setting up an IDE BMDMA transaction, these hooks arm 177 + (->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) 178 + the hardware's DMA engine. ->bmdma_status is used to read the standard 179 + PCI IDE DMA Status register. 218 180 </para> 219 181 182 + <para> 183 + These hooks are typically either no-ops, or simply not implemented, in 184 + FIS-based drivers. 185 + </para> 186 + 187 + </sect2> 188 + 189 + <sect2><title>High-level taskfile hooks</title> 220 190 <programlisting> 221 191 void (*qc_prep) (struct ata_queued_cmd *qc); 222 192 int (*qc_issue) (struct ata_queued_cmd *qc); ··· 248 190 ->qc_issue is used to make a command active, once the hardware 249 191 and S/G tables have been prepared. IDE BMDMA drivers use the 250 192 helper function ata_qc_issue_prot() for taskfile protocol-based 251 - dispatch. More advanced drivers roll their own ->qc_issue 252 - implementation, using this as the "issue new ATA command to 253 - hardware" hook. 193 + dispatch. More advanced drivers implement their own ->qc_issue. 254 194 </para> 255 195 196 + </sect2> 197 + 198 + <sect2><title>Timeout (error) handling</title> 256 199 <programlisting> 257 200 void (*eng_timeout) (struct ata_port *ap); 258 201 </programlisting> 259 202 260 203 <para> 261 - This is a high level error handling function, called from the 262 - error handling thread, when a command times out. 204 + This is a high level error handling function, called from the 205 + error handling thread, when a command times out. Most newer 206 + hardware will implement its own error handling code here. IDE BMDMA 207 + drivers may use the helper function ata_eng_timeout(). 263 208 </para> 264 209 210 + </sect2> 211 + 212 + <sect2><title>Hardware interrupt handling</title> 265 213 <programlisting> 266 214 irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); 267 215 void (*irq_clear) (struct ata_port *); ··· 280 216 is quiet. 281 217 </para> 282 218 219 + </sect2> 220 + 221 + <sect2><title>SATA phy read/write</title> 283 222 <programlisting> 284 223 u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg); 285 224 void (*scr_write) (struct ata_port *ap, unsigned int sc_reg, ··· 294 227 if ->phy_reset hook called the sata_phy_reset() helper function. 295 228 </para> 296 229 230 + </sect2> 231 + 232 + <sect2><title>Init and shutdown</title> 297 233 <programlisting> 298 234 int (*port_start) (struct ata_port *ap); 299 235 void (*port_stop) (struct ata_port *ap); ··· 310 240 tasks. 311 241 </para> 312 242 <para> 313 - ->host_stop() is called when the rmmod or hot unplug process 314 - begins. The hook must stop all hardware interrupts, DMA 315 - engines, etc. 316 - </para> 317 - <para> 318 243 ->port_stop() is called after ->host_stop(). It's sole function 319 244 is to release DMA/memory resources, now that they are no longer 320 245 actively being used. 321 246 </para> 247 + <para> 248 + ->host_stop() is called after all ->port_stop() calls 249 + have completed. The hook must finalize hardware shutdown, release DMA 250 + and other resources, etc. 251 + </para> 252 + 253 + </sect2> 322 254 323 255 </sect1> 324 256 </chapter> ··· 349 277 <chapter id="SILInt"> 350 278 <title>sata_sil Internals</title> 351 279 !Idrivers/scsi/sata_sil.c 280 + </chapter> 281 + 282 + <chapter id="libataThanks"> 283 + <title>Thanks</title> 284 + <para> 285 + The bulk of the ATA knowledge comes thanks to long conversations with 286 + Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA 287 + and SCSI specifications. 288 + </para> 289 + <para> 290 + Thanks to Alan Cox for pointing out similarities 291 + between SATA and SCSI, and in general for motivation to hack on 292 + libata. 293 + </para> 294 + <para> 295 + libata's device detection 296 + method, ata_pio_devchk, and in general all the early probing was 297 + based on extensive study of Hale Landis's probe/reset code in his 298 + ATADRVR driver (www.ata-atapi.com). 299 + </para> 352 300 </chapter> 353 301 354 302 </book>

-16

drivers/scsi/ata_piix.c

··· 665 665 return ata_pci_init_one(pdev, port_info, n_ports); 666 666 } 667 667 668 - /** 669 - * piix_init - 670 - * 671 - * LOCKING: 672 - * 673 - * RETURNS: 674 - * 675 - */ 676 - 677 668 static int __init piix_init(void) 678 669 { 679 670 int rc; ··· 679 688 DPRINTK("done\n"); 680 689 return 0; 681 690 } 682 - 683 - /** 684 - * piix_exit - 685 - * 686 - * LOCKING: 687 - * 688 - */ 689 691 690 692 static void __exit piix_exit(void) 691 693 {

+427 -43

drivers/scsi/libata-core.c

··· 186 186 ata_wait_idle(ap); 187 187 } 188 188 189 + 190 + /** 191 + * ata_tf_load - send taskfile registers to host controller 192 + * @ap: Port to which output is sent 193 + * @tf: ATA taskfile register set 194 + * 195 + * Outputs ATA taskfile to standard ATA host controller using MMIO 196 + * or PIO as indicated by the ATA_FLAG_MMIO flag. 197 + * Writes the control, feature, nsect, lbal, lbam, and lbah registers. 198 + * Optionally (ATA_TFLAG_LBA48) writes hob_feature, hob_nsect, 199 + * hob_lbal, hob_lbam, and hob_lbah. 200 + * 201 + * This function waits for idle (!BUSY and !DRQ) after writing 202 + * registers. If the control register has a new value, this 203 + * function also waits for idle after writing control and before 204 + * writing the remaining registers. 205 + * 206 + * May be used as the tf_load() entry in ata_port_operations. 207 + * 208 + * LOCKING: 209 + * Inherited from caller. 210 + */ 189 211 void ata_tf_load(struct ata_port *ap, struct ata_taskfile *tf) 190 212 { 191 213 if (ap->flags & ATA_FLAG_MMIO) ··· 217 195 } 218 196 219 197 /** 220 - * ata_exec_command - issue ATA command to host controller 198 + * ata_exec_command_pio - issue ATA command to host controller 221 199 * @ap: port to which command is being issued 222 200 * @tf: ATA taskfile register set 223 201 * 224 - * Issues PIO/MMIO write to ATA command register, with proper 202 + * Issues PIO write to ATA command register, with proper 225 203 * synchronization with interrupt handler / other threads. 226 204 * 227 205 * LOCKING: ··· 257 235 ata_pause(ap); 258 236 } 259 237 238 + 239 + /** 240 + * ata_exec_command - issue ATA command to host controller 241 + * @ap: port to which command is being issued 242 + * @tf: ATA taskfile register set 243 + * 244 + * Issues PIO/MMIO write to ATA command register, with proper 245 + * synchronization with interrupt handler / other threads. 246 + * 247 + * LOCKING: 248 + * spin_lock_irqsave(host_set lock) 249 + */ 260 250 void ata_exec_command(struct ata_port *ap, struct ata_taskfile *tf) 261 251 { 262 252 if (ap->flags & ATA_FLAG_MMIO) ··· 339 305 } 340 306 341 307 /** 342 - * ata_tf_read - input device's ATA taskfile shadow registers 308 + * ata_tf_read_pio - input device's ATA taskfile shadow registers 343 309 * @ap: Port from which input is read 344 310 * @tf: ATA taskfile register set for storing input 345 311 * ··· 402 368 } 403 369 } 404 370 371 + 372 + /** 373 + * ata_tf_read - input device's ATA taskfile shadow registers 374 + * @ap: Port from which input is read 375 + * @tf: ATA taskfile register set for storing input 376 + * 377 + * Reads ATA taskfile registers for currently-selected device 378 + * into @tf. 379 + * 380 + * Reads nsect, lbal, lbam, lbah, and device. If ATA_TFLAG_LBA48 381 + * is set, also reads the hob registers. 382 + * 383 + * May be used as the tf_read() entry in ata_port_operations. 384 + * 385 + * LOCKING: 386 + * Inherited from caller. 387 + */ 405 388 void ata_tf_read(struct ata_port *ap, struct ata_taskfile *tf) 406 389 { 407 390 if (ap->flags & ATA_FLAG_MMIO) ··· 432 381 * @ap: port where the device is 433 382 * 434 383 * Reads ATA taskfile status register for currently-selected device 435 - * and return it's value. This also clears pending interrupts 384 + * and return its value. This also clears pending interrupts 436 385 * from this device 437 386 * 438 387 * LOCKING: ··· 448 397 * @ap: port where the device is 449 398 * 450 399 * Reads ATA taskfile status register for currently-selected device 451 - * via MMIO and return it's value. This also clears pending interrupts 400 + * via MMIO and return its value. This also clears pending interrupts 452 401 * from this device 453 402 * 454 403 * LOCKING: ··· 459 408 return readb((void __iomem *) ap->ioaddr.status_addr); 460 409 } 461 410 411 + 412 + /** 413 + * ata_check_status - Read device status reg & clear interrupt 414 + * @ap: port where the device is 415 + * 416 + * Reads ATA taskfile status register for currently-selected device 417 + * and return its value. This also clears pending interrupts 418 + * from this device 419 + * 420 + * May be used as the check_status() entry in ata_port_operations. 421 + * 422 + * LOCKING: 423 + * Inherited from caller. 424 + */ 462 425 u8 ata_check_status(struct ata_port *ap) 463 426 { 464 427 if (ap->flags & ATA_FLAG_MMIO) ··· 480 415 return ata_check_status_pio(ap); 481 416 } 482 417 418 + 419 + /** 420 + * ata_altstatus - Read device alternate status reg 421 + * @ap: port where the device is 422 + * 423 + * Reads ATA taskfile alternate status register for 424 + * currently-selected device and return its value. 425 + * 426 + * Note: may NOT be used as the check_altstatus() entry in 427 + * ata_port_operations. 428 + * 429 + * LOCKING: 430 + * Inherited from caller. 431 + */ 483 432 u8 ata_altstatus(struct ata_port *ap) 484 433 { 485 434 if (ap->ops->check_altstatus) ··· 504 425 return inb(ap->ioaddr.altstatus_addr); 505 426 } 506 427 428 + 429 + /** 430 + * ata_chk_err - Read device error reg 431 + * @ap: port where the device is 432 + * 433 + * Reads ATA taskfile error register for 434 + * currently-selected device and return its value. 435 + * 436 + * Note: may NOT be used as the check_err() entry in 437 + * ata_port_operations. 438 + * 439 + * LOCKING: 440 + * Inherited from caller. 441 + */ 507 442 u8 ata_chk_err(struct ata_port *ap) 508 443 { 509 444 if (ap->ops->check_err) ··· 966 873 } 967 874 } 968 875 876 + 877 + /** 878 + * ata_noop_dev_select - Select device 0/1 on ATA bus 879 + * @ap: ATA channel to manipulate 880 + * @device: ATA device (numbered from zero) to select 881 + * 882 + * This function performs no actual function. 883 + * 884 + * May be used as the dev_select() entry in ata_port_operations. 885 + * 886 + * LOCKING: 887 + * caller. 888 + */ 969 889 void ata_noop_dev_select (struct ata_port *ap, unsigned int device) 970 890 { 971 891 } 892 + 972 893 973 894 /** 974 895 * ata_std_dev_select - Select device 0/1 on ATA bus ··· 991 884 * 992 885 * Use the method defined in the ATA specification to 993 886 * make either device 0, or device 1, active on the 994 - * ATA channel. 887 + * ATA channel. Works with both PIO and MMIO. 888 + * 889 + * May be used as the dev_select() entry in ata_port_operations. 995 890 * 996 891 * LOCKING: 997 892 * caller. ··· 1299 1190 * ata_bus_probe - Reset and probe ATA bus 1300 1191 * @ap: Bus to probe 1301 1192 * 1193 + * Master ATA bus probing function. Initiates a hardware-dependent 1194 + * bus reset, then attempts to identify any devices found on 1195 + * the bus. 1196 + * 1302 1197 * LOCKING: 1198 + * PCI/etc. bus probe sem. 1303 1199 * 1304 1200 * RETURNS: 1305 1201 * Zero on success, non-zero on error. ··· 1343 1229 } 1344 1230 1345 1231 /** 1346 - * ata_port_probe - 1347 - * @ap: 1232 + * ata_port_probe - Mark port as enabled 1233 + * @ap: Port for which we indicate enablement 1348 1234 * 1349 - * LOCKING: 1235 + * Modify @ap data structure such that the system 1236 + * thinks that the entire port is enabled. 1237 + * 1238 + * LOCKING: host_set lock, or some other form of 1239 + * serialization. 1350 1240 */ 1351 1241 1352 1242 void ata_port_probe(struct ata_port *ap) ··· 1359 1241 } 1360 1242 1361 1243 /** 1362 - * __sata_phy_reset - 1363 - * @ap: 1244 + * __sata_phy_reset - Wake/reset a low-level SATA PHY 1245 + * @ap: SATA port associated with target SATA PHY. 1246 + * 1247 + * This function issues commands to standard SATA Sxxx 1248 + * PHY registers, to wake up the phy (and device), and 1249 + * clear any reset condition. 1364 1250 * 1365 1251 * LOCKING: 1252 + * PCI/etc. bus probe sem. 1366 1253 * 1367 1254 */ 1368 1255 void __sata_phy_reset(struct ata_port *ap) ··· 1412 1289 } 1413 1290 1414 1291 /** 1415 - * __sata_phy_reset - 1416 - * @ap: 1292 + * sata_phy_reset - Reset SATA bus. 1293 + * @ap: SATA port associated with target SATA PHY. 1294 + * 1295 + * This function resets the SATA bus, and then probes 1296 + * the bus for devices. 1417 1297 * 1418 1298 * LOCKING: 1299 + * PCI/etc. bus probe sem. 1419 1300 * 1420 1301 */ 1421 1302 void sata_phy_reset(struct ata_port *ap) ··· 1431 1304 } 1432 1305 1433 1306 /** 1434 - * ata_port_disable - 1435 - * @ap: 1307 + * ata_port_disable - Disable port. 1308 + * @ap: Port to be disabled. 1436 1309 * 1437 - * LOCKING: 1310 + * Modify @ap data structure such that the system 1311 + * thinks that the entire port is disabled, and should 1312 + * never attempt to probe or communicate with devices 1313 + * on this port. 1314 + * 1315 + * LOCKING: host_set lock, or some other form of 1316 + * serialization. 1438 1317 */ 1439 1318 1440 1319 void ata_port_disable(struct ata_port *ap) ··· 1549 1416 * ata_set_mode - Program timings and issue SET FEATURES - XFER 1550 1417 * @ap: port on which timings will be programmed 1551 1418 * 1419 + * Set ATA device disk transfer mode (PIO3, UDMA6, etc.). 1420 + * 1552 1421 * LOCKING: 1422 + * PCI/etc. bus probe sem. 1553 1423 * 1554 1424 */ 1555 1425 static void ata_set_mode(struct ata_port *ap) ··· 1603 1467 * @tmout_pat: impatience timeout 1604 1468 * @tmout: overall timeout 1605 1469 * 1606 - * LOCKING: 1470 + * Sleep until ATA Status register bit BSY clears, 1471 + * or a timeout occurs. 1472 + * 1473 + * LOCKING: None. 1607 1474 * 1608 1475 */ 1609 1476 ··· 1692 1553 } 1693 1554 1694 1555 /** 1695 - * ata_bus_edd - 1696 - * @ap: 1556 + * ata_bus_edd - Issue EXECUTE DEVICE DIAGNOSTIC command. 1557 + * @ap: Port to reset and probe 1558 + * 1559 + * Use the EXECUTE DEVICE DIAGNOSTIC command to reset and 1560 + * probe the bus. Not often used these days. 1697 1561 * 1698 1562 * LOCKING: 1563 + * PCI/etc. bus probe sem. 1699 1564 * 1700 1565 */ 1701 1566 ··· 1776 1633 * the device is ATA or ATAPI. 1777 1634 * 1778 1635 * LOCKING: 1779 - * Inherited from caller. Some functions called by this function 1780 - * obtain the host_set lock. 1636 + * PCI/etc. bus probe sem. 1637 + * Obtains host_set lock. 1781 1638 * 1782 1639 * SIDE EFFECTS: 1783 1640 * Sets ATA_FLAG_PORT_DISABLED if bus reset fails. ··· 2019 1876 * @xfer_mode_out: (output) SET FEATURES - XFER MODE code 2020 1877 * @xfer_shift_out: (output) bit shift that selects this mode 2021 1878 * 1879 + * Based on host and device capabilities, determine the 1880 + * maximum transfer mode that is amenable to all. 1881 + * 2022 1882 * LOCKING: 1883 + * PCI/etc. bus probe sem. 2023 1884 * 2024 1885 * RETURNS: 2025 1886 * Zero on success, negative on error. ··· 2056 1909 * @ap: Port associated with device @dev 2057 1910 * @dev: Device to which command will be sent 2058 1911 * 1912 + * Issue SET FEATURES - XFER MODE command to device @dev 1913 + * on port @ap. 1914 + * 2059 1915 * LOCKING: 1916 + * PCI/etc. bus probe sem. 2060 1917 */ 2061 1918 2062 1919 static void ata_dev_set_xfermode(struct ata_port *ap, struct ata_device *dev) ··· 2098 1947 } 2099 1948 2100 1949 /** 2101 - * ata_sg_clean - 2102 - * @qc: 1950 + * ata_sg_clean - Unmap DMA memory associated with command 1951 + * @qc: Command containing DMA memory to be released 1952 + * 1953 + * Unmap all mapped DMA memory associated with this command. 2103 1954 * 2104 1955 * LOCKING: 1956 + * spin_lock_irqsave(host_set lock) 2105 1957 */ 2106 1958 2107 1959 static void ata_sg_clean(struct ata_queued_cmd *qc) ··· 2135 1981 * ata_fill_sg - Fill PCI IDE PRD table 2136 1982 * @qc: Metadata associated with taskfile to be transferred 2137 1983 * 1984 + * Fill PCI IDE PRD (scatter-gather) table with segments 1985 + * associated with the current disk command. 1986 + * 2138 1987 * LOCKING: 1988 + * spin_lock_irqsave(host_set lock) 2139 1989 * 2140 1990 */ 2141 1991 static void ata_fill_sg(struct ata_queued_cmd *qc) ··· 2186 2028 * ata_check_atapi_dma - Check whether ATAPI DMA can be supported 2187 2029 * @qc: Metadata associated with taskfile to check 2188 2030 * 2031 + * Allow low-level driver to filter ATA PACKET commands, returning 2032 + * a status indicating whether or not it is OK to use DMA for the 2033 + * supplied PACKET command. 2034 + * 2189 2035 * LOCKING: 2036 + * spin_lock_irqsave(host_set lock) 2037 + * 2190 2038 * RETURNS: 0 when ATAPI DMA can be used 2191 2039 * nonzero otherwise 2192 2040 */ ··· 2210 2046 * ata_qc_prep - Prepare taskfile for submission 2211 2047 * @qc: Metadata associated with taskfile to be prepared 2212 2048 * 2049 + * Prepare ATA taskfile for submission. 2050 + * 2213 2051 * LOCKING: 2214 2052 * spin_lock_irqsave(host_set lock) 2215 2053 */ ··· 2223 2057 ata_fill_sg(qc); 2224 2058 } 2225 2059 2060 + /** 2061 + * ata_sg_init_one - Associate command with memory buffer 2062 + * @qc: Command to be associated 2063 + * @buf: Memory buffer 2064 + * @buflen: Length of memory buffer, in bytes. 2065 + * 2066 + * Initialize the data-related elements of queued_cmd @qc 2067 + * to point to a single memory buffer, @buf of byte length @buflen. 2068 + * 2069 + * LOCKING: 2070 + * spin_lock_irqsave(host_set lock) 2071 + */ 2072 + 2073 + 2074 + 2075 + /** 2076 + * ata_sg_init_one - Prepare a one-entry scatter-gather list. 2077 + * @qc: Queued command 2078 + * @buf: transfer buffer 2079 + * @buflen: length of buf 2080 + * 2081 + * Builds a single-entry scatter-gather list to initiate a 2082 + * transfer utilizing the specified buffer. 2083 + * 2084 + * LOCKING: 2085 + */ 2226 2086 void ata_sg_init_one(struct ata_queued_cmd *qc, void *buf, unsigned int buflen) 2227 2087 { 2228 2088 struct scatterlist *sg; ··· 2266 2074 sg->length = buflen; 2267 2075 } 2268 2076 2077 + /** 2078 + * ata_sg_init - Associate command with scatter-gather table. 2079 + * @qc: Command to be associated 2080 + * @sg: Scatter-gather table. 2081 + * @n_elem: Number of elements in s/g table. 2082 + * 2083 + * Initialize the data-related elements of queued_cmd @qc 2084 + * to point to a scatter-gather table @sg, containing @n_elem 2085 + * elements. 2086 + * 2087 + * LOCKING: 2088 + * spin_lock_irqsave(host_set lock) 2089 + */ 2090 + 2091 + 2092 + /** 2093 + * ata_sg_init - Assign a scatter gather list to a queued command 2094 + * @qc: Queued command 2095 + * @sg: Scatter-gather list 2096 + * @n_elem: length of sg list 2097 + * 2098 + * Attaches a scatter-gather list to a queued command. 2099 + * 2100 + * LOCKING: 2101 + */ 2102 + 2269 2103 void ata_sg_init(struct ata_queued_cmd *qc, struct scatterlist *sg, 2270 2104 unsigned int n_elem) 2271 2105 { ··· 2301 2083 } 2302 2084 2303 2085 /** 2304 - * ata_sg_setup_one - 2305 - * @qc: 2086 + * ata_sg_setup_one - DMA-map the memory buffer associated with a command. 2087 + * @qc: Command with memory buffer to be mapped. 2088 + * 2089 + * DMA-map the memory buffer associated with queued_cmd @qc. 2306 2090 * 2307 2091 * LOCKING: 2308 2092 * spin_lock_irqsave(host_set lock) 2309 2093 * 2310 2094 * RETURNS: 2311 - * 2095 + * Zero on success, negative on error. 2312 2096 */ 2313 2097 2314 2098 static int ata_sg_setup_one(struct ata_queued_cmd *qc) ··· 2335 2115 } 2336 2116 2337 2117 /** 2338 - * ata_sg_setup - 2339 - * @qc: 2118 + * ata_sg_setup - DMA-map the scatter-gather table associated with a command. 2119 + * @qc: Command with scatter-gather table to be mapped. 2120 + * 2121 + * DMA-map the scatter-gather table associated with queued_cmd @qc. 2340 2122 * 2341 2123 * LOCKING: 2342 2124 * spin_lock_irqsave(host_set lock) 2343 2125 * 2344 2126 * RETURNS: 2127 + * Zero on success, negative on error. 2345 2128 * 2346 2129 */ 2347 2130 ··· 2374 2151 * @ap: 2375 2152 * 2376 2153 * LOCKING: 2154 + * None. (executing in kernel thread context) 2377 2155 * 2378 2156 * RETURNS: 2379 2157 * ··· 2422 2198 * @ap: 2423 2199 * 2424 2200 * LOCKING: 2201 + * None. (executing in kernel thread context) 2425 2202 */ 2426 2203 2427 2204 static void ata_pio_complete (struct ata_port *ap) ··· 2465 2240 ata_qc_complete(qc, drv_stat); 2466 2241 } 2467 2242 2243 + 2244 + /** 2245 + * swap_buf_le16 - 2246 + * @buf: Buffer to swap 2247 + * @buf_words: Number of 16-bit words in buffer. 2248 + * 2249 + * Swap halves of 16-bit words if needed to convert from 2250 + * little-endian byte order to native cpu byte order, or 2251 + * vice-versa. 2252 + * 2253 + * LOCKING: 2254 + */ 2468 2255 void swap_buf_le16(u16 *buf, unsigned int buf_words) 2469 2256 { 2470 2257 #ifdef __BIG_ENDIAN ··· 2652 2415 * @ap: 2653 2416 * 2654 2417 * LOCKING: 2418 + * None. (executing in kernel thread context) 2655 2419 */ 2656 2420 2657 2421 static void ata_pio_block(struct ata_port *ap) ··· 2821 2583 * transaction completed successfully. 2822 2584 * 2823 2585 * LOCKING: 2586 + * Inherited from SCSI layer (none, can sleep) 2824 2587 */ 2825 2588 2826 2589 static void ata_qc_timeout(struct ata_queued_cmd *qc) ··· 2931 2692 * @dev: Device from whom we request an available command structure 2932 2693 * 2933 2694 * LOCKING: 2695 + * None. 2934 2696 */ 2935 2697 2936 2698 static struct ata_queued_cmd *ata_qc_new(struct ata_port *ap) ··· 2957 2717 * @dev: Device from whom we request an available command structure 2958 2718 * 2959 2719 * LOCKING: 2720 + * None. 2960 2721 */ 2961 2722 2962 2723 struct ata_queued_cmd *ata_qc_new_init(struct ata_port *ap, ··· 3022 2781 * in case something prevents using it. 3023 2782 * 3024 2783 * LOCKING: 2784 + * spin_lock_irqsave(host_set lock) 3025 2785 * 3026 2786 */ 3027 2787 void ata_qc_free(struct ata_queued_cmd *qc) ··· 3036 2794 /** 3037 2795 * ata_qc_complete - Complete an active ATA command 3038 2796 * @qc: Command to complete 3039 - * @drv_stat: ATA status register contents 2797 + * @drv_stat: ATA Status register contents 2798 + * 2799 + * Indicate to the mid and upper layers that an ATA 2800 + * command has completed, with either an ok or not-ok status. 3040 2801 * 3041 2802 * LOCKING: 2803 + * spin_lock_irqsave(host_set lock) 3042 2804 * 3043 2805 */ 3044 2806 ··· 3138 2892 return -1; 3139 2893 } 3140 2894 2895 + 3141 2896 /** 3142 2897 * ata_qc_issue_prot - issue taskfile to device in proto-dependent manner 3143 2898 * @qc: command to issue to device ··· 3147 2900 * starts an ATA command. ATA commands are grouped into 3148 2901 * classes called "protocols", and issuing each type of protocol 3149 2902 * is slightly different. 2903 + * 2904 + * May be used as the qc_issue() entry in ata_port_operations. 3150 2905 * 3151 2906 * LOCKING: 3152 2907 * spin_lock_irqsave(host_set lock) ··· 3207 2958 } 3208 2959 3209 2960 /** 3210 - * ata_bmdma_setup - Set up PCI IDE BMDMA transaction 2961 + * ata_bmdma_setup_mmio - Set up PCI IDE BMDMA transaction 3211 2962 * @qc: Info associated with this ATA transaction. 3212 2963 * 3213 2964 * LOCKING: ··· 3314 3065 ap->ioaddr.bmdma_addr + ATA_DMA_CMD); 3315 3066 } 3316 3067 3068 + 3069 + /** 3070 + * ata_bmdma_start - Start a PCI IDE BMDMA transaction 3071 + * @qc: Info associated with this ATA transaction. 3072 + * 3073 + * Writes the ATA_DMA_START flag to the DMA command register. 3074 + * 3075 + * May be used as the bmdma_start() entry in ata_port_operations. 3076 + * 3077 + * LOCKING: 3078 + * spin_lock_irqsave(host_set lock) 3079 + */ 3317 3080 void ata_bmdma_start(struct ata_queued_cmd *qc) 3318 3081 { 3319 3082 if (qc->ap->flags & ATA_FLAG_MMIO) ··· 3334 3073 ata_bmdma_start_pio(qc); 3335 3074 } 3336 3075 3076 + 3077 + /** 3078 + * ata_bmdma_setup - Set up PCI IDE BMDMA transaction 3079 + * @qc: Info associated with this ATA transaction. 3080 + * 3081 + * Writes address of PRD table to device's PRD Table Address 3082 + * register, sets the DMA control register, and calls 3083 + * ops->exec_command() to start the transfer. 3084 + * 3085 + * May be used as the bmdma_setup() entry in ata_port_operations. 3086 + * 3087 + * LOCKING: 3088 + * spin_lock_irqsave(host_set lock) 3089 + */ 3337 3090 void ata_bmdma_setup(struct ata_queued_cmd *qc) 3338 3091 { 3339 3092 if (qc->ap->flags & ATA_FLAG_MMIO) ··· 3355 3080 else 3356 3081 ata_bmdma_setup_pio(qc); 3357 3082 } 3083 + 3084 + 3085 + /** 3086 + * ata_bmdma_irq_clear - Clear PCI IDE BMDMA interrupt. 3087 + * @ap: Port associated with this ATA transaction. 3088 + * 3089 + * Clear interrupt and error flags in DMA status register. 3090 + * 3091 + * May be used as the irq_clear() entry in ata_port_operations. 3092 + * 3093 + * LOCKING: 3094 + * spin_lock_irqsave(host_set lock) 3095 + */ 3358 3096 3359 3097 void ata_bmdma_irq_clear(struct ata_port *ap) 3360 3098 { ··· 3381 3093 3382 3094 } 3383 3095 3096 + 3097 + /** 3098 + * ata_bmdma_status - Read PCI IDE BMDMA status 3099 + * @ap: Port associated with this ATA transaction. 3100 + * 3101 + * Read and return BMDMA status register. 3102 + * 3103 + * May be used as the bmdma_status() entry in ata_port_operations. 3104 + * 3105 + * LOCKING: 3106 + * spin_lock_irqsave(host_set lock) 3107 + */ 3108 + 3384 3109 u8 ata_bmdma_status(struct ata_port *ap) 3385 3110 { 3386 3111 u8 host_stat; ··· 3404 3103 host_stat = inb(ap->ioaddr.bmdma_addr + ATA_DMA_STATUS); 3405 3104 return host_stat; 3406 3105 } 3106 + 3107 + 3108 + /** 3109 + * ata_bmdma_stop - Stop PCI IDE BMDMA transfer 3110 + * @ap: Port associated with this ATA transaction. 3111 + * 3112 + * Clears the ATA_DMA_START flag in the dma control register 3113 + * 3114 + * May be used as the bmdma_stop() entry in ata_port_operations. 3115 + * 3116 + * LOCKING: 3117 + * spin_lock_irqsave(host_set lock) 3118 + */ 3407 3119 3408 3120 void ata_bmdma_stop(struct ata_port *ap) 3409 3121 { ··· 3517 3203 3518 3204 /** 3519 3205 * ata_interrupt - Default ATA host interrupt handler 3520 - * @irq: irq line 3521 - * @dev_instance: pointer to our host information structure 3206 + * @irq: irq line (unused) 3207 + * @dev_instance: pointer to our ata_host_set information structure 3522 3208 * @regs: unused 3523 3209 * 3210 + * Default interrupt handler for PCI IDE devices. Calls 3211 + * ata_host_intr() for each port that is not disabled. 3212 + * 3524 3213 * LOCKING: 3214 + * Obtains host_set lock during operation. 3525 3215 * 3526 3216 * RETURNS: 3217 + * IRQ_NONE or IRQ_HANDLED. 3527 3218 * 3528 3219 */ 3529 3220 ··· 3621 3302 ata_qc_complete(qc, ATA_ERR); 3622 3303 } 3623 3304 3305 + 3306 + /** 3307 + * ata_port_start - Set port up for dma. 3308 + * @ap: Port to initialize 3309 + * 3310 + * Called just after data structures for each port are 3311 + * initialized. Allocates space for PRD table. 3312 + * 3313 + * May be used as the port_start() entry in ata_port_operations. 3314 + * 3315 + * LOCKING: 3316 + */ 3317 + 3624 3318 int ata_port_start (struct ata_port *ap) 3625 3319 { 3626 3320 struct device *dev = ap->host_set->dev; ··· 3646 3314 3647 3315 return 0; 3648 3316 } 3317 + 3318 + 3319 + /** 3320 + * ata_port_stop - Undo ata_port_start() 3321 + * @ap: Port to shut down 3322 + * 3323 + * Frees the PRD table. 3324 + * 3325 + * May be used as the port_stop() entry in ata_port_operations. 3326 + * 3327 + * LOCKING: 3328 + */ 3649 3329 3650 3330 void ata_port_stop (struct ata_port *ap) 3651 3331 { ··· 3701 3357 * @ent: Probe information provided by low-level driver 3702 3358 * @port_no: Port number associated with this ata_port 3703 3359 * 3360 + * Initialize a new ata_port structure, and its associated 3361 + * scsi_host. 3362 + * 3704 3363 * LOCKING: 3364 + * Inherited from caller. 3705 3365 * 3706 3366 */ 3707 3367 ··· 3760 3412 * @host_set: Collections of ports to which we add 3761 3413 * @port_no: Port number associated with this host 3762 3414 * 3415 + * Attach low-level ATA driver to system. 3416 + * 3763 3417 * LOCKING: 3418 + * PCI/etc. bus probe sem. 3764 3419 * 3765 3420 * RETURNS: 3421 + * New ata_port on success, for NULL on error. 3766 3422 * 3767 3423 */ 3768 3424 ··· 3799 3447 } 3800 3448 3801 3449 /** 3802 - * ata_device_add - 3803 - * @ent: 3450 + * ata_device_add - Register hardware device with ATA and SCSI layers 3451 + * @ent: Probe information describing hardware device to be registered 3452 + * 3453 + * This function processes the information provided in the probe 3454 + * information struct @ent, allocates the necessary ATA and SCSI 3455 + * host information structures, initializes them, and registers 3456 + * everything with requisite kernel subsystems. 3457 + * 3458 + * This function requests irqs, probes the ATA bus, and probes 3459 + * the SCSI bus. 3804 3460 * 3805 3461 * LOCKING: 3462 + * PCI/etc. bus probe sem. 3806 3463 * 3807 3464 * RETURNS: 3465 + * Number of ports registered. Zero on error (no ports registered). 3808 3466 * 3809 3467 */ 3810 3468 ··· 3966 3604 /** 3967 3605 * ata_std_ports - initialize ioaddr with standard port offsets. 3968 3606 * @ioaddr: IO address structure to be initialized 3607 + * 3608 + * Utility function which initializes data_addr, error_addr, 3609 + * feature_addr, nsect_addr, lbal_addr, lbam_addr, lbah_addr, 3610 + * device_addr, status_addr, and command_addr to standard offsets 3611 + * relative to cmd_addr. 3612 + * 3613 + * Does not set ctl_addr, altstatus_addr, bmdma_addr, or scr_addr. 3969 3614 */ 3615 + 3970 3616 void ata_std_ports(struct ata_ioports *ioaddr) 3971 3617 { 3972 3618 ioaddr->data_addr = ioaddr->cmd_addr + ATA_REG_DATA; ··· 4015 3645 4016 3646 return probe_ent; 4017 3647 } 3648 + 3649 + 3650 + 3651 + /** 3652 + * ata_pci_init_native_mode - Initialize native-mode driver 3653 + * @pdev: pci device to be initialized 3654 + * @port: array[2] of pointers to port info structures. 3655 + * 3656 + * Utility function which allocates and initializes an 3657 + * ata_probe_ent structure for a standard dual-port 3658 + * PIO-based IDE controller. The returned ata_probe_ent 3659 + * structure can be passed to ata_device_add(). The returned 3660 + * ata_probe_ent structure should then be freed with kfree(). 3661 + */ 4018 3662 4019 3663 #ifdef CONFIG_PCI 4020 3664 struct ata_probe_ent * ··· 4111 3727 * @port_info: Information from low-level host driver 4112 3728 * @n_ports: Number of ports attached to host controller 4113 3729 * 3730 + * This is a helper function which can be called from a driver's 3731 + * xxx_init_one() probe function if the hardware uses traditional 3732 + * IDE taskfile registers. 3733 + * 3734 + * This function calls pci_enable_device(), reserves its register 3735 + * regions, sets the dma mask, enables bus master mode, and calls 3736 + * ata_device_add() 3737 + * 4114 3738 * LOCKING: 4115 3739 * Inherited from PCI layer (may sleep). 4116 3740 * 4117 3741 * RETURNS: 3742 + * Zero on success, negative on errno-based value on error. 4118 3743 * 4119 3744 */ 4120 3745 ··· 4341 3948 } 4342 3949 #endif /* CONFIG_PCI */ 4343 3950 4344 - 4345 - /** 4346 - * ata_init - 4347 - * 4348 - * LOCKING: 4349 - * 4350 - * RETURNS: 4351 - * 4352 - */ 4353 3951 4354 3952 static int __init ata_init(void) 4355 3953 {

+1 -1

drivers/scsi/libata-scsi.c

··· 947 947 } 948 948 949 949 /** 950 - * ata_scsiop_noop - 950 + * ata_scsiop_noop - Command handler that simply returns success. 951 951 * @args: device IDENTIFY data / SCSI command of interest. 952 952 * @rbuf: Response buffer, to which simulated SCSI cmd output is sent. 953 953 * @buflen: Response buffer length.

+58

include/linux/libata.h

··· 467 467 return ap->ops->check_status(ap); 468 468 } 469 469 470 + 471 + /** 472 + * ata_pause - Flush writes and pause 400 nanoseconds. 473 + * @ap: Port to wait for. 474 + * 475 + * LOCKING: 476 + * Inherited from caller. 477 + */ 478 + 470 479 static inline void ata_pause(struct ata_port *ap) 471 480 { 472 481 ata_altstatus(ap); 473 482 ndelay(400); 474 483 } 484 + 485 + 486 + /** 487 + * ata_busy_wait - Wait for a port status register 488 + * @ap: Port to wait for. 489 + * 490 + * Waits up to max*10 microseconds for the selected bits in the port's 491 + * status register to be cleared. 492 + * Returns final value of status register. 493 + * 494 + * LOCKING: 495 + * Inherited from caller. 496 + */ 475 497 476 498 static inline u8 ata_busy_wait(struct ata_port *ap, unsigned int bits, 477 499 unsigned int max) ··· 508 486 509 487 return status; 510 488 } 489 + 490 + 491 + /** 492 + * ata_wait_idle - Wait for a port to be idle. 493 + * @ap: Port to wait for. 494 + * 495 + * Waits up to 10ms for port's BUSY and DRQ signals to clear. 496 + * Returns final value of status register. 497 + * 498 + * LOCKING: 499 + * Inherited from caller. 500 + */ 511 501 512 502 static inline u8 ata_wait_idle(struct ata_port *ap) 513 503 { ··· 559 525 tf->device = ATA_DEVICE_OBS | ATA_DEV1; 560 526 } 561 527 528 + 529 + /** 530 + * ata_irq_on - Enable interrupts on a port. 531 + * @ap: Port on which interrupts are enabled. 532 + * 533 + * Enable interrupts on a legacy IDE device using MMIO or PIO, 534 + * wait for idle, clear any pending interrupts. 535 + * 536 + * LOCKING: 537 + * Inherited from caller. 538 + */ 539 + 562 540 static inline u8 ata_irq_on(struct ata_port *ap) 563 541 { 564 542 struct ata_ioports *ioaddr = &ap->ioaddr; ··· 589 543 590 544 return tmp; 591 545 } 546 + 547 + 548 + /** 549 + * ata_irq_ack - Acknowledge a device interrupt. 550 + * @ap: Port on which interrupts are enabled. 551 + * 552 + * Wait up to 10 ms for legacy IDE device to become idle (BUSY 553 + * or BUSY+DRQ clear). Obtain dma status and port status from 554 + * device. Clear the interrupt. Return port status. 555 + * 556 + * LOCKING: 557 + */ 592 558 593 559 static inline u8 ata_irq_ack(struct ata_port *ap, unsigned int chk_drq) 594 560 {

Configure Feed

Configure Feed