1S390_GUARDED_STORAGE(2) System Calls Manual S390_GUARDED_STORAGE(2)
2
6 s390_guarded_storage - operations with z/Architecture guarded storage
7 facility
8
10 #include <asm/guarded_storage.h> /* Definition of GS_* constants */
11 #include <sys/syscall.h> /* Definition of SYS_* constants */
12 #include <unistd.h>
13 int syscall(SYS_s390_guarded_storage, int command,
15 struct gs_cb *gs_cb);
16 Note: glibc provides no wrapper for s390_guarded_storage(), necessitat‐
18 ing the use of syscall(2).
19
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 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 The command argument indicates which function to perform. The follow‐
33 ing commands are supported:
34 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 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 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 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 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 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
76 On success, the return value of s390_guarded_storage() is 0.
77 On error, -1 is returned, and errno is set to indicate the error.
79
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 EINVAL The value provided in the command argument was not valid.
86 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 EOPNOTSUPP
91 The guarded storage facility is not supported by the hardware.
92
94 This system call is available since Linux 4.12.
95
97 This Linux-specific system call is available only on the s390 architec‐
98 ture.
99 The guarded storage facility is available beginning with System z14.
101
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 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
116 syscall(2)
117
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/.
123Linux Programmer's Manual 2021-03-22 S390_GUARDED_STORAGE(2)