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

[Scott Long]

John-Mark Gurney wrote:
> Ruslan Ermilov wrote this message on Thu, Mar 02, 2006 at 09:18 +0200:
> 
>>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.  :-)
> 
> 
> It depends upon how you view the DMA...  bus_dma WRITE == DMA operation
> that reads data from memory into the device...  It's confusing enough
> to have the bus_dma flags being from the device driver's point of view,
> but talking about DMA in the same point of view is just wrong..  it isn't
> the device driver doing the work, it's the DMA engine, and the engine
> is reading...
> 
> 
>>>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
> 
> 					write
> 
> how can you read into something?  isn't that what humans do when they
> get think something else was said?
> 
> 
>>DMA read operation.  Similarly for writes.  A CPU "writes directly
>>into device memory", a DMA write operation.
> 
> 
> If the cpu writes directly into device memory, then it isn't a DMA
> 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.
> 
> 
> Nope, it's a read...
> 
> 
>>: 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"
> 
> 
> Nope, DMA read's the memory that was writen to by the cpu...
> 
> 
>>: 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"
> 
> 
> Nope, the DMA engine writes the data that is to be consumed by the
> cpu...
> 
> 
>>: BUS_DMASYNC_POSTREAD operation has been performed.
>>  ^^^^^^^^^^^^^^^^^^^^ OK!
> 
> 
> Now riddle me this, what PCI operation is performed to satisify the
> respective requests?
> 

Ah, but what is all of this called when you have a general purpose 
ISA-DMA device sitting on the bug acting on behalf of the CPU for
an arbitrary device.

I'll review this page for correctness again when I'm good and properly
hammered on some of that great Polish vodka that I got a MeetBSD.

Scott