Orange Pi5 kernel

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