So, as promised, I'm getting a copy of this out now, albeit a little
early.  I've integrated the uio idea suggested by Charles Hannum
(I began to like it more and more), so pay attention; some of the
data structures have changed :-)

I did get some comments back from Matthias Drochner, as well, but
they're more generic bus.h comments (and specifically, i386
implementation) than bus dma.  As such, I'm going to adderess those
separately, with Matthias, though probably not until I return from
Pittsburgh.

In any case, the latest revision is below.  Please read carefully,
and (constructively) comment.  I really do want to get this implemented
in some fashion before the end of December (which is a month where I
might actually have time to work on it :-)

Ciao.

Jason R. Thorpe                                       thorpej@nas.nasa.gov
NASA Ames Research Center                               Home: 408.866.1912
NAS: M/S 258-6                                          Work: 415.604.0935
Moffett Field, CA 94035                                Pager: 415.428.6939

 ----- snip -----

NAS $Id: busdma.doc,v 1.19 1996/11/09 01:41:35 thorpej Exp $

PURPOSE
-------

The purpose of this document is to describe a bus- and machine-independent
DMA mapping interface.


All data structures, function prototypes, and macros will be defined
by the port-specific header <machine/bus.h>.  Note that this document
assumes the existence of types already defined by the current "bus.h"
interface.


Unless otherwise noted, all function calls in this interface may be
defined as CPP macros.



DATA TYPES
----------

Individual implementations may name these structures whatever they
wish, providing that the external representations are:

	bus_dma_tag_t		A machine-dependent opaque type
				describing the implementation of
				DMA for a given bus.

	bus_dma_handle_t	A machine-dependent opaque type
				describing a complete DMA mapping.
				The mapping is considered invalid until
				the handle is used in a dmamap load
				operation.  After a DMA transaction,
				a dmamap unload operation is used to
				invalidate the mapping.

	bus_dmamap_load_func_t	A driver-dependent function used to load
				a device's scatter-gather descriptors.
				The type of the function should be:

		typedef	int (*bus_dmamap_load_func_t) __P((bus_addr_t addr,
		    bus_size_t size, void *arg));

				This function will be called iteratively
				by bus_dmamap_load() with the address
				and length of a single, contiguous DMA
				transfer, conforming to the constraints
				of the device.  "arg" is a driver-dependent
				cookie used by the driver to keep state
				between iterations.

				See bus_dmamap_load() for more details.

	bus_dmasync_op_t	An enumerated type providing the following
				unique values:

		BUS_DMASYNC_PREREAD
		BUS_DMASYNC_POSTREAD
		BUS_DMASYNC_PREWRITE
		BUS_DMASYNC_POSTWRITE

				See bus_dmamap_sync() for more details.




FUNCTIONS
---------

int	bus_dmamap_create __P((bus_dma_tag_t tag, bus_size_t size,
	    int nsegments, bus_size_t maxsegsz, int flags,
	    bus_dma_handle_t *dmahp));

	bus_dmamap_create() allocates a dma handle and initializes
	it according to the paramters provided.  Arguments are
	as follows:

	tag		This is the bus_dma_tag_t passed down from the
			parent driver via <bus>_attach_args.

	size		This is the maximum DMA transfer that can
			be mapped by the handle.

	nsegments	Number of segments the device can support
			in a single DMA transaction.  This may
			be the number of scatter-gather descriptors
			supported by the device.

	maxsegsz	The maximum number of bytes that may be
			transfered by any given DMA segment.

	flags		Flags are defined as follows:

		BUS_DMA_WAITOK		It is safe to wait (sleep)
					for resouces during this call.

		BUS_DMA_NOWAIT		It is not safe to wait (sleep)
					for resources during this call.

		BUS_DMA_ALLOCNOW	Perform any resource allocation
					this handle may need now.
					If this is not specified, the
					allocation may be deferred to
					bus_dmamap_load().  If this flag
					is specified, bus_dmamap_load()
					will not block on resource
					allocation.

		BUS_DMA_BUS[1-4]	These flags are placeholders,
					and may be used by busses to
					provide bus-dependent functionality.

	dmahp		This is a pointer to a bus_dma_handle_t.
			A dma handle will be allocated and
			pointed to by *dmahp upon sucessful completion
			of this routine.

	Behavior is not defined if invalid arguments are passed to
	bus_dmamap_create().

	RETURN VALUES

	Returns 0 on success or an error code to indicate mode of failure.



