From nobody Sat Oct 14 17:34:58 2023 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4S79Vr6TMlz4x2k9; Sat, 14 Oct 2023 17:35:00 +0000 (UTC) (envelope-from mhorne@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [IPv6:2610:1c1:1:606c::24b:4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "smtp.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4S79Vr5xhMz4RLv; Sat, 14 Oct 2023 17:35:00 +0000 (UTC) (envelope-from mhorne@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1697304900; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:autocrypt:autocrypt; bh=CNrJ13W5IcxumK2bBB6D8iNg8XCISW/lICLJf+8o0C4=; b=vcYYWxHikIdmJitGTVB8VUQmixkJt5954e2vZFe50BzfGqXi6wM8FWxzKf/KUu3ewOom0N vPKLuKNFDw99EZD3qMVXwkKoxibkDh5gZi6bf6py0fRFGUSaxnnQgg3uZcjbtkKjUuY4Fb DI/cLr5DiMiNZ/Z7owKkDC6etoxcSBDZJqmfurGslosCIoIUAWrkU0mDkabfzNTk/HD2Lg vcIL8XT7TOH0BZrUOXLDbygDIuLUABKiYYQKecGzjVbyVOVC3RZlrUE38LV1+wIAYtqm58 hguktcjyGHGlUPANev+dYyHZe6NWkoHdfr2tw1KYbOP5m+lyzs/mrI2KKUdh1g== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1697304900; a=rsa-sha256; cv=none; b=RVmJLEGWqvZzTq5wJgeqse927HBclP44ass3lCy+uEIk89ytYpFEfjR6P725KLxOHpHIVf A/Mp7253X1kHB2wIVsXnJNdTEY9aMNBrOWJ7ByZg7xyrSf3L40/JXG1zhrJx6gPr3oxX+V n61eRkJSJNxYRJsCNZcfXR+KGw7WTdoKrZWtVhAR9UsNsXBrSe9XKuSYeRFTsqD2/hCWnR g+v9MJi55hfCAY1KtixuMa7ofcguAr9u2HauaLvLkytmhOZaZA8cxqLYoE3LhyovKtes0Q k9MSvR7znFc+SE9r/ySgUgK6By0pvEGxyGS0d9Q+KbzpTYs+Y0tfaltc7+IEjQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1697304900; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:autocrypt:autocrypt; bh=CNrJ13W5IcxumK2bBB6D8iNg8XCISW/lICLJf+8o0C4=; b=p0hUjsR+rXsW2b/IQzE8LMbz+65pzFFr8wXTIH7XafiW+ZfsZPaSlFap1WTxaoStdnS7u/ m1S/99MgZh37Xj8oIejR2bnJGYEEgHhkAVt8Febaub/qUG5oCMUiZ5CgjD8UFOqGX+v06n tVvKB26Fk1M/0FtYJf4PfLfG0X30DQ8U2zfdIH80nwoXF2bARkPVRuC/V7wtKdysWtc/TQ QE5VsVa02ucINt/lrjkrbO6hnOv+iJmoPKDX8Puk2ndLTc04pao316c4QaLRBbykx+PitU vgjhs3466F/rjhK0Z0hjHwXkXo+uq+ilpSxq0zOZJ0fjlX8dYf7yZ2CkQWdeAQ== Received: from [192.168.1.151] (host-173-212-76-127.public.eastlink.ca [173.212.76.127]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) (Authenticated sender: mhorne) by smtp.freebsd.org (Postfix) with ESMTPSA id 4S79Vr30bRzqPm; Sat, 14 Oct 2023 17:35:00 +0000 (UTC) (envelope-from mhorne@freebsd.org) Message-ID: <068574a3-f63a-4830-be1d-2a8cd67c1819@freebsd.org> Date: Sat, 14 Oct 2023 14:34:58 -0300 List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@freebsd.org MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: git: 74e4a8d208f0 - main - pmap: add pmap_kextract(9) man page Content-Language: en-CA To: Konstantin Belousov Cc: src-committers@freebsd.org, dev-commits-src-all@freebsd.org, dev-commits-src-main@freebsd.org References: <202310131827.39DIRXsu082741@gitrepo.freebsd.org> From: Mitchell Horne Autocrypt: addr=mhorne@freebsd.org; keydata= xsBNBFyS2dQBCADdiXBG8hBVLmYbxu7aSzbwLwUf3HkGFz3rooS1kwyy+SfmjZ4UKNnl9WMx WKrJ7OAZpiNH6bLQ5nsqfx09OnpWL8c/QuPbhNdUywQoqqYpRI0K8GEn//nS9Gs0KTYwVpWb XlrzP+jf3Uh/9L5mcQmStLIH4zaaqMYHW+pMuPrvBmLIHTvLj2QjOkxslrcUdord9uvxe5Ht LU8RuTpQpHOKz705Z9/v7twFdi2HtKzpLwO6SzVyu351di1J+GihsVpcT5josQV5cHbIP3Un x+kmtKBEEc/jl/zBglF7ruWUtwgbryID+2ZPEaO1Mj+RResX4LFVMusq3uUpWRb5WJXxABEB AAHNI01pdGNoZWxsIEhvcm5lIDxtaG9ybmVARnJlZUJTRC5vcmc+wsCUBBMBCgA+AhsDBQsJ CAcCBhUKCQgLAgQWAgMBAh4BAheAFiEEkp/cYPcfabAiQvACi/gnTOdUid8FAmIyDpUFCQtC z0EACgkQi/gnTOdUid8IsQf+N8IptrrCgifT5Z0/WUVFfnHThFOKf4zBjaGswsIM8+VKsKnF 15jCWHODUHP6s+dcQ4nQi81PHPsnMfBSkGPvN/X3ess2/1KUVkH+6tAJbqXDjXhD8HT+i0NM QEFIXlLnotpgIKW3yOHjKv3ZvKw9LCvUjyNY9vOJmLk/6AbbkFh+INo65nXtQWb/hM5FVEHW S+zUoU8AqZRJoVAQfj9wmIfg/HdsxeDGKL0zkv5AwKpccvb8VJNGJbCVMgoy5uQYcUeXxcie cg0VlbFLshNQTfyhVQ85vyuHahARrUWs/k8KiYODoBnW1ChtyF8yM6VZTzSYx7pINqPq2YZy i/Htd87ATQRcktnUAQgA3zt4M4ecoQqfxpjliNLujt9klDqvmkJvWmzMuMXdzlPgGRJ0doio 9YIeEdkOt6xN0pPTK/ReCZ8WqFQ8zo23u1pwGuo0CnR58XF19wyxyUuKu/PHbt+56mC8tNHm AXsMyXQmlDqWvn/WzLY7euNRtNS4QQIwtxfM5EC4GGa5KQwxn0kM7dkUSOE/cxr+/kNbHHzb gagZR4cnNUqtPPr3dYXcibCTzgz96Lyt3/qMLXX9RTBRzu+O6E+byxWOe8ar/ZlwY2b4wTQG mhgNttkSxKtxMpZnd8+DGV/bI1P5Ct/K2GeCwNyupQGON5ymn6o7jTch+qmFX0ItkBWO4zn4 9QARAQABwsB8BBgBCgAmAhsMFiEEkp/cYPcfabAiQvACi/gnTOdUid8FAmIyDtwFCQtCz4gA CgkQi/gnTOdUid/i5gf/aQ75pJR4TJFM2vVVr6PDIwTdl0b5EchB4w4s4g/zE84XNbMOQanb BginLYEhAacLQVAvM3XdvUEhwrhaMQdjdSEB1krResL3/mbxrtKwdHSMbHA3IS3XdvxFWTB7 P5JjUSPsW6hqgoidbn4w3OxaNHhs45H2b0Nx5QiKcSyepmCZuB52gCEHnEnrdaz8TFQMXOLq 94WbTmZeIjChW3FB61m1gTf0UEFjoZAfTAUB+pbwoCa4AykIeZnDC19vjsruVU9Gy5rLglwd bjsZNfXIJGOZNEvdF8FOBwM7DlXx7SYvTJcUNoNJjOKtQ0bYGVgGqYOB/y2mTjVuKeU0eOkN Uw== In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit 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ć >> AuthorDate: 2023-08-23 00:12:49 +0000 >> Commit: Mitchell Horne >> 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 >> 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ć 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) >> {