dmx-expbuf.rst (2324B)
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.