linux-api.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH v3] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol
@ 2021-07-13  1:38 Peter Collingbourne
  2021-07-14 20:37 ` Alejandro Colomar (man-pages)
  0 siblings, 1 reply; 3+ messages in thread
From: Peter Collingbourne @ 2021-07-13  1:38 UTC (permalink / raw)
  To: Catalin Marinas, Evgenii Stepanov, Kostya Serebryany,
	Vincenzo Frascino, Dave Martin, Will Deacon, Oleg Nesterov,
	Eric W. Biederman, James E.J. Bottomley, Michael Kerrisk,
	Alejandro Colomar
  Cc: Peter Collingbourne, Linux ARM, Kevin Brodsky, Andrey Konovalov,
	linux-api, Helge Deller, David Spickett, linux-man

Signed-off-by: Peter Collingbourne <pcc@google.com>
---
This feature landed back in 5.11, but the manpage
update seems to have fallen through the cracks.
Here's a v3 with the introducing version specified
and with one formatting nit fixed.

v3:
- s/5.x/5.11/g
- s/.IR/.I/ in one location

v2:
- fix formatting
- address feedback from Dave

 man2/sigaction.2 | 125 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)

diff --git a/man2/sigaction.2 b/man2/sigaction.2
index 57ad6418c..6b90982d4 100644
--- a/man2/sigaction.2
+++ b/man2/sigaction.2
@@ -261,6 +261,44 @@ This flag is meaningful only when establishing a signal handler.
 .\" .I sa_sigaction
 .\" field was added in Linux 2.1.86.)
 .\"
+.TP
+.BR SA_UNSUPPORTED
+Used to dynamically probe for flag bit support.
+.IP
+If an attempt to register a handler succeeds with this flag set in
+.I act->sa_flags
+alongside other flags that are potentially unsupported by the kernel,
+and an immediately subsequent
+.BR sigaction ()
+call specifying the same signal number n and with non-NULL
+.I oldact
+yields
+.B SA_UNSUPPORTED
+.I clear
+in
+.IR oldact->sa_flags ,
+then
+.I oldact->sa_flags
+may be used as a bitmask
+describing which of the potentially unsupported flags are,
+in fact, supported.
+See the section "Dynamically probing for flag bit support"
+below for more details.
+.TP
+.BR SA_EXPOSE_TAGBITS " (since Linux 5.11)"
+Normally, when delivering a signal,
+an architecture-specific set of tag bits are cleared from the
+.I si_addr
+field of
+.IR siginfo_t .
+If this flag is set,
+an architecture-specific subset of the tag bits will be preserved in
+.IR si_addr .
+.IP
+Programs that need to be compatible with Linux versions older than 5.11
+must use
+.B SA_UNSUPPORTED
+to probe for support.
 .SS The siginfo_t argument to a SA_SIGINFO handler
 When the
 .B SA_SIGINFO
@@ -846,6 +884,93 @@ Triggered by a
 .BR seccomp (2)
 filter rule.
 .RE
+.SS Dynamically probing for flag bit support
+The
+.BR sigaction ()
+call on Linux accepts unknown bits set in
+.I act->sa_flags
+without error.
+The behavior of the kernel starting with Linux 5.11 is that a second
+.BR sigaction ()
+will clear unknown bits from
+.IR oldact->sa_flags .
+However, historically, a second
+.BR sigaction ()
+call would typically leave those bits set in
+.IR oldact->sa_flags .
+.PP
+This means that support for new flags cannot be detected
+simply by testing for a flag in
+.IR sa_flags ,
+and a program must test that
+.B SA_UNSUPPORTED
+has been cleared before relying on the contents of
+.IR sa_flags .
+.PP
+Since the behavior of the signal handler cannot be guaranteed
+unless the check passes,
+it is wise to either block the affected signal
+while registering the handler and performing the check in this case,
+or where this is not possible,
+for example if the signal is synchronous, to issue the second
+.BR sigaction ()
+in the signal handler itself.
+.PP
+In kernels that do not support a specific flag,
+the kernel's behavior is as if the flag was not set,
+even if the flag was set in
+.IR act->sa_flags .
+.PP
+The flags
+.BR SA_NOCLDSTOP ,
+.BR SA_NOCLDWAIT ,
+.BR SA_SIGINFO ,
+.BR SA_ONSTACK ,
+.BR SA_RESTART ,
+.BR SA_NODEFER ,
+.BR SA_RESETHAND ,
+and, if defined by the architecture,
+.B SA_RESTORER
+may not be reliably probed for using this mechanism,
+because they were introduced before Linux 5.11.
+However, in general, programs may assume that these flags are supported,
+since they have all been supported since Linux 2.6,
+which was released in the year 2003.
+.PP
+The following example program exits with status 0 if
+.B SA_EXPOSE_TAGBITS
+is determined to be supported, and 1 otherwise.
+.PP
+.EX
+#include <signal.h>
+#include <stdio.h>
+#include <unistd.h>
+
+void handler(int signo, siginfo_t *info, void *context) {
+  struct sigaction oldact;
+  if (sigaction(SIGSEGV, 0, &oldact) == 0 &&
+      !(oldact.sa_flags & SA_UNSUPPORTED) &&
+      (oldact.sa_flags & SA_EXPOSE_TAGBITS)) {
+    _exit(0);
+  } else {
+    _exit(1);
+  }
+}
+
+int main(void) {
+  struct sigaction act = {};
+  act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS;
+  act.sa_sigaction = handler;
+  if (sigaction(SIGSEGV, &act, 0) != 0) {
+    perror("sigaction");
+    return 1;
+  }
+
+  /* Force a SIGSEGV. */
+  *(volatile int *)0 = 0;
+  return 1;
+}
+.EE
 .SH RETURN VALUE
 .BR sigaction ()
 returns 0 on success; on error, \-1 is returned, and
-- 
2.32.0.93.g670b81a890-goog


^ permalink raw reply related	[flat|nested] 3+ messages in thread

* Re: [PATCH v3] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol
  2021-07-13  1:38 [PATCH v3] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol Peter Collingbourne
@ 2021-07-14 20:37 ` Alejandro Colomar (man-pages)
  2021-07-15 20:46   ` Peter Collingbourne
  0 siblings, 1 reply; 3+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-07-14 20:37 UTC (permalink / raw)
  To: Peter Collingbourne, Catalin Marinas, Evgenii Stepanov,
	Kostya Serebryany, Vincenzo Frascino, Dave Martin, Will Deacon,
	Oleg Nesterov, Eric W. Biederman, James E.J. Bottomley,
	Michael Kerrisk
  Cc: Linux ARM, Kevin Brodsky, Andrey Konovalov, linux-api,
	Helge Deller, David Spickett, linux-man

Hi Peter,

On 7/13/21 3:38 AM, Peter Collingbourne wrote:
> Signed-off-by: Peter Collingbourne <pcc@google.com>
> ---
> This feature landed back in 5.11, but the manpage
> update seems to have fallen through the cracks.

Sorry, I don't remember what happened :/
Thanks for the ping.

> Here's a v3 with the introducing version specified
> and with one formatting nit fixed.

Please See some comments below (especially in the example code).

BTW, could you please link to the thread in the kernel mailing list that
added this feature?

Thanks,

Alex

> 
> v3:
> - s/5.x/5.11/g
> - s/.IR/.I/ in one location
> 
> v2:
> - fix formatting
> - address feedback from Dave
> 
>  man2/sigaction.2 | 125 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 125 insertions(+)
> 
> diff --git a/man2/sigaction.2 b/man2/sigaction.2
> index 57ad6418c..6b90982d4 100644
> --- a/man2/sigaction.2
> +++ b/man2/sigaction.2
> @@ -261,6 +261,44 @@ This flag is meaningful only when establishing a signal handler.
>  .\" .I sa_sigaction
>  .\" field was added in Linux 2.1.86.)
>  .\"
> +.TP
> +.BR SA_UNSUPPORTED

s/.BR/.B/

> +Used to dynamically probe for flag bit support.
> +.IP
> +If an attempt to register a handler succeeds with this flag set in
> +.I act->sa_flags
> +alongside other flags that are potentially unsupported by the kernel,
> +and an immediately subsequent
> +.BR sigaction ()
> +call specifying the same signal number n and with non-NULL
> +.I oldact
> +yields
> +.B SA_UNSUPPORTED
> +.I clear
> +in
> +.IR oldact->sa_flags ,
> +then
> +.I oldact->sa_flags
> +may be used as a bitmask
> +describing which of the potentially unsupported flags are,
> +in fact, supported.
> +See the section "Dynamically probing for flag bit support"
> +below for more details.
> +.TP
> +.BR SA_EXPOSE_TAGBITS " (since Linux 5.11)"
> +Normally, when delivering a signal,
> +an architecture-specific set of tag bits are cleared from the
> +.I si_addr
> +field of
> +.IR siginfo_t .
> +If this flag is set,
> +an architecture-specific subset of the tag bits will be preserved in
> +.IR si_addr .
> +.IP
> +Programs that need to be compatible with Linux versions older than 5.11
> +must use
> +.B SA_UNSUPPORTED
> +to probe for support.
>  .SS The siginfo_t argument to a SA_SIGINFO handler
>  When the
>  .B SA_SIGINFO
> @@ -846,6 +884,93 @@ Triggered by a
>  .BR seccomp (2)
>  filter rule.
>  .RE
> +.SS Dynamically probing for flag bit support
> +The
> +.BR sigaction ()
> +call on Linux accepts unknown bits set in
> +.I act->sa_flags
> +without error.
> +The behavior of the kernel starting with Linux 5.11 is that a second
> +.BR sigaction ()
> +will clear unknown bits from
> +.IR oldact->sa_flags .
> +However, historically, a second
> +.BR sigaction ()
> +call would typically leave those bits set in
> +.IR oldact->sa_flags .
> +.PP
> +This means that support for new flags cannot be detected
> +simply by testing for a flag in
> +.IR sa_flags ,
> +and a program must test that
> +.B SA_UNSUPPORTED
> +has been cleared before relying on the contents of
> +.IR sa_flags .
> +.PP
> +Since the behavior of the signal handler cannot be guaranteed
> +unless the check passes,
> +it is wise to either block the affected signal
> +while registering the handler and performing the check in this case,
> +or where this is not possible,
> +for example if the signal is synchronous, to issue the second
> +.BR sigaction ()
> +in the signal handler itself.
> +.PP
> +In kernels that do not support a specific flag,
> +the kernel's behavior is as if the flag was not set,
> +even if the flag was set in
> +.IR act->sa_flags .
> +.PP
> +The flags
> +.BR SA_NOCLDSTOP ,
> +.BR SA_NOCLDWAIT ,
> +.BR SA_SIGINFO ,
> +.BR SA_ONSTACK ,
> +.BR SA_RESTART ,
> +.BR SA_NODEFER ,
> +.BR SA_RESETHAND ,
> +and, if defined by the architecture,
> +.B SA_RESTORER
> +may not be reliably probed for using this mechanism,
> +because they were introduced before Linux 5.11.
> +However, in general, programs may assume that these flags are supported,
> +since they have all been supported since Linux 2.6,
> +which was released in the year 2003.
> +.PP
> +The following example program exits with status 0 if
> +.B SA_EXPOSE_TAGBITS
> +is determined to be supported, and 1 otherwise.
> +.PP
> +.EX
> +#include <signal.h>
> +#include <stdio.h>
> +#include <unistd.h>
> +
> +void handler(int signo, siginfo_t *info, void *context) {

Use 4-space indents.

> +  struct sigaction oldact;
> +  if (sigaction(SIGSEGV, 0, &oldact) == 0 &&
> +      !(oldact.sa_flags & SA_UNSUPPORTED) &&
> +      (oldact.sa_flags & SA_EXPOSE_TAGBITS)) {
> +    _exit(0);
> +  } else {
> +    _exit(1);
> +  }
> +}
> +
> +int main(void) {
> +  struct sigaction act = {};

The {} initializer is a GCC extension.  Please use the C99-conforming
{0} zero initializer.  See
<https://stackoverflow.com/questions/11152160/initializing-a-struct-to-0>.

> +  act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS;
> +  act.sa_sigaction = handler;
> +  if (sigaction(SIGSEGV, &act, 0) != 0) {
> +    perror("sigaction");
> +    return 1;
> +  }
> +
> +  /* Force a SIGSEGV. */
> +  *(volatile int *)0 = 0;

Isn't this equivalent to the following (which wouldn't need a comment)?:

raise(SIGSEGV);

> +  return 1;
> +}
> +.EE
>  .SH RETURN VALUE
>  .BR sigaction ()
>  returns 0 on success; on error, \-1 is returned, and
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH v3] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol
  2021-07-14 20:37 ` Alejandro Colomar (man-pages)
