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