0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: DTV.dmx
0003
0004 .. _DMX_REQBUFS:
0005
0006 *****************
0007 ioctl DMX_REQBUFS
0008 *****************
0009
0010 Name
0011 ====
0012
0013 DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O
0014
0015 .. warning:: this API is still experimental
0016
0017 Synopsis
0018 ========
0019
0020 .. c:macro:: DMX_REQBUFS
0021
0022 ``int ioctl(int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp)``
0023
0024 Arguments
0025 =========
0026
0027 ``fd``
0028 File descriptor returned by :c:func:`open()`.
0029
0030 ``argp``
0031 Pointer to struct :c:type:`dmx_requestbuffers`.
0032
0033 Description
0034 ===========
0035
0036 This ioctl is used to initiate a memory mapped or DMABUF based demux I/O.
0037
0038 Memory mapped buffers are located in device memory and must be allocated
0039 with this ioctl before they can be mapped into the application's address
0040 space. User buffers are allocated by applications themselves, and this
0041 ioctl is merely used to switch the driver into user pointer I/O mode and
0042 to setup some internal structures. Similarly, DMABUF buffers are
0043 allocated by applications through a device driver, and this ioctl only
0044 configures the driver into DMABUF I/O mode without performing any direct
0045 allocation.
0046
0047 To allocate device buffers applications initialize all fields of the
0048 struct :c:type:`dmx_requestbuffers` structure. They set the ``count`` field
0049 to the desired number of buffers, and ``size`` to the size of each
0050 buffer.
0051
0052 When the ioctl is called with a pointer to this structure, the driver will
0053 attempt to allocate the requested number of buffers and it stores the actual
0054 number allocated in the ``count`` field. The ``count`` can be smaller than the number requested, even zero, when the driver runs out of free memory. A larger
0055 number is also possible when the driver requires more buffers to
0056 function correctly. The actual allocated buffer size can is returned
0057 at ``size``, and can be smaller than what's requested.
0058
0059 When this I/O method is not supported, the ioctl returns an ``EOPNOTSUPP``
0060 error code.
0061
0062 Applications can call :ref:`DMX_REQBUFS` again to change the number of
0063 buffers, however this cannot succeed when any buffers are still mapped.
0064 A ``count`` value of zero frees all buffers, after aborting or finishing
0065 any DMA in progress.
0066
0067 Return Value
0068 ============
0069
0070 On success 0 is returned, on error -1 and the ``errno`` variable is set
0071 appropriately. The generic error codes are described at the
0072 :ref:`Generic Error Codes <gen-errors>` chapter.
0073
0074 EOPNOTSUPP
0075 The the requested I/O method is not supported.
