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