Skip to contentSkip to conversation

Extend and reorganize Highmem's documentation

PATCH Superseded Fabio M. De Francesco 2 participants 11 messages Apr 27, 2022 – Apr 28, 2022

Subsystems (2)

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

v3 cover Extend and reorganize Highmem's documentation

This series has the purpose to extend and reorganize Highmem's documentation.

This is still a work in progress, because some information should still be moved from highmem.rst to highmem.h and highmem-internal.h. Specifically I'm talking about moving the "how to" information to the relevant headers, as it as been suggested by Ira Weiny (Intel).

This series is composed by four patches gathered from a previous series made of two, plus two more single patches. The subject of this cover has changed and the layout of the changes across the four patches has changed too. For this reason it is very hard to show a valid versions' log. Therefore, I decided to start over and drop versions (Maintainers of the previous patch have been told to drop them).

Changes from v1 to v2:

1/4 - Fix typos (Mike Rapoport); re-write the description of @page
because the original was wrong (Ira Weiny); add Ira's and Mike's tags in the commit message.
2/4 - Add Ira's and Mike's tags in the commit message. 3/4 - Rework the subject to better summarize what this patch
changes; merge the section which was removed from highmem.rst with the kdocs of highmem.h (suggested by Ira Weiny); add Ira's tag in the commit message.
4/4 - Reformulate a sentence that was incomprehensible due to my
own mistakes in copying and pasting the text of another paragraph (problem noted by Ira Weiny); refer to the kdocs of kmap_local_page () to show how nested mappings should be handled; fix grammar error; add Ira's tag in the commit message.

Changes from v2 to v3:

1/4 - Add a deprecation notice to kunmap_atomic() for consistency
with the same notice in kmap_atomic() (Sebastian Andrzej Siewior); shorten subject and extend commit message.
2/4 - No changes.
3/4 - No changes.
4/4 - Correct a technical inaccuracy about preemption disabling /
re-enabling in kmap_atomic() / kunmap_atomic() (Sebastian Andrzej Siewior).

Fabio M. De Francesco (4):
mm/highmem: Fix kernel-doc warnings in highmem*.h Documentation/vm: Include kdocs from highmem*.h into highmem.rst Documentation/vm: Move "Using kmap-atomic" to highmem.h Documentation/vm: Rework "Temporary Virtual Mappings" section

 Documentation/vm/highmem.rst     | 104 +++++++++++++++++++------------
 include/linux/highmem-internal.h |  15 ++++-
 include/linux/highmem.h          |  49 +++++++++++----
 3 files changed, 112 insertions(+), 56 deletions(-)
Signature · 1 line
2.34.1
#1 lore raw

PATCH v3 1/4 mm/highmem: Fix kernel-doc warnings in highmem*.h

scripts/kernel-doc -v -none include/linux/highmem* reports the following warnings:

include/linux/highmem.h:160: warning: expecting prototype for kunmap_atomic(). Prototype was for nr_free_highpages() instead include/linux/highmem.h:204: warning: No description found for return value of 'alloc_zeroed_user_highpage_movable' include/linux/highmem-internal.h:256: warning: Function parameter or member '__addr' not described in 'kunmap_atomic' include/linux/highmem-internal.h:256: warning: Excess function parameter 'addr' description in 'kunmap_atomic'

Fix these warnings by (1) moving the kernel-doc comments from highmem.h to highmem-internal.h (which is the file were the kunmap_atomic() macro is actually defined), (2) extending and merging it with the comment which was already in highmem-internal.h, (3) using correct parameter names, (4) adding description of return value of alloc_zeroed_user_highpage_movable(),
(5) correcting some technical inaccuracies in comments, and (5) adding a deprecation notice in kunmap_atomic() for consistency with kmap_atomic().

---
 include/linux/highmem-internal.h | 15 ++++++++++++---
 include/linux/highmem.h          | 20 ++++++--------------
 2 files changed, 18 insertions(+), 17 deletions(-)
include/linux/highmem-internal.h +12 -3
index a77be5630209..9968a1282317 100644
@@ -236,9 +236,18 @@ static inline unsigned long totalhigh_pages(void) { return 0UL; }
 
 #endif /* CONFIG_HIGHMEM */
 
