1 .\" Copyright IBM Corp. 2017
2 .\" Author: QingFeng Hao <haoqf@linux.vnet.ibm.com>
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.
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.
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.
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/>.
25 .TH S390_STHYI 2 2020-04-11 "Linux Programmer's Manual"
27 s390_sthyi \- emulate STHYI instruction
30 .B #include <asm/unistd.h>
32 .BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer ",
33 .BI " uint64_t *" return_code ", unsigned long " flags ");
38 system call emulates the STHYI (Store Hypervisor Information) instruction.
39 It provides hardware resource information for the machine and its
40 virtualization levels.
41 This includes CPU type and capacity, as well as the machine model and
46 argument indicates which function to perform.
47 The following code(s) are supported:
50 Return CP (Central Processor) and IFL (Integrated Facility for Linux)
55 argument specifies the address of a response buffer.
58 is 0, the buffer must be one page (4K) in size.
59 If the system call returns 0,
60 the response buffer will be filled with CPU capacity information.
61 Otherwise, the response buffer's content is unchanged.
65 argument stores the return code of the STHYI instruction,
66 using one of the following values:
72 Unsupported function code.
74 For further details about
79 see the reference given in NOTES.
83 argument is provided to allow for future extensions and currently
86 On success (that is: emulation succeeded), the return value of
88 matches the condition code of the STHYI instructions, which is a value
90 A return value of 0 indicates that CPU capacity information is stored in
92 A return value of 3 indicates "unsupported function code" and the content of
95 The return values 1 and 2 are reserved.
97 On error, \-1 is returned, and
103 The value specified in
107 is not a valid address.
110 The value specified in
115 Allocating memory for handling the CPU capacity information failed.
118 The value specified in
122 This system call is available since Linux 4.15.
124 This Linux-specific system call is available only on the s390 architecture.
126 Glibc does not provide a wrapper for this system call, use
130 For details of the STHYI instruction, see
131 .UR https://www.ibm.com\:/support\:/knowledgecenter\:/SSB27U_6.3.0\:/com.ibm.zvm.v630.hcpb4\:/hcpb4sth.htm
132 the documentation page
135 When the system call interface is used, the response buffer doesn't
136 have to fulfill alignment requirements described in the STHYI
137 instruction definition.
139 The kernel caches the response (for up to one second, as of Linux 4.16).
140 Subsequent system call invocations may return the cached response.