1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _VIDIOC_EXPBUF: 4 5******************* 6ioctl VIDIOC_EXPBUF 7******************* 8 9Name 10==== 11 12VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor. 13 14 15Synopsis 16======== 17 18.. c:function:: int ioctl( int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp ) 19 :name: VIDIOC_EXPBUF 20 21 22Arguments 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 32Description 33=========== 34 35This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O 36method, therefore it is available only for ``V4L2_MEMORY_MMAP`` buffers. 37It can be used to export a buffer as a DMABUF file at any time after 38buffers have been allocated with the 39:ref:`VIDIOC_REQBUFS` ioctl. 40 41To export a buffer, applications fill struct 42:c:type:`v4l2_exportbuffer`. The ``type`` field is 43set to the same buffer type as was previously used with struct 44:c:type:`v4l2_requestbuffers` ``type``. 45Applications must also set the ``index`` field. Valid index numbers 46range from zero to the number of buffers allocated with 47:ref:`VIDIOC_REQBUFS` (struct 48:c:type:`v4l2_requestbuffers` ``count``) minus 49one. For the multi-planar API, applications set the ``plane`` field to 50the index of the plane to be exported. Valid planes range from zero to 51the maximal number of valid planes for the currently active format. For 52the single-planar API, applications must set ``plane`` to zero. 53Additional flags may be posted in the ``flags`` field. Refer to a manual 54for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, 55and O_RDWR are supported. All other fields must be set to zero. In the 56case of multi-planar API, every plane is exported separately using 57multiple :ref:`VIDIOC_EXPBUF` calls. 58 59After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a 60driver. This is a DMABUF file descriptor. The application may pass it to 61other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>` 62for details about importing DMABUF files into V4L2 nodes. It is 63recommended to close a DMABUF file when it is no longer used to allow 64the associated memory to be reclaimed. 65 66 67Examples 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 159Return Value 160============ 161 162On success 0 is returned, on error -1 and the ``errno`` variable is set 163appropriately. The generic error codes are described at the 164:ref:`Generic Error Codes <gen-errors>` chapter. 165 166EINVAL 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. 169