-/*
- * Prevent people trying to call kunmap_atomic() as if it were kunmap()
- * kunmap_atomic() should get the return value of kmap_atomic, not the page.
+/**
+ * kunmap_atomic - Unmap the virtual address mapped by kmap_atomic() - deprecated!
+ * @__addr:       Virtual address to be unmapped
+ *
+ * Unmaps an address previously mapped by kmap_atomic() and re-enables
+ * pagefaults, migration, preemption (the latter was disabled only for
+ * !PREEMP_RT configurations). Mappings should be unmapped in the reverse
+ * order that they were mapped. See kmap_local_page() for details.
+ * @__addr can be any address within the mapped page, so there is no need
+ * to subtract any offset that has been added. In contrast to kunmap(),
+ * this function takes the address returned from kmap_atomic(), not the
+ * page passed to it. The compiler will warn you if you pass the page.
  */
 #define kunmap_atomic(__addr)					\
 do {								\
include/linux/highmem.h +6 -14
index 39bb9b47fa9c..3623319a659d 100644
@@ -37,7 +37,7 @@ static inline void *kmap(struct page *page);
 
 /**
  * kunmap - Unmap the virtual address mapped by kmap()
- * @addr:	Virtual address to be unmapped
+ * @page:	Pointer to the page which was mapped by kmap()
  *
  * Counterpart to kmap(). A NOOP for CONFIG_HIGHMEM=n and for mappings of
  * pages in the low memory area.
@@ -138,24 +138,14 @@ static inline void *kmap_local_folio(struct folio *folio, size_t offset);
  *
  * Returns: The virtual address of the mapping
  *
- * Effectively a wrapper around kmap_local_page() which disables pagefaults
- * and preemption.
+ * In fact a wrapper around kmap_local_page() which disables pagefaults,
+ * migration, preemption (the latter disabled only for !PREEMP_RT
+ * configurations).
  *
  * Do not use in new code. Use kmap_local_page() instead.
  */
 static inline void *kmap_atomic(struct page *page);
 
-/**
- * kunmap_atomic - Unmap the virtual address mapped by kmap_atomic()
- * @addr:	Virtual address to be unmapped
- *
- * Counterpart to kmap_atomic().
- *
- * Effectively a wrapper around kunmap_local() which additionally undoes
- * the side effects of kmap_atomic(), i.e. reenabling pagefaults and
- * preemption.
- */
-
 /* Highmem related interfaces for management code */
 static inline unsigned int nr_free_highpages(void);
 static inline unsigned long totalhigh_pages(void);
@@ -191,6 +181,8 @@ static inline void clear_user_highpage(struct page *page, unsigned long vaddr)
  * @vma: The VMA the page is to be allocated for
  * @vaddr: The virtual address the page will be inserted into
  *
+ * Returns: The allocated and zeroed HIGHMEM page
+ *
  * This function will allocate a page for a VMA that the caller knows will
  * be able to migrate in the future using move_pages() or reclaimed
  *
Signature · 1 line
2.34.1
#2 lore raw

Re: [PATCH v3 1/4] mm/highmem: Fix kernel-doc warnings in highmem*.h

Quoted 6 lines · Fabio M. De Francesco
include/linux/highmem-internal.h +0 -0
@@ -236,9 +236,18 @@ static inline unsigned long totalhigh_pages(void) { return 0UL; }
 
 #endif /* CONFIG_HIGHMEM */
 

include/linux/highmem-internal.h static inline unsigned long totalhigh_pages(void) { return 0UL; } · line 245

Quoted 10 lines
include/linux/highmem-internal.h +7 -3
-/*
- * Prevent people trying to call kunmap_atomic() as if it were kunmap()
- * kunmap_atomic() should get the return value of kmap_atomic, not the page.
+/**
+ * kunmap_atomic - Unmap the virtual address mapped by kmap_atomic() - deprecated!
+ * @__addr:       Virtual address to be unmapped
+ *
+ * Unmaps an address previously mapped by kmap_atomic() and re-enables
+ * pagefaults, migration, preemption (the latter was disabled only for
+ * !PREEMP_RT configurations). Mappings should be unmapped in the reverse

Not sure how detailed you want to put it here as "reverses kmap_atomic() doing." might be okay ;) This indicates the "migration" is disabled for !PREEMPT_RT which is not the case. So maybe something like

* Unmaps an address previously mapped by kmap_atomic() and re-enables
* pagefaults, CPU migration (CONFIG_PREEMPT_RT) or preemption
* (!CONFIG_PREEMPT_RT). Mappings should be unmapped in the reverse

will make it clear.
…

include/linux/highmem.h static inline void *kmap_local_folio(struct folio *folio, size_t offset); · line 143

Quoted 11 lines
include/linux/highmem.h +3 -2
@@ -138,24 +138,14 @@ static inline void *kmap_local_folio(struct folio *folio, size_t offset);
  *
  * Returns: The virtual address of the mapping
  *
- * Effectively a wrapper around kmap_local_page() which disables pagefaults
- * and preemption.
+ * In fact a wrapper around kmap_local_page() which disables pagefaults,
+ * migration, preemption (the latter disabled only for !PREEMP_RT
+ * configurations).

and here.

Sebastian

#3 lore raw

Re: [PATCH v3 1/4] mm/highmem: Fix kernel-doc warnings in highmem*.h

Quoted 4 lines · On giovedì 28 aprile 2022 11:11:46 CEST Sebastian Andrzej Siewior wrote:

include/linux/highmem-internal.h static inline unsigned long totalhigh_pages(void)

Quoted 3 lines · Fabio M. De Francesco
include/linux/highmem-internal.h +0 -0
@@ -236,9 +236,18 @@ static inline unsigned long totalhigh_pages(void) 

{ return 0UL; }

Quoted 5 lines

include/linux/highmem-internal.h static inline unsigned long totalhigh_pages(void) { return 0UL; }

Quoted 5 lines
include/linux/highmem-internal.h +0 -2
 #endif /* CONFIG_HIGHMEM */
 
-/*
- * Prevent people trying to call kunmap_atomic() as if it were 

kunmap()

Quoted 1 line

include/linux/highmem-internal.h static inline unsigned long totalhigh_pages(void) · line 240

Quoted 1 line
include/linux/highmem-internal.h +0 -1
- * kunmap_atomic() should get the return value of kmap_atomic, not the 

page.

Quoted 2 lines

include/linux/highmem-internal.h static inline unsigned long totalhigh_pages(void) · line 239

Quoted 2 lines
include/linux/highmem-internal.h +2 -0
+/**
+ * kunmap_atomic - Unmap the virtual address mapped by kmap_atomic() - 

deprecated!

Quoted 5 lines

include/linux/highmem-internal.h static inline unsigned long totalhigh_pages(void) { return 0UL; }

Quoted 5 lines
include/linux/highmem-internal.h +5 -0
+ * @__addr:       Virtual address to be unmapped
+ *
+ * Unmaps an address previously mapped by kmap_atomic() and re-enables
+ * pagefaults, migration, preemption (the latter was disabled only for
+ * !PREEMP_RT configurations). Mappings should be unmapped in the 

reverse

Quoted 3 lines

Not sure how detailed you want to put it here as "reverses kmap_atomic() doing." might be okay ;)

No, it's not sufficient because Matthew Wilcox said that something like "It is the counterpart of kmap_atomic() for unmapping" (or anything similar) is _not_ what he wants to see.

Furthermore, a large part of this text has been written by him (I'm talking of a couple of weeks ago, when this patch was not part of this series - it was on its own until Ira Weiny asked me to gather 4 patches in one only series).

Quoted 2 lines

This indicates the "migration" is disabled for
!PREEMPT_RT which is not the case.

I read again how kmap_atomic() is defined. There are lots of 'if' statements. Only if the code gets to __kmap_local_pfn_prot(), users can be assured that it unconditionally calls both migrate_disable() and preempt_disable().

Quoted 7 lines

So maybe something like

* Unmaps an address previously mapped by kmap_atomic() and re-enables
* pagefaults, CPU migration (CONFIG_PREEMPT_RT) or preemption
* (!CONFIG_PREEMPT_RT). Mappings should be unmapped in the reverse

will make it clear.

I'm starting to think that this level of detail is too much for users who just need to understand how to use this function as well as kmap_local_page().

I prefer something like the following:

+ * Unmaps an address previously mapped by kmap_atomic() and re-enables
+ * pagefaults and possibly also CPU migration and/or preemption. However,
+ * users should not count on disable of migration and/or preemption as a
+ * side effect of calling kmap_atomic(). Mappings must be unmapped in the
+ * reverse [...]

I'd also like to write the same paragraph for kmap_local_page().

What do you think of being less detailed and instead using the text I wrote above?

Thanks,

Fabio

#4 lore raw

Re: [PATCH v3 1/4] mm/highmem: Fix kernel-doc warnings in highmem*.h

Quoted 8 lines · Fabio M. De Francesco

No, it's not sufficient because Matthew Wilcox said that something like "It is the counterpart of kmap_atomic() for unmapping" (or anything similar) is _not_ what he wants to see.

Furthermore, a large part of this text has been written by him (I'm talking of a couple of weeks ago, when this patch was not part of this series - it was on its own until Ira Weiny asked me to gather 4 patches in one only series).

Sure.

Quoted 7 lines
Quoted 2 lines

This indicates the "migration" is disabled for
!PREEMPT_RT which is not the case.

I read again how kmap_atomic() is defined. There are lots of 'if' statements. Only if the code gets to __kmap_local_pfn_prot(), users can be assured that it unconditionally calls both migrate_disable() and preempt_disable().

Right, that part. Then keep it.

Quoted 20 lines
Quoted 7 lines

So maybe something like

* Unmaps an address previously mapped by kmap_atomic() and re-enables
* pagefaults, CPU migration (CONFIG_PREEMPT_RT) or preemption
* (!CONFIG_PREEMPT_RT). Mappings should be unmapped in the reverse

will make it clear.

I'm starting to think that this level of detail is too much for users who just need to understand how to use this function as well as kmap_local_page().

I prefer something like the following:

+ * Unmaps an address previously mapped by kmap_atomic() and re-enables
+ * pagefaults and possibly also CPU migration and/or preemption. However,
+ * users should not count on disable of migration and/or preemption as a
+ * side effect of calling kmap_atomic(). Mappings must be unmapped in the
+ * reverse [...]

Quoted 4 lines

I'd also like to write the same paragraph for kmap_local_page().

What do you think of being less detailed and instead using the text I wrote above?

Sounds perfect.

Quoted 3 lines

Thanks,

Fabio

Sebastian

#5 lore raw

PATCH v3 2/4 Documentation/vm: Include kdocs from highmem*.h into highmem.rst

In reply to Fabio M. De Francesco

kernel-docs that are in include/linux/highmem.h and in include/linux/highmem-internal.h should be included in highmem.rst.

Use kdocs directives to include the above-mentioned comments into highmem.rst.

---
 Documentation/vm/highmem.rst | 7 +++++++
 1 file changed, 7 insertions(+)
Documentation/vm/highmem.rst +7 -0
index 0f69a9fec34d..ccff08a8211d 100644
@@ -145,3 +145,10 @@ The general recommendation is that you don't use more than 8GiB on a 32-bit
 machine - although more might work for you and your workload, you're pretty
 much on your own - don't expect kernel developers to really care much if things
 come apart.
+
+
+Functions
+=========
+
+.. kernel-doc:: include/linux/highmem.h
+.. kernel-doc:: include/linux/highmem-internal.h
Signature · 1 line
2.34.1
#6 lore raw

PATCH v3 3/4 Documentation/vm: Move "Using kmap-atomic" to highmem.h

In reply to Fabio M. De Francesco

The use of kmap_atomic() is new code is being deprecated in favor of kmap_local_page(). For this reason the "Using kmap_atomic" section in highmem.rst is obsolete and unnecessary, but it can still help developers if it were moved to kdocs in highmem.h.

Therefore, move the relevant parts of this section from highmem.rst and merge them with the kdocs in highmem.h.

Cc Jonathan Corbet <[email protected]>
Cc Thomas Gleixner <[email protected]>
Cc Matthew Wilcox <[email protected]>
Cc Peter Zijlstra <[email protected]>
---
 Documentation/vm/highmem.rst | 35 -----------------------------------
 include/linux/highmem.h      | 31 +++++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 35 deletions(-)
Documentation/vm/highmem.rst +0 -35
index ccff08a8211d..e05bf5524174 100644
@@ -72,41 +72,6 @@ The kernel contains several ways of creating temporary mappings:
   It may be assumed that k[un]map_atomic() won't fail.
 
 
-Using kmap_atomic
-=================
-
-When and where to use kmap_atomic() is straightforward.  It is used when code
-wants to access the contents of a page that might be allocated from high memory
-(see __GFP_HIGHMEM), for example a page in the pagecache.  The API has two
-functions, and they can be used in a manner similar to the following::
-
-	/* Find the page of interest. */
-	struct page *page = find_get_page(mapping, offset);
-
-	/* Gain access to the contents of that page. */
-	void *vaddr = kmap_atomic(page);
-
-	/* Do something to the contents of that page. */
-	memset(vaddr, 0, PAGE_SIZE);
-
-	/* Unmap that page. */
-	kunmap_atomic(vaddr);
-
-Note that the kunmap_atomic() call takes the result of the kmap_atomic() call
-not the argument.
-
-If you need to map two pages because you want to copy from one page to
-another you need to keep the kmap_atomic calls strictly nested, like::
-
-	vaddr1 = kmap_atomic(page1);
-	vaddr2 = kmap_atomic(page2);
-
-	memcpy(vaddr1, vaddr2, PAGE_SIZE);
-
-	kunmap_atomic(vaddr2);
-	kunmap_atomic(vaddr1);
-
-
 Cost of Temporary Mappings
 ==========================
 
include/linux/highmem.h +31 -0
index 3623319a659d..d1f9b298415e 100644
@@ -143,6 +143,37 @@ static inline void *kmap_local_folio(struct folio *folio, size_t offset);
  * configurations).
  *
  * Do not use in new code. Use kmap_local_page() instead.
