Documentation/media/uapi/dvb/dmx-expbuf.rst

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