1 .\" Copyright (C) 2018 Eugene Syromyatnikov <evgsyr@gmail.com>
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .TH S390_GUARDED_STORAGE 2 2019-03-06 "Linux Programmer's Manual"
27 s390_guarded_storage \- operations with z/Architecture guarded storage facility
30 .B #include <asm/guarded_storage.h>
32 .BI "int s390_guarded_storage(int " command ", struct gs_cb *" gs_cb ");"
36 There is no glibc wrapper for this system call; see NOTES.
39 .BR s390_guarded_storage ()
40 system call enables the use of the Guarded Storage Facility
41 (a z/Architecture-specific feature) for user-space processes.
43 .\" The description is based on
44 .\" http://www-05.ibm.com/de/linux-on-z-ws-us/agenda/pdfs/8_-_Linux_Whats_New_-_Stefan_Raspl.pdf
45 .\" and "z/Architecture Principles of Operation" obtained from
46 .\" http://publibfi.boulder.ibm.com/epubs/pdf/dz9zr011.pdf
47 The guarded storage facility is a hardware feature that allows marking up to
48 64 memory regions (as of z14) as guarded;
49 reading a pointer with a newly introduced "Load Guarded" (LGG)
50 or "Load Logical and Shift Guarded" (LLGFSG) instructions will cause
51 a range check on the loaded value and invoke a (previously set up)
52 user-space handler if one of the guarded regions is affected.
55 .\" The command description is copied from v4.12-rc1~139^2~56^2 commit message
57 argument indicates which function to perform.
58 The following commands are supported:
61 Enable the guarded storage facility for the calling task.
62 The initial content of the guarded storage control block will be all zeros.
63 After enablement, user-space code can use the "Load Guarded Storage
64 Controls" (LGSC) instruction (or the
66 function wrapper provided in the
67 .I asm/guarded_storage.h
68 header) to load an arbitrary control block.
69 While a task is enabled, the kernel will save and restore the calling content
70 of the guarded storage registers on context switch.
73 Disables the use of the guarded storage facility for the calling task.
74 The kernel will cease to save and restore the content of the guarded storage
75 registers, the task-specific content of these registers is lost.
78 Set a broadcast guarded storage control block to the one provided in the
81 This is called per thread and associates a specific guarded storage control
82 block with the calling task.
83 This control block will be used in the broadcast command
87 Clears the broadcast guarded storage control block.
88 The guarded storage control block will no longer have the association
94 Sends a broadcast to all thread siblings of the calling task.
95 Every sibling that has established a broadcast guarded storage control block
96 will load this control block and will be enabled for guarded storage.
97 The broadcast guarded storage control block is consumed; a second broadcast
98 without a refresh of the stored control block with
100 will not have any effect.
104 argument specifies the address of a guarded storage control block structure
105 and is currently used only by the
107 command; all other aforementioned commands ignore this argument.
109 On success, the return value of
110 .BR s390_guarded_storage ()
113 On error, \-1 is returned, and
115 is set to indicate the error.
122 and the copying of the guarded storage control block structure pointed by the
127 The value provided in the
129 argument was not valid.
134 .BR GS_ENABLE " or " GS_SET_BC_CB ,
135 and the allocation of a new guarded storage control block has failed.
138 The guarded storage facility is not supported by the hardware.
140 .\" 916cda1aa1b412d7cf2991c3af7479544942d121, v4.12-rc1~139^2~56^2
141 This system call is available since Linux 4.12.
143 This Linux-specific system call is available only on the s390 architecture.
145 The guarded storage facility is available beginning with System z14.
147 Glibc does not provide a wrapper for this system call; call it using
150 The description of the guarded storage facility along with related
151 instructions and Guarded Storage Control Block and
152 Guarded Storage Event Parameter List structure layouts
153 is available in "z/Architecture Principles of Operations"
154 beginning from the twelfth edition.
158 structure has a field
160 (Guarded Storage Event Parameter List Address), which is a user-space pointer
161 to a Guarded Storage Event Parameter List structure
162 (that contains the address
163 of the aforementioned event handler in the
165 field), and its layout is available as a
167 structure type definition in the
168 .I asm/guarded_storage.h
171 .\" For the example of using the guarded storage facility, see
172 .\" .UR https://developer.ibm.com/javasdk/2017/09/25/concurrent-scavenge-using-guarded-storage-facility-works/
173 .\" the article with the description of its usage in the Java Garbage Collection