Documentation/media/uapi/v4l/vidioc-expbuf.rst

   1 .. _VIDIOC_EXPBUF:
   2
   3 *******************
   4 ioctl VIDIOC_EXPBUF
   5 *******************
   6
   7 Name
   8 ====
   9
  10 VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor.
  11
  12
  13 Synopsis
  14 ========
  15
  16 .. c:function:: int ioctl( int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp )
  17     :name: VIDIOC_EXPBUF
  18
  19
  20 Arguments
  21 =========
  22
  23 ``fd``
  24     File descriptor returned by :ref:`open() <func-open>`.
  25
  26 ``argp``
  27     Pointer to struct :c:type:`v4l2_exportbuffer`.
  28
  29
  30 Description
  31 ===========
  32
  33 This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O
  34 method, therefore it is available only for ``V4L2_MEMORY_MMAP`` buffers.
  35 It can be used to export a buffer as a DMABUF file at any time after
  36 buffers have been allocated with the
  37 :ref:`VIDIOC_REQBUFS` ioctl.
  38
  39 To export a buffer, applications fill struct
  40 :c:type:`v4l2_exportbuffer`. The ``type`` field is
  41 set to the same buffer type as was previously used with struct
  42 :c:type:`v4l2_requestbuffers` ``type``.
  43 Applications must also set the ``index`` field. Valid index numbers
  44 range from zero to the number of buffers allocated with
  45 :ref:`VIDIOC_REQBUFS` (struct
  46 :c:type:`v4l2_requestbuffers` ``count``) minus
  47 one. For the multi-planar API, applications set the ``plane`` field to
  48 the index of the plane to be exported. Valid planes range from zero to
  49 the maximal number of valid planes for the currently active format. For
  50 the single-planar API, applications must set ``plane`` to zero.
  51 Additional flags may be posted in the ``flags`` field. Refer to a manual
  52 for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
  53 and O_RDWR are supported. All other fields must be set to zero. In the
  54 case of multi-planar API, every plane is exported separately using
  55 multiple :ref:`VIDIOC_EXPBUF` calls.
  56
  57 After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a
  58 driver. This is a DMABUF file descriptor. The application may pass it to
  59 other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>`
  60 for details about importing DMABUF files into V4L2 nodes. It is
  61 recommended to close a DMABUF file when it is no longer used to allow
  62 the associated memory to be reclaimed.
  63
  64
  65 Examples
  66 ========
  67
  68
  69 .. code-block:: c
  70
  71     int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd)
  72     {
  73         struct v4l2_exportbuffer expbuf;
  74
  75         memset(&expbuf, 0, sizeof(expbuf));
  76         expbuf.type = bt;
  77         expbuf.index = index;
  78         if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
  79             perror("VIDIOC_EXPBUF");
  80             return -1;
  81         }
  82
  83         *dmafd = expbuf.fd;
  84
  85         return 0;
  86     }
  87
  88
  89 .. code-block:: c
  90
  91     int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index,
  92         int dmafd[], int n_planes)
  93     {
  94         int i;
  95
  96         for (i = 0; i < n_planes; ++i) {
  97             struct v4l2_exportbuffer expbuf;
  98
  99             memset(&expbuf, 0, sizeof(expbuf));
 100             expbuf.type = bt;
 101             expbuf.index = index;
 102             expbuf.plane = i;
 103             if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
 104                 perror("VIDIOC_EXPBUF");
 105                 while (i)
 106                     close(dmafd[--i]);
 107                 return -1;
 108             }
 109             dmafd[i] = expbuf.fd;
 110         }
 111
 112         return 0;
 113     }
 114
 115
 116 .. c:type:: v4l2_exportbuffer
 117
 118 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 119
 120 .. flat-table:: struct v4l2_exportbuffer
 121     :header-rows:  0
 122     :stub-columns: 0
 123     :widths:       1 1 2
 124
 125     * - __u32
 126       - ``type``
 127       - Type of the buffer, same as struct
 128         :c:type:`v4l2_format` ``type`` or struct
 129         :c:type:`v4l2_requestbuffers` ``type``, set
 130         by the application. See :c:type:`v4l2_buf_type`
 131     * - __u32
 132       - ``index``
 133       - Number of the buffer, set by the application. This field is only
 134         used for :ref:`memory mapping <mmap>` I/O and can range from
 135         zero to the number of buffers allocated with the
 136         :ref:`VIDIOC_REQBUFS` and/or
 137         :ref:`VIDIOC_CREATE_BUFS` ioctls.
 138     * - __u32
 139       - ``plane``
 140       - Index of the plane to be exported when using the multi-planar API.
 141         Otherwise this value must be set to zero.
 142     * - __u32
 143       - ``flags``
 144       - Flags for the newly created file, currently only ``O_CLOEXEC``,
 145         ``O_RDONLY``, ``O_WRONLY``, and ``O_RDWR`` are supported, refer to
 146         the manual of open() for more details.
 147     * - __s32
 148       - ``fd``
 149       - The DMABUF file descriptor associated with a buffer. Set by the
 150         driver.
 151     * - __u32
 152       - ``reserved[11]``
 153       - Reserved field for future use. Drivers and applications must set
 154         the array to zero.
 155
 156
 157 Return Value
 158 ============
 159
 160 On success 0 is returned, on error -1 and the ``errno`` variable is set
 161 appropriately. The generic error codes are described at the
 162 :ref:`Generic Error Codes <gen-errors>` chapter.
 163
 164 EINVAL
 165     A queue is not in MMAP mode or DMABUF exporting is not supported or
 166     ``flags`` or ``type`` or ``index`` or ``plane`` fields are invalid.