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