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