+ *
+ * It is used in atomic context when code wants to access the contents of a
+ * page that might be allocated from high memory (see __GFP_HIGHMEM), for
+ * example a page in the pagecache.  The API has two functions, and they
+ * can be used in a manner similar to the following:
+ *
+ * -- Find the page of interest. --
+ * struct page *page = find_get_page(mapping, offset);
+ *
+ * -- Gain access to the contents of that page. --
+ * void *vaddr = kmap_atomic(page);
+ *
+ * -- Do something to the contents of that page. --
+ * memset(vaddr, 0, PAGE_SIZE);
+ *
+ * -- Unmap that page. --
+ * kunmap_atomic(vaddr);
+ *
+ * Note that the kunmap_atomic() call takes the result of the kmap_atomic()
+ * call, not the argument.
+ *
+ * If you need to map two pages because you want to copy from one page to
+ * another you need to keep the kmap_atomic calls strictly nested, like:
+ *
+ * vaddr1 = kmap_atomic(page1);
+ * vaddr2 = kmap_atomic(page2);
+ *
+ * memcpy(vaddr1, vaddr2, PAGE_SIZE);
+ *
+ * kunmap_atomic(vaddr2);
+ * kunmap_atomic(vaddr1);
  */
 static inline void *kmap_atomic(struct page *page);
 
