Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Thu, 8 Dec 2022 11:22:37 +0700
From:   Bagas Sanjaya <bagasdotme@gmail.com>
To:     "Fabio M. De Francesco" <fmdefrancesco@gmail.com>,
        Jonathan Corbet <corbet@lwn.net>,
        Andrew Morton <akpm@linux-foundation.org>,
        Sebastian Andrzej Siewior <bigeasy@linutronix.de>,
        Ira Weiny <ira.weiny@intel.com>,
        Mike Rapoport <rppt@kernel.org>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org, linux-mm@kvack.org
Cc:     Mike Rapoport <rppt@linux.ibm.com>,
        Peter Zijlstra <a.p.zijlstra@chello.nl>,
        Thomas Gleixner <tglx@linutronix.de>
Subject: Re: [PATCH v2] mm/highmem: Add notes about conversions from
 kmap{,_atomic}()
Message-ID: <Y5FmjdBNEO8aP/Ls@debian.me>
References: <20221207225308.8290-1-fmdefrancesco@gmail.com>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha256;
        protocol="application/pgp-signature"; boundary="DpcXuOK9+sW5uRJK"
Content-Disposition: inline
In-Reply-To: <20221207225308.8290-1-fmdefrancesco@gmail.com>
Precedence: bulk


--DpcXuOK9+sW5uRJK
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Wed, Dec 07, 2022 at 11:53:08PM +0100, Fabio M. De Francesco wrote:
> diff --git a/Documentation/mm/highmem.rst b/Documentation/mm/highmem.rst
> index 0f731d9196b0..59d1078f53df 100644
> --- a/Documentation/mm/highmem.rst
> +++ b/Documentation/mm/highmem.rst
> @@ -57,7 +57,8 @@ list shows them in order of preference of use.
>    It can be invoked from any context (including interrupts) but the mapp=
ings
>    can only be used in the context which acquired them.
> =20
> -  This function should be preferred, where feasible, over all the others.
> +  This function should always be used. kmap_atomic() and kmap() have been
> +  deprecated.

"... always be used, whereas ..."

> +  NOTE: Conversions to kmap_local_page() must take care to follow the ma=
pping
> +  restrictions imposed on kmap_local_page(). Furthermore, the code betwe=
en
> +  calls to kmap_atomic() and kunmap_atomic() may implicitly depend on th=
e side
> +  effects of atomic mappings, i.e. disabling page faults or preemption, =
or both.
> +  In that case, explicit calls to pagefault_disable() or preempt_disable=
() or
> +  both must be made in conjunction with the use of kmap_local_page().
> +
> <snipped>...
> +  NOTE: Conversions to kmap_local_page() must take care to follow the ma=
pping
> +  restrictions imposed on kmap_local_page(). In particular, it is necess=
ary to
> +  make sure that the kernel virtual memory pointer is only valid in the =
thread
> +  that obtained it.
> +

What about using note block to signify conversion notes above?

---- >8 ----

diff --git a/Documentation/mm/highmem.rst b/Documentation/mm/highmem.rst
index 59d1078f53df57..ef53eb580d4cda 100644
--- a/Documentation/mm/highmem.rst
+++ b/Documentation/mm/highmem.rst
@@ -103,12 +103,14 @@ list shows them in order of preference of use.
=20
 * kmap_atomic(). This function has been deprecated; use kmap_local_page().
=20
-  NOTE: Conversions to kmap_local_page() must take care to follow the mapp=
ing
-  restrictions imposed on kmap_local_page(). Furthermore, the code between
-  calls to kmap_atomic() and kunmap_atomic() may implicitly depend on the =
side
-  effects of atomic mappings, i.e. disabling page faults or preemption, or=
 both.
-  In that case, explicit calls to pagefault_disable() or preempt_disable()=
 or
-  both must be made in conjunction with the use of kmap_local_page().
+  .. note::
+     Conversions to kmap_local_page() must take care to follow the mapping
+     restrictions imposed on kmap_local_page(). Furthermore, the code betw=
een
+     calls to kmap_atomic() and kunmap_atomic() may implicitly depend on t=
he
+     side effects of atomic mappings, i.e. disabling page faults or preemp=
tion,
+     or both. In that case, explicit calls to pagefault_disable() or
+     preempt_disable() or both must be made in conjunction with the use of
+     kmap_local_page().
=20
   [Legacy documentation]
=20
@@ -129,10 +131,11 @@ list shows them in order of preference of use.
=20
 * kmap(). This function has been deprecated; use kmap_local_page().
=20
-  NOTE: Conversions to kmap_local_page() must take care to follow the mapp=
ing
-  restrictions imposed on kmap_local_page(). In particular, it is necessar=
y to
-  make sure that the kernel virtual memory pointer is only valid in the th=
read
-  that obtained it.
+  .. note::
+     Conversions to kmap_local_page() must take care to follow the mapping
+     restrictions imposed on kmap_local_page(). In particular, it is neces=
sary
+     to make sure that the kernel virtual memory pointer is only valid in =
the
+     thread that obtained it.
=20
   [Legacy documentation]
=20
Thanks.

--=20
An old man doll... just what I always wanted! - Clara

--DpcXuOK9+sW5uRJK
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iHUEABYIAB0WIQSSYQ6Cy7oyFNCHrUH2uYlJVVFOowUCY5FmhwAKCRD2uYlJVVFO
oyEbAP9nGOIqvunMYBWjKm0wiAVXP9PBwvmq0npDOR8jefqVdAD/VqnrYrP3xgh1
H+9kkiaHpEnQRTgJV4K0W0aMRra/SAI=
=T+NX
-----END PGP SIGNATURE-----

--DpcXuOK9+sW5uRJK--