[PATCH] dma-buf: Update docs to discourage use of dma_buf_mmap()

[Steven Price]

dma_buf_mmap() allows a device driver to forward a mmap() call to the
dma_buf exporter. However this mechanism provides no way for userspace
to use the DMA_BUF_IOCTL_SYNC mechanism to ensure coherency with the
mapped buffer.

Because of this it is wise to migrate away from providing this
mmap() forwarding mechanism and update drivers to avoid using it.
However the user ABI must be maintained, so this existing mmap()
forwarding cannot be removed.

Signed-off-by: Steven Price <steven.price at arm.com>
---
 drivers/dma-buf/dma-buf.c | 23 ++++++++++-------------
 1 file changed, 10 insertions(+), 13 deletions(-)

diff --git a/drivers/dma-buf/dma-buf.c b/drivers/dma-buf/dma-buf.c
index bf4d4c80fbc6..2a7a2c8c4182 100644
--- a/drivers/dma-buf/dma-buf.c
+++ b/drivers/dma-buf/dma-buf.c
@@ -731,20 +731,17 @@ EXPORT_SYMBOL_GPL(dma_buf_unmap_attachment);
  *
  * - And as a CPU fallback in userspace processing pipelines.
  *
- *   Similar to the motivation for kernel cpu access it is again important that
- *   the userspace code of a given importing subsystem can use the same
- *   interfaces with a imported dma-buf buffer object as with a native buffer
- *   object. This is especially important for drm where the userspace part of
- *   contemporary OpenGL, X, and other drivers is huge, and reworking them to
- *   use a different way to mmap a buffer rather invasive.
+ *   Ideally userspace code should directly mmap the dma-buf fd which allows
+ *   the use of the SYNC_START/SYNC_END ioctls as detailed above. However there
+ *   are situations where there is a large body of existing code and reworking
+ *   it to support a different way to mmap a buffer is rather invasive.
  *
- *   The assumption in the current dma-buf interfaces is that redirecting the
- *   initial mmap is all that's needed. A survey of some of the existing
- *   subsystems shows that no driver seems to do any nefarious thing like
- *   syncing up with outstanding asynchronous processing on the device or
- *   allocating special resources at fault time. So hopefully this is good
- *   enough, since adding interfaces to intercept pagefaults and allow pte
- *   shootdowns would increase the complexity quite a bit.
+ *   Some drivers therefore provide an interface that simply redirects the
+ *   mmap to the dma-buf exporter. This is fine as long as the SYNC_START and
+ *   SYNC_END ioctls don't do anything, but may lead to coherency issues
+ *   if they are required. New code should avoid using this because of
+ *   potentially hard to debug coherency problems. The interface, however,
+ *   remains for backwards compatibility.
  *
  *   Interface::
  *      int dma_buf_mmap(struct dma_buf \*, struct vm_area_struct \*,
-- 
2.20.1