On Wed, May 2, 2018 at 2:36 PM, Michael Kerrisk (man-pages) <mtk.manpages@xxxxxxxxx> wrote: > 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 I have not specific preference; IIRC, you preferred the verbatim one in the past, and it's fine with me (as well as GPL/BSD, too). > 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/ -- Eugene Syromyatnikov mailto:evgsyr@xxxxxxxxx xmpp:esyr@jabber.{ru|org} -- 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
