-.TH S390_GUARDED_STORAGE 2 2018-01-14 "Linux Programmer's Manual"
+.\" 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 2019-03-06 "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 ");"
+.BI "int s390_guarded_storage(int " command ", struct 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.
+(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
.\" 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.
+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
The following commands are supported:
.TP
.B GS_ENABLE
-Enable the guarded storage facility for the current task.
+Enable the guarded storage facility for the calling 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
+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
-.B asm/guarded_storage.h
+.I 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
+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 current task.
+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
.I gs_cb
argument.
This is called per thread and associates a specific guarded storage control
-block with the current task.
+block with the calling task.
This control block will be used in the broadcast command
.BR GS_BROADCAST .
.TP
command.
.TP
.B GS_BROADCAST
-Sends a broadcast to all thread siblings of the current task.
+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 used up, a second broadcast
+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
+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
.B EINVAL
The value provided in the
.I command
-argument was not a valid command.
+argument was not valid.
.TP
.B ENOMEM
.I command
and the allocation of a new guarded storage control block has failed.
.TP
.B EOPNOTSUPP
-The guarded storage is not supported by the hardware.
+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.
.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"
+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
+.I 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
+.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
-.B gseha
+.I gseha
field), and its layout is available as a
.B gs_epl
structure type definition in the
-.B asm/guarded_storage.h
+.I asm/guarded_storage.h
header.
.\" .PP
.\" For the example of using the guarded storage facility, see
.\" the article with the description of its usage in the Java Garbage Collection
.\" .UE
.PP
-.PP
.SH SEE ALSO
.BR syscall (2)
projects / thirdparty / man-pages.git / blobdiff