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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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-s390" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Index of Archives]     [Kernel Development]     [Kernel Newbies]     [IDE]     [Security]     [Git]     [Netfilter]     [Bugtraq]     [Yosemite Info]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux ATA RAID]     [Samba]     [Linux Media]     [Device Mapper]

  Powered by Linux