dma-buf: Update docs for SYNC ioctl

danvet · danvet · commit 87e332d56b2c · 2016-03-21T09:26:45.000+01:00
Just a bit of wording polish plus mentioning that it can fail and must
be restarted.

Requested by Sumit.

v2: Fix them typos (Hans).

Cc: Chris Wilson &lt;chris@chris-wilson.co.uk&gt;
Cc: Tiago Vignatti &lt;tiago.vignatti@intel.com&gt;
Cc: Stéphane Marchesin &lt;marcheu@chromium.org&gt;
Cc: David Herrmann &lt;dh.herrmann@gmail.com&gt;
Cc: Sumit Semwal &lt;sumit.semwal@linaro.org&gt;
Cc: Daniel Vetter &lt;daniel.vetter@intel.com&gt;
CC: linux-media@vger.kernel.org
Cc: dri-devel@lists.freedesktop.org
Cc: linaro-mm-sig@lists.linaro.org
Cc: intel-gfx@lists.freedesktop.org
Cc: devel@driverdev.osuosl.org
Cc: Hans Verkuil &lt;hverkuil@xs4all.nl&gt;
Acked-by: Sumit Semwal &lt;sumit.semwal@linaro.org&gt;
Acked-by: Hans Verkuil &lt;hans.verkuil@cisco.com&gt;
Signed-off-by: Daniel Vetter &lt;daniel.vetter@intel.com&gt;
diff --git a/Documentation/dma-buf-sharing.txt b/Documentation/dma-buf-sharing.txt
@@ -352,7 +352,8 @@ Being able to mmap an export dma-buf buffer object has 2 main use-cases:
 
    No special interfaces, userspace simply calls mmap on the dma-buf fd, making
    sure that the cache synchronization ioctl (DMA_BUF_IOCTL_SYNC) is *always*
-   used when the access happens. This is discussed next paragraphs.
+   used when the access happens. Note that DMA_BUF_IOCTL_SYNC can fail with
+   -EAGAIN or -EINTR, in which case it must be restarted.
 
    Some systems might need some sort of cache coherency management e.g. when
    CPU and GPU domains are being accessed through dma-buf at the same time. To
@@ -366,10 +367,10 @@ Being able to mmap an export dma-buf buffer object has 2 main use-cases:
        want (with the new data being consumed by the GPU or say scanout device)
      - munmap once you don't need the buffer any more
 
-    Therefore, for correctness and optimal performance, systems with the memory
-    cache shared by the GPU and CPU i.e. the "coherent" and also the
-    "incoherent" are always required to use SYNC_START and SYNC_END before and
-    after, respectively, when accessing the mapped address.
+    For correctness and optimal performance, it is always required to use
+    SYNC_START and SYNC_END before and after, respectively, when accessing the
+    mapped address. Userspace cannot rely on coherent access, even when there
+    are systems where it just works without calling these ioctls.
 
 2. Supporting existing mmap interfaces in importers
 
diff --git a/drivers/dma-buf/dma-buf.c b/drivers/dma-buf/dma-buf.c
@@ -612,7 +612,7 @@ EXPORT_SYMBOL_GPL(dma_buf_begin_cpu_access);
  * @dmabuf:	[in]	buffer to complete cpu access for.
  * @direction:	[in]	length of range for cpu access.
  *
- * This call must always succeed.
+ * Can return negative error values, returns 0 on success.
  */
 int dma_buf_end_cpu_access(struct dma_buf *dmabuf,
 			   enum dma_data_direction direction)

Original file line number	Diff line number	Diff line change
`@@ -612,7 +612,7 @@ EXPORT_SYMBOL_GPL(dma_buf_begin_cpu_access);`
`612`	`612`	`* @dmabuf: [in] buffer to complete cpu access for.`
`613`	`613`	`* @direction: [in] length of range for cpu access.`
`614`	`614`	`*`
`615`		`- * This call must always succeed.`
	`615`	`+ * Can return negative error values, returns 0 on success.`
`616`	`616`	`*/`
`617`	`617`	`int dma_buf_end_cpu_access(struct dma_buf *dmabuf,`
`618`	`618`	`enum dma_data_direction direction)`