← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/virtualbox-ose/gutsy

« back to all changes in this revision

Viewing changes to include/VBox/trpm.h

  • Committer: Bazaar Package Importer
  • Author(s): Steve Kowalik
  • Date: 2007-09-08 16:44:58 UTC
  • Revision ID: james.westby@ubuntu.com-20070908164458-wao29470vqtr8ksy
Tags: upstream-1.5.0-dfsg2
Import upstream version 1.5.0-dfsg2

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/VBox/trpm.h
 
1
/** @file
 
2
 * TRPM - The Trap Monitor.
 
3
 */
 
4
 
 
5
/*
 
6
 * Copyright (C) 2006-2007 innotek GmbH
 
7
 *
 
8
 * This file is part of VirtualBox Open Source Edition (OSE), as
 
9
 * available from http://www.virtualbox.org. This file is free software;
 
10
 * you can redistribute it and/or modify it under the terms of the GNU
 
11
 * General Public License as published by the Free Software Foundation,
 
12
 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
 
13
 * distribution. VirtualBox OSE is distributed in the hope that it will
 
14
 * be useful, but WITHOUT ANY WARRANTY of any kind.
 
15
 */
 
16
 
 
17
#ifndef ___VBox_trpm_h
 
18
#define ___VBox_trpm_h
 
19
 
 
20
#include <VBox/cdefs.h>
 
21
#include <VBox/types.h>
 
22
#include <VBox/cpum.h>
 
23
 
 
24
 
 
25
__BEGIN_DECLS
 
26
/** @defgroup grp_trpm The Trap Monitor API
 
27
 * @{
 
28
 */
 
29
 
 
30
/**
 
31
 * Trap: error code present or not
 
32
 */
 
33
typedef enum
 
34
{
 
35
    TRPM_TRAP_HAS_ERRORCODE = 0,
 
36
    TRPM_TRAP_NO_ERRORCODE,
 
37
    /** The usual 32-bit paranoia. */
 
38
    TRPM_TRAP_32BIT_HACK = 0x7fffffff
 
39
} TRPMERRORCODE;
 
40
 
 
41
/**
 
42
 * TRPM event type
 
43
 */
 
44
/** Note: must match trpm.mac! */
 
45
typedef enum
 
46
{
 
47
    TRPM_TRAP         = 0,
 
48
    TRPM_HARDWARE_INT = 1,
 
49
    TRPM_SOFTWARE_INT = 2,
 
50
    /** The usual 32-bit paranoia. */
 
51
    TRPM_32BIT_HACK   = 0x7fffffff
 
52
} TRPMEVENT;
 
53
/** Pointer to a TRPM event type. */
 
54
typedef TRPMEVENT *PTRPMEVENT;
 
55
/** Pointer to a const TRPM event type. */
 
56
typedef TRPMEVENT const *PCTRPMEVENT;
 
57
 
 
58
/**
 
59
 * Invalid trap handler for trampoline calls
 
60
 */
 
61
#define TRPM_INVALID_HANDLER        0
 
62
 
 
63
/**
 
64
 * Query info about the current active trap/interrupt.
 
65
 * If no trap is active active an error code is returned.
 
66
 *
 
67
 * @returns VBox status code.
 
68
 * @param   pVM                     The virtual machine.
 
69
 * @param   pu8TrapNo               Where to store the trap number.
 
70
 * @param   pEnmType                Where to store the trap type.
 
71
 */
 
72
TRPMDECL(int)  TRPMQueryTrap(PVM pVM, uint8_t *pu8TrapNo, PTRPMEVENT pEnmType);
 
73
 
 
74
/**
 
75
 * Gets the trap number for the current trap.
 
76
 *
 
77
 * The caller is responsible for making sure there is an active trap which
 
78
 * takes an error code when making this request.
 
79
 *
 
80
 * @returns The current trap number.
 
81
 * @param   pVM         VM handle.
 
82
 */
 
83
TRPMDECL(uint8_t)  TRPMGetTrapNo(PVM pVM);
 
84
 
 
85
/**
 
86
 * Gets the error code for the current trap.
 
87
 *
 
88
 * The caller is responsible for making sure there is an active trap which
 
89
 * takes an error code when making this request.
 
90
 *
 
91
 * @returns Error code.
 
92
 * @param   pVM         VM handle.
 
93
 */
 
94
TRPMDECL(RTGCUINT)  TRPMGetErrorCode(PVM pVM);
 
