Date: Sat, 14 Oct 2023 14:34:58 -0300 From: Mitchell Horne <mhorne@freebsd.org> To: Konstantin Belousov <kostikbel@gmail.com> Cc: src-committers@freebsd.org, dev-commits-src-all@freebsd.org, dev-commits-src-main@freebsd.org Subject: Re: git: 74e4a8d208f0 - main - pmap: add pmap_kextract(9) man page Message-ID: <068574a3-f63a-4830-be1d-2a8cd67c1819@freebsd.org> In-Reply-To: <ZSqXbrd9dn9h5-We@kib.kiev.ua> References: <202310131827.39DIRXsu082741@gitrepo.freebsd.org> <ZSqXbrd9dn9h5-We@kib.kiev.ua>
next in thread | previous in thread | raw e-mail | index | archive | help
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ć <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'? > '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 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) >> {
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?068574a3-f63a-4830-be1d-2a8cd67c1819>