highmem: Document kunmap_local()
PATCH 1/1 highmem: Document kunmap_local()
From: Ira Weiny <[email protected]>
Some users of kmap() add an offset to the kmap() address to be used during the mapping.
When converting to kmap_local_page() the base address does not need to be stored because any address within the page can be used in kunmap_local(). However, this was not clear from the documentation and caused some questions.[1]
Document that any address in the page can be used in kunmap_local() to clarify this for future users.
[1] https://lore.kernel.org/lkml/[email protected]/
--- include/linux/highmem-internal.h | 11 +++++++++++ 1 file changed, 11 insertions(+)
include/linux/highmem-internal.h +11 -0
@@ -246,6 +246,17 @@ do { \__kunmap_atomic (__addr); \ }while (0 ) +/** +* kunmap_local - Unmap a page mapped via kmap_local_page(). +* @__addr: An address within the page mapped +* +* __addr is often an address returned from kmap_local_page(). However, +* this address can be any address within the mapped page. It does not need to +* be the exact address returned from kmap_local_page() +* +* Unmapping should be done in the reverse order of the mapping. See +* kmap_local_page() for details. + */#define kunmap_local (__addr) \ do { \ BUILD_BUG_ON(__same_type((__addr), struct page *)); \
Signature · 1 line
2.31.1
Quoted 4 lines · On Sun, Jan 23, 2022 at 05:30:44PM -0800, [email protected] wrote:
+ *
__addris often an address returned fromkmap_local_page(). However,
+ * this address can be any address within the mapped page. It does not need to
+ * be the exact address returned fromkmap_local_page()
+ */
I'd word this a little different:
Quoted 4 lines
+ *
__addris often an address returned fromkmap_local_page(). However,
+ * this address can be any address within the mapped page. It does not need to
+ * be the exact address returned fromkmap_local_page()
+ */
* @__addr can be any address within the mapped page. Commonly it is the
* address return from kmap_local_page(), but it can also include offsets.
But documenting this definitively is a good idea!
PATCH v2 1/1 highmem: Document kunmap_local()
From: Ira Weiny <[email protected]>
Some users of kmap() add an offset to the kmap() address to be used during the mapping.
When converting to kmap_local_page() the base address does not need to be stored because any address within the page can be used in kunmap_local(). However, this was not clear from the documentation and cause some questions.[1]
Document that any address in the page can be used in kunmap_local() to clarify this for future users.
[1] https://lore.kernel.org/lkml/[email protected]/
---
Changes for V2
Use suggested verbiage from Christoph Hellwig
--- include/linux/highmem-internal.h | 10 ++++++++++ 1 file changed, 10 insertions(+)
include/linux/highmem-internal.h +10 -0
@@ -246,6 +246,16 @@ do { \__kunmap_atomic (__addr); \ }while (0 ) +/** +* kunmap_local - Unmap a page mapped via kmap_local_page(). +* @__addr: An address within the page mapped +* +* @__addr can be any address within the mapped page. Commonly it is the +* address return from kmap_local_page(), but it can also include offsets. +* +* Unmapping should be done in the reverse order of the mapping. See +* kmap_local_page() for details. + */#define kunmap_local (__addr) \ do { \ BUILD_BUG_ON(__same_type((__addr), struct page *)); \
Signature · 1 line
2.31.1