95
 
 
96
/**
 
97
 * Gets the fault address for the current trap.
 
98
 *
 
99
 * The caller is responsible for making sure there is an active trap 0x0e when
 
100
 * making this request.
 
101
 *
 
102
 * @returns Fault address associated with the trap.
 
103
 * @param   pVM         VM handle.
 
104
 */
 
105
TRPMDECL(RTGCUINTPTR) TRPMGetFaultAddress(PVM pVM);
 
106
 
 
107
/**
 
108
 * Clears the current active trap/exception/interrupt.
 
109
 *
 
110
 * The caller is responsible for making sure there is an active trap
 
111
 * when making this request.
 
112
 *
 
113
 * @returns VBox status code.
 
114
 * @param   pVM         The virtual machine handle.
 
115
 */
 
116
TRPMDECL(int) TRPMResetTrap(PVM pVM);
 
117
 
 
118
/**
 
119
 * Assert trap/exception/interrupt.
 
120
 *
 
121
 * The caller is responsible for making sure there is no active trap
 
122
 * when making this request.
 
123
 *
 
124
 * @returns VBox status code.
 
125
 * @param   pVM                 The virtual machine.
 
126
 * @param   u8TrapNo            The trap vector to assert.
 
127
 * @param   enmType             Trap type.
 
128
 */
 
129
TRPMDECL(int)  TRPMAssertTrap(PVM pVM, uint8_t u8TrapNo, TRPMEVENT enmType);
 
130
 
 
131
/**
 
132
 * Sets the error code of the current trap.
 
133
 * (This function is for use in trap handlers and such.)
 
134
 *
 
135
 * The caller is responsible for making sure there is an active trap
 
136
 * which takes an errorcode when making this request.
 
137
 *
 
138
 * @param   pVM         The virtual machine.
 
139
 * @param   uErrorCode  The new error code.
 
140
 */
 
141
TRPMDECL(void)  TRPMSetErrorCode(PVM pVM, RTGCUINT uErrorCode);
 
142
 
 
143
/**
 
144
 * Sets the error code of the current trap.
 
145
 * (This function is for use in trap handlers and such.)
 
146
 *
 
147
 * The caller is responsible for making sure there is an active trap 0e
 
148
 * when making this request.
 
149
 *
 
150
 * @param   pVM         The virtual machine.
 
151
 * @param   uCR2        The new fault address (cr2 register).
 
152
 */
 
153
TRPMDECL(void)  TRPMSetFaultAddress(PVM pVM, RTGCUINTPTR uCR2);
 
154
 
 
155
/**
 
156
 * Checks if the current active trap/interrupt/exception/fault/whatever is a software
 
157
 * interrupt or not.
 
158
 *
 
159
 * The caller is responsible for making sure there is an active trap
 
160
 * when making this request.
 
161
 *
 
162
 * @returns true if software interrupt, false if not.
 
163
 *
 
164
 * @param   pVM         VM handle.
 
165
 */
 
166
TRPMDECL(bool) TRPMIsSoftwareInterrupt(PVM pVM);
 
167
 
 
168
/**
 
169
 * Check if there is an active trap.
 
170
 *
 
171
 * @returns true if trap active, false if not.
 
172
 * @param   pVM         The virtual machine.
 
173
 */
 
174
TRPMDECL(bool)  TRPMHasTrap(PVM pVM);
 
175
 
 
176
/**
 
177
 * Query all info about the current active trap/interrupt.
 
178
 * If no trap is active active an error code is returned.
 
179
 *
 
180
 * @returns VBox status code.
 
181
 * @param   pVM                     The virtual machine.
 
182
 * @param   pu8TrapNo               Where to store the trap number.
 
183
 * @param   pEnmType                Where to store the trap type.
 
184
 * @param   puErrorCode             Where to store the error code associated with some traps.
 
185
 *                                  ~0U is stored if the trap have no error code.
 
186
 * @param   puCR2                   Where to store the CR2 associated with a trap 0E.
 
187
 */
 
188
TRPMDECL(int)  TRPMQueryTrapAll(PVM pVM, uint8_t *pu8TrapNo, PTRPMEVENT pEnmType, PRTGCUINT puErrorCode, PRTGCUINTPTR puCR2);
 
189
 
 
190
 
 
191
/**
 
192
 * Save the active trap.
 
193
 *
 
194
 * This routine useful when doing try/catch in the hypervisor.
 
195
 * Any function which uses temporary trap handlers should
 
196
 * probably also use this facility to save the original trap.
 
197
 *
 
198
 * @param   pVM     VM handle.
 
199
 */
 
200
TRPMDECL(void) TRPMSaveTrap(PVM pVM);
 
