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