1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: V4L 3 4.. _VIDIOC_EXPBUF: 5 6******************* 7ioctl VIDIOC_EXPBUF 8******************* 9 10Name 11==== 12 13VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor. 14 15Synopsis 16======== 17 18.. c:macro:: VIDIOC_EXPBUF 19 20``int ioctl(int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp)`` 21 22Arguments 23========= 24 25``fd`` 26 File descriptor returned by :c:func:`open()`. 27 28``argp`` 29 Pointer to struct :c:type:`v4l2_exportbuffer`. 30 31Description 32=========== 33 34This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O 35method, 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 after 37buffers have been allocated with the 38:ref:`VIDIOC_REQBUFS` ioctl. 39 40To export a buffer, applications fill struct 41:c:type:`v4l2_exportbuffer`. The ``type`` field is 42set to the same buffer type as was previously used with struct 43:c:type:`v4l2_requestbuffers` ``type``. 44Applications must also set the ``index`` field. Valid index numbers 45range from zero to the number of buffers allocated with 46:ref:`VIDIOC_REQBUFS` (struct 47:c:type:`v4l2_requestbuffers` ``count``) minus 48one. For the multi-planar API, applications set the ``plane`` field to 49the index of the plane to be exported. Valid planes range from zero to 50the maximal number of valid planes for the currently active format. For 51the single-planar API, applications must set ``plane`` to zero. 52Additional flags may be posted in the ``flags`` field. Refer to a manual 53for 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 the 55case of multi-planar API, every plane is exported separately using 56multiple :ref:`VIDIOC_EXPBUF` calls. 57 58After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a 59driver. This is a DMABUF file descriptor. The application may pass it to 60other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>` 61for details about importing DMABUF files into V4L2 nodes. It is 62recommended to close a DMABUF file when it is no longer used to allow 63the associated memory to be reclaimed. 64 65Examples 66======== 67 68.. code-block:: c 69 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:: c 88 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_exportbuffer 114 115.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| 116 117.. flat-table:: struct v4l2_exportbuffer 118 :header-rows: 0 119 :stub-columns: 0 120 :widths: 1 1 2 121 122 * - __u32 123 - ``type`` 124 - Type of the buffer, same as struct 125 :c:type:`v4l2_format` ``type`` or struct 126 :c:type:`v4l2_requestbuffers` ``type``, set 127 by the application. See :c:type:`v4l2_buf_type` 128 * - __u32 129 - ``index`` 130 - Number of the buffer, set by the application. This field is only 131 used for :ref:`memory mapping <mmap>` I/O and can range from 132 zero to the number of buffers allocated with the 133 :ref:`VIDIOC_REQBUFS` and/or 134 :ref:`VIDIOC_CREATE_BUFS` ioctls. 135 * - __u32 136 - ``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 * - __u32 140 - ``flags`` 141 - Flags for the newly created file, currently only ``O_CLOEXEC``, 142 ``O_RDONLY``, ``O_WRONLY``, and ``O_RDWR`` are supported, refer to 143 the manual of open() for more details. 144 * - __s32 145 - ``fd`` 146 - The DMABUF file descriptor associated with a buffer. Set by the 147 driver. 148 * - __u32 149 - ``reserved[11]`` 150 - Reserved field for future use. Drivers and applications must set 151 the array to zero. 152 153Return Value 154============ 155 156On success 0 is returned, on error -1 and the ``errno`` variable is set 157appropriately. The generic error codes are described at the 158:ref:`Generic Error Codes <gen-errors>` chapter. 159 160EINVAL 161 A queue is not in MMAP mode or DMABUF exporting is not supported or 162 ``flags`` or ``type`` or ``index`` or ``plane`` fields are invalid. 163