[man-pages PATCH 1/5] s390_runtime_instr.2: note that runtime_instr.h is not a public header

[man-pages PATCH 1/5] s390_runtime_instr.2: note that runtime_instr.h is not a public header

[Eugene Syromyatnikov]

For some reason, runtime_instr.h is inside arch/s390/include/asm/ and
not arch/s390/include/uapi/asm/, so it's not readily available to the
user space programs. Let's reflect it.

* man2/s390_runtime_instr.2 (.SH SYNOPSYS): Comment out the #include
<asm/runtime_instr.h> statement.
(.SH NOTES): Note the existence and presence of runtime_instr.h header
inside the Linux kernel source tree.
---
 man2/s390_runtime_instr.2 | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
index 18c2c07..f979692 100644
--- a/man2/s390_runtime_instr.2
+++ b/man2/s390_runtime_instr.2
@@ -27,8 +27,9 @@
 s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation
 .SH SYNOPSIS
 .nf
-.B #include <asm/runtime_instr.h>
-.PP
+.\" This header never had been a part of uapi as of 4.15
+.\" .B #include <asm/runtime_instr.h>
+.\" .PP
 .BI "int s390_runtime_instr(int " command ", int " signum ");
 .fi
 .SH DESCRIPTION
@@ -85,6 +86,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
+Kernel's header
+.B arch/s390/include/asm/runtime_instr.h
+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.
 .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 1/5] s390_runtime_instr.2: note that runtime_instr.h is not a public header

[Heiko Carstens]

On Sun, Jan 14, 2018 at 07:56:22PM +0100, Eugene Syromyatnikov wrote:
> For some reason, runtime_instr.h is inside arch/s390/include/asm/ and
> not arch/s390/include/uapi/asm/, so it's not readily available to the
> user space programs. Let's reflect it.
> 
> * man2/s390_runtime_instr.2 (.SH SYNOPSYS): Comment out the #include
> <asm/runtime_instr.h> statement.
> (.SH NOTES): Note the existence and presence of runtime_instr.h header
> inside the Linux kernel source tree.
> ---
>  man2/s390_runtime_instr.2 | 11 +++++++++--
>  1 file changed, 9 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
> index 18c2c07..f979692 100644
> --- a/man2/s390_runtime_instr.2
> +++ b/man2/s390_runtime_instr.2
> @@ -27,8 +27,9 @@
>  s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation
>  .SH SYNOPSIS
>  .nf
> -.B #include <asm/runtime_instr.h>
> -.PP
> +.\" This header never had been a part of uapi as of 4.15
> +.\" .B #include <asm/runtime_instr.h>
> +.\" .PP
>  .BI "int s390_runtime_instr(int " command ", int " signum ");
>  .fi
>  .SH DESCRIPTION
> @@ -85,6 +86,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
> +Kernel's header
> +.B arch/s390/include/asm/runtime_instr.h
> +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.

IMHO we shouldn't document the file name of a kernel header that is not
exported. It's name and location can change anytime. I will move the kernel
header file to the uapi directory where it should have been since a long
time.
Thanks for reporting!

--
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 1/5] s390_runtime_instr.2: note that runtime_instr.h is not a public header

[Eugene Syromyatnikov]

On Sat, Jan 20, 2018 at 11:28 AM, Heiko Carstens
<heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
> IMHO we shouldn't document the file name of a kernel header that is not
> exported. It's name and location can change anytime. I will move the kernel
> header file to the uapi directory where it should have been since a long
> time.

In that case, I think it could be rephrased to something like "the
header asm/runtime_instr.h is available for the userspace programs
since Linux 4.15, before that it was located in
arch/s390/include/asm/runtime_instr.h in the kernel's source tree", as
man-pages project (as I understood) tends to reference places in
kernel's source tree if it is deemed useful; it is usually applied to
documentation files, however, although they also have tendency to
migrate over time.

-- 
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 1/5] s390_runtime_instr.2: note that runtime_instr.h is not a public header

[Heiko Carstens]

On Mon, Jan 22, 2018 at 01:11:19PM +0000, Eugene Syromyatnikov wrote:
> On Sat, Jan 20, 2018 at 11:28 AM, Heiko Carstens
> <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
> > IMHO we shouldn't document the file name of a kernel header that is not
> > exported. It's name and location can change anytime. I will move the kernel
> > header file to the uapi directory where it should have been since a long
> > time.
> 
> In that case, I think it could be rephrased to something like "the
> header asm/runtime_instr.h is available for the userspace programs
> since Linux 4.15, before that it was located in
> arch/s390/include/asm/runtime_instr.h in the kernel's source tree", as
> man-pages project (as I understood) tends to reference places in
> kernel's source tree if it is deemed useful; it is usually applied to
> documentation files, however, although they also have tendency to
> migrate over time.

Yes, that's ok. However moving the header file to uapi is not going to
happen before kernel version 4.16.

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