docs/mm: describe set_memory() and set_direct_map() APIs
Mike Rapoport (Microsoft)
reviewerPATCH v2 1/1 docs/mm: describe set_memory() and set_direct_map() APIs
The set_memory() and set_direct_map() APIs change permissions of existing kernel mappings, but their semantics are only described by the code, and that code differs from architecture to architecture.
Add Documentation/mm/kernel-page-tables.rst that briefly describes what the kernel page tables consist of, defines the semantics both APIs have in common, including the parts that are easy to get wrong, and lists the differences between the architecture implementations.
Add kernel-doc comments for the generic set_memory() and set_direct_map() stubs and link them into Documentation/core-api/mm-api.rst.
---
The semantics of set_memory() and set_direct_map() are currently described only by the code, and the code differs from architecture to architecture.
Document what these APIs actually promise, what they merely hint at, and how the architectures disagree.
The discussions that prompted this:
https://lore.kernel.org/all/[email protected]
https://lore.kernel.org/all/[email protected]
---
v2 changes:
* address Kevin's comments
v1: https://patch.msgid.link/[email protected]
--- Documentation/core-api/mm-api.rst | 9 + Documentation/mm/index.rst | 1 + Documentation/mm/kernel-page-tables.rst | 410 ++++++++++++++++++++++++++++++++ include/linux/set_memory.h | 110 +++++++++ 4 files changed, 530 insertions(+)
Documentation/core-api/mm-api.rst +9 -0
@@ -52,6 +52,15 @@ Virtually Contiguous Mappings .. kernel-doc:: mm/vmalloc.c :export: +Kernel Page Table Permissions +============================= + +.. kernel-doc:: include/linux/set_memory.h + :doc: Kernel page table permissions + +.. kernel-doc:: include/linux/set_memory.h + :internal: + File Mapping and Page Cache ===========================
Documentation/mm/index.rst +1 -0
@@ -25,6 +25,7 @@ see the :doc:`admin guide <../admin-guide/mm/index>`. physical_memory page_tables + kernel-page-tables process_addrs bootmem page_allocation
Documentation/mm/kernel-page-tables.rst new file +410 -0
410 lines not on this page · raw message
include/linux/set_memory.h +110 -0
143 lines not on this page · raw message
---
base-commit: d118502628f8b673be9023db8bdf878f64a7ed45
change-id: 20260909-set-memory-docs-5f1d96c680a6
--
Sincerely yours,
Mike.
Quoted 9 lines · Mike Rapoport (Microsoft)
[...]
Documentation/mm/kernel-page-tables.rst new file +7
-0+Modifying the kernel page tables +================================ + +Except for the vmalloc area, the kernel page tables are mostly static. Still, +there are cases when the permissions of existing kernel mappings have to be +updated, for instance when a module is loaded and its text becomes read-only +and executable, or when a page is temporarily removed from the direct map to
Documentation/mm/kernel-page-tables.rst line 107
Quoted 10 lines
Documentation/mm/kernel-page-tables.rst new file +10
-0+reduce its exposure. + +There are two families of functions for this, both declared in +`include/linux/set_memory.h`: + +* `set_memory_*()` change permissions of an arbitrary kernel mapping. They + take a kernel virtual address and the number of pages. + +* `set_direct_map_*()` change permissions of the direct mapping of the page + frame represented by a `struct page`. They take a `struct page` pointer and
The new phrasing is a mouthful but at least should be accurate :) It should probably say "range of page frames" or something like that though.
Looks good otherwise!
Mike Rapoport
reviewerQuoted 15 lines · Kevin Brodsky
Quoted 14 lines · Mike Rapoport (Microsoft)
[...]
(quoted diff) +12
-0+Modifying the kernel page tables +================================ + +Except for the vmalloc area, the kernel page tables are mostly static. Still, +there are cases when the permissions of existing kernel mappings have to be +updated, for instance when a module is loaded and its text becomes read-only +and executable, or when a page is temporarily removed from the direct map to +reduce its exposure. + +There are two families of functions for this, both declared in +`include/linux/set_memory.h`: +
Quoted 8 lines
Review
Quoted 5 lines
(quoted diff) +5
-0+* `set_memory_*()` change permissions of an arbitrary kernel mapping. They + take a kernel virtual address and the number of pages. + +* `set_direct_map_*()` change permissions of the direct mapping of the page + frame represented by a `struct page`. They take a `struct page` pointer andThe new phrasing is a mouthful but at least should be accurate :) It should probably say "range of page frames" or something like that though.
It gets even more mouthful, but you are right, "range" should be there.
Andrew, can you please fold this in:
Documentation/mm/kernel-page-tables.rst +3 -3
@@ -103,9 +103,9 @@ There are two families of functions for this, both declared in * `set_memory_*()` change permissions of an arbitrary kernel mapping. They take a kernel virtual address and the number of pages. -* `set_direct_map_*()` change permissions of the direct mapping of the page - frame represented by a `struct page`. They take a `struct page` pointer and - the number of pages. +* `set_direct_map_*()` change permissions of the direct mapping for the range + of page frames starting at the page represented by a `struct page`. They take + a `struct page` pointer and the number of pages. Architectures that implement `set_memory()` select `CONFIG_ARCH_HAS_SET_MEMORY`
Quoted 4 lines
Looks good otherwise!
Reviewed-by Kevin Brodsky <[email protected]>
Signature · 2 lines
Sincerely yours, Mike.