On Tue, May 18, 2021 at 12:06:42PM +0200, Vlastimil Babka wrote: > > /** > > - * unlock_page - unlock a locked page > > - * @page: the page > > + * folio_unlock - Unlock a locked folio. > > + * @folio: The folio. > > * > > - * Unlocks the page and wakes up sleepers in wait_on_page_locked(). > > - * Also wakes sleepers in wait_on_page_writeback() because the wakeup > > - * mechanism between PageLocked pages and PageWriteback pages is shared. > > - * But that's OK - sleepers in wait_on_page_writeback() just go back to sleep. > > + * Unlocks the folio and wakes up any thread sleeping on the page lock. > > * > > - * Note that this depends on PG_waiters being the sign bit in the byte > > - * that contains PG_locked - thus the BUILD_BUG_ON(). That allows us to > > - * clear the PG_locked bit and test PG_waiters at the same time fairly > > - * portably (architectures that do LL/SC can test any bit, while x86 can > > - * test the sign bit). > > Was it necessary to remove the comments about wait_on_page_writeback() and > PG_waiters etc? I think so. This kernel-doc is for the person who wants to understand how to use the function, not for the person who wants to understand why the function is written the way it is. For that person, we have git log messages and other comments dotted throughout, eg the comment on clear_bit_unlock_is_negative_byte() in mm/filemap.c and the comment on PG_waiters in include/linux/page-flags.h. > > + * Context: May be called from interrupt or process context. May not be > > + * called from NMI context. > > Where did the NMI part come from? If you're in NMI context and call unlock_page() and the page has a waiter on it, we call folio_wake_bit(), which calls spin_lock_irqsave() on the wait_queue_head_t lock, which I believe cannot be done safely from NMI context (as the NMI may have interrupted us while holding that lock).
