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

[Weng, Chuanbo]

In general I agree with you. We will clean up and refine these extensions later.
I've sent out a new version of this patchset and ask Yuan Feng for review.

Thanks,
Chuanbo Weng

-----Original Message-----
From: Zhigang Gong [mailto:zhigang.gong at linux.intel.com] 
Sent: Friday, April 03, 2015 9:45
To: Weng, Chuanbo
Cc: beignet at lists.freedesktop.org; Yuan, Feng
Subject: Re: [Beignet] [PATCH v2 3/3] Add document to describe the detials of v4l2 buffer sharing.

One major comment is we should not introduce such an extension without considering the queue. The correct APIs should be something like clEnqueueAcquireMemObjectFdIntel/clEnqueueReleaseMemObjectFdIntel.
And the corresponding queue must be the parameters. Without that, the user even has no idea how to make the external application synchronized with opencl.

Another more generic comment for all of these internal extensions which are not going to be submitted to the standard is as below:
It seems better to add some beignet specified suffix after Intel which indicates this is a beignet only extension.

Let's us leave the INTEL suffix as a official name for those Intel specific extensions which have been accepted by Khronos.

And for the internal libva sharing extension, as there is already an officially accepted extension. It's time to just apply that offical extension rather than the current unofficial one.


Thanks,
Zhigang Gong.

On Sat, Mar 28, 2015 at 12:34:17AM +0800, Chuanbo Weng wrote:
> 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.freedes
> ktop.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://linuxt
> +v.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
> 
> _______________________________________________
> Beignet mailing list
> Beignet at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/beignet