mirror of https://github.com/mkerrisk/man-pages
151 lines
4.9 KiB
Groff
151 lines
4.9 KiB
Groff
.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)
|