1 ============================= 1 =============================
2 No-MMU memory mapping support 2 No-MMU memory mapping support
3 ============================= 3 =============================
4 4
5 The kernel has limited support for memory mapp 5 The kernel has limited support for memory mapping under no-MMU conditions, such
6 as are used in uClinux environments. From the 6 as are used in uClinux environments. From the userspace point of view, memory
7 mapping is made use of in conjunction with the 7 mapping is made use of in conjunction with the mmap() system call, the shmat()
8 call and the execve() system call. From the ke 8 call and the execve() system call. From the kernel's point of view, execve()
9 mapping is actually performed by the binfmt dr 9 mapping is actually performed by the binfmt drivers, which call back into the
10 mmap() routines to do the actual work. 10 mmap() routines to do the actual work.
11 11
12 Memory mapping behaviour also involves the way 12 Memory mapping behaviour also involves the way fork(), vfork(), clone() and
13 ptrace() work. Under uClinux there is no fork( 13 ptrace() work. Under uClinux there is no fork(), and clone() must be supplied
14 the CLONE_VM flag. 14 the CLONE_VM flag.
15 15
16 The behaviour is similar between the MMU and n 16 The behaviour is similar between the MMU and no-MMU cases, but not identical;
17 and it's also much more restricted in the latt 17 and it's also much more restricted in the latter case:
18 18
19 (#) Anonymous mapping, MAP_PRIVATE 19 (#) Anonymous mapping, MAP_PRIVATE
20 20
21 In the MMU case: VM regions backed by 21 In the MMU case: VM regions backed by arbitrary pages; copy-on-write
22 across fork. 22 across fork.
23 23
24 In the no-MMU case: VM regions backed 24 In the no-MMU case: VM regions backed by arbitrary contiguous runs of
25 pages. 25 pages.
26 26
27 (#) Anonymous mapping, MAP_SHARED 27 (#) Anonymous mapping, MAP_SHARED
28 28
29 These behave very much like private ma 29 These behave very much like private mappings, except that they're
30 shared across fork() or clone() withou 30 shared across fork() or clone() without CLONE_VM in the MMU case. Since
31 the no-MMU case doesn't support these, 31 the no-MMU case doesn't support these, behaviour is identical to
32 MAP_PRIVATE there. 32 MAP_PRIVATE there.
33 33
34 (#) File, MAP_PRIVATE, PROT_READ / PROT_EXEC, 34 (#) File, MAP_PRIVATE, PROT_READ / PROT_EXEC, !PROT_WRITE
35 35
36 In the MMU case: VM regions backed by 36 In the MMU case: VM regions backed by pages read from file; changes to
37 the underlying file are reflected in t 37 the underlying file are reflected in the mapping; copied across fork.
38 38
39 In the no-MMU case: 39 In the no-MMU case:
40 40
41 - If one exists, the kernel will re-u 41 - If one exists, the kernel will re-use an existing mapping to the
42 same segment of the same file if th 42 same segment of the same file if that has compatible permissions,
43 even if this was created by another 43 even if this was created by another process.
44 44
45 - If possible, the file mapping will 45 - If possible, the file mapping will be directly on the backing device
46 if the backing device has the NOMMU 46 if the backing device has the NOMMU_MAP_DIRECT capability and
47 appropriate mapping protection capa 47 appropriate mapping protection capabilities. Ramfs, romfs, cramfs
48 and mtd might all permit this. 48 and mtd might all permit this.
49 49
50 - If the backing device can't or won' 50 - If the backing device can't or won't permit direct sharing,
51 but does have the NOMMU_MAP_COPY ca 51 but does have the NOMMU_MAP_COPY capability, then a copy of the
52 appropriate bit of the file will be 52 appropriate bit of the file will be read into a contiguous bit of
53 memory and any extraneous space bey 53 memory and any extraneous space beyond the EOF will be cleared
54 54
55 - Writes to the file do not affect th 55 - Writes to the file do not affect the mapping; writes to the mapping
56 are visible in other processes (no 56 are visible in other processes (no MMU protection), but should not
57 happen. 57 happen.
58 58
59 (#) File, MAP_PRIVATE, PROT_READ / PROT_EXEC, 59 (#) File, MAP_PRIVATE, PROT_READ / PROT_EXEC, PROT_WRITE
60 60
61 In the MMU case: like the non-PROT_WRI 61 In the MMU case: like the non-PROT_WRITE case, except that the pages in
62 question get copied before the write a 62 question get copied before the write actually happens. From that point
63 on writes to the file underneath that 63 on writes to the file underneath that page no longer get reflected into
64 the mapping's backing pages. The page 64 the mapping's backing pages. The page is then backed by swap instead.
65 65
66 In the no-MMU case: works much like th 66 In the no-MMU case: works much like the non-PROT_WRITE case, except
67 that a copy is always taken and never 67 that a copy is always taken and never shared.
68 68
69 (#) Regular file / blockdev, MAP_SHARED, PROT 69 (#) Regular file / blockdev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
70 70
71 In the MMU case: VM regions backed by 71 In the MMU case: VM regions backed by pages read from file; changes to
72 pages written back to file; writes to 72 pages written back to file; writes to file reflected into pages backing
73 mapping; shared across fork. 73 mapping; shared across fork.
74 74
75 In the no-MMU case: not supported. 75 In the no-MMU case: not supported.
76 76
77 (#) Memory backed regular file, MAP_SHARED, P 77 (#) Memory backed regular file, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
78 78
79 In the MMU case: As for ordinary regul 79 In the MMU case: As for ordinary regular files.
80 80
81 In the no-MMU case: The filesystem pro 81 In the no-MMU case: The filesystem providing the memory-backed file
82 (such as ramfs or tmpfs) may choose to 82 (such as ramfs or tmpfs) may choose to honour an open, truncate, mmap
83 sequence by providing a contiguous seq 83 sequence by providing a contiguous sequence of pages to map. In that
84 case, a shared-writable memory mapping 84 case, a shared-writable memory mapping will be possible. It will work
85 as for the MMU case. If the filesystem 85 as for the MMU case. If the filesystem does not provide any such
86 support, then the mapping request will 86 support, then the mapping request will be denied.
87 87
88 (#) Memory backed blockdev, MAP_SHARED, PROT_ 88 (#) Memory backed blockdev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
89 89
90 In the MMU case: As for ordinary regul 90 In the MMU case: As for ordinary regular files.
91 91
92 In the no-MMU case: As for memory back 92 In the no-MMU case: As for memory backed regular files, but the
93 blockdev must be able to provide a con 93 blockdev must be able to provide a contiguous run of pages without
94 truncate being called. The ramdisk dri 94 truncate being called. The ramdisk driver could do this if it allocated
95 all its memory as a contiguous array u 95 all its memory as a contiguous array upfront.
96 96
97 (#) Memory backed chardev, MAP_SHARED, PROT_R 97 (#) Memory backed chardev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
98 98
99 In the MMU case: As for ordinary regul 99 In the MMU case: As for ordinary regular files.
100 100
101 In the no-MMU case: The character devi 101 In the no-MMU case: The character device driver may choose to honour
102 the mmap() by providing direct access 102 the mmap() by providing direct access to the underlying device if it
103 provides memory or quasi-memory that c 103 provides memory or quasi-memory that can be accessed directly. Examples
104 of such are frame buffers and flash de 104 of such are frame buffers and flash devices. If the driver does not
105 provide any such support, then the map 105 provide any such support, then the mapping request will be denied.
106 106
107 107
108 Further notes on no-MMU MMAP 108 Further notes on no-MMU MMAP
109 ============================ 109 ============================
110 110
111 (#) A request for a private mapping of a file 111 (#) A request for a private mapping of a file may return a buffer that is not
112 page-aligned. This is because XIP may ta 112 page-aligned. This is because XIP may take place, and the data may not be
113 paged aligned in the backing store. 113 paged aligned in the backing store.
114 114
115 (#) A request for an anonymous mapping will a 115 (#) A request for an anonymous mapping will always be page aligned. If
116 possible the size of the request should b 116 possible the size of the request should be a power of two otherwise some
117 of the space may be wasted as the kernel 117 of the space may be wasted as the kernel must allocate a power-of-2
118 granule but will only discard the excess 118 granule but will only discard the excess if appropriately configured as
119 this has an effect on fragmentation. 119 this has an effect on fragmentation.
120 120
121 (#) The memory allocated by a request for an 121 (#) The memory allocated by a request for an anonymous mapping will normally
122 be cleared by the kernel before being ret 122 be cleared by the kernel before being returned in accordance with the
123 Linux man pages (ver 2.22 or later). 123 Linux man pages (ver 2.22 or later).
124 124
125 In the MMU case this can be achieved with 125 In the MMU case this can be achieved with reasonable performance as
126 regions are backed by virtual pages, with 126 regions are backed by virtual pages, with the contents only being mapped
127 to cleared physical pages when a write ha 127 to cleared physical pages when a write happens on that specific page
128 (prior to which, the pages are effectivel 128 (prior to which, the pages are effectively mapped to the global zero page
129 from which reads can take place). This s 129 from which reads can take place). This spreads out the time it takes to
130 initialize the contents of a page - depen 130 initialize the contents of a page - depending on the write-usage of the
131 mapping. 131 mapping.
132 132
133 In the no-MMU case, however, anonymous ma 133 In the no-MMU case, however, anonymous mappings are backed by physical
134 pages, and the entire map is cleared at a 134 pages, and the entire map is cleared at allocation time. This can cause
135 significant delays during a userspace mal 135 significant delays during a userspace malloc() as the C library does an
136 anonymous mapping and the kernel then doe 136 anonymous mapping and the kernel then does a memset for the entire map.
137 137
138 However, for memory that isn't required t 138 However, for memory that isn't required to be precleared - such as that
139 returned by malloc() - mmap() can take a 139 returned by malloc() - mmap() can take a MAP_UNINITIALIZED flag to
140 indicate to the kernel that it shouldn't 140 indicate to the kernel that it shouldn't bother clearing the memory before
141 returning it. Note that CONFIG_MMAP_ALLO 141 returning it. Note that CONFIG_MMAP_ALLOW_UNINITIALIZED must be enabled
142 to permit this, otherwise the flag will b 142 to permit this, otherwise the flag will be ignored.
143 143
144 uClibc uses this to speed up malloc(), an 144 uClibc uses this to speed up malloc(), and the ELF-FDPIC binfmt uses this
145 to allocate the brk and stack region. 145 to allocate the brk and stack region.
146 146
147 (#) A list of all the private copy and anonym 147 (#) A list of all the private copy and anonymous mappings on the system is
148 visible through /proc/maps in no-MMU mode 148 visible through /proc/maps in no-MMU mode.
149 149
150 (#) A list of all the mappings in use by a pr 150 (#) A list of all the mappings in use by a process is visible through
151 /proc/<pid>/maps in no-MMU mode. 151 /proc/<pid>/maps in no-MMU mode.
152 152
153 (#) Supplying MAP_FIXED or a requesting a par 153 (#) Supplying MAP_FIXED or a requesting a particular mapping address will
154 result in an error. 154 result in an error.
155 155
156 (#) Files mapped privately usually have to ha 156 (#) Files mapped privately usually have to have a read method provided by the
157 driver or filesystem so that the contents 157 driver or filesystem so that the contents can be read into the memory
158 allocated if mmap() chooses not to map th 158 allocated if mmap() chooses not to map the backing device directly. An
159 error will result if they don't. This is 159 error will result if they don't. This is most likely to be encountered
160 with character device files, pipes, fifos 160 with character device files, pipes, fifos and sockets.
161 161
162 162
163 Interprocess shared memory 163 Interprocess shared memory
164 ========================== 164 ==========================
165 165
166 Both SYSV IPC SHM shared memory and POSIX shar 166 Both SYSV IPC SHM shared memory and POSIX shared memory is supported in NOMMU
167 mode. The former through the usual mechanism, 167 mode. The former through the usual mechanism, the latter through files created
168 on ramfs or tmpfs mounts. 168 on ramfs or tmpfs mounts.
169 169
170 170
171 Futexes 171 Futexes
172 ======= 172 =======
173 173
174 Futexes are supported in NOMMU mode if the arc 174 Futexes are supported in NOMMU mode if the arch supports them. An error will
175 be given if an address passed to the futex sys 175 be given if an address passed to the futex system call lies outside the
176 mappings made by a process or if the mapping i 176 mappings made by a process or if the mapping in which the address lies does not
177 support futexes (such as an I/O chardev mappin 177 support futexes (such as an I/O chardev mapping).
178 178
179 179
180 No-MMU mremap 180 No-MMU mremap
181 ============= 181 =============
182 182
183 The mremap() function is partially supported. 183 The mremap() function is partially supported. It may change the size of a
184 mapping, and may move it [#]_ if MREMAP_MAYMOV 184 mapping, and may move it [#]_ if MREMAP_MAYMOVE is specified and if the new size
185 of the mapping exceeds the size of the slab ob 185 of the mapping exceeds the size of the slab object currently occupied by the
186 memory to which the mapping refers, or if a sm 186 memory to which the mapping refers, or if a smaller slab object could be used.
187 187
188 MREMAP_FIXED is not supported, though it is ig 188 MREMAP_FIXED is not supported, though it is ignored if there's no change of
189 address and the object does not need to be mov 189 address and the object does not need to be moved.
190 190
191 Shared mappings may not be moved. Shareable m 191 Shared mappings may not be moved. Shareable mappings may not be moved either,
192 even if they are not currently shared. 192 even if they are not currently shared.
193 193
194 The mremap() function must be given an exact m 194 The mremap() function must be given an exact match for base address and size of
195 a previously mapped object. It may not be use 195 a previously mapped object. It may not be used to create holes in existing
196 mappings, move parts of existing mappings or r 196 mappings, move parts of existing mappings or resize parts of mappings. It must
197 act on a complete mapping. 197 act on a complete mapping.
198 198
199 .. [#] Not currently supported. 199 .. [#] Not currently supported.
200 200
201 201
202 Providing shareable character device support 202 Providing shareable character device support
203 ============================================ 203 ============================================
204 204
205 To provide shareable character device support, 205 To provide shareable character device support, a driver must provide a
206 file->f_op->get_unmapped_area() operation. The 206 file->f_op->get_unmapped_area() operation. The mmap() routines will call this
207 to get a proposed address for the mapping. Thi 207 to get a proposed address for the mapping. This may return an error if it
208 doesn't wish to honour the mapping because it' 208 doesn't wish to honour the mapping because it's too long, at a weird offset,
209 under some unsupported combination of flags or 209 under some unsupported combination of flags or whatever.
210 210
211 The driver should also provide backing device 211 The driver should also provide backing device information with capabilities set
212 to indicate the permitted types of mapping on 212 to indicate the permitted types of mapping on such devices. The default is
213 assumed to be readable and writable, not execu 213 assumed to be readable and writable, not executable, and only shareable
214 directly (can't be copied). 214 directly (can't be copied).
215 215
216 The file->f_op->mmap() operation will be calle 216 The file->f_op->mmap() operation will be called to actually inaugurate the
217 mapping. It can be rejected at that point. Ret 217 mapping. It can be rejected at that point. Returning the ENOSYS error will
218 cause the mapping to be copied instead if NOMM 218 cause the mapping to be copied instead if NOMMU_MAP_COPY is specified.
219 219
220 The vm_ops->close() routine will be invoked wh 220 The vm_ops->close() routine will be invoked when the last mapping on a chardev
221 is removed. An existing mapping will be shared 221 is removed. An existing mapping will be shared, partially or not, if possible
222 without notifying the driver. 222 without notifying the driver.
223 223
224 It is permitted also for the file->f_op->get_u 224 It is permitted also for the file->f_op->get_unmapped_area() operation to
225 return -ENOSYS. This will be taken to mean tha 225 return -ENOSYS. This will be taken to mean that this operation just doesn't
226 want to handle it, despite the fact it's got a 226 want to handle it, despite the fact it's got an operation. For instance, it
227 might try directing the call to a secondary dr 227 might try directing the call to a secondary driver which turns out not to
228 implement it. Such is the case for the framebu 228 implement it. Such is the case for the framebuffer driver which attempts to
229 direct the call to the device-specific driver. 229 direct the call to the device-specific driver. Under such circumstances, the
230 mapping request will be rejected if NOMMU_MAP_ 230 mapping request will be rejected if NOMMU_MAP_COPY is not specified, and a
231 copy mapped otherwise. 231 copy mapped otherwise.
232 232
233 .. important:: 233 .. important::
234 234
235 Some types of device may present a dif 235 Some types of device may present a different appearance to anyone
236 looking at them in certain modes. Flas 236 looking at them in certain modes. Flash chips can be like this; for
237 instance if they're in programming or 237 instance if they're in programming or erase mode, you might see the
238 status reflected in the mapping, inste 238 status reflected in the mapping, instead of the data.
239 239
240 In such a case, care must be taken les 240 In such a case, care must be taken lest userspace see a shared or a
241 private mapping showing such informati 241 private mapping showing such information when the driver is busy
242 controlling the device. Remember espec 242 controlling the device. Remember especially: private executable
243 mappings may still be mapped directly 243 mappings may still be mapped directly off the device under some
244 circumstances! 244 circumstances!
245 245
246 246
247 Providing shareable memory-backed file support 247 Providing shareable memory-backed file support
248 ============================================== 248 ==============================================
249 249
250 Provision of shared mappings on memory backed 250 Provision of shared mappings on memory backed files is similar to the provision
251 of support for shared mapped character devices 251 of support for shared mapped character devices. The main difference is that the
252 filesystem providing the service will probably 252 filesystem providing the service will probably allocate a contiguous collection
253 of pages and permit mappings to be made on tha 253 of pages and permit mappings to be made on that.
254 254
255 It is recommended that a truncate operation ap 255 It is recommended that a truncate operation applied to such a file that
256 increases the file size, if that file is empty 256 increases the file size, if that file is empty, be taken as a request to gather
257 enough pages to honour a mapping. This is requ 257 enough pages to honour a mapping. This is required to support POSIX shared
258 memory. 258 memory.
259 259
260 Memory backed devices are indicated by the map 260 Memory backed devices are indicated by the mapping's backing device info having
261 the memory_backed flag set. 261 the memory_backed flag set.
262 262
263 263
264 Providing shareable block device support 264 Providing shareable block device support
265 ======================================== 265 ========================================
266 266
267 Provision of shared mappings on block device f 267 Provision of shared mappings on block device files is exactly the same as for
268 character devices. If there isn't a real devic 268 character devices. If there isn't a real device underneath, then the driver
269 should allocate sufficient contiguous memory t 269 should allocate sufficient contiguous memory to honour any supported mapping.
270 270
271 271
272 Adjusting page trimming behaviour 272 Adjusting page trimming behaviour
273 ================================= 273 =================================
274 274
275 NOMMU mmap automatically rounds up to the near 275 NOMMU mmap automatically rounds up to the nearest power-of-2 number of pages
276 when performing an allocation. This can have 276 when performing an allocation. This can have adverse effects on memory
277 fragmentation, and as such, is left configurab 277 fragmentation, and as such, is left configurable. The default behaviour is to
278 aggressively trim allocations and discard any 278 aggressively trim allocations and discard any excess pages back in to the page
279 allocator. In order to retain finer-grained c 279 allocator. In order to retain finer-grained control over fragmentation, this
280 behaviour can either be disabled completely, o 280 behaviour can either be disabled completely, or bumped up to a higher page
281 watermark where trimming begins. 281 watermark where trimming begins.
282 282
283 Page trimming behaviour is configurable via th 283 Page trimming behaviour is configurable via the sysctl ``vm.nr_trim_pages``.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.