man2/s390_guarded_storage.2

   1 .\" Copyright (C) 2018 Eugene Syromyatnikov <evgsyr@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH S390_GUARDED_STORAGE 2 2021-03-22 "Linux Programmer's Manual"
  26 .SH NAME
  27 s390_guarded_storage \- operations with z/Architecture guarded storage facility
  28 .SH SYNOPSIS
  29 .nf
  30 .BR "#include <asm/guarded_storage.h> " "/* Definition of " GS_* " constants */"
  31 .BR "#include <sys/syscall.h>         " \
  32 "/* Definition of " SYS_* " constants */"
  33 .B #include <unistd.h>
  34 .PP
  35 .BI "int syscall(SYS_s390_guarded_storage, int " command ,
  36 .BI "            struct gs_cb *" gs_cb );
  37 .fi
  38 .PP
  39 .IR Note :
  40 glibc provides no wrapper for
  41 .BR s390_guarded_storage (),
  42 necessitating the use of
  43 .BR syscall (2).
  44 .SH DESCRIPTION
  45 The
  46 .BR s390_guarded_storage ()
  47 system call enables the use of the Guarded Storage Facility
  48 (a z/Architecture-specific feature) for user-space processes.
  49 .PP
  50 .\" The description is based on
  51 .\" http://www-05.ibm.com/de/linux-on-z-ws-us/agenda/pdfs/8_-_Linux_Whats_New_-_Stefan_Raspl.pdf
  52 .\" and "z/Architecture Principles of Operation" obtained from
  53 .\" http://publibfi.boulder.ibm.com/epubs/pdf/dz9zr011.pdf
  54 The guarded storage facility is a hardware feature that allows marking up to
  55 64 memory regions (as of z14) as guarded;
  56 reading a pointer with a newly introduced "Load Guarded" (LGG)
  57 or "Load Logical and Shift Guarded" (LLGFSG) instructions will cause
  58 a range check on the loaded value and invoke a (previously set up)
  59 user-space handler if one of the guarded regions is affected.
  60 .PP
  61 The
  62 .\" The command description is copied from v4.12-rc1~139^2~56^2 commit message
  63 .I command
  64 argument indicates which function to perform.
  65 The following commands are supported:
  66 .TP
  67 .B GS_ENABLE
  68 Enable the guarded storage facility for the calling task.
  69 The initial content of the guarded storage control block will be all zeros.
  70 After enablement, user-space code can use the "Load Guarded Storage
  71 Controls" (LGSC) instruction (or the
  72 .BR load_gs_cb ()
  73 function wrapper provided in the
  74 .I asm/guarded_storage.h
  75 header) to load an arbitrary control block.
  76 While a task is enabled, the kernel will save and restore the calling content
  77 of the guarded storage registers on context switch.
  78 .TP
  79 .B GS_DISABLE
  80 Disables the use of the guarded storage facility for the calling task.
  81 The kernel will cease to save and restore the content of the guarded storage
  82 registers, the task-specific content of these registers is lost.
  83 .TP
  84 .B GS_SET_BC_CB
  85 Set a broadcast guarded storage control block to the one provided in the
  86 .I gs_cb
  87 argument.
  88 This is called per thread and associates a specific guarded storage control
  89 block with the calling task.
  90 This control block will be used in the broadcast command
  91 .BR GS_BROADCAST .
  92 .TP
  93 .B GS_CLEAR_BC_CB
  94 Clears the broadcast guarded storage control block.
  95 The guarded storage control block will no longer have the association
  96 established by the
  97 .B GS_SET_BC_CB
  98 command.
  99 .TP
 100 .B GS_BROADCAST
 101 Sends a broadcast to all thread siblings of the calling task.
 102 Every sibling that has established a broadcast guarded storage control block
 103 will load this control block and will be enabled for guarded storage.
 104 The broadcast guarded storage control block is consumed; a second broadcast
 105 without a refresh of the stored control block with
 106 .B GS_SET_BC_CB
 107 will not have any effect.
 108 .PP
 109 The
 110 .I gs_cb
 111 argument specifies the address of a guarded storage control block structure
 112 and is currently used only by the
 113 .B GS_SET_BC_CB
 114 command; all other aforementioned commands ignore this argument.
 115 .SH RETURN VALUE
 116 On success, the return value of
 117 .BR s390_guarded_storage ()
 118 is 0.
 119 .PP
 120 On error, \-1 is returned, and
 121 .IR errno
 122 is set to indicate the error.
 123 .SH ERRORS
 124 .TP
 125 .B EFAULT
 126 .I command
 127 was
 128 .BR GS_SET_BC_CB
 129 and the copying of the guarded storage control block structure pointed by the
 130 .I gs_cb
 131 argument has failed.
 132 .TP
 133 .B EINVAL
 134 The value provided in the
 135 .I command
 136 argument was not valid.
 137 .TP
 138 .B ENOMEM
 139 .I command
 140 was one of
 141 .BR GS_ENABLE " or " GS_SET_BC_CB ,
 142 and the allocation of a new guarded storage control block has failed.
 143 .TP
 144 .B EOPNOTSUPP
 145 The guarded storage facility is not supported by the hardware.
 146 .SH VERSIONS
 147 .\" 916cda1aa1b412d7cf2991c3af7479544942d121, v4.12-rc1~139^2~56^2
 148 This system call is available since Linux 4.12.
 149 .SH CONFORMING TO
 150 This Linux-specific system call is available only on the s390 architecture.
 151 .PP
 152 The guarded storage facility is available beginning with System z14.
 153 .SH NOTES
 154 The description of the guarded storage facility along with related
 155 instructions and Guarded Storage Control Block and
 156 Guarded Storage Event Parameter List structure layouts
 157 is available in "z/Architecture Principles of Operations"
 158 beginning from the twelfth edition.
 159 .PP
 160 The
 161 .I gs_cb
 162 structure has a field
 163 .I gsepla
 164 (Guarded Storage Event Parameter List Address), which is a user-space pointer
 165 to a Guarded Storage Event Parameter List structure
 166 (that contains the address
 167 of the aforementioned event handler in the
 168 .I gseha
 169 field), and its layout is available as a
 170 .B gs_epl
 171 structure type definition in the
 172 .I asm/guarded_storage.h
 173 header.
 174 .\" .PP
 175 .\" For the example of using the guarded storage facility, see
 176 .\" .UR https://developer.ibm.com/javasdk/2017/09/25/concurrent-scavenge-using-guarded-storage-facility-works/
 177 .\" the article with the description of its usage in the Java Garbage Collection
 178 .\" .UE
 179 .SH SEE ALSO
 180 .BR syscall (2)