Skip to content
Linux Systems Field Manual

linux/mm/mmap.c

Imported from _research/manual-study-linux/file-notes/linux__mm__mmap.c.md.

File Notes: mm/mmap.c

Status: reviewed.

Purpose

Implements virtual-memory-area creation, lookup, expansion, duplication, and teardown around mmap(), munmap(), brk(), process fork, the maple tree VMA index, and the mmap_lock.

Key Types And Functions

  • SYSCALL_DEFINE1(brk): adjusts the process heap.
  • SYSCALL_DEFINE6(mmap_pgoff): syscall entry for mmap.
  • do_mmap(): validates mapping requests and calls mmap_region().
  • find_vma(), find_vma_intersection(), find_vma_prev(): VMA lookup over the maple tree.
  • expand_stack() and mmap_read_lock_maybe_expand(): stack-growth paths that may upgrade from read-side to write-side locking.
  • do_munmap(), vm_munmap(), SYSCALL_DEFINE2(munmap): unmap entry points.
  • dup_mmap(): clones a process address-space VMA layout during fork.

Data Flow

mmap_pgoff() enters with syscall arguments, resolves flags and optional file state, and routes into do_mmap(). do_mmap() requires the caller to hold current->mm->mmap_lock for writing, validates length and offset overflow, checks map-count limits, asks the architecture/address-space policy for an unmapped range, validates fixed-address collision rules, and splits file-backed from anonymous mappings before delegating insertion to mmap_region().

VMA lookup is tree-based. find_vma_intersection() and find_vma() use the mm->mm_mt maple tree rather than scanning a linear list. Previous/next lookup uses VMA_ITERATOR, allowing update paths to walk adjacent regions while keeping tree state local to the iterator.

munmap() goes through do_munmap() and do_vmi_munmap(), making unmap a VMA iterator operation rather than a separate list-specific path. Fork uses dup_mmap() to duplicate the maple tree, filter VM_DONTCOPY ranges, allocate new VMA descriptors, copy anon/file metadata, open VMA operations, insert file mapping interval-tree state, and finally copy page tables.

Invariants And Safety Contracts

  • do_mmap() asserts the write side of mmap_lock.
  • Fixed mappings must not silently replace an existing mapping when MAP_FIXED_NOREPLACE is set.
  • Stack expansion can drop a read lock, acquire the write lock, update the VMA, and downgrade back to a read lock for callers that expect read-side coverage.
  • Forked VMA copies must unwind partially duplicated tree, file, anon-vma, and page-table state on failure.

Rust Translation Guidance

Model the VMA tree as an address-space-owned interval map with mutation methods requiring a MmapWriteGuard. Lookup can return read-guard-tied VMA handles. Fork should be an explicit builder that stages descriptor allocation, anon/file reference acquisition, operation callbacks, and page-table copy so cleanup is automatic if any stage fails.

AI-Native Systems Guidance

The VMA map is a strong pattern for agent memory: keep region metadata indexed by address or logical context span, make region insertion explicit, reject conflicting fixed placements, and treat lazy stack/context growth as a lock upgrade with retry semantics rather than an invisible side effect.

Evidence

  • brk() syscall entry is at mm/mmap.c:116.
  • do_mmap() is documented at mm/mmap.c:280-335 and begins at line 336.
  • do_mmap() asserts the write-held mmap_lock at mm/mmap.c:347.
  • Request validation covers zero length, page alignment, offset overflow, and map-count limits at mm/mmap.c:349-380.
  • Address selection and fixed-range collision checks are at mm/mmap.c:405-414.
  • MAP_LOCKED, file-backed, and anonymous mapping policy branches are at mm/mmap.c:417-543.
  • MAP_NORESERVE, mmap_region(), and populate decisions are at mm/mmap.c:546-565.
  • mmap_pgoff() and the old mmap wrapper are at mm/mmap.c:613-635.
  • Maple-tree VMA lookup is implemented by find_vma_intersection() and find_vma() at mm/mmap.c:876-910.
  • Stack expansion lock upgrade/downgrade is implemented at mm/mmap.c:1015-1052 and mm/mmap.c:1700-1729.
  • do_munmap(), vm_munmap(), and munmap() syscall entry are at mm/mmap.c:1054-1080.
  • dup_mmap() takes old/new mmap locks, duplicates the maple tree, copies VMA metadata, invokes VMA open hooks, inserts file interval-tree state, and calls copy_page_range() at mm/mmap.c:1731-1840.