Unix/Linux Go Back    


NetBSD 6.1.5 - man page for wdc (netbsd section 9)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


WDC(9)				  BSD Kernel Developer's Manual 			   WDC(9)

NAME
     wdc -- machine-independent IDE/ATAPI driver

SYNOPSIS
     #include <dev/ata/atavar.h>
     #include <sys/dev/ic/wdcvar.h>

     int
     wdcprobe(struct channel_softc * chp);

     void
     wdcattach(struct channel_softc * chp);

DESCRIPTION
     The wdc driver provides the machine independent core functions for driving IDE devices.  IDE
     devices-specific drivers (wd(4) or atapibus(4)) will use services provided by wdc.

     The machine-dependent bus front-end provides informations to wdc with the wdc_softc and
     channel_softc structures.	The first one defines global controller properties, and the sec-
     ond contains per-channel informations.  wdc returns informations about the attached devices
     in the ata_drive_datas structure.

     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;
     };

     The bus front-end needs to fill in the following elements of wdc_softc:
	 cap	     supports one or more of the WDC_CAPABILITY flags
	 nchannels   number of channels supported by this controller
	 channels    array of struct channel_softc of size nchannels properly initialised
     The following elements are optional:
	 pio_mode
	 dma_mode
	 dma_arg
	 dma_init
	 dma_start
	 dma_finish
	 claim_hw
	 free_hw

     The WDC_CAPABILITY_DATA16 and WDC_CAPABILITY_DATA32 flags informs wdc 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.

     The WDC_CAPABILITY_DMA and WDC_CAPABILITY_UDMA flags are set for controllers supporting the
     DMA and Ultra-DMA modes.  The bus front-end needs to provide the dma_init(), dma_start() and
     dma_finish() functions.  dma_init() is called just before issuing a DMA command to the IDE
     device.  The arguments are, respectively: 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
     WDC_DMA flags.  dma_start() is called just after issuing a DMA command to the IDE device.
     The arguments are, respectively: dma_arg, the channel number, the drive number on this chan-
     nel, and the WDC_DMA flags.  dma_finish() is called once the transfer is complete.  The
     arguments are, respectively: dma_arg, the channel number, the drive number on this channel,
     and the WDC_DMA flags.  WDC_DMA_READ indicates the direction of the data transfer, and
     WDC_DMA_POLL indicates if the transfer will use (or used) interrupts.

     The WDC_CAPABILITY_MODE flag means that the bus front-end can program the PIO and DMA modes,
     so wdc needs to provide back the supported modes for each drive, and set the drives modes.
     The pio_mode and dma_mode needs to be set to the highest PIO and DMA mode supported.  If
     WDC_CAPABILITY_UDMA is set, then dma_mode must be set to the highest Ultra-DMA mode sup-
     ported.  If WDC_CAPABILITY_MODE is not set, wdc will not attempt to change the current
     drive's settings, assuming the host's firmware has done it right.

     The 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
     claim_hw() and free_hw() functions.  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 oth-
     erwise.  When access has not been granted and sleep is not allowed, the bus front-end shall
     call wdcrestart() with the first argument passed to claim_hw() as argument.  This arguments
     will also be the one passed to free_hw().	This function is called once the transfer is com-
     plete, so that the lock can be released.

     Accesses to the data port are done by using the bus_space stream functions, unless the
     WDC_CAPABILITY_ATA_NOSTREAM or 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 sys-
     tems), 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 channel_softc have to do the appropriate byte-swapping for big-
     endian systems.

     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.

     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.

     The bus front-end needs to fill in the following elements of channel_softc:
	 channel     The channel number on the controller
	 wdc	     A pointer to the controller's wdc_softc
	 cmd_iot, cmd_ioh
		     Bus-space tag and handle for access to the command block registers (which
		     includes the 16-bit data port)
	 ctl_iot, ctl_ioh
		     Bus-space tag and handle for access to the control block registers
	 ch_queue    A pointer to a struct channel_queue.  This will hold the queues of outstand-
		     ing commands for this controller.
     The following elements are optional:
	 data32iot, data32ioh
		     Bus-space tag and handle for 32-bit data accesses.  Only needed if
		     WDC_CAPABILITY_DATA32 is set in the controller's wdc_softc.

     ch_queue can point to a common struct channel_queue if the controller doesn't support con-
     current access to its different channels.	If all channels are independent, it is recom-
     mended that each channel has its own ch_queue (for better performance).

     The bus-specific front-end can use the wdcprobe() function, with a properly initialised
     struct channel_softc as argument ( wdc can be set to NULL.  This allows 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.

     The bus-specific attach function has to call wdcattach() for each channel, with a pointer to
     a properly initialised channel softc as argument.	This will probe devices attached to the
     IDE channel and attach them.  Once this function returns, the ch_drive array of the
     channel_softc will contain the drive's capabilities.  This can be used to properly ini-
     tialise the controller's mode, or disable a channel without drives.

     The elements of interest in ata_drive_datas for a bus front-end are:
	 drive	     The drive number
	 drive_flags
		     Flags indicating the drive capabilities.  A null drive_flags indicate either
		     that no drive is here, or that no driver was found for this device.
	 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.
	 drv_softc   A pointer to the drive's softc.  Can be used to print the drive's name.

     drive_flags handles the following flags:
	 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.
	 DRIVE_CAP32
		     This drive works with 32-bit data I/O.
	 DRIVE_DMA   This drive supports DMA.
	 DRIVE_UDMA  This drive supports Ultra-DMA.
	 DRIVE_MODE  This drive properly reported its PIO and DMA mode.

     Once the controller has been initialised, it has to reset the DRIVE_DMA and DRIVE_UDMA, as
     well as the values of PIO_mode, DMA_mode and UDMA_mode if the modes to be used are not high-
     est ones supported by the drive.

SEE ALSO
     wdc(4), bus_space(9)

CODE REFERENCES
     The wdc core functions are implemented in sys/dev/ic/wdc.c.  Low-level ATA and ATAPI support
     is provided by sys/dev/ata_wdc.c and sys/dev/scsipi/atapi_wdc.c respectively.

     An example of a simple bus front-end can be found in sys/dev/isapnp/wdc_isapnp.c.	A more
     complex one, with multiple channels and bus-master DMA support is sys/dev/pci/pciide.c.
     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.

BSD					  April 18, 2010				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:07 AM.