diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-24 04:52:24 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-24 04:52:24 +0000 |
commit | 100d1b33f088fd38f69129afff7f9c2a1e084a57 (patch) | |
tree | 5bf6b0bb14f22ecf0a5e9439fdd4c4758402400c /man/man2/s390_sthyi.2 | |
parent | Releasing progress-linux version 6.7-2~progress7.99u1. (diff) | |
download | manpages-100d1b33f088fd38f69129afff7f9c2a1e084a57.tar.xz manpages-100d1b33f088fd38f69129afff7f9c2a1e084a57.zip |
Merging upstream version 6.8.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man/man2/s390_sthyi.2')
-rw-r--r-- | man/man2/s390_sthyi.2 | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/man/man2/s390_sthyi.2 b/man/man2/s390_sthyi.2 new file mode 100644 index 0000000..36cbbc4 --- /dev/null +++ b/man/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 2024-05-02 "Linux man-pages (unreleased)" +.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> +.P +.BI "int syscall(SYS_s390_sthyi, unsigned long " function_code , +.BI " void *" resp_buffer ", uint64_t *" return_code , +.BI " unsigned long " flags ); +.fi +.P +.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. +.P +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. +.P +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. +.P +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. +.P +For further details about +.IR return_code , +.IR function_code , +and +.IR resp_buffer , +see the reference given in NOTES. +.P +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. +.P +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 . +.P +When the system call interface is used, the response buffer doesn't +have to fulfill alignment requirements described in the STHYI +instruction definition. +.P +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) |