S390_GUARDED_STORAGE(2)   (2019-03-06)    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 fea-
          ture) 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 con-
               trol 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 wrap-
               per 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 con-
               trol block with the calling task.  This control block
               will be used in the broadcast command GS_BROADCAST.

     Page 1              Linux Programmer's Manual   (printed 5/24/22)

     S390_GUARDED_STORAGE(2)   (2019-03-06)    S390_GUARDED_STORAGE(2)

          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 com-
               mand.

          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 con-
               trol block with GS_SET_BC_CB will not have any effect.

          The gs_cb argument specifies the address of a guarded stor-
          age 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

     Page 2              Linux Programmer's Manual   (printed 5/24/22)

     S390_GUARDED_STORAGE(2)   (2019-03-06)    S390_GUARDED_STORAGE(2)

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

     Page 3              Linux Programmer's Manual   (printed 5/24/22)