mm: add comments to do_mmap(), mmap_region() and vm_mmap() (8ad946eb) · Commits · git / linux-net

mm/mmap.c

+78 −1

Original line number	Diff line number	Diff line
		@@ -277,8 +277,62 @@ static inline bool file_mmap_ok(struct file file, struct inode inode,
		return true;
		}

		/*
		/**
		* do_mmap() - Perform a userland memory mapping into the current process
		* address space of length @len with protection bits @prot, mmap flags @flags
		* (from which VMA flags will be inferred), and any additional VMA flags to
		* apply @vm_flags. If this is a file-backed mapping then the file is specified
		* in @file and page offset into the file via @pgoff.
		*
		* This function does not perform security checks on the file and assumes, if
		* @uf is non-NULL, the caller has provided a list head to track unmap events
		* for userfaultfd @uf.
		*
		* It also simply indicates whether memory population is required by setting
		* @populate, which must be non-NULL, expecting the caller to actually perform
		* this task itself if appropriate.
		*
		* This function will invoke architecture-specific (and if provided and
		* relevant, file system-specific) logic to determine the most appropriate
		* unmapped area in which to place the mapping if not MAP_FIXED.
		*
		* Callers which require userland mmap() behaviour should invoke vm_mmap(),
		* which is also exported for module use.
		*
		* Those which require this behaviour less security checks, userfaultfd and
		* populate behaviour, and who handle the mmap write lock themselves, should
		* call this function.
		*
		* Note that the returned address may reside within a merged VMA if an
		* appropriate merge were to take place, so it doesn't necessarily specify the
		* start of a VMA, rather only the start of a valid mapped range of length
		* @len bytes, rounded down to the nearest page size.
		*
		* The caller must write-lock current->mm->mmap_lock.
		*
		* @file: An optional struct file pointer describing the file which is to be
		* mapped, if a file-backed mapping.
		* @addr: If non-zero, hints at (or if @flags has MAP_FIXED set, specifies) the
		* address at which to perform this mapping. See mmap (2) for details. Must be
		* page-aligned.
		* @len: The length of the mapping. Will be page-aligned and must be at least 1
		* page in size.
		* @prot: Protection bits describing access required to the mapping. See mmap
		* (2) for details.
		* @flags: Flags specifying how the mapping should be performed, see mmap (2)
		* for details.
		* @vm_flags: VMA flags which should be set by default, or 0 otherwise.
		* @pgoff: Page offset into the @file if file-backed, should be 0 otherwise.
		* @populate: A pointer to a value which will be set to 0 if no population of
		* the range is required, or the number of bytes to populate if it is. Must be
		* non-NULL. See mmap (2) for details as to under what circumstances population
		* of the range occurs.
		* @uf: An optional pointer to a list head to track userfaultfd unmap events
		* should unmapping events arise. If provided, it is up to the caller to manage
		* this.
		*
		* Returns: Either an error, or the address at which the requested mapping has
		* been performed.
		*/
		unsigned long do_mmap(struct file *file, unsigned long addr,
		unsigned long len, unsigned long prot,
		@@ -1018,6 +1072,29 @@ int do_munmap(struct mm_struct *mm, unsigned long start, size_t len,
		return do_vmi_munmap(&vmi, mm, start, len, uf, false);
		}

		/**
		* mmap_region() - Actually perform the userland mapping of a VMA into
		* current->mm with known, aligned and overflow-checked @addr and @len, and
		* correctly determined VMA flags @vm_flags and page offset @pgoff.
		*
		* This is an internal memory management function, and should not be used
		* directly.
		*
		* The caller must write-lock current->mm->mmap_lock.
		*
		* @file: If a file-backed mapping, a pointer to the struct file describing the
		* file to be mapped, otherwise NULL.
		* @addr: The page-aligned address at which to perform the mapping.
		* @len: The page-aligned, non-zero, length of the mapping.
		* @vm_flags: The VMA flags which should be applied to the mapping.
		* @pgoff: If @file is specified, the page offset into the file, if not then
		* the virtual page offset in memory of the anonymous mapping.
		* @uf: Optionally, a pointer to a list head used for tracking userfaultfd unmap
		* events.
		*
		* Returns: Either an error, or the address at which the requested mapping has
		* been performed.
		*/
		unsigned long mmap_region(struct file *file, unsigned long addr,
		unsigned long len, vm_flags_t vm_flags, unsigned long pgoff,
		struct list_head *uf)

mm/util.c

+17 −0

Original line number	Diff line number	Diff line
		@@ -582,6 +582,23 @@ unsigned long vm_mmap_pgoff(struct file *file, unsigned long addr,
		return ret;
		}

		/*
		* Perform a userland memory mapping into the current process address space. See
		* the comment for do_mmap() for more details on this operation in general.
		*
		* This differs from do_mmap() in that:
		*
		* a. An offset parameter is provided rather than pgoff, which is both checked
		* for overflow and page alignment.
		* b. mmap locking is performed on the caller's behalf.
		* c. Userfaultfd unmap events and memory population are handled.
		*
		* This means that this function performs essentially the same work as if
		* userland were invoking mmap (2).
		*
		* Returns either an error, or the address at which the requested mapping has
		* been performed.
		*/
		unsigned long vm_mmap(struct file *file, unsigned long addr,
		unsigned long len, unsigned long prot,
		unsigned long flag, unsigned long offset)