1 files changed, 71 insertions, 0 deletions

diff --git a/Software/Beignet/howto/v4l2-buffer-sharing-howto.mdwn b/Software/Beignet/howto/v4l2-buffer-sharing-howto.mdwn
new file mode 100644
index 00000000..85008a88
--- /dev/null
+++ b/Software/Beignet/howto/v4l2-buffer-sharing-howto.mdwn
@@ -0,0 +1,71 @@
+V4l2 Buffer Sharing HowTo
+=========================
+
+Beignet has extension clGetMemObjectFdIntel 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 extension clGetMemObjectFdIntel 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")
+
+- 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 close 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`