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

Author: mhorne

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