[man-pages PATCH 2/5] s390_runtime_instr.2: document the removal of the second argument

[man-pages PATCH 2/5] s390_runtime_instr.2: document the removal of the second argument

[Eugene Syromyatnikov]

Kernel's commit b38feccd663b55ab07116208b68e1ffc7c3c7e78 removed the
second argument from the system call.

* man2/s390_runtime_instr.2 (.SH SYNOPSIS): Add the prototype for the
version syscall available in Linux 4.4 onward.
(.SH DESCRIPTION): Change the description of the signum parameter to
the past tense, note that it is ignored since Linux 4.4.
(.SH VERSIONS): Note that syscall has changed its prototype along with
the reason of change.
(.SH NOTES): Note that it's impossible to judge whether the signal
delivery functionality has been successfully enabled by the
successfulness of the return code.
---
 man2/s390_runtime_instr.2 | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
index f979692..178237f 100644
--- a/man2/s390_runtime_instr.2
+++ b/man2/s390_runtime_instr.2
@@ -30,7 +30,12 @@ s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation
 .\" This heder never had been a part of uapi as of 4.15
 .\" .B #include <asm/runtime_instr.h>
 .\" .PP
+.\" The signum argument has been removed in v4.4-rc1~138^2
+/* From Linux 3.7 to Linux 4.3 */
 .BI "int s390_runtime_instr(int " command ", int " signum ");
+.PP
+/* Since Linux 4.4 */
+.BI "int s390_runtime_instr(int " command ");"
 .fi
 .SH DESCRIPTION
 The
@@ -48,10 +53,12 @@ argument controls whether run-time instrumentation is started
 .PP
 The
 .IR signum
-argument specifies the number of a real-time signal.
-The real-time signal is sent to the thread if the run-time instrumentation
+argument was available up to Linux 4.3 and allowed specifying the number
+of a real-time signal.
+The real-time signal was sent to the thread if the run-time instrumentation
 buffer is full or if the run-time-instrumentation-halted interrupt
 occurred.
+The argument is ignored from Linux 4.4 onwards and no signal is sent.
 .SH RETURN VALUE
 On success,
 .BR s390_runtime_instr ()
@@ -79,6 +86,10 @@ Allocating memory for the run-time instrumentation control block failed.
 The run-time instrumentation facility is not available.
 .SH VERSIONS
 This system call is available since Linux 3.7.
+.PP
+Starting with Linux 4.4, the system call has its second argument removed,
+since "[t]he external interrupts for runtime instrumentation buffer-full
+and runtime instrumentation halted are unused and have no current user."
 .SH CONFORMING TO
 This Linux-specific system call is available only on the s390 architecture.
 The run-time instrumentation facility is available beginning with System z EC12.
@@ -92,6 +103,11 @@ Kernel's header
 contains the necessary declarations for using run-time instrumentation.
 Unfortunately, it hasn't been included as a part of Linux's UAPI
 as of Linux 4.15.
+.PP
+Beware that since the second argument ignored since Linux 4.4, and no error
+is returned in case it is specified on these newer kernels, application
+can't rely on the availability of the signal delivery functionality
+(or at least check it by setting erroneous value in the second argument).
 .SH SEE ALSO
 .BR syscall (2),
 .BR signal (7)
-- 
2.1.4

--
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: [man-pages PATCH 2/5] s390_runtime_instr.2: document the removal of the second argument

[Heiko Carstens]

