git: c1e21468213e - main - pmap_kextract(9): some additions

The branch main has been updated by mhorne:

URL: https://cgit.FreeBSD.org/src/commit/?id=c1e21468213e3ae35c5302f94472f1d996d530cd

commit c1e21468213e3ae35c5302f94472f1d996d530cd
Author:     Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2023-11-06 16:54:18 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2023-11-06 16:54:45 +0000

    pmap_kextract(9): some additions
    
    Mainly, provide a little more detail on the caller's responsibilities.
    
    Suggested by:   kib, jhb
    Reviewed by:    kib, markj
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D42458
---
 share/man/man9/pmap_kextract.9 | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/share/man/man9/pmap_kextract.9 b/share/man/man9/pmap_kextract.9
index 40008a1bc96c..a93bbc70b351 100644
--- a/share/man/man9/pmap_kextract.9
+++ b/share/man/man9/pmap_kextract.9
@@ -31,9 +31,21 @@ The
 function retrieves the underlying physical memory address corresponding to the
 given kernel virtual address
 .Fa va .
-The value of
+The caller is responsible for ensuring that
 .Fa va
-must belong to a valid mapping in the kernel address space.
+belongs to a valid mapping in the kernel address space.
+The returned physical address is only meaningful as long as the mapping remains
+stable, so the caller must also have some knowledge or guarantee of the
+mapping's lifetime.
+For example, it is invalid to call
+.Fn pmap_kextract
+with the address of a malloc'd object while there is a possibility for that
+object to be freed concurrently.
+.Pp
+Unlike
+.Xr pmap_extract 9 ,
+.Fn pmap_kextract
+is safe to be called from any context; it has no internal locking or sleep.
 .Pp
 .Fn vtophys
 is an alias for
@@ -42,7 +54,7 @@ and behaves identically.
 .Sh RETURN VALUES
 The
 .Fn pmap_kextract
-function returns the address of physical memory mapped at the kernel
+function returns the physical address of memory mapped at the kernel
 virtual address
 .Fa va .
 .Pp