diff options
| -rw-r--r-- | docs/Beignet.mdwn | 1 | ||||
| -rw-r--r-- | docs/howto/v4l2-buffer-sharing-howto.mdwn | 64 |
2 files changed, 65 insertions, 0 deletions
diff --git a/docs/Beignet.mdwn b/docs/Beignet.mdwn index c0650bba..2509ece6 100644 --- a/docs/Beignet.mdwn +++ b/docs/Beignet.mdwn @@ -305,6 +305,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 00000000..68d37aa1 --- /dev/null +++ b/docs/howto/v4l2-buffer-sharing-howto.mdwn @@ -0,0 +1,64 @@ +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` |