Debian Codegraph @

upstream/debian-unstable/man2/s390_guarded_storage.2

raw
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)