man page for s390_runtime_instr syscall
Hi Michael,
I've written a man page for the s390_runtime_instr syscall which was merged with 3.7 (e4b8b3f). Now the question is if you would like to include it in the man-pages although it is completely s390 specific and wont be available on any other arch? Or should it go into a different package?
thanks, Jan
--
s390_runtime_instr.2 new file +73 -0
@@ -0,0 +1,73 @@ +.\" Copyright IBM Corp. 2012 +.\" Author: Jan Glauber <[email protected]> +.\" +.TH S390_RUNTIME_INSTR 2 2012-10-09 "Linux Programmer's Manual" +.SH NAME +s390_runtime_instr \- enable/disable s390 CPU runtime instrumentation +.SH SYNOPSIS +.nf +.B #include <asm/runtime_instr.h> + +.BI "int s390_runtime_instr(int " command ", int " signum "); +.fi + +.SH DESCRIPTION +The +.BR s390_runtime_instr () +system call starts or stops CPU runtime instrumentation for the current thread. + +The +.IR command +argument controls whether runtime instumentation is started +( 1 ) or stopped ( 2 ) for the current thread. + +The +.IR signum +argument specifies the number of a real-time signal. The +real-time signal is sent to the thread if the runtime instrumentation +buffer is full or if the runtime-instrumentation-halted interrupt +occured. + +.SH RETURN VALUE +On success +.BR s390_runtime_instr () +returns 0 and enables the thread for +runtime instrumentation by assigning the thread a default runtime +instrumentation control block. The caller can then read and modify the +control block and start the runtime instrumentation. On error, -1 is +returned and +.IR errno +is set to one of the error codes listed below. + +.SH ERRORS +.TP +.B EOPNOTSUPP +The runtime instrumentation facility is not available. +.TP +.B EINVAL +The value specified in +.IR command +is not a valid command or the value specified in +.IR signum +is not a real-time signal number. +.TP +.B ENOMEM +Allocating memory for the runtime instrumentation control block +failed. + +.SH VERSIONS +This system call is available since Linux 3.7. + +.SH CONFORMING TO +This system call +is only available on the s390 architecture. The runtime instrumentation facility is available +beginning with System z EC12. + +.SH NOTES +Glibc does not provide a wrapper for this system call, use +.BR syscall (2) +to call it. + +.SH SEE ALSO +.BR signal (7), +.BR syscall (2)
Hello Jan,
Quoted 5 lines · Jan Glauber
Hi Michael,
I've written a man page for the
s390_runtime_instrsyscall which was merged with 3.7 (e4b8b3f). Now the question is if you would like to include it in the man-pages although it is completely s390 specific
and wont be available on any other arch? Or should it go into a
Quoted 1 line
different package?
Thanks for this page. The man-pages package is the right place for it, but a few things need fixing. Could you see below and resubmit please?
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 line 2
Quoted 5 lines
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +2
-0@@ -0,0 +1,73 @@ +.\" Copyright IBM Corp. 2012 +.\" Author: Jan Glauber <[email protected]>
You have provided no license here. Can you please add one. Please see
http://www.kernel.org/doc/man-pages/licenses.html. (My preference is the "verbatim" license, but others are of course possible.)
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 line 4
Quoted 2 lines
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +2
-0+.\" +.TH S390_RUNTIME_INSTR 2 2012-10-09 "Linux Programmer's Manual"
Update the date here.
Quoted 7 lines
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +7
-0+.SH NAME +s390_runtime_instr \- enable/disable s390 CPU runtime instrumentation +.SH SYNOPSIS +.nf +.B #include <asm/runtime_instr.h> + +.BI "int s390_runtime_instr(int " command ", int " signum ");
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 line 21
Quoted 10 lines
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +10
-0+.fi + +.SH DESCRIPTION +The +.BR s390_runtime_instr () +system call starts or stops CPU runtime instrumentation for the current thread. + +The +.IR command +argument controls whether runtime instumentation is started
Spelling: instrumentation
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 line 26
Quoted 5 lines
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +5
-0+( 1 ) or stopped ( 2 ) for the current thread. + +The +.IR signum +argument specifies the number of a real-time signal. The
Please start new sentences on a new source line.
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 line 29
Quoted 3 lines
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +3
-0+real-time signal is sent to the thread if the runtime instrumentation +buffer is full or if the runtime-instrumentation-halted interrupt +occured.
Spelling: occurred.
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 line 36
Quoted 7 lines
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +7
-0+ +.SH RETURN VALUE +On success +.BR s390_runtime_instr () +returns 0 and enables the thread for +runtime instrumentation by assigning the thread a default runtime +instrumentation control block. The caller can then read and modify the
Start new sentence on a new source line.
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 line 37
Quoted 1 line
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +1
-0+control block and start the runtime instrumentation. On error, -1 is
Start new sentence on a new source line.
Quoted 15 lines
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +15
-0+returned and +.IR errno +is set to one of the error codes listed below. + +.SH ERRORS +.TP +.B EOPNOTSUPP +The runtime instrumentation facility is not available. +.TP +.B EINVAL +The value specified in +.IR command +is not a valid command or the value specified in +.IR signum +is not a real-time signal number.
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 line 62
Quoted 10 lines
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +10
-0+.TP +.B ENOMEM +Allocating memory for the runtime instrumentation control block +failed. + +.SH VERSIONS +This system call is available since Linux 3.7. + +.SH CONFORMING TO +This system call
This Linux-specific system call
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 line 63
Quoted 1 line
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +1
-0+is only available on the s390 architecture. The runtime instrumentation facility is available
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 line 69
Quoted 6 lines
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +6
-0+beginning with System z EC12. + +.SH NOTES +Glibc does not provide a wrapper for this system call, use +.BR syscall (2) +to call it.
Somewhere around here it would be nice to have some notes on how one uses this RI feature. The commit e4b8b3f33fcaa0ed6e6b5482a606091d8cd20beb has a bit of info. I'd suggest including that info in the page, with (possibly) an example.
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 line 73
Quoted 4 lines
s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200 renamed from dev/null 2012-12-04 10:52:46.657720288 +0100 +4
-0+ +.SH SEE ALSO +.BR signal (7), +.BR syscall (2)
Order entries here by section number.
Thanks,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Author of "The Linux Programming Interface"; http://man7.org/tlpi/
Quoted 2 lines · Michael Kerrisk (man-pages)
Thanks for this page. The man-pages package is the right place for it, but a few things need fixing. Could you see below and resubmit please?
I've addressed all of your comments but for the example. We could add the example later when the official documentation is released which did not yet happen.
thanks, Jan
s390_runtime_instr.2 new file +91 -0
@@ -0,0 +1,91 @@ +.\" Copyright IBM Corp. 2012 +.\" Author: Jan Glauber <[email protected]> +.\" Copyright (c) 2012, IBM Corp. +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" <http://www.gnu.org/licenses/>. +.TH S390_RUNTIME_INSTR 2 2012-12-17 "Linux Programmer's Manual" +.SH NAME +s390_runtime_instr \- enable/disable s390 CPU runtime instrumentation +.SH SYNOPSIS +.nf +.B #include <asm/runtime_instr.h> + +.BI "int s390_runtime_instr(int " command ", int " signum "); +.fi + +.SH DESCRIPTION +The +.BR s390_runtime_instr () +system call starts or stops CPU runtime instrumentation for the current thread. + +The +.IR command +argument controls whether runtime instrumentation is started +( 1 ) or stopped ( 2 ) for the current thread. + +The +.IR signum +argument specifies the number of a real-time signal. +The real-time signal is sent to the thread if the runtime instrumentation +buffer is full or if the runtime-instrumentation-halted interrupt +occurred. + +.SH RETURN VALUE +On success +.BR s390_runtime_instr () +returns 0 and enables the thread for +runtime instrumentation by assigning the thread a default runtime +instrumentation control block. +The caller can then read and modify the control block and start the runtime +instrumentation. +On error, -1 is returned and +.IR errno +is set to one of the error codes listed below. + +.SH ERRORS +.TP +.B EOPNOTSUPP +The runtime instrumentation facility is not available. +.TP +.B EINVAL +The value specified in +.IR command +is not a valid command or the value specified in +.IR signum +is not a real-time signal number. +.TP +.B ENOMEM +Allocating memory for the runtime instrumentation control block failed. + +.SH VERSIONS +This system call is available since Linux 3.7. + +.SH CONFORMING TO +This Linux-specific system call is only available on the s390 architecture. +The runtime instrumentation facility is available beginning with System z EC12. + +.SH NOTES +Glibc does not provide a wrapper for this system call, use +.BR syscall (2) +to call it. + +.SH SEE ALSO +.BR syscall (2), +.BR signal (7)
Hello Jan,
Quoted 7 lines · Jan Glauber
Quoted 2 lines · Michael Kerrisk (man-pages)
Thanks for this page. The man-pages package is the right place for it, but a few things need fixing. Could you see below and resubmit please?
I've addressed all of your comments but for the example. We could add the example later when the official documentation is released which did not yet happen.
Okay. I've applied your patch for man-pages-3.45. Thank you for sending in this new page.
Cheers,
Michael
Quoted 97 lines
s390_runtime_instr.2 2012-12-17 12:55:20.942872393 +0100 renamed from dev/null 2012-12-17 11:58:11.967183723 +0100 +91
-0@@ -0,0 +1,91 @@ +.\" Copyright IBM Corp. 2012 +.\" Author: Jan Glauber <[email protected]> +.\" Copyright (c) 2012, IBM Corp. +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" <http://www.gnu.org/licenses/>. +.TH S390_RUNTIME_INSTR 2 2012-12-17 "Linux Programmer's Manual" +.SH NAME +s390_runtime_instr \- enable/disable s390 CPU runtime instrumentation +.SH SYNOPSIS +.nf +.B #include <asm/runtime_instr.h> + +.BI "int s390_runtime_instr(int " command ", int " signum "); +.fi + +.SH DESCRIPTION +The +.BR s390_runtime_instr () +system call starts or stops CPU runtime instrumentation for the current thread. + +The +.IR command +argument controls whether runtime instrumentation is started +( 1 ) or stopped ( 2 ) for the current thread. + +The +.IR signum +argument specifies the number of a real-time signal. +The real-time signal is sent to the thread if the runtime instrumentation +buffer is full or if the runtime-instrumentation-halted interrupt +occurred. + +.SH RETURN VALUE +On success +.BR s390_runtime_instr () +returns 0 and enables the thread for +runtime instrumentation by assigning the thread a default runtime +instrumentation control block. +The caller can then read and modify the control block and start the runtime +instrumentation. +On error, -1 is returned and +.IR errno +is set to one of the error codes listed below. + +.SH ERRORS +.TP +.B EOPNOTSUPP +The runtime instrumentation facility is not available. +.TP +.B EINVAL +The value specified in +.IR command +is not a valid command or the value specified in +.IR signum +is not a real-time signal number. +.TP +.B ENOMEM +Allocating memory for the runtime instrumentation control block failed. + +.SH VERSIONS +This system call is available since Linux 3.7. + +.SH CONFORMING TO +This Linux-specific system call is only available on the s390 architecture. +The runtime instrumentation facility is available beginning with System z EC12. + +.SH NOTES +Glibc does not provide a wrapper for this system call, use +.BR syscall (2) +to call it. + +.SH SEE ALSO +.BR syscall (2), +.BR signal (7)
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Author of "The Linux Programming Interface"; http://man7.org/tlpi/