void	bus_dmamap_destroy __P((bus_dma_tag_t tag, bus_dma_handle_t dmah));

	bus_dmamap_destroy() frees all resources associated with a
	given dma handle.  Arguments are as follows:

	tag		This is the bus_dma_tag_t passed down from the
			parent driver via <bus>_attach_args.

	dmah		The dma handle to destroy.

	In the event that the dma handle contains a valid mapping,
	the mapping will be unloaded via the same mechanism used
	by bus_dmamap_unload().

	Behavior is not defined if invalid arguments are passed
	to bus_dmamap_destroy().

	RETURN VALUES

	If given valid arguments, bus_dmamap_destroy() always suceeds.



int	bus_dmamap_load __P((bus_dma_tag_t tag, bus_dma_handle_t dmah,
	    struct uio *uio, bus_dmamap_load_func_t func, void *funcarg,
	    int flags));

	bus_dmamap_load() loads a dma handle with mappings for a
	DMA transfer.  Arguments are as follows:

	tag		This is the bus_dma_tag_t passed down from the
			parent driver via <bus>_attach_args.

	dmah		The dma handle with which to map the
			transfer.

	uio		A pointer to a struct uio, which describes
			the buffers involved in the DMA transfer.
			The uio structure will contain iovecs which
			describe the buffers involved in the transfer,
			and will set "uio_segflg" to indicate DMA
			to/from kernel or user address space.  If
			"uio_segflg" is UIO_USERSPACE, then the buffers
			are assumed to be in "uio_procp"'s address
			space.  bus_dmamap_load() will ignore the
			value of "uio_rw".  bus_dmamap_load() will
			adjust the "uio_offset" and "uio_resid"
			values as necessary while iterating over
			the uio.

	func		For each physically contiguous DMA segment
			in the uio, this function will be called
			with an address and length suitable for
			programming into DMA controller registers
			or command blocks.  In addition, this function
			will be passed a driver-dependent argument
			which may be used to keep state between
			calls to "func".

			This function will be called no more than the
			number of times specified by the "nsegments"
			parameter passed to bus_dmamap_create().

			The length passed to "func" is bound by
			the "maxsegsz" argument passed to
			bus_dmamap_create().

			This function should return 0 on success
			or an error code to indicate the mode of
			failure.

	funcarg		The driver-dependent argument passed to
			"func".

	flags		Flags are defined as follows:

		BUS_DMA_WAITOK		It is safe to wait (sleep)
					for resources during this call.

		BUS_DMA_NOWAIT		It is not safe to wait (sleep)
					for resources during this call.

		BUS_DMA_BUS[1-4]	These flags are placeholders,
					and may be used by busses to
					provide bus-dependent functionality.

	As noted above, if a dma handle is created with
	BUS_DMA_ALLOCNOW, bus_dmamap_load() will never block.

	If a call to bus_dmamap_load() fails, the mapping in
	the dma handle will be invalid.  It is the responsibility
	of the caller to clean up any inconsistent device state
	resulting from incomplete iteration through the uio.

	Behavior is not defined if invalid arguments are passed to
	bus_dmamap_load().

	RETURN VALUES

	Returns 0 on success or an error code to indicate mode of failure.



void	bus_dmamap_unload __P((bus_dma_tag_t tag, bus_dma_handle_t dmah));

	bus_dmamap_unload() deletes the mappings for a given
	dma handle.  Arguments are as follows:

	tag		This is the bus_dma_tag_t passed down from the
			parent driver via <bus>_attach_args.

	dmah		The dma handle containing the mappings
			which are to be deleted.

	If the dma handle was created with BUS_DMA_ALLOCNOW,
	bus_dmamap_unload() will not free the corresponding
	resources which were allocated by bus_dmamap_create().
	This is to ensure that bus_dmamap_load() will never block
	on resources if the handle was created with BUS_DMA_ALLOCNOW.

	Behavior is not defined if invalid arguments are passed to
	bus_dmamap_unload().

	RETURN VALUES

	If given valid arguments, bus_dmamap_unload() always suceeds.



