.\" $NetBSD: wdc.9,v 1.8 2001/11/28 16:48:11 wiz Exp $ .\" .\" Copyright (c) 1998 Manuel Bouyer. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" .Dd October 18, 1998 .Dt WDC 9 .Os .Sh NAME .Nm wdc .Nd machine-independent IDE/ATAPI driver .Sh SYNOPSIS .Fd #include .Fd #include .Ft int .Fn wdcprobe "struct channel_softc * chp" .Ft void .Fn wdcattach "struct channel_softc * chp" .Sh DESCRIPTION The .Nm driver provides the machine independent core functions for driving IDE devices. IDE devices-specific drivers ( .Nm wd or .Nm atapibus ) will use services provided by .Nm wdc . .Pp The machine-dependent bus front-end provides informations to .Nm with the .Va wdc_softc and .Va channel_softc structures. The first one defines global controller properties, and the second contains per-channel informations. .Nm returns informations about the attached devices in the .Va ata_drive_datas structure. .Bd -literal struct wdc_softc { /* Per controller state */ struct device sc_dev; int cap; #define WDC_CAPABILITY_DATA16 0x0001 #define WDC_CAPABILITY_DATA32 0x0002 #define WDC_CAPABILITY_MODE 0x0004 #define WDC_CAPABILITY_DMA 0x0008 #define WDC_CAPABILITY_UDMA 0x0010 #define WDC_CAPABILITY_HWLOCK 0x0020 #define WDC_CAPABILITY_ATA_NOSTREAM 0x0040 #define WDC_CAPABILITY_ATAPI_NOSTREAM 0x0080 #define WDC_CAPABILITY_NO_EXTRA_RESETS 0x0100 u_int8_t pio_mode; u_int8_t dma_mode; int nchannels; struct channel_softc *channels; void *dma_arg; int (*dma_init)(void *, int, int, void *, size_t, int); void (*dma_start)(void *, int, int, int); int (*dma_finish)(void *, int, int, int); #define WDC_DMA_READ 0x01 #define WDC_DMA_POLL 0x02 int (*claim_hw)(void *, int); void (*free_hw)(void *); }; struct channel_softc { /* Per channel data */ int channel; struct wdc_softc *wdc; bus_space_tag_t cmd_iot; bus_space_handle_t cmd_ioh; bus_space_tag_t ctl_iot; bus_space_handle_t ctl_ioh; bus_space_tag_t data32iot; bus_space_handle_t data32ioh; int ch_flags; #define WDCF_ACTIVE 0x01 #define WDCF_IRQ_WAIT 0x10 u_int8_t ch_status; u_int8_t ch_error; struct ata_drive_datas ch_drive[2]; struct channel_queue *ch_queue; }; struct ata_drive_datas { u_int8_t drive; u_int8_t drive_flags; #define DRIVE_ATA 0x01 #define DRIVE_ATAPI 0x02 #define DRIVE (DRIVE_ATA|DRIVE_ATAPI) #define DRIVE_CAP32 0x04 #define DRIVE_DMA 0x08 #define DRIVE_UDMA 0x10 #define DRIVE_MODE 0x20 u_int8_t PIO_mode; u_int8_t DMA_mode; u_int8_t UDMA_mode; u_int8_t state; struct device *drv_softc; void* chnl_softc; }; .Ed .Pp The bus front-end needs to fill in the following elements of .Va wdc_softc : .Bl -tag -compact -width "dma_finish" -offset "xxxx" .It cap supports one or more of the WDC_CAPABILITY flags .It nchannels number of channels supported by this controller .It channels array of .Va struct channel_softc of size .Va nchannels properly initialised .El The following elements are optional: .Bl -tag -compact -width "dma_finish" -offset "xxxx" .It pio_mode .It dma_mode .It dma_arg .It dma_init .It dma_start .It dma_finish .It claim_hw .It free_hw .El .Pp The .Va WDC_CAPABILITY_DATA16 and .Va WDC_CAPABILITY_DATA32 flags informs .Nm whether the controller supports 16- or 32-bit I/O accesses on the data port. If both are set, a test will be done for each drive using the ATA or ATAPI IDENTIFY command, to automatically select the working mode. .Pp The .Va WDC_CAPABILITY_DMA and .Va WDC_CAPABILITY_UDMA flags are set for controllers supporting the DMA and Ultra-DMA modes. The bus front-end needs to provide the .Fn dma_init , .Fn dma_start and .Fn dma_finish functions. .Fn dma_init is called just before issuing a DMA command to the IDE device. The arguments are, respectively: .Va dma_arg , the channel number, the drive number on this channel, the virtual address of the DMA buffer, the size of the transfer, and the .Va WDC_DMA flags. .Fn dma_start is called just after issuing a DMA command to the IDE device. The arguments are, respectively: .Va dma_arg , the channel number, the drive number on this channel, and the .Va WDC_DMA flags. .Fn dma_finish is called once the transfer is complete. The arguments are, respectively: .Va dma_arg , the channel number, the drive number on this channel, and the .Va WDC_DMA flags. .Va WDC_DMA_READ indicates the direction of the data transfer, and .Va WDC_DMA_POLL indicates if the transfer will use (or used) interrupts. .Pp The .Va WDC_CAPABILITY_MODE flag means that the bus front-end can program the PIO and DMA modes, so .Nm needs to provide back the supported modes for each drive, and set the drives modes. The .Va pio_mode and .Va dma_mode needs to be set to the highest PIO and DMA mode supported. If .Va WDC_CAPABILITY_UDMA is set, then .Va dma_mode must be set to the highest Ultra-DMA mode supported. If .Va WDC_CAPABILITY_MODE is not set, .Nm will not attempt to change the current drive's settings, assuming the host's firmware has done it right. .Pp The .Va WDC_CAPABILITY_HWLOCK flag is set for controllers needing hardware looking before accessing the I/O ports. If this flag is set, the bus front-end needs to provide the .Fn claim_hw and .Fn free_hw functions. .Fn claim_hw will be called when the driver wants to access the controller ports. The second parameter is set to 1 when it is possible to sleep waiting for the lock, 0 otherwise. It should return 1 when access has been granted, 0 otherwise. When access has not been granted and sleep is not allowed, the bus front-end shall call .Fn wdcrestart with the first argument passed to .Fn claim_hw as argument. This arguments will also be the one passed to .Fn free_hw . This function is called once the transfer is complete, so that the lock can be released. .Pp Accesses to the data port are done by using the bus_space stream functions, unless the .Va WDC_CAPABILITY_ATA_NOSTREAM or .Va WDC_CAPABILITY_ATAPI_NOSTREAM flags are set. This should not be used, unless the data bus is not wired properly (which seems common on big-endian systems), and byte-order needs to be preserved for compatibility with the host's firmware. Also note that the IDE bus is a little-endian bus, so the bus_space functions used for the bus_space tag passed in the .Va channel_softc have to do the appropriate byte-swapping for big-endian systems. .Pp .Va WDC_CAPABILITY_NO_EXTRA_RESETS avoid the controller reset at the end of the disks probe. This reset is needed for some controllers, but causes problems with some others. .Pp The bus front-end needs to fill in the following elements of .Va channel_softc : .Bl -tag -compact -width "dma_finish" -offset "xxxx" .It channel The channel number on the controller .It wdc A pointer to the controller's wdc_softc .It cmd_iot, cmd_ioh Bus-space tag and handle for access to the command block registers (which includes the 16-bit data port) .It ctl_iot, ctl_ioh Bus-space tag and handle for access to the control block registers .It ch_queue A pointer to a .Va struct channel_queue . This will hold the queues of outstanding commands for this controller. .El The following elements are optional: .Bl -tag -compact -width "dma_finish" -offset "xxxx" .It data32iot, data32ioh Bus-space tag and handle for 32-bit data accesses. Only needed if .Va WDC_CAPABILITY_DATA32 is set in the controller's .Va wdc_softc . .El .Pp .Va ch_queue can point to a common .Va struct channel_queue if the controller doesn't support concurrent access to its different channels. If all channels are independent, it is recommended that each channel has its own .Va ch_queue (for better performance). .Pp The bus-specific front-end can use the .Fn wdcprobe function, with a properly initialised .Va struct channel_softc as argument ( .Va wdc can be set to NULL. This allows .Fn wdcprobe to be easily used in bus front-end probe functions). This function will return an integer where bit 0 will be set if the master device has been found, and 1 if the slave device has been found. .Pp The bus-specific attach function has to call .Fn wdcattach for each channel, with a pointer to a properly initialised .Va channel softc as argument. This will probe devices attached to the IDE channel and attach them. Once this function returns, the .Va ch_drive array of the .Va channel_softc will contain the drive's capabilities. This can be used to properly initialise the controller's mode, or disable a channel without drives. .Pp The elements of interest in .Va ata_drive_datas for a bus front-end are: .Bl -tag -compact -width "dma_finish" -offset "xxxx" .It drive The drive number .It drive_flags Flags indicating the drive capabilities. A null .Va drive_flags indicate either that no drive is here, or that no driver was found for this device. .It PIO_mode, DMA_mode, UDMA_mode the highest supported modes for this drive compatible with the controller's capabilities. Needs to be reset to the mode to use by the drive, if known. .It drv_softc A pointer to the drive's softc. Can be used to print the drive's name. .El .Pp .Va drive_flags handles the following flags: .Bl -tag -compact -width "dma_finish" -offset "xxxx" .It DRIVE_ATA, DRIVE_ATAPI Gives the drive type, if any. The shortcut DRIVE can be used to just test the presence/absence of a drive. .It DRIVE_CAP32 This drive works with 32-bit data I/O. .It DRIVE_DMA This drive supports DMA. .It DRIVE_UDMA This drive supports Ultra-DMA. .It DRIVE_MODE This drive properly reported its PIO and DMA mode. .El .Pp Once the controller has been initialised, it has to reset the .Va DRIVE_DMA and .Va DRIVE_UDMA , as well as the values of .Va PIO_mode , .Va DMA_mode and .Va UDMA_mode if the modes to be used are not highest ones supported by the drive. .Sh SEE ALSO .Xr wdc 4 , .Xr bus_space 9 .Sh CODE REFERENCES The wdc core functions are implemented in .Pa sys/dev/ic/wdc.c . Low-level ATA and ATAPI support is provided by .Pa sys/dev/ata_wdc.c and .Pa sys/dev/scsipi/atapi_wdc.c respectively. .Pp An example of a simple bus front-end can be found in .Pa sys/dev/isapnp/wdc_isapnp.c . A more complex one, with multiple channels and bus-master DMA support is .Pa sys/dev/pci/pciide.c . .Pa sys/arch/atari/dev/wdc_mb.c makes use of hardware locking, and also provides an example of bus-front end for a big-endian system, which needs byte-swapping bus_space functions.