1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2015 Joyent, Inc. 13.\" Copyright 2023 Oxide Computer Company 14.\" 15.Dd January 19, 2023 16.Dt PLWP_GETXREGS 3PROC 17.Os 18.Sh NAME 19.Nm Plwp_getxregs , 20.Nm Plwp_freexregs , 21.Nm Plwp_setxregs , 22.Nm Lgetxregs , 23.Nm Lsetxregs 24.Nd get and set extended register state 25.Sh LIBRARY 26.Lb libproc 27.Sh SYNOPSIS 28.In libproc.h 29.Ft int 30.Fo Plwp_getxregs 31.Fa "struct ps_prochandle *P" 32.Fa "lwpid_t lwpid" 33.Fa "prxregset_t **xregsp" 34.Fa "size_t *sizep" 35.Fc 36.Ft int 37.Fo Plwp_freexregs 38.Fa "struct ps_prochandle *P" 39.Fa "lwpid_t lwpid" 40.Fa "prxregset_t *xregs" 41.Fa "size_t size" 42.Fc 43.Ft int 44.Fo Plwp_setxregs 45.Fa "struct ps_prochandle *P" 46.Fa "lwpid_t lwpid" 47.Fa "const prxregset_t *xregs" 48.Fc 49.Ft int 50.Fo Lgetxregs 51.Fa "struct ps_lwphandle *L" 52.Fa "prxregset_t **xregsp" 53.Fa "size_t *sizep" 54.Fc 55.Ft int 56.Fo Lsetxregs 57.Fa "struct ps_lwphandle *L" 58.Fa "const prxregset_t *xregs" 59.Fc 60.Sh DESCRIPTION 61The 62.Fn Plwp_getxregs 63and 64.Fn Plwp_setxregs 65functions get and set the extended register state of the thread 66.Fa lwpid 67in the process handle 68.Fa P . 69.Pp 70The extended register state is defined by the architecture. 71These registers may refer to optional registers that have become common on the 72platform, but are not part of the traditional ABI and thus not covered by 73functions such as 74.Xr Plwp_getregs 3PROC 75and 76.Xr Plwp_getfpregs 3PROC . 77Support for the extended registers varies based on the architecture and 78varies based on the specific system. 79For example, on x86 based CPUs the xregs functionality requires the x86 80xsave functionality to be supported. 81.Pp 82The 83.Fn Plwp_getxregs 84function gets the extended register state information, allocates the 85appropriate sized buffer for it, and places a pointer to that buffer 86into 87.Fa xregs 88and updates 89.Fa sizep 90to indicate the size of the allocated structure. 91Due to the fact that hardware has varying sized extended register sets, 92the exact size of the structure can vary between different running 93systems and core files. 94It is also possible that some processor extensions are enabled at 95process runtime, leading for this to further be different between 96different processes on the same system. 97As such, all of the different platform instantiations of the 98.Vt prxregset_t 99end up generally being opaque structures that can be cast to something 100more specific that also includes its size. 101.Pp 102The obtained 103.Vt prxregset_t 104in 105.Fa xregsp 106must be freed by the caller with the 107.Fn Plwp_freexregs 108function. 109.Pp 110The 111.Fn Plwp_setxregs 112function sets the extended register state information in 113.Fa xregs 114for the process handle 115.Fa P . 116.Pp 117Processes must be stopped prior to obtaining the register state of 118individual threads. 119Processes may be stopped with 120.Xr Pstop 3PROC . 121.Pp 122The 123.Sy prxregset_t 124structure is described in 125.Xr proc 5 . 126.Pp 127One may not set the register values of a process that is not an active 128process, e.g. a process handle that refers to a file or a core file. 129.Pp 130The 131.Fn Lgetxregs 132and 133.Fn Lsetxregs 134functions are equivalent to the 135.Fn Plwp_getxregs 136and 137.Fn Plwp_setxregs 138functions except that they operate on a specific thread identified by 139the handle 140.Fa L 141and only require that the thread in question be stopped. 142Data allocated with the 143.Fn Lgetxregs 144functions should be freed with the 145.Fn Plwp_freexregs 146function. 147.Sh RETURN VALUES 148Upon successful completion, the 149.Fn Plwp_getxregs 150and 151.Fn Plwp_setxregs 152functions return 153.Sy 0 154and get or set the register state. 155Otherwise, 156.Sy -1 157is returned and 158.Sy errno 159is set to indicate the error. 160.Sh ERRORS 161For a full list of possible errors see the 162.Sy DIAGNOSTICS 163section in 164.Xr proc 5 . 165.Pp 166The 167.Fn Plwp_getxregs 168and 169.Fn Plwp_setxregs 170function will fail if: 171.Bl -tag -width Er 172.It Er ENODATA 173The process handle 174.Fa P 175does not have any extended register state information. 176This generally happens because the platform does not support it. 177.It Er EBUSY 178The process handle 179.Fa P 180refers to a live process and it is not stopped. 181.It Er ENOENT 182There is no thread with id 183.Fa lwpid 184in the process handle 185.Fa P . 186.El 187The 188.Fn Lgetxregs 189and 190.Fn Lsetxregs 191function will fail if: 192.Bl -tag -width Er 193.It Er ENODATA 194The thread handle 195.Fa L 196does not have any extended register state information. 197This generally happens because the platform does not support it. 198.It Er EBUSY 199The thread handle 200.Fa L 201refers to a live process and the thread is not stopped. 202.El 203.Sh INTERFACE STABILITY 204.Sy Uncommitted 205.Sh MT-LEVEL 206See 207.Sy LOCKING 208in 209.Xr libproc 3LIB . 210.Sh SEE ALSO 211.Xr libproc 3LIB , 212.Xr Plwp_getfpregs 3PROC , 213.Xr Plwp_getregs 3PROC , 214.Xr Plwp_setfpregs 3PROC , 215.Xr Plwp_setregs 3PROC , 216.Xr Pstop 3PROC , 217.Xr proc 5 218