void	bus_dmamap_sync __P((bus_dma_tag_t tag, bus_dma_handle_t dmah,
	    bus_dmasync_op_t op));

	bus_dmamap_sync() performs pre- and post-DMA operation
	cache and/or buffer synchronization.  Arguments are as follows:

	tag		This is the bus_dma_tag_t passed down from the
			parent driver via <bus>_attach_args.

	dmah		The DMA mapping to be synchronized.

	op		The synchronization operation to perform.

	The following DMA synchronization operations are defined:

	BUS_DMASYNC_PREREAD		Perform any pre-read DMA cache
					and/or bounce operations.

	BUS_DMASYNC_POSTREAD		Perform any post-read DMA cache
					and/or bounce operations.

	BUS_DMASYNC_PREWRITE		Perform any pre-write DMA cache
					and/or bounce operations.

	BUS_DMASYNC_POSTWRITE		Perform any post-write DMA cache
					and/or bounce operations.

	This function exists so that multiple read and write transfers
	can be performed with the same buffer, and so that drivers can
	explicitly inform the bus DMA code when their data is 'ready'
	in its DMA buffer.

	An example of multiple read-write use of a single mapping
	might look like:

	bus_dmamap_load(...);

	while (not done) {
		/* invalidate soon-to-be-stale cache blocks */
		bus_dmamap_sync(..., BUS_DMASYNC_PREREAD);

		[ do read DMA ]

		/* copy from bounce */
		bus_dmamap_sync(..., BUS_DMASYNC_POSTREAD);

		/* read data now in driver-provided buffer */

		[ computation ]

		/* data to be written now in driver-provided buffer */

		/* flush write buffers and writeback, copy to bounce */
		bus_dmamap_sync(..., BUS_DMASYNC_PREWRITE);

		[ do write DMA ]

		/* probably a no-op, but provided for consistency */
		bus_dmamap_sync(..., BUS_DMASYNC_POSTWRITE);
	}

	bus_dmamap_unload(...);


	If DMA read and write operations are not preceeded and followed
	by the apropriate synchronization operations, behavior is
	undefined.

	Behavior is not defined if invalid arguments are passed to
	bus_dmamap_sync().

	RETURN VALUES

	If given valid arguments, bus_dmamap_sync() always succeeds.



caddr_t	bus_dmamem_alloc __P((bus_dma_tag_t tag, size_t size,
	    int nsegments, bus_size_t alignment, struct proc *p,
	    int flags));

	bus_dmamem_alloc() allocates memory that is "DMA safe"
	for the bus corresponding to the given tag and maps it
	into virtual address space as determined by "p" (see below).
	Arguments are as follows:

	tag		The is the bus_dma_tag_t passed down from the
			parent driver via <bus>_attach_args.

	size		The amount of memory to allocate.

	nsegments	Specifies the maximum number of segments
			that may compose the allocated memory.  For
			example, if this value is 1, the entire
			allocated memory region must be physically
			contiguous.  If this value is 2, the allocated
			memory region may consist of up to 2
			physically contigious segments, etc.

	alignment	Each segment will be aligned on this boundary.
			Alignment must be a power of 2.  If no alignment
			is necessary, the value 1 should be specified.

	p		This argument is used to determine which
			address space in which to map allocated
			physical pages.  If "p" is NULL, the pages
			are mapped into kernel virtual address
			space.  Otherwise, the pages are mapped
			into the virtual address space of process "p".

	flags		Flags are defined as follows:

		BUS_DMA_WAITOK		It is safe to wait (sleep)
					for resources during this call.

		BUS_DMA_NOWAIT		It is not safe to wait (sleep)
					for resources during this call.

		BUS_DMA_BUS[1-4]	These flags are placeholders,
					and may be used by busses to
					provide bus-dependent functionality.

	All pages allocated by bus_dmamem_alloc() will be wired down
	until they are freed by bus_dmamem_free().

	Behavior is undefined if invalid arguments are passed to
	bus_dmamem_alloc().

	RETURN VALUES

	Returns the virtual address in the address space selected by "p"
	of the allocated memory or NULL if the request cannot be satisfied.



void	bus_dmamem_free __P((bus_dma_tag_t tag, caddr_t va,
	    size_t size, struct proc *p));

	bus_dmamem_free() unmaps and frees memory previously allocated
	by bus_dmamem_alloc().  Arguements are as follows:

	tag		This is the bus_dma_tag_t passed down from the
			parent driver via <bus>_attach_args.

	va		The virtual address of the memory region to be
			freed.

	size		The amount of memory that was allocated
			but bus_dmamem_alloc().

	p		This argument is used to determine which
			address space the pages were mapped into.
			If "p" is NULL, pages were mapped into
			kernel virtual address space.  Otherwise,
			pages were mapped into the virtual address
			space of process "p".

	Behavior is undefined if invalid arguments are passed to
	bus_dmamem_free().

	RETURN VALUES

	If given valid arguments, bus_dmamem_free() always succeeds.