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