[Beignet] [PATCH v2 3/3] Add document to describe the detials of v4l2 buffer sharing.

[Chuanbo Weng]

This document includes the steps of using DMABUF buffer sharing between
v4l2 and Beignet. Also steps to run corresponding example.

Signed-off-by: Chuanbo Weng <chuanbo.weng at intel.com>
---
 docs/Beignet.mdwn                         |  1 +
 docs/howto/v4l2-buffer-sharing-howto.mdwn | 67 +++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+)
 create mode 100644 docs/howto/v4l2-buffer-sharing-howto.mdwn

diff --git a/docs/Beignet.mdwn b/docs/Beignet.mdwn
index aacd7d2..31c0d9a 100644
--- a/docs/Beignet.mdwn
+++ b/docs/Beignet.mdwn
@@ -254,6 +254,7 @@ Documents for OpenCL application developers
 - [[Work with old system without c++11|Beignet/howto/oldgcc-howto]]
 - [[Kernel Optimization Guide|Beignet/optimization-guide]]
 - [[Libva Buffer Sharing|Beignet/howto/libva-buffer-sharing-howto]]
+- [[V4l2 Buffer Sharing|Beignet/howto/v4l2-buffer-sharing-howto]]
 
 The wiki URL is as below:
 [http://www.freedesktop.org/wiki/Software/Beignet/](http://www.freedesktop.org/wiki/Software/Beignet/)
diff --git a/docs/howto/v4l2-buffer-sharing-howto.mdwn b/docs/howto/v4l2-buffer-sharing-howto.mdwn
new file mode 100644
index 0000000..d5a9b56
--- /dev/null
+++ b/docs/howto/v4l2-buffer-sharing-howto.mdwn
@@ -0,0 +1,67 @@
+V4l2 Buffer Sharing HowTo
+=========================
+
+Beignet has extensions (clGetMemObjectFdIntel/clCloseMemObjectFdIntel) to share gpu
+buffer object with v4l2. So users can utilize OpenCL to do processing on input/ouput
+buffers of v4l2 device without buffer copy.
+
+Prerequisite
+------------
+
+Linux kernel supports DMABUF buffer sharing for v4l2 from version 3.8. DMABUF buffer
+sharing runs well for V4L2_PIX_FMT_MJPEG format on this version, but there is a bug
+for V4L2_PIX_FMT_YUYV format. Linux kernel 3.19.0-rc1 fix this bug, so please use kernel
+version 3.19.0-rc1 at least if you want to utilize this feature for V4L2_PIX_FMT_YUYV
+format.
+
+Steps
+-----
+
+The below official v4l2 document describes the details of sharing DMA buffers between
+v4l devices and other devices using v4l2 as a DMABUF importer:
+[http://linuxtv.org/downloads/v4l-dvb-apis/dmabuf.html](http://linuxtv.org/downloads/v4l-dvb-apis/dmabuf.html)
+Beignet has added extensions(clGetMemObjectFdIntel/clCloseMemObjectFdIntel) to support
+this mechanism. Please follow the steps as below to utilize DMABUF buffer sharing between
+v4l devices and Beignet:
+
+- Get the address of this extension by the function:
+  clGetExtensionFunctionAddress("clGetMemObjectFdIntel")
+  and clGetExtensionFunctionAddress("clCloseMemObjectFdIntel")
+
+- Create a number of cl buffer objects, invoke clGetMemObjectFdIntel to get these buffer
+  objects' file descriptors.
+
+- Initiating streaming I/O with DMABUF buffer sharing by calling the VIDIOC_REQBUFS v4l2 ioctl.
+
+- Enqueue these buffers by calling the VIDIOC_QBUF, dequeue a buffer by calling VIDIOC_DQBUF,
+  use OpenCL to do processing on this buffer and re-enqueue...
+
+- Close file descriptors of these buffers by clCloseMemObjectFdIntel if your program doesn't
+  need DMABUF buffer sharing anymore.
+
+Sample code
+-----------
+
+We have developed an example showing how to share DMA buffers between webcam and Beignet in
+examples/v4l2_buffer_sharing directory. The webcam directly captures V4L2_PIX_FMT_YUYV frames
+into cl buffer objects by the way of DMABUF buffer sharing, then frames are got mirror effect
+by OpenCL kernel, and finally show on screen by libva.
+
+Steps to build and run this example:
+
+- Update your linux kernel to at least 3.19.0-rc1.
+
+- Make sure there is a webcam connected to your pc.
+
+- Add option -DBUILD_EXAMPLES=ON to enable building examples when running cmake, such as:
+  `> mkdir build`
+  `> cd build`
+  `> cmake -DBUILD_EXAMPLES=ON ../`
+
+- Build source code:
+  `> make`
+
+- Run:
+  `> cd examples`
+  `> . ../utests/setenv.sh`
+  `> ./example-v4l2_buffer_sharing`
-- 
1.9.1