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(), necessitating 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 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 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.

STANDARDS

       Linux on s390.

HISTORY

       Linux 4.12.  System z14.

NOTES

       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)