s390_guarded_storage

S390_GUARDED_STORAGE(2)        System Calls Manual       S390_GUARDED_STORAGE(2)



NAME
       s390_guarded_storage - operations with z/Architecture guarded storage
       facility

SYNOPSIS
       #include <asm/guarded_storage.h>

       int s390_guarded_storage(int command, struct gs_cb *gs_cb);

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 following
       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_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.

       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 provided
              in the 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
              GS_BROADCAST.

       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 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 appropriately.

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.

CONFORMING TO
       This Linux-specific system call is available only on the s390
       architecture.

       The guarded storage facility is available beginning with System z14.

NOTES
       Glibc does not provide a wrapper for this system call, use syscall(2) to
       call it.

       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.

       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 aforementioned
       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)

COLOPHON
       This page is part of release 5.10 of the Linux man-pages project.  A
       description of the project, information about reporting bugs, and the
       latest version of this page, can be found at
       https://www.kernel.org/doc/man-pages/.



Linux Programmer's Manual          2019-03-06            S390_GUARDED_STORAGE(2)