tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
media: dvb uAPI docs: document mmap-related ioctls
5 new ioctls were added to the DVB demux API, in order to
handle memory maped I/O. Add documentation for them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
+320
+90
Documentation/media/uapi/dvb/dmx-expbuf.rst
+90
Documentation/media/uapi/dvb/dmx-expbuf.rst
···
1
+
.. _DMX_EXPBUF:
2
+
3
+
****************
4
+
ioctl DMX_EXPBUF
5
+
****************
6
+
7
+
Name
8
+
====
9
+
10
+
DMX_EXPBUF - Export a buffer as a DMABUF file descriptor.
11
+
12
+
.. warning:: this API is still experimental
13
+
14
+
15
+
Synopsis
16
+
========
17
+
18
+
.. c:function:: int ioctl( int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp )
19
+
:name: DMX_EXPBUF
20
+
21
+
22
+
Arguments
23
+
=========
24
+
25
+
``fd``
26
+
File descriptor returned by :ref:`open() <dmx_fopen>`.
27
+
28
+
``argp``
29
+
Pointer to struct :c:type:`dmx_exportbuffer`.
30
+
31
+
32
+
Description
33
+
===========
34
+
35
+
This ioctl is an extension to the memory mapping I/O method.
36
+
It can be used to export a buffer as a DMABUF file at any time after
37
+
buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl.
38
+
39
+
The ``reserved`` array must be zeroed before calling it.
40
+
41
+
To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`.
42
+
Applications must set the ``index`` field. Valid index numbers
43
+
range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS`
44
+
(struct :c:type:`dmx_requestbuffers` ``count``) minus one.
45
+
Additional flags may be posted in the ``flags`` field. Refer to a manual
46
+
for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
47
+
and O_RDWR are supported.
48
+
All other fields must be set to zero. In the
49
+
case of multi-planar API, every plane is exported separately using
50
+
multiple :ref:`DMX_EXPBUF` calls.
51
+
52
+
After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a
53
+
driver, on success. This is a DMABUF file descriptor. The application may
54
+
pass it to other DMABUF-aware devices. It is recommended to close a DMABUF
55
+
file when it is no longer used to allow the associated memory to be reclaimed.
56
+
57
+
58
+
Examples
59
+
========
60
+
61
+
62
+
.. code-block:: c
63
+
64
+
int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd)
65
+
{
66
+
struct dmx_exportbuffer expbuf;
67
+
68
+
memset(&expbuf, 0, sizeof(expbuf));
69
+
expbuf.type = bt;
70
+
expbuf.index = index;
71
+
if (ioctl(v4lfd, DMX_EXPBUF, &expbuf) == -1) {
72
+
perror("DMX_EXPBUF");
73
+
return -1;
74
+
}
75
+
76
+
*dmafd = expbuf.fd;
77
+
78
+
return 0;
79
+
}
80
+
81
+
Return Value
82
+
============
83
+
84
+
On success 0 is returned, on error -1 and the ``errno`` variable is set
85
+
appropriately. The generic error codes are described at the
86
+
:ref:`Generic Error Codes <gen-errors>` chapter.
87
+
88
+
EINVAL
89
+
A queue is not in MMAP mode or DMABUF exporting is not supported or
90
+
``flags`` or ``index`` fields are invalid.
+85
Documentation/media/uapi/dvb/dmx-qbuf.rst
+85
Documentation/media/uapi/dvb/dmx-qbuf.rst
···
1
+
.. _DMX_QBUF:
2
+
3
+
*************************
4
+
ioctl DMX_QBUF, DMX_DQBUF
5
+
*************************
6
+
7
+
Name
8
+
====
9
+
10
+
DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver
11
+
12
+
.. warning:: this API is still experimental
13
+
14
+
15
+
Synopsis
16
+
========
17
+
18
+
.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp )
19
+
:name: DMX_QBUF
20
+
21
+
.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp )
22
+
:name: DMX_DQBUF
23
+
24
+
25
+
Arguments
26
+
=========
27
+
28
+
``fd``
29
+
File descriptor returned by :ref:`open() <dmx_fopen>`.
30
+
31
+
``argp``
32
+
Pointer to struct :c:type:`dmx_buffer`.
33
+
34
+
35
+
Description
36
+
===========
37
+
38
+
Applications call the ``DMX_QBUF`` ioctl to enqueue an empty
39
+
(capturing) or filled (output) buffer in the driver's incoming queue.
40
+
The semantics depend on the selected I/O method.
41
+
42
+
To enqueue a buffer applications set the ``index`` field. Valid index
43
+
numbers range from zero to the number of buffers allocated with
44
+
:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus
45
+
one. The contents of the struct :c:type:`dmx_buffer` returned
46
+
by a :ref:`DMX_QUERYBUF` ioctl will do as well.
47
+
48
+
The and ``reserved`` field must be set to 0.
49
+
50
+
When ``DMX_QBUF`` is called with a pointer to this structure, it locks the
51
+
memory pages of the buffer in physical memory, so they cannot be swapped
52
+
out to disk. Buffers remain locked until dequeued, until the
53
+
the device is closed.
54
+
55
+
Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled
56
+
(capturing) buffer from the driver's outgoing queue. They just set the ``reserved`` field array to zero. When ``DMX_DQBUF`` is called with a
57
+
pointer to this structure, the driver fills the remaining fields or
58
+
returns an error code.
59
+
60
+
By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing
61
+
queue. When the ``O_NONBLOCK`` flag was given to the
62
+
:ref:`open() <dmx_fopen>` function, ``DMX_DQBUF`` returns
63
+
immediately with an ``EAGAIN`` error code when no buffer is available.
64
+
65
+
The struct :c:type:`dmx_buffer` structure is specified in
66
+
:ref:`buffer`.
67
+
68
+
69
+
Return Value
70
+
============
71
+
72
+
On success 0 is returned, on error -1 and the ``errno`` variable is set
73
+
appropriately. The generic error codes are described at the
74
+
:ref:`Generic Error Codes <gen-errors>` chapter.
75
+
76
+
EAGAIN
77
+
Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
78
+
buffer was in the outgoing queue.
79
+
80
+
EINVAL
81
+
The ``index`` is out of bounds, or no buffers have been allocated yet.
82
+
83
+
EIO
84
+
``DMX_DQBUF`` failed due to an internal error. Can also indicate
85
+
temporary problems like signal loss or CRC errors.
+65
Documentation/media/uapi/dvb/dmx-querybuf.rst
+65
Documentation/media/uapi/dvb/dmx-querybuf.rst
···
1
+
.. _DMX_QUERYBUF:
2
+
3
+
******************
4
+
ioctl DMX_QUERYBUF
5
+
******************
6
+
7
+
Name
8
+
====
9
+
10
+
DMX_QUERYBUF - Query the status of a buffer
11
+
12
+
.. warning:: this API is still experimental
13
+
14
+
15
+
Synopsis
16
+
========
17
+
18
+
.. c:function:: int ioctl( int fd, DMX_QUERYBUF, struct dvb_buffer *argp )
19
+
:name: DMX_QUERYBUF
20
+
21
+
22
+
Arguments
23
+
=========
24
+
25
+
``fd``
26
+
File descriptor returned by :ref:`open() <dmx_fopen>`.
27
+
28
+
``argp``
29
+
Pointer to struct :c:type:`dvb_buffer`.
30
+
31
+
32
+
Description
33
+
===========
34
+
35
+
This ioctl is part of the mmap streaming I/O method. It can
36
+
be used to query the status of a buffer at any time after buffers have
37
+
been allocated with the :ref:`DMX_REQBUFS` ioctl.
38
+
39
+
The ``reserved`` array must be zeroed before calling it.
40
+
41
+
Applications set the ``index`` field. Valid index numbers range from zero
42
+
to the number of buffers allocated with :ref:`DMX_REQBUFS`
43
+
(struct :c:type:`dvb_requestbuffers` ``count``) minus one.
44
+
45
+
After calling :ref:`DMX_QUERYBUF` with a pointer to this structure,
46
+
drivers return an error code or fill the rest of the structure.
47
+
48
+
On success, the ``offset`` will contain the offset of the buffer from the
49
+
start of the device memory, the ``length`` field its size, and the
50
+
``bytesused`` the number of bytes occupied by data in the buffer (payload).
51
+
52
+
Return Value
53
+
============
54
+
55
+
On success 0 is returned, the ``offset`` will contain the offset of the
56
+
buffer from the start of the device memory, the ``length`` field its size,
57
+
and the ``bytesused`` the number of bytes occupied by data in the buffer
58
+
(payload).
59
+
60
+
On error it returns -1 and the ``errno`` variable is set
61
+
appropriately. The generic error codes are described at the
62
+
:ref:`Generic Error Codes <gen-errors>` chapter.
63
+
64
+
EINVAL
65
+
The ``index`` is out of bounds.
+76
Documentation/media/uapi/dvb/dmx-reqbufs.rst
+76
Documentation/media/uapi/dvb/dmx-reqbufs.rst
···
1
+
.. _DMX_REQBUFS:
2
+
3
+
*****************
4
+
ioctl DMX_REQBUFS
5
+
*****************
6
+
7
+
Name
8
+
====
9
+
10
+
DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O
11
+
12
+
.. warning:: this API is still experimental
13
+
14
+
15
+
Synopsis
16
+
========
17
+
18
+
.. c:function:: int ioctl( int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp )
19
+
:name: DMX_REQBUFS
20
+
21
+
22
+
Arguments
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
+
31
+
Description
32
+
===========
33
+
34
+
This ioctl is used to initiate a memory mapped or DMABUF based demux I/O.
35
+
36
+
Memory mapped buffers are located in device memory and must be allocated
37
+
with this ioctl before they can be mapped into the application's address
38
+
space. User buffers are allocated by applications themselves, and this
39
+
ioctl is merely used to switch the driver into user pointer I/O mode and
40
+
to setup some internal structures. Similarly, DMABUF buffers are
41
+
allocated by applications through a device driver, and this ioctl only
42
+
configures the driver into DMABUF I/O mode without performing any direct
43
+
allocation.
44
+
45
+
The ``reserved`` array must be zeroed before calling it.
46
+
47
+
To allocate device buffers applications initialize all fields of the
48
+
struct :c:type:`dmx_requestbuffers` structure. They set the ``count`` field
49
+
to the desired number of buffers, and ``size`` to the size of each
50
+
buffer.
51
+
52
+
When the ioctl is called with a pointer to this structure, the driver will
53
+
attempt to allocate the requested number of buffers and it stores the actual
54
+
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
55
+
number is also possible when the driver requires more buffers to
56
+
function correctly. The actual allocated buffer size can is returned
57
+
at ``size``, and can be smaller than what's requested.
58
+
59
+
When this I/O method is not supported, the ioctl returns an ``EOPNOTSUPP``
60
+
error code.
61
+
62
+
Applications can call :ref:`DMX_REQBUFS` again to change the number of
63
+
buffers, however this cannot succeed when any buffers are still mapped.
64
+
A ``count`` value of zero frees all buffers, after aborting or finishing
65
+
any DMA in progress.
66
+
67
+
68
+
Return Value
69
+
============
70
+
71
+
On success 0 is returned, on error -1 and the ``errno`` variable is set
72
+
appropriately. The generic error codes are described at the
73
+
:ref:`Generic Error Codes <gen-errors>` chapter.
74
+
75
+
EOPNOTSUPP
76
+
The the requested I/O method is not supported.