Harry Yoo <harry.yoo@xxxxxxxxxx> writes: > While move_ptes() has a comment explaining why rmap locks are needed, > Documentation/mm/process_addrs.rst does not. Without being aware of that > comment, I spent hours figuring out how things could go wrong and why, > in some cases, rmap locks can be safely skipped. > > Add a more comprehensive explanation to the documentation to save time > for others. > > Signed-off-by: Harry Yoo <harry.yoo@xxxxxxxxxx> > --- > Documentation/mm/process_addrs.rst | 32 ++++++++++++++++++++++++++++++ > 1 file changed, 32 insertions(+) > > diff --git a/Documentation/mm/process_addrs.rst b/Documentation/mm/process_addrs.rst > index be49e2a269e4..ee7c0dba339e 100644 > --- a/Documentation/mm/process_addrs.rst > +++ b/Documentation/mm/process_addrs.rst > @@ -744,6 +744,38 @@ You can observe this in the :c:func:`!mremap` implementation in the functions > :c:func:`!take_rmap_locks` and :c:func:`!drop_rmap_locks` which perform the rmap > side of lock acquisition, invoked ultimately by :c:func:`!move_page_tables`. > > +.. note:: If :c:func:`!mremap()` -> :c:func:`!move_ptes()` does not take rmap > + locks, :c:func:`!rmap_walk()` may miss a pte for the folio. > + > + The problematic sequence is as follows: Please don't use :c:func: - just write function() and all the right things will happen. (For extra credit, fix the existing usages :) Thanks, jon
