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