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

[Ruslan Ermilov]

On Wed, Mar 01, 2006 at 04:50:39PM -0700, Scott Long wrote:
> John-Mark Gurney wrote:
> >Ruslan Ermilov wrote this message on Thu, Mar 02, 2006 at 01:26 +0200:
> >
> >>On Tue, Feb 28, 2006 at 07:58:57PM +0000, John-Mark Gurney wrote:
> >>
> >>>jmg         2006-02-28 19:58:57 UTC
> >>>
> >>> FreeBSD src repository
> >>>
> >>> Modified files:
> >>>   share/man/man9       bus_dma.9 
> >>> Log:
> >>> update examples to use the correct terms that was never updated when the
> >>> earlier descriptions were gone over...
> >>> 
> >>> MFC after:      3 days
> >>> 
> >>> Revision  Changes    Path
> >>> 1.32      +3 -3      src/share/man/man9/bus_dma.9
> >>>
> >>
> >>Not enough of fixing: "DMA read" and "DMA write" are also entangled here.
> >
> >
> >Nope...  WRITE == DMA read...  Read the descriptions of the flags
> >very carefully...  If you aren't confused, you don't understand it..
> >The reason you're confused is the reason why everyone gets it wrong,
> >and no one ever gets it correct the first time trying to figure out
> >which one to use...
> >
> 
WRITE == DMA write, it's not THAT confusing, please see below.  :-)

> Think of it from the perspective of the driver doing an operation.  If 
> the driver is reading a block off the disk, then you want to use the
                ^^^^^^^
> PREREAD/POSTREAD operations.
  ^^^^^^^^^^^^^^^^
> 
Correct.  So driver tells a device to "read directly into memory", a
DMA read operation.  Similarly for writes.  A CPU "writes directly
into device memory", a DMA write operation.

> Likewise for writes.  It is done this way
> for clarity in the driver.  I can't imagine how many bugs we'd have if
> write == read in the driver sources.
> 
Yes, that fits my understanding of how things work, and that's what
we have clarified in the manpage not so long ago:

: All operations specified below are performed from the host mem-
: ory point of view, where a read implies data coming from the
                             ^^^^                     ^^^^^^^^
: device to the host memory, and a write implies data going from
  ^^^^^^^^^^^^^^^^^^^^^^^^^        ^^^^^                    ^^^^
: the host memory to the device.  Alternately, the operations can
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
: be thought of in terms of driver operations, where reading a
: network packet or storage sector corresponds to a read operation
: in bus_dma.
: 
: BUS_DMASYNC_PREREAD    Perform any synchronization required
:                        prior to an update of host memory by the
:                        DMA read operation.
: 
: BUS_DMASYNC_PREWRITE   Perform any synchronization required
:                        after an update of host memory by the CPU
:                        and prior to DMA write operations.
: 
: BUS_DMASYNC_POSTREAD   Perform any synchronization required
:                        after DMA read operations and prior to
:                        CPU access to host memory.
: 
: BUS_DMASYNC_POSTWRITE  Perform any synchronization required
:                        after DMA write operations.

However, the text that John-Mark has correctly changed now looks
like this:

: 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.

That's DMA write.

: 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_PREWRITE must be
                                     ^^^^^^^^^^^^^^^^^^^^ OK!
: performed.  Additional sync operations must be performed after
: every CPU write to this memory if additional DMA reads are to be
                                               ^^^^^^^^^ should be "write"
: performed.  Conversely, for the DMA write case, the buffer must
                                      ^^^^^ should be "read"
: be loaded, and a dma sync operation of BUS_DMASYNC_PREREAD must
                                         ^^^^^^^^^^^^^^^^^^^ OK!
: be performed.  The CPU will only be able to see the results of
: this DMA write once the DMA has completed and a
           ^^^^^ should be "read"
: BUS_DMASYNC_POSTREAD operation has been performed.
  ^^^^^^^^^^^^^^^^^^^^ OK!


Cheers,
-- 
Ruslan Ermilov
ru at FreeBSD.org
FreeBSD committer
-------------- 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/20060302/af1c11b0/attachment-0001.bin