linux-next: manual merge of the jc_docs tree with the mm-unstable tree

[Mark Brown <broonie@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 6834 bytes --]

Hi all,

Today's linux-next merge of the jc_docs tree got a conflict in:

  Documentation/mm/hmm.rst

between commit:

  d68817e9c3198 ("mm/hmm: add hmm_range_fault_unlocked_timeout() for mmap lock-drop support")

from the mm-unstable tree and commit:

  e834ee8e571d5 ("docs/mm: Fix braces")

from the jc_docs tree.

I fixed it up (see below) and can carry the fix as necessary. This
is now fixed as far as linux-next is concerned, but any non trivial
conflicts should be mentioned to your upstream maintainer when your tree
is submitted for merging.  You may also want to consider cooperating
with the maintainer of the conflicting tree to minimise any particularly
complex conflicts.

diff --combined Documentation/mm/hmm.rst
index 4e5a750748ae5,54c461e7a143f..0000000000000
--- a/Documentation/mm/hmm.rst
+++ b/Documentation/mm/hmm.rst
@@@ -156,57 -156,42 +156,57 @@@ During the ops->invalidate() callback t
  update action to the range (mark range read only, or fully unmap, etc.). The
  device must complete the update before the driver callback returns.
  
 -When the device driver wants to populate a range of virtual addresses, it can
 -use::
 +When the device driver wants to populate a range of virtual addresses, the
 +normal interface is::
  
 -  int hmm_range_fault(struct hmm_range *range);
 +  int hmm_range_fault_unlocked_timeout(struct hmm_range *range,
 +                                       unsigned long timeout);
  
  It will trigger a page fault on missing or read-only entries if write access is
  requested (see below). Page faults use the generic mm page fault code path just
 -like a CPU page fault. The usage pattern is::
 +like a CPU page fault.
 +
 +The caller must not hold ``mmap_read_lock`` before the call.
 +``hmm_range_fault_unlocked_timeout()`` takes the mmap read lock internally and
 +allows ``handle_mm_fault()`` to drop it during fault handling. This is required
 +for VMAs whose fault handlers may release the mmap lock, for example regions
 +managed by ``userfaultfd``.
 +
 +If the mmap lock is dropped or the range is invalidated, the function refreshes
 +``range->notifier_seq`` and restarts the walk internally. ``-EINTR`` is returned
 +if mmap lock acquisition is interrupted or a fatal signal is pending during
 +retry handling.
 +
 +The timeout is specified in jiffies; passing ``0`` means retry indefinitely. The
 +timeout exists to preserve caller policy for repeated mmu-notifier invalidation
 +and is checked between retry attempts. HMM does not interrupt page fault
 +handling when the timeout expires, but returns ``-EBUSY`` if the retry budget is
 +exhausted before a stable range is obtained.
 +
 +The usage pattern is::
  
   int driver_populate_range(...)
   {
        struct hmm_range range;
 +      unsigned long timeout;
        ...
  
 +      timeout = msecs_to_jiffies(HMM_RANGE_DEFAULT_TIMEOUT);
        range.notifier = &interval_sub;
        range.start = ...;
        range.end = ...;
        range.hmm_pfns = ...;
  
 -      if (!mmget_not_zero(interval_sub->notifier.mm))
 +      if (!mmget_not_zero(interval_sub.mm))
            return -EFAULT;
  
   again:
 -      range.notifier_seq = mmu_interval_read_begin(&interval_sub);
 -      mmap_read_lock(mm);
 -      ret = hmm_range_fault(&range);
 -      if (ret) {
 -          mmap_read_unlock(mm);
 -          if (ret == -EBUSY)
 -                 goto again;
 -          return ret;
 -      }
 -      mmap_read_unlock(mm);
 +      ret = hmm_range_fault_unlocked_timeout(&range, timeout);
 +      if (ret)
 +          goto out_put;
  
        take_lock(driver->update);
 -      if (mmu_interval_read_retry(&ni, range.notifier_seq)) {
 +      if (mmu_interval_read_retry(&interval_sub, range.notifier_seq)) {
            release_lock(driver->update);
            goto again;
        }
@@@ -215,11 -200,7 +215,11 @@@
         * under the update lock */
  
        release_lock(driver->update);
 -      return 0;
 +      ret = 0;
 +
 + out_put:
 +      mmput(interval_sub.mm);
 +      return ret;
   }
  
  The driver->update lock is the same lock that the driver takes inside its
@@@ -227,19 -208,6 +227,19 @@@ invalidate() callback. That lock must b
  mmu_interval_read_retry() to avoid any race with a concurrent CPU page table
  update.
  
 +Holding the mmap lock across HMM faults
 +=======================================
 +
 +Most callers should use ``hmm_range_fault_unlocked_timeout()``. If a driver
 +really needs to hold the mmap lock across work outside HMM, it can use::
 +
 +  int hmm_range_fault(struct hmm_range *range);
 +
 +The mmap lock must be held by the caller and will remain held on return. This
 +interface cannot support VMAs whose fault handlers need to drop the mmap lock.
 +New callers should prefer ``hmm_range_fault_unlocked_timeout()`` unless they
 +have a specific requirement to keep the mmap lock held across the call.
 +
  Leverage default_flags and pfn_flags_mask
  =========================================
  
@@@ -253,8 -221,8 +253,8 @@@ permission, it sets:
      range->default_flags = HMM_PFN_REQ_FAULT;
      range->pfn_flags_mask = 0;
  
 -and calls hmm_range_fault() as described above. This will fill fault all pages
 -in the range with at least read permission.
 +and calls the HMM range fault helper as described above. This will fault
 +all pages in the range with at least read permission.
  
  Now let's say the driver wants to do the same except for one page in the range for
  which it wants to have write permission. Now driver set::
@@@ -268,9 -236,9 +268,9 @@@ address == range->start + (index_of_wri
  write permission i.e., if the CPU pte does not have write permission set then HMM
  will call handle_mm_fault().
  
 -After hmm_range_fault completes the flag bits are set to the current state of
 -the page tables, ie HMM_PFN_VALID | HMM_PFN_WRITE will be set if the page is
 -writable.
 +After the HMM range fault helper completes the flag bits are set to the
 +current state of the page tables, ie HMM_PFN_VALID | HMM_PFN_WRITE will be
 +set if the page is writable.
  
  
  Represent and manage device memory from core kernel point of view
@@@ -348,7 -316,7 +348,7 @@@ between device driver specific code an
     system memory and device private memory.
  
     One of the first steps migrate_vma_setup() does is to invalidate other
-    device's MMUs with the ``mmu_notifier_invalidate_range_start(()`` and
+    device's MMUs with the ``mmu_notifier_invalidate_range_start()`` and
     ``mmu_notifier_invalidate_range_end()`` calls around the page table
     walks to fill in the ``args->src`` array with PFNs to be migrated.
     The ``invalidate_range_start()`` callback is passed a

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]