man2/s390_runtime_instr.2

   1 .\" Copyright (c) IBM Corp. 2012
   2 .\" Author: Jan Glauber <jang@linux.vnet.ibm.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH S390_RUNTIME_INSTR 2 2021-03-22 "Linux Programmer's Manual"
  26 .SH NAME
  27 s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation
  28 .SH SYNOPSIS
  29 .nf
  30 .BR "#include <asm/runtime_instr.h>" " /* Definition of " S390_* " constants */"
  31 .BR "#include <sys/syscall.h>" "       /* Definition of " SYS_* " constants */"
  32 .B #include <unistd.h>
  33 .PP
  34 .BI "int syscall(SYS_s390_runtime_instr, int " command ", int " signum );
  35 .fi
  36 .PP
  37 .IR Note :
  38 glibc provides no wrapper for
  39 .BR s390_runtime_instr (),
  40 necessitating the use of
  41 .BR syscall (2).
  42 .SH DESCRIPTION
  43 The
  44 .BR s390_runtime_instr ()
  45 system call starts or stops CPU run-time instrumentation for the
  46 calling thread.
  47 .PP
  48 The
  49 .IR command
  50 argument controls whether run-time instrumentation is started
  51 .RB ( S390_RUNTIME_INSTR_START ,
  52 1) or stopped
  53 .RB ( S390_RUNTIME_INSTR_STOP ,
  54 2) for the calling thread.
  55 .PP
  56 The
  57 .IR signum
  58 argument specifies the number of a real-time signal.
  59 This argument was used to specify a signal number that should be delivered
  60 to the thread if the run-time instrumentation buffer was full or if
  61 the run-time-instrumentation-halted interrupt had occurred.
  62 This feature was never used,
  63 and in Linux 4.4 support for this feature was removed;
  64 .\" commit b38feccd663b55ab07116208b68e1ffc7c3c7e78
  65 thus, in current kernels, this argument is ignored.
  66 .SH RETURN VALUE
  67 On success,
  68 .BR s390_runtime_instr ()
  69 returns 0 and enables the thread for
  70 run-time instrumentation by assigning the thread a default run-time
  71 instrumentation control block.
  72 The caller can then read and modify the control block and start the run-time
  73 instrumentation.
  74 On error, \-1 is returned and
  75 .IR errno
  76 is set to indicate the error.
  77 .SH ERRORS
  78 .TP
  79 .B EINVAL
  80 The value specified in
  81 .IR command
  82 is not a valid command.
  83 .TP
  84 .B EINVAL
  85 The value specified in
  86 .IR signum
  87 is not a real-time signal number.
  88 From Linux 4.4 onwards, the
  89 .IR signum
  90 argument has no effect,
  91 so that an invalid signal number will not result in an error.
  92 .TP
  93 .B ENOMEM
  94 Allocating memory for the run-time instrumentation control block failed.
  95 .TP
  96 .B EOPNOTSUPP
  97 The run-time instrumentation facility is not available.
  98 .SH VERSIONS
  99 This system call is available since Linux 3.7.
 100 .SH CONFORMING TO
 101 This Linux-specific system call is available only on the s390 architecture.
 102 The run-time instrumentation facility is available
 103 beginning with System z EC12.
 104 .SH NOTES
 105 The
 106 .I asm/runtime_instr.h
 107 header file is available
 108 .\" commit df2f815a7df7edb5335a3bdeee6a8f9f6f9c35c4
 109 since Linux 4.16.
 110 .PP
 111 Starting with Linux 4.4,
 112 support for signalling was removed, as was the check whether
 113 .IR signum
 114 is a valid real-time signal.
 115 For backwards compatibility with older kernels, it is recommended to pass
 116 a valid real-time signal number in
 117 .I signum
 118 and install a handler for that signal.
 119 .SH SEE ALSO
 120 .BR syscall (2),
 121 .BR signal (7)