diff --git a/share/man/man9/wdc.9 b/share/man/man9/wdc.9 index e567ab172719..9accedfedc57 100644 --- a/share/man/man9/wdc.9 +++ b/share/man/man9/wdc.9 @@ -1,4 +1,4 @@ -.\" $NetBSD: wdc.9,v 1.6 2001/06/05 12:56:03 wiz Exp $ +.\" $NetBSD: wdc.9,v 1.7 2001/06/21 11:51:32 wiz Exp $ .\" .\" Copyright (c) 1998 Manuel Bouyer. .\" @@ -43,7 +43,7 @@ .Fn wdcprobe "struct channel_softc * chp" .Ft void .Fn wdcattach "struct channel_softc * chp" -.Sh description +.Sh DESCRIPTION The .Nm driver provides the machine independent core functions for driving IDE @@ -57,12 +57,12 @@ will use services provided by .Pp The machine-dependent bus front-end provides informations to .Nm -vith the +with the .Va wdc_softc and .Va channel_softc structures. -The first one defines global controller properties, and the second contain +The first one defines global controller properties, and the second contains per-channel informations. .Nm returns informations about the attached devices in the @@ -133,16 +133,15 @@ struct ata_drive_datas { 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 +number of channels supported by this controller .It channels array of .Va struct channel_softc @@ -168,7 +167,7 @@ and .Va WDC_CAPABILITY_DATA32 flags informs .Nm -wether the controller supports 16 and 32 bits I/O accesses on the data port. +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 @@ -176,89 +175,89 @@ The .Va WDC_CAPABILITY_DMA and .Va WDC_CAPABILITY_UDMA -flags are set for controllers supporting the DMA and Utra-DMA modes. +flags are set for controllers supporting the DMA and Ultra-DMA modes. The bus front-end needs to provide the -.Va dma_init , -.Va dma_start +.Fn dma_init , +.Fn dma_start and -.Va dma_finish +.Fn dma_finish functions. -.Va dma_init +.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 transfert, and the +the virtual address of the DMA buffer, the size of the transfer, and the .Va WDC_DMA flags. -.Va dma_start +.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. -.Va dma_finish -is called once the transfert is complete. +.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 transfert, and +indicates the direction of the data transfer, and .Va WDC_DMA_POLL -indicates if the transfert will use (or used) interrupts. +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 drives, and set the drives +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 hightest PIO and DMA mode supported. +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 hightest Ultra-DMA mode supported. +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 drives settings, assuming the host's -firmware has done it rigth. +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 access to the +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 -.Va claim_hw +.Fn claim_hw and -.Va free_hw +.Fn free_hw functions. -.Va claim_hw +.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 wainting +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 -.Va wdcrestart() +.Fn wdcrestart with the first argument passed to -.Va claim_hw +.Fn claim_hw as argument. This arguments will also be the one passed to -.Va free_hw. -This function is called once the transfert is complete, so that the lock can +.Fn free_hw . +This function is called once the transfer is complete, so that the lock can be released. .Pp -Access to the data port are done by using the bus_space stream functions, +Accesses to the data port are done by using the bus_space stream functions, unless the .Va WDC_CAPABILITY_ATA_NOSTREAM or @@ -270,11 +269,11 @@ 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 apropriate byte-swapping for big-endian systems. +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, and cause problems with some +This reset is needed for some controllers, but causes problems with some others. .Pp The bus front-end needs to fill in the following @@ -308,28 +307,28 @@ is set in the controller's .Va ch_queue can point to a common .Va struct channel_queue -if the controller doesn't support concurent access to his different channels. -If each channels are independent, it his recommended that each channel have -his own -.Va ch_queue . -Better performances will result. +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 -.Va wdcprobe() -function, with a properly inithialised +.Fn wdcprobe +function, with a properly initialised .Va struct channel_softc as argument ( .Va wdc can be set to NULL. This allows -.Va wdcprobe +.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's attach function has to call -.Va wdcattach() -for each channels, with a pointer to a properly initialised +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. @@ -337,7 +336,7 @@ Once this function returns, the .Va ch_drive array of the .Va channel_softc -will contains the drive's capabilities. +will contain the drive's capabilities. This can be used to properly initialise the controller's mode, or disable a channel without drives. .Pp @@ -351,10 +350,10 @@ The drive number Flags indicating the drive capabilities. A null .Va drive_flags -indicate either that no drive are here, or that no driver was +indicate either that no drive is here, or that no driver was found for this device. .It PIO_mode, DMA_mode, UDMA_mode -the hightest supported modes for this drive compatible with the controller's +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 @@ -371,9 +370,9 @@ 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 +This drive supports DMA. .It DRIVE_UDMA -This drive supports Ultra-DMA +This drive supports Ultra-DMA. .It DRIVE_MODE This drive properly reported its PIO and DMA mode. .El @@ -386,10 +385,10 @@ as well as the values of .Va PIO_mode , .Va DMA_mode and -.Va UDMA_mode -if the modes to be used are not hightest ones supported by the drive. +.Va UDMA_mode +if the modes to be used are not highest ones supported by the drive. .Sh SEE ALSO -.Xr wdc 4 +.Xr wdc 4 , .Xr bus_space 9 .Sh CODE REFERENCES The wdc core functions are implemented in @@ -400,7 +399,7 @@ and .Pa sys/dev/scsipi/atapi_wdc.c respectively. .Pp -An example of simple bus front-end can be found in +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 .