18c2ecf20Sopenharmony_ci.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 28c2ecf20Sopenharmony_ci.. c:namespace:: DTV.dmx 38c2ecf20Sopenharmony_ci 48c2ecf20Sopenharmony_ci.. _DMX_QBUF: 58c2ecf20Sopenharmony_ci 68c2ecf20Sopenharmony_ci************************* 78c2ecf20Sopenharmony_ciioctl DMX_QBUF, DMX_DQBUF 88c2ecf20Sopenharmony_ci************************* 98c2ecf20Sopenharmony_ci 108c2ecf20Sopenharmony_ciName 118c2ecf20Sopenharmony_ci==== 128c2ecf20Sopenharmony_ci 138c2ecf20Sopenharmony_ciDMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver 148c2ecf20Sopenharmony_ci 158c2ecf20Sopenharmony_ci.. warning:: this API is still experimental 168c2ecf20Sopenharmony_ci 178c2ecf20Sopenharmony_ciSynopsis 188c2ecf20Sopenharmony_ci======== 198c2ecf20Sopenharmony_ci 208c2ecf20Sopenharmony_ci.. c:macro:: DMX_QBUF 218c2ecf20Sopenharmony_ci 228c2ecf20Sopenharmony_ci``int ioctl(int fd, DMX_QBUF, struct dmx_buffer *argp)`` 238c2ecf20Sopenharmony_ci 248c2ecf20Sopenharmony_ci.. c:macro:: DMX_DQBUF 258c2ecf20Sopenharmony_ci 268c2ecf20Sopenharmony_ci``int ioctl(int fd, DMX_DQBUF, struct dmx_buffer *argp)`` 278c2ecf20Sopenharmony_ci 288c2ecf20Sopenharmony_ciArguments 298c2ecf20Sopenharmony_ci========= 308c2ecf20Sopenharmony_ci 318c2ecf20Sopenharmony_ci``fd`` 328c2ecf20Sopenharmony_ci File descriptor returned by :c:func:`open()`. 338c2ecf20Sopenharmony_ci 348c2ecf20Sopenharmony_ci``argp`` 358c2ecf20Sopenharmony_ci Pointer to struct :c:type:`dmx_buffer`. 368c2ecf20Sopenharmony_ci 378c2ecf20Sopenharmony_ciDescription 388c2ecf20Sopenharmony_ci=========== 398c2ecf20Sopenharmony_ci 408c2ecf20Sopenharmony_ciApplications call the ``DMX_QBUF`` ioctl to enqueue an empty 418c2ecf20Sopenharmony_ci(capturing) or filled (output) buffer in the driver's incoming queue. 428c2ecf20Sopenharmony_ciThe semantics depend on the selected I/O method. 438c2ecf20Sopenharmony_ci 448c2ecf20Sopenharmony_ciTo enqueue a buffer applications set the ``index`` field. Valid index 458c2ecf20Sopenharmony_cinumbers range from zero to the number of buffers allocated with 468c2ecf20Sopenharmony_ci:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus 478c2ecf20Sopenharmony_cione. The contents of the struct :c:type:`dmx_buffer` returned 488c2ecf20Sopenharmony_ciby a :ref:`DMX_QUERYBUF` ioctl will do as well. 498c2ecf20Sopenharmony_ci 508c2ecf20Sopenharmony_ciWhen ``DMX_QBUF`` is called with a pointer to this structure, it locks the 518c2ecf20Sopenharmony_cimemory pages of the buffer in physical memory, so they cannot be swapped 528c2ecf20Sopenharmony_ciout to disk. Buffers remain locked until dequeued, until the 538c2ecf20Sopenharmony_cithe device is closed. 548c2ecf20Sopenharmony_ci 558c2ecf20Sopenharmony_ciApplications call the ``DMX_DQBUF`` ioctl to dequeue a filled 568c2ecf20Sopenharmony_ci(capturing) buffer from the driver's outgoing queue. 578c2ecf20Sopenharmony_ciThey just set the ``index`` field with the buffer ID to be queued. 588c2ecf20Sopenharmony_ciWhen ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`, 598c2ecf20Sopenharmony_cithe driver fills the remaining fields or returns an error code. 608c2ecf20Sopenharmony_ci 618c2ecf20Sopenharmony_ciBy default ``DMX_DQBUF`` blocks when no buffer is in the outgoing 628c2ecf20Sopenharmony_ciqueue. When the ``O_NONBLOCK`` flag was given to the 638c2ecf20Sopenharmony_ci:c:func:`open()` function, ``DMX_DQBUF`` returns 648c2ecf20Sopenharmony_ciimmediately with an ``EAGAIN`` error code when no buffer is available. 658c2ecf20Sopenharmony_ci 668c2ecf20Sopenharmony_ciThe struct :c:type:`dmx_buffer` structure is specified in 678c2ecf20Sopenharmony_ci:ref:`buffer`. 688c2ecf20Sopenharmony_ci 698c2ecf20Sopenharmony_ciReturn Value 708c2ecf20Sopenharmony_ci============ 718c2ecf20Sopenharmony_ci 728c2ecf20Sopenharmony_ciOn success 0 is returned, on error -1 and the ``errno`` variable is set 738c2ecf20Sopenharmony_ciappropriately. The generic error codes are described at the 748c2ecf20Sopenharmony_ci:ref:`Generic Error Codes <gen-errors>` chapter. 758c2ecf20Sopenharmony_ci 768c2ecf20Sopenharmony_ciEAGAIN 778c2ecf20Sopenharmony_ci Non-blocking I/O has been selected using ``O_NONBLOCK`` and no 788c2ecf20Sopenharmony_ci buffer was in the outgoing queue. 798c2ecf20Sopenharmony_ci 808c2ecf20Sopenharmony_ciEINVAL 818c2ecf20Sopenharmony_ci The ``index`` is out of bounds, or no buffers have been allocated yet. 828c2ecf20Sopenharmony_ci 838c2ecf20Sopenharmony_ciEIO 848c2ecf20Sopenharmony_ci ``DMX_DQBUF`` failed due to an internal error. Can also indicate 858c2ecf20Sopenharmony_ci temporary problems like signal loss or CRC errors. 86