Re: git: 74e4a8d208f0 - main - pmap: add pmap_kextract(9) man page
Date: Sat, 14 Oct 2023 13:28:14 UTC
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ć <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
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'?
> +.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.
> +.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)
> {