s390_guarded_storage.2: New page documenting s390_guarded_storage(2) s390-specific system call

* man2/s390_guarded_storage.2: New file.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/s390_guarded_storage.2

@@ -0,0 +1,150 @@
+.TH S390_GUARDED_STORAGE 2 2018-01-14 "Linux Programmer's Manual"
+.SH NAME
+s390_guarded_storage \- operations with z/Architecture guarded storage facility
+.SH SYNOPSIS
+.nf
+.B #include <asm/guarded_storage.h>
+.PP
+.BI "int s390_guarded_storage(int " command ", stuct gs_cb *" gs_cb ");"
+.fi
+.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 current task.
+The initial content of the guarded storage control block will be all zeros.
+After the enablement, user space code can use the "Load Guarded Storage
+Controls" (LGSC) instruction (or the
+.BR load_gs_cb ()
+function wrapper provided in the
+.B asm/guarded_storage.h
+header) to load an arbitrary control block.
+While a task is enabled, the kernel will save and restore the current content
+of the guarded storage registers on context switch.
+.TP
+.B GS_DISABLE
+Disables the use of the guarded storage facility for the current 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 current 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 current 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 used up, 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 appropriately.
+.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 a valid command.
+.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 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
+Glibc does not provide a wrapper for this system call, use
+.BR syscall (2)
+to call it.
+.PP
+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
+.B gs_cb
+structure has a field
+.B 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
+.B gseha
+field), and its layout is available as a
+.B gs_epl
+structure type definition in the
+.B 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
+.PP
+.PP
+.SH SEE ALSO
+.BR syscall (2)