Skip to content
Linux Systems Field Manual

linux/include/linux/mm.h

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

File Notes: include/linux/mm.h

Status: reviewed.

Purpose

Declares the public/internal memory-management APIs around fault handling, fault descriptors, VMA operation callbacks, fault locking helpers, and handle_mm_fault().

Key Types And Functions

  • struct vm_fault: descriptor passed through fault handling.
  • struct vm_operations_struct: VMA callback table.
  • release_fault_lock() / assert_fault_locked(): fault lock helpers.
  • maybe_mkwrite(): permission-aware PTE write upgrade helper.
  • finish_fault() and handle_mm_fault(): page fault APIs.

Data Flow

Architecture fault handlers and core VM code fill struct vm_fault with VMA, GFP mask, page offset, address, flags, page-table pointers, original PTE/PMD, COW page, returned page, page-table lock, and preallocated PTE. File-backed and special mappings implement vm_operations_struct callbacks so the core can delegate page lookup, write notification, huge faults, special access, and mapping names.

Fault lock helpers abstract whether the current path holds a per-VMA lock or the process-wide mmap_lock.

Invariants And Safety Contracts

  • vm_ops callbacks document whether the caller holds mmap_lock and whether sleeping is allowed.
  • struct vm_fault PTE/PTL fields are valid only while holding the page-table lock.
  • maybe_mkwrite() upgrades a PTE to writable only if the VMA permits writes.
  • handle_mm_fault() is only valid on MMU builds; NOMMU fallback is BUG.

Rust Translation Guidance

Represent vm_operations_struct as a trait over a locked FaultContext. Different callbacks should encode whether sleeping is allowed and which lock is held. Model pte/ptl as fields only available inside a PteLocked state.

AI-Native Systems Guidance

The VMA operation table is a useful pattern for agent-accessible resources: each region can define fault/fetch, write-before-modify, access, and naming callbacks while the core retains policy and accounting.

Evidence

  • Default retry flags and retry-first behavior are at include/linux/mm.h:680-705.
  • struct vm_fault fields are defined at include/linux/mm.h:720-774.
  • struct vm_operations_struct callback table begins at include/linux/mm.h:778-845.
  • Fault lock helpers select per-VMA lock or mmap_lock at include/linux/mm.h:905-934.
  • maybe_mkwrite() checks VMA write permission before making PTE writable at include/linux/mm.h:1990-2002.
  • handle_mm_fault() declaration is at include/linux/mm.h:3177-3180.