epoll: comment the funky #ifdef

epoll: comment the funky #ifdef

Looking for a bug in -rt, I stumbled across this code here from: commit
b01f4612b979 ("epoll keyed wakeups: teach epoll about hints coming with
the wakeup key"), specifically:

  #ifdef CONFIG_DEBUG_LOCK_ALLOC
  static inline void ep_wake_up_nested(wait_queue_head_t *wqueue,
                                      unsigned long events, int subclass)
  {
         unsigned long flags;

         spin_lock_irqsave_nested(&wqueue->lock, flags, subclass);
         wake_up_locked_poll(wqueue, events);
         spin_unlock_irqrestore(&wqueue->lock, flags);
  }
  #else
  static inline void ep_wake_up_nested(wait_queue_head_t *wqueue,
                                      unsigned long events, int subclass)
  {
         wake_up_poll(wqueue, events);
  }
  #endif

You change the function of ep_wake_up_nested() depending on whether
CONFIG_DEBUG_LOCK_ALLOC is set or not.  This looks awfully suspicious,
and there's no comment to explain why.  I initially thought that this
was trying to fool lockdep, and hiding a real bug.

Investigating it, I found the creation of wake_up_nested() (which no
longer exists) but was created for the sole purpose of epoll and its
strange wake ups, as explained in commit 5e508ec50b08 ("lockdep:
annotate epoll")

Although the commit message says "annotate epoll" the change log is much
better at explaining what is happening than what is in the actual code.
Thus a comment is really necessary here.  And to save the time of other
developers from having to go trudging through the git logs trying to
figure out why this code exists.

I took parts of the change log and placed it into a comment above the
affected code.  This will make the description of what is happening more
visible to new developers that have to look at this code for the first
time.

Signed-off-by: Steven Rostedt <rostedt@goodmis.org>
Cc: Davide Libenzi <davidel@xmailserver.org>
Cc: Peter Zijlstra <a.p.zijlstra@chello.nl>
Cc: Alan Cox <alan@lxorguk.ukuu.org.uk>
Cc: Ingo Molnar <mingo@elte.hu>
Cc: David Miller <davem@davemloft.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>