VirtualBox

Changeset 3852

Show
Ignore:
Timestamp:
07/25/07 21:09:09 (1 year ago)
Author:
vboxsync
Message:

Finally splitting up pdm.h. Working on integrating USB into PDM (USBProxy needs CFGM stuff).

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/include/VBox/pdm.h

    • Property svn:keywords changed from Author Date Id Revision to Id
    <
    r3830 r3852  
    3535#include <iprt/stdarg.h> 
    3636 
     37#include <VBox/pdmqueue.h> 
     38#include <VBox/pdmcritsect.h> 
     39#include <VBox/pdmthread.h> 
     40#include <VBox/pdmifs.h> 
     41#include <VBox/pdmdrv.h> 
     42#include <VBox/pdmdev.h> 
     43#include <VBox/pdmusb.h> 
     44#include <VBox/pdmsrv.h> 
     45 
    3746 
    3847__BEGIN_DECLS 
    …… 
    5564 
    5665 
    57 /** @defgroup grp_pdm_queue     The PDM Queue 
    58  * @ingroup grp_pdm 
    59  * @{ 
    60  */ 
    61  
    62 /** Pointer to a PDM queue. Also called PDM queue handle. */ 
    63 typedef struct PDMQUEUE *PPDMQUEUE; 
    64  
    65 /** Pointer to a PDM queue item core. */ 
    66 typedef struct PDMQUEUEITEMCORE *PPDMQUEUEITEMCORE; 
    67  
    68 /** 
    69  * PDM queue item core. 
    70  */ 
    71 typedef struct PDMQUEUEITEMCORE 
    72 { 
    73     /** Pointer to the next item in the pending list - HC Pointer. */ 
    74     HCPTRTYPE(PPDMQUEUEITEMCORE)    pNextHC; 
    75     /** Pointer to the next item in the pending list - GC Pointer. */ 
    76     GCPTRTYPE(PPDMQUEUEITEMCORE)    pNextGC; 
    77 #if HC_ARCH_BITS == 64 && GC_ARCH_BITS == 32 
    78     uint32_t                        Alignment0; 
    79 #endif 
    80 } PDMQUEUEITEMCORE; 
    81  
    82  
    83 /** 
    84  * Queue consumer callback for devices. 
    85  * 
    86  * @returns Success indicator. 
    87  *          If false the item will not be removed and the flushing will stop. 
    88  * @param   pDevIns     The device instance. 
    89  * @param   pItem       The item to consume. Upon return this item will be freed. 
    90  */ 
    91 typedef DECLCALLBACK(bool) FNPDMQUEUEDEV(PPDMDEVINS pDevIns, PPDMQUEUEITEMCORE pItem); 
    92 /** Pointer to a FNPDMQUEUEDEV(). */ 
    93 typedef FNPDMQUEUEDEV *PFNPDMQUEUEDEV; 
    94  
    95 /** 
    96  * Queue consumer callback for drivers. 
    97  * 
    98  * @returns Success indicator. 
    99  *          If false the item will not be removed and the flushing will stop. 
    100  * @param   pDrvIns     The driver instance. 
    101  * @param   pItem       The item to consume. Upon return this item will be freed. 
    102  */ 
    103 typedef DECLCALLBACK(bool) FNPDMQUEUEDRV(PPDMDRVINS pDrvIns, PPDMQUEUEITEMCORE pItem); 
    104 /** Pointer to a FNPDMQUEUEDRV(). */ 
    105 typedef FNPDMQUEUEDRV *PFNPDMQUEUEDRV; 
    106  
    107 /** 
    108  * Queue consumer callback for internal component. 
    109  * 
    110  * @returns Success indicator. 
    111  *          If false the item will not be removed and the flushing will stop. 
    112  * @param   pVM         The VM handle. 
    113  * @param   pItem       The item to consume. Upon return this item will be freed. 
    114  */ 
    115 typedef DECLCALLBACK(bool) FNPDMQUEUEINT(PVM pVM, PPDMQUEUEITEMCORE pItem); 
    116 /** Pointer to a FNPDMQUEUEINT(). */ 
    117 typedef FNPDMQUEUEINT *PFNPDMQUEUEINT; 
    118  
    119 /** 
    120  * Queue consumer callback for external component. 
    121  * 
    122  * @returns Success indicator. 
    123  *          If false the item will not be removed and the flushing will stop. 
    124  * @param   pvUser      User argument. 
    125  * @param   pItem       The item to consume. Upon return this item will be freed. 
    126  */ 
    127 typedef DECLCALLBACK(bool) FNPDMQUEUEEXT(void *pvUser, PPDMQUEUEITEMCORE pItem); 
    128 /** Pointer to a FNPDMQUEUEEXT(). */ 
    129 typedef FNPDMQUEUEEXT *PFNPDMQUEUEEXT; 
    130  
    131 /** 
    132  * Create a queue with a device owner. 
    133  * 
    134  * @returns VBox status code. 
    135  * @param   pVM                 VM handle. 
    136  * @param   pDevIns             Device instance. 
    137  * @param   cbItem              Size a queue item. 
    138  * @param   cItems              Number of items in the queue. 
    139  * @param   cMilliesInterval    Number of milliseconds between polling the queue. 
    140  *                              If 0 then the emulation thread will be notified whenever an item arrives. 
    141  * @param   pfnCallback         The consumer function. 
    142  * @param   fGCEnabled          Set if the queue must be usable from GC. 
    143  * @param   ppQueue             Where to store the queue handle on success. 
    144  * @thread  Emulation thread only. 
    145  */ 
    146 PDMR3DECL(int) PDMR3QueueCreateDevice(PVM pVM, PPDMDEVINS pDevIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, 
    147                                       PFNPDMQUEUEDEV pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue); 
    148  
    149 /** 
    150  * Create a queue with a driver owner. 
    151  * 
    152  * @returns VBox status code. 
    153  * @param   pVM                 VM handle. 
    154  * @param   pDrvIns             Driver instance. 
    155  * @param   cbItem              Size a queue item. 
    156  * @param   cItems              Number of items in the queue. 
    157  * @param   cMilliesInterval    Number of milliseconds between polling the queue. 
    158  *                              If 0 then the emulation thread will be notified whenever an item arrives. 
    159  * @param   pfnCallback         The consumer function. 
    160  * @param   ppQueue             Where to store the queue handle on success. 
    161  * @thread  The emulation thread. 
    162  */ 
    163 PDMR3DECL(int) PDMR3QueueCreateDriver(PVM pVM, PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, 
    164                                       PFNPDMQUEUEDRV pfnCallback, PPDMQUEUE *ppQueue); 
    165  
    166 /** 
    167  * Create a queue with an internal owner. 
    168  * 
    169  * @returns VBox status code. 
    170  * @param   pVM                 VM handle. 
    171  * @param   cbItem              Size a queue item. 
    172  * @param   cItems              Number of items in the queue. 
    173  * @param   cMilliesInterval    Number of milliseconds between polling the queue. 
    174  *                              If 0 then the emulation thread will be notified whenever an item arrives. 
    175  * @param   pfnCallback         The consumer function. 
    176  * @param   fGCEnabled          Set if the queue must be usable from GC. 
    177  * @param   ppQueue             Where to store the queue handle on success. 
    178  * @thread  Emulation thread only. 
    179  */ 
    180 PDMR3DECL(int) PDMR3QueueCreateInternal(PVM pVM, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, 
    181                                         PFNPDMQUEUEINT pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue); 
    182  
    183 /** 
    184  * Create a queue with an external owner. 
    185  * 
    186  * @returns VBox status code. 
    187  * @param   pVM                 VM handle. 
    188  * @param   cbItem              Size a queue item. 
    189  * @param   cItems              Number of items in the queue. 
    190  * @param   cMilliesInterval    Number of milliseconds between polling the queue. 
    191  *                              If 0 then the emulation thread will be notified whenever an item arrives. 
    192  * @param   pfnCallback         The consumer function. 
    193  * @param   pvUser              The user argument to the consumer function. 
    194  * @param   ppQueue             Where to store the queue handle on success. 
    195  * @thread  The emulation thread. 
    196  */ 
    197 PDMR3DECL(int) PDMR3QueueCreateExternal(PVM pVM, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, 
    198                                         PFNPDMQUEUEEXT pfnCallback, void *pvUser, PPDMQUEUE *ppQueue); 
    199  
    200 /** 
    201  * Destroy a queue. 
    202  * 
    203  * @returns VBox status code. 
    204  * @param   pQueue      Queue to destroy. 
    205  * @thread  The emulation thread. 
    206  */ 
    207 PDMR3DECL(int) PDMR3QueueDestroy(PPDMQUEUE pQueue); 
    208  
    209 /** 
    210  * Destroy a all queues owned by the specified device. 
    211  * 
    212  * @returns VBox status code. 
    213  * @param   pVM         VM handle. 
    214  * @param   pDevIns     Device instance. 
    215  * @thread  Emulation thread only. 
    216  */ 
    217 PDMR3DECL(int) PDMR3QueueDestroyDevice(PVM pVM, PPDMDEVINS pDevIns); 
    218  
    219 /** 
    220  * Destroy a all queues owned by the specified driver. 
    221  * 
    222  * @returns VBox status code. 
    223  * @param   pVM         VM handle. 
    224  * @param   pDrvIns     Driver instance. 
    225  * @thread  Emulation thread only. 
    226  */ 
    227 PDMR3DECL(int) PDMR3QueueDestroyDriver(PVM pVM, PPDMDRVINS pDrvIns); 
    228  
    229 /** 
    230  * Flushes pending queues. 
    231  * This is a forced action callback. 
    232  * 
    233  * @param   pVM     VM handle. 
    234  * @thread  The emulation thread. 
    235  */ 
    236 PDMR3DECL(void) PDMR3QueueFlushAll(PVM pVM); 
    237  
    238 /** 
    239  * This is a worker function used by PDMQueueFlush to perform the 
    240  * flush in ring-3. 
    241  * 
    242  * The queue which should be flushed is pointed to by either pQueueFlushGC, 
    243  * pQueueFlushHC, or pQueueue. This function will flush that queue and 
    244  * recalc the queue FF. 
    245  * 
    246  * @param   pVM     The VM handle. 
    247  * @param   pQueue  The queue to flush. Only used in Ring-3. 
    248  */ 
    249 PDMR3DECL(void) PDMR3QueueFlushWorker(PVM pVM, PPDMQUEUE pQueue); 
    250  
    251 /** 
    252  * Flushes a PDM queue. 
    253  * 
    254  * @param   pQueue          The queue handle. 
    255  */ 
    256 PDMDECL(void) PDMQueueFlush(PPDMQUEUE pQueue); 
    257  
    258 /** 
    259  * Allocate an item from a queue. 
    260  * The allocated item must be handed on to PDMQueueInsert() after the 
    261  * data has been filled in. 
    262  * 
    263  * @returns Pointer to allocated queue item. 
    264  * @returns NULL on failure. The queue is exhausted. 
    265  * @param   pQueue      The queue handle. 
    266  * @thread  Any thread. 
    267  */ 
    268 PDMDECL(PPDMQUEUEITEMCORE) PDMQueueAlloc(PPDMQUEUE pQueue); 
    269  
    270 /** 
    271  * Queue an item. 
    272  * The item must have been obtained using PDMQueueAlloc(). Once the item 
    273  * has been passed to this function it must not be touched! 
    274  * 
    275  * @param   pQueue      The queue handle. 
    276  * @param   pItem       The item to insert. 
    277  * @thread  Any thread. 
    278  */ 
    279 PDMDECL(void) PDMQueueInsert(PPDMQUEUE pQueue, PPDMQUEUEITEMCORE pItem); 
    280  
    281 /** 
    282  * Queue an item. 
    283  * The item must have been obtained using PDMQueueAlloc(). Once the item 
    284  * have been passed to this function it must not be touched! 
    285  * 
    286  * @param   pQueue          The queue handle. 
    287  * @param   pItem           The item to insert. 
    288  * @param   NanoMaxDelay    The maximum delay before processing the queue, in nanoseconds. 
    289  *                          This applies only to GC. 
    290  * @thread  Any thread. 
    291  */ 
    292 PDMDECL(void) PDMQueueInsertEx(PPDMQUEUE pQueue, PPDMQUEUEITEMCORE pItem, uint64_t NanoMaxDelay); 
    293  
    294  
    295 /** 
    296  * Gets the GC pointer for the specified queue. 
    297  * 
    298  * @returns The GC address of the queue. 
    299  * @returns NULL if pQueue is invalid. 
    300  * @param   pQueue          The queue handle. 
    301  */ 
    302 PDMDECL(GCPTRTYPE(PPDMQUEUE)) PDMQueueGCPtr(PPDMQUEUE pQueue); 
    303  
    304 /** @} */ 
    305  
    306  
    307  
    308 /** @defgroup grp_pdm_critsect      The PDM Critical Section 
    309  * @ingroup grp_pdm 
    310  * @{ 
    311  */ 
    312  
    313 /** 
    314  * A PDM critical section. 
    315  * Initialize using PDMDRVHLP::pfnCritSectInit(). 
    316  */ 
    317 typedef union PDMCRITSECT 
    318 { 
    319     /** Padding. */ 
    320     uint8_t padding[HC_ARCH_BITS == 64 ? 0xb8 : 0x80]; 
    321 #ifdef PDMCRITSECTINT_DECLARED 
    322     /** The internal structure (not normally visible). */ 
    323     struct PDMCRITSECTINT s; 
    324 #endif 
    325 } PDMCRITSECT; 
    326 /** Pointer to a PDM critical section. */ 
    327 typedef PDMCRITSECT *PPDMCRITSECT; 
    328 /** Pointer to a const PDM critical section. */ 
    329 typedef const PDMCRITSECT *PCPDMCRITSECT; 
    330  
    331 /** 
    332  * Initializes a PDM critical section for internal use. 
    333  * 
    334  * The PDM critical sections are derived from the IPRT critical sections, but 
    335  * works in GC as well. 
    336  * 
    337  * @returns VBox status code. 
    338  * @param   pVM             The VM handle. 
    339  * @param   pDevIns         Device instance. 
    340  * @param   pCritSect       Pointer to the critical section. 
    341  * @param   pszName         The name of the critical section (for statistics). 
    342  */ 
    343 PDMR3DECL(int) PDMR3CritSectInit(PVM pVM, PPDMCRITSECT pCritSect, const char *pszName); 
    344  
    345 /** 
    346  * Leaves a critical section entered with PDMCritSectEnter(). 
    347  * 
    348  * @returns VINF_SUCCESS if entered successfully. 
    349  * @returns rcBusy when encountering a busy critical section in GC/R0. 
    350  * @returns VERR_SEM_DESTROYED if the critical section is dead. 
    351  * 
    352  * @param   pCritSect           The PDM critical section to enter. 
    353  * @param   rcBusy              The status code to return when we're in GC or R0 
    354  *                              and the section is busy. 
    355  */ 
    356 PDMDECL(int) PDMCritSectEnter(PPDMCRITSECT pCritSect, int rcBusy); 
    357  
    358 /** 
    359  * Leaves a critical section entered with PDMCritSectEnter(). 
    360  * 
    361  * @param   pCritSect           The PDM critical section to leave. 
    362  */ 
    363 PDMDECL(void) PDMCritSectLeave(PPDMCRITSECT pCritSect); 
    364  
    365 /** 
    366  * Checks the caller is the owner of the critical section. 
    367  * 
    368  * @returns true if owner. 
    369  * @returns false if not owner. 
    370  * @param   pCritSect   The critical section. 
    371  */ 
    372 PDMDECL(bool) PDMCritSectIsOwner(PCPDMCRITSECT pCritSect); 
    373  
    374 /** 
    375  * Try enter a critical section. 
    376  * 
    377  * @returns VINF_SUCCESS on success. 
    378  * @returns VERR_SEM_BUSY if the critsect was owned. 
    379  * @returns VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.) 
    380  * @returns VERR_SEM_DESTROYED if RTCritSectDelete was called while waiting. 
    381  * @param   pCritSect   The critical section. 
    382  */ 
    383 PDMR3DECL(int) PDMR3CritSectTryEnter(PPDMCRITSECT pCritSect); 
    384  
    385 /** 
    386  * Schedule a event semaphore for signalling upon critsect exit. 
    387  * 
    388  * @returns VINF_SUCCESS on success. 
    389  * @returns VERR_TOO_MANY_SEMAPHORES if an event was already scheduled. 
    390  * @returns VERR_NOT_OWNER if we're not the critsect owner. 
    391  * @returns VERR_SEM_DESTROYED if RTCritSectDelete was called while waiting. 
    392  * @param   pCritSect       The critical section. 
    393  * @param   EventToSignal     The semapore that should be signalled. 
    394  */ 
    395 PDMR3DECL(int) PDMR3CritSectScheduleExitEvent(PPDMCRITSECT pCritSect, RTSEMEVENT EventToSignal); 
    396  
    397 /** 
    398  * Deletes the critical section. 
    399  * 
    400  * @returns VBox status code. 
    401  * @param   pCritSect           The PDM critical section to destroy. 
    402  */ 
    403 PDMR3DECL(int) PDMR3CritSectDelete(PPDMCRITSECT pCritSect); 
    404  
    405 /** 
    406  * Deletes all remaining critical sections. 
    407  * 
    408  * This is called at the end of the termination process. 
    409  * 
    410  * @returns VBox status. 
    411  *          First error code, rest is lost. 
    412  * @param   pVM         The VM handle. 
    413  * @remark  Don't confuse this with PDMR3CritSectDelete. 
    414  */ 
    415 PDMDECL(int) PDMR3CritSectTerm(PVM pVM); 
    416  
    417 /** 
    418  * Process the critical sections queued for ring-3 'leave'. 
    419  * 
    420  * @param   pVM         The VM handle. 
    421  */ 
    422 PDMR3DECL(void) PDMR3CritSectFF(PVM pVM); 
    423  
    424 /** @} */ 
    425  
    426  
    427 /** @group grp_pdm_thread 
    428  * @{ 
    429  */ 
    430  
    431 /** 
    432  * The thread state 
    433  */ 
    434 typedef enum PDMTHREADSTATE 
    435 { 
    436     /** The usual invalid 0 entry. */ 
    437     PDMTHREADSTATE_INVALID = 0, 
    438     /** The thread is initializing. 
    439      * Prev state: none 
    440      * Next state: suspended, terminating (error) */ 
    441     PDMTHREADSTATE_INITIALIZING, 
    442     /** The thread has been asked to suspend. 
    443      * Prev state: running 
    444      * Next state: suspended */ 
    445     PDMTHREADSTATE_SUSPENDING, 
    446     /** The thread is supended. 
    447      * Prev state: suspending, initializing 
    448      * Next state: resuming, terminated. */ 
    449     PDMTHREADSTATE_SUSPENDED, 
    450     /** The thread is active. 
    451      * Prev state: suspended 
    452      * Next state: running, terminating. */ 
    453     PDMTHREADSTATE_RESUMING, 
    454     /** The thread is active. 
    455      * Prev state: resuming 
    456      * Next state: suspending, terminating. */ 
    457     PDMTHREADSTATE_RUNNING, 
    458     /** The thread has been asked to terminate. 
    459      * Prev state: initializing, suspended, resuming, running 
    460      * Next state: terminated. */ 
    461     PDMTHREADSTATE_TERMINATING, 
    462     /** The thread is terminating / has terminated. 
    463      * Prev state: terminating 
    464      * Next state: none */ 
    465     PDMTHREADSTATE_TERMINATED, 
    466     /** The usual 32-bit hack. */ 
    467     PDMTHREADSTATE_32BIT_HACK = 0x7fffffff 
    468 } PDMTHREADSTATE; 
    469  
    470 /** A pointer to a PDM thread. */ 
    471 typedef R3PTRTYPE(struct PDMTHREAD *) PPDMTHREAD; 
    472 /** A pointer to a pointer to a PDM thread. */ 
    473 typedef PPDMTHREAD *PPPDMTHREAD; 
    474  
    475 /** 
    476  * PDM thread, device variation. 
    477  * 
    478  * @returns VBox status code. 
    479  * @param   pDevIns     The device instance. 
    480  * @param   pThread     The PDM thread data. 
    481  */ 
    482 typedef int FNPDMTHREADDEV(PPDMDEVINS pDevIns, PPDMTHREAD pThread); 
    483 /** Pointer to a FNPDMTHREADDEV(). */ 
    484 typedef FNPDMTHREADDEV *PFNPDMTHREADDEV; 
    485  
    486 /** 
    487  * PDM thread, driver variation. 
    488  * 
    489  * @returns VBox status code. 
    490  * @param   pDrvIns     The driver instance. 
    491  * @param   pThread     The PDM thread data. 
    492  */ 
    493 typedef int FNPDMTHREADDRV(PPDMDRVINS pDrvIns, PPDMTHREAD pThread); 
    494 /** Pointer to a FNPDMTHREADDRV(). */ 
    495 typedef FNPDMTHREADDRV *PFNPDMTHREADDRV; 
    496  
    497 /** 
    498  * PDM thread, driver variation. 
    499  * 
    500  * @returns VBox status code. 
    501  * @param   pVM         The VM handle. 
    502  * @param   pThread     The PDM thread data. 
    503  */ 
    504 typedef int FNPDMTHREADINT(PVM pVM, PPDMTHREAD pThread); 
    505 /** Pointer to a FNPDMTHREADINT(). */ 
    506 typedef FNPDMTHREADINT *PFNPDMTHREADINT; 
    507  
    508 /** 
    509  * PDM thread, driver variation. 
    510  * 
    511  * @returns VBox status code. 
    512  * @param   pThread     The PDM thread data. 
    513  */ 
    514 typedef int FNPDMTHREADEXT(PPDMTHREAD pThread); 
    515 /** Pointer to a FNPDMTHREADEXT(). */ 
    516 typedef FNPDMTHREADEXT *PFNPDMTHREADEXT; 
    517  
    518  
    519  
    520 /** 
    521  * PDM thread wakup call, device variation. 
    522  * 
    523  * @returns VBox status code. 
    524  * @param   pDevIns     The device instance. 
    525  * @param   pThread     The PDM thread data. 
    526  */ 
    527 typedef int FNPDMTHREADWAKEUPDEV(PPDMDEVINS pDevIns, PPDMTHREAD pThread); 
    528 /** Pointer to a FNPDMTHREADDEV(). */ 
    529 typedef FNPDMTHREADWAKEUPDEV *PFNPDMTHREADWAKEUPDEV; 
    530  
    531 /** 
    532  * PDM thread wakup call, driver variation. 
    533  * 
    534  * @returns VBox status code. 
    535  * @param   pDrvIns     The driver instance. 
    536  * @param   pThread     The PDM thread data. 
    537  */ 
    538 typedef int FNPDMTHREADWAKEUPDRV(PPDMDRVINS pDrvIns, PPDMTHREAD pThread); 
    539 /** Pointer to a FNPDMTHREADDRV(). */ 
    540 typedef FNPDMTHREADWAKEUPDRV *PFNPDMTHREADWAKEUPDRV; 
    541  
    542 /** 
    543  * PDM thread wakup call, internal variation. 
    544  * 
    545  * @returns VBox status code. 
    546  * @param   pVM         The VM handle. 
    547  * @param   pThread     The PDM thread data. 
    548  */ 
    549 typedef int FNPDMTHREADWAKEUPINT(PVM pVM, PPDMTHREAD pThread); 
    550 /** Pointer to a FNPDMTHREADWAKEUPINT(). */ 
    551 typedef FNPDMTHREADWAKEUPINT *PFNPDMTHREADWAKEUPINT; 
    552  
    553 /** 
    554  * PDM thread wakup call, external variation. 
    555  * 
    556  * @returns VBox status code. 
    557  * @param   pThread     The PDM thread data. 
    558  */ 
    559 typedef int FNPDMTHREADWAKEUPEXT(PPDMTHREAD pThread); 
    560 /** Pointer to a FNPDMTHREADEXT(). */ 
    561 typedef FNPDMTHREADWAKEUPEXT *PFNPDMTHREADWAKEUPEXT; 
    562  
    563  
    564 /** 
    565  * PDM Thread instance data. 
    566  */ 
    567 typedef struct PDMTHREAD 
    568 { 
    569     /** PDMTHREAD_VERSION. */ 
    570     uint32_t                    u32Version; 
    571     /** The thread state. */ 
    572     PDMTHREADSTATE volatile     enmState; 
    573     /** The thread handle. */ 
    574     RTTHREAD                    Thread; 
    575     /** The user parameter. */ 
    576     R3PTRTYPE(void *)           pvUser; 
    577     /** Data specific to the kind of thread. 
    578      * This should really be in PDMTHREADINT, but is placed here because of the 
    579      * function pointer typedefs. So, don't touch these, please. 
    580      */ 
    581     union 
    582     { 
    583         /** PDMTHREADTYPE_DEVICE data. */ 
    584         struct 
    585         { 
    586             /** The device instance. */ 
    587             PPDMDEVINSR3                        pDevIns; 
    588             /** The thread function. */ 
    589             R3PTRTYPE(PFNPDMTHREADDEV)          pfnThread; 
    590             /** Thread. */ 
    591             R3PTRTYPE(PFNPDMTHREADWAKEUPDEV)    pfnWakeup; 
    592         } Dev; 
    593  
    594         /** PDMTHREADTYPE_DRIVER data. */ 
    595         struct 
    596         { 
    597             /** The driver instance. */ 
    598             R3PTRTYPE(PPDMDRVINS)               pDrvIns; 
    599             /** The thread function. */ 
    600             R3PTRTYPE(PFNPDMTHREADDRV)          pfnThread; 
    601             /** Thread. */ 
    602             R3PTRTYPE(PFNPDMTHREADWAKEUPDRV)    pfnWakeup; 
    603         } Drv; 
    604  
    605         /** PDMTHREADTYPE_INTERNAL data. */ 
    606         struct 
    607         { 
    608             /** The thread function. */ 
    609             R3PTRTYPE(PFNPDMTHREADINT)          pfnThread; 
    610             /** Thread. */ 
    611             R3PTRTYPE(PFNPDMTHREADWAKEUPINT)    pfnWakeup; 
    612         } Int; 
    613  
    614         /** PDMTHREADTYPE_EXTERNAL data. */ 
    615         struct 
    616         { 
    617             /** The thread function. */ 
    618             R3PTRTYPE(PFNPDMTHREADEXT)          pfnThread; 
    619             /** Thread. */ 
    620             R3PTRTYPE(PFNPDMTHREADWAKEUPEXT)    pfnWakeup; 
    621         } Ext; 
    622     } u; 
    623  
    624     /** Internal data. */ 
    625     union 
    626     { 
    627 #ifdef PDMTHREADINT_DECLARED 
    628         PDMTHREADINT            s; 
    629 #endif 
    630         uint8_t                 padding[64]; 
    631     } Internal; 
    632 } PDMTHREAD; 
    633  
    634 /** PDMTHREAD::u32Version value. */ 
    635 #define PDMTHREAD_VERSION   0xef010000 
    636  
    637  
    638 /** @} */ 
    639  
    640  
    641  
    642 /** @defgroup grp_pdm_interfaces    Interfaces 
    643  * @ingroup grp_pdm 
    644  * @{ 
    645  */ 
    646  
    647 /** 
    648  * Driver interface identficators. 
    649  */ 
    650 typedef enum PDMINTERFACE 
    651 { 
    652     /** PDMIBASE                - The interface everyone supports. */ 
    653     PDMINTERFACE_BASE = 1, 
    654     /** PDMIMOUSEPORT           - The mouse port interface.             (Down)  Coupled with PDMINTERFACE_MOUSE_CONNECTOR. */ 
    655     PDMINTERFACE_MOUSE_PORT, 
    656     /** PDMIMOUSECONNECTOR      - The mouse connector interface.        (Up)    Coupled with PDMINTERFACE_MOUSE_PORT. */ 
    657     PDMINTERFACE_MOUSE_CONNECTOR, 
    658     /** PDMIKEYBOARDPORT        - The keyboard port interface.          (Down)  Coupled with PDMINTERFACE_KEYBOARD_CONNECTOR. */ 
    659     PDMINTERFACE_KEYBOARD_PORT, 
    660     /** PDMIKEYBOARDCONNECTOR   - The keyboard connector interface.     (Up)    Coupled with PDMINTERFACE_KEYBOARD_PORT. */ 
    661     PDMINTERFACE_KEYBOARD_CONNECTOR, 
    662     /** PDMIDISPLAYPORT         - The display port interface.           (Down)  Coupled with PDMINTERFACE_DISPLAY_CONNECTOR. */ 
    663     PDMINTERFACE_DISPLAY_PORT, 
    664     /** PDMIDISPLAYCONNECTOR    - The display connector interface.      (Up)    Coupled with PDMINTERFACE_DISPLAY_PORT. */ 
    665     PDMINTERFACE_DISPLAY_CONNECTOR, 
    666     /** PDMICHARPORT            - The char notify interface.            (Down)  Coupled with PDMINTERFACE_CHAR. */ 
    667     PDMINTERFACE_CHAR_PORT, 
    668     /** PDMICHAR                - The char driver interface.            (Up)    Coupled with PDMINTERFACE_CHAR_PORT. */ 
    669     PDMINTERFACE_CHAR, 
    670     /** PDMISTREAM              - The stream driver interface           (Up)    No coupling. 
    671      * Used by a char driver to implement PDMINTERFACE_CHAR. */ 
    672     PDMINTERFACE_STREAM, 
    673     /** PDMIBLOCKPORT           - The block notify interface            (Down)  Coupled with PDMINTERFACE_BLOCK. */ 
    674     PDMINTERFACE_BLOCK_PORT, 
    675     /** PDMIBLOCK               - The block driver interface            (Up)    Coupled with PDMINTERFACE_BLOCK_PORT. */ 
    676     PDMINTERFACE_BLOCK, 
    677     /** PDMIBLOCKBIOS           - The block bios interface.             (External) */ 
    678     PDMINTERFACE_BLOCK_BIOS, 
    679     /** PDMIMOUNTNOTIFY         - The mountable notification interface. (Down)  Coupled with PDMINTERFACE_MOUNT. */ 
    680     PDMINTERFACE_MOUNT_NOTIFY, 
    681     /** PDMIMOUNT               - The mountable interface.              (Up)    Coupled with PDMINTERFACE_MOUNT_NOTIFY. */ 
    682     PDMINTERFACE_MOUNT, 
    683     /** PDMIMEDIA               - The media interface.                  (Up)    No coupling. 
    684      * Used by a block unit driver to implement PDMINTERFACE_BLOCK and PDMINTERFACE_BLOCK_BIOS. */ 
    685     PDMINTERFACE_MEDIA, 
    686     /** PDMIISCSITRANSPORT      - The iSCSI transport interface         (Up)    No coupling. 
    687      * used by the iSCSI media driver.  */ 
    688     PDMINTERFACE_ISCSITRANSPORT, 
    689  
    690     /** PDMINETWORKPORT         - The network port interface.           (Down)  Coupled with PDMINTERFACE_NETWORK_CONNECTOR. */ 
    691     PDMINTERFACE_NETWORK_PORT, 
    692     /** PDMINETWORKPORT         - The network connector interface.      (Up)    Coupled with PDMINTERFACE_NETWORK_PORT. */ 
    693     PDMINTERFACE_NETWORK_CONNECTOR, 
    694     /** PDMINETWORKCONFIG       - The network configuartion interface.  (Main)  Used by the managment api. */ 
    695     PDMINTERFACE_NETWORK_CONFIG, 
    696  
    697     /** PDMIAUDIOCONNECTOR      - The audio driver interface.           (Up)    No coupling. */ 
    698     PDMINTERFACE_AUDIO_CONNECTOR, 
    699  
    700     /** PDMIAUDIOSNIFFERPORT    - The Audio Sniffer Device port interface. */ 
    701     PDMINTERFACE_AUDIO_SNIFFER_PORT, 
    702     /** PDMIAUDIOSNIFFERCONNECTOR - The Audio Sniffer Driver connector interface. */ 
    703     PDMINTERFACE_AUDIO_SNIFFER_CONNECTOR, 
    704  
    705     /** PDMIVMMDEVPORT          - The VMM Device port interface. */ 
    706     PDMINTERFACE_VMMDEV_PORT, 
    707     /** PDMIVMMDEVCONNECTOR     - The VMM Device connector interface. */ 
    708     PDMINTERFACE_VMMDEV_CONNECTOR, 
    709  
    710     /** PDMILEDPORTS            - The generic LED port interface.       (Down)  Coupled with PDMINTERFACE_LED_CONNECTORS. */ 
    711     PDMINTERFACE_LED_PORTS, 
    712     /** PDMILEDCONNECTORS       - The generic LED connector interface.  (Up)    Coupled with PDMINTERFACE_LED_PORTS.  */ 
    713     PDMINTERFACE_LED_CONNECTORS, 
    714  
    715     /** PDMIACPIPORT            - ACPI port interface.                  (Down)   Coupled with PDMINTERFACE_ACPI_CONNECTOR. */ 
    716     PDMINTERFACE_ACPI_PORT, 
    717     /** PDMIACPICONNECTOR       - ACPI connector interface.             (Up)     Coupled with PDMINTERFACE_ACPI_PORT. */ 
    718     PDMINTERFACE_ACPI_CONNECTOR, 
    719  
    720     /** PDMIHGCMPORT            - The Host-Guest communication manager port interface. Normally implemented by VMMDev. */ 
    721     PDMINTERFACE_HGCM_PORT, 
    722     /** PDMIHGCMCONNECTOR       - The Host-Guest communication manager connector interface. Normally implemented by Main::VMMDevInterface. */ 
    723     PDMINTERFACE_HGCM_CONNECTOR, 
    724  
    725     /** VUSBIROOTHUBPORT        - VUSB RootHub port interface.          (Down)   Coupled with PDMINTERFACE_USB_RH_CONNECTOR. */ 
    726     PDMINTERFACE_VUSB_RH_PORT, 
    727     /** VUSBIROOTHUBCONNECTOR   - VUSB RootHub connector interface.     (Up)     Coupled with PDMINTERFACE_USB_RH_PORT. */ 
    728     PDMINTERFACE_VUSB_RH_CONNECTOR, 
    729     /** VUSBIRHCONFIG           - VUSB RootHub configuration interface. (Main)   Used by the managment api. */ 
    730     PDMINTERFACE_VUSB_RH_CONFIG, 
    731  
    732     /** VUSBROOTHUBCONNECTOR    - VUSB Device interface.                (Up)     No coupling. */ 
    733     PDMINTERFACE_VUSB_DEVICE, 
    734  
    735     /** PDMIHOSTDEVICEPORT      - The Host Device port interface.       (Down)   Coupled with PDMINTERFACE_HOST_DEVICE_CONNECTOR. */ 
    736     PDMINTERFACE_HOST_DEVICE_PORT, 
    737     /** PDMIHOSTDEVICECONNECTOR - The Host device connector interface   (Up)     Coupled with PDMINTERFACE_HOST_DEVICE_PORT. */ 
    738     PDMINTERFACE_HOST_DEVICE_CONNECTOR, 
    739  
    740     /** Maximum interface number. */ 
    741     PDMINTERFACE_MAX 
    742 } PDMINTERFACE; 
    743  
    744  
    745 /** 
    746  * PDM Driver Base Interface. 
    747  */ 
    748 typedef struct PDMIBASE 
    749 { 
    750     /** 
    751      * Queries an interface to the driver. 
    752      * 
    753      * @returns Pointer to interface. 
    754      * @returns NULL if the interface was not supported by the driver. 
    755      * @param   pInterface          Pointer to this interface structure. 
    756      * @param   enmInterface        The requested interface identification. 
    757      * @thread  Any thread. 
    758      */ 
    759     DECLR3CALLBACKMEMBER(void *, pfnQueryInterface,(struct PDMIBASE *pInterface, PDMINTERFACE enmInterface)); 
    760 } PDMIBASE; 
    761 /** Pointer to a PDM Driver Base Interface. */ 
    762 typedef PDMIBASE *PPDMIBASE; 
    763  
    764  
    765 /** 
    766  * Dummy interface. 
    767  * 
    768  * This is used to typedef other dummy interfaces. The purpose of a dummy 
    769  * interface is to validate the logical function of a driver/device and 
    770  * full a natural interface pair. 
    771  */ 
    772 typedef struct PDMIDUMMY 
    773 { 
    774     RTHCPTR pvDummy; 
    775 } PDMIDUMMY; 
    776  
    777  
    778 /** Pointer to a mouse port interface. */ 
    779 typedef struct PDMIMOUSEPORT *PPDMIMOUSEPORT; 
    780 /** 
    781  * Mouse port interface. 
    782  * Pair with PDMIMOUSECONNECTOR. 
    783  */ 
    784 typedef struct PDMIMOUSEPORT 
    785 { 
    786     /** 
    787      * Puts a mouse event. 
    788      * This is called by the source of mouse events. The event will be passed up until the 
    789      * topmost driver, which then calls the registered event handler. 
    790      * 
    791      * @returns VBox status code. 
    792      * @param   pInterface          Pointer to this interface structure. 
    793      * @param   i32DeltaX       The X delta. 
    794      * @param   i32DeltaY       The Y delta. 
    795      * @param   i32DeltaZ       The Z delta. 
    796      * @param   fButtonStates   The button states, see the PDMIMOUSEPORT_BUTTON_* \#defines. 
    797      * @thread  The emulation thread. 
    798      */ 
    799     DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIMOUSEPORT pInterface, int32_t i32DeltaX, int32_t i32DeltaY, int32_t i32DeltaZ, uint32_t fButtonStates)); 
    800 } PDMIMOUSEPORT; 
    801  
    802 /** Mouse button defines for PDMIMOUSEPORT::pfnPutEvent. 
    803  * @{ */ 
    804 #define PDMIMOUSEPORT_BUTTON_LEFT   BIT(0) 
    805 #define PDMIMOUSEPORT_BUTTON_RIGHT  BIT(1) 
    806 #define PDMIMOUSEPORT_BUTTON_MIDDLE BIT(2) 
    807 /** @} */ 
    808  
    809  
    810 /** 
    811  * Mouse connector interface. 
    812  * Pair with PDMIMOUSEPORT. 
    813  */ 
    814 typedef PDMIDUMMY PDMIMOUSECONNECTOR; 
    815  /** Pointer to a mouse connector interface. */ 
    816 typedef PDMIMOUSECONNECTOR *PPDMIMOUSECONNECTOR; 
    817  
    818  
    819 /** Pointer to a keyboard port interface. */ 
    820 typedef struct PDMIKEYBOARDPORT *PPDMIKEYBOARDPORT; 
    821 /** 
    822  * Keyboard port interface. 
    823  * Pair with PDMIKEYBOARDCONNECTOR. 
    824  */ 
    825 typedef struct PDMIKEYBOARDPORT 
    826 { 
    827     /** 
    828      * Puts a keyboard event. 
    829      * This is called by the source of keyboard events. The event will be passed up until the 
    830      * topmost driver, which then calls the registered event handler. 
    831      * 
    832      * @returns VBox status code. 
    833      * @param   pInterface          Pointer to this interface structure. 
    834      * @param   u8KeyCode           The keycode to queue. 
    835      * @thread  The emulation thread. 
    836      */ 
    837     DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIKEYBOARDPORT pInterface, uint8_t u8KeyCode)); 
    838 } PDMIKEYBOARDPORT; 
    839  
    840 /** 
    841  * Keyboard LEDs. 
    842  */ 
    843 typedef enum PDMKEYBLEDS 
    844 { 
    845     /** No leds. */ 
    846     PDMKEYBLEDS_NONE             = 0x0000, 
    847     /** Num Lock */ 
    848     PDMKEYBLEDS_NUMLOCK          = 0x0001, 
    849     /** Caps Lock */ 
    850     PDMKEYBLEDS_CAPSLOCK         = 0x0002, 
    851     /** Scroll Lock */ 
    852     PDMKEYBLEDS_SCROLLLOCK       = 0x0004 
    853 } PDMKEYBLEDS; 
    854  
    855 /** Pointer to keyboard connector interface. */ 
    856 typedef struct PDMIKEYBOARDCONNECTOR *PPDMIKEYBOARDCONNECTOR; 
    857  
    858  
    859 /** 
    860  * Keyboard connector interface. 
    861  * Pair with PDMIKEYBOARDPORT 
    862  */ 
    863 typedef struct PDMIKEYBOARDCONNECTOR 
    864 { 
    865     /** 
    866      * Notifies the the downstream driver about an LED change initiated by the guest. 
    867      * 
    868      * @param   pInterface      Pointer to the this interface. 
    869      * @param   enmLeds         The new led mask. 
    870      */ 
    871     DECLR3CALLBACKMEMBER(void, pfnLedStatusChange,(PPDMIKEYBOARDCONNECTOR pInterface, PDMKEYBLEDS enmLeds)); 
    872  
    873 } PDMIKEYBOARDCONNECTOR; 
    874  
    875  
    876  
    877 /** Pointer to a display port interface. */ 
    878 typedef struct PDMIDISPLAYPORT *PPDMIDISPLAYPORT; 
    879 /** 
    880  * Display port interface. 
    881  * Pair with PDMIDISPLAYCONNECTOR. 
    882  */ 
    883 typedef struct PDMIDISPLAYPORT 
    884 { 
    885     /** 
    886      * Update the display with any changed regions. 
    887      * 
    888      * Flushes any display changes to the memory pointed to by the 
    889      * PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect() 
    890      * while doing so. 
    891      * 
    892      * @returns VBox status code. 
    893      * @param   pInterface          Pointer to this interface. 
    894      * @thread  The emulation thread. 
    895      */ 
    896     DECLR3CALLBACKMEMBER(int, pfnUpdateDisplay,(PPDMIDISPLAYPORT pInterface)); 
    897  
    898     /** 
    899      * Update the entire display. 
    900      * 
    901      * Flushes the entire display content to the memory pointed to by the 
    902      * PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect(). 
    903      * 
    904      * @returns VBox status code. 
    905      * @param   pInterface          Pointer to this interface. 
    906      * @thread  The emulation thread. 
    907      */ 
    908     DECLR3CALLBACKMEMBER(int, pfnUpdateDisplayAll,(PPDMIDISPLAYPORT pInterface)); 
    909  
    910     /** 
    911      * Return the current guest color depth in bits per pixel (bpp). 
    912      * 
    913      * As the graphics card is able to provide display updates with the bpp 
    914      * requested by the host, this method can be used to query the actual 
    915      * guest color depth. 
    916      * 
    917      * @returns VBox status code. 
    918      * @param   pInterface         Pointer to this interface. 
    919      * @param   pcBits             Where to store the current guest color depth. 
    920      * @thread  Any thread. 
    921      */ 
    922     DECLR3CALLBACKMEMBER(int, pfnQueryColorDepth,(PPDMIDISPLAYPORT pInterface, uint32_t *pcBits)); 
    923  
    924     /** 
    925      * Sets the refresh rate and restart the timer. 
    926      * The rate is defined as the minimum interval between the return of 
    927      * one PDMIDISPLAYPORT::pfnRefresh() call to the next one. 
    928      * 
    929      * The interval timer will be restarted by this call. So at VM startup 
    930      * this function must be called to start the refresh cycle. The refresh 
    931      * rate is not saved, but have to be when resuming a loaded VM state. 
    932      * 
    933      * @returns VBox status code. 
    934      * @param   pInterface          Pointer to this interface. 
    935      * @param   cMilliesInterval    Number of millies between two refreshes. 
    936      * @thread  Any thread. 
    937      */ 
    938     DECLR3CALLBACKMEMBER(int, pfnSetRefreshRate,(PPDMIDISPLAYPORT pInterface, uint32_t cMilliesInterval)); 
    939  
    940     /** 
    941      * Create a 32-bbp snapshot of the display. 
    942      * 
    943      * This will create a 32-bbp bitmap with dword aligned scanline length. Because 
    944      * of a wish for no locks in the graphics device, this must be called from the 
    945      * emulation thread. 
    946      * 
    947      * @param   pInterface          Pointer to this interface. 
    948      * @param   pvData              Pointer the buffer to copy the bits to. 
    949      * @param   cbData              Size of the buffer. 
    950      * @param   pcx                 Where to store the width of the bitmap. (optional) 
    951      * @param   pcy                 Where to store the height of the bitmap. (optional) 
    952      * @param   pcbData             Where to store the actual size of the bitmap. (optional) 
    953      * @thread  The emulation thread. 
    954      */ 
    955     DECLR3CALLBACKMEMBER(int, pfnSnapshot,(PPDMIDISPLAYPORT pInterface, void *pvData, size_t cbData, uint32_t *pcx, uint32_t *pcy, size_t *pcbData)); 
    956  
    957     /** 
    958      * Copy bitmap to the display. 
    959      * 
    960      * This will convert and copy a 32-bbp bitmap (with dword aligned scanline length) to 
    961      * the memory pointed to by the PDMIDISPLAYCONNECTOR interface. 
    962      * 
    963      * @param   pInterface          Pointer to this interface. 
    964      * @param   pvData              Pointer to the bitmap bits. 
    965      * @param   x                   The upper left corner x coordinate of the destination rectangle. 
    966      * @param   y                   The upper left corner y coordinate of the destination rectangle. 
    967      * @param   cx                  The width of the source and destination rectangles. 
    968      * @param   cy                  The height of the source and destination rectangles. 
    969      * @thread  The emulation thread. 
    970      * @remark  This is just a convenience for using the bitmap conversions of the 
    971      *          graphics device. 
    972      */ 
    973     DECLR3CALLBACKMEMBER(int, pfnDisplayBlt,(PPDMIDISPLAYPORT pInterface, const void *pvData, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy)); 
    974  
    975     /** 
    976      * Render a rectangle from guest VRAM to Framebuffer. 
    977      * 
    978      * @param   pInterface          Pointer to this interface. 
    979      * @param   x                   The upper left corner x coordinate of the rectangle to be updated. 
    980      * @param   y                   The upper left corner y coordinate of the rectangle to be updated. 
    981      * @param   cx                  The width of the rectangle to be updated. 
    982      * @param   cy                  The height of the rectangle to be updated. 
    983      * @thread  The emulation thread. 
    984      */ 
    985     DECLR3CALLBACKMEMBER(void, pfnUpdateDisplayRect,(PPDMIDISPLAYPORT pInterface, int32_t x, int32_t y, uint32_t cx, uint32_t cy)); 
    986  
    987     /** 
    988      * Inform the VGA device whether the Display is directly using the guest VRAM and there is no need 
    989      * to render the VRAM to the framebuffer memory. 
    990      * 
    991      * @param   pInterface          Pointer to this interface. 
    992      * @param   fRender             Whether the VRAM content must be rendered to the framebuffer. 
    993      * @thread  The emulation thread. 
    994      */ 
    995     DECLR3CALLBACKMEMBER(void, pfnSetRenderVRAM,(PPDMIDISPLAYPORT pInterface, bool fRender)); 
    996  
    997 } PDMIDISPLAYPORT; 
    998  
    999  
    1000 /** Pointer to a display connector interface. */ 
    1001 typedef struct PDMIDISPLAYCONNECTOR *PPDMIDISPLAYCONNECTOR; 
    1002 /** 
    1003  * Display connector interface. 
    1004  * Pair with PDMIDISPLAYPORT. 
    1005  */ 
    1006 typedef struct PDMIDISPLAYCONNECTOR 
    1007 { 
    1008     /** 
    1009      * Resize the display. 
    1010      * This is called when the resolution changes. This usually happens on 
    1011      * request from the guest os, but may also happen as the result of a reset. 
    1012      * If the callback returns VINF_VGA_RESIZE_IN_PROGRESS, the caller (VGA device) 
    1013      * must not access the connector and return. 
    1014      * 
    1015      * @returns VINF_SUCCESS if the framebuffer resize was completed, 
    1016      *          VINF_VGA_RESIZE_IN_PROGRESS if resize takes time and not yet finished. 
    1017      * @param   pInterface          Pointer to this interface. 
    1018      * @param   cBits               Color depth (bits per pixel) of the new video mode. 
    1019      * @param   pvVRAM              Address of the guest VRAM. 
    1020      * @param   cbLine              Size in bytes of a single scan line. 
    1021      * @param   cx                  New display width. 
    1022      * @param   cy                  New display height. 
    1023      * @thread  The emulation thread. 
    1024      */ 
    1025     DECLR3CALLBACKMEMBER(int, pfnResize,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t cBits, void *pvVRAM, uint32_t cbLine, uint32_t cx, uint32_t cy)); 
    1026  
    1027     /** 
    1028      * Update a rectangle of the display. 
    1029      * PDMIDISPLAYPORT::pfnUpdateDisplay is the caller. 
    1030      * 
    1031      * @param   pInterface          Pointer to this interface.