s390_sthyi(2)

1S390_STHYI(2)                 System Calls Manual                S390_STHYI(2)
2
3
4

NAME

6       s390_sthyi - emulate STHYI instruction
7

SYNOPSIS

9       #include <asm/sthyi.h>        /* Definition of STHYI_* constants */
10       #include <sys/syscall.h>      /* Definition of SYS_* constants */
11       #include <unistd.h>
12
13       int syscall(SYS_s390_sthyi, unsigned long function_code,
14                   void *resp_buffer, uint64_t *return_code,
15                   unsigned long flags);
16
17       Note: glibc provides no wrapper for s390_sthyi(), necessitating the use
18       of syscall(2).
19

DESCRIPTION

21       The s390_sthyi() system call emulates the STHYI (Store  Hypervisor  In‐
22       formation)  instruction.  It provides hardware resource information for
23       the machine and its virtualization levels.  This includes CPU type  and
24       capacity, as well as the machine model and other metrics.
25
26       The  function_code  argument  indicates which function to perform.  The
27       following code(s) are supported:
28
29       STHYI_FC_CP_IFL_CAP
30              Return CP (Central Processor) and IFL (Integrated  Facility  for
31              Linux) capacity information.
32
33       The  resp_buffer  argument  specifies the address of a response buffer.
34       When the function_code is STHYI_FC_CP_IFL_CAP, the buffer must  be  one
35       page  (4K)  in size.  If the system call returns 0, the response buffer
36       will be filled with CPU capacity information.  Otherwise, the  response
37       buffer's content is unchanged.
38
39       The  return_code  argument stores the return code of the STHYI instruc‐
40       tion, using one of the following values:
41
42       0      Success.
43
44       4      Unsupported function code.
45
46       For further details about return_code, function_code, and  resp_buffer,
47       see the reference given in NOTES.
48
49       The  flags argument is provided to allow for future extensions and cur‐
50       rently must be set to 0.
51

RETURN VALUE

53       On  success  (that  is:  emulation  succeeded),  the  return  value  of
54       s390_sthyi()  matches  the  condition  code  of the STHYI instructions,
55       which is a value in the range [0..3].  A return value  of  0  indicates
56       that  CPU  capacity  information  is  stored in *resp_buffer.  A return
57       value of 3 indicates "unsupported function code"  and  the  content  of
58       *resp_buffer is unchanged.  The return values 1 and 2 are reserved.
59
60       On error, -1 is returned, and errno is set to indicate the error.
61

ERRORS

63       EFAULT The value specified in resp_buffer or return_code is not a valid
64              address.
65
66       EINVAL The value specified in flags is nonzero.
67
68       ENOMEM Allocating memory for  handling  the  CPU  capacity  information
69              failed.
70
71       EOPNOTSUPP
72              The value specified in function_code is not valid.
73

VERSIONS

75       This system call is available since Linux 4.15.
76

CONFORMING TO

78       This Linux-specific system call is available only on the s390 architec‐
79       ture.
80

NOTES

82       For details of  the  STHYI  instruction,  see  the  documentation  page
83       ⟨https://www.ibm.com/support/knowledgecenter/SSB27U_6.3.0
84       /com.ibm.zvm.v630.hcpb4/hcpb4sth.htm⟩.
85
86       When the system call interface is used,  the  response  buffer  doesn't
87       have  to fulfill alignment requirements described in the STHYI instruc‐
88       tion definition.
89
90       The kernel caches the response (for up  to  one  second,  as  of  Linux
91       4.16).   Subsequent  system  call invocations may return the cached re‐
92       sponse.
93

COLOPHON

98       This page is part of release 5.12 of the Linux  man-pages  project.   A
99       description  of  the project, information about reporting bugs, and the
100       latest    version    of    this    page,    can     be     found     at
101       https://www.kernel.org/doc/man-pages/.
102
103
104
105Linux Programmer's Manual         2021-03-22                     S390_STHYI(2)