201
 
 
202
/**
 
203
 * Restore a saved trap.
 
204
 *
 
205
 * Multiple restores of a saved trap is possible.
 
206
 *
 
207
 * @param   pVM     VM handle.
 
208
 */
 
209
TRPMDECL(void) TRPMRestoreTrap(PVM pVM);
 
210
 
 
211
/**
 
212
 * Forward trap or interrupt to the guest's handler
 
213
 *
 
214
 *
 
215
 * @returns VBox status code.
 
216
 *  or does not return at all (when the trap is actually forwarded)
 
217
 *
 
218
 * @param   pVM         The VM to operate on.
 
219
 * @param   pRegFrame   Pointer to the register frame for the trap.
 
220
 * @param   iGate       Trap or interrupt gate number
 
221
 * @param   opsize      Instruction size (only relevant for software interrupts)
 
222
 * @param   enmError    TRPM_TRAP_HAS_ERRORCODE or TRPM_TRAP_NO_ERRORCODE.
 
223
 * @param   enmType     TRPM event type
 
224
 * @internal
 
225
 */
 
226
TRPMDECL(int) TRPMForwardTrap(PVM pVM, PCPUMCTXCORE pRegFrame, uint32_t iGate, uint32_t opsize, TRPMERRORCODE enmError, TRPMEVENT enmType);
 
227
 
 
228
/**
 
229
 * Raises a cpu exception which doesn't take an error code.
 
230
 *
 
231
 * This function may or may not dispatch the exception before returning.
 
232
 *
 
233
 * @returns VBox status code fit for scheduling.
 
234
 * @retval  VINF_EM_RAW_GUEST_TRAP if the exception was left pending.
 
235
 * @retval  VINF_TRPM_XCPT_DISPATCHED if the exception was raised and dispatched for raw-mode execution.
 
236
 * @retval  VINF_EM_RESCHEDULE_REM if the exception was dispatched and cannot be executed in raw-mode.
 
237
 *
 
238
 * @param   pVM         The VM handle.
 
239
 * @param   pCtxCore    The CPU context core.
 
240
 * @param   enmXcpt     The exception.
 
241
 */
 
242
TRPMDECL(int) TRPMRaiseXcpt(PVM pVM, PCPUMCTXCORE pCtxCore, X86XCPT enmXcpt);
 
243
 
 
244
/**
 
245
 * Raises a cpu exception with an errorcode.
 
246
 *
 
247
 * This function may or may not dispatch the exception before returning.
 
248
 *
 
249
 * @returns VBox status code fit for scheduling.
 
250
 * @retval  VINF_EM_RAW_GUEST_TRAP if the exception was left pending.
 
251
 * @retval  VINF_TRPM_XCPT_DISPATCHED if the exception was raised and dispatched for raw-mode execution.
 
252
 * @retval  VINF_EM_RESCHEDULE_REM if the exception was dispatched and cannot be executed in raw-mode.
 
253
 *
 
254
 * @param   pVM         The VM handle.
 
255
 * @param   pCtxCore    The CPU context core.
 
256
 * @param   enmXcpt     The exception.
 
257
 * @param   uErr        The error code.
 
258
 */
 
259
TRPMDECL(int) TRPMRaiseXcptErr(PVM pVM, PCPUMCTXCORE pCtxCore, X86XCPT enmXcpt, uint32_t uErr);
 
260
 
 
261
/**
 
262
 * Raises a cpu exception with an errorcode and CR2.
 
263
 *
 
264
 * This function may or may not dispatch the exception before returning.
 
265
 *
 
266
 * @returns VBox status code fit for scheduling.
 
267
 * @retval  VINF_EM_RAW_GUEST_TRAP if the exception was left pending.
 
268
 * @retval  VINF_TRPM_XCPT_DISPATCHED if the exception was raised and dispatched for raw-mode execution.
 
269
 * @retval  VINF_EM_RESCHEDULE_REM if the exception was dispatched and cannot be executed in raw-mode.
 
270
 *
 
271
 * @param   pVM         The VM handle.
 
272
 * @param   pCtxCore    The CPU context core.
 
273
 * @param   enmXcpt     The exception.
 
274
 * @param   uErr        The error code.
 
275
 * @param   uCR2        The CR2 value.
 
276
 */
 
277
TRPMDECL(int) TRPMRaiseXcptErrCR2(PVM pVM, PCPUMCTXCORE pCtxCore, X86XCPT enmXcpt, uint32_t uErr, RTGCUINTPTR uCR2);
 
