git: 74e4a8d208f0 - main - pmap: add pmap_kextract(9) man page

The branch main has been updated by mhorne:

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

commit 74e4a8d208f0b3cf2525e3786f3efba71fcdb752
Author:     Mina Galić <freebsd@igalic.co>
AuthorDate: 2023-08-23 00:12:49 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2023-10-13 18:27:24 +0000

    pmap: add pmap_kextract(9) man page
    
    Add a man page for pmap_kextract(9), with alias to vtophys(9). This man
    page is based on pmap_extract(9).
    
    Add it as cross reference in pmap(9), and add comments above the
    function implementations.
    
    Co-authored-by: Graham Perrin <grahamperrin@gmail.com>
    Co-authored-by: mhorne
    Sponsored by:   The FreeBSD Foundation
    Pull Request:   https://github.com/freebsd/freebsd-src/pull/827
---
 share/man/man9/Makefile        |  2 ++
 share/man/man9/pmap.9          |  1 +
 share/man/man9/pmap_kextract.9 | 65 ++++++++++++++++++++++++++++++++++++++++++
 sys/amd64/amd64/pmap.c         |  8 +++++-
 sys/arm64/arm64/pmap.c         |  6 ++++
 sys/riscv/riscv/pmap.c         |  6 ++++
 6 files changed, 87 insertions(+), 1 deletion(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 0b56a47db332..6768f52a38d6 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -268,6 +268,7 @@ MAN=	accept_filter.9 \
 	pmap_copy.9 \
 	pmap_enter.9 \
 	pmap_extract.9 \
+	pmap_kextract.9 \
 	pmap_growkernel.9 \
 	pmap_init.9 \
 	pmap_is_modified.9 \
@@ -1807,6 +1808,7 @@ MLINKS+=PHOLD.9 PRELE.9 \
 	PHOLD.9 PROC_ASSERT_NOT_HELD.9
 MLINKS+=pmap_copy.9 pmap_copy_page.9
 MLINKS+=pmap_extract.9 pmap_extract_and_hold.9
+MLINKS+=pmap_kextract.9 vtophys.9
 MLINKS+=pmap_init.9 pmap_init2.9
 MLINKS+=pmap_is_modified.9 pmap_ts_referenced.9
 MLINKS+=pmap_pinit.9 pmap_pinit0.9 \
diff --git a/share/man/man9/pmap.9 b/share/man/man9/pmap.9
index 3f6a0f63c264..db27fe880afc 100644
--- a/share/man/man9/pmap.9
+++ b/share/man/man9/pmap.9
@@ -97,6 +97,7 @@ operation.
 .Xr pmap_init2 9 ,
 .Xr pmap_is_modified 9 ,
 .Xr pmap_is_prefaultable 9 ,
+.Xr pmap_kextract 9 ,
 .Xr pmap_map 9 ,
 .Xr pmap_mincore 9 ,
 .Xr pmap_object_init_pt 9 ,
diff --git a/share/man/man9/pmap_kextract.9 b/share/man/man9/pmap_kextract.9
new file mode 100644
index 000000000000..dd73446648f2
--- /dev/null
+++ b/share/man/man9/pmap_kextract.9
@@ -0,0 +1,65 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2023 The FreeBSD Foundation
+.\"
+.\" This manual page was written by Mina Galić <FreeBSD@igalic.co> under
+.\" sponsorship from the FreeBSD Foundation.
+.\"
+.Dd August 24, 2023
+.Dt PMAP_KEXTRACT 9
+.Os
+.Sh NAME
+.Nm pmap_kextract ,
+.Nm vtophys
+.Nd extract a physical address from the kernel page table
+.Sh SYNOPSIS
+.In sys/param.h
+.In vm/vm.h
+.In vm/pmap.h
+.Ft vm_paddr_t
+.Fo pmap_kextract
+.Fa "vm_offset_t va"
+.Fc
+.Ft vm_paddr_t
+.Fo vtophys
+.Fa "vm_offset_t va"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn pmap_kextract
+function retrieves the underlying physical memory address corresponding to the given kernel virtual address
+.Fa va .
+The value of
+.Fa va
+must correlate to an active mapping in the kernel address space.
+.Pp
+.Fn vtophys
+is an alias for
+.Fn pmap_kextract
+and behaves identically.
+.Sh RETURN VALUES
+The
+.Fn pmap_kextract
+function will return the physical address
+.Pq Vt vm_paddr_t
+associated with the kernel virtual address
+.Fa va .
+.Pp
+.Fn pmap_kextract
+generally does not fail.
+However, if supplied with an illegitimate value for
+.Fa va ,
+the function may return zero, an invalid non-zero value, or call
+.Xr panic 9 .
+.Sh SEE ALSO
+.Xr pmap 9 ,
+.Xr pmap_extract 9
+.Sh AUTHORS
+.An -nosplit
+This manual page was written by
+.An Mina Galić Aq Mt FreeBSD@igalic.co ,
+based on the
+.Xr pmap_extract 9
+page written by
+.An Bruce M Simpson Aq Mt bms@spc.org .
diff --git a/sys/amd64/amd64/pmap.c b/sys/amd64/amd64/pmap.c
index ff83d8749313..8c438cfb4639 100644
--- a/sys/amd64/amd64/pmap.c
+++ b/sys/amd64/amd64/pmap.c
@@ -3846,7 +3846,7 @@ pmap_flush_cache_phys_range(vm_paddr_t spa, vm_paddr_t epa, vm_memattr_t mattr)
  *		Extract the physical page address associated
  *		with the given map/virtual_address pair.
  */
-vm_paddr_t 
+vm_paddr_t
 pmap_extract(pmap_t pmap, vm_offset_t va)
 {
 	pdp_entry_t *pdpe;
@@ -3933,6 +3933,12 @@ out:
 	return (m);
 }
 
+/*
+ *	Routine:	pmap_kextract
+ *	Function:
+ *		Extract the physical page address associated with the given kernel
+ *		virtual address.
+ */
 vm_paddr_t
 pmap_kextract(vm_offset_t va)
 {
diff --git a/sys/arm64/arm64/pmap.c b/sys/arm64/arm64/pmap.c
index 6f2afa0b98a3..8c2c6f9d7b81 100644
--- a/sys/arm64/arm64/pmap.c
+++ b/sys/arm64/arm64/pmap.c
@@ -1949,6 +1949,12 @@ pmap_klookup(vm_offset_t va, vm_paddr_t *pa)
 	return (true);
 }
 
+/*
+ *	Routine:	pmap_kextract
+ *	Function:
+ *		Extract the physical page address associated with the given kernel
+ *		virtual address.
+ */
 vm_paddr_t
 pmap_kextract(vm_offset_t va)
 {
diff --git a/sys/riscv/riscv/pmap.c b/sys/riscv/riscv/pmap.c
index 49ee54b37918..66054898b281 100644
--- a/sys/riscv/riscv/pmap.c
+++ b/sys/riscv/riscv/pmap.c
@@ -970,6 +970,12 @@ pmap_extract_and_hold(pmap_t pmap, vm_offset_t va, vm_prot_t prot)
 	return (m);
 }
 
+/*
+ *	Routine:	pmap_kextract
+ *	Function:
+ *		Extract the physical page address associated with the given kernel
+ *		virtual address.
+ */
 vm_paddr_t
 pmap_kextract(vm_offset_t va)
 {