@ 2021-07-15 20:46   ` Peter Collingbourne
  0 siblings, 0 replies; 3+ messages in thread
From: Peter Collingbourne @ 2021-07-15 20:46 UTC (permalink / raw)
  To: Alejandro Colomar (man-pages)
  Cc: Catalin Marinas, Evgenii Stepanov, Kostya Serebryany,
	Vincenzo Frascino, Dave Martin, Will Deacon, Oleg Nesterov,
	Eric W. Biederman, James E.J. Bottomley, Michael Kerrisk,
	Linux ARM, Kevin Brodsky, Andrey Konovalov, Linux API,
	Helge Deller, David Spickett, linux-man

On Wed, Jul 14, 2021 at 1:37 PM Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
>
> Hi Peter,
>
> On 7/13/21 3:38 AM, Peter Collingbourne wrote:
> > Signed-off-by: Peter Collingbourne <pcc@google.com>
> > ---
> > This feature landed back in 5.11, but the manpage
> > update seems to have fallen through the cracks.
>
> Sorry, I don't remember what happened :/
> Thanks for the ping.
>
> > Here's a v3 with the introducing version specified
> > and with one formatting nit fixed.
>
> Please See some comments below (especially in the example code).

Addressed all comments in v4.

> BTW, could you please link to the thread in the kernel mailing list that
> added this feature?

There were several threads (the patch went through several revisions).
But you can find your way to most of the threads starting from here:
https://lore.kernel.org/linux-arm-kernel/?q=pcc+far_el1

Peter

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2021-07-15 20:46 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-07-13  1:38 [PATCH v3] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol Peter Collingbourne
2021-07-14 20:37 ` Alejandro Colomar (man-pages)
2021-07-15 20:46   ` Peter Collingbourne

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).