278
 
 
279
 
 
280
#ifdef IN_RING3
 
281
/** @defgroup grp_trpm_r3   TRPM Host Context Ring 3 API
 
282
 * @ingroup grp_trpm
 
283
 * @{
 
284
 */
 
285
 
 
286
/**
 
287
 * Initializes the SELM.
 
288
 *
 
289
 * @returns VBox status code.
 
290
 * @param   pVM         The VM to operate on.
 
291
 */
 
292
TRPMR3DECL(int) TRPMR3Init(PVM pVM);
 
293
 
 
294
/**
 
295
 * Applies relocations to data and code managed by this component.
 
296
 *
 
297
 * This function will be called at init and whenever the VMM need
 
298
 * to relocate itself inside the GC.
 
299
 *
 
300
 * @param   pVM         The VM handle.
 
301
 * @param   offDelta    Relocation delta relative to old location.
 
302
 */
 
303
TRPMR3DECL(void) TRPMR3Relocate(PVM pVM, RTGCINTPTR offDelta);
 
304
 
 
305
/**
 
306
 * The VM is being reset.
 
307
 *
 
308
 * For the TRPM component this means that any IDT write monitors
 
309
 * needs to be removed, any pending trap cleared, and the IDT reset.
 
310
 *
 
311
 * @param   pVM     VM handle.
 
312
 */
 
313
TRPMR3DECL(void) TRPMR3Reset(PVM pVM);
 
314
 
 
315
/**
 
316
 * Set interrupt gate handler
 
317
 * Used for setting up interrupt gates used for kernel calls.
 
318
 *
 
319
 * @returns VBox status code.
 
320
 * @param   pVM         The VM to operate on.
 
321
 * @param   iTrap       Interrupt number.
 
322
 */
 
323
TRPMR3DECL(int) TRPMR3EnableGuestTrapHandler(PVM pVM, unsigned iTrap);
 
324
 
 
325
/**
 
326
 * Set guest trap/interrupt gate handler
 
327
 * Used for setting up trap gates used for kernel calls.
 
328
 *
 
329
 * @returns VBox status code.
 
330
 * @param   pVM         The VM to operate on.
 
331
 * @param   iTrap       Interrupt/trap number.
 
332
 * @parapm  pHandler    GC handler pointer
 
333
 */
 
334
TRPMR3DECL(int) TRPMR3SetGuestTrapHandler(PVM pVM, unsigned iTrap, RTGCPTR pHandler);
 
335
 
 
336
/**
 
337
 * Get guest trap/interrupt gate handler
 
338
 *
 
339
 * @returns Guest trap handler address or TRPM_INVALID_HANDLER if none installed
 
340
 * @param   pVM         The VM to operate on.
 
341
 * @param   iTrap       Interrupt/trap number.
 
342
 */
 
343
TRPMR3DECL(RTGCPTR) TRPMR3GetGuestTrapHandler(PVM pVM, unsigned iTrap);
 
344
 
 
345
/**
 
346
 * Disable IDT monitoring and syncing
 
347
 *
 
348
 * @param   pVM         The VM to operate on.
 
349
 */
 
350
TRPMR3DECL(void) TRPMR3DisableMonitoring(PVM pVM);
 
351
 
 
352
/**
 
353
 * Check if gate handlers were updated
 
354
 *
 
355
 * @returns VBox status code.
 
356
 * @param   pVM         The VM to operate on.
 
357
 */
 
358
TRPMR3DECL(int) TRPMR3SyncIDT(PVM pVM);
 
359
 
 
360
/**
 
361
 * Check if address is a gate handler (interrupt/trap/task/anything).
 
362
 *
 
363
 * @returns True is gate handler, false if not.
 
364
 *
 
365
 * @param   pVM         VM handle.
 
366
 * @param   GCPtr       GC address to check.
 
367
 */
 
368
TRPMR3DECL(bool) TRPMR3IsGateHandler(PVM pVM, RTGCPTR GCPtr);
 
369
 
 
370
/**
 
371
 * Check if address is a gate handler (interrupt or trap).
 
372
 *
 
373
 * @returns gate nr or ~0 is not found
 
374
 *
 
375
 * @param   pVM         VM handle.
 
376
 * @param   GCPtr       GC address to check.
 
377
 */
 
378
TRPMR3DECL(uint32_t) TRPMR3QueryGateByHandler(PVM pVM, RTGCPTR GCPtr);
 
379
 
 
380
/**
 
381
 * Initializes the SELM.
 
382
 *
 
383
 * @returns VBox status code.
 
384
 * @param   pVM         The VM to operate on.
 
385
 */
 
