From 399644e47874bff147afb19c89228901ac39340e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:40:15 +0200 Subject: Adding upstream version 6.05.01. Signed-off-by: Daniel Baumann --- man2/s390_sthyi.2 | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 man2/s390_sthyi.2 (limited to 'man2/s390_sthyi.2') 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 +.\" +.\" 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 " " /* Definition of " STHYI_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.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) -- cgit v1.2.3