VirtualBox

Changeset 4013 in vbox for trunk/include/VBox


Ignore:
Timestamp:
Aug 3, 2007 12:11:38 AM (17 years ago)
Author:
vboxsync
Message:

pdm.h = include pdm*.h; pdmapi.h = only the 'core' pdm APIs.

Location:
trunk/include/VBox
Files:
3 edited
1 copied

Legend:

Unmodified
Added
Removed

  • trunk/include/VBox/pdm.h

    r4011 r4013  
    2222#define ___VBox_pdm_h
    2323
     24#include <VBox/pdmapi.h>
    2425#include <VBox/pdmqueue.h>
    2526#include <VBox/pdmcritsect.h>
    … …  
    3031#include <VBox/pdmusb.h>
    3132#include <VBox/pdmsrv.h>
    32 
    33 __BEGIN_DECLS
    34 
    35 /** @defgroup grp_pdm       The Pluggable Device Manager API
    36  * @{
    37  */
    3833
    3934/** Source position.
    … …  
    4944#define PDM_SRC_POS_ARGS    RT_SRC_POS_ARGS
    5045
    51 
    52 
    53 /**
    54  * Gets the pending interrupt.
    55  *
    56  * @returns VBox status code.
    57  * @param   pVM             VM handle.
    58  * @param   pu8Interrupt    Where to store the interrupt on success.
    59  */
    60 PDMDECL(int) PDMGetInterrupt(PVM pVM, uint8_t *pu8Interrupt);
    61 
    62 /**
    63  * Sets the pending ISA interrupt.
    64  *
    65  * @returns VBox status code.
    66  * @param   pVM             VM handle.
    67  * @param   u8Irq           The IRQ line.
    68  * @param   u8Level         The new level. See the PDM_IRQ_LEVEL_* \#defines.
    69  */
    70 PDMDECL(int) PDMIsaSetIrq(PVM pVM, uint8_t u8Irq, uint8_t u8Level);
    71 
    72 /**
    73  * Sets the pending I/O APIC interrupt.
    74  *
    75  * @returns VBox status code.
    76  * @param   pVM             VM handle.
    77  * @param   u8Irq           The IRQ line.
    78  * @param   u8Level         The new level. See the PDM_IRQ_LEVEL_* \#defines.
    79  */
    80 PDMDECL(int) PDMIoApicSetIrq(PVM pVM, uint8_t u8Irq, uint8_t u8Level);
    81 
    82 /**
    83  * Set the APIC base.
    84  *
    85  * @returns VBox status code.
    86  * @param   pVM             VM handle.
    87  * @param   u64Base         The new base.
    88  */
    89 PDMDECL(int) PDMApicSetBase(PVM pVM, uint64_t u64Base);
    90 
    91 /**
    92  * Get the APIC base.
    93  *
    94  * @returns VBox status code.
    95  * @param   pVM             VM handle.
    96  * @param   pu64Base        Where to store the APIC base.
    97  */
    98 PDMDECL(int) PDMApicGetBase(PVM pVM, uint64_t *pu64Base);
    99 
    100 /**
    101  * Set the TPR (task priority register?).
    102  *
    103  * @returns VBox status code.
    104  * @param   pVM             VM handle.
    105  * @param   u8TPR           The new TPR.
    106  */
    107 PDMDECL(int) PDMApicSetTPR(PVM pVM, uint8_t u8TPR);
    108 
    109 /**
    110  * Get the TPR (task priority register?).
    111  *
    112  * @returns The current TPR.
    113  * @param   pVM             VM handle.
    114  * @param   pu8TPR          Where to store the TRP.
    115  */
    116 PDMDECL(int) PDMApicGetTPR(PVM pVM, uint8_t *pu8TPR);
    117 
    118 
    119 #ifdef IN_RING3
    120 /** @defgroup grp_pdm_r3    The PDM Host Context Ring-3 API
    121  * @ingroup grp_pdm
    122  * @{
    123  */
    124 
    125 /**
    126  * Initializes the PDM.
    127  *
    128  * @returns VBox status code.
    129  * @param   pVM         The VM to operate on.
    130  */
    131 PDMR3DECL(int) PDMR3Init(PVM pVM);
    132 
    133 /**
    134  * This function will notify all the devices and their
    135  * attached drivers about the VM now being powered on.
    136  *
    137  * @param   pVM     VM Handle.
    138  */
    139 PDMR3DECL(void) PDMR3PowerOn(PVM pVM);
    140 
    141 /**
    142  * This function will notify all the devices and their
    143  * attached drivers about the VM now being reset.
    144  *
    145  * @param   pVM     VM Handle.
    146  */
    147 PDMR3DECL(void) PDMR3Reset(PVM pVM);
    148 
    149 /**
    150  * This function will notify all the devices and their
    151  * attached drivers about the VM now being suspended.
    152  *
    153  * @param   pVM     VM Handle.
    154  */
    155 PDMR3DECL(void) PDMR3Suspend(PVM pVM);
    156 
    157 /**
    158  * This function will notify all the devices and their
    159  * attached drivers about the VM now being resumed.
    160  *
    161  * @param   pVM     VM Handle.
    162  */
    163 PDMR3DECL(void) PDMR3Resume(PVM pVM);
    164 
    165 /**
    166  * This function will notify all the devices and their
    167  * attached drivers about the VM being powered off.
    168  *
    169  * @param   pVM     VM Handle.
    170  */
    171 PDMR3DECL(void) PDMR3PowerOff(PVM pVM);
    172 
    173 
    174 /**
    175  * Applies relocations to GC modules.
    176  *
    177  * This must be done very early in the relocation
    178  * process so that components can resolve GC symbols during relocation.
    179  *
    180  * @param   pVM         VM handle.
    181  * @param   offDelta    Relocation delta relative to old location.
    182  */
    183 PDMR3DECL(void) PDMR3LdrRelocate(PVM pVM, RTGCINTPTR offDelta);
    184 
    185 /**
    186  * Applies relocations to data and code managed by this
    187  * component. This function will be called at init and
    188  * whenever the VMM need to relocate it self inside the GC.
    189  *
    190  * @param   pVM         VM handle.
    191  * @param   offDelta    Relocation delta relative to old location.
    192  */
    193 PDMR3DECL(void) PDMR3Relocate(PVM pVM, RTGCINTPTR offDelta);
    194 
    195 /**
    196  * Terminates the PDM.
    197  *
    198  * Termination means cleaning up and freeing all resources,
    199  * the VM it self is at this point powered off or suspended.
    200  *
    201  * @returns VBox status code.
    202  * @param   pVM         The VM to operate on.
    203  */
    204 PDMR3DECL(int) PDMR3Term(PVM pVM);
    205 
    206 
    207 /**
    208  * Get the address of a symbol in a given HC ring-3 module.
    209  *
    210  * @returns VBox status code.
    211  * @param   pVM             VM handle.
    212  * @param   pszModule       Module name.
    213  * @param   pszSymbol       Symbol name. If it's value is less than 64k it's treated like a
    214  *                          ordinal value rather than a string pointer.
    215  * @param   ppvValue        Where to store the symbol value.
    216  */
    217 PDMR3DECL(int) PDMR3GetSymbolR3(PVM pVM, const char *pszModule, const char *pszSymbol, void **ppvValue);
    218 
    219 /**
    220  * Get the address of a symbol in a given HC ring-0 module.
    221  *
    222  * @returns VBox status code.
    223  * @param   pVM             VM handle.
    224  * @param   pszModule       Module name. If NULL the main R0 module (VMMR0.r0) is assumed.
    225  * @param   pszSymbol       Symbol name. If it's value is less than 64k it's treated like a
    226  *                          ordinal value rather than a string pointer.
    227  * @param   ppvValue        Where to store the symbol value.
    228  */
    229 PDMR3DECL(int) PDMR3GetSymbolR0(PVM pVM, const char *pszModule, const char *pszSymbol, PRTR0PTR ppvValue);
    230 
    231 /**
    232  * Same as PDMR3GetSymbolR0 except that the module will be attempted loaded if not found.
    233  *
    234  * @returns VBox status code.
    235  * @param   pVM             VM handle.
    236  * @param   pszModule       Module name. If NULL the main R0 module (VMMR0.r0) is assumed.
    237  * @param   pszSymbol       Symbol name. If it's value is less than 64k it's treated like a
    238  *                          ordinal value rather than a string pointer.
    239  * @param   ppvValue        Where to store the symbol value.
    240  */
    241 PDMR3DECL(int) PDMR3GetSymbolR0Lazy(PVM pVM, const char *pszModule, const char *pszSymbol, PRTR0PTR ppvValue);
    242 
    243 /**
    244  * Loads a module into the guest context (i.e. into the Hypervisor memory region).
    245  *
    246  * The external (to PDM) use of this interface is to load VMMGC.gc.
    247  *
    248  * @returns VBox status code.
    249  * @param   pVM             The VM to load it into.
    250  * @param   pszFilename     Filename of the module binary.
    251  * @param   pszName         Module name. Case sensitive and the length is limited!
    252  */
    253 PDMR3DECL(int) PDMR3LoadGC(PVM pVM, const char *pszFilename, const char *pszName);
    254 
    255 /**
    256  * Get the address of a symbol in a given GC module.
    257  *
    258  * @returns VBox status code.
    259  * @param   pVM             VM handle.
    260  * @param   pszModule       Module name. If NULL the main GC module (VMMGC.gc) is assumed.
    261  * @param   pszSymbol       Symbol name. If it's value is less than 64k it's treated like a
    262  *                          ordinal value rather than a string pointer.
    263  * @param   pGCPtrValue     Where to store the symbol value.
    264  */
    265 PDMR3DECL(int) PDMR3GetSymbolGC(PVM pVM, const char *pszModule, const char *pszSymbol, PRTGCPTR pGCPtrValue);
    266 
    267 /**
    268  * Same as PDMR3GetSymbolGC except that the module will be attempted loaded if not found.
    269  *
    270  * @returns VBox status code.
    271  * @param   pVM             VM handle.
    272  * @param   pszModule       Module name. If NULL the main GC module (VMMGC.gc) is assumed.
    273  * @param   pszSymbol       Symbol name. If it's value is less than 64k it's treated like a
    274  *                          ordinal value rather than a string pointer.
    275  * @param   pGCPtrValue     Where to store the symbol value.
    276  */
    277 PDMR3DECL(int) PDMR3GetSymbolGCLazy(PVM pVM, const char *pszModule, const char *pszSymbol, PRTGCPTR pGCPtrValue);
    278 
    279 /**
    280  * Queries module information from an EIP.
    281  *
    282  * This is typically used to locate a crash address.
    283  *
    284  * @returns VBox status code.
    285  * @param   pVM         VM handle
    286  * @param   uEIP        EIP to locate.
    287  * @param   pszModName  Where to store the module name.
    288  * @param   cchModName  Size of the module name buffer.
    289  * @param   pMod        Base address of the module.
    290  * @param   pszNearSym1 Name of the closes symbol from below.
    291  * @param   cchNearSym1 Size of the buffer pointed to by pszNearSym1.
    292  * @param   pNearSym1   The address of pszNearSym1.
    293  * @param   pszNearSym2 Name of the closes symbol from below.
    294  * @param   cchNearSym2 Size of the buffer pointed to by pszNearSym2.
    295  * @param   pNearSym2   The address of pszNearSym2.
    296  */
    297 PDMR3DECL(int) PDMR3QueryModFromEIP(PVM pVM, uint32_t uEIP,
    298                                     char *pszModName,  unsigned cchModName,  RTGCPTR *pMod,
    299                                     char *pszNearSym1, unsigned cchNearSym1, RTGCPTR *pNearSym1,
    300                                     char *pszNearSym2, unsigned cchNearSym2, RTGCPTR *pNearSym2);
    301 
    302 
    303 /**
    304  * Module enumeration callback function.
    305  *
    306  * @returns VBox status.
    307  *          Failure will stop the search and return the return code.
    308  *          Warnings will be ignored and not returned.
    309  * @param   pVM             VM Handle.
    310  * @param   pszFilename     Module filename.
    311  * @param   pszName         Module name. (short and unique)
    312  * @param   ImageBase       Address where to executable image is loaded.
    313  * @param   cbImage         Size of the executable image.
    314  * @param   fGC             Set if guest context, clear if host context.
    315  * @param   pvArg           User argument.
    316  */
    317 typedef DECLCALLBACK(int) FNPDMR3ENUM(PVM pVM, const char *pszFilename, const char *pszName, RTUINTPTR ImageBase, size_t cbImage, bool fGC);
    318 /** Pointer to a FNPDMR3ENUM() function. */
    319 typedef FNPDMR3ENUM *PFNPDMR3ENUM;
    320 
    321 
    322 /**
    323  * Enumerate all PDM modules.
    324  *
    325  * @returns VBox status.
    326  * @param   pVM             VM Handle.
    327  * @param   pfnCallback     Function to call back for each of the modules.
    328  * @param   pvArg           User argument.
    329  */
    330 PDMR3DECL(int)  PDMR3EnumModules(PVM pVM, PFNPDMR3ENUM pfnCallback, void *pvArg);
    331 
    332 
    333 /**
    334  * Queries the base interace of a device instance.
    335  *
    336  * The caller can use this to query other interfaces the device implements
    337  * and use them to talk to the device.
    338  *
    339  * @returns VBox status code.
    340  * @param   pVM             VM handle.
    341  * @param   pszDevice       Device name.
    342  * @param   iInstance       Device instance.
    343  * @param   ppBase          Where to store the pointer to the base device interface on success.
    344  * @remark  We're not doing any locking ATM, so don't try call this at times when the
    345  *          device chain is known to be updated.
    346  */
    347 PDMR3DECL(int) PDMR3QueryDevice(PVM pVM, const char *pszDevice, unsigned iInstance, PPDMIBASE *ppBase);
    348 
    349 /**
    350  * Queries the base interface of a device LUN.
    351  *
    352  * This differs from PDMR3QueryLun by that it returns the interface on the
    353  * device and not the top level driver.
    354  *
    355  * @returns VBox status code.
    356  * @param   pVM             VM Handle.
    357  * @param   pszDevice       Device name.
    358  * @param   iInstance       Device instance.
    359  * @param   iLun            The Logical Unit to obtain the interface of.
    360  * @param   ppBase          Where to store the base interface pointer.
    361  * @remark  We're not doing any locking ATM, so don't try call this at times when the
    362  *          device chain is known to be updated.
    363  */
    364 PDMR3DECL(int) PDMR3QueryDeviceLun(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
    365 
    366 /**
    367  * Query the interface of the top level driver on a LUN.
    368  *
    369  * @returns VBox status code.
    370  * @param   pVM             VM Handle.
    371  * @param   pszDevice       Device name.
    372  * @param   iInstance       Device instance.
    373  * @param   iLun            The Logical Unit to obtain the interface of.
    374  * @param   ppBase          Where to store the base interface pointer.
    375  * @remark  We're not doing any locking ATM, so don't try call this at times when the
    376  *          device chain is known to be updated.
    377  */
    378 PDMR3DECL(int) PDMR3QueryLun(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
    379 
    380 /**
    381  * Attaches a preconfigured driver to an existing device instance.
    382  *
    383  * This is used to change drivers and suchlike at runtime.
    384  *
    385  * @returns VBox status code.
    386  * @param   pVM             VM Handle.
    387  * @param   pszDevice       Device name.
    388  * @param   iInstance       Device instance.
    389  * @param   iLun            The Logical Unit to obtain the interface of.
    390  * @param   ppBase          Where to store the base interface pointer. Optional.
    391  * @thread  EMT
    392  */
    393 PDMR3DECL(int) PDMR3DeviceAttach(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
    394 
    395 /**
    396  * Detaches a driver from an existing device instance.
    397  *
    398  * This is used to change drivers and suchlike at runtime.
    399  *
    400  * @returns VBox status code.
    401  * @param   pVM             VM Handle.
    402  * @param   pszDevice       Device name.
    403  * @param   iInstance       Device instance.
    404  * @param   iLun            The Logical Unit to obtain the interface of.
    405  * @thread  EMT
    406  */
    407 PDMR3DECL(int) PDMR3DeviceDetach(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun);
    408 
    409 /**
    410  * Executes pending DMA transfers.
    411  * Forced Action handler.
    412  *
    413  * @param   pVM             VM handle.
    414  */
    415 PDMR3DECL(void) PDMR3DmaRun(PVM pVM);
    416 
    417 /**
    418  * Call polling function.
    419  *
    420  * @param   pVM             VM handle.
    421  */
    422 PDMR3DECL(void) PDMR3Poll(PVM pVM);
    423 
    424 /**
    425  * Service a VMMCALLHOST_PDM_LOCK call.
    426  *
    427  * @returns VBox status code.
    428  * @param   pVM     The VM handle.
    429  */
    430 PDMR3DECL(int) PDMR3LockCall(PVM pVM);
    431 
    432 /** @} */
    43346#endif
    43447
    435 
    436 #ifdef IN_GC
    437 /** @defgroup grp_pdm_gc    The PDM Guest Context API
    438  * @ingroup grp_pdm
    439  * @{
    440  */
    441 /** @} */
    442 #endif
    443 
    444 __END_DECLS
    445 
    446 /** @} */
    447 
    448 #endif
    449 

  • trunk/include/VBox/pdmapi.h

    r4011 r4013  
    11/** @file
    2  * PDM - Pluggable Device Manager.
     2 * PDM - Pluggable Device Manager, Core API.
     3 *
     4 * The 'Core API' has been put in a different header because everyone
     5 * is currently including pdm.h. So, pdm.h is for including all of the
     6 * PDM stuff, while pdmapi.h is for the core stuff.
    37 */
    48
    … …  
    1923 */
    2024
    21 #ifndef ___VBox_pdm_h
    22 #define ___VBox_pdm_h
    23 
    24 #include <VBox/pdmqueue.h>
    25 #include <VBox/pdmcritsect.h>
    26 #include <VBox/pdmthread.h>
    27 #include <VBox/pdmifs.h>
    28 #include <VBox/pdmdrv.h>
    29 #include <VBox/pdmdev.h>
    30 #include <VBox/pdmusb.h>
    31 #include <VBox/pdmsrv.h>
     25#ifndef ___VBox_pdmapi_h
     26#define ___VBox_pdmapi_h
     27
     28#include <VBox/types.h>
    3229
    3330__BEGIN_DECLS
    … …  
    3633 * @{
    3734 */
    38 
    39 /** Source position.
    40  * @deprecated Use RT_SRC_POS */
    41 #define PDM_SRC_POS         RT_SRC_POS
    42 
    43 /** Source position declaration.
    44  * @deprecated Use RT_SRC_POS_DECL */
    45 #define PDM_SRC_POS_DECL    RT_SRC_POS_DECL
    46 
    47 /** Source position arguments.
    48  * @deprecated Use RT_SRC_POS_ARGS */
    49 #define PDM_SRC_POS_ARGS    RT_SRC_POS_ARGS
    50 
    51 
    5235
    5336/**
    … …  
    345328 *          device chain is known to be updated.
    346329 */
    347 PDMR3DECL(int) PDMR3QueryDevice(PVM pVM, const char *pszDevice, unsigned iInstance, PPDMIBASE *ppBase);
     330PDMR3DECL(int) PDMR3QueryDevice(PVM pVM, const char *pszDevice, unsigned iInstance, PPPDMIBASE ppBase);
    348331
    349332/**
    … …  
    362345 *          device chain is known to be updated.
    363346 */
    364 PDMR3DECL(int) PDMR3QueryDeviceLun(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
     347PDMR3DECL(int) PDMR3QueryDeviceLun(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPPDMIBASE ppBase);
    365348
    366349/**
    … …  
    376359 *          device chain is known to be updated.
    377360 */
    378 PDMR3DECL(int) PDMR3QueryLun(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
     361PDMR3DECL(int) PDMR3QueryLun(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPPDMIBASE ppBase);
    379362
    380363/**
    … …  
    391374 * @thread  EMT
    392375 */
    393 PDMR3DECL(int) PDMR3DeviceAttach(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
     376PDMR3DECL(int) PDMR3DeviceAttach(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPPDMIBASE ppBase);
    394377
    395378/**

  • trunk/include/VBox/pdmifs.h

    r4011 r4013  
    153153    DECLR3CALLBACKMEMBER(void *, pfnQueryInterface,(struct PDMIBASE *pInterface, PDMINTERFACE enmInterface));
    154154} PDMIBASE;
    155 /** Pointer to a PDM Driver Base Interface. */
    156 typedef PDMIBASE *PPDMIBASE;
    157155
    158156

  • trunk/include/VBox/types.h

    r3852 r4013  
    118118} VMSTATE;
    119119
     120
     121/** Pointer to a PDM Driver Base Interface. */
     122typedef struct PDMIBASE *PPDMIBASE;
     123/** Pointer to a pointer to a PDM Driver Base Interface. */
     124typedef PPDMIBASE *PPPDMIBASE;
    120125
    121126/** Pointer to a PDM Device Instance. */
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