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;
From:   <alexlzhu@fb.com>
To:     <linux-doc@vger.kernel.org>, <linux-kernel@vger.kernel.org>,
        <Kernel-team@fb.com>
CC:     Alexander Zhu <alexlzhu@fb.com>
Subject: [PATCH v2] docs/mm: Improve grammar on mmu_notifier documentation.
Date:   Fri, 16 Sep 2022 08:35:16 -0700
Message-ID: <20220916153516.3253582-1-alexlzhu@fb.com>
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain
Precedence: bulk

From: Alexander Zhu <alexlzhu@fb.com>

Improve grammar on mmu_notifier documentation.

Signed-off-by: Alexander Zhu <alexlzhu@fb.com>
---
Changes in v2:
    -add blank line back in to avoid kernel test robot complaining

 Documentation/mm/mmu_notifier.rst | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/Documentation/mm/mmu_notifier.rst b/Documentation/mm/mmu_not=
ifier.rst
index df5d7777fc6b..751b6eaf456e 100644
--- a/Documentation/mm/mmu_notifier.rst
+++ b/Documentation/mm/mmu_notifier.rst
@@ -7,10 +7,11 @@ When clearing a pte/pmd we are given a choice to notify=
 the event through
 (notify version of \*_clear_flush call mmu_notifier_invalidate_range) un=
der
 the page table lock. But that notification is not necessary in all cases=
.
=20
-For secondary TLB (non CPU TLB) like IOMMU TLB or device TLB (when devic=
e use
-thing like ATS/PASID to get the IOMMU to walk the CPU page table to acce=
ss a
-process virtual address space). There is only 2 cases when you need to n=
otify
-those secondary TLB while holding page table lock when clearing a pte/pm=
d:
+For secondary TLB (non CPU TLB) like IOMMU TLB or device TLB (when the d=
evice
+uses something like ATS/PASID to get the IOMMU to walk the CPU page tabl=
e to
+access a process virtual address space). There are only 2 cases when you=
 need
+to notify the secondary TLB while holding the page table lock when clear=
ing
+a pte/pmd:
=20
   A) page backing address is free before mmu_notifier_invalidate_range_e=
nd()
   B) a page table entry is updated to point to a new page (COW, write fa=
ult
@@ -27,13 +28,13 @@ happen:
   - set page table entry to point to new page
=20
 If clearing the page table entry is not followed by a notify before sett=
ing
-the new pte/pmd value then you can break memory model like C11 or C++11 =
for
-the device.
+the new pte/pmd value then you can break the memory model like C11 or C+=
+11
+for the device.
=20
 Consider the following scenario (device use a feature similar to ATS/PAS=
ID):
=20
-Two address addrA and addrB such that \|addrA - addrB\| >=3D PAGE_SIZE w=
e assume
-they are write protected for COW (other case of B apply too).
+Two addresses addrA and addrB such that \|addrA - addrB\| >=3D PAGE_SIZE=
 we assume
+they are write protected for COW (other case of B applies as well).
=20
 ::
=20
@@ -87,13 +88,13 @@ they are write protected for COW (other case of B app=
ly too).
  DEV-thread-0  {read addrA from old page}
  DEV-thread-2  {read addrB from new page}
=20
-So here because at time N+2 the clear page table entry was not pair with=
 a
-notification to invalidate the secondary TLB, the device see the new val=
ue for
-addrB before seeing the new value for addrA. This break total memory ord=
ering
+Here because at time N+2 the clear page table entry was not paired with =
a
+notification to invalidate the secondary TLB, the device sees the new va=
lue for
+addrB before seeing the new value for addrA. This breaks total memory or=
dering
 for the device.
=20
 When changing a pte to write protect or to point to a new write protecte=
d page
 with same content (KSM) it is fine to delay the mmu_notifier_invalidate_=
range
 call to mmu_notifier_invalidate_range_end() outside the page table lock.=
 This
 is true even if the thread doing the page table update is preempted righ=
t after
-releasing page table lock but before call mmu_notifier_invalidate_range_=
end().
+releasing the page table lock but before calling mmu_notifier_invalidate=
_range_end().
--=20
2.30.2