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/unistd.h>
10
11       int s390_sthyi(unsigned long function_code, void *resp_buffer,
12                      uint64_t *return_code, unsigned long flags);
13

DESCRIPTION

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

RETURN VALUE

45       On  success  (that  is:  emulation  succeeded),  the  return  value  of
46       s390_sthyi()  matches  the  condition  code  of the STHYI instructions,
47       which is a value in the range [0..3].  A return value  of  0  indicates
48       that  CPU  capacity  information  is  stored in *resp_buffer.  A return
49       value of 3 indicates "unsupported function code"  and  the  content  of
50       *resp_buffer is unchanged.  The return values 1 and 2 are reserved.
51
52       On error, -1 is returned, and errno is set appropriately.
53

ERRORS

55       EFAULT The value specified in resp_buffer or return_code is not a valid
56              address.
57
58       EINVAL The value specified in flags is nonzero.
59
60       ENOMEM Allocating memory for  handling  the  CPU  capacity  information
61              failed.
62
63       EOPNOTSUPP
64              The value specified in function_code is not valid.
65

VERSIONS

67       This system call is available since Linux 4.15.
68

CONFORMING TO

70       This Linux-specific system call is available only on the s390 architec‐
71       ture.
72

NOTES

74       Glibc does not provide a wrapper for this system call,  use  syscall(2)
75       to call it.
76
77       For  details of the STHYI instruction, see ⟨https://www.ibm.com/support
78       /knowledgecenter/SSB27U_6.3.0/com.ibm.zvm.v630.hcpb4/hcpb4sth.htm⟩.
79

COLOPHON

84       This page is part of release 4.16 of the Linux  man-pages  project.   A
85       description  of  the project, information about reporting bugs, and the
86       latest    version    of    this    page,    can     be     found     at
87       https://www.kernel.org/doc/man-pages/.
88
89
90
91Linux Programmer's Manual         2018-02-02                     S390_STHYI(2)