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

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