/*
 * Copyright (c) 1997 by Sun Microsystems, Inc.
 * All Rights Reserved
 */

	ident	"@(#)README	1.8	97/10/06 SMI"

DRIVER NAME:
	dma

ARCHITECTURES:
	This directory contains a SPARC-specific dma driver and an 
	Intel-specific dma driver.

NOTE:
	The DMA interfaces used in these drivers are platform-dependent
	and are considered obsolete and are not recommended.  Please
	refer to the "isp" sample driver for an example of the use of
	the preferred platform-independent Solaris DMA interfaces.

DESCRIPTION OF DRIVER:

	These drivers are not intended to be efficient or bulletproof;
	they are intended to show how to write a DDI/DKI-compliant
	drivers and to demonstrate the similarites and differences
	between DDI/DKI-compliant DMA routines on SPARC and x86.

	SPARC:
	    The SPARC dma driver is for a fictional SBus device that is
	    capable of doing DMA.

	x86:
	    The i386 driver is for a fictional device that is capable of
	    doing DMA.  The fictional device has three registers (see
	    dma_reg.h): 
	     - a control/status register (CSR) for control and status bits
	     - a device address register, to specify the data offset within
	       the device's internal address space
	     - a transfer length register.  

	    It is assumed that the registers start at "ioaddr" as given in
	    the dma.conf file, that they are all two bytes wide, and are
	    contiguous in x86 I/O space.

	    The device address and transfer length registers are set to
	    program the area of the device involved in DMA transfers, and
	    a bit in the CSR is set to start the I/O, which uses the
	    system's DMA engine.

	    By not specifying the DDI_DMA_PARTIAL flag in the call to
	    ddi_dma_setup, we insure that all transfers requested here
	    will fit within one DMA "window" to simplify the looping code.
	    The fictional dma device has no DMA hardware of its own, so
	    we must use the x86 system board's DMA hardware via the
	    ddi_dmae(9F) functions.  

CAVEATS AND CONSTRAINTS:
	This sample code is written for hypothetical hardware and will not 
	actually run on any platform.

DISCLAIMER:
	This driver is meant to illustrate the functionality of the 
	DDI/DKI. It is meant to be a skeleton that can be used as a basis
	for a real-world driver. This driver will not actually run. 


COMPILING/LOADING:
	Use the Makefile in the dma directory to compile the drivers.
	The Makefile determines the architecture (x86 or sparc) of the 
	build machine and sets a preprocessor variable (i386 or sparc)
	accordingly. The object files are placed in an appropriate
	architecture-specific subdirectory of the dma directory. The
	drivers also can be build using the Makefiles in the
	architecture-specific subdirectories.

REFERENCES:
        SunOS 5.5 Writing Device Drivers
