s390_sthyi(2)

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

NAME

6       s390_sthyi - emulate STHYI instruction
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

STANDARDS

78       Linux on s390.
79

HISTORY

81       Linux 4.15.
82

NOTES

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