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