On 10/14/23 10:28, Konstantin Belousov wrote:
On Fri, Oct 13, 2023 at 06:27:33PM +0000, Mitchell Horne wrote:
The branch main has been updated by mhorne:
URL:
https://cgit.FreeBSD.org/src/commit/?id=74e4a8d208f0b3cf2525e3786f3efba71fcdb752
commit 74e4a8d208f0b3cf2525e3786f3efba71fcdb752
Author: Mina Galić <free...@igalic.co>
AuthorDate: 2023-08-23 00:12:49 +0000
Commit: Mitchell Horne <mho...@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 <grahamper...@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ć <free...@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
Line too long.
+.Fa va .
+The value of
+.Fa va
+must correlate to an active mapping in the kernel address space.
What does it mean 'correlate'?
'correlate' means that the relationship exists in both directions. We
could describe an address as "belonging to" a VA->PA mapping, or we
could say that an address "posseses" such a mapping. Maybe you have a
strong opinion on why one is incorrect.
Since 'correlate' is not established terminology, and needlessly
confusing, I can simplify it to:
"The value of va must belong to an active mapping in..."
If you have a different suggestion, let me know.
+.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
and 'associated'?
The function returns address of physical memory mapped at the supplied
kernel virtual address.
Sure, this is more accurate.
+.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 free...@igalic.co ,
+based on the
+.Xr pmap_extract 9
+page written by
+.An Bruce M Simpson Aq Mt b...@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)
{