Signature · 1 line
2.34.1
#7 lore raw

PATCH v3 4/4 Documentation/vm: Rework "Temporary Virtual Mappings" section

In reply to Fabio M. De Francesco

Extend and rework the "Temporary Virtual Mappings" section of the highmem.rst documentation.

Despite the local kmaps were introduced by Thomas Gleixner in October 2020, documentation was still missing information about them. These additions rely largely on Gleixner's patches, Jonathan Corbet's LWN articles, comments by Ira Weiny and Matthew Wilcox, and in-code comments from highmem.h.

1) Add a paragraph to document kmap_local_page().
2) Reorder the list of functions by decreasing order of preference of use.
3) Rework part of the kmap() entry in list.

Cc Jonathan Corbet <[email protected]>
Cc Thomas Gleixner <[email protected]>
Cc Sebastian Andrzej Siewior <[email protected]>
Cc Matthew Wilcox <[email protected]>
Cc Peter Zijlstra <[email protected]>
---
 Documentation/vm/highmem.rst | 74 ++++++++++++++++++++++++++++++------
 1 file changed, 63 insertions(+), 11 deletions(-)
Documentation/vm/highmem.rst +63 -11
index e05bf5524174..c8aff448612b 100644
@@ -50,26 +50,78 @@ space when they use mm context tags.
 Temporary Virtual Mappings
 ==========================
 
