Skip to content
Linux Systems Field Manual

linux/mm/filemap.c

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

File Notes: mm/filemap.c

Status: reviewed.

Purpose

Implements the page-cache side of file-backed memory: XArray lookup, folio creation, buffered reads, mmap faults, batch PTE mapping, cache-folio read helpers, and generic buffered writes.

Key Types And Functions

  • filemap_get_entry(): lockless page-cache/XArray lookup.
  • __filemap_get_folio_mpol(): lookup or create a folio with optional locking, allocation, and memory policy.
  • filemap_get_pages(): buffered read batch lookup, readahead, creation, and update loop.
  • filemap_read() and generic_file_read_iter(): generic buffered file reads.
  • filemap_fault(): mmap fault handler for file-backed VMAs.
  • filemap_map_pages(): opportunistic batch mapping for page-cache folios.
  • do_read_cache_folio() and read_cache_folio(): cache read helpers.
  • generic_perform_write(): generic buffered write loop.

Data Flow

Page-cache lookup uses the mapping XArray under RCU. filemap_get_entry() loads the slot, skips exceptional values, pins the folio with folio_try_get(), and reloads the slot to avoid racing with truncation or replacement.

Read paths use filemap_get_pages() to fetch a batch, trigger synchronous or asynchronous readahead, create missing folios, update stale pages, and retry when truncation races invalidate a candidate. File-backed mmap faults enter filemap_fault(), look up or create the target cache folio, drop and retry the mmap_lock when required, lock/read the folio, then return a VM fault result. filemap_map_pages() walks cache entries under RCU and installs multiple PTEs when pages are already resident.

Buffered writes run generic_perform_write(): choose chunks, throttle dirty state, call filesystem write_begin, copy from the iterator atomically enough to avoid deadlocking on mmap faults, then call write_end and handle short copy/forward-progress cases.

Invariants And Safety Contracts

  • Page-cache lookup must tolerate concurrent truncation, replacement, and exceptional XArray values.
  • Folio references are only trusted after the slot is revalidated.
  • filemap_fault() may drop mmap_lock; callers must honor VM fault retry results.
  • Buffered write copy avoids faulting while holding locks that mmap fault paths would need.
  • Filesystems provide a_ops callbacks for actual storage read/write behavior.

Rust Translation Guidance

Represent the page cache as a mapping-owned indexed folio store. RCU-like lookup should return an optionally pinned folio after revalidation. Fault and read paths should encode retry/drop-lock as explicit result variants. Filesystem callbacks should be trait methods with clear lock-state requirements around read_folio, write_begin, and write_end.

AI-Native Systems Guidance

For AI systems, filemap.c is a model for backing-store caches: lockless index lookup, revalidated pins, demand population, batch mapping of hot resident data, and write paths that avoid deadlocks between user data copy and cache mutation.

Evidence

  • The lockless page-cache protocol is documented at mm/filemap.c:1862-1880.
  • filemap_get_entry() uses XArray lookup, RCU, folio pinning, and slot revalidation at mm/filemap.c:1882-1923.
  • __filemap_get_folio_mpol() lookup, lock, create, and add behavior is at mm/filemap.c:1926-2071.
  • filemap_update_page() is at mm/filemap.c:2554-2608.
  • filemap_create_folio() holds invalidate-lock coverage while adding and reading a cache folio at mm/filemap.c:2610-2661.
  • Readahead helper flow is at mm/filemap.c:2663-2675.
  • filemap_get_pages() performs read-batch lookup, readahead, creation, update, and retry behavior at mm/filemap.c:2677-2744.
  • filemap_read() is documented at mm/filemap.c:2765-2775 and begins at line 2778.
  • generic_file_read_iter() is at mm/filemap.c:2945-3009.
  • filemap_fault() is documented at mm/filemap.c:3523-3544 and implements file-backed mmap fault lookup/read/retry behavior at mm/filemap.c:3523-3704.
  • filemap_map_pages() maps resident cache folios under RCU at mm/filemap.c:3889-3993.
  • generic_file_vm_ops wires file-backed VMA operations at mm/filemap.c:4021-4025.
  • do_read_cache_folio() and read_cache_folio() are at mm/filemap.c:4097-4180.
  • generic_perform_write() begins at mm/filemap.c:4335 and runs the write-begin/copy/write-end loop at mm/filemap.c:4339-4415.