s390_runtime_instr(2)

1s390_runtime_instr(2)         System Calls Manual        s390_runtime_instr(2)
2
3
4

NAME

6       s390_runtime_instr - enable/disable s390 CPU run-time instrumentation
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <asm/runtime_instr.h> /* Definition of S390_* constants */
13       #include <sys/syscall.h>       /* Definition of SYS_* constants */
14       #include <unistd.h>
15
16       int syscall(SYS_s390_runtime_instr, int command, int signum);
17
18       Note: glibc provides no wrapper for s390_runtime_instr(), necessitating
19       the use of syscall(2).
20

DESCRIPTION

22       The s390_runtime_instr() system call starts or stops CPU  run-time  in‐
23       strumentation for the calling thread.
24
25       The  command  argument  controls  whether  run-time  instrumentation is
26       started  (S390_RUNTIME_INSTR_START,  1)  or  stopped  (S390_RUNTIME_IN‐
27       STR_STOP, 2) for the calling thread.
28
29       The  signum  argument specifies the number of a real-time signal.  This
30       argument was used to specify a signal number that should  be  delivered
31       to the thread if the run-time instrumentation buffer was full or if the
32       run-time-instrumentation-halted interrupt had occurred.   This  feature
33       was  never used, and in Linux 4.4 support for this feature was removed;
34       thus, in current kernels, this argument is ignored.
35

RETURN VALUE

37       On success, s390_runtime_instr() returns 0 and enables the  thread  for
38       run-time instrumentation by assigning the thread a default run-time in‐
39       strumentation control block.  The caller can then read and  modify  the
40       control  block and start the run-time instrumentation.  On error, -1 is
41       returned and errno is set to indicate the error.
42

ERRORS

44       EINVAL The value specified in command is not a valid command.
45
46       EINVAL The value specified in signum is not a real-time signal  number.
47              From  Linux  4.4  onwards, the signum argument has no effect, so
48              that an invalid signal number will not result in an error.
49
50       ENOMEM Allocating memory for the run-time instrumentation control block
51              failed.
52
53       EOPNOTSUPP
54              The run-time instrumentation facility is not available.
55

STANDARDS

57       Linux on s390.
58

HISTORY

60       Linux 3.7.  System z EC12.
61

NOTES

63       The asm/runtime_instr.h header file is available since Linux 4.16.
64
65       Starting with Linux 4.4, support for signalling was removed, as was the
66       check whether signum is a valid real-time signal.  For  backwards  com‐
67       patibility  with older kernels, it is recommended to pass a valid real-
68       time signal number in signum and install a handler for that signal.
69