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

   1 .. _DMX_QBUF:
   2
   3 *************************
   4 ioctl DMX_QBUF, DMX_DQBUF
   5 *************************
   6
   7 Name
   8 ====
   9
  10 DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver
  11
  12 .. warning:: this API is still experimental
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp )
  19     :name: DMX_QBUF
  20
  21 .. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp )
  22     :name: DMX_DQBUF
  23
  24
  25 Arguments
  26 =========
  27
  28 ``fd``
  29     File descriptor returned by :ref:`open() <dmx_fopen>`.
  30
  31 ``argp``
  32     Pointer to struct :c:type:`dmx_buffer`.
  33
  34
  35 Description
  36 ===========
  37
  38 Applications call the ``DMX_QBUF`` ioctl to enqueue an empty
  39 (capturing) or filled (output) buffer in the driver's incoming queue.
  40 The semantics depend on the selected I/O method.
  41
  42 To enqueue a buffer applications set the ``index`` field. Valid index
  43 numbers range from zero to the number of buffers allocated with
  44 :ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus
  45 one. The contents of the struct :c:type:`dmx_buffer` returned
  46 by a :ref:`DMX_QUERYBUF` ioctl will do as well.
  47
  48 When ``DMX_QBUF`` is called with a pointer to this structure, it locks the
  49 memory pages of the buffer in physical memory, so they cannot be swapped
  50 out to disk. Buffers remain locked until dequeued, until the
  51 the device is closed.
  52
  53 Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled
  54 (capturing) buffer from the driver's outgoing queue. They just set the ``reserved`` field array to zero. When ``DMX_DQBUF`` is called with a
  55 pointer to this structure, the driver fills the remaining fields or
  56 returns an error code.
  57
  58 By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing
  59 queue. When the ``O_NONBLOCK`` flag was given to the
  60 :ref:`open() <dmx_fopen>` function, ``DMX_DQBUF`` returns
  61 immediately with an ``EAGAIN`` error code when no buffer is available.
  62
  63 The struct :c:type:`dmx_buffer` structure is specified in
  64 :ref:`buffer`.
  65
  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 EAGAIN
  75     Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
  76     buffer was in the outgoing queue.
  77
  78 EINVAL
  79     The ``index`` is out of bounds, or no buffers have been allocated yet.
  80
  81 EIO
  82     ``DMX_DQBUF`` failed due to an internal error. Can also indicate
  83     temporary problems like signal loss or CRC errors.