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

[Ruslan Ermilov]

On Thu, Mar 02, 2006 at 10:16:29AM -0800, John-Mark Gurney wrote:
> > Correct.  So driver tells a device to "read directly into memory", a
> 					write
> 
> how can you read into something?
> 
The driver tells the disk to READ data and put it into the memory.

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

OK, so DMA read/write ops are from the device's perspective and dma
sync ops are from the host memory's perspective, but then the above
descriptions should all be fixed, and the phrase "to be DMA'ed into
a device" doesn't make sense.

              BUS_DMASYNC_PREREAD    Perform any synchronization required
                                     prior to an update of host memory by the
                                     DMA read operation.

A DMA read by the device of the host memory cannot update it; it's
a DMA write that's meant here.

              BUS_DMASYNC_PREWRITE   Perform any synchronization required
                                     after an update of host memory by the CPU
                                     and prior to DMA write operations.

The device will read host memory for writing/sending purposes, it's
a DMA read then.

Please review the following patch that fixes these inconsistencies.

%%%
Index: bus_dma.9
===================================================================
RCS file: /home/ncvs/src/share/man/man9/bus_dma.9,v
retrieving revision 1.33
diff -u -r1.33 bus_dma.9
--- bus_dma.9	1 Mar 2006 23:56:18 -0000	1.33
+++ bus_dma.9	2 Mar 2006 18:48:46 -0000
@@ -255,8 +255,8 @@
 description below for more details on how to use these operations.
 .Pp
 All operations specified below are performed from the host memory 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.
+where a read implies data coming from the device to the host memory (DMA write),
+and a write implies data going from the host memory to the device (DMA read).
 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
@@ -264,15 +264,15 @@
 .Bl -tag -width BUS_DMASYNC_POSTWRITE
 .It Dv BUS_DMASYNC_PREREAD
 Perform any synchronization required prior to an update of host memory by the
-DMA read operation.
+DMA write operation.
 .It Dv BUS_DMASYNC_PREWRITE
 Perform any synchronization required after an update of host memory by the CPU
-and prior to DMA write operations.
+and prior to DMA read operations.
 .It Dv BUS_DMASYNC_POSTREAD
-Perform any synchronization required after DMA read operations and prior to
+Perform any synchronization required after DMA write operations and prior to
 CPU access to host memory.
 .It Dv BUS_DMASYNC_POSTWRITE
-Perform any synchronization required after DMA write operations.
+Perform any synchronization required after DMA read operations.
 .El
 .It Vt bus_dma_lock_t
 Client specified lock/mutex manipulation method.
@@ -672,8 +672,8 @@
 .Fn 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.
+For example, the CPU might be used to set up the contents of a buffer
+that is to be DMA read by 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
 .Dv BUS_DMASYNC_PREWRITE
%%%


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/167e36bd/attachment.bin