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

[Maxime Henrion]

Justin T. Gibbs wrote:
> > mux         2003/06/13 13:07:49 PDT
> > 
> >   FreeBSD src repository
> > 
> >   Modified files:
> >     share/man/man9       bus_dma.9 
> >   Log:
> >   - Document the fact that you can specify several DMA operations to
> >     bus_dmamap_sync() by OR'ing them together.
> >   - Don't document what BUS_DMASYNC_PREREAD|BUS_DMASYNC_PREWRITE and
> >     BUS_DMASYNC_POSTREAD|BUS_DMASYNC_POSTWRITE is supposed to do when
> >     passed to bus_dmamap_sync().  There are other possible combinations
> >     and the reader just needs to know what the individual flags do and
> >     that he can combine different DMA operations.
> 
> I purposely documented the only combinations that make sense.  This
> would also allow us to change back to using an enum in the future
> since the combinations are limited just by changing the names of the
> operations.  It simply does not make sense to combine pre and post sync
> ops since doing so implies that you will lose data if your buffers are
> being bounced.  In other words, any update from the CPU that you expect
> your device to see must occur after you have POST'ed any PRE'ed operation
> so that the buffer contents updated by the CPU are synced.

It sure doesn't make sense to combine PREREAD and POSTREAD or PREWRITE
and POSTWRITE, but I don't see what would be wrong with
PREREAD|POSTWRITE or POSTREAD|PREWRITE.  One can imagine a scenario
where the device is DMA'ing some data to memory and where you DMA it
back to the device, and thus you would like to do a POSTREAD|PREWRITE.
I agree that this sounds unlikely and that it also relies on
bus_dmamap_sync() somehow knowing the ordering of things, but it's
possible, and wouldn't cause any data loss, whether be buffers are
bounced or not.

Anyways, whether it's useful or not, I believe it would be more
consistent with other manpages to leave things as is and maybe add a
comment to tell that some combinations make no sense.  Would you be
happy with this?

Cheers,
Maxime