| 1 |
.\" Copyright 2018, Eugene Syromyatnikov <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH s390_guarded_storage 2 2026-02-22 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
s390_guarded_storage \- operations with z/Architecture guarded storage facility |
| 9 |
.SH LIBRARY |
| 10 |
Standard C library |
| 11 |
.RI ( libc ,\~ \-lc ) |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
.BR "#include <asm/guarded_storage.h> " "/* Definition of " GS_* " constants */" |
| 15 |
.BR "#include <sys/syscall.h> " \ |
| 16 |
"/* Definition of " SYS_* " constants */" |
| 17 |
.B #include <unistd.h> |
| 18 |
.P |
| 19 |
.BI "int syscall(SYS_s390_guarded_storage, int " command , |
| 20 |
.BI " struct gs_cb *" gs_cb ); |
| 21 |
.fi |
| 22 |
.P |
| 23 |
.IR Note : |
| 24 |
glibc provides no wrapper for |
| 25 |
.BR s390_guarded_storage (), |
| 26 |
necessitating the use of |
| 27 |
.BR syscall (2). |
| 28 |
.SH DESCRIPTION |
| 29 |
The |
| 30 |
.BR s390_guarded_storage () |
| 31 |
system call enables the use of the Guarded Storage Facility |
| 32 |
(a z/Architecture-specific feature) for user-space processes. |
| 33 |
.P |
| 34 |
.\" The description is based on |
| 35 |
.\" http://www-05.ibm.com/de/linux-on-z-ws-us/agenda/pdfs/8_-_Linux_Whats_New_-_Stefan_Raspl.pdf |
| 36 |
.\" and "z/Architecture Principles of Operation" obtained from |
| 37 |
.\" http://publibfi.boulder.ibm.com/epubs/pdf/dz9zr011.pdf |
| 38 |
The guarded storage facility is a hardware feature that allows marking up to |
| 39 |
64 memory regions (as of z14) as guarded; |
| 40 |
reading a pointer with a newly introduced "Load Guarded" (LGG) |
| 41 |
or "Load Logical and Shift Guarded" (LLGFSG) instructions will cause |
| 42 |
a range check on the loaded value and invoke a (previously set up) |
| 43 |
user-space handler if one of the guarded regions is affected. |
| 44 |
.P |
| 45 |
The |
| 46 |
.\" The command description is copied from v4.12-rc1~139^2~56^2 commit message |
| 47 |
.I command |
| 48 |
argument indicates which function to perform. |
| 49 |
The following commands are supported: |
| 50 |
.TP |
| 51 |
.B GS_ENABLE |
| 52 |
Enable the guarded storage facility for the calling task. |
| 53 |
The initial content of the guarded storage control block will be all zeros. |
| 54 |
After enablement, user-space code can use the "Load Guarded Storage |
| 55 |
Controls" (LGSC) instruction (or the |
| 56 |
.BR load_gs_cb () |
| 57 |
function wrapper provided in the |
| 58 |
.I asm/guarded_storage.h |
| 59 |
header) to load an arbitrary control block. |
| 60 |
While a task is enabled, the kernel will save and restore the calling content |
| 61 |
of the guarded storage registers on context switch. |
| 62 |
.TP |
| 63 |
.B GS_DISABLE |
| 64 |
Disables the use of the guarded storage facility for the calling task. |
| 65 |
The kernel will cease to save and restore the content of the guarded storage |
| 66 |
registers, the task-specific content of these registers is lost. |
| 67 |
.TP |
| 68 |
.B GS_SET_BC_CB |
| 69 |
Set a broadcast guarded storage control block to the one provided in the |
| 70 |
.I gs_cb |
| 71 |
argument. |
| 72 |
This is called per thread and associates a specific guarded storage control |
| 73 |
block with the calling task. |
| 74 |
This control block will be used in the broadcast command |
| 75 |
.BR GS_BROADCAST . |
| 76 |
.TP |
| 77 |
.B GS_CLEAR_BC_CB |
| 78 |
Clears the broadcast guarded storage control block. |
| 79 |
The guarded storage control block will no longer have the association |
| 80 |
established by the |
| 81 |
.B GS_SET_BC_CB |
| 82 |
command. |
| 83 |
.TP |
| 84 |
.B GS_BROADCAST |
| 85 |
Sends a broadcast to all thread siblings of the calling task. |
| 86 |
Every sibling that has established a broadcast guarded storage control block |
| 87 |
will load this control block and will be enabled for guarded storage. |
| 88 |
The broadcast guarded storage control block is consumed; |
| 89 |
a second broadcast |
| 90 |
without a refresh of the stored control block with |
| 91 |
.B GS_SET_BC_CB |
| 92 |
will not have any effect. |
| 93 |
.P |
| 94 |
The |
| 95 |
.I gs_cb |
| 96 |
argument specifies the address of a guarded storage control block structure |
| 97 |
and is currently used only by the |
| 98 |
.B GS_SET_BC_CB |
| 99 |
command; |
| 100 |
all other aforementioned commands ignore this argument. |
| 101 |
.SH RETURN VALUE |
| 102 |
On success, the return value of |
| 103 |
.BR s390_guarded_storage () |
| 104 |
is 0. |
| 105 |
.P |
| 106 |
On error, \-1 is returned, and |
| 107 |
.I errno |
| 108 |
is set to indicate the error. |
| 109 |
.SH ERRORS |
| 110 |
.TP |
| 111 |
.B EFAULT |
| 112 |
.I command |
| 113 |
was |
| 114 |
.B GS_SET_BC_CB |
| 115 |
and the copying of the guarded storage control block structure pointed by the |
| 116 |
.I gs_cb |
| 117 |
argument has failed. |
| 118 |
.TP |
| 119 |
.B EINVAL |
| 120 |
The value provided in the |
| 121 |
.I command |
| 122 |
argument was not valid. |
| 123 |
.TP |
| 124 |
.B ENOMEM |
| 125 |
.I command |
| 126 |
was one of |
| 127 |
.BR GS_ENABLE " or " GS_SET_BC_CB , |
| 128 |
and the allocation of a new guarded storage control block has failed. |
| 129 |
.TP |
| 130 |
.B EOPNOTSUPP |
| 131 |
The guarded storage facility is not supported by the hardware. |
| 132 |
.SH STANDARDS |
| 133 |
Linux on s390. |
| 134 |
.SH HISTORY |
| 135 |
.\" 916cda1aa1b412d7cf2991c3af7479544942d121, v4.12-rc1~139^2~56^2 |
| 136 |
Linux 4.12, |
| 137 |
System z14. |
| 138 |
.SH NOTES |
| 139 |
The description of the guarded storage facility along with related |
| 140 |
instructions and Guarded Storage Control Block and |
| 141 |
Guarded Storage Event Parameter List structure layouts |
| 142 |
is available in "z/Architecture Principles of Operations" |
| 143 |
beginning from the twelfth edition. |
| 144 |
.P |
| 145 |
The |
| 146 |
.I gs_cb |
| 147 |
structure has a field |
| 148 |
.I gsepla |
| 149 |
(Guarded Storage Event Parameter List Address), which is a user-space pointer |
| 150 |
to a Guarded Storage Event Parameter List structure |
| 151 |
(that contains the address |
| 152 |
of the aforementioned event handler in the |
| 153 |
.I gseha |
| 154 |
field), and its layout is available as a |
| 155 |
.B gs_epl |
| 156 |
structure type definition in the |
| 157 |
.I asm/guarded_storage.h |
| 158 |
header. |
| 159 |
.\" .P |
| 160 |
.\" For the example of using the guarded storage facility, see |
| 161 |
.\" .UR https://developer.ibm.com/javasdk/2017/09/25/concurrent-scavenge-using-guarded-storage-facility-works/ |
| 162 |
.\" the article with the description of its usage in the Java Garbage Collection |
| 163 |
.\" .UE |
| 164 |
.SH SEE ALSO |
| 165 |
.BR syscall (2) |