Documentation/userspace-api/media/dvb/dmx-reqbufs.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: DTV.dmx
   3
   4 .. _DMX_REQBUFS:
   5
   6 *****************
   7 ioctl DMX_REQBUFS
   8 *****************
   9
  10 Name
  11 ====
  12
  13 DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O
  14
  15 .. warning:: this API is still experimental
  16
  17 Synopsis
  18 ========
  19
  20 .. c:macro:: DMX_REQBUFS
  21
  22 ``int ioctl(int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp)``
  23
  24 Arguments
  25 =========
  26
  27 ``fd``
  28     File descriptor returned by :c:func:`open()`.
  29
  30 ``argp``
  31     Pointer to struct :c:type:`dmx_requestbuffers`.
  32
  33 Description
  34 ===========
  35
  36 This ioctl is used to initiate a memory mapped or DMABUF based demux I/O.
  37
  38 Memory mapped buffers are located in device memory and must be allocated
  39 with this ioctl before they can be mapped into the application's address
  40 space. User buffers are allocated by applications themselves, and this
  41 ioctl is merely used to switch the driver into user pointer I/O mode and
  42 to setup some internal structures. Similarly, DMABUF buffers are
  43 allocated by applications through a device driver, and this ioctl only
  44 configures the driver into DMABUF I/O mode without performing any direct
  45 allocation.
  46
  47 To allocate device buffers applications initialize all fields of the
  48 struct :c:type:`dmx_requestbuffers` structure. They set the  ``count`` field
  49 to the desired number of buffers,  and ``size`` to the size of each
  50 buffer.
  51
  52 When the ioctl is called with a pointer to this structure, the driver will
  53 attempt to allocate the requested number of buffers and it stores the actual
  54 number allocated in the ``count`` field. The ``count`` can be smaller than the number requested, even zero, when the driver runs out of free memory. A larger
  55 number is also possible when the driver requires more buffers to
  56 function correctly. The actual allocated buffer size can is returned
  57 at ``size``, and can be smaller than what's requested.
  58
  59 When this I/O method is not supported, the ioctl returns an ``EOPNOTSUPP``
  60 error code.
  61
  62 Applications can call :ref:`DMX_REQBUFS` again to change the number of
  63 buffers, however this cannot succeed when any buffers are still mapped.
  64 A ``count`` value of zero frees all buffers, after aborting or finishing
  65 any DMA in progress.
  66
  67 Return Value
  68 ============
  69
  70 On success 0 is returned, on error -1 and the ``errno`` variable is set
  71 appropriately. The generic error codes are described at the
  72 :ref:`Generic Error Codes <gen-errors>` chapter.
  73
  74 EOPNOTSUPP
  75     The  the requested I/O method is not supported.