143051d27SRobert Mustacchi.\" 243051d27SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 343051d27SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 443051d27SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 543051d27SRobert Mustacchi.\" 1.0 of the CDDL. 643051d27SRobert Mustacchi.\" 743051d27SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 843051d27SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 943051d27SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 1043051d27SRobert Mustacchi.\" 1143051d27SRobert Mustacchi.\" 1243051d27SRobert Mustacchi.\" Copyright 2015 Joyent, Inc. 13*ed093b41SRobert Mustacchi.\" Copyright 2023 Oxide Computer Company 1443051d27SRobert Mustacchi.\" 15*ed093b41SRobert Mustacchi.Dd January 19, 2023 1643051d27SRobert Mustacchi.Dt PLWP_GETXREGS 3PROC 1743051d27SRobert Mustacchi.Os 1843051d27SRobert Mustacchi.Sh NAME 1943051d27SRobert Mustacchi.Nm Plwp_getxregs , 20*ed093b41SRobert Mustacchi.Nm Plwp_freexregs , 21*ed093b41SRobert Mustacchi.Nm Plwp_setxregs , 22*ed093b41SRobert Mustacchi.Nm Lgetxregs , 23*ed093b41SRobert Mustacchi.Nm Lsetxregs 2443051d27SRobert Mustacchi.Nd get and set extended register state 25ab618543SJohn Levon.Sh LIBRARY 2643051d27SRobert Mustacchi.Lb libproc 27ab618543SJohn Levon.Sh SYNOPSIS 2843051d27SRobert Mustacchi.In libproc.h 2943051d27SRobert Mustacchi.Ft int 3043051d27SRobert Mustacchi.Fo Plwp_getxregs 3143051d27SRobert Mustacchi.Fa "struct ps_prochandle *P" 3243051d27SRobert Mustacchi.Fa "lwpid_t lwpid" 33*ed093b41SRobert Mustacchi.Fa "prxregset_t **xregsp" 34*ed093b41SRobert Mustacchi.Fa "size_t *sizep" 35*ed093b41SRobert Mustacchi.Fc 36*ed093b41SRobert Mustacchi.Ft int 37*ed093b41SRobert Mustacchi.Fo Plwp_freexregs 38*ed093b41SRobert Mustacchi.Fa "struct ps_prochandle *P" 39*ed093b41SRobert Mustacchi.Fa "lwpid_t lwpid" 4043051d27SRobert Mustacchi.Fa "prxregset_t *xregs" 41*ed093b41SRobert Mustacchi.Fa "size_t size" 4243051d27SRobert Mustacchi.Fc 4343051d27SRobert Mustacchi.Ft int 4443051d27SRobert Mustacchi.Fo Plwp_setxregs 4543051d27SRobert Mustacchi.Fa "struct ps_prochandle *P" 4643051d27SRobert Mustacchi.Fa "lwpid_t lwpid" 4743051d27SRobert Mustacchi.Fa "const prxregset_t *xregs" 4843051d27SRobert Mustacchi.Fc 49*ed093b41SRobert Mustacchi.Ft int 50*ed093b41SRobert Mustacchi.Fo Lgetxregs 51*ed093b41SRobert Mustacchi.Fa "struct ps_lwphandle *L" 52*ed093b41SRobert Mustacchi.Fa "prxregset_t **xregsp" 53*ed093b41SRobert Mustacchi.Fa "size_t *sizep" 54*ed093b41SRobert Mustacchi.Fc 55*ed093b41SRobert Mustacchi.Ft int 56*ed093b41SRobert Mustacchi.Fo Lsetxregs 57*ed093b41SRobert Mustacchi.Fa "struct ps_lwphandle *L" 58*ed093b41SRobert Mustacchi.Fa "const prxregset_t *xregs" 59*ed093b41SRobert Mustacchi.Fc 6043051d27SRobert Mustacchi.Sh DESCRIPTION 6143051d27SRobert MustacchiThe 6243051d27SRobert Mustacchi.Fn Plwp_getxregs 6343051d27SRobert Mustacchiand 6443051d27SRobert Mustacchi.Fn Plwp_setxregs 6543051d27SRobert Mustacchifunctions get and set the extended register state of the thread 6643051d27SRobert Mustacchi.Fa lwpid 6743051d27SRobert Mustacchiin the process handle 6843051d27SRobert Mustacchi.Fa P . 6943051d27SRobert Mustacchi.Pp 7072d3dbb9SYuri PankovThe extended register state is defined by the architecture. 7172d3dbb9SYuri PankovThese registers may refer to optional registers that have become common on the 72*ed093b41SRobert Mustacchiplatform, but are not part of the traditional ABI and thus not covered by 7343051d27SRobert Mustacchifunctions such as 7443051d27SRobert Mustacchi.Xr Plwp_getregs 3PROC 7543051d27SRobert Mustacchiand 7643051d27SRobert Mustacchi.Xr Plwp_getfpregs 3PROC . 77*ed093b41SRobert MustacchiSupport for the extended registers varies based on the architecture and 78*ed093b41SRobert Mustacchivaries based on the specific system. 79*ed093b41SRobert MustacchiFor example, on x86 based CPUs the xregs functionality requires the x86 80*ed093b41SRobert Mustacchixsave functionality to be supported. 8143051d27SRobert Mustacchi.Pp 8243051d27SRobert MustacchiThe 8343051d27SRobert Mustacchi.Fn Plwp_getxregs 84*ed093b41SRobert Mustacchifunction gets the extended register state information, allocates the 85*ed093b41SRobert Mustacchiappropriate sized buffer for it, and places a pointer to that buffer 86*ed093b41SRobert Mustacchiinto 87*ed093b41SRobert Mustacchi.Fa xregs 88*ed093b41SRobert Mustacchiand updates 89*ed093b41SRobert Mustacchi.Fa sizep 90*ed093b41SRobert Mustacchito indicate the size of the allocated structure. 91*ed093b41SRobert MustacchiDue to the fact that hardware has varying sized extended register sets, 92*ed093b41SRobert Mustacchithe exact size of the structure can vary between different running 93*ed093b41SRobert Mustacchisystems and core files. 94*ed093b41SRobert MustacchiIt is also possible that some processor extensions are enabled at 95*ed093b41SRobert Mustacchiprocess runtime, leading for this to further be different between 96*ed093b41SRobert Mustacchidifferent processes on the same system. 97*ed093b41SRobert MustacchiAs such, all of the different platform instantiations of the 98*ed093b41SRobert Mustacchi.Vt prxregset_t 99*ed093b41SRobert Mustacchiend up generally being opaque structures that can be cast to something 100*ed093b41SRobert Mustacchimore specific that also includes its size. 101*ed093b41SRobert Mustacchi.Pp 102*ed093b41SRobert MustacchiThe obtained 103*ed093b41SRobert Mustacchi.Vt prxregset_t 104*ed093b41SRobert Mustacchiin 105*ed093b41SRobert Mustacchi.Fa xregsp 106*ed093b41SRobert Mustacchimust be freed by the caller with the 107*ed093b41SRobert Mustacchi.Fn Plwp_freexregs 108*ed093b41SRobert Mustacchifunction. 109*ed093b41SRobert Mustacchi.Pp 110*ed093b41SRobert MustacchiThe 11143051d27SRobert Mustacchi.Fn Plwp_setxregs 11243051d27SRobert Mustacchifunction sets the extended register state information in 11343051d27SRobert Mustacchi.Fa xregs 11443051d27SRobert Mustacchifor the process handle 11543051d27SRobert Mustacchi.Fa P . 11643051d27SRobert Mustacchi.Pp 11743051d27SRobert MustacchiProcesses must be stopped prior to obtaining the register state of 11872d3dbb9SYuri Pankovindividual threads. 11972d3dbb9SYuri PankovProcesses may be stopped with 12043051d27SRobert Mustacchi.Xr Pstop 3PROC . 12143051d27SRobert Mustacchi.Pp 12243051d27SRobert MustacchiThe 12343051d27SRobert Mustacchi.Sy prxregset_t 12443051d27SRobert Mustacchistructure is described in 125bbf21555SRichard Lowe.Xr proc 5 . 12643051d27SRobert Mustacchi.Pp 12743051d27SRobert MustacchiOne may not set the register values of a process that is not an active 12843051d27SRobert Mustacchiprocess, e.g. a process handle that refers to a file or a core file. 129*ed093b41SRobert Mustacchi.Pp 130*ed093b41SRobert MustacchiThe 131*ed093b41SRobert Mustacchi.Fn Lgetxregs 132*ed093b41SRobert Mustacchiand 133*ed093b41SRobert Mustacchi.Fn Lsetxregs 134*ed093b41SRobert Mustacchifunctions are equivalent to the 135*ed093b41SRobert Mustacchi.Fn Plwp_getxregs 136*ed093b41SRobert Mustacchiand 137*ed093b41SRobert Mustacchi.Fn Plwp_setxregs 138*ed093b41SRobert Mustacchifunctions except that they operate on a specific thread identified by 139*ed093b41SRobert Mustacchithe handle 140*ed093b41SRobert Mustacchi.Fa L 141*ed093b41SRobert Mustacchiand only require that the thread in question be stopped. 142*ed093b41SRobert MustacchiData allocated with the 143*ed093b41SRobert Mustacchi.Fn Lgetxregs 144*ed093b41SRobert Mustacchifunctions should be freed with the 145*ed093b41SRobert Mustacchi.Fn Plwp_freexregs 146*ed093b41SRobert Mustacchifunction. 14743051d27SRobert Mustacchi.Sh RETURN VALUES 14843051d27SRobert MustacchiUpon successful completion, the 14943051d27SRobert Mustacchi.Fn Plwp_getxregs 15043051d27SRobert Mustacchiand 15143051d27SRobert Mustacchi.Fn Plwp_setxregs 15243051d27SRobert Mustacchifunctions return 15343051d27SRobert Mustacchi.Sy 0 15472d3dbb9SYuri Pankovand get or set the register state. 15572d3dbb9SYuri PankovOtherwise, 15643051d27SRobert Mustacchi.Sy -1 15743051d27SRobert Mustacchiis returned and 15843051d27SRobert Mustacchi.Sy errno 15943051d27SRobert Mustacchiis set to indicate the error. 16043051d27SRobert Mustacchi.Sh ERRORS 16143051d27SRobert MustacchiFor a full list of possible errors see the 16243051d27SRobert Mustacchi.Sy DIAGNOSTICS 16343051d27SRobert Mustacchisection in 164bbf21555SRichard Lowe.Xr proc 5 . 16543051d27SRobert Mustacchi.Pp 16643051d27SRobert MustacchiThe 16743051d27SRobert Mustacchi.Fn Plwp_getxregs 16843051d27SRobert Mustacchiand 16943051d27SRobert Mustacchi.Fn Plwp_setxregs 17043051d27SRobert Mustacchifunction will fail if: 17143051d27SRobert Mustacchi.Bl -tag -width Er 17243051d27SRobert Mustacchi.It Er ENODATA 17343051d27SRobert MustacchiThe process handle 17443051d27SRobert Mustacchi.Fa P 17543051d27SRobert Mustacchidoes not have any extended register state information. 176*ed093b41SRobert MustacchiThis generally happens because the platform does not support it. 17743051d27SRobert Mustacchi.It Er EBUSY 17843051d27SRobert MustacchiThe process handle 17943051d27SRobert Mustacchi.Fa P 18043051d27SRobert Mustacchirefers to a live process and it is not stopped. 18143051d27SRobert Mustacchi.It Er ENOENT 182*ed093b41SRobert MustacchiThere is no thread with id 183*ed093b41SRobert Mustacchi.Fa lwpid 184*ed093b41SRobert Mustacchiin the process handle 185*ed093b41SRobert Mustacchi.Fa P . 18643051d27SRobert Mustacchi.El 18743051d27SRobert MustacchiThe 188*ed093b41SRobert Mustacchi.Fn Lgetxregs 18943051d27SRobert Mustacchiand 190*ed093b41SRobert Mustacchi.Fn Lsetxregs 191*ed093b41SRobert Mustacchifunction will fail if: 192*ed093b41SRobert Mustacchi.Bl -tag -width Er 193*ed093b41SRobert Mustacchi.It Er ENODATA 194*ed093b41SRobert MustacchiThe thread handle 195*ed093b41SRobert Mustacchi.Fa L 196*ed093b41SRobert Mustacchidoes not have any extended register state information. 197*ed093b41SRobert MustacchiThis generally happens because the platform does not support it. 198*ed093b41SRobert Mustacchi.It Er EBUSY 199*ed093b41SRobert MustacchiThe thread handle 200*ed093b41SRobert Mustacchi.Fa L 201*ed093b41SRobert Mustacchirefers to a live process and the thread is not stopped. 202*ed093b41SRobert Mustacchi.El 20343051d27SRobert Mustacchi.Sh INTERFACE STABILITY 20443051d27SRobert Mustacchi.Sy Uncommitted 20543051d27SRobert Mustacchi.Sh MT-LEVEL 20643051d27SRobert MustacchiSee 20743051d27SRobert Mustacchi.Sy LOCKING 20843051d27SRobert Mustacchiin 20943051d27SRobert Mustacchi.Xr libproc 3LIB . 21043051d27SRobert Mustacchi.Sh SEE ALSO 21143051d27SRobert Mustacchi.Xr libproc 3LIB , 21243051d27SRobert Mustacchi.Xr Plwp_getfpregs 3PROC , 21343051d27SRobert Mustacchi.Xr Plwp_getregs 3PROC , 21443051d27SRobert Mustacchi.Xr Plwp_setfpregs 3PROC , 21543051d27SRobert Mustacchi.Xr Plwp_setregs 3PROC , 21643051d27SRobert Mustacchi.Xr Pstop 3PROC , 217bbf21555SRichard Lowe.Xr proc 5 218