On Sun, Jan 14, 2018 at 07:56:27PM +0100, Eugene Syromyatnikov wrote:
> Kernel's commit b38feccd663b55ab07116208b68e1ffc7c3c7e78 removed the
> second argument from the system call.
> 
> * man2/s390_runtime_instr.2 (.SH SYNOPSIS): Add the prototype for the
> version syscall available in Linux 4.4 onward.
> (.SH DESCRIPTION): Change the description of the signum parameter to
> the past tense, note that it is ignored since Linux 4.4.
> (.SH VERSIONS): Note that syscall has changed its prototype along with
> the reason of change.
> (.SH NOTES): Note that it's impossible to judge whether the signal
> delivery functionality has been successfully enabled by the
> successfulness of the return code.
> ---
>  man2/s390_runtime_instr.2 | 20 ++++++++++++++++++--
>  1 file changed, 18 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
> index f979692..178237f 100644
> --- a/man2/s390_runtime_instr.2
> +++ b/man2/s390_runtime_instr.2
>  .BI "int s390_runtime_instr(int " command ", int " signum ");
> +.PP
> +/* Since Linux 4.4 */
> +.BI "int s390_runtime_instr(int " command ");"
...
> -argument specifies the number of a real-time signal.
> -The real-time signal is sent to the thread if the run-time instrumentation
> +argument was available up to Linux 4.3 and allowed specifying the number
> +of a real-time signal.
> +The real-time signal was sent to the thread if the run-time instrumentation
>  buffer is full or if the run-time-instrumentation-halted interrupt
>  occurred.
> +The argument is ignored from Linux 4.4 onwards and no signal is sent.
>  .SH RETURN VALUE
>  On success,
>  .BR s390_runtime_instr ()
> @@ -79,6 +86,10 @@ Allocating memory for the run-time instrumentation control block failed.
>  The run-time instrumentation facility is not available.
>  .SH VERSIONS
>  This system call is available since Linux 3.7.
> +.PP
> +Starting with Linux 4.4, the system call has its second argument removed,
> +since "[t]he external interrupts for runtime instrumentation buffer-full
> +and runtime instrumentation halted are unused and have no current user."
>  .SH CONFORMING TO
>  This Linux-specific system call is available only on the s390 architecture.
>  The run-time instrumentation facility is available beginning with System z EC12.
> @@ -92,6 +103,11 @@ Kernel's header
>  contains the necessary declarations for using run-time instrumentation.
>  Unfortunately, it hasn't been included as a part of Linux's UAPI
>  as of Linux 4.15.
> +.PP
> +Beware that since the second argument ignored since Linux 4.4, and no error
> +is returned in case it is specified on these newer kernels, application
> +can't rely on the availability of the signal delivery functionality
> +(or at least check it by setting erroneous value in the second argument).

All what you write is correct, however I don't think this should be
documented. It was actually a bad decision to remove the second system call
argument and don't check it's validity anymore.

If you now document the above people will start using the system call with
only one parameter which isn't backwards compatible.

I'd rather add the second parameter again to the system call so that code
stays backwards compatible.

Thanks for reporting this inconsistency as well!

--
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: [man-pages PATCH 2/5] s390_runtime_instr.2: document the removal of the second argument

[Eugene Syromyatnikov]

On Sat, Jan 20, 2018 at 11:41 AM, Heiko Carstens
<heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
> If you now document the above people will start using the system call with
> only one parameter which isn't backwards compatible.
>
> I'd rather add the second parameter again to the system call so that code
> stays backwards compatible.

Well, it ought to be documented somehow, especially if the syscall
parameter will be added back, as there could be situation where
application gets successful return code for the call non-zero value of
the second argument and gets no signals as it is the one of the kernel
releases where this parameter was removed. I can update the patch to
reflect this once the patch that returns the second argument reaches
the kernel tree.

-- 
Eugene Syromyatnikov
mailto:evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:esyr@jabber.{ru|org}
--
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: [man-pages PATCH 2/5] s390_runtime_instr.2: document the removal of the second argument

[Heiko Carstens]

On Mon, Jan 22, 2018 at 01:16:25PM +0000, Eugene Syromyatnikov wrote:
> On Sat, Jan 20, 2018 at 11:41 AM, Heiko Carstens
> <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
> > If you now document the above people will start using the system call with
> > only one parameter which isn't backwards compatible.
> >
> > I'd rather add the second parameter again to the system call so that code
> > stays backwards compatible.
> 
> Well, it ought to be documented somehow, especially if the syscall
> parameter will be added back, as there could be situation where
> application gets successful return code for the call non-zero value of
> the second argument and gets no signals as it is the one of the kernel
> releases where this parameter was removed. I can update the patch to
> reflect this once the patch that returns the second argument reaches
> the kernel tree.

So, I think something like the below should be ok:

>From 6c7e2113c62fbb95662fba03f7fa298f4b737c1f Mon Sep 17 00:00:00 2001
From: Heiko Carstens <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org>
Date: Wed, 31 Jan 2018 08:15:31 +0100
Subject: [PATCH] s390_runtime_instr.2: document signum argument behavior
 change

Document that the signum argument is ignored in newer kernels, but
that user space should pass a valid real-time signal number for
backwards compatibility.

Signed-off-by: Heiko Carstens <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org>
---
 man2/s390_runtime_instr.2 | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
index 18c2c0763eed..d5790e10f222 100644
--- a/man2/s390_runtime_instr.2
+++ b/man2/s390_runtime_instr.2
@@ -47,10 +47,9 @@ argument controls whether run-time instrumentation is started
 .PP
 The
 .IR signum
