| blob | c331a4d6b3e20a2e201d6ca4a5dc719617143b2a |
1 '\" te
2 .\" Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH __SPARC_UTRAP_INSTALL 2 "Nov 11, 1997"
7 .SH NAME
8 __sparc_utrap_install \- install a SPARC V9 user trap handler
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/utrap.h>
14 \fBint\fR \fB__sparc_utrap_install\fR(\fButrap_entry_t\fR \fItype\fR,
15 \fButrap_handler_t\fR \fInew_precise\fR, \fButrap_handler_t\fR \fInew_deferred\fR,
16 \fButrap_handler_t *\fR\fIold_precise\fR, \fButrap_handler_t *\fR\fIold_deferred\fR);
17 .fi
19 .SH DESCRIPTION
20 .sp
21 .LP
22 The \fB__sparc_utrap_install()\fR function establishes \fInew_precise\fR and
23 \fInew_deferred\fR user trap handlers as the new values for the specified
24 \fItype\fR and returns the existing user trap handler values in
25 \fB*\fR\fIold_precise\fR and \fB*\fR\fIold_deferred\fR in a single atomic
26 operation. A new handler address of \fINULL\fR means no user handler of that
27 type will be installed. A new handler address of \fBUTH_NOCHANGE\fR means that
28 the user handler for that type should not be changed. An old handler pointer of
29 \fINULL\fR means that the user is not interested in the old handler address.
30 .sp
31 .LP
32 A \fIprecise trap\fR is caused by a specific instruction and occurs before any
33 program-visible state has been changed by this instruction. When a precise trap
34 occurs, the program counter (PC) saved in the Trap Program Counter (TPC)
35 register points to the instruction that induced the trap; all instructions
36 prior to this trapping instruction have been executed. The next program
37 counter (nPC) saved in the Trap Next Program Counter (TnPC) register points to
38 the next instruction following the trapping instruction, which has not yet been
39 executed. A \fIdeferred trap\fR is also caused by a particular instruction,
40 but unlike a precise trap, a deferred trap may occur after the program-visible
41 state has been changed. See the \fISPARC Architecture Manual, Version 9\fR for
42 further information on precise and deferred traps.
43 .sp
44 .LP
45 The list that follows contains hardware traps and their corresponding user trap
46 types. User trap types marked with a plus-sign (\fB+\fR) are required and must
47 be provided by all ABI-conforming implementations. The others may not be
48 present on every implementation; an attempt to install a user trap handler for
49 those conditions will return \fBEINVAL\fR. User trap types marked with an
50 asterisk (\fB*\fR) are implemented as precise traps only.
51 .sp
53 .sp
54 .TS
55 box;
56 c | c
57 l | l .
58 \fBTrap Name\fR \fBUser Trap Type (utrap_entry_t)\fR
59 _
60 \fBillegal_instruction\fR T{
61 \fBUT_ILLTRAP_INSTRUCTION\fR +*\fB or UT_ILLEGAL_INSTRUCTION\fR
62 T}
63 _
64 \fBfp_disabled\fR \fBUT_FP_DISABLED\fR +*
65 _
66 \fBfp_exception_ieee_754\fR \fBUT_FP_EXCEPTION_IEEE_754\fR +
67 _
68 \fBfp_exception_other\fR \fBUT_FP_EXCEPTION_OTHER\fR
69 _
70 \fBtag_overflow\fR \fBUT_TAG_OVERFLOW\fR +*
71 _
72 \fBdivision_by_zero\fR \fBUT_DIVISION_BY_ZERO\fR +
73 _
74 \fBmem_address_not_aligned\fR \fBUT_MEM_ADDRESS_NOT_ALIGNED\fR +
75 _
76 \fBprivileged_action\fR \fBUT_PRIVILEGED_ACTION\fR +
77 _
78 \fBprivileged_opcode\fR \fBUT_PRIVILEGED_OPCODE\fR
79 _
80 \fBasync_data_error\fR \fBUT_ASYNC_DATA_ERROR\fR
81 _
82 \fBtrap_instruction\fR T{
83 \fBUT_TRAP_INSTRUCTION_16 \fRthrough \fBUT_TRAP_INSTRUCTION_31\fR +*
84 T}
85 _
86 T{
87 \fBinstruction_access_exception\fR \fBinstruction_access_MMU_miss\fR \fBinstruction_access_error\fR
88 T} T{
89 \fBUT_INSTRUCTION_EXCEPTION \fRor \fBUT_INSTRUCTION_PROTECTION \fRor \fBUT_INSTRUCTION_ERROR \fR
90 T}
91 _
92 T{
93 \fBdata_access_exception\fR \fBdata_access_MMU_miss\fR \fBdata_access_error\fR \fBdata_access_protection\fR
94 T} T{
95 \fBUT_DATA_EXCEPTION \fRor \fBUT_DATA_PROTECTION \fRor \fBUT_DATA_ERROR\fR
96 T}
97 .TE
99 .sp
100 .LP
101 The following explanations are provided for those user trap types that are not
102 self-explanatory.
103 .sp
104 .ne 2
105 .na
106 \fB\fBUT_ILLTRAP_INSTRUCTION\fR\fR
107 .ad
108 .sp .6
109 .RS 4n
110 This trap is raised by user execution of the \fBILLTRAP\fR \fBINSTRUCTION.\fR
111 It is always precise.
112 .RE
114 .sp
115 .ne 2
116 .na
117 \fB\fBUT_ILLEGAL_INSTRUCTION\fR\fR
118 .ad
119 .sp .6
120 .RS 4n
121 This trap will be raised by the execution of otherwise undefined opcodes. It is
122 implementation-dependent as to what opcodes raise this trap; the ABI only
123 specifies the interface. The trap may be precise or deferred.
124 .RE
126 .sp
127 .ne 2
128 .na
129 \fB\fBUT_PRIVILEGED_OPCODE\fR\fR
130 .ad
131 .sp .6
132 .RS 4n
133 All opcodes declared to be privileged in SPARC V9 will raise this trap. It is
134 implementation-dependent whether other opcodes will raise it as well; the ABI
135 only specifies the interface.
136 .RE
138 .sp
139 .ne 2
140 .na
141 \fB\fBUT_DATA_EXCEPTION,\fR \fBUT_INSTRUCTION_EXCEPTION\fR\fR
142 .ad
143 .sp .6
144 .RS 4n
145 No valid user mapping can be made to this address, for a data or instruction
146 access, respectively.
147 .RE
149 .sp
150 .ne 2
151 .na
152 \fB\fBUT_DATA_PROTECTION,\fR \fBUT_INSTRUCTION_PROTECTION\fR\fR
153 .ad
154 .sp .6
155 .RS 4n
156 A valid mapping exists, and user privilege to it exists, but the type of access
157 (read, write, or execute) is denied, for a data or instruction access,
158 respectively.
159 .RE
161 .sp
162 .ne 2
163 .na
164 \fB\fBUT_DATA_ERROR,\fR \fBUT_INSTRUCTION_ERROR\fR\fR
165 .ad
166 .sp .6
167 .RS 4n
168 A valid mapping exists, and both user privilege and the type of access are
169 allowed, but an unrecoverable error occurred in attempting the access, for a
170 data or instruction access, respectively. \fB%l1\fR will contain either
171 \fBBUS_ADDRERR\fR or \fBBUS_OBJERR.\fR
172 .RE
174 .sp
175 .ne 2
176 .na
177 \fB\fBUT_FP_DISABLED\fR\fR
178 .ad
179 .sp .6
180 .RS 4n
181 This trap is raised when an application issues a floating point instruction
182 (including load or store) and the SPARC V9 Floating Point Registers State
183 (FPRS) FEF bit is 0. If a user handler is installed for this trap, it will be
184 given control. Otherwise the system will set FEF to one and retry the
185 instruction.
186 .RE
188 .sp
189 .LP
190 For all traps, the handler executes in a new register window, where the
191 \fIin\fR registers are the \fIout\fR registers of the previous frame and have
192 the value they contained at the time of the trap, similar to a normal
193 subroutine call after the \fBsave\fR instruction. The \fIglobal\fR registers
194 (including the special registers \fB%ccr\fR, \fB%asi\fR, and \fB%y\fR) and the
195 \fIfloating-point\fR registers have their values from the time of the trap. The
196 stack pointer register \fB%sp\fR plus the BIAS will point to a properly-aligned
197 128-byte register save area; if the handler needs scratch space, it should
198 decrement the stack pointer to obtain it. If the handler needs access to the
199 previous frame's \fIin\fR registers or \fIlocal\fR registers, it should execute
200 a \fBFLUSHW\fR instruction, and then access them off of the frame pointer. If
201 the handler calls an ABI-conforming function, it must set the \fB%asi\fR
202 register to \fBASI_PRIMARY_NOFAULT\fR before the call.
203 .sp
204 .LP
205 On entry to a precise user trap handler \fB%l6\fR contains the \fB%pc\fR and
206 \fB%l7\fR contains the \fB%npc\fR at the time of the trap. To return from a
207 handler and reexecute the trapped instruction, the handler would execute:
208 .sp
209 .in +2
210 .nf
211 jmpl %l6, %g0 ! Trapped PC supplied to user trap handler
212 return %l7 ! Trapped nPC supplied to user trap handler
213 .fi
214 .in -2
215 .sp
217 .sp
218 .LP
219 To return from a handler and skip the trapped instruction, the handler would
220 execute:
221 .sp
222 .in +2
223 .nf
224 jmpl %l7, %g0 ! Trapped nPC supplied to user trap handler
225 return %l7 + 4 ! Trapped nPC + 4
226 .fi
227 .in -2
228 .sp
230 .sp
231 .LP
232 On entry to a deferred trap handler \fB%o0\fR contains the address of the
233 instruction that caused the trap and \fB%o1\fR contains the actual instruction
234 (right-justified, zero-extended), if the information is available. Otherwise
235 \fB%o0\fR contains the value \(mi1 and \fB%o1\fR is undefined. Additional
236 information may be made available for certain cases of deferred traps, as
237 indicated in the following table.
238 .sp
240 .sp
241 .TS
242 box;
243 l | l
244 l | l .
245 \fBInstructions\fR \fBAdditional Information\fR
246 _
247 LD-type (LDSTUB) T{
248 \fB%o2\fR contains the effective address (\fIrs1\fR + \fIrs2\fR | \fIsimm13\fR).
249 T}
250 _
251 ST-type (CAS, SWAP) T{
252 \fB%o2\fR contains the effective address (\fI rs1\fR + \fIrs2\fR |\fIsimm13\fR).
253 T}
254 _
255 Integer arithmetic T{
256 \fB%o2\fR contains the \fIrs1\fR value. \fB%o3\fR contains the \fIrs2\fR | \fIsimm13\fR value. \fB%o4\fR contains the contents of the \fB%y\fR register.
257 T}
258 _
259 Floating-point arithmetic T{
260 \fB%o2\fR contains the address of \fIrs1\fR value. \fB%o3\fR contains the address of \fIrs2\fR value.
261 T}
262 _
263 Control-transfer T{
264 \fB%o2\fR contains the target address (\fIrs1\fR + \fIrs2\fR | \fIsimm13\fR).
265 T}
266 _
267 Asynchronous data errors T{
268 \fB%o2\fR contains the address that caused the error. \fB%o3\fR contains the effective ASI, if available, else \(mi1.
269 T}
270 .TE
272 .sp
273 .LP
274 To return from a deferred trap, the trap handler issues:
275 .sp
276 .LP
277 ta 68 ! ST_RETURN_FROM_DEFERRED_TRAP
278 .sp
279 .LP
280 The following pseudo-code explains how the operating system dispatches traps:
281 .sp
282 .in +2
283 .nf
284 if (precise trap) {
285 if (precise_handler) {
286 invoke(precise_handler);
287 /* not reached */
288 } else {
289 convert_to_signal(precise_trap);
290 }
291 } else if (deferred_trap) {
292 invoke(deferred_handler);
293 /* not reached */
294 } else {
295 convert_to_signal(deferred_trap);
296 }
297 }
298 if (signal)
299 send(signal);
300 .fi
301 .in -2
303 .sp
304 .LP
305 User trap handlers must preserve all registers except the \fIlocals\fR
306 (\fB%l0-7\fR) and the \fIouts\fR (\fB%o0-7\fR), that is, \fB%i0-7\fR,
307 \fB%g1-7\fR, \fB%d0-d62\fR, \fB%asi\fR, \fB%fsr\fR, \fB%fprs\fR, \fB%ccr\fR,
308 and \fB%y,\fR except to the extent that modifying the registers is part of the
309 desired functionality of the handler. For example, the handler for
310 \fBUT_FP_DISABLED\fR may load floating-point registers.
311 .SH RETURN VALUES
312 .sp
313 .LP
314 Upon successful completion, \fB0\fR is returned. Otherwise, a non-zero value is
315 returned and \fBerrno\fR is set to indicate the error.
316 .SH ERRORS
317 .sp
318 .LP
319 The \fB__sparc_utrap_install()\fR function will fail if:
320 .sp
321 .ne 2
322 .na
323 \fB\fBEINVAL\fR\fR
324 .ad
325 .RS 10n
326 The \fItype\fR argument is not a supported user trap type; the new user trap
327 handler address is not word aligned; the old user trap handler address cannot
328 be returned; or the user program is not a 64-bit executable.
329 .RE
331 .SH EXAMPLES
332 .LP
333 \fBExample 1 \fRA sample program using the \fB__sparc_utrap_install()\fR
334 function.
335 .sp
336 .LP
337 The \fB__sparc_utrap_install()\fR function is normally used by user programs
338 that wish to provide their own tailored exception handlers as a faster
339 alternative to \fBsignal\fR(3C), or to handle exceptions that are not directly
340 supported by the \fBsignal()\fR interface, such as \fBfp_disabled\fR.
342 .sp
343 .in +2
344 .nf
345 extern void *fpdis_trap_handler();
346 utrap_handler_t new_precise = (utrap_handler_t)fpdis_trap_handler;
347 double d;
348 int err;
349 err = __sparc_utrap_install(UT_FP_DISABLED, new_precise,
350 UTH_NOCHANGE, NULL, NULL);
351 if (err == EINVAL) {
352 /* unexpected error, do something */
353 exit (1);
354 }
355 d = 1.0e-300;
356 ENTRY(fpdis_trap_handler)
357 wr %g0, FPRS_FEF, %fprs
358 jmpl %l6, %g0
359 return %l7
360 SET_SIZE(fpdis_trap_handler)
361 .fi
362 .in -2
364 .sp
365 .LP
366 This example turns on bit 2, FEF, in the Floating-Point Registers State (FPRS)
367 Register, after a floating-point instruction causes an \fBfp_disabled\fR trap.
368 (Note that this example simulates part of the default system behavior; programs
369 do not need such a handler. The example is for illustrative purposes only.)
371 .SH ATTRIBUTES
372 .sp
373 .LP
374 See \fBattributes\fR(5) for descriptions of the following attributes:
375 .sp
377 .sp
378 .TS
379 box;
380 c | c
381 l | l .
382 ATTRIBUTE TYPE ATTRIBUTE VALUE
383 _
384 MT-Level MT-Safe
385 .TE
387 .SH SEE ALSO
388 .sp
389 .LP
390 \fBsignal\fR(3C), \fBattributes\fR(5)
391 .sp
392 .LP
393 \fISPARC Architecture Manual, Version 9\fR
394 .sp
395 .LP
396 Manufacturer's processor chip user manuals
397 .SH NOTES
398 .sp
399 .LP
400 The Exceptions and Interrupt Descriptions section of the SPARC V9 manual
401 documents which hardware traps are mandatory or optional, and whether they can
402 be implemented as precise or deferred traps, or both. The manufacturer's
403 processor chip user manuals describe the details of the traps supported for the
404 specific processor implementation.