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

Signed-off-by NeilBrown <[email protected]>

--

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

man2/epoll_ctl.2 +20 -0

index 1fbe74eeea4e..6388f19195f1 100644
@@ -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 ()

man7/epoll.7 +22 -0

index a372d9727978..31b1a8c8c9ba 100644
@@ -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

Hi Neil,

Quoted 6 lines · NeilBrown

Signed-off-by NeilBrown <[email protected]>

--

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

Thanks. I applied this, and also added the additional piece shown at the end of this mail.

Quoted 2 lines

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

Sounds like it might be useful, but I don't know for sure. On the assumption that it might be possible to convince you to write one, could you briefly list what you think should be covered in the page?

Quoted 67 lines

Comments (of course) welcome.

NeilBrown

man2/epoll_ctl.2 +20 -0

index 1fbe74eeea4e..6388f19195f1 100644
@@ -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 ()

man7/epoll.7 +22 -0

index a372d9727978..31b1a8c8c9ba 100644
@@ -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

man7/epoll.7 it is the caller's responsibility to rearm the file · line 207

Quoted 10 lines

man7/epoll.7 +7 -0

+.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:

All of the above looks good. I also added the piece sad little detail shown below.

Cheers,

Michael

man2/epoll_ctl.2 +28 -0

@@ -174,6 +174,7 @@ until the next call to
 on the same
 .BR epoll (7)
 file descriptor.
+See also BUGS.
 .SH RETURN VALUE
 When successful,
 .BR epoll_ctl ()

@@ -270,6 +271,33 @@ when using
 Applications that need to be portable to kernels before 2.6.9
 should specify a non-null pointer in
 .IR event .
+
+If
+.B EPOLLWAKEUP
+is specified in
+.IR flags ,
+but the caller does not have the
+.BR CAP_BLOCK_SUSPEND
+capability, then the
+.B EPOLLWAKEUP
+flag is
+.IR "silently ignored" .
+This unfortunate behavior is necessary because no validity
+checks were performed on the
+.IR flags
+argument in the original implementation, and the addition of the
+.B EPOLLWAKEUP
+with a check that caused the call to fail if the caller did not have the
+.B CAP_BLOCK_SUSPEND
+capability caused a breakage in at least one existing user-space
+application that happened to randomly (and uselessly) specify this bit.
+.\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
+.\" https://lwn.net/Articles/520198/
+A robust application should therefore double check that it has the
+.B CAP_BLOCK_SUSPEND
+capability if attempting to use the
+.B EPOLLWAKEUP
+flag.
 .SH SEE ALSO
 .BR epoll_create (2),
 .BR epoll_wait (2),

--Sig_/ryAieyiS4Xod5WCxzxhl62b
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: quoted-printable

(adding lkml and linux-pm and I probably should have done from the start).

Quoted 13 lines · On Mon, 07 Jul 2014 08:46:28 +0200 "Michael Kerrisk (man-pages)"…

Hi Neil,
=20

Quoted 6 lines · NeilBrown

=20
=20

Signed-off-by NeilBrown <[email protected]>

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

=20
Thanks. I applied this, and also added the additional piece shown=20 at the end of this mail.
=20

Quoted 6 lines

Quoted 2 lines

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

=20
Sounds like it might be useful, but I don't know for sure. On the=20 assumption that it might be possible to convince you to write one, could you briefly list what you think should be covered in the page?

I was particularly thinking of "/sys/power/autosleep" because my change to epoll.7 mentioned autosleep, but there was no man page to reference. The interaction of /sys/power/wakeup_count" with suspend/resume is also wor= th
documenting as is the use of wake_locks via /sys/power/wake_{,un}lock (which could also usefully be referenced by epoll(7)).

Given the number of filenames here, maybe this belongs in section 5 rather than section 7. Similar to proc(5) we could have power(5) which documents /sys/power ???
(OK, I can see this might be opening a can of worms - we'll be having class(5) and bus(5) and devices(5) next... but maybe this is a good thing. And seeing these are all part of the kernel API, maybe they should be in section 2 with the systemcalls. Or do with need a new section of API virtu= al
files ....)

