1.\" $NetBSD: wdc.9,v 1.4 2000/05/15 06:34:47 bouyer Exp $ 2 3.\" 4.\" Copyright (c) 1998 Manuel Bouyer. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30.\" INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\" 33.\" 34 35.Dd October 18, 1998 36.Dt wdc 9 37.Os 38.Sh NAME 39.Nm wdc 40.Nd machine-indepedant IDE/ATAPI driver 41.Sh SYNOPSIS 42.Fd #include <dev/ata/atavar.h> 43.Fd #include <sys/dev/ic/wdcvar.h> 44.Ft int 45.Fn wdcprobe "struct channel_softc * chp" 46.Ft void 47.Fn wdcattach "struct channel_softc * chp" 48.Sh description 49The 50.Nm 51driver provides the machine independant core functions for driving IDE 52devices. 53IDE devices-specific drivers ( 54.Nm wd 55or 56.Nm atapibus ) 57will use services provided by 58.Nm wdc . 59.Pp 60The machine-dependant bus front-end provides informations to 61.Nm 62vith the 63.Va wdc_softc 64and 65.Va channel_softc 66structures. 67The first one defines global controller properties, and the second contain 68per-channel informations. 69.Nm 70returns informations about the attached devices in the 71.Va ata_drive_datas 72structure. 73.Bd -literal 74struct wdc_softc { /* Per controller state */ 75 struct device sc_dev; 76 int cap; 77#define WDC_CAPABILITY_DATA16 0x0001 78#define WDC_CAPABILITY_DATA32 0x0002 79#define WDC_CAPABILITY_MODE 0x0004 80#define WDC_CAPABILITY_DMA 0x0008 81#define WDC_CAPABILITY_UDMA 0x0010 82#define WDC_CAPABILITY_HWLOCK 0x0020 83#define WDC_CAPABILITY_ATA_NOSTREAM 0x0040 84#define WDC_CAPABILITY_ATAPI_NOSTREAM 0x0080 85#define WDC_CAPABILITY_NO_EXTRA_RESETS 0x0100 86 u_int8_t pio_mode; 87 u_int8_t dma_mode; 88 int nchannels; 89 struct channel_softc *channels; 90 91 void *dma_arg; 92 int (*dma_init) __P((void *, int, int, void *, size_t, 93 void (*dma_start) __P((void *, int, int, int)); 94 int (*dma_finish) __P((void *, int, int, int)); 95#define WDC_DMA_READ 0x01 96#define WDC_DMA_POLL 0x02 97 98 int (*claim_hw) __P((void *, int)); 99 void (*free_hw) __P((void *)); 100}; 101 102struct channel_softc { /* Per channel data */ 103 int channel; 104 struct wdc_softc *wdc; 105 bus_space_tag_t cmd_iot; 106 bus_space_handle_t cmd_ioh; 107 bus_space_tag_t ctl_iot; 108 bus_space_handle_t ctl_ioh; 109 bus_space_tag_t data32iot; 110 bus_space_handle_t data32ioh; 111 int ch_flags; 112#define WDCF_ACTIVE 0x01 113#define WDCF_IRQ_WAIT 0x10 114 u_int8_t ch_status; 115 u_int8_t ch_error; 116 struct ata_drive_datas ch_drive[2]; 117 struct channel_queue *ch_queue; 118}; 119 120struct ata_drive_datas { 121 u_int8_t drive; 122 u_int8_t drive_flags; 123#define DRIVE_ATA 0x01 124#define DRIVE_ATAPI 0x02 125#define DRIVE (DRIVE_ATA|DRIVE_ATAPI) 126#define DRIVE_CAP32 0x04 127#define DRIVE_DMA 0x08 128#define DRIVE_UDMA 0x10 129#define DRIVE_MODE 0x20 130 u_int8_t PIO_mode; 131 u_int8_t DMA_mode; 132 u_int8_t UDMA_mode; 133 u_int8_t state; 134 135 struct device *drv_softc; 136 void* chnl_softc; 137}; 138 139.Ed 140 141The bus front-end needs to fill in the following elements of 142.Va wdc_softc : 143.Bl -tag -compact -width "dma_finish" -offset "xxxx" 144.It cap 145supports one or more of the WDC_CAPABILITY flags 146.It nchannels 147number of channels supported by this controller 148.It channels 149array of 150.Va struct channel_softc 151of size 152.Va nchannels 153properly initialised 154.El 155The following elements are optional: 156.Bl -tag -compact -width "dma_finish" -offset "xxxx" 157.It pio_mode 158.It dma_mode 159.It dma_arg 160.It dma_init 161.It dma_start 162.It dma_finish 163.It claim_hw 164.It free_hw 165.El 166.Pp 167The 168.Va WDC_CAPABILITY_DATA16 169and 170.Va WDC_CAPABILITY_DATA32 171flags informs 172.Nm 173wether the controller supports 16 and 32 bits I/O accesses on the data port. 174If both are set, a test will be done for each drive using the ATA or 175ATAPI IDENTIFY command, to automatically select the working mode. 176.Pp 177The 178.Va WDC_CAPABILITY_DMA 179and 180.Va WDC_CAPABILITY_UDMA 181flags are set for controllers supporting the DMA and Utra-DMA modes. 182The bus front-end needs to provide the 183.Va dma_init , 184.Va dma_start 185and 186.Va dma_finish 187functions. 188.Va dma_init 189is called just before issuing a DMA command to the IDE device. 190The arguments are, respectively: 191.Va dma_arg , 192the channel number, the drive number on this channel, 193the virtual address of the DMA buffer, the size of the transfert, and the 194.Va WDC_DMA 195flags. 196.Va dma_start 197is called just after issuing a DMA command to the IDE device. 198The arguments are, respectively: 199.Va dma_arg , 200the channel number, the drive number on this channel, and the 201.Va WDC_DMA 202flags. 203.Va dma_finish 204is called once the transfert is complete. 205The arguments are, respectively: 206.Va dma_arg , 207the channel number, the drive number on this channel, and the 208.Va WDC_DMA 209flags. 210.Va WDC_DMA_READ 211indicates the direction of the data transfert, and 212.Va WDC_DMA_POLL 213indicates if the transfert will use (or used) interrupts. 214.Pp 215The 216.Va WDC_CAPABILITY_MODE 217flag means that the bus front-end can program the PIO and DMA modes, so 218.Nm 219needs to provide back the supported modes for each drives, and set the drives 220modes. 221The 222.Va pio_mode 223and 224.Va dma_mode 225needs to be set to the hightest PIO and DMA mode supported. 226If 227.Va WDC_CAPABILITY_UDMA 228is set, then 229.Va dma_mode 230must be set to the hightest Ultra-DMA mode supported. 231If 232.Va WDC_CAPABILITY_MODE 233is not set, 234.Nm 235will not attempt to change the current drives settings, assuming the host's 236firmware has done it rigth. 237.Pp 238The 239.Va WDC_CAPABILITY_HWLOCK 240flag is set for controllers needing hardware looking before access to the 241I/O ports. 242If this flag is set, the bus front-end needs to provide the 243.Va claim_hw 244and 245.Va free_hw 246functions. 247.Va claim_hw 248will be called when the driver wants to access the controller ports. 249The second parameter is set to 1 when it is possible to sleep wainting 250for the lock, 0 otherwise. 251It should return 1 when access has been granted, 0 otherwise. 252When access has not been granted and sleep is not allowed, the bus 253front-end shall call 254.Va wdcrestart() 255with the first argument passed to 256.Va claim_hw 257as argument. 258This arguments will also be the one passed to 259.Va free_hw. 260This function is called once the transfert is complete, so that the lock can 261be released. 262.Pp 263Access to the data port are done by using the bus_space stream functions, 264unless the 265.Va WDC_CAPABILITY_ATA_NOSTREAM 266or 267.Va WDC_CAPABILITY_ATAPI_NOSTREAM 268flags are set. 269This should not be used, unless the data bus is not wired properly (which 270seems common on big-endian systems), and byte-order needs to be preserved 271for compatibility with the host's firmware. 272Also note that the IDE bus is a little-endian bus, so the bus_space 273functions used for the bus_space tag passed in the 274.Va channel_softc 275have to do the apropriate byte-swapping for big-endian systems. 276.Pp 277.Va WDC_CAPABILITY_NO_EXTRA_RESETS 278avoid the controller reset at the end of the disks probe. 279This reset is needed for some controllers, and cause problems with some 280others. 281.Pp 282The bus front-end needs to fill in the following 283elements of 284.Va channel_softc : 285.Bl -tag -compact -width "dma_finish" -offset "xxxx" 286.It channel 287The channel number on the controller 288.It wdc 289A pointer to the controller's wdc_softc 290.It cmd_iot, cmd_ioh 291Bus-space tag and handle for access to the command block registers (which 292includes the 16-bit data port) 293.It ctl_iot, ctl_ioh 294Bus-space tag and handle for access to the control block registers 295.It ch_queue 296A pointer to a 297.Va struct channel_queue . 298This will hold the queues of outstanding commands for this controller. 299.El 300The following elements are optional: 301.Bl -tag -compact -width "dma_finish" -offset "xxxx" 302.It data32iot, data32ioh 303Bus-space tag and handle for 32-bit data accesses. 304Only needed if 305.Va WDC_CAPABILITY_DATA32 306is set in the controller's 307.Va wdc_softc . 308.El 309.Pp 310.Va ch_queue 311can point to a common 312.Va struct channel_queue 313if the controller doesn't support concurent access to his different channels. 314If each channels are independant, it his recommended that each channel have 315his own 316.Va ch_queue . 317Better performances will result. 318.Pp 319The bus-specific front-end can use the 320.Va wdcprobe() 321function, with a properly inithialised 322.Va struct channel_softc 323as argument ( 324.Va wdc 325can be set to NULL. 326This allows 327.Va wdcprobe 328to be easily used in bus front-end probe functions). 329This function will return an integer where bit 0 will be set if the master 330device has been found, and 1 if the slave device has been found. 331.Pp 332The bus-specific's attach function has to call 333.Va wdcattach() 334for each channels, with a pointer to a properly initialised 335.Va channel softc 336as argument. 337This will probe devices attached to the IDE channel and attach them. 338Once this function returns, the 339.Va ch_drive 340array of the 341.Va channel_softc 342will contains the drive's capabilities. 343This can be used to properly initialise the controller's mode, or disable a 344channel without drives. 345.Pp 346The elements of interest in 347.Va ata_drive_datas 348for a bus front-end are: 349.Bl -tag -compact -width "dma_finish" -offset "xxxx" 350.It drive 351The drive number 352.It drive_flags 353Flags indicating the drive capabilities. 354A null 355.Va drive_flags 356indicate either that no drive are here, or that no driver was 357found for this device. 358.It PIO_mode, DMA_mode, UDMA_mode 359the hightest supported modes for this drive compatible with the controller's 360capabilities. 361Needs to be reset to the mode to use by the drive, if known. 362.It drv_softc 363A pointer to the drive's softc. 364Can be used to print the drive's name. 365.El 366.Pp 367.Va drive_flags 368handles the following flags: 369.Bl -tag -compact -width "dma_finish" -offset "xxxx" 370.It DRIVE_ATA, DRIVE_ATAPI 371Gives the drive type, if any. 372The shortcut DRIVE can be used to just test the presence/absence of a drive. 373.It DRIVE_CAP32 374This drive works with 32-bit data I/O. 375.It DRIVE_DMA 376This drive supports DMA 377.It DRIVE_UDMA 378This drive supports Ultra-DMA 379.It DRIVE_MODE 380This drive properly reported its PIO and DMA mode. 381.El 382.Pp 383Once the controller has been initialised, it has to reset the 384.Va DRIVE_DMA 385and 386.Va DRIVE_UDMA , 387as well as the values of 388.Va PIO_mode , 389.Va DMA_mode 390and 391.Va UDMA_mode 392if the modes to be used are not hightest ones supported by the drive. 393.Sh SEE ALSO 394.Xr wdc 4 395.Xr bus_space 9 396.Sh CODE REFERENCES 397The wdc core functions are implemented in 398.Pa sys/dev/ic/wdc.c . 399Low-level ATA and ATAPI support is provided by 400.Pa sys/dev/ata_wdc.c 401and 402.Pa sys/dev/scsipi/atapi_wdc.c 403respectively. 404.Pp 405An example of simple bus front-end can be found in 406.Pa sys/dev/isapnp/wdc_isapnp.c . 407A more complex one, with multiple channels and bus-master DMA support is 408.Pa sys/dev/pci/pciide.c . 409.Pa sys/arch/atari/dev/wdc_mb.c 410makes use of hardware locking, and also provides an example of bus-front 411end for a big-endian system, which needs byte-swapping bus_space functions. 412