s390_guarded_storage(2) System Calls Manual s390_guarded_storage(2) 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(), necessitat- ing 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 follow- ing 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_stor- age.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 pro- vided in the gs_cb argument. This is called per thread and as- sociates a specific guarded storage control block with the call- ing task. This control block will be used in the broadcast com- mand GS_BROADCAST. GS_CLEAR_BC_CB Clears the broadcast guarded storage control block. The guarded storage control block will no longer have the association estab- lished 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. VERSIONS This system call is available since Linux 4.12. STANDARDS This Linux-specific system call is available only on the s390 architec- ture. The guarded storage facility is available beginning with System z14. NOTES The description of the guarded storage facility along with related in- structions and Guarded Storage Control Block and Guarded Storage Event Parameter List structure layouts is available in "z/Architecture Prin- ciples 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 aforemen- tioned 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) Linux man-pages 6.03 2022-10-30 s390_guarded_storage(2)
Generated by dwww version 1.15 on Thu Jun 27 09:25:16 CEST 2024.