| .\" Copyright (C) 2018 Eugene Syromyatnikov <evgsyr@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH S390_GUARDED_STORAGE 2 2021-03-22 "Linux Programmer's Manual" |
| .SH NAME |
| s390_guarded_storage \- operations with z/Architecture guarded storage facility |
| .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> |
| .PP |
| .BI "int syscall(SYS_s390_guarded_storage, int " command , |
| .BI " struct gs_cb *" gs_cb ); |
| .fi |
| .PP |
| .IR Note : |
| glibc provides no wrapper for |
| .BR s390_guarded_storage (2), |
| 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. |
| .PP |
| .\" 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. |
| .PP |
| 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. |
| .PP |
| 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. |
| .PP |
| On error, \-1 is returned, and |
| .IR errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| .I command |
| was |
| .BR 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 VERSIONS |
| .\" 916cda1aa1b412d7cf2991c3af7479544942d121, v4.12-rc1~139^2~56^2 |
| This system call is available since Linux 4.12. |
| .SH CONFORMING TO |
| This Linux-specific system call is available only on the s390 architecture. |
| .PP |
| The guarded storage facility is available beginning with 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. |
| .PP |
| 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. |
| .\" .PP |
| .\" 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) |