mirror of https://github.com/mkerrisk/man-pages
177 lines
6.1 KiB
Groff
177 lines
6.1 KiB
Groff
.\" Copyright (C) 2018 Eugene Syromyatnikov <evgsyr@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH S390_GUARDED_STORAGE 2 2019-03-06 "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 ", struct gs_cb *" gs_cb ");"
|
|
.fi
|
|
.PP
|
|
.IR Note :
|
|
There is no glibc wrapper for this system call; see NOTES.
|
|
.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 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.
|
|
.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 to indicate the error.
|
|
.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 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 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; call it using
|
|
.BR syscall (2)
|
|
.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
|
|
.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.
|
|
.\" .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
|
|
.SH SEE ALSO
|
|
.BR syscall (2)
|