1 files changed, 133 insertions, 0 deletions
diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2
new file mode 100644
index 0000000..9c6af82
--- /dev/null
+++ b/man2/s390_sthyi.2
@@ -0,0 +1,133 @@
+.\" Copyright IBM Corp. 2017
+.\" Author: QingFeng Hao <haoqf@linux.vnet.ibm.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH s390_sthyi 2 2023-03-30 "Linux man-pages 6.05.01"
+.SH NAME
+s390_sthyi \- emulate STHYI instruction
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <asm/sthyi.h>" "        /* Definition of " STHYI_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_s390_sthyi, unsigned long " function_code ,
+.BI "            void *" resp_buffer ", uint64_t *" return_code ,
+.BI "            unsigned long " flags );
+.fi
+.PP
+.IR Note :
+glibc provides no wrapper for
+.BR s390_sthyi (),
+necessitating the use of
+.BR syscall (2).
+.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
+.B STHYI_FC_CP_IFL_CAP
+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
+.BR STHYI_FC_CP_IFL_CAP ,
+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
+.I *resp_buffer
+is unchanged.
+The return values 1 and 2 are reserved.
+.PP
+On error, \-1 is returned, and
+.I 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 STANDARDS
+Linux on s390.
+.SH HISTORY
+Linux 4.15.
+.SH NOTES
+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)