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       When  the function_code is 0, the buffer must be one page (4K) in size.
28       If the system call returns 0, the response buffer will be  filled  with
29       CPU  capacity information.  Otherwise, the response buffer's content is
30       unchanged.
31
32       The return_code argument stores the return code of the  STHYI  instruc‐
33       tion, using one of the following values:
34
35       0       Success.
36
37       4       Unsupported function code.
38
39       For  further details about return_code, function_code, and resp_buffer,
40       see the reference given in NOTES.
41
42       The flags argument is provided to allow for future extensions and  cur‐
43       rently must be set to 0.
44

RETURN VALUE

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

ERRORS

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

VERSIONS

68       This system call is available since Linux 4.15.
69

CONFORMING TO

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

NOTES

75       Glibc  does  not provide a wrapper for this system call, use syscall(2)
76       to call it.
77
78       For details of  the  STHYI  instruction,  see  the  documentation  page
79       ⟨https://www.ibm.com/support/knowledgecenter/SSB27U_6.3.0
80       /com.ibm.zvm.v630.hcpb4/hcpb4sth.htm⟩.
81
82       When the system call interface is used,  the  response  buffer  doesn't
83       have  to fulfill alignment requirements described in the STHYI instruc‐
84       tion definition.
85
86       The kernel caches the response (for up  to  one  second,  as  of  Linux
87       4.16).   Subsequent  system  call  invocations  may  return  the cached
88       response.
89

COLOPHON

94       This page is part of release 5.02 of the Linux  man-pages  project.   A
95       description  of  the project, information about reporting bugs, and the
96       latest    version    of    this    page,    can     be     found     at
97       https://www.kernel.org/doc/man-pages/.
98
99
100
101Linux Programmer's Manual         2019-03-06                     S390_STHYI(2)