Debian Codegraph @

upstream/debian-unstable/man2/s390_sthyi.2

raw
1 .\" Copyright 2017, International Business Machines Corp.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH s390_sthyi 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 s390_sthyi \- emulate STHYI instruction
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <asm/sthyi.h>" " /* Definition of " STHYI_* " constants */"
15 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
16 .B #include <unistd.h>
17 .P
18 .BI "int syscall(SYS_s390_sthyi, unsigned long " function_code ,
19 .BI " void *" resp_buffer ", uint64_t *" return_code ,
20 .BI " unsigned long " flags );
21 .fi
22 .P
23 .IR Note :
24 glibc provides no wrapper for
25 .BR s390_sthyi (),
26 necessitating the use of
27 .BR syscall (2).
28 .SH DESCRIPTION
29 The
30 .BR s390_sthyi ()
31 system call emulates the STHYI (Store Hypervisor Information) instruction.
32 It provides hardware resource information for the machine and its
33 virtualization levels.
34 This includes CPU type and capacity, as well as the machine model and
35 other metrics.
36 .P
37 The
38 .I function_code
39 argument indicates which function to perform.
40 The following code(s) are supported:
41 .TP
42 .B STHYI_FC_CP_IFL_CAP
43 Return CP (Central Processor) and IFL (Integrated Facility for Linux)
44 capacity information.
45 .P
46 The
47 .I resp_buffer
48 argument specifies the address of a response buffer.
49 When the
50 .I function_code
51 is
52 .BR STHYI_FC_CP_IFL_CAP ,
53 the buffer must be one page (4K) in size.
54 If the system call returns 0,
55 the response buffer will be filled with CPU capacity information.
56 Otherwise, the response buffer's content is unchanged.
57 .P
58 The
59 .I return_code
60 argument stores the return code of the STHYI instruction,
61 using one of the following values:
62 .TP
63 0
64 Success.
65 .TP
66 4
67 Unsupported function code.
68 .P
69 For further details about
70 .IR return_code ,
71 .IR function_code ,
72 and
73 .IR resp_buffer ,
74 see the reference given in NOTES.
75 .P
76 The
77 .I flags
78 argument is provided to allow for future extensions and currently
79 must be set to 0.
80 .SH RETURN VALUE
81 On success (that is: emulation succeeded), the return value of
82 .BR s390_sthyi ()
83 matches the condition code of the STHYI instructions, which is a value
84 in the range [0..3].
85 A return value of 0 indicates that CPU capacity information is stored in
86 .IR *resp_buffer .
87 A return value of 3 indicates "unsupported function code" and the content of
88 .I *resp_buffer
89 is unchanged.
90 The return values 1 and 2 are reserved.
91 .P
92 On error, \-1 is returned, and
93 .I errno
94 is set to indicate the error.
95 .SH ERRORS
96 .TP
97 .B EFAULT
98 The value specified in
99 .I resp_buffer
100 or
101 .I return_code
102 is not a valid address.
103 .TP
104 .B EINVAL
105 The value specified in
106 .I flags
107 is nonzero.
108 .TP
109 .B ENOMEM
110 Allocating memory for handling the CPU capacity information failed.
111 .TP
112 .B EOPNOTSUPP
113 The value specified in
114 .I function_code
115 is not valid.
116 .SH STANDARDS
117 Linux on s390.
118 .SH HISTORY
119 Linux 4.15.
120 .SH NOTES
121 For details of the STHYI instruction, see
122 .UR https:\://www.ibm.com\:/support\:/knowledgecenter\:/SSB27U_6.3.0\:/com.ibm.zvm.v630.hcpb4\:/hcpb4sth.htm
123 the documentation page
124 .UE .
125 .P
126 When the system call interface is used, the response buffer doesn't
127 have to fulfill alignment requirements described in the STHYI
128 instruction definition.
129 .P
130 The kernel caches the response (for up to one second, as of Linux 4.16).
131 Subsequent system call invocations may return the cached response.
132 .SH SEE ALSO
133 .BR syscall (2)