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