Hello On 04/14/2018 06:43 PM, Eugene Syromyatnikov wrote: > * man2/s390_guarded_storage.2: New file. > > Signed-off-by: Eugene Syromyatnikov <evgsyr@xxxxxxxxx> Thanks very much for this page! I've already merged it (and done some light editing), but I need a license for the page. Which would you like? Please see https://www.kernel.org/doc/man-pages/licenses.html Cheers, Michael > --- > 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..563e011 > --- /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 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) > -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