-The kernel contains several ways of creating temporary mappings:
+The kernel contains several ways of creating temporary mappings. The following
+list shows them in order of preference of use.
 
-* vmap().  This can be used to make a long duration mapping of multiple
-  physical pages into a contiguous virtual space.  It needs global
-  synchronization to unmap.
+* kmap_local_page().  This function is used to require short term mappings.
+  It can be invoked from any context (including interrupts) but the mappings
+  can only be used in the context which acquired them.
+
+  This function should be preferred, where feasible, over all the others.
 
-* kmap().  This permits a short duration mapping of a single page.  It needs
-  global synchronization, but is amortized somewhat.  It is also prone to
-  deadlocks when using in a nested fashion, and so it is not recommended for
-  new code.
+  These mappings are thread-local and CPU-local (i.e., migration from one CPU
+  to another is disabled - this is why they are called "local"), but they don't
+  disable preemption. It's valid to take pagefaults in a local kmap region,
+  unless the context in which the local mapping is acquired does not allow it
+  for other reasons.
+
+  kmap_local_page() always returns a valid virtual address and it is assumed
+  that kunmap_local() will never fail.
+
+  If a task holding local kmaps is preempted, the maps are removed on context
+  switch and restored when the task comes back on the CPU. The maps are
+  strictly thread-local and CPU-local, therefore it is guaranteed that the
+  task stays on the CPU and the CPU cannot be unplugged until the local kmaps
+  are released.
+
+  Nesting kmap_local_page() and kmap_atomic() mappings is allowed to a certain
+  extent (up to KMAP_TYPE_NR) but their invocations have to be strictly ordered
+  because the map implementation is stack based. See kmap_local_page () kdocs
+  (included in the "Functions" section) for details on how to manage nested
+  mappings.
 
 * kmap_atomic().  This permits a very short duration mapping of a single
   page.  Since the mapping is restricted to the CPU that issued it, it
   performs well, but the issuing task is therefore required to stay on that
   CPU until it has finished, lest some other task displace its mappings.
 
