1.\" $NetBSD: wdc.9,v 1.9 2002/02/13 08:18:57 ross 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 u_int8_t pio_mode; 85 u_int8_t dma_mode; 86 int nchannels; 87 struct channel_softc *channels; 88 89 void *dma_arg; 90 int (*dma_init)(void *, int, int, void *, size_t, int); 91 void (*dma_start)(void *, int, int, int); 92 int (*dma_finish)(void *, int, int, int); 93#define WDC_DMA_READ 0x01 94#define WDC_DMA_POLL 0x02 95 96 int (*claim_hw)(void *, int); 97 void (*free_hw)(void *); 98}; 99 100struct channel_softc { /* Per channel data */ 101 int channel; 102 struct wdc_softc *wdc; 103 bus_space_tag_t cmd_iot; 104 bus_space_handle_t cmd_ioh; 105 bus_space_tag_t ctl_iot; 106 bus_space_handle_t ctl_ioh; 107 bus_space_tag_t data32iot; 108 bus_space_handle_t data32ioh; 109 int ch_flags; 110#define WDCF_ACTIVE 0x01 111#define WDCF_IRQ_WAIT 0x10 112 u_int8_t ch_status; 113 u_int8_t ch_error; 114 struct ata_drive_datas ch_drive[2]; 115 struct channel_queue *ch_queue; 116}; 117 118struct ata_drive_datas { 119 u_int8_t drive; 120 u_int8_t drive_flags; 121#define DRIVE_ATA 0x01 122#define DRIVE_ATAPI 0x02 123#define DRIVE (DRIVE_ATA|DRIVE_ATAPI) 124#define DRIVE_CAP32 0x04 125#define DRIVE_DMA 0x08 126#define DRIVE_UDMA 0x10 127#define DRIVE_MODE 0x20 128 u_int8_t PIO_mode; 129 u_int8_t DMA_mode; 130 u_int8_t UDMA_mode; 131 u_int8_t state; 132 133 struct device *drv_softc; 134 void* chnl_softc; 135}; 136.Ed 137.Pp 138The bus front-end needs to fill in the following elements of 139.Va wdc_softc : 140.Bl -tag -compact -width "dma_finish" -offset "xxxx" 141.It cap 142supports one or more of the WDC_CAPABILITY flags 143.It nchannels 144number of channels supported by this controller 145.It channels 146array of 147.Va struct channel_softc 148of size 149.Va nchannels 150properly initialised 151.El 152The following elements are optional: 153.Bl -tag -compact -width "dma_finish" -offset "xxxx" 154.It pio_mode 155.It dma_mode 156.It dma_arg 157.It dma_init 158.It dma_start 159.It dma_finish 160.It claim_hw 161.It free_hw 162.El 163.Pp 164The 165.Va WDC_CAPABILITY_DATA16 166and 167.Va WDC_CAPABILITY_DATA32 168flags informs 169.Nm 170whether the controller supports 16- or 32-bit I/O accesses on the data port. 171If both are set, a test will be done for each drive using the ATA or 172ATAPI IDENTIFY command, to automatically select the working mode. 173.Pp 174The 175.Va WDC_CAPABILITY_DMA 176and 177.Va WDC_CAPABILITY_UDMA 178flags are set for controllers supporting the DMA and Ultra-DMA modes. 179The bus front-end needs to provide the 180.Fn dma_init , 181.Fn dma_start 182and 183.Fn dma_finish 184functions. 185.Fn dma_init 186is called just before issuing a DMA command to the IDE device. 187The arguments are, respectively: 188.Va dma_arg , 189the channel number, the drive number on this channel, 190the virtual address of the DMA buffer, the size of the transfer, and the 191.Va WDC_DMA 192flags. 193.Fn dma_start 194is called just after issuing a DMA command to the IDE device. 195The arguments are, respectively: 196.Va dma_arg , 197the channel number, the drive number on this channel, and the 198.Va WDC_DMA 199flags. 200.Fn dma_finish 201is called once the transfer is complete. 202The arguments are, respectively: 203.Va dma_arg , 204the channel number, the drive number on this channel, and the 205.Va WDC_DMA 206flags. 207.Va WDC_DMA_READ 208indicates the direction of the data transfer, and 209.Va WDC_DMA_POLL 210indicates if the transfer will use (or used) interrupts. 211.Pp 212The 213.Va WDC_CAPABILITY_MODE 214flag means that the bus front-end can program the PIO and DMA modes, so 215.Nm 216needs to provide back the supported modes for each drive, and set the drives 217modes. 218The 219.Va pio_mode 220and 221.Va dma_mode 222needs to be set to the highest PIO and DMA mode supported. 223If 224.Va WDC_CAPABILITY_UDMA 225is set, then 226.Va dma_mode 227must be set to the highest Ultra-DMA mode supported. 228If 229.Va WDC_CAPABILITY_MODE 230is not set, 231.Nm 232will not attempt to change the current drive's settings, assuming the host's 233firmware has done it right. 234.Pp 235The 236.Va WDC_CAPABILITY_HWLOCK 237flag is set for controllers needing hardware looking before accessing the 238I/O ports. 239If this flag is set, the bus front-end needs to provide the 240.Fn claim_hw 241and 242.Fn free_hw 243functions. 244.Fn claim_hw 245will be called when the driver wants to access the controller ports. 246The second parameter is set to 1 when it is possible to sleep waiting 247for the lock, 0 otherwise. 248It should return 1 when access has been granted, 0 otherwise. 249When access has not been granted and sleep is not allowed, the bus 250front-end shall call 251.Fn wdcrestart 252with the first argument passed to 253.Fn claim_hw 254as argument. 255This arguments will also be the one passed to 256.Fn free_hw . 257This function is called once the transfer is complete, so that the lock can 258be released. 259.Pp 260Accesses to the data port are done by using the bus_space stream functions, 261unless the 262.Va WDC_CAPABILITY_ATA_NOSTREAM 263or 264.Va WDC_CAPABILITY_ATAPI_NOSTREAM 265flags are set. 266This should not be used, unless the data bus is not wired properly (which 267seems common on big-endian systems), and byte-order needs to be preserved 268for compatibility with the host's firmware. 269Also note that the IDE bus is a little-endian bus, so the bus_space 270functions used for the bus_space tag passed in the 271.Va channel_softc 272have to do the appropriate byte-swapping for big-endian systems. 273.Pp 274.Va WDC_CAPABILITY_NO_EXTRA_RESETS 275avoid the controller reset at the end of the disks probe. 276This reset is needed for some controllers, but causes problems with some 277others. 278.Pp 279The bus front-end needs to fill in the following 280elements of 281.Va channel_softc : 282.Bl -tag -compact -width "dma_finish" -offset "xxxx" 283.It channel 284The channel number on the controller 285.It wdc 286A pointer to the controller's wdc_softc 287.It cmd_iot, cmd_ioh 288Bus-space tag and handle for access to the command block registers (which 289includes the 16-bit data port) 290.It ctl_iot, ctl_ioh 291Bus-space tag and handle for access to the control block registers 292.It ch_queue 293A pointer to a 294.Va struct channel_queue . 295This will hold the queues of outstanding commands for this controller. 296.El 297The following elements are optional: 298.Bl -tag -compact -width "dma_finish" -offset "xxxx" 299.It data32iot, data32ioh 300Bus-space tag and handle for 32-bit data accesses. 301Only needed if 302.Va WDC_CAPABILITY_DATA32 303is set in the controller's 304.Va wdc_softc . 305.El 306.Pp 307.Va ch_queue 308can point to a common 309.Va struct channel_queue 310if the controller doesn't support concurrent access to its different channels. 311If all channels are independent, it is recommended that each channel has 312its own 313.Va ch_queue 314(for better performance). 315.Pp 316The bus-specific front-end can use the 317.Fn wdcprobe 318function, with a properly initialised 319.Va struct channel_softc 320as argument ( 321.Va wdc 322can be set to NULL. 323This allows 324.Fn wdcprobe 325to be easily used in bus front-end probe functions). 326This function will return an integer where bit 0 will be set if the master 327device has been found, and 1 if the slave device has been found. 328.Pp 329The bus-specific attach function has to call 330.Fn wdcattach 331for each channel, with a pointer to a properly initialised 332.Va channel softc 333as argument. 334This will probe devices attached to the IDE channel and attach them. 335Once this function returns, the 336.Va ch_drive 337array of the 338.Va channel_softc 339will contain the drive's capabilities. 340This can be used to properly initialise the controller's mode, or disable a 341channel without drives. 342.Pp 343The elements of interest in 344.Va ata_drive_datas 345for a bus front-end are: 346.Bl -tag -compact -width "dma_finish" -offset "xxxx" 347.It drive 348The drive number 349.It drive_flags 350Flags indicating the drive capabilities. 351A null 352.Va drive_flags 353indicate either that no drive is here, or that no driver was 354found for this device. 355.It PIO_mode, DMA_mode, UDMA_mode 356the highest supported modes for this drive compatible with the controller's 357capabilities. 358Needs to be reset to the mode to use by the drive, if known. 359.It drv_softc 360A pointer to the drive's softc. 361Can be used to print the drive's name. 362.El 363.Pp 364.Va drive_flags 365handles the following flags: 366.Bl -tag -compact -width "dma_finish" -offset "xxxx" 367.It DRIVE_ATA, DRIVE_ATAPI 368Gives the drive type, if any. 369The shortcut DRIVE can be used to just test the presence/absence of a drive. 370.It DRIVE_CAP32 371This drive works with 32-bit data I/O. 372.It DRIVE_DMA 373This drive supports DMA. 374.It DRIVE_UDMA 375This drive supports Ultra-DMA. 376.It DRIVE_MODE 377This drive properly reported its PIO and DMA mode. 378.El 379.Pp 380Once the controller has been initialised, it has to reset the 381.Va DRIVE_DMA 382and 383.Va DRIVE_UDMA , 384as well as the values of 385.Va PIO_mode , 386.Va DMA_mode 387and 388.Va UDMA_mode 389if the modes to be used are not highest ones supported by the drive. 390.Sh SEE ALSO 391.Xr wdc 4 , 392.Xr bus_space 9 393.Sh CODE REFERENCES 394The wdc core functions are implemented in 395.Pa sys/dev/ic/wdc.c . 396Low-level ATA and ATAPI support is provided by 397.Pa sys/dev/ata_wdc.c 398and 399.Pa sys/dev/scsipi/atapi_wdc.c 400respectively. 401.Pp 402An example of a simple bus front-end can be found in 403.Pa sys/dev/isapnp/wdc_isapnp.c . 404A more complex one, with multiple channels and bus-master DMA support is 405.Pa sys/dev/pci/pciide.c . 406.Pa sys/arch/atari/dev/wdc_mb.c 407makes use of hardware locking, and also provides an example of bus-front 408end for a big-endian system, which needs byte-swapping bus_space functions. 409