Hello QingFeng Thank you for this manual page! Could I ask that you address some points below please. On 11/20/2017 02:34 PM, QingFeng Hao wrote: > Signed-off-by: QingFeng Hao <haoqf@xxxxxxxxxxxxxxxxxx> > --- > man2/s390_sthyi.2 | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 115 insertions(+) > create mode 100644 man2/s390_sthyi.2 > > diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2 > new file mode 100644 > index 0000000..c8797b7 > --- /dev/null > +++ b/man2/s390_sthyi.2 > @@ -0,0 +1,115 @@ > +.\" Copyright IBM Corp. 2017 > +.\" Author: QingFeng Hao <haoqf@xxxxxxxxxxxxxxxxxx> > +.\" > +.\" %%%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 2017-09-21 "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 *" buffer ", uint64_t *" return_code ", unsigned long " flags "); > +.fi > +.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: > +.RB ( 0 ) > +CP and IFL capacity information. The line above is hard to understand. It needs a verb. What is done with the CP and IFL capacity information? It may also be helpful to explain what the abbreviations "CP" and "IFL" stand for. > +.PP > +The > +.I buffer > +argument specifies the address of response buffer. 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, success > +.RB ( 0 ) > +or unsupported function code > +.RB ( 4 ). > +For details about this and function_code, buffer argument, please reference the link in > +.IR "CONFORMING TO" > +below. > +.PP > +The > +.I flags > +argument is provided to allow for future extensions and currently > +must be set to "0". > +.SH RETURN VALUE > +On success, > +.BR s390_sthyi () > +returns 0 and stores CPU capacity information to > +.I buffer. > +.PP > +On error, -1 is returned, and > +.IR errno > +is set appropriately. > +.PP > +On other cases, the value of condition code is returned, which currently What does "On other cases" mean? When do those cases happen? Could you reword please. > +is only 3 indicating "unsupported function code". > +.SH ERRORS > +.TP > +.B EINVAL > +The value specified in > +.I flags > +is non-zero. > +.TP > +.B EOPNOTSUPP > +The value specified in > +.I function_code > +is not a valid value. > +.TP > +.B EFAULT > +The value specified in > +.I buffer > +or > +.I return_code > +is not a valid address. > +.TP > +.B ENOMEM > +Allocating memory for handling the CPU capacity information failed. > +.IR "CONFORMING TO" > +below. The last two lines do not make a complete sentence. What do you want to say here? > +.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. > +For details about the STHYI instruction, please reference the link: > +https://www.ibm.com/support/knowledgecenter/SSB27U_6.3.0/com.ibm.zvm.v630.hcpb4/hcpb4sth.htm#hcpb4-sth__headsec > +.SH NOTES > +Glibc does not provide a wrapper for this system call, use > +.BR syscall (2) > +to call it. > +.SH SEE ALSO > +.BR syscall (2) > Thank you, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
