163 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_EXPBUF:5 6*******************7ioctl VIDIOC_EXPBUF8*******************9 10Name11====12 13VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor.14 15Synopsis16========17 18.. c:macro:: VIDIOC_EXPBUF19 20``int ioctl(int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp)``21 22Arguments23=========24 25``fd``26 File descriptor returned by :c:func:`open()`.27 28``argp``29 Pointer to struct :c:type:`v4l2_exportbuffer`.30 31Description32===========33 34This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O35method, therefore it is available only for ``V4L2_MEMORY_MMAP`` buffers.36It can be used to export a buffer as a DMABUF file at any time after37buffers have been allocated with the38:ref:`VIDIOC_REQBUFS` ioctl.39 40To export a buffer, applications fill struct41:c:type:`v4l2_exportbuffer`. The ``type`` field is42set to the same buffer type as was previously used with struct43:c:type:`v4l2_requestbuffers` ``type``.44Applications must also set the ``index`` field. Valid index numbers45range from zero to the number of buffers allocated with46:ref:`VIDIOC_REQBUFS` (struct47:c:type:`v4l2_requestbuffers` ``count``) minus48one. For the multi-planar API, applications set the ``plane`` field to49the index of the plane to be exported. Valid planes range from zero to50the maximal number of valid planes for the currently active format. For51the single-planar API, applications must set ``plane`` to zero.52Additional flags may be posted in the ``flags`` field. Refer to a manual53for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,54and O_RDWR are supported. All other fields must be set to zero. In the55case of multi-planar API, every plane is exported separately using56multiple :ref:`VIDIOC_EXPBUF` calls.57 58After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a59driver. This is a DMABUF file descriptor. The application may pass it to60other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>`61for details about importing DMABUF files into V4L2 nodes. It is62recommended to close a DMABUF file when it is no longer used to allow63the associated memory to be reclaimed.64 65Examples66========67 68.. code-block:: c69 70 int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd)71 {72 struct v4l2_exportbuffer expbuf;73 74 memset(&expbuf, 0, sizeof(expbuf));75 expbuf.type = bt;76 expbuf.index = index;77 if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {78 perror("VIDIOC_EXPBUF");79 return -1;80 }81 82 *dmafd = expbuf.fd;83 84 return 0;85 }86 87.. code-block:: c88 89 int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index,90 int dmafd[], int n_planes)91 {92 int i;93 94 for (i = 0; i < n_planes; ++i) {95 struct v4l2_exportbuffer expbuf;96 97 memset(&expbuf, 0, sizeof(expbuf));98 expbuf.type = bt;99 expbuf.index = index;100 expbuf.plane = i;101 if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {102 perror("VIDIOC_EXPBUF");103 while (i)104 close(dmafd[--i]);105 return -1;106 }107 dmafd[i] = expbuf.fd;108 }109 110 return 0;111 }112 113.. c:type:: v4l2_exportbuffer114 115.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|116 117.. flat-table:: struct v4l2_exportbuffer118 :header-rows: 0119 :stub-columns: 0120 :widths: 1 1 2121 122 * - __u32123 - ``type``124 - Type of the buffer, same as struct125 :c:type:`v4l2_format` ``type`` or struct126 :c:type:`v4l2_requestbuffers` ``type``, set127 by the application. See :c:type:`v4l2_buf_type`128 * - __u32129 - ``index``130 - Number of the buffer, set by the application. This field is only131 used for :ref:`memory mapping <mmap>` I/O and can range from132 zero to the number of buffers allocated with the133 :ref:`VIDIOC_REQBUFS` and/or134 :ref:`VIDIOC_CREATE_BUFS` ioctls.135 * - __u32136 - ``plane``137 - Index of the plane to be exported when using the multi-planar API.138 Otherwise this value must be set to zero.139 * - __u32140 - ``flags``141 - Flags for the newly created file, currently only ``O_CLOEXEC``,142 ``O_RDONLY``, ``O_WRONLY``, and ``O_RDWR`` are supported, refer to143 the manual of open() for more details.144 * - __s32145 - ``fd``146 - The DMABUF file descriptor associated with a buffer. Set by the147 driver.148 * - __u32149 - ``reserved[11]``150 - Reserved field for future use. Drivers and applications must set151 the array to zero.152 153Return Value154============155 156On success 0 is returned, on error -1 and the ``errno`` variable is set157appropriately. The generic error codes are described at the158:ref:`Generic Error Codes <gen-errors>` chapter.159 160EINVAL161 A queue is not in MMAP mode or DMABUF exporting is not supported or162 ``flags`` or ``type`` or ``index`` or ``plane`` fields are invalid.163