On Thu, Aug 14, 2003 at 06:53:32PM -0700, cgd@broadcom.com wrote:
> well, what do you mean "some device that isn't coherent?"

I don't think it's relevant because I don't have an actual machine
in mind.  Just a hypothetical case that would actually be pretty
brain-dead.  (Not to say that brain-dead things don't get to market,
mind you...)

OK.  So I think that in summary, it might make the most sense to:

	* Make BUS_DMA_COHERENT required for proper operation by
	  changing the description in bus_dmamem_map()

		BUS_DMA_COHERENT This flag is a hint to the machine-depen-
				 dent back-end that indicates that the
				 memory needs to be mapped in a coherent
				 fashion.  That is, that no writes to
				 the memory should result in extra data
				 being written the memory (through a
				 partial update of a cacheline followed
				 by a full cacheline write-back, for example).

				 The back-end may ignore this if it has a
				 fully-coherent memory system.  The back-
				 end may also choose to map this memory as
				 uncachable in some fashion.

				 This flag may impose a performance penalty
				 if used when unnecessary.  It is most
				 useful for regions of memory that may
				 be simultaneously accessed by the CPU
				 and a device.  For example, an ethernet
				 descriptor ring is commonly accessed by
				 both the CPU and the ethernet device
				 while data buffers are not.

				 Note that if this flag is used, it must
				 also be used with the corresponding
				 bus_dmamap_load() function.

				 Note that all calls to bus_dmamap_sync()
				 must still be made as there may be machine-
				 dependent operations required to complete
				 synchronization before and after DMA
				 operations.

				 Also note that this flag only applies
				 to coherency between the CPU and memory.
				 Coherency between memory and the device
				 is controlled with a different flag.  See
				 the description of the bus_dmamap_load()
				 function.

	* Add BUS_DMA_COHERENT to bus_dmamap_load()

		BUS_DMA_COHERENT This flag is a hint to the machine-depen-
				 dent back-end that indicates that the
				 region being loaded into the DMA map
				 should be handled as a coherent region
				 by any calls to the bus_dmamap_sync()
				 function.  Coherency implies that no writes
				 to the memory should accidentally write
				 more data than intended (through a write
				 of an entire cacheline, for example).

				 This flag must be passed to
				 bus_dmamap_load() when loading a dmamap
				 for a region that was mapped using this
				 flag with bus_dmamem_map().

				 Note that this flag applies to coherency
				 between the CPU and memory.  Coherency
				 between memory and the device doing DMA
				 is assumed.  See the description of the
				 BUS_DMA_STREAMING flag for this function.

				 See further discussion of this flag in
				 the description of the bus_dmamem_map()
				 function.
				  
> I think the above is fairly good, but i'd probably polish it a bunch.  8-)

How's the above?

-allen

-- 
 Allen Briggs                     briggs@wasabisystems.com
 Wasabi Systems, Inc.             http://www.wasabisystems.com/