# s390_guarded_storage

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


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


* * *