From 3d08cd331c1adcf0d917392f7e527b3f00511748 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:22 +0200 Subject: Merging upstream version 6.8. Signed-off-by: Daniel Baumann --- man/man2/s390_guarded_storage.2 | 162 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 man/man2/s390_guarded_storage.2 (limited to 'man/man2/s390_guarded_storage.2') diff --git a/man/man2/s390_guarded_storage.2 b/man/man2/s390_guarded_storage.2 new file mode 100644 index 0000000..9155161 --- /dev/null +++ b/man/man2/s390_guarded_storage.2 @@ -0,0 +1,162 @@ +.\" Copyright (C) 2018 Eugene Syromyatnikov +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH s390_guarded_storage 2 2024-05-02 "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 " "/* Definition of " GS_* " constants */" +.BR "#include " \ +"/* Definition of " SYS_* " constants */" +.B #include +.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) -- cgit v1.2.3