man2/s390_guarded_storage.2

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