Skip to content
Linux Systems Field Manual

linux/include/linux/mm-types.h

Imported from _research/manual-study-linux/file-notes/linux__include__linux__mm_types.h.md.

File Notes: include/linux/mm_types.h

Status: reviewed.

Purpose

Defines central memory-management data structures: virtual memory areas, address-space locking fields, and page-fault result bitmasks.

Key Types

  • struct vm_area_struct: virtual memory area descriptor.
  • struct mm_struct: process address-space descriptor.
  • vm_fault_t and enum vm_fault_reason: typed fault result bitmask.

Data Flow

A VMA covers [vm_start, vm_end) inside an mm_struct. It stores access permissions, flags, anonymous/file backing, VMA operations, private data, NUMA policy, per-VMA lock/refcount state, interval-tree linkage, userfaultfd state, and PFN tracking state.

mm_struct owns process-wide memory state including VMA count, page-table lock, and mmap_lock. With per-VMA locking enabled, mm_lock_seq coordinates write lock state with VMA readers.

Fault handlers return vm_fault_t bitmasks so the core VM and architecture fault paths can distinguish OOM, SIGBUS, major fault, SIGSEGV, retry, fallback, COW completion, and lock-release completion.

Invariants And Safety Contracts

  • VMA flags should be modified through helper functions, not raw writes.
  • Per-VMA sequence/refcount fields have explicit lock and RCU semantics.
  • mmap_lock layout is performance-sensitive because its hot fields can cause cacheline bouncing.
  • VM_FAULT_COMPLETED means the fault completed while the mmap lock was released; callers must respect that lifetime boundary.

Rust Translation Guidance

Use separate types for AddressSpace, Vma, and FaultResult. Treat VMA flags as an opaque bitflag wrapper with controlled mutation APIs. Encode lock state in read/write VMA guards and mmap guards.

AI-Native Systems Guidance

For agent memory/state systems, represent accessible regions explicitly with permissions, backing store, callbacks, and typed fault results. Do not let an agent keep a mutable handle to a region after a retry/drop-lock outcome.

Evidence

  • vm_area_struct stores address range, mm pointer, permissions, flags, VMA ops, backing file, private data, and anon state at include/linux/mm_types.h:920-984.
  • Per-VMA locking and refcount states are documented at include/linux/mm_types.h:950-1037.
  • mm_struct includes VMA count, page-table lock, mmap_lock, and per-VMA lock sequence state at include/linux/mm_types.h:1218-1262.
  • vm_fault_t and fault reasons are defined at include/linux/mm_types.h:1647-1705.