compat: backport poll_requested_events() and poll_does_not_wait()

The main thing for the backport was the poll_table key and qproc
fields renames. We only enable this for kernels > 2.6.31 given that
these old fields only exist as of that kernel and this is currently
only used by video drivers which are only supported as of v3.2.

mcgrof@frijol ~/linux-next (git::master)$ git describe --contains 626cf236
v3.4-rc1~109^2~52

commit 626cf236608505d376e4799adb4f7eb00a8594af
Author: Hans Verkuil <hans.verkuil@cisco.com>
Date:   Fri Mar 23 15:02:27 2012 -0700

    poll: add poll_requested_events() and poll_does_not_wait() functions

    In some cases the poll() implementation in a driver has to do different
    things depending on the events the caller wants to poll for.  An example
    is when a driver needs to start a DMA engine if the caller polls for
    POLLIN, but doesn't want to do that if POLLIN is not requested but instead
    only POLLOUT or POLLPRI is requested.  This is something that can happen
    in the video4linux subsystem among others.

    Unfortunately, the current epoll/poll/select implementation doesn't
    provide that information reliably.  The poll_table_struct does have it: it
    has a key field with the event mask.  But once a poll() call matches one
    or more bits of that mask any following poll() calls are passed a NULL
    poll_table pointer.

    Also, the eventpoll implementation always left the key field at ~0 instead
    of using the requested events mask.

    This was changed in eventpoll.c so the key field now contains the actual
    events that should be polled for as set by the caller.

    The solution to the NULL poll_table pointer is to set the qproc field to
    NULL in poll_table once poll() matches the events, not the poll_table
    pointer itself.  That way drivers can obtain the mask through a new
    poll_requested_events inline.

    The poll_table_struct can still be NULL since some kernel code calls it
    internally (netfs_state_poll() in ./drivers/staging/pohmelfs/netfs.h).  In
    that case poll_requested_events() returns ~0 (i.e.  all events).

    Very rarely drivers might want to know whether poll_wait will actually
    wait.  If another earlier file descriptor in the set already matched the
    events the caller wanted to wait for, then the kernel will return from the
    select() call without waiting.  This might be useful information in order
    to avoid doing expensive work.

    A new helper function poll_does_not_wait() is added that drivers can use
    to detect this situation.  This is now used in sock_poll_wait() in
    include/net/sock.h.  This was the only place in the kernel that needed
    this information.

    Drivers should no longer access any of the poll_table internals, but use
    the poll_requested_events() and poll_does_not_wait() access functions
    instead.  In order to enforce that the poll_table fields are now prepended
    with an underscore and a comment was added warning against using them
    directly.

    This required a change in unix_dgram_poll() in unix/af_unix.c which used
    the key field to get the requested events.  It's been replaced by a call
    to poll_requested_events().

    For qproc it was especially important to change its name since the
    behavior of that field changes with this patch since this function pointer
    can now be NULL when that wasn't possible in the past.

    Any driver accessing the qproc or key fields directly will now fail to compile.

    Some notes regarding the correctness of this patch: the driver's poll()
    function is called with a 'struct poll_table_struct *wait' argument.  This
    pointer may or may not be NULL, drivers can never rely on it being one or
    the other as that depends on whether or not an earlier file descriptor in
    the select()'s fdset matched the requested events.

    There are only three things a driver can do with the wait argument:

    1) obtain the key field:

        events = wait ? wait->key : ~0;

       This will still work although it should be replaced with the new
       poll_requested_events() function (which does exactly the same).
       This will now even work better, since wait is no longer set to NULL
       unnecessarily.

    2) use the qproc callback. This could be deadly since qproc can now be
       NULL. Renaming qproc should prevent this from happening. There are no
       kernel drivers that actually access this callback directly, BTW.

    3) test whether wait == NULL to determine whether poll would return without
       waiting. This is no longer sufficient as the correct test is now
       wait == NULL || wait->_qproc == NULL.

       However, the worst that can happen here is a slight performance hit in
       the case where wait != NULL and wait->_qproc == NULL. In that case the
       driver will assume that poll_wait() will actually add the fd to the set
       of waiting file descriptors. Of course, poll_wait() will not do that
       since it tests for wait->_qproc. This will not break anything, though.

       There is only one place in the whole kernel where this happens
       (sock_poll_wait() in include/net/sock.h) and that code will be replaced
       by a call to poll_does_not_wait() in the next patch.

       Note that even if wait->_qproc != NULL drivers cannot rely on poll_wait()
       actually waiting. The next file descriptor from the set might match the
       event mask and thus any possible waits will never happen.

    Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
    Reviewed-by: Jonathan Corbet <corbet@lwn.net>
    Reviewed-by: Al Viro <viro@zeniv.linux.org.uk>
    Cc: Davide Libenzi <davidel@xmailserver.org>
    Signed-off-by: Hans de Goede <hdegoede@redhat.com>
    Cc: Mauro Carvalho Chehab <mchehab@infradead.org>
    Cc: David Miller <davem@davemloft.net>
    Cc: Eric Dumazet <eric.dumazet@gmail.com>
    Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
    Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Signed-off-by: Luis R. Rodriguez <mcgrof@do-not-panic.com>

diff --git a/backport/include/linux/compat-3.4.h b/backport/include/linux/compat-3.4.h
index 3866330b566903b2b39c74c340fd4ae16cb0f38c..dab64fc0ad746da567c15fb9a82ed9e9401b163a 100644 (file)
--- a/backport/include/linux/compat-3.4.h
+++ b/backport/include/linux/compat-3.4.h
@@ -5,6 +5,8 @@
 
 #if (LINUX_VERSION_CODE < KERNEL_VERSION(3,4,0))
 
+#include <linux/poll.h>
+
 /*
  * defined here to allow things to compile but technically
  * using this for memory regions will yield in a no-op on newer
@@ -144,6 +146,31 @@ static inline void eth_hw_addr_random(struct net_device *dev)
 #define __config_enabled(arg1_or_junk) ___config_enabled(arg1_or_junk 1, 0)
 #define ___config_enabled(__ignored, val, ...) val
 
+#if (LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,31))
+/*
+ * Return true if it is guaranteed that poll will not wait. This is the case
+ * if the poll() of another file descriptor in the set got an event, so there
+ * is no need for waiting.
+ */
+#define poll_does_not_wait LINUX_BACKPORT(poll_does_not_wait)
+static inline bool poll_does_not_wait(const poll_table *p)
+{
+       return p == NULL || p->qproc == NULL;
+}
+
+/*
+ * Return the set of events that the application wants to poll for.
+ * This is useful for drivers that need to know whether a DMA transfer has
+ * to be started implicitly on poll(). You typically only want to do that
+ * if the application is actually polling for POLLIN and/or POLLOUT.
+ */
+#define poll_requested_events LINUX_BACKPORT(poll_requested_events)
+static inline unsigned long poll_requested_events(const poll_table *p)
+{
+       return p ? p->key : ~0UL;
+}
+#endif /* (LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,31)) */
+
 #endif /* (LINUX_VERSION_CODE < KERNEL_VERSION(3,4,0)) */
 
 #endif /* LINUX_5_4_COMPAT_H */