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