man2/s390_guarded_storage.2

   1 .TH S390_GUARDED_STORAGE 2 2018-01-14 "Linux Programmer's Manual"
   2 .SH NAME
   3 s390_guarded_storage \- operations with z/Architecture guarded storage facility
   4 .SH SYNOPSIS
   5 .nf
   6 .B #include <asm/guarded_storage.h>
   7 .PP
   8 .BI "int s390_guarded_storage(int " command ", stuct gs_cb *" gs_cb ");"
   9 .fi
  10 .SH DESCRIPTION
  11 The
  12 .BR s390_guarded_storage ()
  13 system call enables the use of the Guarded Storage Facility
  14 (a z/Architecture-specific feature) for user space processes.
  15 .PP
  16 .\" The description is based on
  17 .\" http://www-05.ibm.com/de/linux-on-z-ws-us/agenda/pdfs/8_-_Linux_Whats_New_-_Stefan_Raspl.pdf
  18 .\" and "z/Architecture Principles of Operation" obtained from
  19 .\" http://publibfi.boulder.ibm.com/epubs/pdf/dz9zr011.pdf
  20 The guarded storage facility is a hardware feature that allows marking up to
  21 64 memory regions (as of z14) as guarded;
  22 reading a pointer with a newly introduced "Load Guarded" (LGG) or "Load Logical
  23 and Shift Guarded" (LLGFSG) instructions will cause a range check on the loaded
  24 value and invoke a (previously set up) user space handler if one of the guarded
  25 regions is affected.
  26 .PP
  27 The
  28 .\" The command description is copied from v4.12-rc1~139^2~56^2 commit message
  29 .I command
  30 argument indicates which function to perform.
  31 The following commands are supported:
  32 .TP
  33 .B GS_ENABLE
  34 Enable the guarded storage facility for the current task.
  35 The initial content of the guarded storage control block will be all zeros.
  36 After the enablement, user space code can use the "Load Guarded Storage
  37 Controls" (LGSC) instruction (or the
  38 .BR load_gs_cb ()
  39 function wrapper provided in the
  40 .B asm/guarded_storage.h
  41 header) to load an arbitrary control block.
  42 While a task is enabled, the kernel will save and restore the current content
  43 of the guarded storage registers on context switch.
  44 .TP
  45 .B GS_DISABLE
  46 Disables the use of the guarded storage facility for the current task.
  47 The kernel will cease to save and restore the content of the guarded storage
  48 registers, the task-specific content of these registers is lost.
  49 .TP
  50 .B GS_SET_BC_CB
  51 Set a broadcast guarded storage control block to the one provided in the
  52 .I gs_cb
  53 argument.
  54 This is called per thread and associates a specific guarded storage control
  55 block with the current task.
  56 This control block will be used in the broadcast command
  57 .BR GS_BROADCAST .
  58 .TP
  59 .B GS_CLEAR_BC_CB
  60 Clears the broadcast guarded storage control block.
  61 The guarded storage control block will no longer have the association
  62 established by the
  63 .B GS_SET_BC_CB
  64 command.
  65 .TP
  66 .B GS_BROADCAST
  67 Sends a broadcast to all thread siblings of the current task.
  68 Every sibling that has established a broadcast guarded storage control block
  69 will load this control block and will be enabled for guarded storage.
  70 The broadcast guarded storage control block is used up, a second broadcast
  71 without a refresh of the stored control block with
  72 .B GS_SET_BC_CB
  73 will not have any effect.
  74 .PP
  75 The
  76 .I gs_cb
  77 argument specifies the address of a guarded storage control block structure and
  78 is currently used only by the
  79 .B GS_SET_BC_CB
  80 command; all other aforementioned commands ignore this argument.
  81 .SH RETURN VALUE
  82 On success, the return value of
  83 .BR s390_guarded_storage ()
  84 is 0.
  85 .PP
  86 On error, \-1 is returned, and
  87 .IR errno
  88 is set appropriately.
  89 .SH ERRORS
  90 .TP
  91 .B EFAULT
  92 .I command
  93 was
  94 .BR GS_SET_BC_CB
  95 and the copying of the guarded storage control block structure pointed by the
  96 .I gs_cb
  97 argument has failed.
  98 .TP
  99 .B EINVAL
 100 The value provided in the
 101 .I command
 102 argument was not a valid command.
 103 .TP
 104 .B ENOMEM
 105 .I command
 106 was one of
 107 .BR GS_ENABLE " or " GS_SET_BC_CB ,
 108 and the allocation of a new guarded storage control block has failed.
 109 .TP
 110 .B EOPNOTSUPP
 111 The guarded storage is not supported by the hardware.
 112 .SH VERSIONS
 113 .\" 916cda1aa1b412d7cf2991c3af7479544942d121, v4.12-rc1~139^2~56^2
 114 This system call is available since Linux 4.12.
 115 .SH CONFORMING TO
 116 This Linux-specific system call is available only on the s390 architecture.
 117 .PP
 118 The guarded storage facility is available beginning with System z14.
 119 .SH NOTES
 120 Glibc does not provide a wrapper for this system call, use
 121 .BR syscall (2)
 122 to call it.
 123 .PP
 124 The description of the guarded storage facility along with related instructions
 125 and Guarded Storage Control Block and Guarded Storage Event Parameter List
 126 structure layouts is available in "z/Architecture Principles of Operations"
 127 beginning from the twelfth edition.
 128 .PP
 129 The
 130 .B gs_cb
 131 structure has a field
 132 .B gsepla
 133 (Guarded Storage Event Parameter List Address), which is a user space pointer
 134 to a Guarded Storage Event Parameter List structure (that contains the address
 135 of the aforementioned event handler in the
 136 .B gseha
 137 field), and its layout is available as a
 138 .B gs_epl
 139 structure type definition in the
 140 .B asm/guarded_storage.h
 141 header.
 142 .\" .PP
 143 .\" For the example of using the guarded storage facility, see
 144 .\" .UR https://developer.ibm.com/javasdk/2017/09/25/concurrent-scavenge-using-guarded-storage-facility-works/
 145 .\" the article with the description of its usage in the Java Garbage Collection
 146 .\" .UE
 147 .PP
 148 .PP
 149 .SH SEE ALSO
 150 .BR syscall (2)