1 .\" Copyright (C) 2018 Eugene Syromyatnikov <evgsyr@gmail.com>
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .TH S390_GUARDED_STORAGE 2 2021-03-22 "Linux Programmer's Manual"
7 s390_guarded_storage \- operations with z/Architecture guarded storage facility
10 .RI ( libc ", " \-lc )
13 .BR "#include <asm/guarded_storage.h> " "/* Definition of " GS_* " constants */"
14 .BR "#include <sys/syscall.h> " \
15 "/* Definition of " SYS_* " constants */"
16 .B #include <unistd.h>
18 .BI "int syscall(SYS_s390_guarded_storage, int " command ,
19 .BI " struct gs_cb *" gs_cb );
23 glibc provides no wrapper for
24 .BR s390_guarded_storage (),
25 necessitating the use of
29 .BR s390_guarded_storage ()
30 system call enables the use of the Guarded Storage Facility
31 (a z/Architecture-specific feature) for user-space processes.
33 .\" The description is based on
34 .\" http://www-05.ibm.com/de/linux-on-z-ws-us/agenda/pdfs/8_-_Linux_Whats_New_-_Stefan_Raspl.pdf
35 .\" and "z/Architecture Principles of Operation" obtained from
36 .\" http://publibfi.boulder.ibm.com/epubs/pdf/dz9zr011.pdf
37 The guarded storage facility is a hardware feature that allows marking up to
38 64 memory regions (as of z14) as guarded;
39 reading a pointer with a newly introduced "Load Guarded" (LGG)
40 or "Load Logical and Shift Guarded" (LLGFSG) instructions will cause
41 a range check on the loaded value and invoke a (previously set up)
42 user-space handler if one of the guarded regions is affected.
45 .\" The command description is copied from v4.12-rc1~139^2~56^2 commit message
47 argument indicates which function to perform.
48 The following commands are supported:
51 Enable the guarded storage facility for the calling task.
52 The initial content of the guarded storage control block will be all zeros.
53 After enablement, user-space code can use the "Load Guarded Storage
54 Controls" (LGSC) instruction (or the
56 function wrapper provided in the
57 .I asm/guarded_storage.h
58 header) to load an arbitrary control block.
59 While a task is enabled, the kernel will save and restore the calling content
60 of the guarded storage registers on context switch.
63 Disables the use of the guarded storage facility for the calling task.
64 The kernel will cease to save and restore the content of the guarded storage
65 registers, the task-specific content of these registers is lost.
68 Set a broadcast guarded storage control block to the one provided in the
71 This is called per thread and associates a specific guarded storage control
72 block with the calling task.
73 This control block will be used in the broadcast command
77 Clears the broadcast guarded storage control block.
78 The guarded storage control block will no longer have the association
84 Sends a broadcast to all thread siblings of the calling task.
85 Every sibling that has established a broadcast guarded storage control block
86 will load this control block and will be enabled for guarded storage.
87 The broadcast guarded storage control block is consumed; a second broadcast
88 without a refresh of the stored control block with
90 will not have any effect.
94 argument specifies the address of a guarded storage control block structure
95 and is currently used only by the
97 command; all other aforementioned commands ignore this argument.
99 On success, the return value of
100 .BR s390_guarded_storage ()
103 On error, \-1 is returned, and
105 is set to indicate the error.
112 and the copying of the guarded storage control block structure pointed by the
117 The value provided in the
119 argument was not valid.
124 .BR GS_ENABLE " or " GS_SET_BC_CB ,
125 and the allocation of a new guarded storage control block has failed.
128 The guarded storage facility is not supported by the hardware.
130 .\" 916cda1aa1b412d7cf2991c3af7479544942d121, v4.12-rc1~139^2~56^2
131 This system call is available since Linux 4.12.
133 This Linux-specific system call is available only on the s390 architecture.
135 The guarded storage facility is available beginning with System z14.
137 The description of the guarded storage facility along with related
138 instructions and Guarded Storage Control Block and
139 Guarded Storage Event Parameter List structure layouts
140 is available in "z/Architecture Principles of Operations"
141 beginning from the twelfth edition.
145 structure has a field
147 (Guarded Storage Event Parameter List Address), which is a user-space pointer
148 to a Guarded Storage Event Parameter List structure
149 (that contains the address
150 of the aforementioned event handler in the
152 field), and its layout is available as a
154 structure type definition in the
155 .I asm/guarded_storage.h
158 .\" For the example of using the guarded storage facility, see
159 .\" .UR https://developer.ibm.com/javasdk/2017/09/25/concurrent-scavenge-using-guarded-storage-facility-works/
160 .\" the article with the description of its usage in the Java Garbage Collection