-  kmap_atomic() may also be used by interrupt contexts, since it is does not
-  sleep and the caller may not sleep until after kunmap_atomic() is called.
+  kmap_atomic() may also be used by interrupt contexts, since it does not
+  sleep and the callers too may not sleep until after kunmap_atomic() is
+  called.
+
+  Each call of kmap_atomic() in the kernel creates a non-preemptible section
+  and disable pagefaults. This could be a source of unwanted latency, so it
+  should be only used if it is absolutely required, otherwise kmap_local_page()
+  should be used where it is feasible.
 
-  It may be assumed that k[un]map_atomic() won't fail.
+  It is assumed that k[un]map_atomic() won't fail.
+
+* kmap().  This should be used to make short duration mapping of a single
+  page with no restrictions on preemption or migration. It comes with an
+  overhead as mapping space is restricted and protected by a global lock
+  for synchronization. When mapping is no longer needed, the address that
+  the page was mapped to must be released with kunmap().
+
+  Mapping changes must be propagated across all the CPUs. kmap() also
+  requires global TLB invalidation when the kmap's pool wraps and it might
+  block when the mapping space is fully utilized until a slot becomes
+  available. Therefore, kmap() is only callable from preemptible context.
+
+  All the above work is necessary if a mapping must last for a relatively
+  long time but the bulk of high-memory mappings in the kernel are
+  short-lived and only used in one place. This means that the cost of
+  kmap() is mostly wasted in such cases. kmap() was not intended for long
+  term mappings but it has morphed in that direction and its use is
+  strongly discouraged in newer code and the set of the preceding functions
+  should be preferred.
+
+  On 64-bit systems, calls to kmap_local_page(), kmap_atomic() and kmap() have
+  no real work to do because a 64-bit address space is more than sufficient to
+  address all the physical memory whose pages are permanently mapped.
+
+* vmap().  This can be used to make a long duration mapping of multiple
+  physical pages into a contiguous virtual space.  It needs global
+  synchronization to unmap.
 
 
 Cost of Temporary Mappings
Signature · 1 line
2.34.1
#8 lore raw

Re: [PATCH v3 4/4] Documentation/vm: Rework "Temporary Virtual Mappings" section

Quoted 4 lines · Fabio M. De Francesco

index e05bf5524174..c8aff448612b 100644

Documentation/vm/highmem.rst +0 -0
@@ -50,26 +50,78 @@ space when they use mm context tags.

…

Documentation/vm/highmem.rst space when they use mm context tags.

Quoted 8 lines
Documentation/vm/highmem.rst +3 -4
-* kmap().  This permits a short duration mapping of a single page.  It needs
-  global synchronization, but is amortized somewhat.  It is also prone to
-  deadlocks when using in a nested fashion, and so it is not recommended for
-  new code.
+  These mappings are thread-local and CPU-local (i.e., migration from one CPU
+  to another is disabled - this is why they are called "local"), but they don't
+  disable preemption. 

So if you replace this block with

These mappings are thread-local and CPU-local meaning that the mapping can only be accessed from within this thread and the thread is bound the CPU while the mapping is active. Even if the thread is preempted (since preemption is never disabled by the function) the CPU can not be unplugged from the system via CPU-hotplug until the mapping is disposed.

The you could drop the latter block

Documentation/vm/highmem.rst space when they use mm context tags.

Quoted 6 lines

It's valid to take pagefaults in a local kmap region,

