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>
11
12       int s390_guarded_storage(int command, struct gs_cb *gs_cb);
13

DESCRIPTION

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

RETURN VALUE

70       On success, the return value of s390_guarded_storage() is 0.
71
72       On error, -1 is returned, and errno is set appropriately.
73

ERRORS

75       EFAULT command  was GS_SET_BC_CB and the copying of the guarded storage
76              control block  structure  pointed  by  the  gs_cb  argument  has
77              failed.
78
79       EINVAL The value provided in the command argument was not valid.
80
81       ENOMEM command was one of GS_ENABLE or GS_SET_BC_CB, and the allocation
82              of a new guarded storage control block has failed.
83
84       EOPNOTSUPP
85              The guarded storage facility is not supported by the hardware.
86

VERSIONS

88       This system call is available since Linux 4.12.
89

CONFORMING TO

91       This Linux-specific system call is available only on the s390 architec‐
92       ture.
93
94       The guarded storage facility is available beginning with System z14.
95

NOTES

97       Glibc  does  not provide a wrapper for this system call, use syscall(2)
98       to call it.
99
100       The description of the guarded  storage  facility  along  with  related
101       instructions  and  Guarded  Storage  Control  Block and Guarded Storage
102       Event Parameter List structure layouts is available in  "z/Architecture
103       Principles of Operations" beginning from the twelfth edition.
104
105       The gs_cb structure has a field gsepla (Guarded Storage Event Parameter
106       List Address), which is a user-space pointer to a Guarded Storage Event
107       Parameter  List  structure  (that contains the address of the aforemen‐
108       tioned event handler in the gseha field), and its layout  is  available
109       as  a  gs_epl  structure  type  definition in the asm/guarded_storage.h
110       header.
111

SEE ALSO

113       syscall(2)
114

COLOPHON

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