Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/uebayasi-xip]: src/share/man/man9 Use .Dv instead of .Va for #defined co...
details: https://anonhg.NetBSD.org/src/rev/f9e63b23c0f5
branches: uebayasi-xip
changeset: 751666:f9e63b23c0f5
user: jruoho <jruoho%NetBSD.org@localhost>
date: Sun Apr 18 15:19:18 2010 +0000
description:
Use .Dv instead of .Va for #defined constants.
diffstat:
share/man/man9/wdc.9 | 412 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 412 insertions(+), 0 deletions(-)
diffs (truncated from 416 to 300 lines):
diff -r 237d124f6fa3 -r f9e63b23c0f5 share/man/man9/wdc.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/wdc.9 Sun Apr 18 15:19:18 2010 +0000
@@ -0,0 +1,412 @@
+.\" $NetBSD: wdc.9,v 1.17.2.2 2010/04/18 15:19:18 jruoho 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.
+.\"
+.\" 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 April 18, 2010
+.Dt WDC 9
+.Os
+.Sh NAME
+.Nm wdc
+.Nd machine-independent IDE/ATAPI driver
+.Sh SYNOPSIS
+.In dev/ata/atavar.h
+.In sys/dev/ic/wdcvar.h
+.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
+.Po
+.Xr wd 4
+or
+.Xr atapibus 4
+.Pc
+will use services provided by
+.Nm .
+.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
+#define WDC_CAPABILITY_PREATA 0x0200
+#define WDC_CAPABILITY_IRQACK 0x0400
+#define WDC_CAPABILITY_SINGLE_DRIVE 0x0800
+#define WDC_CAPABILITY_NOIRQ 0x1000
+#define WDC_CAPABILITY_SELECT 0x2000
+ uint8_t pio_mode;
+ uint8_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
+ uint8_t ch_status;
+ uint8_t ch_error;
+ struct ata_drive_datas ch_drive[2];
+ struct channel_queue *ch_queue;
+};
+
+struct ata_drive_datas {
+ uint8_t drive;
+ uint8_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
+ uint8_t PIO_mode;
+ uint8_t DMA_mode;
+ uint8_t UDMA_mode;
+ uint8_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
+.Dv WDC_CAPABILITY_DATA16
+and
+.Dv 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
+.Dv WDC_CAPABILITY_DMA
+and
+.Dv 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
+.Dv 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
+.Dv 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
+.Dv WDC_DMA
+flags.
+.Dv WDC_DMA_READ
+indicates the direction of the data transfer, and
+.Dv WDC_DMA_POLL
+indicates if the transfer will use (or used) interrupts.
+.Pp
+The
+.Dv 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
+.Dv WDC_CAPABILITY_UDMA
+is set, then
+.Va dma_mode
+must be set to the highest Ultra-DMA mode supported.
+If
+.Dv 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
+.Dv 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
+.Dv WDC_CAPABILITY_ATA_NOSTREAM
+or
+.Dv 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
+.Dv 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
+.Dv WDC_CAPABILITY_NOIRQ
+tells the driver that this controller doesn't have its interrupt lines
+wired up usefully, so it should always use polled transfers.
+.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
Home |
Main Index |
Thread Index |
Old Index