Documentation/vm/highmem.rst +4 -0
+  unless the context in which the local mapping is acquired does not allow it
+  for other reasons.
 
+  kmap_local_page() always returns a valid virtual address and it is assumed
+  that kunmap_local() will never fail.

from here

Documentation/vm/highmem.rst space when they use mm context tags. · line 75

Quoted 5 lines
Documentation/vm/highmem.rst +5 -0
+  If a task holding local kmaps is preempted, the maps are removed on context
+  switch and restored when the task comes back on the CPU. The maps are
+  strictly thread-local and CPU-local, therefore it is guaranteed that the
+  task stays on the CPU and the CPU cannot be unplugged until the local kmaps
+  are released.

to here since it mostly the same thing.

Documentation/vm/highmem.rst space when they use mm context tags. · line 79

Quoted 3 lines
Documentation/vm/highmem.rst +3 -0
+  Nesting kmap_local_page() and kmap_atomic() mappings is allowed to a certain
+  extent (up to KMAP_TYPE_NR) but their invocations have to be strictly ordered
+  because the map implementation is stack based. See kmap_local_page () kdocs

kmap_local_page () => kmap_local_page()

Quoted 8 lines
Documentation/vm/highmem.rst +2 -0
+  (included in the "Functions" section) for details on how to manage nested
+  mappings.
 
 * kmap_atomic().  This permits a very short duration mapping of a single
   page.  Since the mapping is restricted to the CPU that issued it, it
   performs well, but the issuing task is therefore required to stay on that
   CPU until it has finished, lest some other task displace its mappings.
 

Documentation/vm/highmem.rst space when they use mm context tags. · line 95

Quoted 10 lines
Documentation/vm/highmem.rst +8 -2
-  kmap_atomic() may also be used by interrupt contexts, since it is does not
-  sleep and the caller may not sleep until after kunmap_atomic() is called.
+  kmap_atomic() may also be used by interrupt contexts, since it does not
+  sleep and the callers too may not sleep until after kunmap_atomic() is
+  called.
+
+  Each call of kmap_atomic() in the kernel creates a non-preemptible section
+  and disable pagefaults. This could be a source of unwanted latency, so it
+  should be only used if it is absolutely required, otherwise kmap_local_page()
+  should be used where it is feasible.

I'm not keen about the "absolutely required" wording and "feasible". That said, the other pieces look good, thank you for the work.

Documentation/vm/highmem.rst space when they use mm context tags. · line 97

Quoted 2 lines
Documentation/vm/highmem.rst +1 -1
-  It may be assumed that k[un]map_atomic() won't fail.
+  It is assumed that k[un]map_atomic() won't fail.

Sebastian

#9 lore raw

Re: [PATCH v3 4/4] Documentation/vm: Rework "Temporary Virtual Mappings" section

Quoted 8 lines · On giovedì 28 aprile 2022 11:02:10 CEST Sebastian Andrzej Siewior wrote:
Quoted 4 lines · Fabio M. De Francesco

index e05bf5524174..c8aff448612b 100644

Documentation/vm/highmem.rst +0 -0
@@ -50,26 +50,78 @@ space when they use mm context tags.

…

Quoted 2 lines

-* kmap(). This permits a short duration mapping of a single page. It

needs

Quoted 1 line
Quoted 1 line

- global synchronization, but is amortized somewhat. It is also prone

to

Quoted 1 line
Quoted 1 line

- deadlocks when using in a nested fashion, and so it is not

recommended for

Quoted 2 lines

Documentation/vm/highmem.rst

Quoted 2 lines
Documentation/vm/highmem.rst +1 -1
-  new code.
+  These mappings are thread-local and CPU-local (i.e., migration from 

one CPU

Quoted 1 line
Quoted 1 line

+ to another is disabled - this is why they are called "local"), but

they don't

Quoted 6 lines
Quoted 1 line

+ disable preemption.

So if you replace this block with

These mappings are thread-local and CPU-local meaning that the mapping can only be accessed from within this thread and the thread is bound

the

Quoted 1 line

CPU while the mapping is active. Even if the thread is preempted

(since

Quoted 2 lines

preemption is never disabled by the function) the CPU can not be unplugged from the system via CPU-hotplug until the mapping is

disposed.

OK, I'm too wordy here :(

Quoted 3 lines

The you could drop the latter block

Quoted 1 line

It's valid to take pagefaults in a local kmap

region,

Quoted 1 line
Quoted 1 line

+ unless the context in which the local mapping is acquired does not