-argument specifies the number of a real-time signal.
-The real-time signal is sent to the thread if the run-time instrumentation
-buffer is full or if the run-time-instrumentation-halted interrupt
-occurred.
+argument specifies the number of a real-time signal. This argument has no
+effect, since support for signalling was never used and kernel support was
+removed.
 .SH RETURN VALUE
 On success,
 .BR s390_runtime_instr ()
@@ -67,9 +66,16 @@ is set to one of the error codes listed below.
 .B EINVAL
 The value specified in
 .IR command
-is not a valid command or the value specified in
+is not a valid command.
+.TP
+.B EINVAL
+The value specified in
 .IR signum
-is not a real-time signal number.
+is not a real-time signal number. With Linux 4.4 and newer kernel versions,
+the
+.IR signum
+argument has no effect, so that an invalid signal number will not result in an
+error.
 .TP
 .B ENOMEM
 Allocating memory for the run-time instrumentation control block failed.
@@ -85,6 +91,12 @@ The run-time instrumentation facility is available beginning with System z EC12.
 Glibc does not provide a wrapper for this system call, use
 .BR syscall (2)
 to call it.
+.PP
+Support for signalling was removed with Linux 4.4. With Linux 4.4
+also the check if
+.IR signum
+is a valid real-time signal was removed. For backwards compatibility with old
+kernels it is recommended to pass a valid real-time signal number.
 .SH SEE ALSO
 .BR syscall (2),
 .BR signal (7)
-- 
2.13.5

--
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: [man-pages PATCH 2/5] s390_runtime_instr.2: document the removal of the second argument

[Eugene Syromyatnikov]

On Wed, Jan 31, 2018 at 7:20 AM, Heiko Carstens
<heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
> @@ -85,6 +91,12 @@ The run-time instrumentation facility is available beginning with System z EC12.
>  Glibc does not provide a wrapper for this system call, use
>  .BR syscall (2)
>  to call it.
> +.PP
> +Support for signalling was removed with Linux 4.4. With Linux 4.4
> +also the check if
> +.IR signum
> +is a valid real-time signal was removed. For backwards compatibility with old
> +kernels it is recommended to pass a valid real-time signal number.
I would recommend passing 0 instead, as passing non-zero signal number
implies that the userspace process expects to receive this signal in
the future in case of aforementioned events, and this will not happen
on Linux 4.4 onwards.

--
Eugene Syromyatnikov
mailto:evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:esyr@jabber.{ru|org}
--
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: [man-pages PATCH 2/5] s390_runtime_instr.2: document the removal of the second argument

[Heiko Carstens]

On Wed, Jan 31, 2018 at 08:41:39AM +0000, Eugene Syromyatnikov wrote:
> On Wed, Jan 31, 2018 at 7:20 AM, Heiko Carstens
> <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
> > @@ -85,6 +91,12 @@ The run-time instrumentation facility is available beginning with System z EC12.
> >  Glibc does not provide a wrapper for this system call, use
> >  .BR syscall (2)
> >  to call it.
> > +.PP
> > +Support for signalling was removed with Linux 4.4. With Linux 4.4
> > +also the check if
> > +.IR signum
> > +is a valid real-time signal was removed. For backwards compatibility with old
> > +kernels it is recommended to pass a valid real-time signal number.
> I would recommend passing 0 instead, as passing non-zero signal number
> implies that the userspace process expects to receive this signal in
> the future in case of aforementioned events, and this will not happen
> on Linux 4.4 onwards.

Passing 0 as signum is not backwards compatible, since that will result in
an error with old kernels.

--
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: [man-pages PATCH 2/5] s390_runtime_instr.2: document the removal of the second argument

[Eugene Syromyatnikov]

On Wed, Jan 31, 2018 at 9:21 AM, Heiko Carstens
<heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
> On Wed, Jan 31, 2018 at 08:41:39AM +0000, Eugene Syromyatnikov wrote:
>> On Wed, Jan 31, 2018 at 7:20 AM, Heiko Carstens
>> <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
>> > @@ -85,6 +91,12 @@ The run-time instrumentation facility is available beginning with System z EC12.
>> >  Glibc does not provide a wrapper for this system call, use
>> >  .BR syscall (2)
>> >  to call it.
>> > +.PP
>> > +Support for signalling was removed with Linux 4.4. With Linux 4.4
>> > +also the check if
>> > +.IR signum
>> > +is a valid real-time signal was removed. For backwards compatibility with old
>> > +kernels it is recommended to pass a valid real-time signal number.
>> I would recommend passing 0 instead, as passing non-zero signal number
>> implies that the userspace process expects to receive this signal in
>> the future in case of aforementioned events, and this will not happen
>> on Linux 4.4 onwards.
>
> Passing 0 as signum is not backwards compatible, since that will result in
> an error with old kernels.
>
Oh, I see, sorry, for some reason I thought that passing 0 was
equivalent to the current behaviour (no signal is sent), but after
checking the code again I see that it is not the case.


