[linux-block.git] / Documentation / mm / remap_file_pages.rst

.. _remap_file_pages:

==============================
remap_file_pages() system call
==============================

The remap_file_pages() system call is used to create a nonlinear mapping,
that is, a mapping in which the pages of the file are mapped into a
nonsequential order in memory. The advantage of using remap_file_pages()
over using repeated calls to mmap(2) is that the former approach does not
require the kernel to create additional VMA (Virtual Memory Area) data
structures.

Supporting of nonlinear mapping requires significant amount of non-trivial
code in kernel virtual memory subsystem including hot paths. Also to get
nonlinear mapping work kernel need a way to distinguish normal page table
entries from entries with file offset (pte_file). Kernel reserves flag in
PTE for this purpose. PTE flags are scarce resource especially on some CPU
architectures. It would be nice to free up the flag for other usage.

Fortunately, there are not many users of remap_file_pages() in the wild.
It's only known that one enterprise RDBMS implementation uses the syscall
on 32-bit systems to map files bigger than can linearly fit into 32-bit
virtual address space. This use-case is not critical anymore since 64-bit
systems are widely available.

The syscall is deprecated and replaced it with an emulation now. The
emulation creates new VMAs instead of nonlinear mappings. It's going to
work slower for rare users of remap_file_pages() but ABI is preserved.

One side effect of emulation (apart from performance) is that user can hit
vm.max_map_count limit more easily due to additional VMAs. See comment for
DEFAULT_MAX_MAP_COUNT for more details on the limit.
Commit	Line	Data
acc9f3a3 MR	1	.. _remap_file_pages:
	2
	3	==============================
	4	remap_file_pages() system call
	5	==============================
	6
33041a0d KS	7	The remap_file_pages() system call is used to create a nonlinear mapping,
	8	that is, a mapping in which the pages of the file are mapped into a
	9	nonsequential order in memory. The advantage of using remap_file_pages()
	10	over using repeated calls to mmap(2) is that the former approach does not
	11	require the kernel to create additional VMA (Virtual Memory Area) data
	12	structures.
	13
	14	Supporting of nonlinear mapping requires significant amount of non-trivial
	15	code in kernel virtual memory subsystem including hot paths. Also to get
	16	nonlinear mapping work kernel need a way to distinguish normal page table
	17	entries from entries with file offset (pte_file). Kernel reserves flag in
	18	PTE for this purpose. PTE flags are scarce resource especially on some CPU
	19	architectures. It would be nice to free up the flag for other usage.
	20
	21	Fortunately, there are not many users of remap_file_pages() in the wild.
	22	It's only known that one enterprise RDBMS implementation uses the syscall
	23	on 32-bit systems to map files bigger than can linearly fit into 32-bit
	24	virtual address space. This use-case is not critical anymore since 64-bit
	25	systems are widely available.
	26
c8d78c18 KS	27	The syscall is deprecated and replaced it with an emulation now. The
	28	emulation creates new VMAs instead of nonlinear mappings. It's going to
	29	work slower for rare users of remap_file_pages() but ABI is preserved.
33041a0d KS	30
	31	One side effect of emulation (apart from performance) is that user can hit
	32	vm.max_map_count limit more easily due to additional VMAs. See comment for
	33	DEFAULT_MAX_MAP_COUNT for more details on the limit.