VirtualBox

Changeset 13579 in vbox


Ignore:
Timestamp:
Oct 27, 2008 1:58:43 PM (16 years ago)
Author:
vboxsync
Message:

selm.h: stripped duplicated doxygen comments.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/VBox/selm.h

    r13577 r13579  
    11/** @file
    2  * SELM - The Selector Monitor(/Manager).
     2 * SELM - The Selector Manager.
    33 */
    44
    … …  
    4343 */
    4444
    45 /**
    46  * Returns Hypervisor's Trap 08 (\#DF) selector.
    47  *
    48  * @returns Hypervisor's Trap 08 (\#DF) selector.
    49  * @param   pVM     VM Handle.
    50  */
    51 VMMDECL(RTSEL) SELMGetTrap8Selector(PVM pVM);
    52 
    53 /**
    54  * Sets EIP of Hypervisor's Trap 08 (\#DF) TSS.
    55  *
    56  * @param   pVM     VM Handle.
    57  * @param   u32EIP  EIP of Trap 08 handler.
    58  */
    59 VMMDECL(void) SELMSetTrap8EIP(PVM pVM, uint32_t u32EIP);
    60 
    61 /**
    62  * Sets ss:esp for ring1 in main Hypervisor's TSS.
    63  *
    64  * @param   pVM     VM Handle.
    65  * @param   ss      Ring1 SS register value.
    66  * @param   esp     Ring1 ESP register value.
    67  */
    68 VMMDECL(void) SELMSetRing1Stack(PVM pVM, uint32_t ss, RTGCPTR32 esp);
    69 
    70 /**
    71  * Gets ss:esp for ring1 in main Hypervisor's TSS.
    72  *
    73  * @returns VBox status code.
    74  * @param   pVM     VM Handle.
    75  * @param   pSS     Ring1 SS register value.
    76  * @param   pEsp    Ring1 ESP register value.
    77  */
    78 VMMDECL(int) SELMGetRing1Stack(PVM pVM, uint32_t *pSS, PRTGCPTR32 pEsp);
    79 
    80 /**
    81  * Returns Guest TSS pointer
    82  *
    83  * @param   pVM     VM Handle.
    84  */
    85 VMMDECL(RTGCPTR) SELMGetGuestTSS(PVM pVM);
    86 
    87 /**
    88  * Gets the hypervisor code selector (CS).
    89  * @returns CS selector.
    90  * @param   pVM     The VM handle.
    91  */
    92 VMMDECL(RTSEL) SELMGetHyperCS(PVM pVM);
    93 
    94 /**
    95  * Gets the 64-mode hypervisor code selector (CS64).
    96  * @returns CS selector.
    97  * @param   pVM     The VM handle.
    98  */
    99 VMMDECL(RTSEL) SELMGetHyperCS64(PVM pVM);
    100 
    101 /**
    102  * Gets the hypervisor data selector (DS).
    103  * @returns DS selector.
    104  * @param   pVM     The VM handle.
    105  */
    106 VMMDECL(RTSEL) SELMGetHyperDS(PVM pVM);
    107 
    108 /**
    109  * Gets the hypervisor TSS selector.
    110  * @returns TSS selector.
    111  * @param   pVM     The VM handle.
    112  */
    113 VMMDECL(RTSEL) SELMGetHyperTSS(PVM pVM);
    114 
    115 /**
    116  * Gets the hypervisor TSS Trap 8 selector.
    117  * @returns TSS Trap 8 selector.
    118  * @param   pVM     The VM handle.
    119  */
    120 VMMDECL(RTSEL) SELMGetHyperTSSTrap08(PVM pVM);
    121 
    122 /**
    123  * Gets the address for the hypervisor GDT.
    124  *
    125  * @returns The GDT address.
    126  * @param   pVM     The VM handle.
    127  * @remark  This is intended only for very special use, like in the world
    128  *          switchers. Don't exploit this API!
    129  */
    130 VMMDECL(RTRCPTR) SELMGetHyperGDT(PVM pVM);
    131 
    132 /**
    133  * Gets info about the current TSS.
    134  *
    135  * @returns VBox status code.
    136  * @retval  VINF_SUCCESS if we've got a TSS loaded.
    137  * @retval  VERR_SELM_NO_TSS if we haven't got a TSS (rather unlikely).
    138  *
    139  * @param   pVM                 The VM handle.
    140  * @param   pGCPtrTss           Where to store the TSS address.
    141  * @param   pcbTss              Where to store the TSS size limit.
    142  * @param   pfCanHaveIOBitmap   Where to store the can-have-I/O-bitmap indicator. (optional)
    143  */
    144 VMMDECL(int) SELMGetTSSInfo(PVM pVM, PRTGCUINTPTR pGCPtrTss, PRTGCUINTPTR pcbTss, bool *pfCanHaveIOBitmap);
    145 
    146 /**
    147  * Converts a GC selector based address to a flat address.
    148  *
    149  * No limit checks are done. Use the SELMToFlat*() or SELMValidate*() functions
    150  * for that.
    151  *
    152  * @returns Flat address.
    153  * @param   pVM         VM Handle.
    154  * @param   SelReg      Selector register
    155  * @param   pCtxCore    CPU context
    156  * @param   Addr        Address part.
    157  */
    158 VMMDECL(RTGCPTR) SELMToFlat(PVM pVM, DIS_SELREG SelReg, PCPUMCTXCORE pCtxCore, RTGCPTR Addr);
    159 
    160 /**
    161  * Converts a GC selector based address to a flat address.
    162  *
    163  * No limit checks are done. Use the SELMToFlat*() or SELMValidate*() functions
    164  * for that.
    165  *
    166  * Note: obsolete; DO NOT USE!
    167  *
    168  * @returns Flat address.
    169  * @param   pVM     VM Handle.
    170  * @param   Sel     Selector part.
    171  * @param   Addr    Address part.
    172  */
    173 VMMDECL(RTGCPTR) SELMToFlatBySel(PVM pVM, RTSEL Sel, RTGCPTR Addr);
     45VMMDECL(RTSEL)      SELMGetTrap8Selector(PVM pVM);
     46VMMDECL(void)       SELMSetTrap8EIP(PVM pVM, uint32_t u32EIP);
     47VMMDECL(void)       SELMSetRing1Stack(PVM pVM, uint32_t ss, RTGCPTR32 esp);
     48VMMDECL(int)        SELMGetRing1Stack(PVM pVM, uint32_t *pSS, PRTGCPTR32 pEsp);
     49VMMDECL(RTGCPTR)    SELMGetGuestTSS(PVM pVM);
     50VMMDECL(RTSEL)      SELMGetHyperCS(PVM pVM);
     51VMMDECL(RTSEL)      SELMGetHyperCS64(PVM pVM);
     52VMMDECL(RTSEL)      SELMGetHyperDS(PVM pVM);
     53VMMDECL(RTSEL)      SELMGetHyperTSS(PVM pVM);
     54VMMDECL(RTSEL)      SELMGetHyperTSSTrap08(PVM pVM);
     55VMMDECL(RTRCPTR)    SELMGetHyperGDT(PVM pVM);
     56VMMDECL(int)        SELMGetTSSInfo(PVM pVM, PRTGCUINTPTR pGCPtrTss, PRTGCUINTPTR pcbTss, bool *pfCanHaveIOBitmap);
     57VMMDECL(RTGCPTR)    SELMToFlat(PVM pVM, DIS_SELREG SelReg, PCPUMCTXCORE pCtxCore, RTGCPTR Addr);
     58VMMDECL(RTGCPTR)    SELMToFlatBySel(PVM pVM, RTSEL Sel, RTGCPTR Addr);
    17459
    17560/** Flags for SELMToFlatEx().
    … …  
    19378/** @} */
    19479
    195 /**
    196  * Converts a GC selector based address to a flat address.
    197  *
    198  * Some basic checking is done, but not all kinds yet.
    199  *
    200  * @returns VBox status
    201  * @param   pVM         VM Handle.
    202  * @param   SelReg      Selector register
    203  * @param   pCtxCore    CPU context
    204  * @param   Addr        Address part.
    205  * @param   fFlags      SELMTOFLAT_FLAGS_*
    206  *                      GDT entires are valid.
    207  * @param   ppvGC       Where to store the GC flat address.
    208  */
    209 VMMDECL(int) SELMToFlatEx(PVM pVM, DIS_SELREG SelReg, PCCPUMCTXCORE pCtxCore, RTGCPTR Addr, unsigned fFlags, PRTGCPTR ppvGC);
    210 
    211 /**
    212  * Converts a GC selector based address to a flat address.
    213  *
    214  * Some basic checking is done, but not all kinds yet.
    215  *
    216  * Note: Obsolete: DO NOT USE
    217  *
    218  * @returns VBox status
    219  * @param   pVM         VM Handle.
    220  * @param   eflags      Current eflags
    221  * @param   Sel         Selector part.
    222  * @param   Addr        Address part.
    223  * @param   pHiddenSel  Hidden selector register (can be NULL)
    224  * @param   fFlags      SELMTOFLAT_FLAGS_*
    225  *                      GDT entires are valid.
    226  * @param   ppvGC       Where to store the GC flat address.
    227  * @param   pcb         Where to store the bytes from *ppvGC which can be accessed according to
    228  *                      the selector. NULL is allowed.
    229  */
    230 VMMDECL(int) SELMToFlatBySelEx(PVM pVM, X86EFLAGS eflags, RTSEL Sel, RTGCPTR Addr, CPUMSELREGHID *pHiddenSel, unsigned fFlags, PRTGCPTR ppvGC, uint32_t *pcb);
    231 
    232 /**
    233  * Validates and converts a GC selector based code address to a flat address.
    234  *
    235  * @returns VBox status code.
    236  * @param   pVM          VM Handle.
    237  * @param   eflags       Current eflags
    238  * @param   SelCPL       Current privilege level. Get this from SS - CS might be conforming!
    239  *                       A full selector can be passed, we'll only use the RPL part.
    240  * @param   SelCS        Selector part.
    241  * @param   pHiddenSel   The hidden CS selector register.
    242  * @param   Addr         Address part.
    243  * @param   ppvFlat      Where to store the flat address.
    244  */
    245 VMMDECL(int) SELMValidateAndConvertCSAddr(PVM pVM, X86EFLAGS eflags, RTSEL SelCPL, RTSEL SelCS, PCPUMSELREGHID pHiddenCSSel, RTGCPTR Addr, PRTGCPTR ppvFlat);
    246 
    247 /**
    248  * Validates and converts a GC selector based code address to a flat address.
    249  *
    250  * This is like SELMValidateAndConvertCSAddr + SELMIsSelector32Bit but with
    251  * invalid hidden CS data. It's customized for dealing efficiently with CS
    252  * at GC trap time.
    253  *
    254  * @returns VBox status code.
    255  * @param   pVM          VM Handle.
    256  * @param   eflags       Current eflags
    257  * @param   SelCPL       Current privilege level. Get this from SS - CS might be conforming!
    258  *                       A full selector can be passed, we'll only use the RPL part.
    259  * @param   SelCS        Selector part.
    260  * @param   Addr         Address part.
    261  * @param   ppvFlat      Where to store the flat address.
    262  * @param   pcBits       Where to store the 64-bit/32-bit/16-bit indicator.
    263  */
    264 VMMDECL(int) SELMValidateAndConvertCSAddrGCTrap(PVM pVM, X86EFLAGS eflags, RTSEL SelCPL, RTSEL SelCS, RTGCPTR Addr, PRTGCPTR ppvFlat, uint32_t *pcBits);
    265 
    266 /**
    267  * Return the cpu mode corresponding to the (CS) selector
    268  *
    269  * @returns DISCPUMODE according to the selector type (16, 32 or 64 bits)
    270  * @param   pVM        VM Handle.
    271  * @param   eflags     Current eflags register
    272  * @param   Sel        The selector.
    273  * @param   pHiddenSel The hidden selector register.
    274  */
     80VMMDECL(int)        SELMToFlatEx(PVM pVM, DIS_SELREG SelReg, PCCPUMCTXCORE pCtxCore, RTGCPTR Addr, unsigned fFlags, PRTGCPTR ppvGC);
     81VMMDECL(int)        SELMToFlatBySelEx(PVM pVM, X86EFLAGS eflags, RTSEL Sel, RTGCPTR Addr, CPUMSELREGHID *pHiddenSel, unsigned fFlags, PRTGCPTR ppvGC, uint32_t *pcb);
     82VMMDECL(int)        SELMValidateAndConvertCSAddr(PVM pVM, X86EFLAGS eflags, RTSEL SelCPL, RTSEL SelCS, PCPUMSELREGHID pHiddenCSSel, RTGCPTR Addr, PRTGCPTR ppvFlat);
     83VMMDECL(int)        SELMValidateAndConvertCSAddrGCTrap(PVM pVM, X86EFLAGS eflags, RTSEL SelCPL, RTSEL SelCS, RTGCPTR Addr, PRTGCPTR ppvFlat, uint32_t *pcBits);
    27584VMMDECL(DISCPUMODE) SELMGetCpuModeFromSelector(PVM pVM, X86EFLAGS eflags, RTSEL Sel, CPUMSELREGHID *pHiddenSel);
    276 
    277 /**
    278  * Returns flat address and limit of LDT by LDT selector.
    279  *
    280  * Fully validate selector.
    281  *
    282  * @returns VBox status.
    283  * @param   pVM       VM Handle.
    284  * @param   SelLdt    LDT selector.
    285  * @param   ppvLdt    Where to store the flat address of LDT.
    286  * @param   pcbLimit  Where to store LDT limit.
    287  */
    288 VMMDECL(int) SELMGetLDTFromSel(PVM pVM, RTSEL SelLdt, PRTGCPTR ppvLdt, unsigned *pcbLimit);
    289 
     85VMMDECL(int)        SELMGetLDTFromSel(PVM pVM, RTSEL SelLdt, PRTGCPTR ppvLdt, unsigned *pcbLimit);
    29086
    29187/**
    … …  
    316112typedef const SELMSELINFO *PCSELMSELINFO;
    317113
    318 /**
    319  * Validates a CS selector.
    320  *
    321  * @returns VBox status code.
    322  * @param   pSelInfo    Pointer to the selector information for the CS selector.
    323  * @param   SelCPL      The selector defining the CPL (SS).
    324  */
    325 VMMDECL(int) SELMSelInfoValidateCS(PCSELMSELINFO pSelInfo, RTSEL SelCPL);
     114VMMDECL(int)        SELMSelInfoValidateCS(PCSELMSELINFO pSelInfo, RTSEL SelCPL);
    326115
    327116/** @def SELMSelInfoIsExpandDown
    … …  
    339128
    340129
    341 
    342130#ifdef IN_RING3
    343131/** @defgroup grp_selm_r3   The Selector Monitor(/Manager) API
    … …  
    345133 * @{
    346134 */
    347 
    348 /**
    349  * Initializes the SELM.
    350  *
    351  * @returns VBox status code.
    352  * @param   pVM         The VM to operate on.
    353  */
    354 VMMR3DECL(int) SELMR3Init(PVM pVM);
    355 
    356 /**
    357  * Finalizes HMA page attributes.
    358  *
    359  * @returns VBox status code.
    360  * @param   pVM     The VM handle.
    361  */
    362 VMMR3DECL(int) SELMR3InitFinalize(PVM pVM);
    363 
    364 /**
    365  * Applies relocations to data and code managed by this
    366  * component. This function will be called at init and
    367  * whenever the VMM need to relocate it self inside the GC.
    368  *
    369  * @param   pVM     The VM.
    370  */
    371 VMMR3DECL(void) SELMR3Relocate(PVM pVM);
    372 
    373 /**
    374  * Notification callback which is called whenever there is a chance that a CR3
    375  * value might have changed.
    376  * This is called by PGM.
    377  *
    378  * @param   pVM       The VM handle
    379  */
    380 VMMR3DECL(void) SELMR3PagingModeChanged(PVM pVM);
    381 
    382 /**
    383  * Terminates the SELM.
    384  *
    385  * Termination means cleaning up and freeing all resources,
    386  * the VM it self is at this point powered off or suspended.
    387  *
    388  * @returns VBox status code.
    389  * @param   pVM         The VM to operate on.
    390  */
    391 VMMR3DECL(int) SELMR3Term(PVM pVM);
    392 
    393 /**
    394  * The VM is being reset.
    395  *
    396  * For the SELM component this means that any GDT/LDT/TSS monitors
    397  * needs to be removed.
    398  *
    399  * @param   pVM     VM handle.
    400  */
    401 VMMR3DECL(void) SELMR3Reset(PVM pVM);
    402 
    403 /**
    404  * Updates the Guest GDT & LDT virtualization based on current CPU state.
    405  *
    406  * @returns VBox status code.
    407  * @param   pVM         The VM to operate on.
    408  */
    409 VMMR3DECL(int) SELMR3UpdateFromCPUM(PVM pVM);
    410 
    411 /**
    412  * Compares the Guest GDT and LDT with the shadow tables.
    413  * This is a VBOX_STRICT only function.
    414  *
    415  * @returns VBox status code.
    416  * @param   pVM         The VM Handle.
    417  */
    418 VMMR3DECL(int) SELMR3DebugCheck(PVM pVM);
    419 #ifdef VBOX_STRICT
    420 # define SELMR3DEBUGCHECK(pVM)     SELMR3DebugCheck(pVM)
    421 #else
    422 # define SELMR3DEBUGCHECK(pVM)     do { } while (0)
    423 #endif
    424 
    425 /**
    426  * Check if the TSS ring 0 stack selector and pointer were updated (for now)
    427  *
    428  * @returns VBox status code.
    429  * @param   pVM         The VM to operate on.
    430  */
    431 VMMR3DECL(int) SELMR3SyncTSS(PVM pVM);
    432 
    433 /**
    434  * Gets information about a selector.
    435  * Intended for the debugger mostly and will prefer the guest
    436  * descriptor tables over the shadow ones.
    437  *
    438  * @returns VINF_SUCCESS on success.
    439  * @returns VERR_INVALID_SELECTOR if the selector isn't fully inside the descriptor table.
    440  * @returns VERR_SELECTOR_NOT_PRESENT if the selector wasn't present.
    441  * @returns VERR_PAGE_TABLE_NOT_PRESENT or VERR_PAGE_NOT_PRESENT if the pagetable or page
    442  *          backing the selector table wasn't present.
    443  * @returns Other VBox status code on other errros.
    444  *
    445  * @param   pVM         VM handle.
    446  * @param   Sel         The selector to get info about.
    447  * @param   pSelInfo    Where to store the information.
    448  */
    449 VMMR3DECL(int) SELMR3GetSelectorInfo(PVM pVM, RTSEL Sel, PSELMSELINFO pSelInfo);
    450 
    451 /**
    452  * Gets information about a selector from the shadow tables.
    453  *
    454  * This is intended to be faster than the SELMR3GetSelectorInfo() method, but requires
    455  * that the caller ensures that the shadow tables are up to date.
    456  *
    457  * @returns VINF_SUCCESS on success.
    458  * @returns VERR_INVALID_SELECTOR if the selector isn't fully inside the descriptor table.
    459  * @returns VERR_SELECTOR_NOT_PRESENT if the selector wasn't present.
    460  * @returns VERR_PAGE_TABLE_NOT_PRESENT or VERR_PAGE_NOT_PRESENT if the pagetable or page
    461  *          backing the selector table wasn't present.
    462  * @returns Other VBox status code on other errors.
    463  *
    464  * @param   pVM         VM handle.
    465  * @param   Sel         The selector to get info about.
    466  * @param   pSelInfo    Where to store the information.
    467  */
    468 VMMR3DECL(int) SELMR3GetShadowSelectorInfo(PVM pVM, RTSEL Sel, PSELMSELINFO pSelInfo);
    469 
    470 /**
    471  * Validates the RawR0 TSS values against the one in the Guest TSS.
    472  *
    473  * @returns true if it matches.
    474  * @returns false and assertions on mismatch..
    475  * @param   pVM     VM Handle.
    476  */
    477 VMMR3DECL(bool) SELMR3CheckTSS(PVM pVM);
    478 
    479 
    480 /**
    481  * Disable GDT/LDT/TSS monitoring and syncing
    482  *
    483  * @param   pVM         The VM to operate on.
    484  */
    485 VMMR3DECL(void) SELMR3DisableMonitoring(PVM pVM);
    486 
    487 
    488 /**
    489  * Dumps a descriptor.
    490  *
    491  * @param   Desc    Descriptor to dump.
    492  * @param   Sel     Selector number.
    493  * @param   pszMsg  Message to prepend the log entry with.
    494  */
    495 VMMR3DECL(void) SELMR3DumpDescriptor(X86DESC  Desc, RTSEL Sel, const char *pszMsg);
    496 
    497 /**
    498  * Dumps the hypervisor GDT.
    499  *
    500  * @param   pVM     VM handle.
    501  */
    502 VMMR3DECL(void) SELMR3DumpHyperGDT(PVM pVM);
    503 
    504 /**
    505  * Dumps the hypervisor LDT.
    506  *
    507  * @param   pVM     VM handle.
    508  */
    509 VMMR3DECL(void) SELMR3DumpHyperLDT(PVM pVM);
    510 
    511 /**
    512  * Dumps the guest GDT.
    513  *
    514  * @param   pVM     VM handle.
    515  */
    516 VMMR3DECL(void) SELMR3DumpGuestGDT(PVM pVM);
    517 
    518 /**
    519  * Dumps the guest LDT.
    520  *
    521  * @param   pVM     VM handle.
    522  */
    523 VMMR3DECL(void) SELMR3DumpGuestLDT(PVM pVM);
    524 
     135VMMR3DECL(int)      SELMR3Init(PVM pVM);
     136VMMR3DECL(int)      SELMR3InitFinalize(PVM pVM);
     137VMMR3DECL(void)     SELMR3Relocate(PVM pVM);
     138VMMR3DECL(void)     SELMR3PagingModeChanged(PVM pVM);
     139VMMR3DECL(int)      SELMR3Term(PVM pVM);
     140VMMR3DECL(void)     SELMR3Reset(PVM pVM);
     141VMMR3DECL(int)      SELMR3UpdateFromCPUM(PVM pVM);
     142VMMR3DECL(int)      SELMR3SyncTSS(PVM pVM);
     143VMMR3DECL(int)      SELMR3GetSelectorInfo(PVM pVM, RTSEL Sel, PSELMSELINFO pSelInfo);
     144VMMR3DECL(int)      SELMR3GetShadowSelectorInfo(PVM pVM, RTSEL Sel, PSELMSELINFO pSelInfo);
     145VMMR3DECL(void)     SELMR3DisableMonitoring(PVM pVM);
     146VMMR3DECL(void)     SELMR3DumpDescriptor(X86DESC  Desc, RTSEL Sel, const char *pszMsg);
     147VMMR3DECL(void)     SELMR3DumpHyperGDT(PVM pVM);
     148VMMR3DECL(void)     SELMR3DumpHyperLDT(PVM pVM);
     149VMMR3DECL(void)     SELMR3DumpGuestGDT(PVM pVM);
     150VMMR3DECL(void)     SELMR3DumpGuestLDT(PVM pVM);
     151VMMR3DECL(bool)     SELMR3CheckTSS(PVM pVM);
     152VMMR3DECL(int)      SELMR3DebugCheck(PVM pVM);
     153/** @def SELMR3_DEBUG_CHECK
     154 * Invokes SELMR3DebugCheck in stricts builds. */
     155# ifdef VBOX_STRICT
     156#  define SELMR3_DEBUG_CHECK(pVM)    SELMR3DebugCheck(pVM)
     157# else
     158#  define SELMR3_DEBUG_CHECK(pVM)    do { } while (0)
     159# endif
    525160/** @} */
    526 #endif
    527 
     161#endif /* IN_RING3 */
    528162
    529163/** @} */
    530164__END_DECLS
    531165
     166#endif
    532167
    533 #endif
Note: See TracChangeset for help on using the changeset viewer.

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