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

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)
>>   {