1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: DTV.dmx
3
4 .. _DMX_EXPBUF:
5
6 ****************
7 ioctl DMX_EXPBUF
8 ****************
9
10 Name
11 ====
12
13 DMX_EXPBUF - Export a buffer as a DMABUF file descriptor.
14
15 .. warning:: this API is still experimental
16
17 Synopsis
18 ========
19
20 .. c:macro:: DMX_EXPBUF
21
22 ``int ioctl(int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp)``
23
24 Arguments
25 =========
26
27 ``fd``
28 File descriptor returned by :c:func:`open()`.
29
30 ``argp``
31 Pointer to struct :c:type:`dmx_exportbuffer`.
32
33 Description
34 ===========
35
36 This ioctl is an extension to the memory mapping I/O method.
37 It can be used to export a buffer as a DMABUF file at any time after
38 buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl.
39
40 To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`.
41 Applications must set the ``index`` field. Valid index numbers
42 range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS`
43 (struct :c:type:`dmx_requestbuffers` ``count``) minus one.
44 Additional flags may be posted in the ``flags`` field. Refer to a manual
45 for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
46 and O_RDWR are supported.
47 All other fields must be set to zero. In the
48 case of multi-planar API, every plane is exported separately using
49 multiple :ref:`DMX_EXPBUF` calls.
50
51 After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a
52 driver, on success. This is a DMABUF file descriptor. The application may
53 pass it to other DMABUF-aware devices. It is recommended to close a DMABUF
54 file when it is no longer used to allow the associated memory to be reclaimed.
55
56 Examples
57 ========
58
59 .. code-block:: c
60
61 int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd)
62 {
63 struct dmx_exportbuffer expbuf;
64
65 memset(&expbuf, 0, sizeof(expbuf));
66 expbuf.type = bt;
67 expbuf.index = index;
68 if (ioctl(v4lfd, DMX_EXPBUF, &expbuf) == -1) {
69 perror("DMX_EXPBUF");
70 return -1;
71 }
72
73 *dmafd = expbuf.fd;
74
75 return 0;
76 }
77
78 Return Value
79 ============
80
81 On success 0 is returned, on error -1 and the ``errno`` variable is set
82 appropriately. The generic error codes are described at the
83 :ref:`Generic Error Codes <gen-errors>` chapter.
84
85 EINVAL
86 A queue is not in MMAP mode or DMABUF exporting is not supported or
87 ``flags`` or ``index`` fields are invalid.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.