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 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 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 architec-
       ture.

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

COLOPHON
       This page is part of release 5.05 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)