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