Print this page
15254 %ymm registers not restored after signal handler
15367 x86 getfpregs() summons corrupting %xmm ghosts
15333 want x86 /proc xregs support (libc_db, libproc, mdb, etc.)
15336 want libc functions for extended ucontext_t
15334 want ps_lwphandle-specific reg routines
15328 FPU_CW_INIT mistreats reserved bit
15335 i86pc fpu_subr.c isn't really platform-specific
15332 setcontext(2) isn't actually noreturn
15331 need <sys/stdalign.h>
Change-Id: I7060aa86042dfb989f77fc3323c065ea2eafa9ad
Conflicts:
usr/src/uts/common/fs/proc/prcontrol.c
usr/src/uts/intel/os/archdep.c
usr/src/uts/intel/sys/ucontext.h
usr/src/uts/intel/syscall/getcontext.c
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/makecontext.3c
+++ new/usr/src/man/man3c/makecontext.3c
1 1 .\"
2 2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 3 .\" permission to reproduce portions of its copyrighted documentation.
4 4 .\" Original documentation from The Open Group can be obtained online at
5 5 .\" http://www.opengroup.org/bookstore/.
6 6 .\"
7 7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 8 .\" Group, have given us permission to reprint portions of their
9 9 .\" documentation.
10 10 .\"
11 11 .\" In the following statement, the phrase ``this text'' refers to portions
12 12 .\" of the system documentation.
13 13 .\"
14 14 .\" Portions of this text are reprinted and reproduced in electronic form
15 15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 16 .\" Standard for Information Technology -- Portable Operating System
17 17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 20 .\" between these versions and the original IEEE and The Open Group
21 21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 22 .\" document. The original Standard can be obtained online at
23 23 .\" http://www.opengroup.org/unix/online.html.
24 24 .\"
25 25 .\" This notice shall appear on any product containing this material.
26 26 .\"
27 27 .\" The contents of this file are subject to the terms of the
28 28 .\" Common Development and Distribution License (the "License").
29 29 .\" You may not use this file except in compliance with the License.
30 30 .\"
31 31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 32 .\" or http://www.opensolaris.org/os/licensing.
33 33 .\" See the License for the specific language governing permissions
34 34 .\" and limitations under the License.
35 35 .\"
|
↓ open down ↓ |
35 lines elided |
↑ open up ↑ |
36 36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 38 .\" If applicable, add the following below this CDDL HEADER, with the
39 39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 41 .\"
42 42 .\"
43 43 .\" Copyright 1989 AT&T
44 44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 45 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
46 +.\" Copyright 2023 Oxide Computer Company
46 47 .\"
47 -.TH MAKECONTEXT 3C "February 17, 2023"
48 -.SH NAME
49 -makecontext, swapcontext \- manipulate user contexts
50 -.SH SYNOPSIS
51 -.nf
52 -#include <ucontext.h>
53 -
54 -\fBvoid\fR \fBmakecontext\fR(\fBucontext_t *\fR\fIucp\fR, \fBvoid (*\fR\fIfunc\fR)(), \fBint\fR \fIargc\fR...);
55 -.fi
56 -
57 -.LP
58 -.nf
59 -\fBint\fR \fBswapcontext\fR(\fBucontext_t *restrict\fR \fIoucp\fR,
60 - \fBconst ucontext_t *restrict\fR \fIucp\fR);
61 -.fi
62 -
63 -.SH DESCRIPTION
64 -The \fBmakecontext()\fR function modifies the context specified by \fIucp\fR,
65 -which has been initialized using \fBgetcontext\fR(2). When this context is
66 -resumed using \fBswapcontext()\fR or \fBsetcontext\fR(2), execution continues
67 -by calling the function \fIfunc\fR, passing it the arguments that follow
68 -\fIargc\fR in the \fBmakecontext()\fR call. The value of \fIargc\fR must match
69 -the number of pointer-sized integer arguments passed to \fIfunc\fR, otherwise
70 -the behavior is undefined.
71 -.sp
72 -.LP
73 -Before a call is made to \fBmakecontext()\fR, the context being modified should
74 -have a stack allocated for it. The stack is assigned to the context by
75 -initializing the \fBuc_stack\fR member.
76 -.sp
77 -.LP
78 -The \fBuc_link\fR member is used to determine the context that will be resumed
79 -when the context being modified by \fBmakecontext()\fR returns. The
80 -\fBuc_link\fR member should be initialized prior to the call to
81 -\fBmakecontext()\fR. If the \fBuc_link\fR member is initialized to \fINULL\fR,
82 -the thread executing \fIfunc\fR will exit when \fIfunc\fR returns. See
83 -\fBpthread_exit\fR(3C).
84 -.sp
85 -.LP
86 -The \fBswapcontext()\fR function saves the current context in the context
87 -structure pointed to by \fIoucp\fR and sets the context to the context
88 -structure pointed to by \fIucp\fR.
89 -.sp
90 -.LP
91 -If the \fIucp\fR or \fIoucp\fR argument points to an invalid address, the
92 -behavior is undefined and \fBerrno\fR may be set to \fBEFAULT\fR.
93 -.SH RETURN VALUES
94 -On successful completion, \fBswapcontext()\fR returns \fB0\fR. Otherwise,
95 -\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error.
96 -.SH ERRORS
97 -The \fBswapcontext()\fR function will fail if:
98 -.sp
99 -.ne 2
100 -.na
101 -\fB\fBENOMEM\fR\fR
102 -.ad
103 -.RS 10n
104 -The \fIucp\fR argument does not have enough stack left to complete the
105 -operation.
106 -.RE
107 -
108 -.sp
109 -.LP
110 -The \fBswapcontext()\fR function may fail if:
111 -.sp
112 -.ne 2
113 -.na
114 -\fB\fBEFAULT\fR\fR
115 -.ad
116 -.RS 10n
117 -The \fIucp\fR or \fIoucp\fR argument points to an invalid address.
118 -.RE
119 -
120 -.SH EXAMPLES
121 -\fBExample 1 \fRAlternate execution context on a stack whose memory was
122 -allocated using \fBmmap()\fR.
123 -.sp
124 -.in +2
125 -.nf
48 +.Dd March 20, 2023
49 +.Dt MAKECONTEXT 3C
50 +.Os
51 +.Sh NAME
52 +.Nm makecontext ,
53 +.Nm swapcontext ,
54 +.Nm swapcontext_extd
55 +.Nd manipulate user contexts
56 +.Sh SYNOPSIS
57 +.In ucontext.h
58 +.Ft void
59 +.Fo makecontext
60 +.Fa "ucontext_t *ucp"
61 +.Fa "void (*ifunc)()"
62 +.Fa "int argc"
63 +.Fa "..."
64 +.Fc
65 +.Ft int
66 +.Fo swapcontext
67 +.Fa "ucontext_t *restrict oucp"
68 +.Fa "const ucontext_t *restrict ucp"
69 +.Fc
70 +.Ft int
71 +.Fo swapcontext_extd
72 +.Fa "ucontext_t *restrict oucp"
73 +.Fa "uint32_t flags"
74 +.Fa "const ucontext_t *restrict ucp"
75 +.Fc
76 +.Sh DESCRIPTION
77 +The
78 +.Fn makecontext
79 +function modifies the context specified by
80 +.Fa ucp ,
81 +which has been initialized using
82 +.Xr getcontext 2 or
83 +.Xr getcontext_extd 2 .
84 +When this context is resumed using
85 +.Fn swapcontext ,
86 +.Fn swapcontext_extd ,
87 +or
88 +.Xr setcontext 2 ,
89 +execution continues by calling the function
90 +.Fa func ,
91 +passing it the arguments that follow
92 +.Fa argc
93 +in the
94 +.Fn makecontext
95 +call.
96 +The value of
97 +.Fa argc
98 +must match the number of pointer-sized integer arguments passed to
99 +.Fa func ,
100 +otherwise the behavior is undefined.
101 +.Pp
102 +Before a call is made to
103 +.Fn makecontext ,
104 +the context being modified should have a stack allocated for it.
105 +The stack is assigned to the context by initializing the
106 +.Fa uc_stack
107 +member.
108 +.Pp
109 +The
110 +.Fa uc_link
111 +member is used to determine the context that will be resumed when the context
112 +being modified by
113 +.Fn makecontext
114 +returns.
115 +The
116 +.Fa uc_link
117 +member should be initialized prior to the call to
118 +.Fn makecontext .
119 +If the
120 +.Fa uc_link
121 +member is initialized to
122 +.Dv NULL ,
123 +the thread executing
124 +.Fa func
125 +will exit when
126 +.Fa func returns.
127 +See
128 +.Xr pthread_exit 3C .
129 +.Pp
130 +The
131 +.Fn swapcontext
132 +function saves the current context in the context structure pointed to by
133 +.Fa oucp
134 +and sets the context to the context structure pointed to by
135 +.Fa ucp .
136 +.Pp
137 +If the
138 +.Fa ucp
139 +or
140 +.Fa oucp
141 +argument points to an invalid address, the behavior is undefined and
142 +.Va errno
143 +may be set to
144 +.Er EFAULT .
145 +.Pp
146 +The
147 +.Fn swapcontext_extd
148 +function is similar to
149 +.Fn swapcontext
150 +except that it performs a call to
151 +.Xr getcontext_extd 2
152 +to get and save the current context, passing the
153 +.Fa flags
154 +argument to
155 +.Xr getcontext_extd 2 .
156 +Note, the same constraints around the initialization of the
157 +.Vt ucontext_t
158 +that are discussed in
159 +.Xr getcontext_extd 2
160 +still apply.
161 +Mainly, the context must either have originally come from
162 +.Xr ucontext_alloc 3C
163 +or prior to its first use been zeroed.
164 +See
165 +.Xr getcontext_extd 2
166 +for more information.
167 +.Sh RETURN VALUES
168 +On successful completion,
169 +.Fn swapcontext
170 +and
171 +.Fn swapcontext_extd
172 +return
173 +.Sy 0 .
174 +Otherwise,
175 +.Sy -1
176 +is returned and
177 +.Va errno
178 +is set to indicate the error.
179 +.Sh EXAMPLES
180 +.Sy Example 1
181 +Alternate execution context on a stack whose memory was allocated using
182 +.Fn mmap .
183 +.Bd -literal -offset 2
126 184 #include <stdio.h>
127 185 #include <ucontext.h>
128 186 #include <sys/mman.h>
129 187
130 188 void
131 189 assign(long a, int *b)
132 190 {
133 191 *b = (int)a;
134 192 }
135 193
136 194 int
137 195 main(int argc, char **argv)
138 196 {
139 197 ucontext_t uc, back;
140 198 size_t sz = 0x10000;
141 199 int value = 0;
142 200
143 201 getcontext(&uc);
144 202
145 203 uc.uc_stack.ss_sp = mmap(0, sz,
146 204 PROT_READ | PROT_WRITE | PROT_EXEC,
147 205 MAP_PRIVATE | MAP_ANON, -1, 0);
148 206 uc.uc_stack.ss_size = sz;
149 207 uc.uc_stack.ss_flags = 0;
|
↓ open down ↓ |
14 lines elided |
↑ open up ↑ |
150 208
151 209 uc.uc_link = &back;
152 210
153 211 makecontext(&uc, assign, 2, 100L, &value);
154 212 swapcontext(&back, &uc);
155 213
156 214 printf("done %d\en", value);
157 215
158 216 return (0);
159 217 }
160 -.fi
161 -.in -2
162 -
163 -.SH USAGE
218 +.Ed
219 +.Sh ERRORS
220 +The
221 +.Fn swapcontext
222 +and
223 +.Fn swapcontext_extd
224 +function will fail if:
225 +.Bl -tag -width Er
226 +.It Er ENOMEM
227 +The
228 +.Fa ucp
229 +argument does not have enough stack left to complete the operation.
230 +.El
231 +.Pp
232 +The
233 +.Fn swapcontext
234 +and
235 +.Fn swapcontext_extd
236 +functions may fail if:
237 +.Bl -tag -width Er
238 +.It Er EFAULT
239 +The
240 +.Fa ucp
241 +or
242 +.Fa oucp
243 +argument points to an invalid address.
244 +.El
245 +.Pp
246 +The
247 +.Fn swapcontext_extd
248 +function may additionally fail if:
249 +.Bl -tag -width Er
250 +.It Er EINVAL
251 +The
252 +.Fa flags
253 +argument contains invalid values.
254 +.El
255 +.Sh USAGE
164 256 These functions are useful for implementing user-level context switching
165 -between multiple threads of control within a process (co-processing). More
166 -effective multiple threads of control can be obtained by using native support
167 -for multithreading. See \fBthreads\fR(7).
168 -.SH ATTRIBUTES
169 -See \fBattributes\fR(7) for descriptions of the following attributes:
170 -.sp
171 -
172 -.sp
173 -.TS
174 -box;
175 -c | c
176 -l | l .
177 -ATTRIBUTE TYPE ATTRIBUTE VALUE
178 -_
179 -Interface Stability Standard
180 -_
181 -MT-Level MT-Safe
182 -.TE
183 -
184 -.SH SEE ALSO
185 -.BR getcontext (2),
186 -.BR mmap (2),
187 -.BR sigaction (2),
188 -.BR sigprocmask (2),
189 -.BR pthread_exit (3C),
190 -.BR ucontext.h (3HEAD),
191 -.BR attributes (7),
192 -.BR standards (7),
193 -.BR threads (7)
194 -.SH NOTES
195 -The semantics of the \fBuc_stack\fR member of the \fBucontext_t\fR structure
196 -have changed as they apply to inputs to \fBmakecontext()\fR. Prior to Solaris
197 -10, the \fBss_sp\fR member of the \fBuc_stack\fR structure represented the high
198 -memory address of the area reserved for the stack. The \fBss_sp\fR member now
199 -represents the base (low memory address), in keeping with other uses of
200 -\fBss_sp\fR.
201 -.sp
202 -.LP
203 -This change in the meaning of \fBss_sp\fR is now the default behavior. The
204 -\fB-D__MAKECONTEXT_V2_SOURCE\fR compilation flag used in Solaris 9 update
205 -releases to access this behavior is obsolete.
206 -.sp
207 -.LP
257 +between multiple threads of control within a process
258 +.Pq co-processing .
259 +More effective multiple threads of control can be obtained by using native
260 +support for multithreading.
261 +See
262 +.Xr threads 7 .
263 +.Sh INTERFACE STABILITY
264 +.Sy Committed
265 +.Sh MT-LEVEL
266 +.Sy MT-Safe
267 +.Sh SEE ALSO
268 +.Xr getcontext 2 ,
269 +.Xr getcontext_extd 2 ,
270 +.Xr mmap 2 ,
271 +.Xr sigaction 2 ,
272 +.Xr sigprocmask 2 ,
273 +.Xr pthread_exit 3C ,
274 +.Xr ucontext_alloc 3C ,
275 +.Xr ucontext.h 3HEAD ,
276 +.Xr attributes 7 ,
277 +.Xr standards 7 ,
278 +.Xr threads 7
279 +.Sh NOTES
280 +The semantics of the
281 +.Fa uc_stack
282 +member of the
283 +.Fa ucontext_t
284 +structure have changed as they apply to inputs to
285 +.Fn makecontext .
286 +Prior to Solaris 10, the
287 +.Fa ss_sp
288 +member of the
289 +.Fa uc_stack
290 +tructure represented the high memory address of the area reserved for the stack.
291 +The
292 +.Fa ss_sp
293 +member now represents the base
294 +.Pq low memory address ,
295 +in keeping with other uses of
296 +.Fa ss_sp .
297 +This change in the meaning of
298 +.Fa ss_sp
299 +is the default behavior.
300 +.Pp
208 301 Binary compatibility has been preserved with releases prior to Solaris 10.
209 -Before recompiling, applications that use \fBmakecontext()\fR must be updated
210 -to reflect this behavior change. The example below demonstrates a typical change
211 -that must be applied:
212 -.sp
213 -.in +2
214 -.nf
302 +Before recompiling, applications that use
303 +.Fn makecontext
304 +must be updated to reflect this behavior change.
305 +The example below demonstrates a typical change that must be applied:
306 +.Bd -literal -offset 2
215 307 --- example1_s9.c Thu Oct 3 11:58:17 2002
216 308 +++ example1.c Thu Jun 27 13:28:16 2002
217 309 @@ -27,12 +27,9 @@
218 310 uc.uc_stack.ss_sp = mmap(0, sz,
219 311 PROT_READ | PROT_WRITE | PROT_EXEC,
220 312 MAP_PRIVATE | MAP_ANON, -1, 0);
221 313 - uc.uc_stack.ss_sp = (char *)uc.uc_stack.ss_sp + sz - 8;
222 314 uc.uc_stack.ss_size = sz;
223 315 uc.uc_stack.ss_flags = 0;
224 316
225 317 uc.uc_link = &back
226 318
227 319 makecontext(&uc, assign, 2, 100L, &value);
228 320 .fi
229 -.in -2
230 -
321 +.Ed
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX