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