s390_guarded_storage(2) System Calls Manual s390_guarded_storage(2)
NAME
s390_guarded_storage - operations with z/Architecture guarded storage
facility
LIBRARY
Standard C library (libc, -lc)
SYNOPSIS
#include <asm/guarded_storage.h> /* Definition of GS_* constants */
#include <sys/syscall.h> /* Definition of SYS_* constants */
#include <unistd.h>
int syscall(SYS_s390_guarded_storage, int command,
struct gs_cb *gs_cb);
Note: glibc provides no wrapper for s390_guarded_storage(), necessitat-
ing the use of syscall(2).
DESCRIPTION
The s390_guarded_storage() system call enables the use of the Guarded
Storage Facility (a z/Architecture-specific feature) for user-space
processes.
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.
The command argument indicates which function to perform. The follow-
ing commands are supported:
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
load_gs_cb() function wrapper provided in the asm/guarded_stor-
age.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.
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.
GS_SET_BC_CB
Set a broadcast guarded storage control block to the one pro-
vided in the gs_cb argument. This is called per thread and as-
sociates a specific guarded storage control block with the call-
ing task. This control block will be used in the broadcast com-
mand GS_BROADCAST.
GS_CLEAR_BC_CB
Clears the broadcast guarded storage control block. The guarded
storage control block will no longer have the association estab-
lished by the GS_SET_BC_CB command.
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 GS_SET_BC_CB will not have any effect.
The gs_cb argument specifies the address of a guarded storage control
block structure and is currently used only by the GS_SET_BC_CB command;
all other aforementioned commands ignore this argument.
RETURN VALUE
On success, the return value of s390_guarded_storage() is 0.
On error, -1 is returned, and errno is set to indicate the error.
ERRORS
EFAULT command was GS_SET_BC_CB and the copying of the guarded storage
control block structure pointed by the gs_cb argument has
failed.
EINVAL The value provided in the command argument was not valid.
ENOMEM command was one of GS_ENABLE or GS_SET_BC_CB, and the allocation
of a new guarded storage control block has failed.
EOPNOTSUPP
The guarded storage facility is not supported by the hardware.
VERSIONS
This system call is available since Linux 4.12.
STANDARDS
This Linux-specific system call is available only on the s390 architec-
ture.
The guarded storage facility is available beginning with System z14.
NOTES
The description of the guarded storage facility along with related in-
structions and Guarded Storage Control Block and Guarded Storage Event
Parameter List structure layouts is available in "z/Architecture Prin-
ciples of Operations" beginning from the twelfth edition.
The gs_cb structure has a field 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 aforemen-
tioned event handler in the gseha field), and its layout is available
as a gs_epl structure type definition in the asm/guarded_storage.h
header.
SEE ALSO
syscall(2)
Linux man-pages 6.03 2022-10-30 s390_guarded_storage(2)
Generated by dwww version 1.15 on Thu Jun 27 09:25:16 CEST 2024.