1*4882a593Smuzhiyun.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2*4882a593Smuzhiyun.. c:namespace:: DTV.dmx 3*4882a593Smuzhiyun 4*4882a593Smuzhiyun.. _DMX_QBUF: 5*4882a593Smuzhiyun 6*4882a593Smuzhiyun************************* 7*4882a593Smuzhiyunioctl DMX_QBUF, DMX_DQBUF 8*4882a593Smuzhiyun************************* 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunName 11*4882a593Smuzhiyun==== 12*4882a593Smuzhiyun 13*4882a593SmuzhiyunDMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver 14*4882a593Smuzhiyun 15*4882a593Smuzhiyun.. warning:: this API is still experimental 16*4882a593Smuzhiyun 17*4882a593SmuzhiyunSynopsis 18*4882a593Smuzhiyun======== 19*4882a593Smuzhiyun 20*4882a593Smuzhiyun.. c:macro:: DMX_QBUF 21*4882a593Smuzhiyun 22*4882a593Smuzhiyun``int ioctl(int fd, DMX_QBUF, struct dmx_buffer *argp)`` 23*4882a593Smuzhiyun 24*4882a593Smuzhiyun.. c:macro:: DMX_DQBUF 25*4882a593Smuzhiyun 26*4882a593Smuzhiyun``int ioctl(int fd, DMX_DQBUF, struct dmx_buffer *argp)`` 27*4882a593Smuzhiyun 28*4882a593SmuzhiyunArguments 29*4882a593Smuzhiyun========= 30*4882a593Smuzhiyun 31*4882a593Smuzhiyun``fd`` 32*4882a593Smuzhiyun File descriptor returned by :c:func:`open()`. 33*4882a593Smuzhiyun 34*4882a593Smuzhiyun``argp`` 35*4882a593Smuzhiyun Pointer to struct :c:type:`dmx_buffer`. 36*4882a593Smuzhiyun 37*4882a593SmuzhiyunDescription 38*4882a593Smuzhiyun=========== 39*4882a593Smuzhiyun 40*4882a593SmuzhiyunApplications call the ``DMX_QBUF`` ioctl to enqueue an empty 41*4882a593Smuzhiyun(capturing) or filled (output) buffer in the driver's incoming queue. 42*4882a593SmuzhiyunThe semantics depend on the selected I/O method. 43*4882a593Smuzhiyun 44*4882a593SmuzhiyunTo enqueue a buffer applications set the ``index`` field. Valid index 45*4882a593Smuzhiyunnumbers range from zero to the number of buffers allocated with 46*4882a593Smuzhiyun:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus 47*4882a593Smuzhiyunone. The contents of the struct :c:type:`dmx_buffer` returned 48*4882a593Smuzhiyunby a :ref:`DMX_QUERYBUF` ioctl will do as well. 49*4882a593Smuzhiyun 50*4882a593SmuzhiyunWhen ``DMX_QBUF`` is called with a pointer to this structure, it locks the 51*4882a593Smuzhiyunmemory pages of the buffer in physical memory, so they cannot be swapped 52*4882a593Smuzhiyunout to disk. Buffers remain locked until dequeued, until the 53*4882a593Smuzhiyunthe device is closed. 54*4882a593Smuzhiyun 55*4882a593SmuzhiyunApplications call the ``DMX_DQBUF`` ioctl to dequeue a filled 56*4882a593Smuzhiyun(capturing) buffer from the driver's outgoing queue. 57*4882a593SmuzhiyunThey just set the ``index`` field with the buffer ID to be queued. 58*4882a593SmuzhiyunWhen ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`, 59*4882a593Smuzhiyunthe driver fills the remaining fields or returns an error code. 60*4882a593Smuzhiyun 61*4882a593SmuzhiyunBy default ``DMX_DQBUF`` blocks when no buffer is in the outgoing 62*4882a593Smuzhiyunqueue. When the ``O_NONBLOCK`` flag was given to the 63*4882a593Smuzhiyun:c:func:`open()` function, ``DMX_DQBUF`` returns 64*4882a593Smuzhiyunimmediately with an ``EAGAIN`` error code when no buffer is available. 65*4882a593Smuzhiyun 66*4882a593SmuzhiyunThe struct :c:type:`dmx_buffer` structure is specified in 67*4882a593Smuzhiyun:ref:`buffer`. 68*4882a593Smuzhiyun 69*4882a593SmuzhiyunReturn Value 70*4882a593Smuzhiyun============ 71*4882a593Smuzhiyun 72*4882a593SmuzhiyunOn success 0 is returned, on error -1 and the ``errno`` variable is set 73*4882a593Smuzhiyunappropriately. The generic error codes are described at the 74*4882a593Smuzhiyun:ref:`Generic Error Codes <gen-errors>` chapter. 75*4882a593Smuzhiyun 76*4882a593SmuzhiyunEAGAIN 77*4882a593Smuzhiyun Non-blocking I/O has been selected using ``O_NONBLOCK`` and no 78*4882a593Smuzhiyun buffer was in the outgoing queue. 79*4882a593Smuzhiyun 80*4882a593SmuzhiyunEINVAL 81*4882a593Smuzhiyun The ``index`` is out of bounds, or no buffers have been allocated yet. 82*4882a593Smuzhiyun 83*4882a593SmuzhiyunEIO 84*4882a593Smuzhiyun ``DMX_DQBUF`` failed due to an internal error. Can also indicate 85*4882a593Smuzhiyun temporary problems like signal loss or CRC errors. 86