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

NAME

6       s390_guarded_storage  -  operations with z/Architecture guarded storage
7       facility
8

SYNOPSIS

10       #include <asm/guarded_storage.h> /* Definition of GS_* constants */
11       #include <sys/syscall.h>         /* Definition of SYS_* constants */
12       #include <unistd.h>
13
14       int syscall(SYS_s390_guarded_storage, int command,
15                   struct gs_cb *gs_cb);
16
17       Note: glibc provides no wrapper for s390_guarded_storage(), necessitat‐
18       ing the use of syscall(2).
19

DESCRIPTION

21       The  s390_guarded_storage()  system call enables the use of the Guarded
22       Storage Facility (a  z/Architecture-specific  feature)  for  user-space
23       processes.
24
25       The  guarded storage facility is a hardware feature that allows marking
26       up to 64 memory regions (as of z14) as guarded; reading a pointer  with
27       a  newly  introduced  "Load  Guarded"  (LGG) or "Load Logical and Shift
28       Guarded" (LLGFSG) instructions will cause a range check on  the  loaded
29       value and invoke a (previously set up) user-space handler if one of the
30       guarded regions is affected.
31
32       The command argument indicates which function to perform.  The  follow‐
33       ing commands are supported:
34
35       GS_ENABLE
36              Enable  the  guarded storage facility for the calling task.  The
37              initial content of the guarded storage control block will be all
38              zeros.   After  enablement,  user-space  code  can use the "Load
39              Guarded   Storage   Controls"   (LGSC)   instruction   (or   the
40              load_gs_cb()  function wrapper provided in the asm/guarded_stor‐
41              age.h header) to load an arbitrary control block.  While a  task
42              is enabled, the kernel will save and restore the calling content
43              of the guarded storage registers on context switch.
44
45       GS_DISABLE
46              Disables the use of the guarded storage facility for the calling
47              task.   The kernel will cease to save and restore the content of
48              the guarded storage  registers,  the  task-specific  content  of
49              these registers is lost.
50
51       GS_SET_BC_CB
52              Set  a  broadcast  guarded storage control block to the one pro‐
53              vided in the gs_cb argument.  This is called per thread and  as‐
54              sociates a specific guarded storage control block with the call‐
55              ing task.  This control block will be used in the broadcast com‐
56              mand GS_BROADCAST.
57
58       GS_CLEAR_BC_CB
59              Clears the broadcast guarded storage control block.  The guarded
60              storage control block will no longer have the association estab‐
61              lished by the GS_SET_BC_CB command.
62
63       GS_BROADCAST
64              Sends  a  broadcast  to all thread siblings of the calling task.
65              Every sibling that has established a broadcast  guarded  storage
66              control  block  will load this control block and will be enabled
67              for guarded storage.   The  broadcast  guarded  storage  control
68              block  is  consumed; a second broadcast without a refresh of the
69              stored control block with GS_SET_BC_CB will not have any effect.
70
71       The gs_cb argument specifies the address of a guarded  storage  control
72       block structure and is currently used only by the GS_SET_BC_CB command;
73       all other aforementioned commands ignore this argument.
74

RETURN VALUE

76       On success, the return value of s390_guarded_storage() is 0.
77
78       On error, -1 is returned, and errno is set to indicate the error.
79

ERRORS

81       EFAULT command was GS_SET_BC_CB and the copying of the guarded  storage
82              control  block  structure  pointed  by  the  gs_cb  argument has
83              failed.
84
85       EINVAL The value provided in the command argument was not valid.
86
87       ENOMEM command was one of GS_ENABLE or GS_SET_BC_CB, and the allocation
88              of a new guarded storage control block has failed.
89
90       EOPNOTSUPP
91              The guarded storage facility is not supported by the hardware.
92

VERSIONS

94       This system call is available since Linux 4.12.
95

CONFORMING TO

97       This Linux-specific system call is available only on the s390 architec‐
98       ture.
99
100       The guarded storage facility is available beginning with System z14.
101

NOTES

103       The description of the guarded storage facility along with related  in‐
104       structions  and Guarded Storage Control Block and Guarded Storage Event
105       Parameter List structure layouts is available in "z/Architecture  Prin‐
106       ciples of Operations" beginning from the twelfth edition.
107
108       The gs_cb structure has a field gsepla (Guarded Storage Event Parameter
109       List Address), which is a user-space pointer to a Guarded Storage Event
110       Parameter  List  structure  (that contains the address of the aforemen‐
111       tioned event handler in the gseha field), and its layout  is  available
112       as  a  gs_epl  structure  type  definition in the asm/guarded_storage.h
113       header.
114

SEE ALSO

116       syscall(2)
117

COLOPHON

119       This page is part of release 5.12 of the Linux  man-pages  project.   A
120       description  of  the project, information about reporting bugs, and the
121       latest    version    of    this    page,    can     be     found     at
122       https://www.kernel.org/doc/man-pages/.
123
124
125
126Linux Programmer's Manual         2021-03-22           S390_GUARDED_STORAGE(2)
Impressum