VirtualBox

source: vbox/trunk/include/VBox/patm.h@ 4878

Last change on this file since 4878 was 4787, checked in by vboxsync, 17 years ago

Eliminated HCPTRTYPE and replaced with R3R0PTRTYPE where necessary.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 18.4 KB
Line 
1/** @file
2 * PATM - Dynamic Guest OS Patching Manager
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_patm_h
18#define ___VBox_patm_h
19
20#include <VBox/cdefs.h>
21#include <VBox/types.h>
22#include <VBox/cpum.h>
23#include <VBox/dis.h>
24
25
26__BEGIN_DECLS
27
28/** @defgroup grp_patm The Patch Manager API
29 * @{
30 */
31#define MAX_PATCHES 512
32
33/**
34 * Flags for specifying the type of patch to install with PATMR3InstallPatch
35 * @{
36 */
37#define PATMFL_CODE32 BIT64(0)
38#define PATMFL_INTHANDLER BIT64(1)
39#define PATMFL_SYSENTER BIT64(2)
40#define PATMFL_GUEST_SPECIFIC BIT64(3)
41#define PATMFL_USER_MODE BIT64(4)
42#define PATMFL_IDTHANDLER BIT64(5)
43#define PATMFL_TRAPHANDLER BIT64(6)
44#define PATMFL_DUPLICATE_FUNCTION BIT64(7)
45#define PATMFL_REPLACE_FUNCTION_CALL BIT64(8)
46#define PATMFL_TRAPHANDLER_WITH_ERRORCODE BIT64(9)
47#define PATMFL_INTHANDLER_WITH_ERRORCODE (PATMFL_TRAPHANDLER_WITH_ERRORCODE)
48#define PATMFL_MMIO_ACCESS BIT64(10)
49/* no more room -> change PATMInternal.h if more is needed!! */
50
51/*
52 * Flags above 1024 are reserved for internal use!
53 */
54/** @} */
55
56/** Enable to activate sysenter emulation in GC. */
57/* #define PATM_EMULATE_SYSENTER */
58
59/**
60 * Maximum number of cached VGA writes
61 */
62#define MAX_VGA_WRITE_CACHE 64
63
64typedef struct PATMGCSTATE
65{
66 // Virtual Flags register (IF + more later on)
67 uint32_t uVMFlags;
68
69 /* Pending PATM actions (internal use only) */
70 uint32_t uPendingAction;
71
72 // Records the number of times all patches are called (indicating how many exceptions we managed to avoid)
73 uint32_t uPatchCalls;
74 // Scratchpad dword
75 uint32_t uScratch;
76 // Debugging info
77 uint32_t uIretEFlags, uIretCS, uIretEIP;
78
79 /* PATM stack pointer */
80 uint32_t Psp;
81
82 /* PATM interrupt flag */
83 uint32_t fPIF;
84 /* PATM inhibit irq address (used by sti) */
85 RTGCPTR GCPtrInhibitInterrupts;
86
87 /* Scratch room for call patch */
88 RTGCPTR GCCallPatchTargetAddr;
89 RTGCPTR GCCallReturnAddr;
90
91 /* Temporary storage for guest registers. */
92 struct
93 {
94 uint32_t uEAX;
95 uint32_t uECX;
96 uint32_t uEDI;
97 uint32_t eFlags;
98 uint32_t uFlags;
99 } Restore;
100
101} PATMGCSTATE, *PPATMGCSTATE;
102
103typedef struct PATMTRAPREC
104{
105 // pointer to original guest code instruction (for emulation)
106 RTGCPTR pNewEIP;
107 // pointer to the next guest code instruction
108 RTGCPTR pNextInstr;
109 //pointer to the corresponding next instruction in the patch block
110 RTGCPTR pNextPatchInstr;
111} PATMTRAPREC, *PPATMTRAPREC;
112
113
114/**
115 * Translation state (currently patch to GC ptr)
116 */
117typedef enum
118{
119 PATMTRANS_FAILED,
120 PATMTRANS_SAFE, /* Safe translation */
121 PATMTRANS_PATCHSTART, /* Instruction starts a patch block */
122 PATMTRANS_OVERWRITTEN, /* Instruction overwritten by patchjump */
123 PATMTRANS_INHIBITIRQ /* Instruction must be executed due to instruction fusing */
124} PATMTRANSSTATE;
125
126/**
127 * Load virtualized flags.
128 *
129 * This function is called from CPUMRawEnter(). It doesn't have to update the
130 * IF and IOPL eflags bits, the caller will enforce those to set and 0 repectively.
131 *
132 * @param pVM VM handle.
133 * @param pCtxCore The cpu context core.
134 * @see pg_raw
135 */
136PATMDECL(void) PATMRawEnter(PVM pVM, PCPUMCTXCORE pCtxCore);
137
138/**
139 * Restores virtualized flags.
140 *
141 * This function is called from CPUMRawLeave(). It will update the eflags register.
142 *
143 * @param pVM VM handle.
144 * @param pCtxCore The cpu context core.
145 * @param rawRC Raw mode return code
146 * @see @ref pg_raw
147 */
148PATMDECL(void) PATMRawLeave(PVM pVM, PCPUMCTXCORE pCtxCore, int rawRC);
149
150/**
151 * Get the EFLAGS.
152 * This is a worker for CPUMRawGetEFlags().
153 *
154 * @returns The eflags.
155 * @param pVM The VM handle.
156 * @param pCtxCore The context core.
157 */
158PATMDECL(uint32_t) PATMRawGetEFlags(PVM pVM, PCCPUMCTXCORE pCtxCore);
159
160/**
161 * Updates the EFLAGS.
162 * This is a worker for CPUMRawSetEFlags().
163 *
164 * @param pVM The VM handle.
165 * @param pCtxCore The context core.
166 * @param efl The new EFLAGS value.
167 */
168PATMDECL(void) PATMRawSetEFlags(PVM pVM, PCPUMCTXCORE pCtxCore, uint32_t efl);
169
170/**
171 * Returns the guest context pointer of the GC context structure
172 *
173 * @returns VBox status code.
174 * @param pVM The VM to operate on.
175 */
176PATMDECL(GCPTRTYPE(PPATMGCSTATE)) PATMQueryGCState(PVM pVM);
177
178/**
179 * Checks whether the GC address is part of our patch region
180 *
181 * @returns true -> yes, false -> no
182 * @param pVM The VM to operate on.
183 * @param pAddr Guest context address
184 */
185PATMDECL(bool) PATMIsPatchGCAddr(PVM pVM, RTGCPTR pAddr);
186
187/**
188 * Check if we must use raw mode (patch code being executed or marked safe for IF=0)
189 *
190 * @param pVM VM handle.
191 * @param pAddrGC Guest context address
192 */
193PATMDECL(bool) PATMShouldUseRawMode(PVM pVM, RTGCPTR pAddrGC);
194
195/**
196 * Query PATM state (enabled/disabled)
197 *
198 * @returns 0 - disabled, 1 - enabled
199 * @param pVM The VM to operate on.
200 */
201#define PATMIsEnabled(pVM) (pVM->fPATMEnabled)
202
203/**
204 * Set parameters for pending MMIO patch operation
205 *
206 * @returns VBox status code.
207 * @param pDevIns Device instance.
208 * @param GCPhys MMIO physical address
209 * @param pCachedData GC pointer to cached data
210 */
211PATMDECL(int) PATMSetMMIOPatchInfo(PVM pVM, RTGCPHYS GCPhys, RTGCPTR pCachedData);
212
213
214/**
215 * Adds branch pair to the lookup cache of the particular branch instruction
216 *
217 * @returns VBox status
218 * @param pVM The VM to operate on.
219 * @param pJumpTableGC Pointer to branch instruction lookup cache
220 * @param pBranchTarget Original branch target
221 * @param pRelBranchPatch Relative duplicated function address
222 */
223PATMDECL(int) PATMAddBranchToLookupCache(PVM pVM, RTGCPTR pJumpTableGC, RTGCPTR pBranchTarget, RTGCUINTPTR pRelBranchPatch);
224
225
226/**
227 * Checks if the int 3 was caused by a patched instruction
228 *
229 * @returns VBox status
230 *
231 * @param pVM The VM handle.
232 * @param pCtxCore The relevant core context.
233 */
234PATMDECL(int) PATMHandleInt3PatchTrap(PVM pVM, PCPUMCTXCORE pRegFrame);
235
236/**
237 * Checks if the int 3 was caused by a patched instruction
238 *
239 * @returns VBox status
240 *
241 * @param pVM The VM handle.
242 * @param pInstrGC Instruction pointer
243 * @param pOpcode Original instruction opcode (out, optional)
244 * @param pSize Original instruction size (out, optional)
245 */
246PATMDECL(bool) PATMIsInt3Patch(PVM pVM, RTGCPTR pInstrGC, uint32_t *pOpcode, uint32_t *pSize);
247
248
249/**
250 * Checks if the interrupt flag is enabled or not.
251 *
252 * @returns true if it's enabled.
253 * @returns false if it's diabled.
254 *
255 * @param pVM The VM handle.
256 */
257PATMDECL(bool) PATMAreInterruptsEnabled(PVM pVM);
258
259/**
260 * Checks if the interrupt flag is enabled or not.
261 *
262 * @returns true if it's enabled.
263 * @returns false if it's diabled.
264 *
265 * @param pVM The VM handle.
266 * @param pCtxCore CPU context
267 */
268PATMDECL(bool) PATMAreInterruptsEnabledByCtxCore(PVM pVM, PCPUMCTXCORE pCtxCore);
269
270#ifdef PATM_EMULATE_SYSENTER
271/**
272 * Emulate sysenter, sysexit and syscall instructions
273 *
274 * @returns VBox status
275 *
276 * @param pVM The VM handle.
277 * @param pCtxCore The relevant core context.
278 * @param pCpu Disassembly context
279 */
280PATMDECL(int) PATMSysCall(PVM pVM, PCPUMCTXCORE pRegFrame, PDISCPUSTATE pCpu);
281#endif
282
283#ifdef IN_GC
284/** @defgroup grp_patm_gc The Patch Manager API
285 * @ingroup grp_patm
286 * @{
287 */
288
289/**
290 * Checks if the write is located on a page with was patched before.
291 * (if so, then we are not allowed to turn on r/w)
292 *
293 * @returns VBox status
294 * @param pVM The VM to operate on.
295 * @param pRegFrame CPU context
296 * @param GCPtr GC pointer to write address
297 * @param cbWrite Nr of bytes to write
298 *
299 */
300PATMGCDECL(int) PATMGCHandleWriteToPatchPage(PVM pVM, PCPUMCTXCORE pRegFrame, RTGCPTR GCPtr, uint32_t cbWrite);
301
302/**
303 * Checks if the illegal instruction was caused by a patched instruction
304 *
305 * @returns VBox status
306 *
307 * @param pVM The VM handle.
308 * @param pCtxCore The relevant core context.
309 */
310PATMDECL(int) PATMGCHandleIllegalInstrTrap(PVM pVM, PCPUMCTXCORE pRegFrame);
311
312/** @} */
313
314#endif
315
316#ifdef IN_RING3
317/** @defgroup grp_patm_r3 The Patch Manager API
318 * @ingroup grp_patm
319 * @{
320 */
321
322/**
323 * Query PATM state (enabled/disabled)
324 *
325 * @returns 0 - disabled, 1 - enabled
326 * @param pVM The VM to operate on.
327 */
328PATMR3DECL(int) PATMR3IsEnabled(PVM pVM);
329
330/**
331 * Initializes the PATM.
332 *
333 * @returns VBox status code.
334 * @param pVM The VM to operate on.
335 */
336PATMR3DECL(int) PATMR3Init(PVM pVM);
337
338/**
339 * Finalizes HMA page attributes.
340 *
341 * @returns VBox status code.
342 * @param pVM The VM handle.
343 */
344PATMR3DECL(int) PATMR3InitFinalize(PVM pVM);
345
346/**
347 * Applies relocations to data and code managed by this
348 * component. This function will be called at init and
349 * whenever the VMM need to relocate it self inside the GC.
350 *
351 * The PATM will update the addresses used by the switcher.
352 *
353 * @param pVM The VM.
354 */
355PATMR3DECL(void) PATMR3Relocate(PVM pVM);
356
357/**
358 * Terminates the PATM.
359 *
360 * Termination means cleaning up and freeing all resources,
361 * the VM it self is at this point powered off or suspended.
362 *
363 * @returns VBox status code.
364 * @param pVM The VM to operate on.
365 */
366PATMR3DECL(int) PATMR3Term(PVM pVM);
367
368/**
369 * PATM reset callback.
370 *
371 * @returns VBox status code.
372 * @param pVM The VM which is reset.
373 */
374PATMR3DECL(int) PATMR3Reset(PVM pVM);
375
376/**
377 * Returns the host context pointer and size of the patch memory block
378 *
379 * @returns VBox status code.
380 * @param pVM The VM to operate on.
381 * @param pcb Size of the patch memory block
382 */
383PATMR3DECL(void *) PATMR3QueryPatchMemHC(PVM pVM, uint32_t *pcb);
384
385/**
386 * Returns the guest context pointer and size of the patch memory block
387 *
388 * @returns VBox status code.
389 * @param pVM The VM to operate on.
390 * @param pcb Size of the patch memory block
391 */
392PATMR3DECL(RTGCPTR) PATMR3QueryPatchMemGC(PVM pVM, uint32_t *pcb);
393
394/**
395 * Checks whether the GC address is inside a generated patch jump
396 *
397 * @returns true -> yes, false -> no
398 * @param pVM The VM to operate on.
399 * @param pAddr Guest context address
400 * @param pPatchAddr Guest context patch address (if true)
401 */
402PATMR3DECL(bool) PATMR3IsInsidePatchJump(PVM pVM, RTGCPTR pAddr, PRTGCPTR pPatchAddr);
403
404
405/**
406 * Returns the GC pointer of the patch for the specified GC address
407 *
408 * @returns VBox status code.
409 * @param pVM The VM to operate on.
410 * @param pAddrGC Guest context address
411 */
412PATMR3DECL(RTGCPTR) PATMR3QueryPatchGCPtr(PVM pVM, RTGCPTR pAddrGC);
413
414/**
415 * Checks whether the HC address is part of our patch region
416 *
417 * @returns VBox status code.
418 * @param pVM The VM to operate on.
419 * @param pAddrGC Guest context address
420 */
421PATMR3DECL(bool) PATMR3IsPatchHCAddr(PVM pVM, R3PTRTYPE(uint8_t *) pAddrHC);
422
423/**
424 * Convert a GC patch block pointer to a HC patch pointer
425 *
426 * @returns HC pointer or NULL if it's not a GC patch pointer
427 * @param pVM The VM to operate on.
428 * @param pAddrGC GC pointer
429 */
430PATMR3DECL(R3PTRTYPE(void *)) PATMR3GCPtrToHCPtr(PVM pVM, RTGCPTR pAddrGC);
431
432
433/**
434 * Returns the host context pointer and size of the GC context structure
435 *
436 * @returns VBox status code.
437 * @param pVM The VM to operate on.
438 */
439PATMR3DECL(PPATMGCSTATE) PATMR3QueryGCStateHC(PVM pVM);
440
441/**
442 * Handle trap inside patch code
443 *
444 * @returns VBox status code.
445 * @param pVM The VM to operate on.
446 * @param pCtx CPU context
447 * @param pEip GC pointer of trapping instruction
448 * @param pNewEip GC pointer to new instruction
449 */
450PATMR3DECL(int) PATMR3HandleTrap(PVM pVM, PCPUMCTX pCtx, RTGCPTR pEip, RTGCPTR *ppNewEip);
451
452/**
453 * Handle page-fault in monitored page
454 *
455 * @returns VBox status code.
456 * @param pVM The VM to operate on.
457 */
458PATMR3DECL(int) PATMR3HandleMonitoredPage(PVM pVM);
459
460/**
461 * Notifies PATM about a (potential) write to code that has been patched.
462 *
463 * @returns VBox status code.
464 * @param pVM The VM to operate on.
465 * @param GCPtr GC pointer to write address
466 * @param cbWrite Nr of bytes to write
467 *
468 */
469PATMR3DECL(int) PATMR3PatchWrite(PVM pVM, RTGCPTR GCPtr, uint32_t cbWrite);
470
471/**
472 * Notify PATM of a page flush
473 *
474 * @returns VBox status code
475 * @param pVM The VM to operate on.
476 * @param addr GC address of the page to flush
477 */
478PATMR3DECL(int) PATMR3FlushPage(PVM pVM, RTGCPTR addr);
479
480/**
481 * Allows or disallow patching of privileged instructions executed by the guest OS
482 *
483 * @returns VBox status code.
484 * @param pVM The VM to operate on.
485 * @param fAllowPatching Allow/disallow patching
486 */
487PATMR3DECL(int) PATMR3AllowPatching(PVM pVM, uint32_t fAllowPatching);
488
489/**
490 * Patch privileged instruction at specified location
491 *
492 * @returns VBox status code.
493 * @param pVM The VM to operate on.
494 * @param pInstr Guest context point to privileged instruction (0:32 flat address)
495 * @param flags Patch flags
496 *
497 * @note returns failure if patching is not allowed or possible
498 */
499PATMR3DECL(int) PATMR3InstallPatch(PVM pVM, RTGCPTR pInstrGC, uint64_t flags);
500
501/**
502 * Gives hint to PATM about supervisor guest instructions
503 *
504 * @returns VBox status code.
505 * @param pVM The VM to operate on.
506 * @param pInstr Guest context point to privileged instruction
507 * @param flags Patch flags
508 */
509PATMR3DECL(int) PATMR3AddHint(PVM pVM, RTGCPTR pInstrGC, uint32_t flags);
510
511/**
512 * Patch branch target function for call/jump at specified location.
513 * (in responds to a VINF_PATM_DUPLICATE_FUNCTION GC exit reason)
514 *
515 * @returns VBox status code.
516 * @param pVM The VM to operate on.
517 * @param pCtx Guest context
518 *
519 */
520PATMR3DECL(int) PATMR3DuplicateFunctionRequest(PVM pVM, PCPUMCTX pCtx);
521
522/**
523 * Query the corresponding GC instruction pointer from a pointer inside the patch block itself
524 *
525 * @returns original GC instruction pointer or 0 if not found
526 * @param pVM The VM to operate on.
527 * @param pPatchGC GC address in patch block
528 * @param pEnmState State of the translated address (out)
529 *
530 */
531PATMR3DECL(RTGCPTR) PATMR3PatchToGCPtr(PVM pVM, RTGCPTR pPatchGC, PATMTRANSSTATE *pEnmState);
532
533/**
534 * Converts Guest code GC ptr to Patch code GC ptr (if found)
535 *
536 * @returns corresponding GC pointer in patch block
537 * @param pVM The VM to operate on.
538 * @param pInstrGC Guest context pointer to privileged instruction
539 *
540 */
541PATMR3DECL(RTGCPTR) PATMR3GuestGCPtrToPatchGCPtr(PVM pVM, GCPTRTYPE(uint8_t*) pInstrGC);
542
543/**
544 * Query the opcode of the original code that was overwritten by the 5 bytes patch jump
545 *
546 * @returns VBox status code.
547 * @param pVM The VM to operate on.
548 * @param pInstrGC GC address of instr
549 * @param pByte opcode byte pointer (OUT)
550 * @returns VBOX error code
551 *
552 */
553PATMR3DECL(int) PATMR3QueryOpcode(PVM pVM, RTGCPTR pInstrGC, uint8_t *pByte);
554
555/**
556 * Disable patch for privileged instruction at specified location
557 *
558 * @returns VBox status code.
559 * @param pVM The VM to operate on.
560 * @param pInstr Guest context point to privileged instruction
561 *
562 * @note returns failure if patching is not allowed or possible
563 *
564 */
565PATMR3DECL(int) PATMR3DisablePatch(PVM pVM, RTGCPTR pInstrGC);
566
567
568/**
569 * Enable patch for privileged instruction at specified location
570 *
571 * @returns VBox status code.
572 * @param pVM The VM to operate on.
573 * @param pInstr Guest context point to privileged instruction
574 *
575 * @note returns failure if patching is not allowed or possible
576 *
577 */
578PATMR3DECL(int) PATMR3EnablePatch(PVM pVM, RTGCPTR pInstrGC);
579
580
581/**
582 * Remove patch for privileged instruction at specified location
583 *
584 * @returns VBox status code.
585 * @param pVM The VM to operate on.
586 * @param pInstr Guest context point to privileged instruction
587 *
588 * @note returns failure if patching is not allowed or possible
589 *
590 */
591PATMR3DECL(int) PATMR3RemovePatch(PVM pVM, RTGCPTR pInstrGC);
592
593
594/**
595 * Detects it the specified address falls within a 5 byte jump generated for an active patch.
596 * If so, this patch is permanently disabled.
597 *
598 * @param pVM The VM to operate on.
599 * @param pInstrGC Guest context pointer to instruction
600 * @param pConflictGC Guest context pointer to check
601 */
602PATMR3DECL(int) PATMR3DetectConflict(PVM pVM, RTGCPTR pInstrGC, RTGCPTR pConflictGC);
603
604
605/**
606 * Checks if the instructions at the specified address has been patched already.
607 *
608 * @returns boolean, patched or not
609 * @param pVM The VM to operate on.
610 * @param pInstrGC Guest context pointer to instruction
611 */
612PATMR3DECL(bool) PATMR3HasBeenPatched(PVM pVM, RTGCPTR pInstrGC);
613
614
615/**
616 * Install Linux 2.6 spinlock patch
617 *
618 * @returns VBox status code.
619 * @param pVM The VM to operate on
620 * @param pCallAcquireSpinlockGC GC pointer of call instruction
621 * @param cbAcquireSpinlockCall Instruction size
622 *
623 */
624PATMR3DECL(int) PATMInstallSpinlockPatch(PVM pVM, RTGCPTR pCallAcquireSpinlockGC, uint32_t cbAcquireSpinlockCall);
625
626
627/**
628 * Check if supplied call target is the Linux 2.6 spinlock acquire function
629 *
630 * @returns boolean
631 * @param pVM The VM to operate on
632 * @param pCallAcquireSpinlockGC Call target GC address
633 *
634 */
635PATMR3DECL(bool) PATMIsSpinlockAcquire(PVM pVM, RTGCPTR pCallTargetGC);
636
637/**
638 * Check if supplied call target is the Linux 2.6 spinlock release function
639 *
640 * @returns boolean
641 * @param pVM The VM to operate on
642 * @param pCallTargetGC Call target GC address
643 *
644 */
645PATMR3DECL(bool) PATMIsSpinlockRelease(PVM pVM, RTGCPTR pCallTargetGC);
646
647/**
648 * Check if supplied call target is the Linux 2.6 spinlock release function (patched equivalent)
649 *
650 * @returns boolean
651 * @param pVM The VM to operate on
652 * @param pCallTargetGC Call target GC address
653 *
654 */
655PATMR3DECL(bool) PATMIsSpinlockReleasePatch(PVM pVM, RTGCPTR pCallTargetGC);
656
657/** @} */
658#endif
659
660
661/** @} */
662__END_DECLS
663
664
665#endif
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette