[man-pages PATCH 5/5] man2: describe s390_guarded_storage s390-specific system call

[man-pages PATCH 5/5] man2: describe s390_guarded_storage s390-specific system call

[Eugene Syromyatnikov]

---
 man2/s390_guarded_storage.2 | 150 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 150 insertions(+)
 create mode 100644 man2/s390_guarded_storage.2

diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2
new file mode 100644
index 0000000..4d72713
--- /dev/null
+++ b/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 calls enables the use of guarded storage facility (specific to the s390
+architecture) 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 pointed with a newly introduced "Load Guarded" (LGG) or "Load Logical
+and Shift Guarded" (LLGFSG) instructions will do 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 enalement, the 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 no longer has 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 ()
+returns 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 of
+.I command
+is not recognised.
+.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"
+starting 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
+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)
-- 
2.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [man-pages PATCH 5/5] man2: describe s390_guarded_storage s390-specific system call

[Heiko Carstens]

On Sun, Jan 14, 2018 at 07:56:43PM +0100, Eugene Syromyatnikov wrote:
> ---
>  man2/s390_guarded_storage.2 | 150 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 150 insertions(+)
>  create mode 100644 man2/s390_guarded_storage.2
> 
> diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2
> +.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 enalement, the user space code can use the "Load Guarded Storage

enablement

> +.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 of
> +.I command
> +is not recognised.

Maybe: "The value specified for command is not a valid command." ?

> +.B EOPNOTSUPP
> +The guarded storage is not supported by the hardware.

"The guarded storage facility is not available."

Thanks for providing the man page!

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html