-- 
Eugene Syromyatnikov
mailto:evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:esyr@jabber.{ru|org}
--
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: [man-pages PATCH 2/5] s390_runtime_instr.2: document the removal of the second argument

[Eugene Syromyatnikov]

On Wed, Jan 31, 2018 at 7:20 AM, Heiko Carstens
<heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
> On Mon, Jan 22, 2018 at 01:16:25PM +0000, Eugene Syromyatnikov wrote:
>> On Sat, Jan 20, 2018 at 11:41 AM, Heiko Carstens
>> <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
>> > If you now document the above people will start using the system call with
>> > only one parameter which isn't backwards compatible.
>> >
>> > I'd rather add the second parameter again to the system call so that code
>> > stays backwards compatible.
>>
>> Well, it ought to be documented somehow, especially if the syscall
>> parameter will be added back, as there could be situation where
>> application gets successful return code for the call non-zero value of
>> the second argument and gets no signals as it is the one of the kernel
>> releases where this parameter was removed. I can update the patch to
>> reflect this once the patch that returns the second argument reaches
>> the kernel tree.
>
> So, I think something like the below should be ok:
>
> From 6c7e2113c62fbb95662fba03f7fa298f4b737c1f Mon Sep 17 00:00:00 2001
> From: Heiko Carstens <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org>
> Date: Wed, 31 Jan 2018 08:15:31 +0100
> Subject: [PATCH] s390_runtime_instr.2: document signum argument behavior
>  change
>
> Document that the signum argument is ignored in newer kernels, but
> that user space should pass a valid real-time signal number for
> backwards compatibility.
>
> Signed-off-by: Heiko Carstens <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org>
> ---
>  man2/s390_runtime_instr.2 | 24 ++++++++++++++++++------
>  1 file changed, 18 insertions(+), 6 deletions(-)
>
> diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
> index 18c2c0763eed..d5790e10f222 100644
> --- a/man2/s390_runtime_instr.2
> +++ b/man2/s390_runtime_instr.2
> @@ -47,10 +47,9 @@ argument controls whether run-time instrumentation is started
>  .PP
>  The
>  .IR signum
> -argument specifies the number of a real-time signal.
> -The real-time signal is sent to the thread if the run-time instrumentation
> -buffer is full or if the run-time-instrumentation-halted interrupt
> -occurred.
> +argument specifies the number of a real-time signal. This argument has no
> +effect, since support for signalling was never used and kernel support was
> +removed.
>  .SH RETURN VALUE
>  On success,
>  .BR s390_runtime_instr ()
> @@ -67,9 +66,16 @@ is set to one of the error codes listed below.
>  .B EINVAL
>  The value specified in
>  .IR command
> -is not a valid command or the value specified in
> +is not a valid command.
> +.TP
> +.B EINVAL
> +The value specified in
>  .IR signum
> -is not a real-time signal number.
> +is not a real-time signal number. With Linux 4.4 and newer kernel versions,
> +the
> +.IR signum
> +argument has no effect, so that an invalid signal number will not result in an
> +error.
>  .TP
>  .B ENOMEM
>  Allocating memory for the run-time instrumentation control block failed.
> @@ -85,6 +91,12 @@ The run-time instrumentation facility is available beginning with System z EC12.
>  Glibc does not provide a wrapper for this system call, use
>  .BR syscall (2)
>  to call it.
> +.PP
> +Support for signalling was removed with Linux 4.4. With Linux 4.4
> +also the check if
> +.IR signum
> +is a valid real-time signal was removed. For backwards compatibility with old
> +kernels it is recommended to pass a valid real-time signal number.
>  .SH SEE ALSO
>  .BR syscall (2),
>  .BR signal (7)
> --
> 2.13.5
>

Acked-by: Eugene Syromyatnikov <evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>

-- 
Eugene Syromyatnikov
mailto:evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:esyr@jabber.{ru|org}
--
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