From: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
To: "Fabio M. De Francesco" <fmdefrancesco@gmail.com>
Cc: Ira Weiny <ira.weiny@intel.com>,
Andrew Morton <akpm@linux-foundation.org>,
Catalin Marinas <catalin.marinas@arm.com>,
"Matthew Wilcox (Oracle)" <willy@infradead.org>,
Will Deacon <will@kernel.org>,
Peter Collingbourne <pcc@google.com>,
Vlastimil Babka <vbabka@suse.cz>,
linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org,
outreachy@lists.linux.dev, Mike Rapoport <rppt@linux.ibm.com>
Subject: Re: [PATCH v3 1/4] mm/highmem: Fix kernel-doc warnings in highmem*.h
Date: Thu, 28 Apr 2022 13:05:21 +0200 [thread overview]
Message-ID: <Ymp08dSdeDjvwF9b@linutronix.de> (raw)
In-Reply-To: <2598013.X9hSmTKtgW@leap>
On 2022-04-28 12:54:14 [+0200], Fabio M. De Francesco wrote:
> No, it's not sufficient because Matthew Wilcox said that something like "It
> is the counterpart of kmap_atomic() for unmapping" (or anything similar) is
> _not_ what he wants to see.
>
> Furthermore, a large part of this text has been written by him (I'm talking
> of a couple of weeks ago, when this patch was not part of this series - it
> was on its own until Ira Weiny asked me to gather 4 patches in one only
> series).
Sure.
> > This indicates the "migration" is disabled for
> > !PREEMPT_RT which is not the case.
>
> I read again how kmap_atomic() is defined. There are lots of 'if'
> statements. Only if the code gets to __kmap_local_pfn_prot(), users can be
> assured that it unconditionally calls both migrate_disable() and
> preempt_disable().
Right, that part. Then keep it.
> > So maybe something like
> >
> > * Unmaps an address previously mapped by kmap_atomic() and re-enables
> > * pagefaults, CPU migration (CONFIG_PREEMPT_RT) or preemption
> > * (!CONFIG_PREEMPT_RT). Mappings should be unmapped in the reverse
> >
> > will make it clear.
>
> I'm starting to think that this level of detail is too much for users who
> just need to understand how to use this function as well as
> kmap_local_page().
>
> I prefer something like the following:
>
> + * Unmaps an address previously mapped by kmap_atomic() and re-enables
> + * pagefaults and possibly also CPU migration and/or preemption. However,
> + * users should not count on disable of migration and/or preemption as a
> + * side effect of calling kmap_atomic(). Mappings must be unmapped in the
> + * reverse [...]
>
> I'd also like to write the same paragraph for kmap_local_page().
>
> What do you think of being less detailed and instead using the text I wrote
> above?
Sounds perfect.
> Thanks,
>
> Fabio
Sebastian
next prev parent reply other threads:[~2022-04-28 11:05 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-04-27 18:38 [PATCH v3 0/4] Extend and reorganize Highmem's documentation Fabio M. De Francesco
2022-04-27 18:38 ` [PATCH v3 1/4] mm/highmem: Fix kernel-doc warnings in highmem*.h Fabio M. De Francesco
2022-04-28 9:11 ` Sebastian Andrzej Siewior
2022-04-28 10:54 ` Fabio M. De Francesco
2022-04-28 11:05 ` Sebastian Andrzej Siewior [this message]
2022-04-27 18:38 ` [PATCH v3 2/4] Documentation/vm: Include kdocs from highmem*.h into highmem.rst Fabio M. De Francesco
2022-04-27 18:38 ` [PATCH v3 3/4] Documentation/vm: Move "Using kmap-atomic" to highmem.h Fabio M. De Francesco
2022-04-27 18:38 ` [PATCH v3 4/4] Documentation/vm: Rework "Temporary Virtual Mappings" section Fabio M. De Francesco
2022-04-28 9:02 ` Sebastian Andrzej Siewior
2022-04-28 11:14 ` Fabio M. De Francesco
2022-04-28 16:34 ` Sebastian Andrzej Siewior
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=Ymp08dSdeDjvwF9b@linutronix.de \
--to=bigeasy@linutronix.de \
--cc=akpm@linux-foundation.org \
--cc=catalin.marinas@arm.com \
--cc=fmdefrancesco@gmail.com \
--cc=ira.weiny@intel.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=outreachy@lists.linux.dev \
--cc=pcc@google.com \
--cc=rppt@linux.ibm.com \
--cc=vbabka@suse.cz \
--cc=will@kernel.org \
--cc=willy@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).