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.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
19 VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor.
25 .. c:function:: int ioctl( int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp )
33 File descriptor returned by :ref:`open() <func-open>`.
36 Pointer to struct :c:type:`v4l2_exportbuffer`.
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.
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.
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.
80 int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd)
82 struct v4l2_exportbuffer expbuf;
84 memset(&expbuf, 0, sizeof(expbuf));
87 if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
88 perror("VIDIOC_EXPBUF");
100 int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index,
101 int dmafd[], int n_planes)
105 for (i = 0; i < n_planes; ++i) {
106 struct v4l2_exportbuffer expbuf;
108 memset(&expbuf, 0, sizeof(expbuf));
110 expbuf.index = index;
112 if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
113 perror("VIDIOC_EXPBUF");
118 dmafd[i] = expbuf.fd;
125 .. c:type:: v4l2_exportbuffer
127 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
129 .. flat-table:: struct v4l2_exportbuffer
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`
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.
149 - Index of the plane to be exported when using the multi-planar API.
150 Otherwise this value must be set to zero.
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.
158 - The DMABUF file descriptor associated with a buffer. Set by the
162 - Reserved field for future use. Drivers and applications must set
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.
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.