cvs commit: src/share/man/man9 bus_dma.9

[Thomas Moestl]

On Wed, 2004/08/11 at 08:04:58 -0700, John-Mark Gurney wrote:
> John-Mark Gurney wrote this message on Wed, Aug 11, 2004 at 14:52 +0000:
> > jmg         2004-08-11 14:52:33 UTC
> > 
> >   FreeBSD src repository
> > 
> >   Modified files:
> >     share/man/man9       bus_dma.9 
> >   Log:
> >   fix description of the macros for BUS_DMASYNC opertions.  It's from the CPU's
> >   point of view...  Add a reference to a better description of what the ops
> >   do...
> 
> If you were previously confused (and even if you thought you knew what
> they were) on what BUS_DMASYNC_ ops to us, please reread the manpage
> and review any drivers written using them.

Hmmm. It seems to me that the text the new reference points to is
wrong, or at least ambiguous:

              bus_dmamap_sync() is the method used to ensure that CPU and
              device DMA access to shared memory is coherent.  For example,
              the CPU might be used to setup the contents of a buffer that is
              to be DMA'ed into a device.  To ensure that the data are visible
              via the device's mapping of that memory, the buffer must be
              loaded and a dma sync operation of BUS_DMASYNC_PREREAD must be
              performed.  Additional sync operations must be performed after
              every CPU write to this memory if additional DMA reads are to be
              performed.  Conversely, for the DMA write case, the buffer must
              be loaded, and a dma sync operation of BUS_DMASYNC_PREWRITE must
              be performed.  The CPU will only be able to see the results of
              this DMA write once the DMA has completed and a
              BUS_DMASYNC_POSTWRITE operation has been performed.

When the CPU sets up data to be DMAed into the device from memory, it
needs to use a PREWRITE, not POSTREAD, sync before starting the DMA
operation. Likewise, after DMAing data out of the device and into
memory, a POSTREAD is required. This is quickly evident when looking
into the busdma implementations, for example the way the i386 one
deals with bounce buffers on syncs.
The best way to memorize the flags (and probably their origin) is to
imagine a disk controller; a write to disk will need the *WRITE flags
(but it reads from memory), and vice versa.

NetBSD has a nice clarification:
              Synchronization operations are expressed from the perspective of
              the host RAM, e.g., a device -> memory operation is a READ and a
              memory -> device operation is a WRITE.

I think that something of that variety is required, since there are
always the two opposite meanings of "reading from" and "reading into".

	- Thomas

-- 
Thomas Moestl	<t.moestl at tu-bs.de>	http://www.tu-bs.de/~y0015675/
		<tmm at FreeBSD.org>	http://people.FreeBSD.org/~tmm/
OpenPGP fingerprint: 1C97 A604 2BD0 E492 51D0  9C0F 1FE6 4F1D 419C 776C
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/cvs-src/attachments/20040812/5d5865ab/attachment.bin