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

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

[NeilBrown]

[-- 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 --]

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

[Michael Kerrisk (man-pages)]

Hi Neil,

On 07/06/2014 11:03 AM, NeilBrown wrote:
> 
> 
> Signed-off-by: NeilBrown <neilb-l3A5Bk7waGM@public.gmane.org>
> --
> 
> 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.

> 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?

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

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

Cheers,

Michael

--- a/man2/epoll_ctl.2
+++ b/man2/epoll_ctl.2
@@ -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),




-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[NeilBrown]

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


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

On Mon, 07 Jul 2014 08:46:28 +0200 "Michael Kerrisk (man-pages)"
<mtk.manpages@gmail.com> wrote:

> Hi Neil,
> 
> On 07/06/2014 11:03 AM, NeilBrown wrote:
> > 
> > 
> > Signed-off-by: NeilBrown <neilb@suse.de>
> > --
> > 
> > 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.
> 
> > 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?

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 worth
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 virtual
files ....)

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

And thanks for your improvements to my submission!

NeilBrown


> 
> > 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:
> 
> All of the above looks good. I also added the piece sad little 
> detail shown below.
> 
> Cheers,
> 
> Michael
> 
> --- a/man2/epoll_ctl.2
> +++ b/man2/epoll_ctl.2
> @@ -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),
> 
> 
> 
> 


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

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

[Rafael J. Wysocki]

On Monday, July 07, 2014 09:01:57 PM NeilBrown wrote:
> 
> --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).

First off, thanks a lot for taking care of this!

> On Mon, 07 Jul 2014 08:46:28 +0200 "Michael Kerrisk (man-pages)"
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> 
> > Hi Neil,
> >=20
> > On 07/06/2014 11:03 AM, NeilBrown wrote:
> > >=20
> > >=20
> > > Signed-off-by: NeilBrown <neilb-l3A5Bk7waGM@public.gmane.org>
> > > --
> > >=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
> > > 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 :-)

That probably is a good estimation.

Please note that there is some documentation of these things in
Documentation/ABI/testing/sysfs-power in the kernel tree that may be useful
for creating that page.

Also please let me know if I can help.

Rafael

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] epoll_ctl.2: minor clarification concerning when a WAKEUP event is "processes"

[NeilBrown]

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


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 <neilb-l3A5Bk7waGM@public.gmane.org>

diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2
index 2936bc7e97f7..74a09b6c276b 100644
--- a/man2/epoll_ctl.2
+++ b/man2/epoll_ctl.2
@@ -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,

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

Re: [PATCH] epoll_ctl.2: minor clarification concerning when a WAKEUP event is "processes"

[Michael Kerrisk (man-pages)]

Hi Neil,
On 07/09/2014 05:37 AM, NeilBrown wrote:
> 
> 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".

Thanks. Probably better to be explicit, as you say. Applied.

Cheers,

Michael


> Signed-off-by: NeilBrown <neilb-l3A5Bk7waGM@public.gmane.org>
> 
> diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2
> index 2936bc7e97f7..74a09b6c276b 100644
> --- a/man2/epoll_ctl.2
> +++ b/man2/epoll_ctl.2
> @@ -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,
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] epoll_ctl.2: minor clarification concerning when a WAKEUP event is "processes"

[Rafael J. Wysocki]

On Wednesday, July 09, 2014 01:37:46 PM NeilBrown wrote:
> 
> --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 <neilb-l3A5Bk7waGM@public.gmane.org>

Acked-by: Rafael J. Wysocki <rafael.j.wysocki-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>

> diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2
> index 2936bc7e97f7..74a09b6c276b 100644
> --- a/man2/epoll_ctl.2
> +++ b/man2/epoll_ctl.2
> @@ -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--
> 

-- 
I speak only for myself.
Rafael J. Wysocki, Intel Open Source Technology Center.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html