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
  61 The
  62 .Fn Plwp_getxregs
  63 and
  64 .Fn Plwp_setxregs
  65 functions get and set the extended register state of the thread
  66 .Fa lwpid
  67 in the process handle
  68 .Fa P .
  69 .Pp
  70 The extended register state is defined by the architecture.
  71 These registers may refer to optional registers that have become common on the
  72 platform, but are not part of the traditional ABI and thus not covered by
  73 functions such as
  74 .Xr Plwp_getregs 3PROC
  75 and
  76 .Xr Plwp_getfpregs 3PROC .
  77 Support for the extended registers varies based on the architecture and
  78 varies based on the specific system.
  79 For example, on x86 based CPUs the xregs functionality requires the x86
  80 xsave functionality to be supported.
  81 .Pp
  82 The
  83 .Fn Plwp_getxregs
  84 function gets the extended register state information, allocates the
  85 appropriate sized buffer for it, and places a pointer to that buffer
  86 into
  87 .Fa xregs
  88 and updates
  89 .Fa sizep
  90 to indicate the size of the allocated structure.
  91 Due to the fact that hardware has varying sized extended register sets,
  92 the exact size of the structure can vary between different running
  93 systems and core files.
  94 It is also possible that some processor extensions are enabled at
  95 process runtime, leading for this to further be different between
  96 different processes on the same system.
  97 As such, all of the different platform instantiations of the
  98 .Vt prxregset_t
  99 end up generally being opaque structures that can be cast to something
 100 more specific that also includes its size.
 101 .Pp
 102 The obtained
 103 .Vt prxregset_t
 104 in
 105 .Fa xregsp
 106 must be freed by the caller with the
 107 .Fn Plwp_freexregs
 108 function.
 109 .Pp
 110 The
 111 .Fn Plwp_setxregs
 112 function sets the extended register state information in
 113 .Fa xregs
 114 for the process handle
 115 .Fa P .
 116 .Pp
 117 Processes must be stopped prior to obtaining the register state of
 118 individual threads.
 119 Processes may be stopped with
 120 .Xr Pstop 3PROC .
 121 .Pp
 122 The
 123 .Sy prxregset_t
 124 structure is described in
 125 .Xr proc 5 .
 126 .Pp
 127 One may not set the register values of a process that is not an active
 128 process, e.g. a process handle that refers to a file or a core file.
 129 .Pp
 130 The
 131 .Fn Lgetxregs
 132 and
 133 .Fn Lsetxregs
 134 functions are equivalent to the
 135 .Fn Plwp_getxregs
 136 and
 137 .Fn Plwp_setxregs
 138 functions except that they operate on a specific thread identified by
 139 the handle
 140 .Fa L
 141 and only require that the thread in question be stopped.
 142 Data allocated with the
 143 .Fn Lgetxregs
 144 functions should be freed with the
 145 .Fn Plwp_freexregs
 146 function.
 147 .Sh RETURN VALUES
 148 Upon successful completion, the
 149 .Fn Plwp_getxregs
 150 and
 151 .Fn Plwp_setxregs
 152 functions return
 153 .Sy 0
 154 and get or set the register state.
 155 Otherwise,
 156 .Sy -1
 157 is returned and
 158 .Sy errno
 159 is set to indicate the error.
 160 .Sh ERRORS
 161 For a full list of possible errors see the
 162 .Sy DIAGNOSTICS
 163 section in
 164 .Xr proc 5 .
 165 .Pp
 166 The
 167 .Fn Plwp_getxregs
 168 and
 169 .Fn Plwp_setxregs
 170 function will fail if:
 171 .Bl -tag -width Er
 172 .It Er ENODATA
 173 The process handle
 174 .Fa P
 175 does not have any extended register state information.
 176 This generally happens because the platform does not support it.
 177 .It Er EBUSY
 178 The process handle
 179 .Fa P
 180 refers to a live process and it is not stopped.
 181 .It Er ENOENT
 182 There is no thread with id
 183 .Fa lwpid
 184 in the process handle
 185 .Fa P .
 186 .El
 187 The
 188 .Fn Lgetxregs
 189 and
 190 .Fn Lsetxregs
 191 function will fail if:
 192 .Bl -tag -width Er
 193 .It Er ENODATA
 194 The thread handle
 195 .Fa L
 196 does not have any extended register state information.
 197 This generally happens because the platform does not support it.
 198 .It Er EBUSY
 199 The thread handle
 200 .Fa L
 201 refers to a live process and the thread is not stopped.
 202 .El
 203 .Sh INTERFACE STABILITY
 204 .Sy Uncommitted
 205 .Sh MT-LEVEL
 206 See
 207 .Sy LOCKING
 208 in
 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