0002 NO-MMU MEMORY MAPPING SUPPORT
0005 The kernel has limited support for memory mapping under no-MMU conditions, such
0006 as are used in uClinux environments. From the userspace point of view, memory
0007 mapping is made use of in conjunction with the mmap() system call, the shmat()
0008 call and the execve() system call. From the kernel's point of view, execve()
0009 mapping is actually performed by the binfmt drivers, which call back into the
0010 mmap() routines to do the actual work.
0012 Memory mapping behaviour also involves the way fork(), vfork(), clone() and
0013 ptrace() work. Under uClinux there is no fork(), and clone() must be supplied
0014 the CLONE_VM flag.
0016 The behaviour is similar between the MMU and no-MMU cases, but not identical;
0017 and it's also much more restricted in the latter case:
0019 (*) Anonymous mapping, MAP_PRIVATE
0021 In the MMU case: VM regions backed by arbitrary pages; copy-on-write
0022 across fork.
0024 In the no-MMU case: VM regions backed by arbitrary contiguous runs of
0027 (*) Anonymous mapping, MAP_SHARED
0029 These behave very much like private mappings, except that they're
0030 shared across fork() or clone() without CLONE_VM in the MMU case. Since
0031 the no-MMU case doesn't support these, behaviour is identical to
0032 MAP_PRIVATE there.
0034 (*) File, MAP_PRIVATE, PROT_READ / PROT_EXEC, !PROT_WRITE
0036 In the MMU case: VM regions backed by pages read from file; changes to
0037 the underlying file are reflected in the mapping; copied across fork.
0039 In the no-MMU case:
0041 - If one exists, the kernel will re-use an existing mapping to the
0042 same segment of the same file if that has compatible permissions,
0043 even if this was created by another process.
0045 - If possible, the file mapping will be directly on the backing device
0046 if the backing device has the NOMMU_MAP_DIRECT capability and
0047 appropriate mapping protection capabilities. Ramfs, romfs, cramfs
0048 and mtd might all permit this.
0050 - If the backing device device can't or won't permit direct sharing,
0051 but does have the NOMMU_MAP_COPY capability, then a copy of the
0052 appropriate bit of the file will be read into a contiguous bit of
0053 memory and any extraneous space beyond the EOF will be cleared
0055 - Writes to the file do not affect the mapping; writes to the mapping
0056 are visible in other processes (no MMU protection), but should not
0059 (*) File, MAP_PRIVATE, PROT_READ / PROT_EXEC, PROT_WRITE
0061 In the MMU case: like the non-PROT_WRITE case, except that the pages in
0062 question get copied before the write actually happens. From that point
0063 on writes to the file underneath that page no longer get reflected into
0064 the mapping's backing pages. The page is then backed by swap instead.
0066 In the no-MMU case: works much like the non-PROT_WRITE case, except
0067 that a copy is always taken and never shared.
0069 (*) Regular file / blockdev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
0071 In the MMU case: VM regions backed by pages read from file; changes to
0072 pages written back to file; writes to file reflected into pages backing
0073 mapping; shared across fork.
0075 In the no-MMU case: not supported.
0077 (*) Memory backed regular file, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
0079 In the MMU case: As for ordinary regular files.
0081 In the no-MMU case: The filesystem providing the memory-backed file
0082 (such as ramfs or tmpfs) may choose to honour an open, truncate, mmap
0083 sequence by providing a contiguous sequence of pages to map. In that
0084 case, a shared-writable memory mapping will be possible. It will work
0085 as for the MMU case. If the filesystem does not provide any such
0086 support, then the mapping request will be denied.
0088 (*) Memory backed blockdev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
0090 In the MMU case: As for ordinary regular files.
0092 In the no-MMU case: As for memory backed regular files, but the
0093 blockdev must be able to provide a contiguous run of pages without
0094 truncate being called. The ramdisk driver could do this if it allocated
0095 all its memory as a contiguous array upfront.
0097 (*) Memory backed chardev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
0099 In the MMU case: As for ordinary regular files.
0101 In the no-MMU case: The character device driver may choose to honour
0102 the mmap() by providing direct access to the underlying device if it
0103 provides memory or quasi-memory that can be accessed directly. Examples
0104 of such are frame buffers and flash devices. If the driver does not
0105 provide any such support, then the mapping request will be denied.
0109 FURTHER NOTES ON NO-MMU MMAP
0112 (*) A request for a private mapping of a file may return a buffer that is not
0113 page-aligned. This is because XIP may take place, and the data may not be
0114 paged aligned in the backing store.
0116 (*) A request for an anonymous mapping will always be page aligned. If
0117 possible the size of the request should be a power of two otherwise some
0118 of the space may be wasted as the kernel must allocate a power-of-2
0119 granule but will only discard the excess if appropriately configured as
0120 this has an effect on fragmentation.
0122 (*) The memory allocated by a request for an anonymous mapping will normally
0123 be cleared by the kernel before being returned in accordance with the
0124 Linux man pages (ver 2.22 or later).
0126 In the MMU case this can be achieved with reasonable performance as
0127 regions are backed by virtual pages, with the contents only being mapped
0128 to cleared physical pages when a write happens on that specific page
0129 (prior to which, the pages are effectively mapped to the global zero page
0130 from which reads can take place). This spreads out the time it takes to
0131 initialize the contents of a page - depending on the write-usage of the
0134 In the no-MMU case, however, anonymous mappings are backed by physical
0135 pages, and the entire map is cleared at allocation time. This can cause
0136 significant delays during a userspace malloc() as the C library does an
0137 anonymous mapping and the kernel then does a memset for the entire map.
0139 However, for memory that isn't required to be precleared - such as that
0140 returned by malloc() - mmap() can take a MAP_UNINITIALIZED flag to
0141 indicate to the kernel that it shouldn't bother clearing the memory before
0142 returning it. Note that CONFIG_MMAP_ALLOW_UNINITIALIZED must be enabled
0143 to permit this, otherwise the flag will be ignored.
0145 uClibc uses this to speed up malloc(), and the ELF-FDPIC binfmt uses this
0146 to allocate the brk and stack region.
0148 (*) A list of all the private copy and anonymous mappings on the system is
0149 visible through /proc/maps in no-MMU mode.
0151 (*) A list of all the mappings in use by a process is visible through
0152 /proc/<pid>/maps in no-MMU mode.
0154 (*) Supplying MAP_FIXED or a requesting a particular mapping address will
0155 result in an error.
0157 (*) Files mapped privately usually have to have a read method provided by the
0158 driver or filesystem so that the contents can be read into the memory
0159 allocated if mmap() chooses not to map the backing device directly. An
0160 error will result if they don't. This is most likely to be encountered
0161 with character device files, pipes, fifos and sockets.
0165 INTERPROCESS SHARED MEMORY
0168 Both SYSV IPC SHM shared memory and POSIX shared memory is supported in NOMMU
0169 mode. The former through the usual mechanism, the latter through files created
0170 on ramfs or tmpfs mounts.
0177 Futexes are supported in NOMMU mode if the arch supports them. An error will
0178 be given if an address passed to the futex system call lies outside the
0179 mappings made by a process or if the mapping in which the address lies does not
0180 support futexes (such as an I/O chardev mapping).
0184 NO-MMU MREMAP
0187 The mremap() function is partially supported. It may change the size of a
0188 mapping, and may move it[*] if MREMAP_MAYMOVE is specified and if the new size
0189 of the mapping exceeds the size of the slab object currently occupied by the
0190 memory to which the mapping refers, or if a smaller slab object could be used.
0192 MREMAP_FIXED is not supported, though it is ignored if there's no change of
0193 address and the object does not need to be moved.
0195 Shared mappings may not be moved. Shareable mappings may not be moved either,
0196 even if they are not currently shared.
0198 The mremap() function must be given an exact match for base address and size of
0199 a previously mapped object. It may not be used to create holes in existing
0200 mappings, move parts of existing mappings or resize parts of mappings. It must
0201 act on a complete mapping.
0203 [*] Not currently supported.
0207 PROVIDING SHAREABLE CHARACTER DEVICE SUPPORT
0210 To provide shareable character device support, a driver must provide a
0211 file->f_op->get_unmapped_area() operation. The mmap() routines will call this
0212 to get a proposed address for the mapping. This may return an error if it
0213 doesn't wish to honour the mapping because it's too long, at a weird offset,
0214 under some unsupported combination of flags or whatever.
0216 The driver should also provide backing device information with capabilities set
0217 to indicate the permitted types of mapping on such devices. The default is
0218 assumed to be readable and writable, not executable, and only shareable
0219 directly (can't be copied).
0221 The file->f_op->mmap() operation will be called to actually inaugurate the
0222 mapping. It can be rejected at that point. Returning the ENOSYS error will
0223 cause the mapping to be copied instead if NOMMU_MAP_COPY is specified.
0225 The vm_ops->close() routine will be invoked when the last mapping on a chardev
0226 is removed. An existing mapping will be shared, partially or not, if possible
0227 without notifying the driver.
0229 It is permitted also for the file->f_op->get_unmapped_area() operation to
0230 return -ENOSYS. This will be taken to mean that this operation just doesn't
0231 want to handle it, despite the fact it's got an operation. For instance, it
0232 might try directing the call to a secondary driver which turns out not to
0233 implement it. Such is the case for the framebuffer driver which attempts to
0234 direct the call to the device-specific driver. Under such circumstances, the
0235 mapping request will be rejected if NOMMU_MAP_COPY is not specified, and a
0236 copy mapped otherwise.
0238 IMPORTANT NOTE:
0240 Some types of device may present a different appearance to anyone
0241 looking at them in certain modes. Flash chips can be like this; for
0242 instance if they're in programming or erase mode, you might see the
0243 status reflected in the mapping, instead of the data.
0245 In such a case, care must be taken lest userspace see a shared or a
0246 private mapping showing such information when the driver is busy
0247 controlling the device. Remember especially: private executable
0248 mappings may still be mapped directly off the device under some
0253 PROVIDING SHAREABLE MEMORY-BACKED FILE SUPPORT
0256 Provision of shared mappings on memory backed files is similar to the provision
0257 of support for shared mapped character devices. The main difference is that the
0258 filesystem providing the service will probably allocate a contiguous collection
0259 of pages and permit mappings to be made on that.
0261 It is recommended that a truncate operation applied to such a file that
0262 increases the file size, if that file is empty, be taken as a request to gather
0263 enough pages to honour a mapping. This is required to support POSIX shared
0266 Memory backed devices are indicated by the mapping's backing device info having
0267 the memory_backed flag set.
0271 PROVIDING SHAREABLE BLOCK DEVICE SUPPORT
0274 Provision of shared mappings on block device files is exactly the same as for
0275 character devices. If there isn't a real device underneath, then the driver
0276 should allocate sufficient contiguous memory to honour any supported mapping.
0280 ADJUSTING PAGE TRIMMING BEHAVIOUR
0283 NOMMU mmap automatically rounds up to the nearest power-of-2 number of pages
0284 when performing an allocation. This can have adverse effects on memory
0285 fragmentation, and as such, is left configurable. The default behaviour is to
0286 aggressively trim allocations and discard any excess pages back in to the page
0287 allocator. In order to retain finer-grained control over fragmentation, this
0288 behaviour can either be disabled completely, or bumped up to a higher page
0289 watermark where trimming begins.
0291 Page trimming behaviour is configurable via the sysctl `vm.nr_trim_pages'.