]>
Commit | Line | Data |
---|---|---|
c336d6e0 QH |
1 | .\" Copyright IBM Corp. 2017 |
2 | .\" Author: QingFeng Hao <haoqf@linux.vnet.ibm.com> | |
3 | .\" | |
e4a74ca8 | 4 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
c336d6e0 | 5 | .\" |
4c1c5274 | 6 | .TH s390_sthyi 2 (date) "Linux man-pages (unreleased)" |
c336d6e0 QH |
7 | .SH NAME |
8 | s390_sthyi \- emulate STHYI instruction | |
f76a2b19 AC |
9 | .SH LIBRARY |
10 | Standard C library | |
8fc3b2cf | 11 | .RI ( libc ", " \-lc ) |
c336d6e0 QH |
12 | .SH SYNOPSIS |
13 | .nf | |
c6450cf8 | 14 | .BR "#include <asm/sthyi.h>" " /* Definition of " STHYI_* " constants */" |
d4d00668 AC |
15 | .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" |
16 | .B #include <unistd.h> | |
c336d6e0 | 17 | .PP |
d4d00668 AC |
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 ); | |
c336d6e0 | 21 | .fi |
632d1152 GC |
22 | .PP |
23 | .IR Note : | |
d4d00668 | 24 | glibc provides no wrapper for |
9a52fd2e | 25 | .BR s390_sthyi (), |
d4d00668 AC |
26 | necessitating the use of |
27 | .BR syscall (2). | |
c336d6e0 QH |
28 | .SH DESCRIPTION |
29 | The | |
30 | .BR s390_sthyi () | |
31 | system call emulates the STHYI (Store Hypervisor Information) instruction. | |
a6ae6344 MK |
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 | |
c336d6e0 QH |
35 | other metrics. |
36 | .PP | |
37 | The | |
38 | .I function_code | |
39 | argument indicates which function to perform. | |
40 | The following code(s) are supported: | |
5057157b | 41 | .TP |
c6450cf8 | 42 | .B STHYI_FC_CP_IFL_CAP |
c336d6e0 QH |
43 | Return CP (Central Processor) and IFL (Integrated Facility for Linux) |
44 | capacity information. | |
45 | .PP | |
46 | The | |
2cd9bbfa | 47 | .I resp_buffer |
a6ae6344 | 48 | argument specifies the address of a response buffer. |
b2c7f822 ES |
49 | When the |
50 | .I function_code | |
c6450cf8 AC |
51 | is |
52 | .BR STHYI_FC_CP_IFL_CAP , | |
53 | the buffer must be one page (4K) in size. | |
a6ae6344 MK |
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. | |
c336d6e0 QH |
57 | .PP |
58 | The | |
59 | .I return_code | |
a6ae6344 MK |
60 | argument stores the return code of the STHYI instruction, |
61 | using one of the following values: | |
0019177e | 62 | .TP |
ba6f9c34 | 63 | 0 |
5057157b MK |
64 | Success. |
65 | .TP | |
ba6f9c34 | 66 | 4 |
5057157b MK |
67 | Unsupported function code. |
68 | .PP | |
69 | For further details about | |
70 | .IR return_code , | |
71 | .IR function_code , | |
72 | and | |
0d757f49 | 73 | .IR resp_buffer , |
4f684d1d | 74 | see the reference given in NOTES. |
c336d6e0 QH |
75 | .PP |
76 | The | |
77 | .I flags | |
78 | argument is provided to allow for future extensions and currently | |
ba6f9c34 | 79 | must be set to 0. |
c336d6e0 | 80 | .SH RETURN VALUE |
9224781f | 81 | On success (that is: emulation succeeded), the return value of |
c336d6e0 QH |
82 | .BR s390_sthyi () |
83 | matches the condition code of the STHYI instructions, which is a value | |
9224781f MK |
84 | in the range [0..3]. |
85 | A return value of 0 indicates that CPU capacity information is stored in | |
0d757f49 | 86 | .IR *resp_buffer . |
9224781f | 87 | A return value of 3 indicates "unsupported function code" and the content of |
1ae6b2c7 | 88 | .I *resp_buffer |
9224781f MK |
89 | is unchanged. |
90 | The return values 1 and 2 are reserved. | |
c336d6e0 | 91 | .PP |
ba6f9c34 | 92 | On error, \-1 is returned, and |
1ae6b2c7 | 93 | .I errno |
f6a4078b | 94 | is set to indicate the error. |
c336d6e0 QH |
95 | .SH ERRORS |
96 | .TP | |
c336d6e0 QH |
97 | .B EFAULT |
98 | The value specified in | |
2cd9bbfa | 99 | .I resp_buffer |
c336d6e0 QH |
100 | or |
101 | .I return_code | |
102 | is not a valid address. | |
103 | .TP | |
763235c5 MK |
104 | .B EINVAL |
105 | The value specified in | |
106 | .I flags | |
107 | is nonzero. | |
108 | .TP | |
c336d6e0 QH |
109 | .B ENOMEM |
110 | Allocating memory for handling the CPU capacity information failed. | |
763235c5 MK |
111 | .TP |
112 | .B EOPNOTSUPP | |
113 | The value specified in | |
2cd9bbfa | 114 | .I function_code |
763235c5 | 115 | is not valid. |
c336d6e0 QH |
116 | .SH VERSIONS |
117 | This system call is available since Linux 4.15. | |
3113c7f3 | 118 | .SH STANDARDS |
c336d6e0 | 119 | This Linux-specific system call is available only on the s390 architecture. |
c336d6e0 | 120 | .SH NOTES |
4f684d1d MK |
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 | |
b2c7f822 | 123 | the documentation page |
4f684d1d | 124 | .UE . |
b2c7f822 ES |
125 | .PP |
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 | .PP | |
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. | |
c336d6e0 QH |
132 | .SH SEE ALSO |
133 | .BR syscall (2) |