| .\" Copyright (c) IBM Corp. 2012 |
| .\" Author: Jan Glauber <jang@linux.vnet.ibm.com> |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" 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/>. |
| .\" %%%LICENSE_END |
| .\" |
| .TH S390_RUNTIME_INSTR 2 2021-03-22 "Linux Programmer's Manual" |
| .SH NAME |
| s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation |
| .SH SYNOPSIS |
| .nf |
| .B #include <asm/runtime_instr.h> |
| .PP |
| .BI "int s390_runtime_instr(int " command ", int " signum ");" |
| .fi |
| .PP |
| .IR Note : |
| There is no glibc wrapper for this system call; see NOTES. |
| .SH DESCRIPTION |
| The |
| .BR s390_runtime_instr () |
| system call starts or stops CPU run-time instrumentation for the |
| calling thread. |
| .PP |
| The |
| .IR command |
| argument controls whether run-time instrumentation is started |
| .RB ( S390_RUNTIME_INSTR_START , |
| 1) or stopped |
| .RB ( S390_RUNTIME_INSTR_STOP , |
| 2) for the calling thread. |
| .PP |
| The |
| .IR signum |
| argument specifies the number of a real-time signal. |
| This argument was used to specify a signal number that should be delivered |
| to the thread if the run-time instrumentation buffer was full or if |
| the run-time-instrumentation-halted interrupt had occurred. |
| This feature was never used, |
| and in Linux 4.4 support for this feature was removed; |
| .\" commit b38feccd663b55ab07116208b68e1ffc7c3c7e78 |
| thus, in current kernels, this argument is ignored. |
| .SH RETURN VALUE |
| On success, |
| .BR s390_runtime_instr () |
| returns 0 and enables the thread for |
| run-time instrumentation by assigning the thread a default run-time |
| instrumentation control block. |
| The caller can then read and modify the control block and start the run-time |
| instrumentation. |
| On error, \-1 is returned and |
| .IR errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EINVAL |
| The value specified in |
| .IR command |
| is not a valid command. |
| .TP |
| .B EINVAL |
| The value specified in |
| .IR signum |
| is not a real-time signal number. |
| From Linux 4.4 onwards, 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. |
| .TP |
| .B EOPNOTSUPP |
| The run-time instrumentation facility is not available. |
| .SH VERSIONS |
| This system call is available since Linux 3.7. |
| .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. |
| .SH NOTES |
| Glibc does not provide a wrapper for this system call; call it using |
| .BR syscall (2) |
| .PP |
| The |
| .I asm/runtime_instr.h |
| header file is available |
| .\" commit df2f815a7df7edb5335a3bdeee6a8f9f6f9c35c4 |
| since Linux 4.16. |
| .PP |
| Starting with Linux 4.4, |
| support for signalling was removed, as was the check whether |
| .IR signum |
| is a valid real-time signal. |
| For backwards compatibility with older kernels, it is recommended to pass |
| a valid real-time signal number in |
| .I signum |
| and install a handler for that signal. |
| .SH SEE ALSO |
| .BR syscall (2), |
| .BR signal (7) |