allow it

Quoted 3 lines

Documentation/vm/highmem.rst space when they use mm context tags.

Quoted 3 lines
Documentation/vm/highmem.rst +2 -0
+  for other reasons.
 
+  kmap_local_page() always returns a valid virtual address and it is 

assumed

Quoted 5 lines
Quoted 1 line

+ that kunmap_local() will never fail.

from here

Quoted 1 line

+ If a task holding local kmaps is preempted, the maps are removed on

context

Quoted 1 line
Quoted 1 line

+ switch and restored when the task comes back on the CPU. The maps

are

Quoted 1 line
Quoted 1 line

+ strictly thread-local and CPU-local, therefore it is guaranteed that

the

Quoted 1 line
Quoted 1 line

+ task stays on the CPU and the CPU cannot be unplugged until the

local kmaps

Quoted 3 lines
Quoted 1 line

+ are released.

to here since it mostly the same thing.

I agree, this is redundant.

Quoted 2 lines
Quoted 2 lines

+ Nesting kmap_local_page() and kmap_atomic() mappings is allowed to a

certain

Quoted 1 line
Quoted 1 line

+ extent (up to KMAP_TYPE_NR) but their invocations have to be

strictly ordered

Quoted 1 line
Quoted 1 line

+ because the map implementation is stack based. See kmap_local_page

() kdocs

Quoted 2 lines

kmap_local_page () => kmap_local_page()

Sure, it's just a typo.

Quoted 1 line
Quoted 1 line

+ (included in the "Functions" section) for details on how to manage

nested

Quoted 3 lines
Quoted 3 lines

+ mappings.

* kmap_atomic(). This permits a very short duration mapping of a

single

Quoted 2 lines
Quoted 2 lines

page. Since the mapping is restricted to the CPU that issued it, it performs well, but the issuing task is therefore required to stay on

that

Quoted 1 line
Quoted 1 line

CPU until it has finished, lest some other task displace its

mappings.

Quoted 2 lines
Quoted 2 lines

- kmap_atomic() may also be used by interrupt contexts, since it is

does not

Quoted 1 line
Quoted 1 line

- sleep and the caller may not sleep until after kunmap_atomic() is

called.

Quoted 1 line
Quoted 1 line

+ kmap_atomic() may also be used by interrupt contexts, since it does

not

Quoted 1 line
Quoted 1 line

+ sleep and the callers too may not sleep until after kunmap_atomic()

is

Quoted 3 lines

Documentation/vm/highmem.rst space when they use mm context tags.

Quoted 3 lines
Documentation/vm/highmem.rst +3 -0
+  called.
+
+  Each call of kmap_atomic() in the kernel creates a non-preemptible 

section

Quoted 1 line
Quoted 1 line

+ and disable pagefaults. This could be a source of unwanted latency,

so it

Quoted 1 line
Quoted 1 line

+ should be only used if it is absolutely required, otherwise

kmap_local_page()

Quoted 4 lines
Quoted 1 line

+ should be used where it is feasible.

I'm not keen about the "absolutely required" wording and "feasible". That said, the other pieces look good, thank you for the work.

I'll rewrite the last part of this sentence as it follows:

+ should be only used if it is required, otherwise kmap_local_page()
+ should be preferred.

Thank you so much for the time you have spent for reviewing and helping,

Fabio

#10 lore raw

Re: [PATCH v3 4/4] Documentation/vm: Rework "Temporary Virtual Mappings" section

Quoted 11 lines · Fabio M. De Francesco
Quoted 1 line
Quoted 1 line

+ should be only used if it is absolutely required, otherwise

kmap_local_page()

Quoted 4 lines
Quoted 1 line

+ should be used where it is feasible.

I'm not keen about the "absolutely required" wording and "feasible". That said, the other pieces look good, thank you for the work.

I'll rewrite the last part of this sentence as it follows:

+ should be only used if it is required, otherwise kmap_local_page()
+ should be preferred.

Yeah, my point is that it shouldn't be required. Using a kmap_atomic() mapping only because it is not limited to a thread/ CPU sounds wrong. This shouldn't be a valid requirement. Therefore kmap_local() should always be the way to go.

Anyway, I can live with that and hopefully that interface will removed soon :) You yourself, as you pointed out, removed a user or two so I'm confident that it will happen at some point ;)

Quoted 1 line

Thank you so much for the time you have spent for reviewing and helping,

You are welcome.

Quoted 1 line

Fabio

Sebastian