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.. _DMX_EXPBUF:
11
12****************
13ioctl DMX_EXPBUF
14****************
15
16Name
17====
18
19DMX_EXPBUF - Export a buffer as a DMABUF file descriptor.
20
21.. warning:: this API is still experimental
22
23
24Synopsis
25========
26
27.. c:function:: int ioctl( int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp )
28    :name: DMX_EXPBUF
29
30
31Arguments
32=========
33
34``fd``
35    File descriptor returned by :ref:`open() <dmx_fopen>`.
36
37``argp``
38    Pointer to struct :c:type:`dmx_exportbuffer`.
39
40
41Description
42===========
43
44This ioctl is an extension to the memory mapping I/O method.
45It can be used to export a buffer as a DMABUF file at any time after
46buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl.
47
48To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`.
49Applications must set the ``index`` field. Valid index numbers
50range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS`
51(struct :c:type:`dmx_requestbuffers` ``count``) minus one.
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.
55All other fields must be set to zero. In the
56case of multi-planar API, every plane is exported separately using
57multiple :ref:`DMX_EXPBUF` calls.
58
59After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a
60driver, on success. This is a DMABUF file descriptor. The application may
61pass it to other DMABUF-aware devices. It is recommended to close a DMABUF
62file when it is no longer used to allow the associated memory to be reclaimed.
63
64
65Examples
66========
67
68
69.. code-block:: c
70
71    int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd)
72    {
73	struct dmx_exportbuffer expbuf;
74
75	memset(&expbuf, 0, sizeof(expbuf));
76	expbuf.type = bt;
77	expbuf.index = index;
78	if (ioctl(v4lfd, DMX_EXPBUF, &expbuf) == -1) {
79	    perror("DMX_EXPBUF");
80	    return -1;
81	}
82
83	*dmafd = expbuf.fd;
84
85	return 0;
86    }
87
88Return Value
89============
90
91On success 0 is returned, on error -1 and the ``errno`` variable is set
92appropriately. The generic error codes are described at the
93:ref:`Generic Error Codes <gen-errors>` chapter.
94
95EINVAL
96    A queue is not in MMAP mode or DMABUF exporting is not supported or
97    ``flags`` or ``index`` fields are invalid.
98