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

From: Konstantin Belousov <kostikbel_at_gmail.com>
Date: Tue, 17 Oct 2023 09:05:15 UTC 
On Mon, Oct 16, 2023 at 03:54:32PM -0700, John Baldwin wrote:
> On 10/14/23 10:34 AM, Mitchell Horne wrote:
> > On 10/14/23 10:28, Konstantin Belousov wrote:
> > > On Fri, Oct 13, 2023 at 06:27:33PM +0000, Mitchell Horne wrote:
> > > > +.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.
> 
> I suggest tweaking this further just to be very explicit about the type
> of address being returned:
> 
> The
> .Fn pmap_kextract
> function returns the physical address of memory mapped at the
> kernel virtual address
> .Va va .
> 
> or some such.

There are two larger things that are worth adding to the man page, IMO.

1. pmap_kextract() is safe to be used from any context (in particular, it
   does not do any locking internally)

2. it is caller duty to ensure that the active mapping is alive and stable
   long enough for the answer to be useful