Aren
/
NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve grammar and formatting, fix some typos.

This commit is contained in:
wiz 2001-06-21 11:51:32 +00:00
parent c242c84057
commit ad3ce1d8c4
1 changed files with 55 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
share/man/man9/wdc.9
View File

@ -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 .