[patch[ epoll_ctl.2, epoll.7: document EPOLLWAKEUP

[NeilBrown <neilb-l3A5Bk7waGM@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 2340 bytes --]



Signed-off-by: NeilBrown <neilb-l3A5Bk7waGM@public.gmane.org>
--

I noticed that this was missing so had a go at writing something.

Is there / Should there be a section 7 man page describing suspend and
autosuspend and wakelocks etc??

Comments (of course) welcome.

NeilBrown


diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2
index 1fbe74eeea4e..6388f19195f1 100644
--- a/man2/epoll_ctl.2
+++ b/man2/epoll_ctl.2
@@ -154,6 +154,26 @@ The user must call
 with
 .B EPOLL_CTL_MOD
 to rearm the file descriptor with a new event mask.
+.TP
+.BR EPOLLWAKEUP " (since Linux 3.5)"
+If
+.B EPOLLONESHOT
+and
+.B EPOLLET
+are clear and the process has the
+.B CAP_BLOCK_SUSPEND
+.BR capability (7),
+ensure that the system does not enter "suspend" or
+"hibernate" while this event is pending or being processed.
+The event is considered as being "processed" from when it returned by
+a call to
+.BR epoll_wait (2)
+until the next call to
+.BR epoll_wait (2)
+on the same
+.BR epoll (7)
+file descriptor.
+.\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
 .SH RETURN VALUE
 When successful,
 .BR epoll_ctl ()
diff --git a/man7/epoll.7 b/man7/epoll.7
index a372d9727978..31b1a8c8c9ba 100644
--- a/man7/epoll.7
+++ b/man7/epoll.7
@@ -173,6 +173,35 @@ it is the caller's responsibility to rearm the file
descriptor using .BR epoll_ctl (2)
 with
 .BR EPOLL_CTL_MOD .
+.SS Interaction with autosleep
+If the system is in
+.B autosleep
+mode via
+.I /sys/power/autosleep
+and an event happens which wakes the device from sleep, the device
+driver will only keep the device awake until that event is queued.  To
+keep the device awake until the event has been processed it is
+necessary to use
+.B epoll
+and the
+.B EPOLLWAKEUP
+flag.
+
+When this flag is set in the
+.B events
+field for a
+.I struct epoll_event
+then system will be kept awake from the moment the event is queued,
+through the
+.IR epoll_wait (2)
+call which returns the event until the subsequent
+.IR epoll_wait (2)
+call.  If the event should keep the system awake beyond that time,
+the a separate
+.I wake_lock
+should be taken before the second
+.IR epoll_wait (2)
+call.
 .SS /proc interfaces
 The following interfaces can be used to limit the amount of
 kernel memory consumed by epoll:

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 828 bytes --]