386
TRPMR3DECL(int) TRPMR3Term(PVM pVM);
 
387
 
 
388
 
 
389
/**
 
390
 * Inject event (such as external irq or trap)
 
391
 *
 
392
 * @returns VBox status code.
 
393
 * @param   pVM         The VM to operate on.
 
394
 * @param   enmEvent    Trpm event type
 
395
 */
 
396
TRPMR3DECL(int) TRPMR3InjectEvent(PVM pVM, TRPMEVENT enmEvent);
 
397
 
 
398
/** @} */
 
399
#endif
 
400
 
 
401
 
 
402
#ifdef IN_GC
 
403
/** @defgroup grp_trpm_gc    The TRPM Guest Context API
 
404
 * @ingroup grp_trpm
 
405
 * @{
 
406
 */
 
407
 
 
408
/**
 
409
 * Guest Context temporary trap handler
 
410
 *
 
411
 * @returns VBox status code (appropriate for GC return).
 
412
 *          In this context VBOX_SUCCESS means to restart the instruction.
 
413
 * @param   pVM         VM handle.
 
414
 * @param   pRegFrame   Trap register frame.
 
415
 */
 
416
typedef DECLCALLBACK(int) FNTRPMGCTRAPHANDLER(PVM pVM, PCPUMCTXCORE pRegFrame);
 
417
/** Pointer to a TRPMGCTRAPHANDLER() function. */
 
418
typedef FNTRPMGCTRAPHANDLER *PFNTRPMGCTRAPHANDLER;
 
419
 
 
420
/**
 
421
 * Arms a temporary trap handler for traps in Hypervisor code.
 
422
 *
 
423
 * The operation is similar to a System V signal handler. I.e. when the handler
 
424
 * is called it is first set to default action. So, if you need to handler more
 
425
 * than one trap, you must reinstall the handler.
 
426
 *
 
427
 * To uninstall the temporary handler, call this function with pfnHandler set to NULL.
 
428
 *
 
429
 * @returns VBox status.
 
430
 * @param   pVM         VM handle.
 
431
 * @param   iTrap       Trap number to install handler [0..255].
 
432
 * @param   pfnHandler  Pointer to the handler. Use NULL for uninstalling the handler.
 
433
 */
 
434
TRPMGCDECL(int) TRPMGCSetTempHandler(PVM pVM, unsigned iTrap, PFNTRPMGCTRAPHANDLER pfnHandler);
 
435
 
 
436
/**
 
437
 * Return to host context from a hypervisor trap handler.
 
438
 * It will also reset any traps that are pending.
 
439
 *
 
440
 * This function will *never* return.
 
441
 *
 
442
 * @param   pVM     The VM handle.
 
443
 * @param   rc      The return code for host context.
 
444
 */
 
445
TRPMGCDECL(void) TRPMGCHyperReturnToHost(PVM pVM, int rc);
 
446
 
 
447
/** @} */
 
448
#endif
 
449
 
 
450
 
 
451
#ifdef IN_RING0
 
452
/** @defgroup grp_trpm_r0   TRPM Host Context Ring 0 API
 
453
 * @ingroup grp_trpm
 
454
 * @{
 
455
 */
 
456
 
 
457
/**
 
458
 * Dispatches an interrupt that arrived while we were in the guest context.
 
459
 *
 
460
 * @param   pVM     The VM handle.
 
461
 * @remark  Must be called with interrupts disabled.
 
462
 */
 
463
TRPMR0DECL(void) TRPMR0DispatchHostInterrupt(PVM pVM);
 
464
 
 
465
# ifndef VBOX_WITHOUT_IDT_PATCHING
 
466
 
 
467
/**
 
468
 * Changes the VMMR0Entry() call frame and stack used by the IDT patch code
 
469
 * so that we'll dispatch an interrupt rather than returning directly to Ring-3
 
470
 * when VMMR0Entry() returns.
 
471
 *
 
472
 * @param   pVM         Pointer to the VM.
 
473
 * @param   pvRet       Pointer to the return address of VMMR0Entry() on the stack.
 
474
 */
 
475
TRPMR0DECL(void) TRPMR0SetupInterruptDispatcherFrame(PVM pVM, void *pvRet);
 
476
 
 
477
# endif /* !VBOX_WITHOUT_IDT_PATCHING */
 
478
 
 
479
/** @} */
 
480
#endif
 
481
 
 
482
/** @} */
 
483
__END_DECLS
 
484
 
 
485
#endif