So I guess "ls /sys/power" is a brief list of what should be included in the page :-)

I guess it should be obvious, but it never hurts to be explicit. When the epoll file descriptor is closed all events are assumed to be "processed".
Also if the event is removed with EPOLL_CTL_DEL or the EPOLLWAKEUP flag is removed with EPOLL_CTL_MOD the event will be "processed".

Signed-off-by NeilBrown <[email protected]>

man2/epoll_ctl.2 +8 -1

index 2936bc7e97f7..74a09b6c276b 100644
@@ -173,7 +173,14 @@ until the next call to
 .BR epoll_wait (2)
 on the same
 .BR epoll (7)
-file descriptor.
+file descriptor,
+the closure of that file descriptor,
+the removal of the event file descriptor with
+.BR EPOLL_CTL_DEL ,
+or the clearing of
+.B EPOLLWAKEUP
+for the event file descriptor with
+.BR EPOLL_CTL_MOD .
 See also BUGS.
 .SH RETURN VALUE
 When successful,

--Sig_/BvtUQvnWLsVQBetw73gPkyQ
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: quoted-printable

I guess it should be obvious, but it never hurts to be explicit. When the epoll file descriptor is closed all events are assumed to be "processed".
Also if the event is removed with EPOLL_CTL_DEL or the EPOLLWAKEUP flag is removed with EPOLL_CTL_MOD the event will be "processed".

Signed-off-by NeilBrown <[email protected]>

man2/epoll_ctl.2 +8 -2

index 2936bc7e97f7..74a09b6c276b 100644
@@ -173,7 +173,14 @@ until the next call to
 .BR epoll_wait (2)
 on the same
 .BR epoll (7)
-file descriptor.
+file descriptor,
+the closure of that file descriptor,
+the removal of the event file descriptor with
+.BR EPOLL_CTL_DEL ,
+or the clearing of
+.B EPOLLWAKEUP
+for the event file descriptor with
+.BR EPOLL_CTL_MOD .
 See also BUGS.
 .SH RETURN VALUE
 When successful,
 
--Sig_/BvtUQvnWLsVQBetw73gPkyQ

Content-Type: application/pgp-signature; name=signature.asc
Content-Disposition: attachment; filename=signature.asc

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)

iQIVAwUBU7y5Cjnsnt1WYoG5AQJjuQ/+JshOD5nn4wRh83j+QK8Y1ff1Fynw2jh4 vWGGdF/XdEyJgagnFuIuVHHmn0yyGvGYE8xFzgtBJqs12O6+7AshRUXtCSjr6f7r kwa4dZQvwDMr0SchoIsftexZJJPQOE7zxDwm7jjk7682/VoePbCtXHUnVUM3G6Hl 5n/11WDocetHFztj95lIF8KIQZ98Q7ZOETvdxnZXIvBtxxaPLVdOS/a7d8q2bcP3 /rvM+JyA0SnUx3ZFTbqYWmUk/WWDjXhBEwt5fSqqph4zOT7sxjCH1kmap1MV4ej2 ZzQ5rgecQDL+YAJTLYNKeDCeYpGQYVDNUK4oLq5ofsNLcump3jAlnUfmB96ifD7h iXxWExv9r1Zk3aS//ZRgFQuGas+w23wklEjaavwQFt9S0aoS6zmcsSWpucyvpYCW JOguVvqO4qphadh1gfOhWEpYVgD9AhADqICLymwcVAphYq/TenRqFPv7UdbcBE0l vDM5D8R0bLrcHLheA2YWwwxTDdZo49D08Pf7RopKbnoMxmwpoxRdkYiJ/n981wgR 4S3FQgSAD+wsI87kwkf0uU3YXT5IYrMt5VoaQZysDTC1ryPuHn4JPexw0YRDOd7l D+SSounos3jqMTVsmKolA84pSMmEcPwQ0624QHouWWkGVlcApIw2xDgr1c6TYzPq s/V/0SXPztU=
=8PYy
-----END PGP SIGNATURE-----

--Sig_/BvtUQvnWLsVQBetw73gPkyQ--