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