| .\" Copyright IBM Corp. 2017 |
| .\" Author: QingFeng Hao <haoqf@linux.vnet.ibm.com> |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .\" |
| .TH S390_STHYI 2 2021-03-22 "Linux Programmer's Manual" |
| .SH NAME |
| s390_sthyi \- emulate STHYI instruction |
| .SH SYNOPSIS |
| .nf |
| .B #include <asm/unistd.h> |
| .PP |
| .BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer "," |
| .BI " uint64_t *" return_code ", unsigned long " flags ");" |
| .fi |
| .PP |
| .IR Note : |
| There is no glibc wrapper for this system call; see NOTES. |
| .SH DESCRIPTION |
| The |
| .BR s390_sthyi () |
| system call emulates the STHYI (Store Hypervisor Information) instruction. |
| It provides hardware resource information for the machine and its |
| virtualization levels. |
| This includes CPU type and capacity, as well as the machine model and |
| other metrics. |
| .PP |
| The |
| .I function_code |
| argument indicates which function to perform. |
| The following code(s) are supported: |
| .TP |
| 0 |
| Return CP (Central Processor) and IFL (Integrated Facility for Linux) |
| capacity information. |
| .PP |
| The |
| .I resp_buffer |
| argument specifies the address of a response buffer. |
| When the |
| .I function_code |
| is 0, the buffer must be one page (4K) in size. |
| If the system call returns 0, |
| the response buffer will be filled with CPU capacity information. |
| Otherwise, the response buffer's content is unchanged. |
| .PP |
| The |
| .I return_code |
| argument stores the return code of the STHYI instruction, |
| using one of the following values: |
| .TP |
| 0 |
| Success. |
| .TP |
| 4 |
| Unsupported function code. |
| .PP |
| For further details about |
| .IR return_code , |
| .IR function_code , |
| and |
| .IR resp_buffer , |
| see the reference given in NOTES. |
| .PP |
| The |
| .I flags |
| argument is provided to allow for future extensions and currently |
| must be set to 0. |
| .SH RETURN VALUE |
| On success (that is: emulation succeeded), the return value of |
| .BR s390_sthyi () |
| matches the condition code of the STHYI instructions, which is a value |
| in the range [0..3]. |
| A return value of 0 indicates that CPU capacity information is stored in |
| .IR *resp_buffer . |
| A return value of 3 indicates "unsupported function code" and the content of |
| .IR *resp_buffer |
| is unchanged. |
| The return values 1 and 2 are reserved. |
| .PP |
| On error, \-1 is returned, and |
| .IR errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| The value specified in |
| .I resp_buffer |
| or |
| .I return_code |
| is not a valid address. |
| .TP |
| .B EINVAL |
| The value specified in |
| .I flags |
| is nonzero. |
| .TP |
| .B ENOMEM |
| Allocating memory for handling the CPU capacity information failed. |
| .TP |
| .B EOPNOTSUPP |
| The value specified in |
| .I function_code |
| is not valid. |
| .SH VERSIONS |
| This system call is available since Linux 4.15. |
| .SH CONFORMING TO |
| This Linux-specific system call is available only on the s390 architecture. |
| .SH NOTES |
| Glibc does not provide a wrapper for this system call; call it using |
| .BR syscall (2) |
| .PP |
| For details of the STHYI instruction, see |
| .UR https://www.ibm.com\:/support\:/knowledgecenter\:/SSB27U_6.3.0\:/com.ibm.zvm.v630.hcpb4\:/hcpb4sth.htm |
| the documentation page |
| .UE . |
| .PP |
| When the system call interface is used, the response buffer doesn't |
| have to fulfill alignment requirements described in the STHYI |
| instruction definition. |
| .PP |
| The kernel caches the response (for up to one second, as of Linux 4.16). |
| Subsequent system call invocations may return the cached response. |
| .SH SEE ALSO |
| .BR syscall (2) |