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

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