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