diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:40:15 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:40:15 +0000 |
commit | 399644e47874bff147afb19c89228901ac39340e (patch) | |
tree | 1c4c0b733f4c16b5783b41bebb19194a9ef62ad1 /man2/s390_guarded_storage.2 | |
parent | Initial commit. (diff) | |
download | manpages-399644e47874bff147afb19c89228901ac39340e.tar.xz manpages-399644e47874bff147afb19c89228901ac39340e.zip |
Adding upstream version 6.05.01.upstream/6.05.01
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man2/s390_guarded_storage.2')
-rw-r--r-- | man2/s390_guarded_storage.2 | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2 new file mode 100644 index 0000000..63d5c83 --- /dev/null +++ b/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 2023-03-30 "Linux man-pages 6.05.01" +.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> +.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 (), +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 +.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. +.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) |