1__sparc_utrap_install(2) System Calls __sparc_utrap_install(2)
2
6 __sparc_utrap_install - install a SPARC V9 user trap handler
7
9 #include <sys/utrap.h>
10 int __sparc_utrap_install(utrap_entry_t type,
12 utrap_handler_t new_precise, utrap_handler_t new_deferred,
13 utrap_handler_t *old_precise, utrap_handler_t *old_deferred);
14
17 The __sparc_utrap_install() function establishes new_precise and
18 new_deferred user trap handlers as the new values for the specified
19 type and returns the existing user trap handler values in *old_precise
20 and *old_deferred in a single atomic operation. A new handler address
21 of NULL means no user handler of that type will be installed. A new
22 handler address of UTH_NOCHANGE means that the user handler for that
23 type should not be changed. An old handler pointer of NULL means that
24 the user is not interested in the old handler address.
25 A precise trap is caused by a specific instruction and occurs before
28 any program-visible state has been changed by this instruction. When a
29 precise trap occurs, the program counter (PC) saved in the Trap Program
30 Counter (TPC) register points to the instruction that induced the trap;
31 all instructions prior to this trapping instruction have been executed.
32 The next program counter (nPC) saved in the Trap Next Program Counter
33 (TnPC) register points to the next instruction following the trapping
34 instruction, which has not yet been executed. A deferred trap is also
35 caused by a particular instruction, but unlike a precise trap, a
36 deferred trap may occur after the program-visible state has been
37 changed. See the SPARC Architecture Manual, Version 9 for further
38 information on precise and deferred traps.
39 The list that follows contains hardware traps and their corresponding
42 user trap types. User trap types marked with a plus-sign (+) are
43 required and must be provided by all ABI-conforming implementations.
44 The others may not be present on every implementation; an attempt to
45 install a user trap handler for those conditions will return EINVAL.
46 User trap types marked with an asterisk (*) are implemented as precise
47 traps only.
48 ┌─────────────────────────────┬───────────────────────────────┐
53 │ Trap Name │User Trap Type (utrap_entry_t) │
54 ├─────────────────────────────┼───────────────────────────────┤
55 │illegal_instruction │UT_ILLTRAP_INSTRUCTION +* or │
56 │ │UT_ILLEGAL_INSTRUCTION │
57 ├─────────────────────────────┼───────────────────────────────┤
58 │fp_disabled │UT_FP_DISABLED +* │
59 ├─────────────────────────────┼───────────────────────────────┤
60 │fp_exception_ieee_754 │UT_FP_EXCEPTION_IEEE_754 + │
61 ├─────────────────────────────┼───────────────────────────────┤
62 │fp_exception_other │UT_FP_EXCEPTION_OTHER │
63 ├─────────────────────────────┼───────────────────────────────┤
64 │tag_overflow │UT_TAG_OVERFLOW +* │
65 ├─────────────────────────────┼───────────────────────────────┤
66 │division_by_zero │UT_DIVISION_BY_ZERO + │
67 ├─────────────────────────────┼───────────────────────────────┤
68 │mem_address_not_aligned │UT_MEM_ADDRESS_NOT_ALIGNED + │
69 ├─────────────────────────────┼───────────────────────────────┤
70 │privileged_action │UT_PRIVILEGED_ACTION + │
71 ├─────────────────────────────┼───────────────────────────────┤
72 │privileged_opcode │UT_PRIVILEGED_OPCODE │
73 ├─────────────────────────────┼───────────────────────────────┤
74 │async_data_error │UT_ASYNC_DATA_ERROR │
75 ├─────────────────────────────┼───────────────────────────────┤
76 │trap_instruction │UT_TRAP_INSTRUCTION_16 through │
77 │ │UT_TRAP_INSTRUCTION_31 +* │
78 ├─────────────────────────────┼───────────────────────────────┤
79 │instruction_access_excep‐ │UT_INSTRUCTION_EXCEPTION or │
80 │tion instruc‐ │UT_INSTRUCTION_PROTECTION or │
81 │tion_access_MMU_miss │UT_INSTRUCTION_ERROR │
82 │instruction_access_error │ │
83 ├─────────────────────────────┼───────────────────────────────┤
84 │data_access_exception │UT_DATA_EXCEPTION or │
85 │data_access_MMU_miss │UT_DATA_PROTECTION or │
86 │data_access_error │UT_DATA_ERROR │
87 │data_access_protection │ │
88 └─────────────────────────────┴───────────────────────────────┘
89 The following explanations are provided for those user trap types that
92 are not self-explanatory.
93 UT_ILLTRAP_INSTRUCTION
95 This trap is raised by user execution of the ILLTRAP INSTRUCTION.
97 It is always precise.
98 UT_ILLEGAL_INSTRUCTION
101 This trap will be raised by the execution of otherwise undefined
103 opcodes. It is implementation-dependent as to what opcodes raise
104 this trap; the ABI only specifies the interface. The trap may be
105 precise or deferred.
106 UT_PRIVILEGED_OPCODE
109 All opcodes declared to be privileged in SPARC V9 will raise this
111 trap. It is implementation-dependent whether other opcodes will
112 raise it as well; the ABI only specifies the interface.
113 UT_DATA_EXCEPTION, UT_INSTRUCTION_EXCEPTION
116 No valid user mapping can be made to this address, for a data or
118 instruction access, respectively.
119 UT_DATA_PROTECTION, UT_INSTRUCTION_PROTECTION
122 A valid mapping exists, and user privilege to it exists, but the
124 type of access (read, write, or execute) is denied, for a data or
125 instruction access, respectively.
126 UT_DATA_ERROR, UT_INSTRUCTION_ERROR
129 A valid mapping exists, and both user privilege and the type of
131 access are allowed, but an unrecoverable error occurred in attempt‐
132 ing the access, for a data or instruction access, respectively. %l1
133 will contain either BUS_ADDRERR or BUS_OBJERR.
134 UT_FP_DISABLED
137 This trap is raised when an application issues a floating point
139 instruction (including load or store) and the SPARC V9 Floating
140 Point Registers State (FPRS) FEF bit is 0. If a user handler is
141 installed for this trap, it will be given control. Otherwise the
142 system will set FEF to one and retry the instruction.
143 For all traps, the handler executes in a new register window, where the
147 in registers are the out registers of the previous frame and have the
148 value they contained at the time of the trap, similar to a normal sub‐
149 routine call after the save instruction. The global registers (includ‐
150 ing the special registers %ccr, %asi, and %y) and the floating-point
151 registers have their values from the time of the trap. The stack
152 pointer register %sp plus the BIAS will point to a properly-aligned
153 128-byte register save area; if the handler needs scratch space, it
154 should decrement the stack pointer to obtain it. If the handler needs
155 access to the previous frame's in registers or local registers, it
156 should execute a FLUSHW instruction, and then access them off of the
157 frame pointer. If the handler calls an ABI-conforming function, it must
158 set the %asi register to ASI_PRIMARY_NOFAULT before the call.
159 On entry to a precise user trap handler %l6 contains the %pc and %l7
162 contains the %npc at the time of the trap. To return from a handler
163 and reexecute the trapped instruction, the handler would execute:
164 jmpl %l6, %g0 ! Trapped PC supplied to user trap handler
166 return %l7 ! Trapped nPC supplied to user trap handler
167 To return from a handler and skip the trapped instruction, the handler
172 would execute:
173 jmpl %l7, %g0 ! Trapped nPC supplied to user trap handler
175 return %l7 + 4 ! Trapped nPC + 4
176 On entry to a deferred trap handler %o0 contains the address of the
181 instruction that caused the trap and %o1 contains the actual instruc‐
182 tion (right-justified, zero-extended), if the information is available.
183 Otherwise %o0 contains the value −1 and %o1 is undefined. Additional
184 information may be made available for certain cases of deferred traps,
185 as indicated in the following table.
186 ┌──────────────────────────┬───────────────────────────────────────┐
191 │Instructions │ Additional Information │
192 ├──────────────────────────┼───────────────────────────────────────┤
193 │LD-type (LDSTUB) │ %o2 contains the effective address │
194 │ │ (rs1 + rs2 | simm13). │
195 ├──────────────────────────┼───────────────────────────────────────┤
196 │ST-type (CAS, SWAP) │ %o2 contains the effective address ( │
197 │ │ rs1 + rs2 |simm13). │
198 ├──────────────────────────┼───────────────────────────────────────┤
199 │Integer arithmetic │ %o2 contains the rs1 value. %o3 con‐ │
200 │ │ tains the rs2 | simm13 value. %o4 │
201 │ │ contains the contents of the %y reg‐ │
202 │ │ ister. │
203 ├──────────────────────────┼───────────────────────────────────────┤
204 │Floating-point arithmetic │ %o2 contains the address of rs1 │
205 │ │ value. %o3 contains the address of │
206 │ │ rs2 value. │
207 ├──────────────────────────┼───────────────────────────────────────┤
208 │Control-transfer │ %o2 contains the target address (rs1 │
209 │ │ + rs2 | simm13). │
210 ├──────────────────────────┼───────────────────────────────────────┤
211 │Asynchronous data errors │ %o2 contains the address that caused │
212 │ │ the error. %o3 contains the effective │
213 │ │ ASI, if available, else −1. │
214 └──────────────────────────┴───────────────────────────────────────┘
215 To return from a deferred trap, the trap handler issues:
218 ta 68 ! ST_RETURN_FROM_DEFERRED_TRAP
221 The following pseudo-code explains how the operating system dispatches
224 traps:
225 if (precise trap) {
227 if (precise_handler) {
228 invoke(precise_handler);
229 /* not reached */
230 } else {
231 convert_to_signal(precise_trap);
232 }
233 } else if (deferred_trap) {
234 invoke(deferred_handler);
235 /* not reached */
236 } else {
237 convert_to_signal(deferred_trap);
238 }
239 }
240 if (signal)
241 send(signal);
242 User trap handlers must preserve all registers except the locals
246 (%l0-7) and the outs (%o0-7), that is, %i0-7, %g1-7, %d0-d62, %asi,
247 %fsr, %fprs, %ccr, and %y, except to the extent that modifying the reg‐
248 isters is part of the desired functionality of the handler. For exam‐
249 ple, the handler for UT_FP_DISABLED may load floating-point registers.
250
252 Upon successful completion, 0 is returned. Otherwise, a non-zero value
253 is returned and errno is set to indicate the error.
254
256 The __sparc_utrap_install() function will fail if:
257 EINVAL The type argument is not a supported user trap type; the new
259 user trap handler address is not word aligned; the old user
260 trap handler address cannot be returned; or the user program
261 is not a 64-bit executable.
262
265 Example 1 A sample program using the __sparc_utrap_install() function.
266 The __sparc_utrap_install() function is normally used by user programs
269 that wish to provide their own tailored exception handlers as a faster
270 alternative to signal(3C), or to handle exceptions that are not
271 directly supported by the signal() interface, such as fp_disabled.
272 extern void *fpdis_trap_handler();
275 utrap_handler_t new_precise = (utrap_handler_t)fpdis_trap_handler;
276 double d;
277 int err;
278 err = __sparc_utrap_install(UT_FP_DISABLED, new_precise,
279 UTH_NOCHANGE, NULL, NULL);
280 if (err == EINVAL) {
281 /* unexpected error, do something */
282 exit (1);
283 }
284 d = 1.0e-300;
285 ENTRY(fpdis_trap_handler)
286 wr %g0, FPRS_FEF, %fprs
287 jmpl %l6, %g0
288 return %l7
289 SET_SIZE(fpdis_trap_handler)
290 This example turns on bit 2, FEF, in the Floating-Point Registers State
294 (FPRS) Register, after a floating-point instruction causes an fp_dis‐
295 abled trap. (Note that this example simulates part of the default sys‐
296 tem behavior; programs do not need such a handler. The example is for
297 illustrative purposes only.)
298
301 See attributes(5) for descriptions of the following attributes:
302 ┌─────────────────────────────┬─────────────────────────────┐
307 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
308 ├─────────────────────────────┼─────────────────────────────┤
309 │MT-Level │MT-Safe │
310 └─────────────────────────────┴─────────────────────────────┘
311
313 signal(3C), attributes(5)
314 SPARC Architecture Manual, Version 9
317 Manufacturer's processor chip user manuals
320
322 The Exceptions and Interrupt Descriptions section of the SPARC V9 man‐
323 ual documents which hardware traps are mandatory or optional, and
324 whether they can be implemented as precise or deferred traps, or both.
325 The manufacturer's processor chip user manuals describe the details of
326 the traps supported for the specific processor implementation.
327SunOS 5.11 11 Nov 1997 __sparc_utrap_install(2)