| Message ID | 20241206225204.4008261-7-surenb@google.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | move per-vma lock into vm_area_struct | expand |
Hi, Can someone explain what the (consistent) usage of '!' does in this file? This is the only file in Documentation/ that uses this syntax. E.g.: > diff --git a/Documentation/mm/process_addrs.rst b/Documentation/mm/process_addrs.rst > index 81417fa2ed20..92cf497a9e3c 100644 > --- a/Documentation/mm/process_addrs.rst > +++ b/Documentation/mm/process_addrs.rst > @@ -716,7 +716,11 @@ calls :c:func:`!rcu_read_lock` to ensure that the VMA is looked up in an RCU > critical section, then attempts to VMA lock it via :c:func:`!vma_start_read`, > before releasing the RCU lock via :c:func:`!rcu_read_unlock`. > > -VMA read locks hold the read lock on the :c:member:`!vma->vm_lock` semaphore for > +In cases when the user already holds mmap read lock, :c:func:`!vma_start_read_locked` > +and :c:func:`!vma_start_read_locked_nested` can be used. These functions always > +succeed in acquiring VMA read lock. thanks.
On Fri, 6 Dec 2024 19:23:59 -0800, Randy Dunlap wrote: > Hi, > > Can someone explain what the (consistent) usage of '!' does in this file? > This is the only file in Documentation/ that uses this syntax. > > > E.g.: > >> diff --git a/Documentation/mm/process_addrs.rst b/Documentation/mm/process_addrs.rst >> index 81417fa2ed20..92cf497a9e3c 100644 >> --- a/Documentation/mm/process_addrs.rst >> +++ b/Documentation/mm/process_addrs.rst >> @@ -716,7 +716,11 @@ calls :c:func:`!rcu_read_lock` to ensure that the VMA is looked up in an RCU >> critical section, then attempts to VMA lock it via :c:func:`!vma_start_read`, >> before releasing the RCU lock via :c:func:`!rcu_read_unlock`. >> >> -VMA read locks hold the read lock on the :c:member:`!vma->vm_lock` semaphore for >> +In cases when the user already holds mmap read lock, :c:func:`!vma_start_read_locked` >> +and :c:func:`!vma_start_read_locked_nested` can be used. These functions always >> +succeed in acquiring VMA read lock. > Quoting from https://www.sphinx-doc.org/en/master/usage/referencing.html#syntax * Suppressed link: Prefixing with an exclamation mark (!) prevents the creation of a link but otherwise keeps the visual output of the role. For example, writing :py:func:`!target` displays target(), with no link generated. This is helpful for cases in which the link target does not exist; e.g. changelog entries that describe removed functionality, or third-party libraries that don’t support intersphinx. Suppressing the link prevents warnings in nitpicky mode. But in kernel documentation, there is a preferred alternative. Referencing by function names is the way to go. For example: calls rcu_read_lock() to ensure that the VMA is looked up in an RCU critical section, then attempts to VMA lock it via vma_start_read(), before releasing the RCU lock via rcu_read_unlock(). In cases when the user already holds mmap read lock, vma_start_read_locked() and vma_start_read_locked_nested() can be used. These functions always succeed in acquiring VMA read lock. They work regardless of link target's existence. Kernel-specific Sphinx extension named "automarkup" does conversions for you. HTH, Akira > thanks. > -- > ~Randy
On Fri, Dec 6, 2024 at 8:24 PM Akira Yokosawa <akiyks@gmail.com> wrote: > > On Fri, 6 Dec 2024 19:23:59 -0800, Randy Dunlap wrote: > > Hi, > > > > Can someone explain what the (consistent) usage of '!' does in this file? > > This is the only file in Documentation/ that uses this syntax. > > > > > > E.g.: > > > >> diff --git a/Documentation/mm/process_addrs.rst b/Documentation/mm/process_addrs.rst > >> index 81417fa2ed20..92cf497a9e3c 100644 > >> --- a/Documentation/mm/process_addrs.rst > >> +++ b/Documentation/mm/process_addrs.rst > >> @@ -716,7 +716,11 @@ calls :c:func:`!rcu_read_lock` to ensure that the VMA is looked up in an RCU > >> critical section, then attempts to VMA lock it via :c:func:`!vma_start_read`, > >> before releasing the RCU lock via :c:func:`!rcu_read_unlock`. > >> > >> -VMA read locks hold the read lock on the :c:member:`!vma->vm_lock` semaphore for > >> +In cases when the user already holds mmap read lock, :c:func:`!vma_start_read_locked` > >> +and :c:func:`!vma_start_read_locked_nested` can be used. These functions always > >> +succeed in acquiring VMA read lock. > > > > Quoting from https://www.sphinx-doc.org/en/master/usage/referencing.html#syntax > > * Suppressed link: Prefixing with an exclamation mark (!) prevents the > creation of a link but otherwise keeps the visual output of the role. > > For example, writing :py:func:`!target` displays target(), with no link > generated. > > This is helpful for cases in which the link target does not exist; e.g. > changelog entries that describe removed functionality, or third-party > libraries that don’t support intersphinx. Suppressing the link prevents > warnings in nitpicky mode. > > But in kernel documentation, there is a preferred alternative. > Referencing by function names is the way to go. For example: > > calls rcu_read_lock() to ensure that the VMA is looked up in an RCU > critical section, then attempts to VMA lock it via vma_start_read(), > before releasing the RCU lock via rcu_read_unlock(). > > In cases when the user already holds mmap read lock, vma_start_read_locked() > and vma_start_read_locked_nested() can be used. These functions always > succeed in acquiring VMA read lock. > > They work regardless of link target's existence. > Kernel-specific Sphinx extension named "automarkup" does conversions > for you. Thanks for the information. I was simply following the same style the document was written in. Sounds like converting it to the preferred alternative in a separate patch would be best. Lorenzo, WDYT? > > HTH, Akira > > > thanks. > > -- > > ~Randy >
diff --git a/Documentation/mm/process_addrs.rst b/Documentation/mm/process_addrs.rst index 81417fa2ed20..92cf497a9e3c 100644 --- a/Documentation/mm/process_addrs.rst +++ b/Documentation/mm/process_addrs.rst @@ -716,7 +716,11 @@ calls :c:func:`!rcu_read_lock` to ensure that the VMA is looked up in an RCU critical section, then attempts to VMA lock it via :c:func:`!vma_start_read`, before releasing the RCU lock via :c:func:`!rcu_read_unlock`. -VMA read locks hold the read lock on the :c:member:`!vma->vm_lock` semaphore for +In cases when the user already holds mmap read lock, :c:func:`!vma_start_read_locked` +and :c:func:`!vma_start_read_locked_nested` can be used. These functions always +succeed in acquiring VMA read lock. + +VMA read locks hold the read lock on the :c:member:`!vma.vm_lock` semaphore for their duration and the caller of :c:func:`!lock_vma_under_rcu` must release it via :c:func:`!vma_end_read`. @@ -780,7 +784,7 @@ keep VMAs locked across entirely separate write operations. It also maintains correct lock ordering. Each time a VMA read lock is acquired, we acquire a read lock on the -:c:member:`!vma->vm_lock` read/write semaphore and hold it, while checking that +:c:member:`!vma.vm_lock` read/write semaphore and hold it, while checking that the sequence count of the VMA does not match that of the mm. If it does, the read lock fails. If it does not, we hold the lock, excluding @@ -790,7 +794,7 @@ Importantly, maple tree operations performed in :c:func:`!lock_vma_under_rcu` are also RCU safe, so the whole read lock operation is guaranteed to function correctly. -On the write side, we acquire a write lock on the :c:member:`!vma->vm_lock` +On the write side, we acquire a write lock on the :c:member:`!vma.vm_lock` read/write semaphore, before setting the VMA's sequence number under this lock, also simultaneously holding the mmap write lock.
Change the documentation to reflect that vm_lock is integrated into vma. Document newly introduced vma_start_read_locked{_nested} functions. Signed-off-by: Suren Baghdasaryan <surenb@google.com> Reviewed-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com> --- Documentation/mm/process_addrs.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-)