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.
  55 They just set the ``index`` field withe the buffer ID to be queued.
  56 When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`,
  57 the driver fills the remaining fields or returns an error code.
  58
  59 By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing
  60 queue. When the ``O_NONBLOCK`` flag was given to the
  61 :ref:`open() <dmx_fopen>` function, ``DMX_DQBUF`` returns
  62 immediately with an ``EAGAIN`` error code when no buffer is available.
  63
  64 The struct :c:type:`dmx_buffer` structure is specified in
  65 :ref:`buffer`.
  66
  67
  68 Return Value
  69 ============
  70
  71 On success 0 is returned, on error -1 and the ``errno`` variable is set
  72 appropriately. The generic error codes are described at the
  73 :ref:`Generic Error Codes <gen-errors>` chapter.
  74
  75 EAGAIN
  76     Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
  77     buffer was in the outgoing queue.
  78
  79 EINVAL
  80     The ``index`` is out of bounds, or no buffers have been allocated yet.
  81
  82 EIO
  83     ``DMX_DQBUF`` failed due to an internal error. Can also indicate
  84     temporary problems like signal loss or CRC errors.