1 .. SPDX-License-Identifier: GFDL-1.1-no-invari !! 1 .. Permission is granted to copy, distribute and/or modify this
2 .. c:namespace:: DTV.dmx !! 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
3 9
4 .. _dmx-mmap: 10 .. _dmx-mmap:
5 11
6 ***************** 12 *****************
7 Digital TV mmap() 13 Digital TV mmap()
8 ***************** 14 *****************
9 15
10 Name 16 Name
11 ==== 17 ====
12 18
13 dmx-mmap - Map device memory into application 19 dmx-mmap - Map device memory into application address space
14 20
15 .. warning:: this API is still experimental 21 .. warning:: this API is still experimental
16 22
17 Synopsis 23 Synopsis
18 ======== 24 ========
19 25
20 .. code-block:: c 26 .. code-block:: c
21 27
22 #include <unistd.h> 28 #include <unistd.h>
23 #include <sys/mman.h> 29 #include <sys/mman.h>
24 30
>> 31
25 .. c:function:: void *mmap( void *start, size_ 32 .. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset )
>> 33 :name: dmx-mmap
26 34
27 Arguments 35 Arguments
28 ========= 36 =========
29 37
30 ``start`` 38 ``start``
31 Map the buffer to this address in the appl 39 Map the buffer to this address in the application's address space.
32 When the ``MAP_FIXED`` flag is specified, 40 When the ``MAP_FIXED`` flag is specified, ``start`` must be a
33 multiple of the pagesize and mmap will fai 41 multiple of the pagesize and mmap will fail when the specified
34 address cannot be used. Use of this option 42 address cannot be used. Use of this option is discouraged;
35 applications should just specify a ``NULL` 43 applications should just specify a ``NULL`` pointer here.
36 44
37 ``length`` 45 ``length``
38 Length of the memory area to map. This mus 46 Length of the memory area to map. This must be a multiple of the
39 DVB packet length (188, on most drivers). 47 DVB packet length (188, on most drivers).
40 48
41 ``prot`` 49 ``prot``
42 The ``prot`` argument describes the desire 50 The ``prot`` argument describes the desired memory protection.
43 Regardless of the device type and the dire 51 Regardless of the device type and the direction of data exchange it
44 should be set to ``PROT_READ`` | ``PROT_WR 52 should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read
45 and write access to image buffers. Drivers 53 and write access to image buffers. Drivers should support at least
46 this combination of flags. 54 this combination of flags.
47 55
48 ``flags`` 56 ``flags``
49 The ``flags`` parameter specifies the type 57 The ``flags`` parameter specifies the type of the mapped object,
50 mapping options and whether modifications 58 mapping options and whether modifications made to the mapped copy of
51 the page are private to the process or are 59 the page are private to the process or are to be shared with other
52 references. 60 references.
53 61
54 ``MAP_FIXED`` requests that the driver sel 62 ``MAP_FIXED`` requests that the driver selects no other address than
55 the one specified. If the specified addres 63 the one specified. If the specified address cannot be used,
56 :c:func:`mmap()` will fail. If ``MAP_FIXED !! 64 :ref:`mmap() <dmx-mmap>` will fail. If ``MAP_FIXED`` is specified,
57 ``start`` must be a multiple of the pagesi 65 ``start`` must be a multiple of the pagesize. Use of this option is
58 discouraged. 66 discouraged.
59 67
60 One of the ``MAP_SHARED`` or ``MAP_PRIVATE 68 One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set.
61 ``MAP_SHARED`` allows applications to shar 69 ``MAP_SHARED`` allows applications to share the mapped memory with
62 other (e. g. child-) processes. 70 other (e. g. child-) processes.
63 71
64 .. note:: 72 .. note::
65 73
66 The Linux Digital TV applications shoul 74 The Linux Digital TV applications should not set the
67 ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``M 75 ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON``
68 flags. 76 flags.
69 77
70 ``fd`` 78 ``fd``
71 File descriptor returned by :c:func:`open( !! 79 File descriptor returned by :ref:`open() <dmx_fopen>`.
72 80
73 ``offset`` 81 ``offset``
74 Offset of the buffer in device memory, as 82 Offset of the buffer in device memory, as returned by
75 :ref:`DMX_QUERYBUF` ioctl. 83 :ref:`DMX_QUERYBUF` ioctl.
76 84
>> 85
77 Description 86 Description
78 =========== 87 ===========
79 88
80 The :c:func:`mmap()` function asks to map ``le !! 89 The :ref:`mmap() <dmx-mmap>` function asks to map ``length`` bytes starting at
81 ``offset`` in the memory of the device specifi 90 ``offset`` in the memory of the device specified by ``fd`` into the
82 application address space, preferably at addre 91 application address space, preferably at address ``start``. This latter
83 address is a hint only, and is usually specifi 92 address is a hint only, and is usually specified as 0.
84 93
85 Suitable length and offset parameters are quer 94 Suitable length and offset parameters are queried with the
86 :ref:`DMX_QUERYBUF` ioctl. Buffers must be all 95 :ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the
87 :ref:`DMX_REQBUFS` ioctl before they can be qu 96 :ref:`DMX_REQBUFS` ioctl before they can be queried.
88 97
89 To unmap buffers the :c:func:`munmap()` functi !! 98 To unmap buffers the :ref:`munmap() <dmx-munmap>` function is used.
>> 99
90 100
91 Return Value 101 Return Value
92 ============ 102 ============
93 103
94 On success :c:func:`mmap()` returns a pointer !! 104 On success :ref:`mmap() <dmx-mmap>` returns a pointer to the mapped buffer. On
95 error ``MAP_FAILED`` (-1) is returned, and the 105 error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set
96 appropriately. Possible error codes are: 106 appropriately. Possible error codes are:
97 107
98 EBADF 108 EBADF
99 ``fd`` is not a valid file descriptor. 109 ``fd`` is not a valid file descriptor.
100 110
101 EACCES 111 EACCES
102 ``fd`` is not open for reading and writing 112 ``fd`` is not open for reading and writing.
103 113
104 EINVAL 114 EINVAL
105 The ``start`` or ``length`` or ``offset`` 115 The ``start`` or ``length`` or ``offset`` are not suitable. (E. g.
106 they are too large, or not aligned on a `` 116 they are too large, or not aligned on a ``PAGESIZE`` boundary.)
107 117
108 The ``flags`` or ``prot`` value is not sup 118 The ``flags`` or ``prot`` value is not supported.
109 119
110 No buffers have been allocated with the 120 No buffers have been allocated with the
111 :ref:`DMX_REQBUFS` ioctl. 121 :ref:`DMX_REQBUFS` ioctl.
112 122
113 ENOMEM 123 ENOMEM
114 Not enough physical or virtual memory was 124 Not enough physical or virtual memory was available to complete the
115 request. 125 request.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.