]>
Commit | Line | Data |
---|---|---|
c336d6e0 QH |
1 | .\" Copyright IBM Corp. 2017 |
2 | .\" Author: QingFeng Hao <haoqf@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 | .\" | |
8538a62b | 25 | .TH S390_STHYI 2 2018-02-02 "Linux Programmer's Manual" |
c336d6e0 QH |
26 | .SH NAME |
27 | s390_sthyi \- emulate STHYI instruction | |
28 | .SH SYNOPSIS | |
29 | .nf | |
30 | .B #include <asm/unistd.h> | |
31 | .PP | |
0d757f49 | 32 | .BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer ", |
c336d6e0 QH |
33 | .BI " uint64_t *" return_code ", unsigned long " flags "); |
34 | .fi | |
35 | .SH DESCRIPTION | |
36 | The | |
37 | .BR s390_sthyi () | |
38 | system call emulates the STHYI (Store Hypervisor Information) instruction. | |
a6ae6344 MK |
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 | |
c336d6e0 QH |
42 | other metrics. |
43 | .PP | |
44 | The | |
45 | .I function_code | |
46 | argument indicates which function to perform. | |
47 | The following code(s) are supported: | |
5057157b MK |
48 | .TP |
49 | 0 | |
c336d6e0 QH |
50 | Return CP (Central Processor) and IFL (Integrated Facility for Linux) |
51 | capacity information. | |
52 | .PP | |
53 | The | |
2cd9bbfa | 54 | .I resp_buffer |
a6ae6344 | 55 | argument specifies the address of a response buffer. |
b2c7f822 ES |
56 | When the |
57 | .I function_code | |
58 | is 0, it has to be one page (4K) in size. | |
a6ae6344 MK |
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. | |
c336d6e0 QH |
62 | .PP |
63 | The | |
64 | .I return_code | |
a6ae6344 MK |
65 | argument stores the return code of the STHYI instruction, |
66 | using one of the following values: | |
5057157b | 67 | .TP 8 |
ba6f9c34 | 68 | 0 |
5057157b MK |
69 | Success. |
70 | .TP | |
ba6f9c34 | 71 | 4 |
5057157b MK |
72 | Unsupported function code. |
73 | .PP | |
74 | For further details about | |
75 | .IR return_code , | |
76 | .IR function_code , | |
77 | and | |
0d757f49 | 78 | .IR resp_buffer , |
4f684d1d | 79 | see the reference given in NOTES. |
c336d6e0 QH |
80 | .PP |
81 | The | |
82 | .I flags | |
83 | argument is provided to allow for future extensions and currently | |
ba6f9c34 | 84 | must be set to 0. |
c336d6e0 | 85 | .SH RETURN VALUE |
9224781f | 86 | On success (that is: emulation succeeded), the return value of |
c336d6e0 QH |
87 | .BR s390_sthyi () |
88 | matches the condition code of the STHYI instructions, which is a value | |
9224781f MK |
89 | in the range [0..3]. |
90 | A return value of 0 indicates that CPU capacity information is stored in | |
0d757f49 | 91 | .IR *resp_buffer . |
9224781f | 92 | A return value of 3 indicates "unsupported function code" and the content of |
0d757f49 | 93 | .IR *resp_buffer |
9224781f MK |
94 | is unchanged. |
95 | The return values 1 and 2 are reserved. | |
c336d6e0 | 96 | .PP |
ba6f9c34 | 97 | On error, \-1 is returned, and |
c336d6e0 QH |
98 | .IR errno |
99 | is set appropriately. | |
100 | .SH ERRORS | |
101 | .TP | |
c336d6e0 QH |
102 | .B EFAULT |
103 | The value specified in | |
2cd9bbfa | 104 | .I resp_buffer |
c336d6e0 QH |
105 | or |
106 | .I return_code | |
107 | is not a valid address. | |
108 | .TP | |
763235c5 MK |
109 | .B EINVAL |
110 | The value specified in | |
111 | .I flags | |
112 | is nonzero. | |
113 | .TP | |
c336d6e0 QH |
114 | .B ENOMEM |
115 | Allocating memory for handling the CPU capacity information failed. | |
763235c5 MK |
116 | .TP |
117 | .B EOPNOTSUPP | |
118 | The value specified in | |
2cd9bbfa | 119 | .I function_code |
763235c5 | 120 | is not valid. |
c336d6e0 QH |
121 | .SH VERSIONS |
122 | This system call is available since Linux 4.15. | |
123 | .SH CONFORMING TO | |
124 | This Linux-specific system call is available only on the s390 architecture. | |
c336d6e0 QH |
125 | .SH NOTES |
126 | Glibc does not provide a wrapper for this system call, use | |
127 | .BR syscall (2) | |
128 | to call it. | |
4f684d1d MK |
129 | .PP |
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 | |
b2c7f822 | 132 | the documentation page |
4f684d1d | 133 | .UE . |
b2c7f822 ES |
134 | .PP |
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. | |
138 | .PP | |
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. | |
c336d6e0 QH |
141 | .SH SEE ALSO |
142 | .BR syscall (2) |