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