1 files changed, 162 insertions, 0 deletions
diff --git a/man/man2/s390_guarded_storage.2 b/man/man2/s390_guarded_storage.2
new file mode 100644
index 000000000..dd77e010c
--- /dev/null
+++ b/man/man2/s390_guarded_storage.2
@@ -0,0 +1,162 @@
+.\" Copyright (C) 2018 Eugene Syromyatnikov <evgsyr@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH s390_guarded_storage 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+s390_guarded_storage \- operations with z/Architecture guarded storage facility
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.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>
+.P
+.BI "int syscall(SYS_s390_guarded_storage, int " command ,
+.BI "            struct gs_cb *" gs_cb );
+.fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR s390_guarded_storage (),
+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.
+.P
+.\" 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.
+.P
+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.
+.P
+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.
+.P
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+.I command
+was
+.B 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 STANDARDS
+Linux on s390.
+.SH HISTORY
+.\" 916cda1aa1b412d7cf2991c3af7479544942d121, v4.12-rc1~139^2~56^2
+Linux 4.12.
+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.
+.P
+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.
+.\" .P
+.\" 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)