1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _DMX_REQBUFS:
11
12*****************
13ioctl DMX_REQBUFS
14*****************
15
16Name
17====
18
19DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O
20
21.. warning:: this API is still experimental
22
23
24Synopsis
25========
26
27.. c:function:: int ioctl( int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp )
28    :name: DMX_REQBUFS
29
30
31Arguments
32=========
33
34``fd``
35    File descriptor returned by :ref:`open() <dmx_fopen>`.
36
37``argp``
38    Pointer to struct :c:type:`dmx_requestbuffers`.
39
40Description
41===========
42
43This ioctl is used to initiate a memory mapped or DMABUF based demux I/O.
44
45Memory mapped buffers are located in device memory and must be allocated
46with this ioctl before they can be mapped into the application's address
47space. User buffers are allocated by applications themselves, and this
48ioctl is merely used to switch the driver into user pointer I/O mode and
49to setup some internal structures. Similarly, DMABUF buffers are
50allocated by applications through a device driver, and this ioctl only
51configures the driver into DMABUF I/O mode without performing any direct
52allocation.
53
54To allocate device buffers applications initialize all fields of the
55struct :c:type:`dmx_requestbuffers` structure. They set the  ``count`` field
56to the desired number of buffers,  and ``size`` to the size of each
57buffer.
58
59When the ioctl is called with a pointer to this structure, the driver will
60attempt to allocate the requested number of buffers and it stores the actual
61number 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
62number is also possible when the driver requires more buffers to
63function correctly. The actual allocated buffer size can is returned
64at ``size``, and can be smaller than what's requested.
65
66When this I/O method is not supported, the ioctl returns an ``EOPNOTSUPP``
67error code.
68
69Applications can call :ref:`DMX_REQBUFS` again to change the number of
70buffers, however this cannot succeed when any buffers are still mapped.
71A ``count`` value of zero frees all buffers, after aborting or finishing
72any DMA in progress.
73
74
75Return Value
76============
77
78On success 0 is returned, on error -1 and the ``errno`` variable is set
79appropriately. The generic error codes are described at the
80:ref:`Generic Error Codes <gen-errors>` chapter.
81
82EOPNOTSUPP
83    The  the requested I/O method is not supported.
84