Changeset 3852 in vbox for trunk/include
- Timestamp:
- Jul 25, 2007 7:09:09 PM (18 years ago)
- Location:
- trunk/include/VBox
- Files:
-
- 3 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/include/VBox/pdm.h
-
Property svn:keywords
changed from
Author Date Id RevisiontoId
r3830 r3852 35 35 #include <iprt/stdarg.h> 36 36 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 37 46 38 47 __BEGIN_DECLS … … 55 64 56 65 57 /** @defgroup grp_pdm_queue The PDM Queue58 * @ingroup grp_pdm59 * @{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 PDMQUEUEITEMCORE72 {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 == 3278 uint32_t Alignment0;79 #endif80 } 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 the240 * 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 and244 * 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 the261 * 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 item273 * 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 item284 * 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 Section309 * @ingroup grp_pdm310 * @{311 */312 313 /**314 * A PDM critical section.315 * Initialize using PDMDRVHLP::pfnCritSectInit().316 */317 typedef union PDMCRITSECT318 {319 /** Padding. */320 uint8_t padding[HC_ARCH_BITS == 64 ? 0xb8 : 0x80];321 #ifdef PDMCRITSECTINT_DECLARED322 /** The internal structure (not normally visible). */323 struct PDMCRITSECTINT s;324 #endif325 } 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, but335 * 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 R0354 * 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_thread428 * @{429 */430 431 /**432 * The thread state433 */434 typedef enum PDMTHREADSTATE435 {436 /** The usual invalid 0 entry. */437 PDMTHREADSTATE_INVALID = 0,438 /** The thread is initializing.439 * Prev state: none440 * Next state: suspended, terminating (error) */441 PDMTHREADSTATE_INITIALIZING,442 /** The thread has been asked to suspend.443 * Prev state: running444 * Next state: suspended */445 PDMTHREADSTATE_SUSPENDING,446 /** The thread is supended.447 * Prev state: suspending, initializing448 * Next state: resuming, terminated. */449 PDMTHREADSTATE_SUSPENDED,450 /** The thread is active.451 * Prev state: suspended452 * Next state: running, terminating. */453 PDMTHREADSTATE_RESUMING,454 /** The thread is active.455 * Prev state: resuming456 * Next state: suspending, terminating. */457 PDMTHREADSTATE_RUNNING,458 /** The thread has been asked to terminate.459 * Prev state: initializing, suspended, resuming, running460 * Next state: terminated. */461 PDMTHREADSTATE_TERMINATING,462 /** The thread is terminating / has terminated.463 * Prev state: terminating464 * Next state: none */465 PDMTHREADSTATE_TERMINATED,466 /** The usual 32-bit hack. */467 PDMTHREADSTATE_32BIT_HACK = 0x7fffffff468 } 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 PDMTHREAD568 {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 the579 * function pointer typedefs. So, don't touch these, please.580 */581 union582 {583 /** PDMTHREADTYPE_DEVICE data. */584 struct585 {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 struct596 {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 struct607 {608 /** The thread function. */609 R3PTRTYPE(PFNPDMTHREADINT) pfnThread;610 /** Thread. */611 R3PTRTYPE(PFNPDMTHREADWAKEUPINT) pfnWakeup;612 } Int;613 614 /** PDMTHREADTYPE_EXTERNAL data. */615 struct616 {617 /** The thread function. */618 R3PTRTYPE(PFNPDMTHREADEXT) pfnThread;619 /** Thread. */620 R3PTRTYPE(PFNPDMTHREADWAKEUPEXT) pfnWakeup;621 } Ext;622 } u;623 624 /** Internal data. */625 union626 {627 #ifdef PDMTHREADINT_DECLARED628 PDMTHREADINT s;629 #endif630 uint8_t padding[64];631 } Internal;632 } PDMTHREAD;633 634 /** PDMTHREAD::u32Version value. */635 #define PDMTHREAD_VERSION 0xef010000636 637 638 /** @} */639 640 641 642 /** @defgroup grp_pdm_interfaces Interfaces643 * @ingroup grp_pdm644 * @{645 */646 647 /**648 * Driver interface identficators.649 */650 typedef enum PDMINTERFACE651 {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_MAX742 } PDMINTERFACE;743 744 745 /**746 * PDM Driver Base Interface.747 */748 typedef struct PDMIBASE749 {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 dummy769 * interface is to validate the logical function of a driver/device and770 * full a natural interface pair.771 */772 typedef struct PDMIDUMMY773 {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 PDMIMOUSEPORT785 {786 /**787 * Puts a mouse event.788 * This is called by the source of mouse events. The event will be passed up until the789 * 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 PDMIKEYBOARDPORT826 {827 /**828 * Puts a keyboard event.829 * This is called by the source of keyboard events. The event will be passed up until the830 * 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 PDMKEYBLEDS844 {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 = 0x0004853 } PDMKEYBLEDS;854 855 /** Pointer to keyboard connector interface. */856 typedef struct PDMIKEYBOARDCONNECTOR *PPDMIKEYBOARDCONNECTOR;857 858 859 /**860 * Keyboard connector interface.861 * Pair with PDMIKEYBOARDPORT862 */863 typedef struct PDMIKEYBOARDCONNECTOR864 {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 PDMIDISPLAYPORT884 {885 /**886 * Update the display with any changed regions.887 *888 * Flushes any display changes to the memory pointed to by the889 * 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 the902 * 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 bpp914 * requested by the host, this method can be used to query the actual915 * 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 of927 * one PDMIDISPLAYPORT::pfnRefresh() call to the next one.928 *929 * The interval timer will be restarted by this call. So at VM startup930 * this function must be called to start the refresh cycle. The refresh931 * 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. Because944 * of a wish for no locks in the graphics device, this must be called from the945 * 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) to961 * 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 the971 * 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 need989 * 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 PDMIDISPLAYCONNECTOR1007 {1008 /**1009 * Resize the display.1010 * This is called when the resolution changes. This usually happens on1011 * 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.1032 * @param x The upper left corner x coordinate of the rectangle.1033 * @param y The upper left corner y coordinate of the rectangle.1034 * @param cx The width of the rectangle.1035 * @param cy The height of the rectangle.1036 * @thread The emulation thread.1037 */1038 DECLR3CALLBACKMEMBER(void, pfnUpdateRect,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));1039 1040 /**1041 * Refresh the display.1042 *1043 * The interval between these calls is set by1044 * PDMIDISPLAYPORT::pfnSetRefreshRate(). The driver should call1045 * PDMIDISPLAYPORT::pfnUpdateDisplay() if it wishes to refresh the1046 * display. PDMIDISPLAYPORT::pfnUpdateDisplay calls pfnUpdateRect with1047 * the changed rectangles.1048 *1049 * @param pInterface Pointer to this interface.1050 * @thread The emulation thread.1051 */1052 DECLR3CALLBACKMEMBER(void, pfnRefresh,(PPDMIDISPLAYCONNECTOR pInterface));1053 1054 /**1055 * Reset the display.1056 *1057 * Notification message when the graphics card has been reset.1058 *1059 * @param pInterface Pointer to this interface.1060 * @thread The emulation thread.1061 */1062 DECLR3CALLBACKMEMBER(void, pfnReset,(PPDMIDISPLAYCONNECTOR pInterface));1063 1064 /**1065 * LFB video mode enter/exit.1066 *1067 * Notification message when LinearFrameBuffer video mode is enabled/disabled.1068 *1069 * @param pInterface Pointer to this interface.1070 * @param fEnabled false - LFB mode was disabled,1071 * true - an LFB mode was disabled1072 * @thread The emulation thread.1073 */1074 DECLCALLBACKMEMBER(void, pfnLFBModeChange)(PPDMIDISPLAYCONNECTOR pInterface, bool fEnabled);1075 1076 /**1077 * Process the guest graphics adapter information.1078 *1079 * Direct notification from guest to the display connector.1080 *1081 * @param pInterface Pointer to this interface.1082 * @param pvVRAM Address of the guest VRAM.1083 * @param u32VRAMSize Size of the guest VRAM.1084 * @thread The emulation thread.1085 */1086 DECLCALLBACKMEMBER(void, pfnProcessAdapterData)(PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, uint32_t u32VRAMSize);1087 1088 /**1089 * Process the guest display information.1090 *1091 * Direct notification from guest to the display connector.1092 *1093 * @param pInterface Pointer to this interface.1094 * @param pvVRAM Address of the guest VRAM.1095 * @param uScreenId The index of the guest display to be processed.1096 * @thread The emulation thread.1097 */1098 DECLCALLBACKMEMBER(void, pfnProcessDisplayData)(PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, unsigned uScreenId);1099 1100 1101 /** Read-only attributes.1102 * For preformance reasons some readonly attributes are kept in the interface.1103 * We trust the interface users to respect the readonlyness of these.1104 * @{1105 */1106 /** Pointer to the display data buffer. */1107 uint8_t *pu8Data;1108 /** Size of a scanline in the data buffer. */1109 uint32_t cbScanline;1110 /** The color depth (in bits) the graphics card is supposed to provide. */1111 uint32_t cBits;1112 /** The display width. */1113 uint32_t cx;1114 /** The display height. */1115 uint32_t cy;1116 /** @} */1117 } PDMIDISPLAYCONNECTOR;1118 1119 1120 1121 /**1122 * Block drive type.1123 */1124 typedef enum PDMBLOCKTYPE1125 {1126 /** Error (for the query function). */1127 PDMBLOCKTYPE_ERROR = 1,1128 /** 360KB 5 1/4" floppy drive. */1129 PDMBLOCKTYPE_FLOPPY_360,1130 /** 720KB 3 1/2" floppy drive. */1131 PDMBLOCKTYPE_FLOPPY_720,1132 /** 1.2MB 5 1/4" floppy drive. */1133 PDMBLOCKTYPE_FLOPPY_1_20,1134 /** 1.44MB 3 1/2" floppy drive. */1135 PDMBLOCKTYPE_FLOPPY_1_44,1136 /** 2.88MB 3 1/2" floppy drive. */1137 PDMBLOCKTYPE_FLOPPY_2_88,1138 /** CDROM drive. */1139 PDMBLOCKTYPE_CDROM,1140 /** DVD drive. */1141 PDMBLOCKTYPE_DVD,1142 /** Hard disk drive. */1143 PDMBLOCKTYPE_HARD_DISK1144 } PDMBLOCKTYPE;1145 1146 1147 /**1148 * Block raw command data transfer direction.1149 */1150 typedef enum PDMBLOCKTXDIR1151 {1152 PDMBLOCKTXDIR_NONE = 0,1153 PDMBLOCKTXDIR_FROM_DEVICE,1154 PDMBLOCKTXDIR_TO_DEVICE1155 } PDMBLOCKTXDIR;1156 1157 /**1158 * Block notify interface.1159 * Pair with PDMIBLOCK.1160 */1161 typedef PDMIDUMMY PDMIBLOCKPORT;1162 /** Pointer to a block notify interface (dummy). */1163 typedef PDMIBLOCKPORT *PPDMIBLOCKPORT;1164 1165 /** Pointer to a block interface. */1166 typedef struct PDMIBLOCK *PPDMIBLOCK;1167 /**1168 * Block interface.1169 * Pair with PDMIBLOCKPORT.1170 */1171 typedef struct PDMIBLOCK1172 {1173 /**1174 * Read bits.1175 *1176 * @returns VBox status code.1177 * @param pInterface Pointer to the interface structure containing the called function pointer.1178 * @param off Offset to start reading from.1179 * @param pvBuf Where to store the read bits.1180 * @param cbRead Number of bytes to read.1181 * @thread Any thread.1182 */1183 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIBLOCK pInterface, uint64_t off, void *pvBuf, size_t cbRead));1184 1185 /**1186 * Write bits.1187 *1188 * @returns VBox status code.1189 * @param pInterface Pointer to the interface structure containing the called function pointer.1190 * @param off Offset to start writing at.1191 * @param pvBuf Where to store the write bits.1192 * @param cbWrite Number of bytes to write.1193 * @thread Any thread.1194 */1195 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIBLOCK pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));1196 1197 /**1198 * Make sure that the bits written are actually on the storage medium.1199 *1200 * @returns VBox status code.1201 * @param pInterface Pointer to the interface structure containing the called function pointer.1202 * @thread Any thread.1203 */1204 DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIBLOCK pInterface));1205 1206 /**1207 * Send a raw command to the underlying device (CDROM).1208 * This method is optional (i.e. the function pointer may be NULL).1209 *1210 * @returns VBox status code.1211 * @param pInterface Pointer to the interface structure containing the called function pointer.1212 * @param pbCmd Offset to start reading from.1213 * @param enmTxDir Direction of transfer.1214 * @param pvBuf Pointer tp the transfer buffer.1215 * @param cbBuf Size of the transfer buffer.1216 * @param pbSenseKey Status of the command (when return value is VERR_DEV_IO_ERROR).1217 * @param cTimeoutMillies Command timeout in milliseconds.1218 * @thread Any thread.1219 */1220 DECLR3CALLBACKMEMBER(int, pfnSendCmd,(PPDMIBLOCK pInterface, const uint8_t *pbCmd, PDMBLOCKTXDIR enmTxDir, void *pvBuf, size_t *pcbBuf, uint8_t *pbSenseKey, uint32_t cTimeoutMillies));1221 1222 /**1223 * Check if the media is readonly or not.1224 *1225 * @returns true if readonly.1226 * @returns false if read/write.1227 * @param pInterface Pointer to the interface structure containing the called function pointer.1228 * @thread Any thread.1229 */1230 DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIBLOCK pInterface));1231 1232 /**1233 * Gets the media size in bytes.1234 *1235 * @returns Media size in bytes.1236 * @param pInterface Pointer to the interface structure containing the called function pointer.1237 * @thread Any thread.1238 */1239 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIBLOCK pInterface));1240 1241 /**1242 * Gets the block drive type.1243 *1244 * @returns block drive type.1245 * @param pInterface Pointer to the interface structure containing the called function pointer.1246 * @thread Any thread.1247 */1248 DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCK pInterface));1249 1250 /**1251 * Gets the UUID of the block drive.1252 * Don't return the media UUID if it's removable.1253 *1254 * @returns VBox status code.1255 * @param pInterface Pointer to the interface structure containing the called function pointer.1256 * @param pUuid Where to store the UUID on success.1257 * @thread Any thread.1258 */1259 DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIBLOCK pInterface, PRTUUID pUuid));1260 } PDMIBLOCK;1261 1262 1263 /** Pointer to a mount interface. */1264 typedef struct PDMIMOUNTNOTIFY *PPDMIMOUNTNOTIFY;1265 /**1266 * Block interface.1267 * Pair with PDMIMOUNT.1268 */1269 typedef struct PDMIMOUNTNOTIFY1270 {1271 /**1272 * Called when a media is mounted.1273 *1274 * @param pInterface Pointer to the interface structure containing the called function pointer.1275 * @thread The emulation thread.1276 */1277 DECLR3CALLBACKMEMBER(void, pfnMountNotify,(PPDMIMOUNTNOTIFY pInterface));1278 1279 /**1280 * Called when a media is unmounted1281 * @param pInterface Pointer to the interface structure containing the called function pointer.1282 * @thread The emulation thread.1283 */1284 DECLR3CALLBACKMEMBER(void, pfnUnmountNotify,(PPDMIMOUNTNOTIFY pInterface));1285 } PDMIMOUNTNOTIFY;1286 1287 1288 /* Pointer to mount interface. */1289 typedef struct PDMIMOUNT *PPDMIMOUNT;1290 /**1291 * Mount interface.1292 * Pair with PDMIMOUNTNOTIFY.1293 */1294 typedef struct PDMIMOUNT1295 {1296 /**1297 * Mount a media.1298 *1299 * This will not unmount any currently mounted media!1300 *1301 * @returns VBox status code.1302 * @param pInterface Pointer to the interface structure containing the called function pointer.1303 * @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have1304 * constructed a configuration which can be attached to the bottom driver.1305 * @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.1306 * @thread The emulation thread.1307 */1308 DECLR3CALLBACKMEMBER(int, pfnMount,(PPDMIMOUNT pInterface, const char *pszFilename, const char *pszCoreDriver));1309 1310 /**1311 * Unmount the media.1312 *1313 * The driver will validate and pass it on. On the rebounce it will decide whether or not to detach it self.1314 *1315 * @returns VBox status code.1316 * @param pInterface Pointer to the interface structure containing the called function pointer.1317 * @thread The emulation thread.1318 * @param fForce Force the unmount, even for locked media.1319 * @thread The emulation thread.1320 */1321 DECLR3CALLBACKMEMBER(int, pfnUnmount,(PPDMIMOUNT pInterface, bool fForce));1322 1323 /**1324 * Checks if a media is mounted.1325 *1326 * @returns true if mounted.1327 * @returns false if not mounted.1328 * @param pInterface Pointer to the interface structure containing the called function pointer.1329 * @thread Any thread.1330 */1331 DECLR3CALLBACKMEMBER(bool, pfnIsMounted,(PPDMIMOUNT pInterface));1332 1333 /**1334 * Locks the media, preventing any unmounting of it.1335 *1336 * @returns VBox status code.1337 * @param pInterface Pointer to the interface structure containing the called function pointer.1338 * @thread The emulation thread.1339 */1340 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMIMOUNT pInterface));1341 1342 /**1343 * Unlocks the media, canceling previous calls to pfnLock().1344 *1345 * @returns VBox status code.1346 * @param pInterface Pointer to the interface structure containing the called function pointer.1347 * @thread The emulation thread.1348 */1349 DECLR3CALLBACKMEMBER(int, pfnUnlock,(PPDMIMOUNT pInterface));1350 1351 /**1352 * Checks if a media is locked.1353 *1354 * @returns true if locked.1355 * @returns false if not locked.1356 * @param pInterface Pointer to the interface structure containing the called function pointer.1357 * @thread Any thread.1358 */1359 DECLR3CALLBACKMEMBER(bool, pfnIsLocked,(PPDMIMOUNT pInterface));1360 } PDMIBLOCKMOUNT;1361 1362 /**1363 * BIOS translation mode.1364 */1365 typedef enum PDMBIOSTRANSLATION1366 {1367 /** No translation. */1368 PDMBIOSTRANSLATION_NONE = 1,1369 /** LBA translation. */1370 PDMBIOSTRANSLATION_LBA,1371 /** Automatic select mode. */1372 PDMBIOSTRANSLATION_AUTO1373 } PDMBIOSTRANSLATION;1374 1375 /** Pointer to BIOS translation mode. */1376 typedef PDMBIOSTRANSLATION *PPDMBIOSTRANSLATION;1377 1378 /** Pointer to a media interface. */1379 typedef struct PDMIMEDIA *PPDMIMEDIA;1380 /**1381 * Media interface.1382 * Makes up the fundation for PDMIBLOCK and PDMIBLOCKBIOS.1383 */1384 typedef struct PDMIMEDIA1385 {1386 /**1387 * Read bits.1388 *1389 * @returns VBox status code.1390 * @param pInterface Pointer to the interface structure containing the called function pointer.1391 * @param off Offset to start reading from.1392 * @param pvBuf Where to store the read bits.1393 * @param cbRead Number of bytes to read.1394 * @thread Any thread.1395 */1396 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIMEDIA pInterface, uint64_t off, void *pvBuf, size_t cbRead));1397 1398 /**1399 * Write bits.1400 *1401 * @returns VBox status code.1402 * @param pInterface Pointer to the interface structure containing the called function pointer.1403 * @param off Offset to start writing at.1404 * @param pvBuf Where to store the write bits.1405 * @param cbWrite Number of bytes to write.1406 * @thread Any thread.1407 */1408 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIMEDIA pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));1409 1410 /**1411 * Make sure that the bits written are actually on the storage medium.1412 *1413 * @returns VBox status code.1414 * @param pInterface Pointer to the interface structure containing the called function pointer.1415 * @thread Any thread.1416 */1417 DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIMEDIA pInterface));1418 1419 /**1420 * Get the media size in bytes.1421 *1422 * @returns Media size in bytes.1423 * @param pInterface Pointer to the interface structure containing the called function pointer.1424 * @thread Any thread.1425 */1426 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIMEDIA pInterface));1427 1428 /**1429 * Check if the media is readonly or not.1430 *1431 * @returns true if readonly.1432 * @returns false if read/write.1433 * @param pInterface Pointer to the interface structure containing the called function pointer.1434 * @thread Any thread.1435 */1436 DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIMEDIA pInterface));1437 1438 /**1439 * Get stored media geometry - BIOS property.1440 * This is an optional feature of a media.1441 *1442 * @returns VBox status code.1443 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.1444 * @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetGeometry() yet.1445 * @param pInterface Pointer to the interface structure containing the called function pointer.1446 * @param pcCylinders Number of cylinders.1447 * @param pcHeads Number of heads.1448 * @param pcSectors Number of sectors. This number is 1-based.1449 * @remark This have no influence on the read/write operations.1450 * @thread Any thread.1451 */1452 DECLR3CALLBACKMEMBER(int, pfnBiosGetGeometry,(PPDMIMEDIA pInterface, uint32_t *pcCylinders, uint32_t *pcHeads, uint32_t *pcSectors));1453 1454 /**1455 * Store the media geometry - BIOS property.1456 * This is an optional feature of a media.1457 *1458 * @returns VBox status code.1459 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.1460 * @param pInterface Pointer to the interface structure containing the called function pointer.1461 * @param cCylinders Number of cylinders.1462 * @param cHeads Number of heads.1463 * @param cSectors Number of sectors. This number is 1-based.1464 * @remark This have no influence on the read/write operations.1465 * @thread The emulation thread.1466 */1467 DECLR3CALLBACKMEMBER(int, pfnBiosSetGeometry,(PPDMIMEDIA pInterface, uint32_t cCylinders, uint32_t cHeads, uint32_t cSectors));1468 1469 /**1470 * Get stored geometry translation mode - BIOS property.1471 * This is an optional feature of a media.1472 *1473 * @returns VBox status code.1474 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry translation mode.1475 * @returns VERR_PDM_TRANSLATION_NOT_SET if the translation hasn't been set using pfnBiosSetTranslation() yet.1476 * @param pInterface Pointer to the interface structure containing the called function pointer.1477 * @param penmTranslation Where to store the translation type.1478 * @remark This have no influence on the read/write operations.1479 * @thread Any thread.1480 */1481 DECLR3CALLBACKMEMBER(int, pfnBiosGetTranslation,(PPDMIMEDIA pInterface, PPDMBIOSTRANSLATION penmTranslation));1482 1483 /**1484 * Store media geometry - BIOS property.1485 * This is an optional feature of a media.1486 *1487 * @returns VBox status code.1488 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.1489 * @param pInterface Pointer to the interface structure containing the called function pointer.1490 * @param enmTranslation The translation type.1491 * @remark This have no influence on the read/write operations.1492 * @thread The emulation thread.1493 */1494 DECLR3CALLBACKMEMBER(int, pfnBiosSetTranslation,(PPDMIMEDIA pInterface, PDMBIOSTRANSLATION enmTranslation));1495 1496 /**1497 * Gets the UUID of the media drive.1498 *1499 * @returns VBox status code.1500 * @param pInterface Pointer to the interface structure containing the called function pointer.1501 * @param pUuid Where to store the UUID on success.1502 * @thread Any thread.1503 */1504 DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIMEDIA pInterface, PRTUUID pUuid));1505 1506 } PDMIMEDIA;1507 1508 1509 /** Pointer to a block BIOS interface. */1510 typedef struct PDMIBLOCKBIOS *PPDMIBLOCKBIOS;1511 /**1512 * Media BIOS interface.1513 * The interface the getting and setting properties which the BIOS/CMOS care about.1514 */1515 typedef struct PDMIBLOCKBIOS1516 {1517 /**1518 * Get stored media geometry - BIOS property.1519 * This is an optional feature of a media.1520 *1521 * @returns VBox status code.1522 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.1523 * @param pInterface Pointer to the interface structure containing the called function pointer.1524 * @param pcCylinders Number of cylinders.1525 * @param pcHeads Number of heads.1526 * @param pcSectors Number of sectors. This number is 1-based.1527 * @remark This have no influence on the read/write operations.1528 * @thread Any thread.1529 */1530 DECLR3CALLBACKMEMBER(int, pfnGetGeometry,(PPDMIBLOCKBIOS pInterface, uint32_t *pcCylinders, uint32_t *pcHeads, uint32_t *pcSectors));1531 1532 /**1533 * Store the media geometry - BIOS property.1534 * This is an optional feature of a media.1535 *1536 * @returns VBox status code.1537 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.1538 * @param pInterface Pointer to the interface structure containing the called function pointer.1539 * @param cCylinders Number of cylinders.1540 * @param cHeads Number of heads.1541 * @param cSectors Number of sectors. This number is 1-based.1542 * @remark This have no influence on the read/write operations.1543 * @thread The emulation thread.1544 */1545 DECLR3CALLBACKMEMBER(int, pfnSetGeometry,(PPDMIBLOCKBIOS pInterface, uint32_t cCylinders, uint32_t cHeads, uint32_t cSectors));1546 1547 /**1548 * Get stored geometry translation mode - BIOS property.1549 * This is an optional feature of a media.1550 *1551 * @returns VBox status code.1552 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry translation mode.1553 * @param pInterface Pointer to the interface structure containing the called function pointer.1554 * @param penmTranslation Where to store the translation type.1555 * @remark This have no influence on the read/write operations.1556 * @thread Any thread.1557 */1558 DECLR3CALLBACKMEMBER(int, pfnGetTranslation,(PPDMIBLOCKBIOS pInterface, PPDMBIOSTRANSLATION penmTranslation));1559 1560 /**1561 * Store media geometry - BIOS property.1562 * This is an optional feature of a media.1563 *1564 * @returns VBox status code.1565 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.1566 * @param pInterface Pointer to the interface structure containing the called function pointer.1567 * @param enmTranslation The translation type.1568 * @remark This have no influence on the read/write operations.1569 * @thread The emulation thread.1570 */1571 DECLR3CALLBACKMEMBER(int, pfnSetTranslation,(PPDMIBLOCKBIOS pInterface, PDMBIOSTRANSLATION enmTranslation));1572 1573 /**1574 * Checks if the device should be visible to the BIOS or not.1575 *1576 * @returns true if the device is visible to the BIOS.1577 * @returns false if the device is not visible to the BIOS.1578 * @param pInterface Pointer to the interface structure containing the called function pointer.1579 * @thread Any thread.1580 */1581 DECLR3CALLBACKMEMBER(bool, pfnIsVisible,(PPDMIBLOCKBIOS pInterface));1582 1583 /**1584 * Gets the block drive type.1585 *1586 * @returns block drive type.1587 * @param pInterface Pointer to the interface structure containing the called function pointer.1588 * @thread Any thread.1589 */1590 DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCKBIOS pInterface));1591 1592 } PDMIBLOCKBIOS;1593 1594 1595 /** Pointer to a static block core driver interface. */1596 typedef struct PDMIMEDIASTATIC *PPDMIMEDIASTATIC;1597 /**1598 * Static block core driver interface.1599 */1600 typedef struct PDMIMEDIASTATIC1601 {1602 /**1603 * Check if the specified file is a format which the core driver can handle.1604 *1605 * @returns true / false accordingly.1606 * @param pInterface Pointer to the interface structure containing the called function pointer.1607 * @param pszFilename Name of the file to probe.1608 */1609 DECLR3CALLBACKMEMBER(bool, pfnCanHandle,(PPDMIMEDIASTATIC pInterface, const char *pszFilename));1610 } PDMIMEDIASTATIC;1611 1612 1613 /** Pointer to an iSCSI Request PDU buffer. */1614 typedef struct ISCSIREQ *PISCSIREQ;1615 /**1616 * iSCSI Request PDU buffer (gather).1617 */1618 typedef struct ISCSIREQ1619 {1620 /** Length of PDU segment in bytes. */1621 size_t cbSeg;1622 /** Pointer to PDU segment. */1623 const void *pcvSeg;1624 } ISCSIREQ;1625 1626 /** Pointer to an iSCSI Response PDU buffer. */1627 typedef struct ISCSIRES *PISCSIRES;1628 /**1629 * iSCSI Response PDU buffer (scatter).1630 */1631 typedef struct ISCSIRES1632 {1633 /** Length of PDU segment. */1634 size_t cbSeg;1635 /** Pointer to PDU segment. */1636 void *pvSeg;1637 } ISCSIRES;1638 1639 /** Pointer to an iSCSI transport driver interface. */1640 typedef struct PDMIISCSITRANSPORT *PPDMIISCSITRANSPORT;1641 /**1642 * iSCSI transport driver interface.1643 */1644 typedef struct PDMIISCSITRANSPORT1645 {1646 /**1647 * Read bytes from an iSCSI transport stream. If the connection fails, it is automatically1648 * reopened on the next call after the error is signalled. Error recovery in this case is1649 * the duty of the caller.1650 *1651 * @returns VBox status code.1652 * @param pTransport Pointer to the interface structure containing the called function pointer.1653 * @param pvBuf Where to store the read bits.1654 * @param cbBuf Number of bytes to read.1655 * @param pcbRead Actual number of bytes read.1656 * @thread Any thread.1657 * @todo Correct the docs.1658 */1659 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIISCSITRANSPORT pTransport, PISCSIRES prgResponse, unsigned int cnResponse));1660 1661 /**1662 * Write bytes to an iSCSI transport stream. Padding is performed when necessary. If the connection1663 * fails, it is automatically reopened on the next call after the error is signalled. Error recovery1664 * in this case is the duty of the caller.1665 *1666 * @returns VBox status code.1667 * @param pTransport Pointer to the interface structure containing the called function pointer.1668 * @param pvBuf Where the write bits are stored.1669 * @param cbWrite Number of bytes to write.1670 * @thread Any thread.1671 * @todo Correct the docs.1672 */1673 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIISCSITRANSPORT pTransport, PISCSIREQ prgRequest, unsigned int cnRequest));1674 1675 /**1676 * Open the iSCSI transport stream.1677 *1678 * @returns VBox status code.1679 * @param pTransport Pointer to the interface structure containing the called function pointer.1680 * @param pszTargetAddress Pointer to string of the format address:port.1681 * @thread Any thread.1682 */1683 DECLR3CALLBACKMEMBER(int, pfnOpen,(PPDMIISCSITRANSPORT pTransport, const char *pszTargetAddress));1684 1685 /**1686 * Close the iSCSI transport stream.1687 *1688 * @returns VBox status code.1689 * @param pTransport Pointer to the interface structure containing the called function pointer.1690 * @thread Any thread.1691 */1692 DECLR3CALLBACKMEMBER(int, pfnClose,(PPDMIISCSITRANSPORT pTransport));1693 } PDMIISCSITRANSPORT;1694 1695 1696 /** Pointer to a char port interface. */1697 typedef struct PDMICHARPORT *PPDMICHARPORT;1698 /**1699 * Char port interface.1700 * Pair with PDMICHAR.1701 */1702 typedef struct PDMICHARPORT1703 {1704 /**1705 * Deliver data read to the device/driver.1706 *1707 * @returns VBox status code.1708 * @param pInterface Pointer to the interface structure containing the called function pointer.1709 * @param pvBuf Where the read bits are stored.1710 * @param pcbRead Number of bytes available for reading/having been read.1711 * @thread Any thread.1712 */1713 DECLR3CALLBACKMEMBER(int, pfnNotifyRead,(PPDMICHARPORT pInterface, const void *pvBuf, size_t *pcbRead));1714 } PDMICHARPORT;1715 1716 /** Pointer to a char interface. */1717 typedef struct PDMICHAR *PPDMICHAR;1718 /**1719 * Char interface.1720 * Pair with PDMICHARPORT.1721 */1722 typedef struct PDMICHAR1723 {1724 /**1725 * Write bits.1726 *1727 * @returns VBox status code.1728 * @param pInterface Pointer to the interface structure containing the called function pointer.1729 * @param pvBuf Where to store the write bits.1730 * @param cbWrite Number of bytes to write.1731 * @thread Any thread.1732 */1733 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMICHAR pInterface, const void *pvBuf, size_t cbWrite));1734 } PDMICHAR;1735 1736 1737 /** Pointer to a stream interface. */1738 typedef struct PDMISTREAM *PPDMISTREAM;1739 /**1740 * Stream interface.1741 * Makes up the fundation for PDMICHAR.1742 */1743 typedef struct PDMISTREAM1744 {1745 /**1746 * Read bits.1747 *1748 * @returns VBox status code.1749 * @param pInterface Pointer to the interface structure containing the called function pointer.1750 * @param pvBuf Where to store the read bits.1751 * @param cbRead Number of bytes to read/bytes actually read.1752 * @thread Any thread.1753 */1754 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMISTREAM pInterface, void *pvBuf, size_t *cbRead));1755 1756 /**1757 * Write bits.1758 *1759 * @returns VBox status code.1760 * @param pInterface Pointer to the interface structure containing the called function pointer.1761 * @param pvBuf Where to store the write bits.1762 * @param cbWrite Number of bytes to write/bytes actually written.1763 * @thread Any thread.1764 */1765 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMISTREAM pInterface, const void *pvBuf, size_t *cbWrite));1766 } PDMISTREAM;1767 1768 1769 /** Pointer to a host device port interface. */1770 typedef struct PDMIHOSTDEVICEPORT *PPDMIHOSTDEVICEPORT;1771 1772 /**1773 * Char port interface.1774 * Pair with PDMIHOSTDEVICECONNECTOR.1775 */1776 typedef struct PDMIHOSTDEVICEPORT1777 {1778 /**1779 * Deliver data read to the device/driver.1780 *1781 * @returns VBox status code.1782 * @param pInterface Pointer to the interface structure containing the called function pointer.1783 * @param pvBuf Where the read bits are stored.1784 * @param pcbRead Number of bytes available for reading/having been read.1785 * @thread Any thread.1786 */1787 DECLR3CALLBACKMEMBER(int, pfnNotifyRead,(PPDMIHOSTDEVICEPORT pInterface, const void *pvBuf, size_t *pcbRead));1788 } PDMIHOSTDEVICEPORT;1789 1790 /** Pointer to a Host Device connector interface. */1791 typedef struct PDMIHOSTDEVICECONNECTOR *PPDMIHOSTDEVICECONNECTOR;1792 1793 /**1794 * Host device connector interface1795 * Pair with PDMIHOSTDEVICEPORT.1796 */1797 typedef struct PDMIHOSTDEVICECONNECTOR1798 {1799 /**1800 * Write bits.1801 *1802 * @returns VBox status code.1803 * @param pInterface Pointer to the interface structure containing the called function pointer.1804 * @param pvBuf Where to store the write bits.1805 * @param pcbWrite Number of bytes to write/bytes actually written.1806 * @thread Any thread.1807 */1808 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIHOSTDEVICECONNECTOR pInterface, const void *pvBuf, size_t *pcbWrite));1809 1810 /**1811 * Read bits.1812 *1813 * @returns VBox status code.1814 * @param pInterface Pointer to the interface structure containing the called function pointer.1815 * @param pvBuf Where to store the read bits.1816 * @param pcbRead Number of bytes to read/bytes actually read.1817 * @thread Any thread.1818 */1819 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIHOSTDEVICECONNECTOR pInterface, void *pvBuf, size_t *pcbRead));1820 1821 /**1822 * Perform IO control on the host device.1823 *1824 * @returns VBox status code.1825 * @param pInterface Pointer to the interface structure containing the called function pointer.1826 * @param uCommand The number of the command to set or get data1827 * @param pvData Where to store the command data.1828 * @thread Any thread.1829 */1830 DECLR3CALLBACKMEMBER(int, pfnIOCtl,(PPDMIHOSTDEVICECONNECTOR pInterface, RTUINT uCommand, void *pvData));1831 } PDMIHOSTDEVICECONNECTOR;1832 1833 1834 /** ACPI power source identifier */1835 typedef enum PDMACPIPOWERSOURCE1836 {1837 PDM_ACPI_POWER_SOURCE_UNKNOWN = 0,1838 PDM_ACPI_POWER_SOURCE_OUTLET,1839 PDM_ACPI_POWER_SOURCE_BATTERY1840 } PDMACPIPOWERSOURCE;1841 /** Pointer to ACPI battery state. */1842 typedef PDMACPIPOWERSOURCE *PPDMACPIPOWERSOURCE;1843 1844 /** ACPI battey capacity */1845 typedef enum PDMACPIBATCAPACITY1846 {1847 PDM_ACPI_BAT_CAPACITY_MIN = 0,1848 PDM_ACPI_BAT_CAPACITY_MAX = 100,1849 PDM_ACPI_BAT_CAPACITY_UNKNOWN = 2551850 } PDMACPIBATCAPACITY;1851 /** Pointer to ACPI battery capacity. */1852 typedef PDMACPIBATCAPACITY *PPDMACPIBATCAPACITY;1853 1854 /** ACPI battery state. See ACPI 3.0 spec '_BST (Battery Status)' */1855 typedef enum PDMACPIBATSTATE1856 {1857 PDM_ACPI_BAT_STATE_CHARGED = 0x00,1858 PDM_ACPI_BAT_STATE_CHARGING = 0x01,1859 PDM_ACPI_BAT_STATE_DISCHARGING = 0x02,1860 PDM_ACPI_BAT_STATE_CRITICAL = 0x041861 } PDMACPIBATSTATE;1862 /** Pointer to ACPI battery state. */1863 typedef PDMACPIBATSTATE *PPDMACPIBATSTATE;1864 1865 /** Pointer to an ACPI port interface. */1866 typedef struct PDMIACPIPORT *PPDMIACPIPORT;1867 /**1868 * ACPI port interface.1869 */1870 typedef struct PDMIACPIPORT1871 {1872 /**1873 * Send an ACPI power off event.1874 *1875 * @returns VBox status code1876 * @param pInterface Pointer to the interface structure containing the called function pointer.1877 */1878 DECLR3CALLBACKMEMBER(int, pfnPowerButtonPress,(PPDMIACPIPORT pInterface));1879 } PDMIACPIPORT;1880 1881 /** Pointer to an ACPI connector interface. */1882 typedef struct PDMIACPICONNECTOR *PPDMIACPICONNECTOR;1883 /**1884 * ACPI connector interface.1885 */1886 typedef struct PDMIACPICONNECTOR1887 {1888 /**1889 * Get the current power source of the host system.1890 *1891 * @returns VBox status code1892 * @param pInterface Pointer to the interface structure containing the called function pointer.1893 * @param penmPowerSource Pointer to the power source result variable.1894 */1895 DECLR3CALLBACKMEMBER(int, pfnQueryPowerSource,(PPDMIACPICONNECTOR, PPDMACPIPOWERSOURCE penmPowerSource));1896 1897 /**1898 * Query the current battery status of the host system.1899 *1900 * @returns VBox status code?1901 * @param pInterface Pointer to the interface structure containing the called function pointer.1902 * @param pfPresent Is set to true if battery is present, false otherwise.1903 * @param penmRemainingCapacity Pointer to the battery remaining capacity (0 - 100 or 255 for unknown).1904 * @param penmBatteryState Pointer to the battery status.1905 * @param pu32PresentRate Pointer to the present rate (0..1000 of the total capacity).1906 */1907 DECLR3CALLBACKMEMBER(int, pfnQueryBatteryStatus,(PPDMIACPICONNECTOR, bool *pfPresent, PPDMACPIBATCAPACITY penmRemainingCapacity,1908 PPDMACPIBATSTATE penmBatteryState, uint32_t *pu32PresentRate));1909 } PDMIACPICONNECTOR;1910 1911 1912 /** Pointer to a VMMDevice port interface. */1913 typedef struct PDMIVMMDEVPORT *PPDMIVMMDEVPORT;1914 /**1915 * VMMDevice port interface.1916 */1917 typedef struct PDMIVMMDEVPORT1918 {1919 /**1920 * Return the current absolute mouse position in pixels1921 *1922 * @returns VBox status code1923 * @param pAbsX Pointer of result value, can be NULL1924 * @param pAbsY Pointer of result value, can be NULL1925 */1926 DECLR3CALLBACKMEMBER(int, pfnQueryAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, uint32_t *pAbsX, uint32_t *pAbsY));1927 1928 /**1929 * Set the new absolute mouse position in pixels1930 *1931 * @returns VBox status code1932 * @param absX New absolute X position1933 * @param absY New absolute Y position1934 */1935 DECLR3CALLBACKMEMBER(int, pfnSetAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, uint32_t absX, uint32_t absY));1936 1937 /**1938 * Return the current mouse capability flags1939 *1940 * @returns VBox status code1941 * @param pCapabilities Pointer of result value1942 */1943 DECLR3CALLBACKMEMBER(int, pfnQueryMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t *pCapabilities));1944 1945 /**1946 * Set the current mouse capability flag (host side)1947 *1948 * @returns VBox status code1949 * @param capabilities Capability mask1950 */1951 DECLR3CALLBACKMEMBER(int, pfnSetMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t capabilities));1952 1953 /**1954 * Issue a display resolution change request.1955 *1956 * Note that there can only one request in the queue and that in case the guest does1957 * not process it, issuing another request will overwrite the previous.1958 *1959 * @returns VBox status code1960 * @param cx Horizontal pixel resolution (0 = do not change).1961 * @param cy Vertical pixel resolution (0 = do not change).1962 * @param cBits Bits per pixel (0 = do not change).1963 * @param display The display index.1964 */1965 DECLR3CALLBACKMEMBER(int, pfnRequestDisplayChange,(PPDMIVMMDEVPORT pInterface, uint32_t cx, uint32_t cy, uint32_t cBits, uint32_t display));1966 1967 /**1968 * Pass credentials to guest.1969 *1970 * Note that there can only be one set of credentials and the guest may or may not1971 * query them and may do whatever it wants with them.1972 *1973 * @returns VBox status code1974 * @param pszUsername User name, may be empty (UTF-8)1975 * @param pszPassword Password, may be empty (UTF-8)1976 * @param pszDomain Domain name, may be empty (UTF-8)1977 * @param fFlags Bitflags1978 */1979 DECLR3CALLBACKMEMBER(int, pfnSetCredentials,(PPDMIVMMDEVPORT pInterface, const char *pszUsername,1980 const char *pszPassword, const char *pszDomain,1981 uint32_t fFlags));1982 1983 /**1984 * Notify the driver about a VBVA status change.1985 *1986 * @returns Nothing. Because it is informational callback.1987 * @param fEnabled Current VBVA status.1988 */1989 DECLCALLBACKMEMBER(void, pfnVBVAChange)(PPDMIVMMDEVPORT pInterface, bool fEnabled);1990 1991 /**1992 * Issue a seamless mode change request.1993 *1994 * Note that there can only one request in the queue and that in case the guest does1995 * not process it, issuing another request will overwrite the previous.1996 *1997 * @returns VBox status code1998 * @param fEnabled Seamless mode enabled or not1999 */2000 DECLR3CALLBACKMEMBER(int, pfnRequestSeamlessChange,(PPDMIVMMDEVPORT pInterface, bool fEnabled));2001 2002 } PDMIVMMDEVPORT;2003 2004 /** Forward declaration of the video accelerator command memory. */2005 struct _VBVAMEMORY;2006 /** Forward declaration of the guest information structure. */2007 struct VBoxGuestInfo;2008 /** Pointer to video accelerator command memory. */2009 typedef struct _VBVAMEMORY *PVBVAMEMORY;2010 2011 /** Pointer to a VMMDev connector interface. */2012 typedef struct PDMIVMMDEVCONNECTOR *PPDMIVMMDEVCONNECTOR;2013 /**2014 * VMMDev connector interface.2015 * Pair with PDMIVMMDEVPORT.2016 */2017 typedef struct PDMIVMMDEVCONNECTOR2018 {2019 /**2020 * Report guest OS version.2021 * Called whenever the Additions issue a guest version report request.2022 *2023 * @param pInterface Pointer to this interface.2024 * @param pGuestInfo Pointer to guest information structure2025 * @thread The emulation thread.2026 */2027 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestVersion,(PPDMIVMMDEVCONNECTOR pInterface, struct VBoxGuestInfo *pGuestInfo));2028 2029 /**2030 * Update the guest additions capabilities.2031 * This is called when the guest additions capabilities change. The new capabilities2032 * are given and the connector should update its internal state.2033 *2034 * @param pInterface Pointer to this interface.2035 * @param newCapabilities New capabilities.2036 * @thread The emulation thread.2037 */2038 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));2039 2040 /**2041 * Update the mouse capabilities.2042 * This is called when the mouse capabilities change. The new capabilities2043 * are given and the connector should update its internal state.2044 *2045 * @param pInterface Pointer to this interface.2046 * @param newCapabilities New capabilities.2047 * @thread The emulation thread.2048 */2049 DECLR3CALLBACKMEMBER(void, pfnUpdateMouseCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));2050 2051 /**2052 * Update the pointer shape.2053 * This is called when the mouse pointer shape changes. The new shape2054 * is passed as a caller allocated buffer that will be freed after returning2055 *2056 * @param pInterface Pointer to this interface.2057 * @param fVisible Visibility indicator (if false, the other parameters are undefined).2058 * @param fAlpha Flag whether alpha channel is being passed.2059 * @param xHot Pointer hot spot x coordinate.2060 * @param yHot Pointer hot spot y coordinate.2061 * @param x Pointer new x coordinate on screen.2062 * @param y Pointer new y coordinate on screen.2063 * @param cx Pointer width in pixels.2064 * @param cy Pointer height in pixels.2065 * @param cbScanline Size of one scanline in bytes.2066 * @param pvShape New shape buffer.2067 * @thread The emulation thread.2068 */2069 DECLR3CALLBACKMEMBER(void, pfnUpdatePointerShape,(PPDMIVMMDEVCONNECTOR pInterface, bool fVisible, bool fAlpha,2070 uint32_t xHot, uint32_t yHot,2071 uint32_t cx, uint32_t cy,2072 void *pvShape));2073 2074 /**2075 * Enable or disable video acceleration on behalf of guest.2076 *2077 * @param pInterface Pointer to this interface.2078 * @param fEnable Whether to enable acceleration.2079 * @param pVbvaMemory Video accelerator memory.2080 2081 * @return VBox rc. VINF_SUCCESS if VBVA was enabled.2082 * @thread The emulation thread.2083 */2084 DECLR3CALLBACKMEMBER(int, pfnVideoAccelEnable,(PPDMIVMMDEVCONNECTOR pInterface, bool fEnable, PVBVAMEMORY pVbvaMemory));2085 2086 /**2087 * Force video queue processing.2088 *2089 * @param pInterface Pointer to this interface.2090 * @thread The emulation thread.2091 */2092 DECLR3CALLBACKMEMBER(void, pfnVideoAccelFlush,(PPDMIVMMDEVCONNECTOR pInterface));2093 2094 /**2095 * Return whether the given video mode is supported/wanted by the host.2096 *2097 * @returns VBox status code2098 * @param pInterface Pointer to this interface.2099 * @param cy Video mode horizontal resolution in pixels.2100 * @param cx Video mode vertical resolution in pixels.2101 * @param cBits Video mode bits per pixel.2102 * @param pfSupported Where to put the indicator for whether this mode is supported. (output)2103 * @thread The emulation thread.2104 */2105 DECLR3CALLBACKMEMBER(int, pfnVideoModeSupported,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cx, uint32_t cy, uint32_t cBits, bool *pfSupported));2106 2107 /**2108 * Queries by how many pixels the height should be reduced when calculating video modes2109 *2110 * @returns VBox status code2111 * @param pInterface Pointer to this interface.2112 * @param pcyReduction Pointer to the result value.2113 * @thread The emulation thread.2114 */2115 DECLR3CALLBACKMEMBER(int, pfnGetHeightReduction,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcyReduction));2116 2117 /**2118 * Informs about a credentials judgement result from the guest.2119 *2120 * @returns VBox status code2121 * @param pInterface Pointer to this interface.2122 * @param fFlags Judgement result flags.2123 * @thread The emulation thread.2124 */2125 DECLR3CALLBACKMEMBER(int, pfnSetCredentialsJudgementResult,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t fFlags));2126 2127 /**2128 * Set the visible region of the display2129 *2130 * @returns VBox status code.2131 * @param pInterface Pointer to this interface.2132 * @param cRect Number of rectangles in pRect2133 * @param pRect Rectangle array2134 * @thread The emulation thread.2135 */2136 DECLR3CALLBACKMEMBER(int, pfnSetVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cRect, PRTRECT pRect));2137 2138 /**2139 * Query the visible region of the display2140 *2141 * @returns VBox status code.2142 * @param pInterface Pointer to this interface.2143 * @param pcRect Number of rectangles in pRect2144 * @param pRect Rectangle array (set to NULL to query the number of rectangles)2145 * @thread The emulation thread.2146 */2147 DECLR3CALLBACKMEMBER(int, pfnQueryVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcRect, PRTRECT pRect));2148 2149 } PDMIVMMDEVCONNECTOR;2150 2151 2152 /**2153 * MAC address.2154 * (The first 24 bits are the 'company id', where the first bit seems to have a special meaning if set.)2155 */2156 typedef union PDMMAC2157 {2158 /** 8-bit view. */2159 uint8_t au8[6];2160 /** 16-bit view. */2161 uint16_t au16[3];2162 } PDMMAC;2163 /** Pointer to a MAC address. */2164 typedef PDMMAC *PPDMMAC;2165 /** Pointer to a const MAC address. */2166 typedef const PDMMAC *PCPDMMAC;2167 2168 2169 /** Pointer to a network port interface */2170 typedef struct PDMINETWORKPORT *PPDMINETWORKPORT;2171 /**2172 * Network port interface.2173 */2174 typedef struct PDMINETWORKPORT2175 {2176 /**2177 * Check how much data the device/driver can receive data now.2178 * This must be called before the pfnRecieve() method is called.2179 *2180 * @returns Number of bytes the device can receive now.2181 * @param pInterface Pointer to the interface structure containing the called function pointer.2182 * @thread EMT2183 */2184 DECLR3CALLBACKMEMBER(size_t, pfnCanReceive,(PPDMINETWORKPORT pInterface));2185 2186 /**2187 * Receive data from the network.2188 *2189 * @returns VBox status code.2190 * @param pInterface Pointer to the interface structure containing the called function pointer.2191 * @param pvBuf The available data.2192 * @param cb Number of bytes available in the buffer.2193 * @thread EMT2194 */2195 DECLR3CALLBACKMEMBER(int, pfnReceive,(PPDMINETWORKPORT pInterface, const void *pvBuf, size_t cb));2196 2197 } PDMINETWORKPORT;2198 2199 2200 /**2201 * Network link state.2202 */2203 typedef enum PDMNETWORKLINKSTATE2204 {2205 /** Invalid state. */2206 PDMNETWORKLINKSTATE_INVALID = 0,2207 /** The link is up. */2208 PDMNETWORKLINKSTATE_UP,2209 /** The link is down. */2210 PDMNETWORKLINKSTATE_DOWN,2211 /** The link is temporarily down while resuming. */2212 PDMNETWORKLINKSTATE_DOWN_RESUME2213 } PDMNETWORKLINKSTATE;2214 2215 2216 /** Pointer to a network connector interface */2217 typedef struct PDMINETWORKCONNECTOR *PPDMINETWORKCONNECTOR;2218 /**2219 * Network connector interface.2220 */2221 typedef struct PDMINETWORKCONNECTOR2222 {2223 /**2224 * Send data to the network.2225 *2226 * @returns VBox status code.2227 * @param pInterface Pointer to the interface structure containing the called function pointer.2228 * @param pvBuf Data to send.2229 * @param cb Number of bytes to send.2230 * @thread EMT2231 */2232 DECLR3CALLBACKMEMBER(int, pfnSend,(PPDMINETWORKCONNECTOR pInterface, const void *pvBuf, size_t cb));2233 2234 /**2235 * Set promiscuous mode.2236 *2237 * This is called when the promiscuous mode is set. This means that there doesn't have2238 * to be a mode change when it's called.2239 *2240 * @param pInterface Pointer to the interface structure containing the called function pointer.2241 * @param fPromiscuous Set if the adaptor is now in promiscuous mode. Clear if it is not.2242 * @thread EMT2243 */2244 DECLR3CALLBACKMEMBER(void, pfnSetPromiscuousMode,(PPDMINETWORKCONNECTOR pInterface, bool fPromiscuous));2245 2246 /**2247 * Notification on link status changes.2248 *2249 * @param pInterface Pointer to the interface structure containing the called function pointer.2250 * @param enmLinkState The new link state.2251 * @thread EMT2252 */2253 DECLR3CALLBACKMEMBER(void, pfnNotifyLinkChanged,(PPDMINETWORKCONNECTOR pInterface, PDMNETWORKLINKSTATE enmLinkState));2254 2255 /**2256 * More receive buffer has become available.2257 *2258 * This is called when the NIC frees up receive buffers.2259 *2260 * @param pInterface Pointer to the interface structure containing the called function pointer.2261 * @thread EMT2262 */2263 DECLR3CALLBACKMEMBER(void, pfnNotifyCanReceive,(PPDMINETWORKCONNECTOR pInterface));2264 2265 } PDMINETWORKCONNECTOR;2266 2267 2268 /** Pointer to a network config port interface */2269 typedef struct PDMINETWORKCONFIG *PPDMINETWORKCONFIG;2270 /**2271 * Network config port interface.2272 */2273 typedef struct PDMINETWORKCONFIG2274 {2275 /**2276 * Gets the current Media Access Control (MAC) address.2277 *2278 * @returns VBox status code.2279 * @param pInterface Pointer to the interface structure containing the called function pointer.2280 * @param pMac Where to store the MAC address.2281 * @thread EMT2282 */2283 DECLR3CALLBACKMEMBER(int, pfnGetMac,(PPDMINETWORKCONFIG pInterface, PPDMMAC *pMac));2284 2285 /**2286 * Gets the new link state.2287 *2288 * @returns The current link state.2289 * @param pInterface Pointer to the interface structure containing the called function pointer.2290 * @thread EMT2291 */2292 DECLR3CALLBACKMEMBER(PDMNETWORKLINKSTATE, pfnGetLinkState,(PPDMINETWORKCONFIG pInterface));2293 2294 /**2295 * Sets the new link state.2296 *2297 * @returns VBox status code.2298 * @param pInterface Pointer to the interface structure containing the called function pointer.2299 * @param enmState The new link state2300 * @thread EMT2301 */2302 DECLR3CALLBACKMEMBER(int, pfnSetLinkState,(PPDMINETWORKCONFIG pInterface, PDMNETWORKLINKSTATE enmState));2303 2304 } PDMINETWORKCONFIG;2305 2306 2307 /** Pointer to a network connector interface */2308 typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;2309 /**2310 * Audio connector interface.2311 */2312 typedef struct PDMIAUDIOCONNECTOR2313 {2314 DECLR3CALLBACKMEMBER(void, pfnRun,(PPDMIAUDIOCONNECTOR pInterface));2315 2316 /* DECLR3CALLBACKMEMBER(int, pfnSetRecordSource,(PPDMIAUDIOINCONNECTOR pInterface, AUDIORECSOURCE)); */2317 2318 } PDMIAUDIOCONNECTOR;2319 2320 2321 /** @todo r=bird: the two following interfaces are hacks to work around the missing audio driver2322 * interface. This should be addressed rather than making more temporary hacks. */2323 2324 /** Pointer to a Audio Sniffer Device port interface. */2325 typedef struct PDMIAUDIOSNIFFERPORT *PPDMIAUDIOSNIFFERPORT;2326 2327 /**2328 * Audio Sniffer port interface.2329 */2330 typedef struct PDMIAUDIOSNIFFERPORT2331 {2332 /**2333 * Enables or disables sniffing. If sniffing is being enabled also sets a flag2334 * whether the audio must be also left on the host.2335 *2336 * @returns VBox status code2337 * @param pInterface Pointer to this interface.2338 * @param fEnable 'true' for enable sniffing, 'false' to disable.2339 * @param fKeepHostAudio Indicates whether host audio should also present2340 * 'true' means that sound should not be played2341 * by the audio device.2342 */2343 DECLR3CALLBACKMEMBER(int, pfnSetup,(PPDMIAUDIOSNIFFERPORT pInterface, bool fEnable, bool fKeepHostAudio));2344 2345 } PDMIAUDIOSNIFFERPORT;2346 2347 /** Pointer to a Audio Sniffer connector interface. */2348 typedef struct PDMIAUDIOSNIFFERCONNECTOR *PPDMIAUDIOSNIFFERCONNECTOR;2349 2350 /**2351 * Audio Sniffer connector interface.2352 * Pair with PDMIAUDIOSNIFFERPORT.2353 */2354 typedef struct PDMIAUDIOSNIFFERCONNECTOR2355 {2356 /**2357 * AudioSniffer device calls this method when audio samples2358 * are about to be played and sniffing is enabled.2359 *2360 * @param pInterface Pointer to this interface.2361 * @param pvSamples Audio samples buffer.2362 * @param cSamples How many complete samples are in the buffer.2363 * @param iSampleHz The sample frequency in Hz.2364 * @param cChannels Number of channels. 1 for mono, 2 for stereo.2365 * @param cBits How many bits a sample for a single channel has. Normally 8 or 16.2366 * @param fUnsigned Whether samples are unsigned values.2367 * @thread The emulation thread.2368 */2369 DECLR3CALLBACKMEMBER(void, pfnAudioSamplesOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, void *pvSamples, uint32_t cSamples,2370 int iSampleHz, int cChannels, int cBits, bool fUnsigned));2371 2372 /**2373 * AudioSniffer device calls this method when output volume is changed.2374 *2375 * @param pInterface Pointer to this interface.2376 * @param u16LeftVolume 0..0xFFFF volume level for left channel.2377 * @param u16RightVolume 0..0xFFFF volume level for right channel.2378 * @thread The emulation thread.2379 */2380 DECLR3CALLBACKMEMBER(void, pfnAudioVolumeOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, uint16_t u16LeftVolume, uint16_t u16RightVolume));2381 2382 } PDMIAUDIOSNIFFERCONNECTOR;2383 2384 2385 /**2386 * Generic status LED core.2387 * Note that a unit doesn't have to support all the indicators.2388 */2389 typedef union PDMLEDCORE2390 {2391 /** 32-bit view. */2392 uint32_t volatile u32;2393 /** Bit view. */2394 struct2395 {2396 /** Reading/Receiving indicator. */2397 uint32_t fReading : 1;2398 /** Writing/Sending indicator. */2399 uint32_t fWriting : 1;2400 /** Busy indicator. */2401 uint32_t fBusy : 1;2402 /** Error indicator. */2403 uint32_t fError : 1;2404 } s;2405 } PDMLEDCORE;2406 2407 /** LED bit masks for the u32 view.2408 * @{ */2409 /** Reading/Receiving indicator. */2410 #define PDMLED_READING BIT(0)2411 /** Writing/Sending indicator. */2412 #define PDMLED_WRITING BIT(1)2413 /** Busy indicator. */2414 #define PDMLED_BUSY BIT(2)2415 /** Error indicator. */2416 #define PDMLED_ERROR BIT(3)2417 /** @} */2418 2419 2420 /**2421 * Generic status LED.2422 * Note that a unit doesn't have to support all the indicators.2423 */2424 typedef struct PDMLED2425 {2426 /** Just a magic for sanity checking. */2427 uint32_t u32Magic;2428 uint32_t u32Alignment; /**< structure size alignment. */2429 /** The actual LED status.2430 * Only the device is allowed to change this. */2431 PDMLEDCORE Actual;2432 /** The asserted LED status which is cleared by the reader.2433 * The device will assert the bits but never clear them.2434 * The driver clears them as it sees fit. */2435 PDMLEDCORE Asserted;2436 } PDMLED;2437 2438 /** Pointer to an LED. */2439 typedef PDMLED *PPDMLED;2440 /** Pointer to a const LED. */2441 typedef const PDMLED *PCPDMLED;2442 2443 #define PDMLED_MAGIC ( 0x11335577 )2444 2445 /** Pointer to an LED ports interface. */2446 typedef struct PDMILEDPORTS *PPDMILEDPORTS;2447 /**2448 * Interface for exporting LEDs.2449 */2450 typedef struct PDMILEDPORTS2451 {2452 /**2453 * Gets the pointer to the status LED of a unit.2454 *2455 * @returns VBox status code.2456 * @param pInterface Pointer to the interface structure containing the called function pointer.2457 * @param iLUN The unit which status LED we desire.2458 * @param ppLed Where to store the LED pointer.2459 */2460 DECLR3CALLBACKMEMBER(int, pfnQueryStatusLed,(PPDMILEDPORTS pInterface, unsigned iLUN, PPDMLED *ppLed));2461 2462 } PDMILEDPORTS;2463 2464 2465 /** Pointer to an LED connectors interface. */2466 typedef struct PDMILEDCONNECTORS *PPDMILEDCONNECTORS;2467 /**2468 * Interface for reading LEDs.2469 */2470 typedef struct PDMILEDCONNECTORS2471 {2472 /**2473 * Notification about a unit which have been changed.2474 *2475 * The driver must discard any pointers to data owned by2476 * the unit and requery it.2477 *2478 * @param pInterface Pointer to the interface structure containing the called function pointer.2479 * @param iLUN The unit number.2480 */2481 DECLR3CALLBACKMEMBER(void, pfnUnitChanged,(PPDMILEDCONNECTORS pInterface, unsigned iLUN));2482 } PDMILEDCONNECTORS;2483 2484 2485 /** The special status unit number */2486 #define PDM_STATUS_LUN 9992487 2488 2489 #ifdef VBOX_HGCM2490 2491 /** Abstract HGCM command structure. Used only to define a typed pointer. */2492 struct VBOXHGCMCMD;2493 2494 /** Pointer to HGCM command structure. This pointer is unique and identifies2495 * the command being processed. The pointer is passed to HGCM connector methods,2496 * and must be passed back to HGCM port when command is completed.2497 */2498 typedef struct VBOXHGCMCMD *PVBOXHGCMCMD;2499 2500 /** Pointer to a HGCM port interface. */2501 typedef struct PDMIHGCMPORT *PPDMIHGCMPORT;2502 2503 /**2504 * HGCM port interface. Normally implemented by VMMDev.2505 */2506 typedef struct PDMIHGCMPORT2507 {2508 /**2509 * Notify the guest on a command completion.2510 *2511 * @param pInterface Pointer to this interface.2512 * @param rc The return code (VBox error code).2513 * @param pCmd A pointer that identifies the completed command.2514 *2515 * @returns VBox status code2516 */2517 DECLR3CALLBACKMEMBER(void, pfnCompleted,(PPDMIHGCMPORT pInterface, int32_t rc, PVBOXHGCMCMD pCmd));2518 2519 } PDMIHGCMPORT;2520 2521 2522 /** Pointer to a HGCM connector interface. */2523 typedef struct PDMIHGCMCONNECTOR *PPDMIHGCMCONNECTOR;2524 2525 /** Pointer to a HGCM service location structure. */2526 typedef struct HGCMSERVICELOCATION *PHGCMSERVICELOCATION;2527 2528 /**2529 * HGCM connector interface.2530 * Pair with PDMIHGCMPORT.2531 */2532 typedef struct PDMIHGCMCONNECTOR2533 {2534 /**2535 * Locate a service and inform it about a client connection.2536 *2537 * @param pInterface Pointer to this interface.2538 * @param pCmd A pointer that identifies the command.2539 * @param pServiceLocation Pointer to the service location structure.2540 * @param pu32ClientID Where to store the client id for the connection.2541 * @return VBox status code.2542 * @thread The emulation thread.2543 */2544 DECLR3CALLBACKMEMBER(int, pfnConnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, PHGCMSERVICELOCATION pServiceLocation, uint32_t *pu32ClientID));2545 2546 /**2547 * Disconnect from service.2548 *2549 * @param pInterface Pointer to this interface.2550 * @param pCmd A pointer that identifies the command.2551 * @param u32ClientID The client id returned by the pfnConnect call.2552 * @return VBox status code.2553 * @thread The emulation thread.2554 */2555 DECLR3CALLBACKMEMBER(int, pfnDisconnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID));2556 2557 /**2558 * Process a guest issued command.2559 *2560 * @param pInterface Pointer to this interface.2561 * @param pCmd A pointer that identifies the command.2562 * @param u32ClientID The client id returned by the pfnConnect call.2563 * @param u32Function Function to be performed by the service.2564 * @param cParms Number of parameters in the array pointed to by paParams.2565 * @param paParms Pointer to an array of parameters.2566 * @return VBox status code.2567 * @thread The emulation thread.2568 */2569 DECLR3CALLBACKMEMBER(int, pfnCall,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID, uint32_t u32Function,2570 uint32_t cParms, PVBOXHGCMSVCPARM paParms));2571 2572 } PDMIHGCMCONNECTOR;2573 2574 #endif2575 2576 /** @} */2577 2578 2579 /** @defgroup grp_pdm_driver Drivers2580 * @ingroup grp_pdm2581 * @{2582 */2583 2584 2585 /**2586 * Construct a driver instance for a VM.2587 *2588 * @returns VBox status.2589 * @param pDrvIns The driver instance data.2590 * If the registration structure is needed, pDrvIns->pDrvReg points to it.2591 * @param pCfgHandle Configuration node handle for the driver. Use this to obtain the configuration2592 * of the driver instance. It's also found in pDrvIns->pCfgHandle as it's expected2593 * to be used frequently in this function.2594 */2595 typedef DECLCALLBACK(int) FNPDMDRVCONSTRUCT(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle);2596 /** Pointer to a FNPDMDRVCONSTRUCT() function. */2597 typedef FNPDMDRVCONSTRUCT *PFNPDMDRVCONSTRUCT;2598 2599 /**2600 * Destruct a driver instance.2601 *2602 * Most VM resources are freed by the VM. This callback is provided so that2603 * any non-VM resources can be freed correctly.2604 *2605 * @param pDrvIns The driver instance data.2606 */2607 typedef DECLCALLBACK(void) FNPDMDRVDESTRUCT(PPDMDRVINS pDrvIns);2608 /** Pointer to a FNPDMDRVDESTRUCT() function. */2609 typedef FNPDMDRVDESTRUCT *PFNPDMDRVDESTRUCT;2610 2611 /**2612 * Driver I/O Control interface.2613 *2614 * This is used by external components, such as the COM interface, to2615 * communicate with a driver using a driver specific interface. Generally,2616 * the driver interfaces are used for this task.2617 *2618 * @returns VBox status code.2619 * @param pDrvIns Pointer to the driver instance.2620 * @param uFunction Function to perform.2621 * @param pvIn Pointer to input data.2622 * @param cbIn Size of input data.2623 * @param pvOut Pointer to output data.2624 * @param cbOut Size of output data.2625 * @param pcbOut Where to store the actual size of the output data.2626 */2627 typedef DECLCALLBACK(int) FNPDMDRVIOCTL(PPDMDRVINS pDrvIns, RTUINT uFunction,2628 void *pvIn, RTUINT cbIn,2629 void *pvOut, RTUINT cbOut, PRTUINT pcbOut);2630 /** Pointer to a FNPDMDRVIOCTL() function. */2631 typedef FNPDMDRVIOCTL *PFNPDMDRVIOCTL;2632 2633 /**2634 * Power On notification.2635 *2636 * @param pDrvIns The driver instance data.2637 */2638 typedef DECLCALLBACK(void) FNPDMDRVPOWERON(PPDMDRVINS pDrvIns);2639 /** Pointer to a FNPDMDRVPOWERON() function. */2640 typedef FNPDMDRVPOWERON *PFNPDMDRVPOWERON;2641 2642 /**2643 * Reset notification.2644 *2645 * @returns VBox status.2646 * @param pDrvIns The driver instance data.2647 */2648 typedef DECLCALLBACK(void) FNPDMDRVRESET(PPDMDRVINS pDrvIns);2649 /** Pointer to a FNPDMDRVRESET() function. */2650 typedef FNPDMDRVRESET *PFNPDMDRVRESET;2651 2652 /**2653 * Suspend notification.2654 *2655 * @returns VBox status.2656 * @param pDrvIns The driver instance data.2657 */2658 typedef DECLCALLBACK(void) FNPDMDRVSUSPEND(PPDMDRVINS pDrvIns);2659 /** Pointer to a FNPDMDRVSUSPEND() function. */2660 typedef FNPDMDRVSUSPEND *PFNPDMDRVSUSPEND;2661 2662 /**2663 * Resume notification.2664 *2665 * @returns VBox status.2666 * @param pDrvIns The driver instance data.2667 */2668 typedef DECLCALLBACK(void) FNPDMDRVRESUME(PPDMDRVINS pDrvIns);2669 /** Pointer to a FNPDMDRVRESUME() function. */2670 typedef FNPDMDRVRESUME *PFNPDMDRVRESUME;2671 2672 /**2673 * Power Off notification.2674 *2675 * @param pDrvIns The driver instance data.2676 */2677 typedef DECLCALLBACK(void) FNPDMDRVPOWEROFF(PPDMDRVINS pDrvIns);2678 /** Pointer to a FNPDMDRVPOWEROFF() function. */2679 typedef FNPDMDRVPOWEROFF *PFNPDMDRVPOWEROFF;2680 2681 /**2682 * Detach notification.2683 *2684 * This is called when a driver below it in the chain is detaching itself2685 * from it. The driver should adjust it's state to reflect this.2686 *2687 * This is like ejecting a cdrom or floppy.2688 *2689 * @param pDrvIns The driver instance.2690 */2691 typedef DECLCALLBACK(void) FNPDMDRVDETACH(PPDMDRVINS pDrvIns);2692 /** Pointer to a FNPDMDRVDETACH() function. */2693 typedef FNPDMDRVDETACH *PFNPDMDRVDETACH;2694 2695 2696 2697 /** PDM Driver Registration Structure,2698 * This structure is used when registering a driver from2699 * VBoxInitDrivers() (HC Ring-3). PDM will continue use till2700 * the VM is terminated.2701 */2702 typedef struct PDMDRVREG2703 {2704 /** Structure version. PDM_DRVREG_VERSION defines the current version. */2705 uint32_t u32Version;2706 /** Driver name. */2707 char szDriverName[32];2708 /** The description of the driver. The UTF-8 string pointed to shall, like this structure,2709 * remain unchanged from registration till VM destruction. */2710 const char *pszDescription;2711 2712 /** Flags, combination of the PDM_DRVREG_FLAGS_* \#defines. */2713 RTUINT fFlags;2714 /** Driver class(es), combination of the PDM_DRVREG_CLASS_* \#defines. */2715 RTUINT fClass;2716 /** Maximum number of instances (per VM). */2717 RTUINT cMaxInstances;2718 /** Size of the instance data. */2719 RTUINT cbInstance;2720 2721 /** Construct instance - required. */2722 PFNPDMDRVCONSTRUCT pfnConstruct;2723 /** Destruct instance - optional. */2724 PFNPDMDRVDESTRUCT pfnDestruct;2725 /** I/O control - optional. */2726 PFNPDMDRVIOCTL pfnIOCtl;2727 /** Power on notification - optional. */2728 PFNPDMDRVPOWERON pfnPowerOn;2729 /** Reset notification - optional. */2730 PFNPDMDRVRESET pfnReset;2731 /** Suspend notification - optional. */2732 PFNPDMDRVSUSPEND pfnSuspend;2733 /** Resume notification - optional. */2734 PFNPDMDRVRESUME pfnResume;2735 /** Detach notification - optional. */2736 PFNPDMDRVDETACH pfnDetach;2737 /** Power off notification - optional. */2738 PFNPDMDRVPOWEROFF pfnPowerOff;2739 2740 } PDMDRVREG;2741 /** Pointer to a PDM Driver Structure. */2742 typedef PDMDRVREG *PPDMDRVREG;2743 /** Const pointer to a PDM Driver Structure. */2744 typedef PDMDRVREG const *PCPDMDRVREG;2745 2746 /** Current DRVREG version number. */2747 #define PDM_DRVREG_VERSION 0x800100002748 2749 /** PDM Device Flags.2750 * @{ */2751 /** @def PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT2752 * The bit count for the current host. */2753 #if HC_ARCH_BITS == 322754 # define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT 0x0000000012755 #elif HC_ARCH_BITS == 642756 # define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT 0x0000000022757 #else2758 # error Unsupported HC_ARCH_BITS value.2759 #endif2760 /** The host bit count mask. */2761 #define PDM_DRVREG_FLAGS_HOST_BITS_MASK 0x0000000032762 2763 /** @} */2764 2765 2766 /** PDM Driver Classes.2767 * @{ */2768 /** Mouse input driver. */2769 #define PDM_DRVREG_CLASS_MOUSE BIT(0)2770 /** Keyboard input driver. */2771 #define PDM_DRVREG_CLASS_KEYBOARD BIT(1)2772 /** Display driver. */2773 #define PDM_DRVREG_CLASS_DISPLAY BIT(2)2774 /** Network transport driver. */2775 #define PDM_DRVREG_CLASS_NETWORK BIT(3)2776 /** Block driver. */2777 #define PDM_DRVREG_CLASS_BLOCK BIT(4)2778 /** Media driver. */2779 #define PDM_DRVREG_CLASS_MEDIA BIT(5)2780 /** Mountable driver. */2781 #define PDM_DRVREG_CLASS_MOUNTABLE BIT(6)2782 /** Audio driver. */2783 #define PDM_DRVREG_CLASS_AUDIO BIT(7)2784 /** VMMDev driver. */2785 #define PDM_DRVREG_CLASS_VMMDEV BIT(8)2786 /** Status driver. */2787 #define PDM_DRVREG_CLASS_STATUS BIT(9)2788 /** ACPI driver. */2789 #define PDM_DRVREG_CLASS_ACPI BIT(10)2790 /** USB related driver. */2791 #define PDM_DRVREG_CLASS_USB BIT(11)2792 /** ISCSI Transport related driver. */2793 #define PDM_DRVREG_CLASS_ISCSITRANSPORT BIT(12)2794 /** Char driver. */2795 #define PDM_DRVREG_CLASS_CHAR BIT(13)2796 /** Stream driver. */2797 #define PDM_DRVREG_CLASS_STREAM BIT(14)2798 /** @} */2799 2800 2801 /**2802 * Poller callback.2803 *2804 * @param pDrvIns The driver instance.2805 */2806 typedef DECLCALLBACK(void) FNPDMDRVPOLLER(PPDMDRVINS pDrvIns);2807 /** Pointer to a FNPDMDRVPOLLER function. */2808 typedef FNPDMDRVPOLLER *PFNPDMDRVPOLLER;2809 2810 #ifdef IN_RING32811 /**2812 * PDM Driver API.2813 */2814 typedef struct PDMDRVHLP2815 {2816 /** Structure version. PDM_DRVHLP_VERSION defines the current version. */2817 uint32_t u32Version;2818 2819 /**2820 * Attaches a driver (chain) to the driver.2821 *2822 * @returns VBox status code.2823 * @param pDrvIns Driver instance.2824 * @param ppBaseInterface Where to store the pointer to the base interface.2825 */2826 DECLR3CALLBACKMEMBER(int, pfnAttach,(PPDMDRVINS pDrvIns, PPDMIBASE *ppBaseInterface));2827 2828 /**2829 * Detach the driver the drivers below us.2830 *2831 * @returns VBox status code.2832 * @param pDrvIns Driver instance.2833 */2834 DECLR3CALLBACKMEMBER(int, pfnDetach,(PPDMDRVINS pDrvIns));2835 2836 /**2837 * Detach the driver from the driver above it and destroy this2838 * driver and all drivers below it.2839 *2840 * @returns VBox status code.2841 * @param pDrvIns Driver instance.2842 */2843 DECLR3CALLBACKMEMBER(int, pfnDetachSelf,(PPDMDRVINS pDrvIns));2844 2845 /**2846 * Prepare a media mount.2847 *2848 * The driver must not have anything attached to itself2849 * when calling this function as the purpose is to set up the configuration2850 * of an future attachment.2851 *2852 * @returns VBox status code2853 * @param pDrvIns Driver instance.2854 * @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have2855 * constructed a configuration which can be attached to the bottom driver.2856 * @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.2857 */2858 DECLR3CALLBACKMEMBER(int, pfnMountPrepare,(PPDMDRVINS pDrvIns, const char *pszFilename, const char *pszCoreDriver));2859 2860 /**2861 * Assert that the current thread is the emulation thread.2862 *2863 * @returns True if correct.2864 * @returns False if wrong.2865 * @param pDrvIns Driver instance.2866 * @param pszFile Filename of the assertion location.2867 * @param iLine Linenumber of the assertion location.2868 * @param pszFunction Function of the assertion location.2869 */2870 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));2871 2872 /**2873 * Assert that the current thread is NOT the emulation thread.2874 *2875 * @returns True if correct.2876 * @returns False if wrong.2877 * @param pDrvIns Driver instance.2878 * @param pszFile Filename of the assertion location.2879 * @param iLine Linenumber of the assertion location.2880 * @param pszFunction Function of the assertion location.2881 */2882 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));2883 2884 /**2885 * Set the VM error message2886 *2887 * @returns rc.2888 * @param pDrvIns Driver instance.2889 * @param rc VBox status code.2890 * @param RT_SRC_POS_DECL Use RT_SRC_POS.2891 * @param pszFormat Error message format string.2892 * @param ... Error message arguments.2893 */2894 DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));2895 2896 /**2897 * Set the VM error message2898 *2899 * @returns rc.2900 * @param pDrvIns Driver instance.2901 * @param rc VBox status code.2902 * @param RT_SRC_POS_DECL Use RT_SRC_POS.2903 * @param pszFormat Error message format string.2904 * @param va Error message arguments.2905 */2906 DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));2907 2908 /**2909 * Set the VM runtime error message2910 *2911 * @returns VBox status code.2912 * @param pDrvIns Driver instance.2913 * @param fFatal Whether it is a fatal error or not.2914 * @param pszErrorID Error ID string.2915 * @param pszFormat Error message format string.2916 * @param ... Error message arguments.2917 */2918 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDRVINS pDrvIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));2919 2920 /**2921 * Set the VM runtime error message2922 *2923 * @returns VBox status code.2924 * @param pDrvIns Driver instance.2925 * @param fFatal Whether it is a fatal error or not.2926 * @param pszErrorID Error ID string.2927 * @param pszFormat Error message format string.2928 * @param va Error message arguments.2929 */2930 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDRVINS pDrvIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));2931 2932 /**2933 * Create a queue.2934 *2935 * @returns VBox status code.2936 * @param pDrvIns Driver instance.2937 * @param cbItem Size a queue item.2938 * @param cItems Number of items in the queue.2939 * @param cMilliesInterval Number of milliseconds between polling the queue.2940 * If 0 then the emulation thread will be notified whenever an item arrives.2941 * @param pfnCallback The consumer function.2942 * @param ppQueue Where to store the queue handle on success.2943 * @thread The emulation thread.2944 */2945 DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, PFNPDMQUEUEDRV pfnCallback, PPDMQUEUE *ppQueue));2946 2947 /**2948 * Register a poller function.2949 * TEMPORARY HACK FOR NETWORKING! DON'T USE!2950 *2951 * @returns VBox status code.2952 * @param pDrvIns Driver instance.2953 * @param pfnPoller The callback function.2954 */2955 DECLR3CALLBACKMEMBER(int, pfnPDMPollerRegister,(PPDMDRVINS pDrvIns, PFNPDMDRVPOLLER pfnPoller));2956 2957 /**2958 * Query the virtual timer frequency.2959 *2960 * @returns Frequency in Hz.2961 * @param pDrvIns Driver instance.2962 * @thread Any thread.2963 */2964 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualFreq,(PPDMDRVINS pDrvIns));2965 2966 /**2967 * Query the virtual time.2968 *2969 * @returns The current virtual time.2970 * @param pDrvIns Driver instance.2971 * @thread Any thread.2972 */2973 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualTime,(PPDMDRVINS pDrvIns));2974 2975 /**2976 * Creates a timer.2977 *2978 * @returns VBox status.2979 * @param pDrvIns Driver instance.2980 * @param enmClock The clock to use on this timer.2981 * @param pfnCallback Callback function.2982 * @param pszDesc Pointer to description string which must stay around2983 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).2984 * @param ppTimer Where to store the timer on success.2985 */2986 DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDRVINS pDrvIns, TMCLOCK enmClock, PFNTMTIMERDRV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer));2987 2988 /**2989 * Register a save state data unit.2990 *2991 * @returns VBox status.2992 * @param pDrvIns Driver instance.2993 * @param pszName Data unit name.2994 * @param u32Instance The instance identifier of the data unit.2995 * This must together with the name be unique.2996 * @param u32Version Data layout version number.2997 * @param cbGuess The approximate amount of data in the unit.2998 * Only for progress indicators.2999 * @param pfnSavePrep Prepare save callback, optional.3000 * @param pfnSaveExec Execute save callback, optional.3001 * @param pfnSaveDone Done save callback, optional.3002 * @param pfnLoadPrep Prepare load callback, optional.3003 * @param pfnLoadExec Execute load callback, optional.3004 * @param pfnLoadDone Done load callback, optional.3005 */3006 DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,3007 PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,3008 PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone));3009 3010 /**3011 * Deregister a save state data unit.3012 *3013 * @returns VBox status.3014 * @param pDrvIns Driver instance.3015 * @param pszName Data unit name.3016 * @param u32Instance The instance identifier of the data unit.3017 * This must together with the name be unique.3018 */3019 DECLR3CALLBACKMEMBER(int, pfnSSMDeregister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance));3020 3021 /**3022 * Registers a statistics sample if statistics are enabled.3023 *3024 * @param pDrvIns Driver instance.3025 * @param pvSample Pointer to the sample.3026 * @param enmType Sample type. This indicates what pvSample is pointing at.3027 * @param pszName Sample name. The name is on this form "/<component>/<sample>".3028 * Further nesting is possible.3029 * @param enmUnit Sample unit.3030 * @param pszDesc Sample description.3031 */3032 DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName,3033 STAMUNIT enmUnit, const char *pszDesc));3034 3035 /**3036 * Same as pfnSTAMRegister except that the name is specified in a3037 * RTStrPrintf like fashion.3038 *3039 * @returns VBox status.3040 * @param pDrvIns Driver instance.3041 * @param pvSample Pointer to the sample.3042 * @param enmType Sample type. This indicates what pvSample is pointing at.3043 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.3044 * @param enmUnit Sample unit.3045 * @param pszDesc Sample description.3046 * @param pszName The sample name format string.3047 * @param ... Arguments to the format string.3048 */3049 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,3050 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, ...));3051 3052 /**3053 * Same as pfnSTAMRegister except that the name is specified in a3054 * RTStrPrintfV like fashion.3055 *3056 * @returns VBox status.3057 * @param pDrvIns Driver instance.3058 * @param pvSample Pointer to the sample.3059 * @param enmType Sample type. This indicates what pvSample is pointing at.3060 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.3061 * @param enmUnit Sample unit.3062 * @param pszDesc Sample description.3063 * @param pszName The sample name format string.3064 * @param args Arguments to the format string.3065 */3066 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,3067 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list args));3068 3069 /**3070 * Calls the HC R0 VMM entry point, in a safer but slower manner than SUPCallVMMR0.3071 * When entering using this call the R0 components can call into the host kernel3072 * (i.e. use the SUPR0 and RT APIs).3073 *3074 * See VMMR0Entry() for more details.3075 *3076 * @returns error code specific to uFunction.3077 * @param pDrvIns The driver instance.3078 * @param uOperation Operation to execute.3079 * This is limited to services.3080 * @param pvArg Pointer to argument structure or if cbArg is 0 just an value.3081 * @param cbArg The size of the argument. This is used to copy whatever the argument3082 * points at into a kernel buffer to avoid problems like the user page3083 * being invalidated while we're executing the call.3084 */3085 DECLR3CALLBACKMEMBER(int, pfnSUPCallVMMR0Ex,(PPDMDRVINS pDrvIns, unsigned uOperation, void *pvArg, unsigned cbArg));3086 3087 /** Just a safety precaution. */3088 uint32_t u32TheEnd;3089 } PDMDRVHLP;3090 /** Pointer PDM Driver API. */3091 typedef PDMDRVHLP *PPDMDRVHLP;3092 /** Pointer const PDM Driver API. */3093 typedef const PDMDRVHLP *PCPDMDRVHLP;3094 3095 /** Current DRVHLP version number. */3096 #define PDM_DRVHLP_VERSION 0x900100003097 3098 3099 3100 /**3101 * PDM Driver Instance.3102 */3103 typedef struct PDMDRVINS3104 {3105 /** Structure version. PDM_DRVINS_VERSION defines the current version. */3106 uint32_t u32Version;3107 3108 /** Internal data. */3109 union3110 {3111 #ifdef PDMDRVINSINT_DECLARED3112 PDMDRVINSINT s;3113 #endif3114 uint8_t padding[HC_ARCH_BITS == 32 ? 32 : 64];3115 } Internal;3116 3117 /** Pointer the PDM Driver API. */3118 HCPTRTYPE(PCPDMDRVHLP) pDrvHlp;3119 /** Pointer to driver registration structure. */3120 HCPTRTYPE(PCPDMDRVREG) pDrvReg;3121 /** Configuration handle. */3122 HCPTRTYPE(PCFGMNODE) pCfgHandle;3123 /** Driver instance number. */3124 RTUINT iInstance;3125 /** Pointer to the base interface of the device/driver instance above. */3126 HCPTRTYPE(PPDMIBASE) pUpBase;3127 /** Pointer to the base interface of the driver instance below. */3128 HCPTRTYPE(PPDMIBASE) pDownBase;3129 /** The base interface of the driver.3130 * The driver constructor initializes this. */3131 PDMIBASE IBase;3132 /* padding to make achInstanceData aligned at 16 byte boundrary. */3133 uint32_t au32Padding[HC_ARCH_BITS == 32 ? 3 : 1];3134 /** Pointer to driver instance data. */3135 HCPTRTYPE(void *) pvInstanceData;3136 /** Driver instance data. The size of this area is defined3137 * in the PDMDRVREG::cbInstanceData field. */3138 char achInstanceData[4];3139 } PDMDRVINS;3140 3141 /** Current DRVREG version number. */3142 #define PDM_DRVINS_VERSION 0xa00100003143 3144 /** Converts a pointer to the PDMDRVINS::IBase to a pointer to PDMDRVINS. */3145 #define PDMIBASE_2_PDMDRV(pInterface) ( (PPDMDRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDRVINS, IBase)) )3146 3147 /**3148 * @copydoc PDMDRVHLP::pfnVMSetError3149 */3150 DECLINLINE(int) PDMDrvHlpVMSetError(PPDMDRVINS pDrvIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)3151 {3152 va_list va;3153 va_start(va, pszFormat);3154 pDrvIns->pDrvHlp->pfnVMSetErrorV(pDrvIns, rc, RT_SRC_POS_ARGS, pszFormat, va);3155 va_end(va);3156 return rc;3157 }3158 3159 /** @def PDMDRV_SET_ERROR3160 * Set the VM error. See PDMDrvHlpVMSetError() for printf like message formatting.3161 */3162 #define PDMDRV_SET_ERROR(pDrvIns, rc, pszError) \3163 PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, "%s", pszError)3164 3165 /**3166 * @copydoc PDMDRVHLP::pfnVMSetRuntimeError3167 */3168 DECLINLINE(int) PDMDrvHlpVMSetRuntimeError(PPDMDRVINS pDrvIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...)3169 {3170 va_list va;3171 int rc;3172 va_start(va, pszFormat);3173 rc = pDrvIns->pDrvHlp->pfnVMSetRuntimeErrorV(pDrvIns, fFatal, pszErrorID, pszFormat, va);3174 va_end(va);3175 return rc;3176 }3177 3178 /** @def PDMDRV_SET_RUNTIME_ERROR3179 * Set the VM runtime error. See PDMDrvHlpVMSetRuntimeError() for printf like message formatting.3180 */3181 #define PDMDRV_SET_RUNTIME_ERROR(pDrvIns, fFatal, pszErrorID, pszError) \3182 PDMDrvHlpVMSetError(pDrvIns, fFatal, pszErrorID, "%s", pszError)3183 3184 #endif /* IN_RING3 */3185 3186 3187 /** @def PDMDRV_ASSERT_EMT3188 * Assert that the current thread is the emulation thread.3189 */3190 #ifdef VBOX_STRICT3191 # define PDMDRV_ASSERT_EMT(pDrvIns) pDrvIns->pDrvHlp->pfnAssertEMT(pDrvIns, __FILE__, __LINE__, __FUNCTION__)3192 #else3193 # define PDMDRV_ASSERT_EMT(pDrvIns) do { } while (0)3194 #endif3195 3196 /** @def PDMDRV_ASSERT_OTHER3197 * Assert that the current thread is NOT the emulation thread.3198 */3199 #ifdef VBOX_STRICT3200 # define PDMDRV_ASSERT_OTHER(pDrvIns) pDrvIns->pDrvHlp->pfnAssertOther(pDrvIns, __FILE__, __LINE__, __FUNCTION__)3201 #else3202 # define PDMDRV_ASSERT_OTHER(pDrvIns) do { } while (0)3203 #endif3204 3205 3206 #ifdef IN_RING33207 /**3208 * @copydoc PDMDRVHLP::pfnSTAMRegister3209 */3210 DECLINLINE(void) PDMDrvHlpSTAMRegister(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)3211 {3212 pDrvIns->pDrvHlp->pfnSTAMRegister(pDrvIns, pvSample, enmType, pszName, enmUnit, pszDesc);3213 }3214 3215 /**3216 * @copydoc PDMDRVHLP::pfnSTAMRegisterF3217 */3218 DECLINLINE(void) PDMDrvHlpSTAMRegisterF(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,3219 const char *pszDesc, const char *pszName, ...)3220 {3221 va_list va;3222 va_start(va, pszName);3223 pDrvIns->pDrvHlp->pfnSTAMRegisterV(pDrvIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);3224 va_end(va);3225 }3226 #endif /* IN_RING3 */3227 3228 3229 3230 /** Pointer to callbacks provided to the VBoxDriverRegister() call. */3231 typedef struct PDMDRVREGCB *PPDMDRVREGCB;3232 /** Pointer to const callbacks provided to the VBoxDriverRegister() call. */3233 typedef const struct PDMDRVREGCB *PCPDMDRVREGCB;3234 3235 /**3236 * Callbacks for VBoxDriverRegister().3237 */3238 typedef struct PDMDRVREGCB3239 {3240 /** Interface version.3241 * This is set to PDM_DRVREG_CB_VERSION. */3242 uint32_t u32Version;3243 3244 /**3245 * Registers a driver with the current VM instance.3246 *3247 * @returns VBox status code.3248 * @param pCallbacks Pointer to the callback table.3249 * @param pDrvReg Pointer to the driver registration record.3250 * This data must be permanent and readonly.3251 */3252 DECLR3CALLBACKMEMBER(int, pfnRegister,(PCPDMDRVREGCB pCallbacks, PCPDMDRVREG pDrvReg));3253 } PDMDRVREGCB;3254 3255 /** Current version of the PDMDRVREGCB structure. */3256 #define PDM_DRVREG_CB_VERSION 0xb00100003257 3258 3259 /**3260 * The VBoxDriverRegister callback function.3261 *3262 * PDM will invoke this function after loading a driver module and letting3263 * the module decide which drivers to register and how to handle conflicts.3264 *3265 * @returns VBox status code.3266 * @param pCallbacks Pointer to the callback table.3267 * @param u32Version VBox version number.3268 */3269 typedef DECLCALLBACK(int) FNPDMVBOXDRIVERSREGISTER(PCPDMDRVREGCB pCallbacks, uint32_t u32Version);3270 3271 /**3272 * Register external drivers3273 *3274 * @returns VBox status code.3275 * @param pVM The VM to operate on.3276 * @param pfnCallback Driver registration callback3277 */3278 PDMR3DECL(int) PDMR3RegisterDrivers(PVM pVM, FNPDMVBOXDRIVERSREGISTER pfnCallback);3279 3280 /** @} */3281 3282 3283 3284 3285 /** @defgroup grp_pdm_device Devices3286 * @ingroup grp_pdm3287 * @{3288 */3289 3290 3291 /** @def PDMBOTHCBDECL3292 * Macro for declaring a callback which is static in HC and exported in GC.3293 */3294 #if defined(IN_GC) || defined(IN_RING0)3295 # define PDMBOTHCBDECL(type) DECLEXPORT(type)3296 #else3297 # define PDMBOTHCBDECL(type) static type3298 #endif3299 3300 3301 /**3302 * Construct a device instance for a VM.3303 *3304 * @returns VBox status.3305 * @param pDevIns The device instance data.3306 * If the registration structure is needed, pDevIns->pDevReg points to it.3307 * @param iInstance Instance number. Use this to figure out which registers and such to use.3308 * The instance number is also found in pDevIns->iInstance, but since it's3309 * likely to be freqently used PDM passes it as parameter.3310 * @param pCfgHandle Configuration node handle for the device. Use this to obtain the configuration3311 * of the device instance. It's also found in pDevIns->pCfgHandle, but since it's3312 * primary usage will in this function it's passed as a parameter.3313 */3314 typedef DECLCALLBACK(int) FNPDMDEVCONSTRUCT(PPDMDEVINS pDevIns, int iInstance, PCFGMNODE pCfgHandle);3315 /** Pointer to a FNPDMDEVCONSTRUCT() function. */3316 typedef FNPDMDEVCONSTRUCT *PFNPDMDEVCONSTRUCT;3317 3318 /**3319 * Destruct a device instance.3320 *3321 * Most VM resources are freed by the VM. This callback is provided so that any non-VM3322 * resources can be freed correctly.3323 *3324 * @returns VBox status.3325 * @param pDevIns The device instance data.3326 */3327 typedef DECLCALLBACK(int) FNPDMDEVDESTRUCT(PPDMDEVINS pDevIns);3328 /** Pointer to a FNPDMDEVDESTRUCT() function. */3329 typedef FNPDMDEVDESTRUCT *PFNPDMDEVDESTRUCT;3330 3331 /**3332 * Device relocation callback.3333 *3334 * When this callback is called the device instance data, and if the3335 * device have a GC component, is being relocated, or/and the selectors3336 * have been changed. The device must use the chance to perform the3337 * necessary pointer relocations and data updates.3338 *3339 * Before the GC code is executed the first time, this function will be3340 * called with a 0 delta so GC pointer calculations can be one in one place.3341 *3342 * @param pDevIns Pointer to the device instance.3343 * @param offDelta The relocation delta relative to the old location.3344 *3345 * @remark A relocation CANNOT fail.3346 */3347 typedef DECLCALLBACK(void) FNPDMDEVRELOCATE(PPDMDEVINS pDevIns, RTGCINTPTR offDelta);3348 /** Pointer to a FNPDMDEVRELOCATE() function. */3349 typedef FNPDMDEVRELOCATE *PFNPDMDEVRELOCATE;3350 3351 3352 /**3353 * Device I/O Control interface.3354 *3355 * This is used by external components, such as the COM interface, to3356 * communicate with devices using a class wide interface or a device3357 * specific interface.3358 *3359 * @returns VBox status code.3360 * @param pDevIns Pointer to the device instance.3361 * @param uFunction Function to perform.3362 * @param pvIn Pointer to input data.3363 * @param cbIn Size of input data.3364 * @param pvOut Pointer to output data.3365 * @param cbOut Size of output data.3366 * @param pcbOut Where to store the actual size of the output data.3367 */3368 typedef DECLCALLBACK(int) FNPDMDEVIOCTL(PPDMDEVINS pDevIns, RTUINT uFunction,3369 void *pvIn, RTUINT cbIn,3370 void *pvOut, RTUINT cbOut, PRTUINT pcbOut);3371 /** Pointer to a FNPDMDEVIOCTL() function. */3372 typedef FNPDMDEVIOCTL *PFNPDMDEVIOCTL;3373 3374 /**3375 * Power On notification.3376 *3377 * @returns VBox status.3378 * @param pDevIns The device instance data.3379 */3380 typedef DECLCALLBACK(void) FNPDMDEVPOWERON(PPDMDEVINS pDevIns);3381 /** Pointer to a FNPDMDEVPOWERON() function. */3382 typedef FNPDMDEVPOWERON *PFNPDMDEVPOWERON;3383 3384 /**3385 * Reset notification.3386 *3387 * @returns VBox status.3388 * @param pDevIns The device instance data.3389 */3390 typedef DECLCALLBACK(void) FNPDMDEVRESET(PPDMDEVINS pDevIns);3391 /** Pointer to a FNPDMDEVRESET() function. */3392 typedef FNPDMDEVRESET *PFNPDMDEVRESET;3393 3394 /**3395 * Suspend notification.3396 *3397 * @returns VBox status.3398 * @param pDevIns The device instance data.3399 */3400 typedef DECLCALLBACK(void) FNPDMDEVSUSPEND(PPDMDEVINS pDevIns);3401 /** Pointer to a FNPDMDEVSUSPEND() function. */3402 typedef FNPDMDEVSUSPEND *PFNPDMDEVSUSPEND;3403 3404 /**3405 * Resume notification.3406 *3407 * @returns VBox status.3408 * @param pDevIns The device instance data.3409 */3410 typedef DECLCALLBACK(void) FNPDMDEVRESUME(PPDMDEVINS pDevIns);3411 /** Pointer to a FNPDMDEVRESUME() function. */3412 typedef FNPDMDEVRESUME *PFNPDMDEVRESUME;3413 3414 /**3415 * Power Off notification.3416 *3417 * @param pDevIns The device instance data.3418 */3419 typedef DECLCALLBACK(void) FNPDMDEVPOWEROFF(PPDMDEVINS pDevIns);3420 /** Pointer to a FNPDMDEVPOWEROFF() function. */3421 typedef FNPDMDEVPOWEROFF *PFNPDMDEVPOWEROFF;3422 3423 /**3424 * Attach command.3425 *3426 * This is called to let the device attach to a driver for a specified LUN3427 * during runtime. This is not called during VM construction, the device3428 * constructor have to attach to all the available drivers.3429 *3430 * This is like plugging in the keyboard or mouse after turning on the PC.3431 *3432 * @returns VBox status code.3433 * @param pDevIns The device instance.3434 * @param iLUN The logical unit which is being detached.3435 */3436 typedef DECLCALLBACK(int) FNPDMDEVATTACH(PPDMDEVINS pDevIns, unsigned iLUN);3437 /** Pointer to a FNPDMDEVATTACH() function. */3438 typedef FNPDMDEVATTACH *PFNPDMDEVATTACH;3439 3440 /**3441 * Detach notification.3442 *3443 * This is called when a driver is detaching itself from a LUN of the device.3444 * The device should adjust it's state to reflect this.3445 *3446 * This is like unplugging the network cable to use it for the laptop or3447 * something while the PC is still running.3448 *3449 * @param pDevIns The device instance.3450 * @param iLUN The logical unit which is being detached.3451 */3452 typedef DECLCALLBACK(void) FNPDMDEVDETACH(PPDMDEVINS pDevIns, unsigned iLUN);3453 /** Pointer to a FNPDMDEVDETACH() function. */3454 typedef FNPDMDEVDETACH *PFNPDMDEVDETACH;3455 3456 /**3457 * Query the base interface of a logical unit.3458 *3459 * @returns VBOX status code.3460 * @param pDevIns The device instance.3461 * @param iLUN The logicial unit to query.3462 * @param ppBase Where to store the pointer to the base interface of the LUN.3463 */3464 typedef DECLCALLBACK(int) FNPDMDEVQUERYINTERFACE(PPDMDEVINS pDevIns, unsigned iLUN, PPDMIBASE *ppBase);3465 /** Pointer to a FNPDMDEVQUERYINTERFACE() function. */3466 typedef FNPDMDEVQUERYINTERFACE *PFNPDMDEVQUERYINTERFACE;3467 3468 /**3469 * Init complete notification.3470 * This can be done to do communication with other devices and other3471 * initialization which requires everything to be in place.3472 *3473 * @returns VBOX status code.3474 * @param pDevIns The device instance.3475 */3476 typedef DECLCALLBACK(int) FNPDMDEVINITCOMPLETE(PPDMDEVINS pDevIns);3477 /** Pointer to a FNPDMDEVINITCOMPLETE() function. */3478 typedef FNPDMDEVINITCOMPLETE *PFNPDMDEVINITCOMPLETE;3479 3480 3481 3482 /** PDM Device Registration Structure,3483 * This structure is used when registering a device from3484 * VBoxInitDevices() in HC Ring-3. PDM will continue use till3485 * the VM is terminated.3486 */3487 typedef struct PDMDEVREG3488 {3489 /** Structure version. PDM_DEVREG_VERSION defines the current version. */3490 uint32_t u32Version;3491 /** Device name. */3492 char szDeviceName[32];3493 /** Name of guest context module (no path).3494 * Only evalutated if PDM_DEVREG_FLAGS_GC is set. */3495 char szGCMod[32];3496 /** Name of guest context module (no path).3497 * Only evalutated if PDM_DEVREG_FLAGS_GC is set. */3498 char szR0Mod[32];3499 /** The description of the device. The UTF-8 string pointed to shall, like this structure,3500 * remain unchanged from registration till VM destruction. */3501 const char *pszDescription;3502 3503 /** Flags, combination of the PDM_DEVREG_FLAGS_* \#defines. */3504 RTUINT fFlags;3505 /** Device class(es), combination of the PDM_DEVREG_CLASS_* \#defines. */3506 RTUINT fClass;3507 /** Maximum number of instances (per VM). */3508 RTUINT cMaxInstances;3509 /** Size of the instance data. */3510 RTUINT cbInstance;3511 3512 /** Construct instance - required. */3513 PFNPDMDEVCONSTRUCT pfnConstruct;3514 /** Destruct instance - optional. */3515 PFNPDMDEVDESTRUCT pfnDestruct;3516 /** Relocation command - optional. */3517 PFNPDMDEVRELOCATE pfnRelocate;3518 /** I/O Control interface - optional. */3519 PFNPDMDEVIOCTL pfnIOCtl;3520 /** Power on notification - optional. */3521 PFNPDMDEVPOWERON pfnPowerOn;3522 /** Reset notification - optional. */3523 PFNPDMDEVRESET pfnReset;3524 /** Suspend notification - optional. */3525 PFNPDMDEVSUSPEND pfnSuspend;3526 /** Resume notification - optional. */3527 PFNPDMDEVRESUME pfnResume;3528 /** Attach command - optional. */3529 PFNPDMDEVATTACH pfnAttach;3530 /** Detach notification - optional. */3531 PFNPDMDEVDETACH pfnDetach;3532 /** Query a LUN base interface - optional. */3533 PFNPDMDEVQUERYINTERFACE pfnQueryInterface;3534 /** Init complete notification - optional. */3535 PFNPDMDEVINITCOMPLETE pfnInitComplete;3536 /** Power off notification - optional. */3537 PFNPDMDEVPOWEROFF pfnPowerOff;3538 } PDMDEVREG;3539 /** Pointer to a PDM Device Structure. */3540 typedef PDMDEVREG *PPDMDEVREG;3541 /** Const pointer to a PDM Device Structure. */3542 typedef PDMDEVREG const *PCPDMDEVREG;3543 3544 /** Current DEVREG version number. */3545 #define PDM_DEVREG_VERSION 0xc00100003546 3547 /** PDM Device Flags.3548 * @{ */3549 /** This flag is used to indicate that the device has a GC component. */3550 #define PDM_DEVREG_FLAGS_GC 0x000000013551 /** This flag is used to indicate that the device has a R0 component. */3552 #define PDM_DEVREG_FLAGS_R0 0x000100003553 3554 /** @def PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT3555 * The bit count for the current host. */3556 #if HC_ARCH_BITS == 323557 # define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT 0x000000023558 #elif HC_ARCH_BITS == 643559 # define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT 0x000000043560 #else3561 # error Unsupported HC_ARCH_BITS value.3562 #endif3563 /** The host bit count mask. */3564 #define PDM_DEVREG_FLAGS_HOST_BITS_MASK 0x000000063565 3566 /** The device support only 32-bit guests. */3567 #define PDM_DEVREG_FLAGS_GUEST_BITS_32 0x000000083568 /** The device support only 64-bit guests. */3569 #define PDM_DEVREG_FLAGS_GUEST_BITS_64 0x000000103570 /** The device support both 32-bit & 64-bit guests. */3571 #define PDM_DEVREG_FLAGS_GUEST_BITS_32_64 0x000000183572 /** @def PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT3573 * The guest bit count for the current compilation. */3574 #if GC_ARCH_BITS == 323575 # define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_323576 #elif GC_ARCH_BITS == 643577 # define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_643578 #else3579 # error Unsupported GC_ARCH_BITS value.3580 #endif3581 /** The guest bit count mask. */3582 #define PDM_DEVREG_FLAGS_GUEST_BITS_MASK 0x000000183583 3584 /** Indicates that the devices support PAE36 on a 32-bit guest. */3585 #define PDM_DEVREG_FLAGS_PAE36 0x000000203586 /** @} */3587 3588 3589 /** PDM Device Classes.3590 * The order is important, lower bit earlier instantiation.3591 * @{ */3592 /** Architecture device. */3593 #define PDM_DEVREG_CLASS_ARCH BIT(0)3594 /** Architecture BIOS device. */3595 #define PDM_DEVREG_CLASS_ARCH_BIOS BIT(1)3596 /** PCI bus brigde. */3597 #define PDM_DEVREG_CLASS_BUS_PCI BIT(2)3598 /** ISA bus brigde. */3599 #define PDM_DEVREG_CLASS_BUS_ISA BIT(3)3600 /** Input device (mouse, keyboard, joystick,..). */3601 #define PDM_DEVREG_CLASS_INPUT BIT(4)3602 /** Interrupt controller (PIC). */3603 #define PDM_DEVREG_CLASS_PIC BIT(5)3604 /** Interval controoler (PIT). */3605 #define PDM_DEVREG_CLASS_PIT BIT(6)3606 /** RTC/CMOS. */3607 #define PDM_DEVREG_CLASS_RTC BIT(7)3608 /** DMA controller. */3609 #define PDM_DEVREG_CLASS_DMA BIT(8)3610 /** VMM Device. */3611 #define PDM_DEVREG_CLASS_VMM_DEV BIT(9)3612 /** Graphics device, like VGA. */3613 #define PDM_DEVREG_CLASS_GRAPHICS BIT(10)3614 /** Storage controller device. */3615 #define PDM_DEVREG_CLASS_STORAGE BIT(11)3616 /** Network interface controller. */3617 #define PDM_DEVREG_CLASS_NETWORK BIT(12)3618 /** Audio. */3619 #define PDM_DEVREG_CLASS_AUDIO BIT(13)3620 /** USB bus? */3621 #define PDM_DEVREG_CLASS_BUS_USB BIT(14) /* ??? */3622 /** ACPI. */3623 #define PDM_DEVREG_CLASS_ACPI BIT(15)3624 /** Serial controller device. */3625 #define PDM_DEVREG_CLASS_SERIAL BIT(16)3626 /** Parallel controller device */3627 #define PDM_DEVREG_CLASS_PARALLEL BIT(17)3628 /** Misc devices (always last). */3629 #define PDM_DEVREG_CLASS_MISC BIT(31)3630 /** @} */3631 3632 3633 /** @name IRQ Level for use with the *SetIrq APIs.3634 * @{3635 */3636 /** Assert the IRQ (can assume value 1). */3637 #define PDM_IRQ_LEVEL_HIGH BIT(0)3638 /** Deassert the IRQ (can assume value 0). */3639 #define PDM_IRQ_LEVEL_LOW 03640 /** flip-flop - assert and then deassert it again immediately. */3641 #define PDM_IRQ_LEVEL_FLIP_FLOP (BIT(1) | PDM_IRQ_LEVEL_HIGH)3642 /** @} */3643 3644 3645 /**3646 * PCI Bus registaration structure.3647 * All the callbacks, except the PCIBIOS hack, are working on PCI devices.3648 */3649 typedef struct PDMPCIBUSREG3650 {3651 /** Structure version number. PDM_PCIBUSREG_VERSION defines the current version. */3652 uint32_t u32Version;3653 3654 /**3655 * Registers the device with the default PCI bus.3656 *3657 * @returns VBox status code.3658 * @param pDevIns Device instance of the PCI Bus.3659 * @param pPciDev The PCI device structure.3660 * Any PCI enabled device must keep this in it's instance data!3661 * Fill in the PCI data config before registration, please.3662 * @param pszName Pointer to device name (permanent, readonly). For debugging, not unique.3663 * @param iDev The device number ((dev << 3) | function) the device should have on the bus.3664 * If negative, the pci bus device will assign one.3665 */3666 DECLR3CALLBACKMEMBER(int, pfnRegisterHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, const char *pszName, int iDev));3667 3668 /**3669 * Registers a I/O region (memory mapped or I/O ports) for a PCI device.3670 *3671 * @returns VBox status code.3672 * @param pDevIns Device instance of the PCI Bus.3673 * @param pPciDev The PCI device structure.3674 * @param iRegion The region number.3675 * @param cbRegion Size of the region.3676 * @param iType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.3677 * @param pfnCallback Callback for doing the mapping.3678 */3679 DECLR3CALLBACKMEMBER(int, pfnIORegionRegisterHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback));3680 3681 /**3682 * Register PCI configuration space read/write callbacks.3683 *3684 * @param pDevIns Device instance of the PCI Bus.3685 * @param pPciDev The PCI device structure.3686 * @param pfnRead Pointer to the user defined PCI config read function.3687 * @param ppfnReadOld Pointer to function pointer which will receive the old (default)3688 * PCI config read function. This way, user can decide when (and if)3689 * to call default PCI config read function. Can be NULL.3690 * @param pfnWrite Pointer to the user defined PCI config write function.3691 * @param pfnWriteOld Pointer to function pointer which will receive the old (default)3692 * PCI config write function. This way, user can decide when (and if)3693 * to call default PCI config write function. Can be NULL.3694 * @thread EMT3695 */3696 DECLR3CALLBACKMEMBER(void, pfnSetConfigCallbacksHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,3697 PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld));3698 3699 /**3700 * Set the IRQ for a PCI device.3701 *3702 * @param pDevIns Device instance of the PCI Bus.3703 * @param pPciDev The PCI device structure.3704 * @param iIrq IRQ number to set.3705 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.3706 */3707 DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iIrq, int iLevel));3708 3709 /**3710 * Saves a state of the PCI device.3711 *3712 * @returns VBox status code.3713 * @param pDevIns Device instance of the PCI Bus.3714 * @param pPciDev Pointer to PCI device.3715 * @param pSSMHandle The handle to save the state to.3716 */3717 DECLR3CALLBACKMEMBER(int, pfnSaveExecHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PSSMHANDLE pSSMHandle));3718 3719 /**3720 * Loads a saved PCI device state.3721 *3722 * @returns VBox status code.3723 * @param pDevIns Device instance of the PCI Bus.3724 * @param pPciDev Pointer to PCI device.3725 * @param pSSMHandle The handle to the saved state.3726 */3727 DECLR3CALLBACKMEMBER(int, pfnLoadExecHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PSSMHANDLE pSSMHandle));3728 3729 /**3730 * Called to perform the job of the bios.3731 * This is only called for the first PCI Bus - it is expected to3732 * service all the PCI buses.3733 *3734 * @returns VBox status.3735 * @param pDevIns Device instance of the first bus.3736 */3737 DECLR3CALLBACKMEMBER(int, pfnFakePCIBIOSHC,(PPDMDEVINS pDevIns));3738 3739 /** The name of the SetIrq GC entry point. */3740 const char *pszSetIrqGC;3741 3742 /** The name of the SetIrq R0 entry point. */3743 const char *pszSetIrqR0;3744 3745 } PDMPCIBUSREG;3746 /** Pointer to a PCI bus registration structure. */3747 typedef PDMPCIBUSREG *PPDMPCIBUSREG;3748 3749 /** Current PDMPCIBUSREG version number. */3750 #define PDM_PCIBUSREG_VERSION 0xd00200003751 3752 /**3753 * PCI Bus GC helpers.3754 */3755 typedef struct PDMPCIHLPGC3756 {3757 /** Structure version. PDM_PCIHLPGC_VERSION defines the current version. */3758 uint32_t u32Version;3759 3760 /**3761 * Set an ISA IRQ.3762 *3763 * @param pDevIns PCI device instance.3764 * @param iIrq IRQ number to set.3765 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.3766 * @thread EMT only.3767 */3768 DECLGCCALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));3769 3770 /**3771 * Set an I/O-APIC IRQ.3772 *3773 * @param pDevIns PCI device instance.3774 * @param iIrq IRQ number to set.3775 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.3776 * @thread EMT only.3777 */3778 DECLGCCALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));3779 3780 #ifdef VBOX_WITH_PDM_LOCK3781 /**3782 * Acquires the PDM lock.3783 *3784 * @returns VINF_SUCCESS on success.3785 * @returns rc if we failed to acquire the lock.3786 * @param pDevIns The PCI device instance.3787 * @param rc What to return if we fail to acquire the lock.3788 */3789 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));3790 3791 /**3792 * Releases the PDM lock.3793 *3794 * @param pDevIns The PCI device instance.3795 */3796 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));3797 #endif3798 /** Just a safety precaution. */3799 uint32_t u32TheEnd;3800 } PDMPCIHLPGC;3801 /** Pointer to PCI helpers. */3802 typedef GCPTRTYPE(PDMPCIHLPGC *) PPDMPCIHLPGC;3803 /** Pointer to const PCI helpers. */3804 typedef GCPTRTYPE(const PDMPCIHLPGC *) PCPDMPCIHLPGC;3805 3806 /** Current PDMPCIHLPR3 version number. */3807 #define PDM_PCIHLPGC_VERSION 0xe10100003808 3809 3810 /**3811 * PCI Bus R0 helpers.3812 */3813 typedef struct PDMPCIHLPR03814 {3815 /** Structure version. PDM_PCIHLPR0_VERSION defines the current version. */3816 uint32_t u32Version;3817 3818 /**3819 * Set an ISA IRQ.3820 *3821 * @param pDevIns PCI device instance.3822 * @param iIrq IRQ number to set.3823 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.3824 * @thread EMT only.3825 */3826 DECLR0CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));3827 3828 /**3829 * Set an I/O-APIC IRQ.3830 *3831 * @param pDevIns PCI device instance.3832 * @param iIrq IRQ number to set.3833 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.3834 * @thread EMT only.3835 */3836 DECLR0CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));3837 3838 #ifdef VBOX_WITH_PDM_LOCK3839 /**3840 * Acquires the PDM lock.3841 *3842 * @returns VINF_SUCCESS on success.3843 * @returns rc if we failed to acquire the lock.3844 * @param pDevIns The PCI device instance.3845 * @param rc What to return if we fail to acquire the lock.3846 */3847 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));3848 3849 /**3850 * Releases the PDM lock.3851 *3852 * @param pDevIns The PCI device instance.3853 */3854 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));3855 #endif3856 3857 /** Just a safety precaution. */3858 uint32_t u32TheEnd;3859 } PDMPCIHLPR0;3860 /** Pointer to PCI helpers. */3861 typedef R0PTRTYPE(PDMPCIHLPR0 *) PPDMPCIHLPR0;3862 /** Pointer to const PCI helpers. */3863 typedef R0PTRTYPE(const PDMPCIHLPR0 *) PCPDMPCIHLPR0;3864 3865 /** Current PDMPCIHLPR0 version number. */3866 #define PDM_PCIHLPR0_VERSION 0xe10100003867 3868 /**3869 * PCI device helpers.3870 */3871 typedef struct PDMPCIHLPR33872 {3873 /** Structure version. PDM_PCIHLPR3_VERSION defines the current version. */3874 uint32_t u32Version;3875 3876 /**3877 * Set an ISA IRQ.3878 *3879 * @param pDevIns The PCI device instance.3880 * @param iIrq IRQ number to set.3881 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.3882 * @thread EMT only.3883 */3884 DECLR3CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));3885 3886 /**3887 * Set an I/O-APIC IRQ.3888 *3889 * @param pDevIns The PCI device instance.3890 * @param iIrq IRQ number to set.3891 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.3892 * @thread EMT only.3893 */3894 DECLR3CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));3895 3896 #ifdef VBOX_WITH_PDM_LOCK3897 /**3898 * Acquires the PDM lock.3899 *3900 * @returns VINF_SUCCESS on success.3901 * @returns Fatal error on failure.3902 * @param pDevIns The PCI device instance.3903 * @param rc Dummy for making the interface identical to the GC and R0 versions.3904 */3905 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));3906 3907 /**3908 * Releases the PDM lock.3909 *3910 * @param pDevIns The PCI device instance.3911 */3912 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));3913 #endif3914 3915 /**3916 * Gets the address of the GC PCI Bus helpers.3917 *3918 * This should be called at both construction and relocation time3919 * to obtain the correct address of the GC helpers.3920 *3921 * @returns GC pointer to the PCI Bus helpers.3922 * @param pDevIns Device instance of the PCI Bus.3923 * @thread EMT only.3924 */3925 DECLR3CALLBACKMEMBER(PCPDMPCIHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));3926 3927 /**3928 * Gets the address of the R0 PCI Bus helpers.3929 *3930 * This should be called at both construction and relocation time3931 * to obtain the correct address of the GC helpers.3932 *3933 * @returns R0 pointer to the PCI Bus helpers.3934 * @param pDevIns Device instance of the PCI Bus.3935 * @thread EMT only.3936 */3937 DECLR3CALLBACKMEMBER(PCPDMPCIHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));3938 3939 /** Just a safety precaution. */3940 uint32_t u32TheEnd;3941 } PDMPCIHLPR3;3942 /** Pointer to PCI helpers. */3943 typedef HCPTRTYPE(PDMPCIHLPR3 *) PPDMPCIHLPR3;3944 /** Pointer to const PCI helpers. */3945 typedef HCPTRTYPE(const PDMPCIHLPR3 *) PCPDMPCIHLPR3;3946 3947 /** Current PDMPCIHLPR3 version number. */3948 #define PDM_PCIHLPR3_VERSION 0xf10100003949 3950 3951 /**3952 * Programmable Interrupt Controller registration structure.3953 */3954 typedef struct PDMPICREG3955 {3956 /** Structure version number. PDM_PICREG_VERSION defines the current version. */3957 uint32_t u32Version;3958 3959 /**3960 * Set the an IRQ.3961 *3962 * @param pDevIns Device instance of the PIC.3963 * @param iIrq IRQ number to set.3964 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.3965 */3966 DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, int iIrq, int iLevel));3967 3968 /**3969 * Get a pending interrupt.3970 *3971 * @returns Pending interrupt number.3972 * @param pDevIns Device instance of the PIC.3973 */3974 DECLR3CALLBACKMEMBER(int, pfnGetInterruptHC,(PPDMDEVINS pDevIns));3975 3976 /** The name of the GC SetIrq entry point. */3977 const char *pszSetIrqGC;3978 /** The name of the GC GetInterrupt entry point. */3979 const char *pszGetInterruptGC;3980 3981 /** The name of the R0 SetIrq entry point. */3982 const char *pszSetIrqR0;3983 /** The name of the R0 GetInterrupt entry point. */3984 const char *pszGetInterruptR0;3985 } PDMPICREG;3986 /** Pointer to a PIC registration structure. */3987 typedef PDMPICREG *PPDMPICREG;3988 3989 /** Current PDMPICREG version number. */3990 #define PDM_PICREG_VERSION 0xe00200003991 3992 /**3993 * PIC GC helpers.3994 */3995 typedef struct PDMPICHLPGC3996 {3997 /** Structure version. PDM_PICHLPGC_VERSION defines the current version. */3998 uint32_t u32Version;3999 4000 /**4001 * Set the interrupt force action flag.4002 *4003 * @param pDevIns Device instance of the PIC.4004 */4005 DECLGCCALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));4006 4007 /**4008 * Clear the interrupt force action flag.4009 *4010 * @param pDevIns Device instance of the PIC.4011 */4012 DECLGCCALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));4013 4014 #ifdef VBOX_WITH_PDM_LOCK4015 /**4016 * Acquires the PDM lock.4017 *4018 * @returns VINF_SUCCESS on success.4019 * @returns rc if we failed to acquire the lock.4020 * @param pDevIns The PIC device instance.4021 * @param rc What to return if we fail to acquire the lock.4022 */4023 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));4024 4025 /**4026 * Releases the PDM lock.4027 *4028 * @param pDevIns The PIC device instance.4029 */4030 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));4031 #endif4032 /** Just a safety precaution. */4033 uint32_t u32TheEnd;4034 } PDMPICHLPGC;4035 4036 /** Pointer to PIC GC helpers. */4037 typedef GCPTRTYPE(PDMPICHLPGC *) PPDMPICHLPGC;4038 /** Pointer to const PIC GC helpers. */4039 typedef GCPTRTYPE(const PDMPICHLPGC *) PCPDMPICHLPGC;4040 4041 /** Current PDMPICHLPGC version number. */4042 #define PDM_PICHLPGC_VERSION 0xfc0100004043 4044 4045 /**4046 * PIC R0 helpers.4047 */4048 typedef struct PDMPICHLPR04049 {4050 /** Structure version. PDM_PICHLPR0_VERSION defines the current version. */4051 uint32_t u32Version;4052 4053 /**4054 * Set the interrupt force action flag.4055 *4056 * @param pDevIns Device instance of the PIC.4057 */4058 DECLR0CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));4059 4060 /**4061 * Clear the interrupt force action flag.4062 *4063 * @param pDevIns Device instance of the PIC.4064 */4065 DECLR0CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));4066 4067 #ifdef VBOX_WITH_PDM_LOCK4068 /**4069 * Acquires the PDM lock.4070 *4071 * @returns VINF_SUCCESS on success.4072 * @returns rc if we failed to acquire the lock.4073 * @param pDevIns The PIC device instance.4074 * @param rc What to return if we fail to acquire the lock.4075 */4076 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));4077 4078 /**4079 * Releases the PDM lock.4080 *4081 * @param pDevIns The PCI device instance.4082 */4083 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));4084 #endif4085 4086 /** Just a safety precaution. */4087 uint32_t u32TheEnd;4088 } PDMPICHLPR0;4089 4090 /** Pointer to PIC R0 helpers. */4091 typedef R0PTRTYPE(PDMPICHLPR0 *) PPDMPICHLPR0;4092 /** Pointer to const PIC R0 helpers. */4093 typedef R0PTRTYPE(const PDMPICHLPR0 *) PCPDMPICHLPR0;4094 4095 /** Current PDMPICHLPR0 version number. */4096 #define PDM_PICHLPR0_VERSION 0xfc0100004097 4098 /**4099 * PIC HC helpers.4100 */4101 typedef struct PDMPICHLPR34102 {4103 /** Structure version. PDM_PICHLP_VERSION defines the current version. */4104 uint32_t u32Version;4105 4106 /**4107 * Set the interrupt force action flag.4108 *4109 * @param pDevIns Device instance of the PIC.4110 */4111 DECLR3CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));4112 4113 /**4114 * Clear the interrupt force action flag.4115 *4116 * @param pDevIns Device instance of the PIC.4117 */4118 DECLR3CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));4119 4120 #ifdef VBOX_WITH_PDM_LOCK4121 /**4122 * Acquires the PDM lock.4123 *4124 * @returns VINF_SUCCESS on success.4125 * @returns Fatal error on failure.4126 * @param pDevIns The PIC device instance.4127 * @param rc Dummy for making the interface identical to the GC and R0 versions.4128 */4129 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));4130 4131 /**4132 * Releases the PDM lock.4133 *4134 * @param pDevIns The PIC device instance.4135 */4136 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));4137 #endif4138 4139 /**4140 * Gets the address of the GC PIC helpers.4141 *4142 * This should be called at both construction and relocation time4143 * to obtain the correct address of the GC helpers.4144 *4145 * @returns GC pointer to the PIC helpers.4146 * @param pDevIns Device instance of the PIC.4147 */4148 DECLR3CALLBACKMEMBER(PCPDMPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));4149 4150 /**4151 * Gets the address of the R0 PIC helpers.4152 *4153 * This should be called at both construction and relocation time4154 * to obtain the correct address of the GC helpers.4155 *4156 * @returns R0 pointer to the PIC helpers.4157 * @param pDevIns Device instance of the PIC.4158 */4159 DECLR3CALLBACKMEMBER(PCPDMPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));4160 4161 /** Just a safety precaution. */4162 uint32_t u32TheEnd;4163 } PDMPICHLPR3;4164 4165 /** Pointer to PIC HC helpers. */4166 typedef HCPTRTYPE(PDMPICHLPR3 *) PPDMPICHLPR3;4167 /** Pointer to const PIC HC helpers. */4168 typedef HCPTRTYPE(const PDMPICHLPR3 *) PCPDMPICHLPR3;4169 4170 /** Current PDMPICHLPR3 version number. */4171 #define PDM_PICHLPR3_VERSION 0xf00100004172 4173 4174 4175 /**4176 * Advanced Programmable Interrupt Controller registration structure.4177 */4178 typedef struct PDMAPICREG4179 {4180 /** Structure version number. PDM_APICREG_VERSION defines the current version. */4181 uint32_t u32Version;4182 4183 /**4184 * Get a pending interrupt.4185 *4186 * @returns Pending interrupt number.4187 * @param pDevIns Device instance of the APIC.4188 */4189 DECLR3CALLBACKMEMBER(int, pfnGetInterruptHC,(PPDMDEVINS pDevIns));4190 4191 /**4192 * Set the APIC base.4193 *4194 * @param pDevIns Device instance of the APIC.4195 * @param u64Base The new base.4196 */4197 DECLR3CALLBACKMEMBER(void, pfnSetBaseHC,(PPDMDEVINS pDevIns, uint64_t u64Base));4198 4199 /**4200 * Get the APIC base.4201 *4202 * @returns Current base.4203 * @param pDevIns Device instance of the APIC.4204 */4205 DECLR3CALLBACKMEMBER(uint64_t, pfnGetBaseHC,(PPDMDEVINS pDevIns));4206 4207 /**4208 * Set the TPR (task priority register?).4209 *4210 * @param pDevIns Device instance of the APIC.4211 * @param u8TPR The new TPR.4212 */4213 DECLR3CALLBACKMEMBER(void, pfnSetTPRHC,(PPDMDEVINS pDevIns, uint8_t u8TPR));4214 4215 /**4216 * Get the TPR (task priority register?).4217 *4218 * @returns The current TPR.4219 * @param pDevIns Device instance of the APIC.4220 */4221 DECLR3CALLBACKMEMBER(uint8_t, pfnGetTPRHC,(PPDMDEVINS pDevIns));4222 4223 /**4224 * Private interface between the IOAPIC and APIC.4225 *4226 * This is a low-level, APIC/IOAPIC implementation specific interface4227 * which is registered with PDM only because it makes life so much4228 * simpler right now (GC bits). This is a bad bad hack! The correct4229 * way of doing this would involve some way of querying GC interfaces4230 * and relocating them. Perhaps doing some kind of device init in GC...4231 *4232 * @returns The current TPR.4233 * @param pDevIns Device instance of the APIC.4234 * @param u8Dest See APIC implementation.4235 * @param u8DestMode See APIC implementation.4236 * @param u8DeliveryMode See APIC implementation.4237 * @param iVector See APIC implementation.4238 * @param u8Polarity See APIC implementation.4239 * @param u8TriggerMode See APIC implementation.4240 */4241 DECLR3CALLBACKMEMBER(void, pfnBusDeliverHC,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,4242 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));4243 4244 /** The name of the GC GetInterrupt entry point. */4245 const char *pszGetInterruptGC;4246 /** The name of the GC SetBase entry point. */4247 const char *pszSetBaseGC;4248 /** The name of the GC GetBase entry point. */4249 const char *pszGetBaseGC;4250 /** The name of the GC SetTPR entry point. */4251 const char *pszSetTPRGC;4252 /** The name of the GC GetTPR entry point. */4253 const char *pszGetTPRGC;4254 /** The name of the GC BusDeliver entry point. */4255 const char *pszBusDeliverGC;4256 4257 /** The name of the R0 GetInterrupt entry point. */4258 const char *pszGetInterruptR0;4259 /** The name of the R0 SetBase entry point. */4260 const char *pszSetBaseR0;4261 /** The name of the R0 GetBase entry point. */4262 const char *pszGetBaseR0;4263 /** The name of the R0 SetTPR entry point. */4264 const char *pszSetTPRR0;4265 /** The name of the R0 GetTPR entry point. */4266 const char *pszGetTPRR0;4267 /** The name of the R0 BusDeliver entry point. */4268 const char *pszBusDeliverR0;4269 4270 } PDMAPICREG;4271 /** Pointer to an APIC registration structure. */4272 typedef PDMAPICREG *PPDMAPICREG;4273 4274 /** Current PDMAPICREG version number. */4275 #define PDM_APICREG_VERSION 0x700100004276 4277 4278 /**4279 * APIC GC helpers.4280 */4281 typedef struct PDMAPICHLPGC4282 {4283 /** Structure version. PDM_APICHLPGC_VERSION defines the current version. */4284 uint32_t u32Version;4285 4286 /**4287 * Set the interrupt force action flag.4288 *4289 * @param pDevIns Device instance of the APIC.4290 */4291 DECLGCCALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));4292 4293 /**4294 * Clear the interrupt force action flag.4295 *4296 * @param pDevIns Device instance of the APIC.4297 */4298 DECLGCCALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));4299 4300 /**4301 * Sets or clears the APIC bit in the CPUID feature masks.4302 *4303 * @param pDevIns Device instance of the APIC.4304 * @param fEnabled If true the bit is set, else cleared.4305 */4306 DECLGCCALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));4307 4308 #ifdef VBOX_WITH_PDM_LOCK4309 /**4310 * Acquires the PDM lock.4311 *4312 * @returns VINF_SUCCESS on success.4313 * @returns rc if we failed to acquire the lock.4314 * @param pDevIns The APIC device instance.4315 * @param rc What to return if we fail to acquire the lock.4316 */4317 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));4318 4319 /**4320 * Releases the PDM lock.4321 *4322 * @param pDevIns The APIC device instance.4323 */4324 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));4325 #endif4326 /** Just a safety precaution. */4327 uint32_t u32TheEnd;4328 } PDMAPICHLPGC;4329 /** Pointer to APIC GC helpers. */4330 typedef GCPTRTYPE(PDMAPICHLPGC *) PPDMAPICHLPGC;4331 /** Pointer to const APIC helpers. */4332 typedef GCPTRTYPE(const PDMAPICHLPGC *) PCPDMAPICHLPGC;4333 4334 /** Current PDMAPICHLPGC version number. */4335 #define PDM_APICHLPGC_VERSION 0x600100004336 4337 4338 /**4339 * APIC R0 helpers.4340 */4341 typedef struct PDMAPICHLPR04342 {4343 /** Structure version. PDM_APICHLPR0_VERSION defines the current version. */4344 uint32_t u32Version;4345 4346 /**4347 * Set the interrupt force action flag.4348 *4349 * @param pDevIns Device instance of the APIC.4350 */4351 DECLR0CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));4352 4353 /**4354 * Clear the interrupt force action flag.4355 *4356 * @param pDevIns Device instance of the APIC.4357 */4358 DECLR0CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));4359 4360 /**4361 * Sets or clears the APIC bit in the CPUID feature masks.4362 *4363 * @param pDevIns Device instance of the APIC.4364 * @param fEnabled If true the bit is set, else cleared.4365 */4366 DECLR0CALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));4367 4368 #ifdef VBOX_WITH_PDM_LOCK4369 /**4370 * Acquires the PDM lock.4371 *4372 * @returns VINF_SUCCESS on success.4373 * @returns rc if we failed to acquire the lock.4374 * @param pDevIns The APIC device instance.4375 * @param rc What to return if we fail to acquire the lock.4376 */4377 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));4378 4379 /**4380 * Releases the PDM lock.4381 *4382 * @param pDevIns The APIC device instance.4383 */4384 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));4385 #endif4386 4387 /** Just a safety precaution. */4388 uint32_t u32TheEnd;4389 } PDMAPICHLPR0;4390 /** Pointer to APIC GC helpers. */4391 typedef GCPTRTYPE(PDMAPICHLPR0 *) PPDMAPICHLPR0;4392 /** Pointer to const APIC helpers. */4393 typedef R0PTRTYPE(const PDMAPICHLPR0 *) PCPDMAPICHLPR0;4394 4395 /** Current PDMAPICHLPR0 version number. */4396 #define PDM_APICHLPR0_VERSION 0x600100004397 4398 /**4399 * APIC HC helpers.4400 */4401 typedef struct PDMAPICHLPR34402 {4403 /** Structure version. PDM_APICHLPR3_VERSION defines the current version. */4404 uint32_t u32Version;4405 4406 /**4407 * Set the interrupt force action flag.4408 *4409 * @param pDevIns Device instance of the APIC.4410 */4411 DECLR3CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));4412 4413 /**4414 * Clear the interrupt force action flag.4415 *4416 * @param pDevIns Device instance of the APIC.4417 */4418 DECLR3CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));4419 4420 /**4421 * Sets or clears the APIC bit in the CPUID feature masks.4422 *4423 * @param pDevIns Device instance of the APIC.4424 * @param fEnabled If true the bit is set, else cleared.4425 */4426 DECLR3CALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));4427 4428 #ifdef VBOX_WITH_PDM_LOCK4429 /**4430 * Acquires the PDM lock.4431 *4432 * @returns VINF_SUCCESS on success.4433 * @returns Fatal error on failure.4434 * @param pDevIns The APIC device instance.4435 * @param rc Dummy for making the interface identical to the GC and R0 versions.4436 */4437 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));4438 4439 /**4440 * Releases the PDM lock.4441 *4442 * @param pDevIns The APIC device instance.4443 */4444 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));4445 #endif4446 4447 /**4448 * Gets the address of the GC APIC helpers.4449 *4450 * This should be called at both construction and relocation time4451 * to obtain the correct address of the GC helpers.4452 *4453 * @returns GC pointer to the APIC helpers.4454 * @param pDevIns Device instance of the APIC.4455 */4456 DECLR3CALLBACKMEMBER(PCPDMAPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));4457 4458 /**4459 * Gets the address of the R0 APIC helpers.4460 *4461 * This should be called at both construction and relocation time4462 * to obtain the correct address of the R0 helpers.4463 *4464 * @returns R0 pointer to the APIC helpers.4465 * @param pDevIns Device instance of the APIC.4466 */4467 DECLR3CALLBACKMEMBER(PCPDMAPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));4468 4469 /** Just a safety precaution. */4470 uint32_t u32TheEnd;4471 } PDMAPICHLPR3;4472 /** Pointer to APIC helpers. */4473 typedef HCPTRTYPE(PDMAPICHLPR3 *) PPDMAPICHLPR3;4474 /** Pointer to const APIC helpers. */4475 typedef HCPTRTYPE(const PDMAPICHLPR3 *) PCPDMAPICHLPR3;4476 4477 /** Current PDMAPICHLP version number. */4478 #define PDM_APICHLPR3_VERSION 0xfd0100004479 4480 4481 /**4482 * I/O APIC registration structure.4483 */4484 typedef struct PDMIOAPICREG4485 {4486 /** Struct version+magic number (PDM_IOAPICREG_VERSION). */4487 uint32_t u32Version;4488 4489 /**4490 * Set the an IRQ.4491 *4492 * @param pDevIns Device instance of the I/O APIC.4493 * @param iIrq IRQ number to set.4494 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.4495 */4496 DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, int iIrq, int iLevel));4497 4498 /** The name of the GC SetIrq entry point. */4499 const char *pszSetIrqGC;4500 4501 /** The name of the R0 SetIrq entry point. */4502 const char *pszSetIrqR0;4503 } PDMIOAPICREG;4504 /** Pointer to an APIC registration structure. */4505 typedef PDMIOAPICREG *PPDMIOAPICREG;4506 4507 /** Current PDMAPICREG version number. */4508 #define PDM_IOAPICREG_VERSION 0x500100004509 4510 4511 /**4512 * IOAPIC GC helpers.4513 */4514 typedef struct PDMIOAPICHLPGC4515 {4516 /** Structure version. PDM_IOAPICHLPGC_VERSION defines the current version. */4517 uint32_t u32Version;4518 4519 /**4520 * Private interface between the IOAPIC and APIC.4521 *4522 * See comments about this hack on PDMAPICREG::pfnBusDeliverHC.4523 *4524 * @returns The current TPR.4525 * @param pDevIns Device instance of the IOAPIC.4526 * @param u8Dest See APIC implementation.4527 * @param u8DestMode See APIC implementation.4528 * @param u8DeliveryMode See APIC implementation.4529 * @param iVector See APIC implementation.4530 * @param u8Polarity See APIC implementation.4531 * @param u8TriggerMode See APIC implementation.4532 */4533 DECLGCCALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,4534 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));4535 4536 #ifdef VBOX_WITH_PDM_LOCK4537 /**4538 * Acquires the PDM lock.4539 *4540 * @returns VINF_SUCCESS on success.4541 * @returns rc if we failed to acquire the lock.4542 * @param pDevIns The IOAPIC device instance.4543 * @param rc What to return if we fail to acquire the lock.4544 */4545 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));4546 4547 /**4548 * Releases the PDM lock.4549 *4550 * @param pDevIns The IOAPIC device instance.4551 */4552 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));4553 #endif4554 4555 /** Just a safety precaution. */4556 uint32_t u32TheEnd;4557 } PDMIOAPICHLPGC;4558 /** Pointer to IOAPIC GC helpers. */4559 typedef GCPTRTYPE(PDMAPICHLPGC *)PPDMIOAPICHLPGC;4560 /** Pointer to const IOAPIC helpers. */4561 typedef GCPTRTYPE(const PDMIOAPICHLPGC *) PCPDMIOAPICHLPGC;4562 4563 /** Current PDMIOAPICHLPGC version number. */4564 #define PDM_IOAPICHLPGC_VERSION 0xfe0100004565 4566 4567 /**4568 * IOAPIC R0 helpers.4569 */4570 typedef struct PDMIOAPICHLPR04571 {4572 /** Structure version. PDM_IOAPICHLPR0_VERSION defines the current version. */4573 uint32_t u32Version;4574 4575 /**4576 * Private interface between the IOAPIC and APIC.4577 *4578 * See comments about this hack on PDMAPICREG::pfnBusDeliverHC.4579 *4580 * @returns The current TPR.4581 * @param pDevIns Device instance of the IOAPIC.4582 * @param u8Dest See APIC implementation.4583 * @param u8DestMode See APIC implementation.4584 * @param u8DeliveryMode See APIC implementation.4585 * @param iVector See APIC implementation.4586 * @param u8Polarity See APIC implementation.4587 * @param u8TriggerMode See APIC implementation.4588 */4589 DECLR0CALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,4590 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));4591 4592 #ifdef VBOX_WITH_PDM_LOCK4593 /**4594 * Acquires the PDM lock.4595 *4596 * @returns VINF_SUCCESS on success.4597 * @returns rc if we failed to acquire the lock.4598 * @param pDevIns The IOAPIC device instance.4599 * @param rc What to return if we fail to acquire the lock.4600 */4601 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));4602 4603 /**4604 * Releases the PDM lock.4605 *4606 * @param pDevIns The IOAPIC device instance.4607 */4608 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));4609 #endif4610 4611 /** Just a safety precaution. */4612 uint32_t u32TheEnd;4613 } PDMIOAPICHLPR0;4614 /** Pointer to IOAPIC R0 helpers. */4615 typedef R0PTRTYPE(PDMAPICHLPGC *) PPDMIOAPICHLPR0;4616 /** Pointer to const IOAPIC helpers. */4617 typedef R0PTRTYPE(const PDMIOAPICHLPR0 *) PCPDMIOAPICHLPR0;4618 4619 /** Current PDMIOAPICHLPR0 version number. */4620 #define PDM_IOAPICHLPR0_VERSION 0xfe0100004621 4622 /**4623 * IOAPIC HC helpers.4624 */4625 typedef struct PDMIOAPICHLPR34626 {4627 /** Structure version. PDM_IOAPICHLPR3_VERSION defines the current version. */4628 uint32_t u32Version;4629 4630 /**4631 * Private interface between the IOAPIC and APIC.4632 *4633 * See comments about this hack on PDMAPICREG::pfnBusDeliverHC.4634 *4635 * @returns The current TPR.4636 * @param pDevIns Device instance of the IOAPIC.4637 * @param u8Dest See APIC implementation.4638 * @param u8DestMode See APIC implementation.4639 * @param u8DeliveryMode See APIC implementation.4640 * @param iVector See APIC implementation.4641 * @param u8Polarity See APIC implementation.4642 * @param u8TriggerMode See APIC implementation.4643 */4644 DECLR3CALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,4645 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));4646 4647 #ifdef VBOX_WITH_PDM_LOCK4648 /**4649 * Acquires the PDM lock.4650 *4651 * @returns VINF_SUCCESS on success.4652 * @returns Fatal error on failure.4653 * @param pDevIns The IOAPIC device instance.4654 * @param rc Dummy for making the interface identical to the GC and R0 versions.4655 */4656 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));4657 4658 /**4659 * Releases the PDM lock.4660 *4661 * @param pDevIns The IOAPIC device instance.4662 */4663 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));4664 #endif4665 4666 /**4667 * Gets the address of the GC IOAPIC helpers.4668 *4669 * This should be called at both construction and relocation time4670 * to obtain the correct address of the GC helpers.4671 *4672 * @returns GC pointer to the IOAPIC helpers.4673 * @param pDevIns Device instance of the IOAPIC.4674 */4675 DECLR3CALLBACKMEMBER(PCPDMIOAPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));4676 4677 /**4678 * Gets the address of the R0 IOAPIC helpers.4679 *4680 * This should be called at both construction and relocation time4681 * to obtain the correct address of the R0 helpers.4682 *4683 * @returns R0 pointer to the IOAPIC helpers.4684 * @param pDevIns Device instance of the IOAPIC.4685 */4686 DECLR3CALLBACKMEMBER(PCPDMIOAPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));4687 4688 /** Just a safety precaution. */4689 uint32_t u32TheEnd;4690 } PDMIOAPICHLPR3;4691 /** Pointer to IOAPIC HC helpers. */4692 typedef HCPTRTYPE(PDMIOAPICHLPR3 *) PPDMIOAPICHLPR3;4693 /** Pointer to const IOAPIC helpers. */4694 typedef HCPTRTYPE(const PDMIOAPICHLPR3 *) PCPDMIOAPICHLPR3;4695 4696 /** Current PDMIOAPICHLPR3 version number. */4697 #define PDM_IOAPICHLPR3_VERSION 0xff0100004698 4699 4700 4701 #ifdef IN_RING34702 4703 /**4704 * DMA Transfer Handler.4705 *4706 * @returns Number of bytes transferred.4707 * @param pDevIns Device instance of the DMA.4708 * @param pvUser User pointer.4709 * @param uChannel Channel number.4710 * @param off DMA position.4711 * @param cb Block size.4712 */4713 typedef DECLCALLBACK(uint32_t) FNDMATRANSFERHANDLER(PPDMDEVINS pDevIns, void *pvUser, unsigned uChannel, uint32_t off, uint32_t cb);4714 /** Pointer to a FNDMATRANSFERHANDLER(). */4715 typedef FNDMATRANSFERHANDLER *PFNDMATRANSFERHANDLER;4716 4717 /**4718 * DMA Controller registration structure.4719 */4720 typedef struct PDMDMAREG4721 {4722 /** Structure version number. PDM_DMACREG_VERSION defines the current version. */4723 uint32_t u32Version;4724 4725 /**4726 * Execute pending transfers.4727 *4728 * @returns A more work indiciator. I.e. 'true' if there is more to be done, and 'false' if all is done.4729 * @param pDevIns Device instance of the DMAC.4730 */4731 DECLR3CALLBACKMEMBER(bool, pfnRun,(PPDMDEVINS pDevIns));4732 4733 /**4734 * Register transfer function for DMA channel.4735 *4736 * @param pDevIns Device instance of the DMAC.4737 * @param uChannel Channel number.4738 * @param pfnTransferHandler Device specific transfer function.4739 * @param pvUSer User pointer to be passed to the callback.4740 */4741 DECLR3CALLBACKMEMBER(void, pfnRegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));4742 4743 /**4744 * Read memory4745 *4746 * @returns Number of bytes read.4747 * @param pDevIns Device instance of the DMAC.4748 * @param pvBuffer Pointer to target buffer.4749 * @param off DMA position.4750 * @param cbBlock Block size.4751 */4752 DECLR3CALLBACKMEMBER(uint32_t, pfnReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock));4753 4754 /**4755 * Write memory4756 *4757 * @returns Number of bytes written.4758 * @param pDevIns Device instance of the DMAC.4759 * @param pvBuffer Memory to write.4760 * @param off DMA position.4761 * @param cbBlock Block size.4762 */4763 DECLR3CALLBACKMEMBER(uint32_t, pfnWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock));4764 4765 /**4766 * Set the DREQ line.4767 *4768 * @param pDevIns Device instance of the DMAC.4769 * @param uChannel Channel number.4770 * @param uLevel Level of the line.4771 */4772 DECLR3CALLBACKMEMBER(void, pfnSetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));4773 4774 /**4775 * Get channel mode4776 *4777 * @returns Channel mode.4778 * @param pDevIns Device instance of the DMAC.4779 * @param uChannel Channel number.4780 */4781 DECLR3CALLBACKMEMBER(uint8_t, pfnGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));4782 4783 } PDMDMACREG;4784 /** Pointer to a DMAC registration structure. */4785 typedef PDMDMACREG *PPDMDMACREG;4786 4787 /** Current PDMDMACREG version number. */4788 #define PDM_DMACREG_VERSION 0xf50100004789 4790 4791 /**4792 * DMA Controller device helpers.4793 */4794 typedef struct PDMDMACHLP4795 {4796 /** Structure version. PDM_DMACHLP_VERSION defines the current version. */4797 uint32_t u32Version;4798 4799 /* to-be-defined */4800 4801 } PDMDMACHLP;4802 /** Pointer to DMAC helpers. */4803 typedef PDMDMACHLP *PPDMDMACHLP;4804 /** Pointer to const DMAC helpers. */4805 typedef const PDMDMACHLP *PCPDMDMACHLP;4806 4807 /** Current PDMDMACHLP version number. */4808 #define PDM_DMACHLP_VERSION 0xf60100004809 4810 #endif /* IN_RING3 */4811 4812 4813 4814 /**4815 * RTC registration structure.4816 */4817 typedef struct PDMRTCREG4818 {4819 /** Structure version number. PDM_RTCREG_VERSION defines the current version. */4820 uint32_t u32Version;4821 uint32_t u32Alignment; /**< structure size alignment. */4822 4823 /**4824 * Write to a CMOS register and update the checksum if necessary.4825 *4826 * @returns VBox status code.4827 * @param pDevIns Device instance of the RTC.4828 * @param iReg The CMOS register index.4829 * @param u8Value The CMOS register value.4830 */4831 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));4832 4833 /**4834 * Read a CMOS register.4835 *4836 * @returns VBox status code.4837 * @param pDevIns Device instance of the RTC.4838 * @param iReg The CMOS register index.4839 * @param pu8Value Where to store the CMOS register value.4840 */4841 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));4842 4843 } PDMRTCREG;4844 /** Pointer to a RTC registration structure. */4845 typedef PDMRTCREG *PPDMRTCREG;4846 /** Pointer to a const RTC registration structure. */4847 typedef const PDMRTCREG *PCPDMRTCREG;4848 4849 /** Current PDMRTCREG version number. */4850 #define PDM_RTCREG_VERSION 0xfa0100004851 4852 4853 /**4854 * RTC device helpers.4855 */4856 typedef struct PDMRTCHLP4857 {4858 /** Structure version. PDM_RTCHLP_VERSION defines the current version. */4859 uint32_t u32Version;4860 4861 /* to-be-defined */4862 4863 } PDMRTCHLP;4864 /** Pointer to RTC helpers. */4865 typedef PDMRTCHLP *PPDMRTCHLP;4866 /** Pointer to const RTC helpers. */4867 typedef const PDMRTCHLP *PCPDMRTCHLP;4868 4869 /** Current PDMRTCHLP version number. */4870 #define PDM_RTCHLP_VERSION 0xf60100004871 4872 4873 4874 #ifdef IN_RING34875 4876 /**4877 * PDM Device API.4878 */4879 typedef struct PDMDEVHLP4880 {4881 /** Structure version. PDM_DEVHLP_VERSION defines the current version. */4882 uint32_t u32Version;4883 4884 /**4885 * Register a number of I/O ports with a device.4886 *4887 * These callbacks are of course for the host context (HC).4888 * Register HC handlers before guest context (GC) handlers! There must be a4889 * HC handler for every GC handler!4890 *4891 * @returns VBox status.4892 * @param pDevIns The device instance to register the ports with.4893 * @param Port First port number in the range.4894 * @param cPorts Number of ports to register.4895 * @param pvUser User argument.4896 * @param pfnOut Pointer to function which is gonna handle OUT operations.4897 * @param pfnIn Pointer to function which is gonna handle IN operations.4898 * @param pfnOutStr Pointer to function which is gonna handle string OUT operations.4899 * @param pfnInStr Pointer to function which is gonna handle string IN operations.4900 * @param pszDesc Pointer to description string. This must not be freed.4901 */4902 DECLR3CALLBACKMEMBER(int, pfnIOPortRegister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTHCPTR pvUser,4903 PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,4904 PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc));4905 4906 /**4907 * Register a number of I/O ports with a device for GC.4908 *4909 * These callbacks are for the host context (GC).4910 * Register host context (HC) handlers before guest context handlers! There must be a4911 * HC handler for every GC handler!4912 *4913 * @returns VBox status.4914 * @param pDevIns The device instance to register the ports with and which GC module4915 * to resolve the names against.4916 * @param Port First port number in the range.4917 * @param cPorts Number of ports to register.4918 * @param pvUser User argument.4919 * @param pszOut Name of the GC function which is gonna handle OUT operations.4920 * @param pszIn Name of the GC function which is gonna handle IN operations.4921 * @param pszOutStr Name of the GC function which is gonna handle string OUT operations.4922 * @param pszInStr Name of the GC function which is gonna handle string IN operations.4923 * @param pszDesc Pointer to description string. This must not be freed.4924 */4925 DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterGC,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTGCPTR pvUser,4926 const char *pszOut, const char *pszIn,4927 const char *pszOutStr, const char *pszInStr, const char *pszDesc));4928 4929 /**4930 * Register a number of I/O ports with a device.4931 *4932 * These callbacks are of course for the ring-0 host context (R0).4933 * Register R3 (HC) handlers before R0 (R0) handlers! There must be a R3 (HC) handler for every R0 handler!4934 *4935 * @returns VBox status.4936 * @param pDevIns The device instance to register the ports with.4937 * @param Port First port number in the range.4938 * @param cPorts Number of ports to register.4939 * @param pvUser User argument. (if pointer, then it must be in locked memory!)4940 * @param pszOut Name of the R0 function which is gonna handle OUT operations.4941 * @param pszIn Name of the R0 function which is gonna handle IN operations.4942 * @param pszOutStr Name of the R0 function which is gonna handle string OUT operations.4943 * @param pszInStr Name of the R0 function which is gonna handle string IN operations.4944 * @param pszDesc Pointer to description string. This must not be freed.4945 */4946 DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterR0,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTR0PTR pvUser,4947 const char *pszOut, const char *pszIn,4948 const char *pszOutStr, const char *pszInStr, const char *pszDesc));4949 4950 /**4951 * Deregister I/O ports.4952 *4953 * This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.4954 *4955 * @returns VBox status.4956 * @param pDevIns The device instance owning the ports.4957 * @param Port First port number in the range.4958 * @param cPorts Number of ports to deregister.4959 */4960 DECLR3CALLBACKMEMBER(int, pfnIOPortDeregister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts));4961 4962 4963 /**4964 * Register a Memory Mapped I/O (MMIO) region.4965 *4966 * These callbacks are of course for the host context (HC).4967 * Register HC handlers before guest context (GC) handlers! There must be a4968 * HC handler for every GC handler!4969 *4970 * @returns VBox status.4971 * @param pDevIns The device instance to register the MMIO with.4972 * @param GCPhysStart First physical address in the range.4973 * @param cbRange The size of the range (in bytes).4974 * @param pvUser User argument.4975 * @param pfnWrite Pointer to function which is gonna handle Write operations.4976 * @param pfnRead Pointer to function which is gonna handle Read operations.4977 * @param pfnFill Pointer to function which is gonna handle Fill/memset operations. (optional)4978 * @param pszDesc Pointer to description string. This must not be freed.4979 */4980 DECLR3CALLBACKMEMBER(int, pfnMMIORegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTHCPTR pvUser,4981 PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, PFNIOMMMIOFILL pfnFill,4982 const char *pszDesc));4983 4984 /**4985 * Register a Memory Mapped I/O (MMIO) region for GC.4986 *4987 * These callbacks are for the guest context (GC).4988 * Register host context (HC) handlers before guest context handlers! There must be a4989 * HC handler for every GC handler!4990 *4991 * @returns VBox status.4992 * @param pDevIns The device instance to register the MMIO with.4993 * @param GCPhysStart First physical address in the range.4994 * @param cbRange The size of the range (in bytes).4995 * @param pvUser User argument.4996 * @param pszWrite Name of the GC function which is gonna handle Write operations.4997 * @param pszRead Name of the GC function which is gonna handle Read operations.4998 * @param pszFill Name of the GC function which is gonna handle Fill/memset operations. (optional)4999 * @param pszDesc Pointer to description string. This must not be freed.5000 */5001 DECLR3CALLBACKMEMBER(int, pfnMMIORegisterGC,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTGCPTR pvUser,5002 const char *pszWrite, const char *pszRead, const char *pszFill,5003 const char *pszDesc));5004 5005 /**5006 * Register a Memory Mapped I/O (MMIO) region for R0.5007 *5008 * These callbacks are for the ring-0 host context (R0).5009 * Register R3 (HC) handlers before R0 handlers! There must be a R3 handler for every R0 handler!5010 *5011 * @returns VBox status.5012 * @param pDevIns The device instance to register the MMIO with.5013 * @param GCPhysStart First physical address in the range.5014 * @param cbRange The size of the range (in bytes).5015 * @param pvUser User argument. (if pointer, then it must be in locked memory!)5016 * @param pszWrite Name of the GC function which is gonna handle Write operations.5017 * @param pszRead Name of the GC function which is gonna handle Read operations.5018 * @param pszFill Name of the GC function which is gonna handle Fill/memset operations. (optional)5019 * @param pszDesc Pointer to description string. This must not be freed.5020 */5021 DECLR3CALLBACKMEMBER(int, pfnMMIORegisterR0,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTR0PTR pvUser,5022 const char *pszWrite, const char *pszRead, const char *pszFill,5023 const char *pszDesc));5024 5025 /**5026 * Deregister a Memory Mapped I/O (MMIO) region.5027 *5028 * This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.5029 *5030 * @returns VBox status.5031 * @param pDevIns The device instance owning the MMIO region(s).5032 * @param GCPhysStart First physical address in the range.5033 * @param cbRange The size of the range (in bytes).5034 */5035 DECLR3CALLBACKMEMBER(int, pfnMMIODeregister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange));5036 5037 /**5038 * Register a ROM (BIOS) region.5039 *5040 * It goes without saying that this is read-only memory. The memory region must be5041 * in unassigned memory. I.e. from the top of the address space or on the PC in5042 * the 0xa0000-0xfffff range.5043 *5044 * @returns VBox status.5045 * @param pDevIns The device instance owning the ROM region.5046 * @param GCPhysStart First physical address in the range.5047 * Must be page aligned!5048 * @param cbRange The size of the range (in bytes).5049 * Must be page aligned!5050 * @param pvBinary Pointer to the binary data backing the ROM image.5051 * This must be cbRange bytes big.5052 * It will be copied and doesn't have to stick around.5053 * @param pszDesc Pointer to description string. This must not be freed.5054 * @remark There is no way to remove the rom, automatically on device cleanup or5055 * manually from the device yet. At present I doubt we need such features...5056 */5057 DECLR3CALLBACKMEMBER(int, pfnROMRegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, const void *pvBinary, const char *pszDesc));5058 5059 /**5060 * Register a save state data unit.5061 *5062 * @returns VBox status.5063 * @param pDevIns Device instance.5064 * @param pszName Data unit name.5065 * @param u32Instance The instance identifier of the data unit.5066 * This must together with the name be unique.5067 * @param u32Version Data layout version number.5068 * @param cbGuess The approximate amount of data in the unit.5069 * Only for progress indicators.5070 * @param pfnSavePrep Prepare save callback, optional.5071 * @param pfnSaveExec Execute save callback, optional.5072 * @param pfnSaveDone Done save callback, optional.5073 * @param pfnLoadPrep Prepare load callback, optional.5074 * @param pfnLoadExec Execute load callback, optional.5075 * @param pfnLoadDone Done load callback, optional.5076 */5077 DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDEVINS pDevIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,5078 PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,5079 PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone));5080 5081 /**5082 * Creates a timer.5083 *5084 * @returns VBox status.5085 * @param pDevIns Device instance.5086 * @param enmClock The clock to use on this timer.5087 * @param pfnCallback Callback function.5088 * @param pszDesc Pointer to description string which must stay around5089 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).5090 * @param ppTimer Where to store the timer on success.5091 */5092 DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer));5093 5094 /**5095 * Creates an external timer.5096 *5097 * @returns timer pointer5098 * @param pDevIns Device instance.5099 * @param enmClock The clock to use on this timer.5100 * @param pfnCallback Callback function.5101 * @param pvUser User pointer5102 * @param pszDesc Pointer to description string which must stay around5103 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).5104 */5105 DECLR3CALLBACKMEMBER(PTMTIMERHC, pfnTMTimerCreateExternal,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMEREXT pfnCallback, void *pvUser, const char *pszDesc));5106 5107 /**5108 * Registers the device with the default PCI bus.5109 *5110 * @returns VBox status code.5111 * @param pDevIns Device instance.5112 * @param pPciDev The PCI device structure.5113 * Any PCI enabled device must keep this in it's instance data!5114 * Fill in the PCI data config before registration, please.5115 * @remark This is the simple interface, a Ex interface will be created if5116 * more features are needed later.5117 */5118 DECLR3CALLBACKMEMBER(int, pfnPCIRegister,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev));5119 5120 /**5121 * Registers a I/O region (memory mapped or I/O ports) for a PCI device.5122 *5123 * @returns VBox status code.5124 * @param pDevIns Device instance.5125 * @param iRegion The region number.5126 * @param cbRegion Size of the region.5127 * @param enmType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.5128 * @param pfnCallback Callback for doing the mapping.5129 */5130 DECLR3CALLBACKMEMBER(int, pfnPCIIORegionRegister,(PPDMDEVINS pDevIns, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback));5131 5132 /**5133 * Register PCI configuration space read/write callbacks.5134 *5135 * @param pDevIns Device instance.5136 * @param pPciDev The PCI device structure.5137 * If NULL the default PCI device for this device instance is used.5138 * @param pfnRead Pointer to the user defined PCI config read function.5139 * @param ppfnReadOld Pointer to function pointer which will receive the old (default)5140 * PCI config read function. This way, user can decide when (and if)5141 * to call default PCI config read function. Can be NULL.5142 * @param pfnWrite Pointer to the user defined PCI config write function.5143 * @param pfnWriteOld Pointer to function pointer which will receive the old (default)5144 * PCI config write function. This way, user can decide when (and if)5145 * to call default PCI config write function. Can be NULL.5146 * @thread EMT5147 */5148 DECLR3CALLBACKMEMBER(void, pfnPCISetConfigCallbacks,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,5149 PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld));5150 5151 /**5152 * Set the IRQ for a PCI device.5153 *5154 * @param pDevIns Device instance.5155 * @param iIrq IRQ number to set.5156 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.5157 * @thread Any thread, but will involve the emulation thread.5158 */5159 DECLR3CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));5160 5161 /**5162 * Set the IRQ for a PCI device, but don't wait for EMT to process5163 * the request when not called from EMT.5164 *5165 * @param pDevIns Device instance.5166 * @param iIrq IRQ number to set.5167 * @param iLevel IRQ level.5168 * @thread Any thread, but will involve the emulation thread.5169 */5170 DECLR3CALLBACKMEMBER(void, pfnPCISetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));5171 5172 /**5173 * Set ISA IRQ for a device.5174 *5175 * @param pDevIns Device instance.5176 * @param iIrq IRQ number to set.5177 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.5178 * @thread Any thread, but will involve the emulation thread.5179 */5180 DECLR3CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));5181 5182 /**5183 * Set the ISA IRQ for a device, but don't wait for EMT to process5184 * the request when not called from EMT.5185 *5186 * @param pDevIns Device instance.5187 * @param iIrq IRQ number to set.5188 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.5189 * @thread Any thread, but will involve the emulation thread.5190 */5191 DECLR3CALLBACKMEMBER(void, pfnISASetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));5192 5193 /**5194 * Attaches a driver (chain) to the device.5195 *5196 * The first call for a LUN this will serve as a registartion of the LUN. The pBaseInterface and5197 * the pszDesc string will be registered with that LUN and kept around for PDMR3QueryDeviceLun().5198 *5199 * @returns VBox status code.5200 * @param pDevIns Device instance.5201 * @param iLun The logical unit to attach.5202 * @param pBaseInterface Pointer to the base interface for that LUN. (device side / down)5203 * @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up)5204 * @param pszDesc Pointer to a string describing the LUN. This string must remain valid5205 * for the live of the device instance.5206 */5207 DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMDEVINS pDevIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE *ppBaseInterface, const char *pszDesc));5208 5209 #if 05210 /* USB... */5211 5212 #endif5213 5214 /**5215 * Allocate memory which is associated with current VM instance5216 * and automatically freed on it's destruction.5217 *5218 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.5219 * @param pDevIns Device instance.5220 * @param cb Number of bytes to allocate.5221 */5222 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVINS pDevIns, size_t cb));5223 5224 /**5225 * Allocate memory which is associated with current VM instance5226 * and automatically freed on it's destruction. The memory is ZEROed.5227 *5228 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.5229 * @param pDevIns Device instance.5230 * @param cb Number of bytes to allocate.5231 */5232 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAllocZ,(PPDMDEVINS pDevIns, size_t cb));5233 5234 /**5235 * Free memory allocated with pfnMMHeapAlloc() and pfnMMHeapAllocZ().5236 *5237 * @param pDevIns Device instance.5238 * @param pv Pointer to the memory to free.5239 */5240 DECLR3CALLBACKMEMBER(void, pfnMMHeapFree,(PPDMDEVINS pDevIns, void *pv));5241 5242 /**5243 * Set the VM error message5244 *5245 * @returns rc.5246 * @param pDevIns Device instance.5247 * @param rc VBox status code.5248 * @param RT_SRC_POS_DECL Use RT_SRC_POS.5249 * @param pszFormat Error message format string.5250 * @param ... Error message arguments.5251 */5252 DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));5253 5254 /**5255 * Set the VM error message5256 *5257 * @returns rc.5258 * @param pDevIns Device instance.5259 * @param rc VBox status code.5260 * @param RT_SRC_POS_DECL Use RT_SRC_POS.5261 * @param pszFormat Error message format string.5262 * @param va Error message arguments.5263 */5264 DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));5265 5266 /**5267 * Set the VM runtime error message5268 *5269 * @returns VBox status code.5270 * @param pDevIns Device instance.5271 * @param fFatal Whether it is a fatal error or not.5272 * @param pszErrorID Error ID string.5273 * @param pszFormat Error message format string.5274 * @param ... Error message arguments.5275 */5276 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));5277 5278 /**5279 * Set the VM runtime error message5280 *5281 * @returns VBox status code.5282 * @param pDevIns Device instance.5283 * @param fFatal Whether it is a fatal error or not.5284 * @param pszErrorID Error ID string.5285 * @param pszFormat Error message format string.5286 * @param va Error message arguments.5287 */5288 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));5289 5290 /**5291 * Assert that the current thread is the emulation thread.5292 *5293 * @returns True if correct.5294 * @returns False if wrong.5295 * @param pDevIns Device instance.5296 * @param pszFile Filename of the assertion location.5297 * @param iLine The linenumber of the assertion location.5298 * @param pszFunction Function of the assertion location.5299 */5300 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction));5301 5302 /**5303 * Assert that the current thread is NOT the emulation thread.5304 *5305 * @returns True if correct.5306 * @returns False if wrong.5307 * @param pDevIns Device instance.5308 * @param pszFile Filename of the assertion location.5309 * @param iLine The linenumber of the assertion location.5310 * @param pszFunction Function of the assertion location.5311 */5312 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction));5313 5314 /**5315 * Stops the VM and enters the debugger to look at the guest state.5316 *5317 * Use the PDMDeviceDBGFStop() inline function with the RT_SRC_POS macro instead of5318 * invoking this function directly.5319 *5320 * @returns VBox status code which must be passed up to the VMM.5321 * @param pDevIns Device instance.5322 * @param pszFile Filename of the assertion location.5323 * @param iLine The linenumber of the assertion location.5324 * @param pszFunction Function of the assertion location.5325 * @param pszFormat Message. (optional)5326 * @param args Message parameters.5327 */5328 DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction, const char *pszFormat, va_list args));5329 5330 /**5331 * Register a info handler with DBGF,5332 *5333 * @returns VBox status code.5334 * @param pDevIns Device instance.5335 * @param pszName The identifier of the info.5336 * @param pszDesc The description of the info and any arguments the handler may take.5337 * @param pfnHandler The handler function to be called to display the info.5338 */5339 DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMDEVINS pDevIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDEV pfnHandler));5340 5341 /**5342 * Registers a statistics sample if statistics are enabled.5343 *5344 * @param pDevIns Device instance of the DMA.5345 * @param pvSample Pointer to the sample.5346 * @param enmType Sample type. This indicates what pvSample is pointing at.5347 * @param pszName Sample name. The name is on this form "/<component>/<sample>".5348 * Further nesting is possible.5349 * @param enmUnit Sample unit.5350 * @param pszDesc Sample description.5351 */5352 DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc));5353 5354 /**5355 * Same as pfnSTAMRegister except that the name is specified in a5356 * RTStrPrintf like fashion.5357 *5358 * @returns VBox status.5359 * @param pDevIns Device instance of the DMA.5360 * @param pvSample Pointer to the sample.5361 * @param enmType Sample type. This indicates what pvSample is pointing at.5362 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.5363 * @param enmUnit Sample unit.5364 * @param pszDesc Sample description.5365 * @param pszName The sample name format string.5366 * @param ... Arguments to the format string.5367 */5368 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,5369 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, ...));5370 5371 /**5372 * Same as pfnSTAMRegister except that the name is specified in a5373 * RTStrPrintfV like fashion.5374 *5375 * @returns VBox status.5376 * @param pDevIns Device instance of the DMA.5377 * @param pvSample Pointer to the sample.5378 * @param enmType Sample type. This indicates what pvSample is pointing at.5379 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.5380 * @param enmUnit Sample unit.5381 * @param pszDesc Sample description.5382 * @param pszName The sample name format string.5383 * @param args Arguments to the format string.5384 */5385 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,5386 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list args));5387 5388 /**5389 * Register the RTC device.5390 *5391 * @returns VBox status code.5392 * @param pDevIns Device instance.5393 * @param pRtcReg Pointer to a RTC registration structure.5394 * @param ppRtcHlp Where to store the pointer to the helper functions.5395 */5396 DECLR3CALLBACKMEMBER(int, pfnRTCRegister,(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp));5397 5398 /**5399 * Create a queue.5400 *5401 * @returns VBox status code.5402 * @param pDevIns The device instance.5403 * @param cbItem The size of a queue item.5404 * @param cItems The number of items in the queue.5405 * @param cMilliesInterval The number of milliseconds between polling the queue.5406 * If 0 then the emulation thread will be notified whenever an item arrives.5407 * @param pfnCallback The consumer function.5408 * @param fGCEnabled Set if the queue should work in GC too.5409 * @param ppQueue Where to store the queue handle on success.5410 * @thread The emulation thread.5411 */5412 DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDEVINS pDevIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,5413 PFNPDMQUEUEDEV pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue));5414 5415 /**5416 * Initializes a PDM critical section.5417 *5418 * The PDM critical sections are derived from the IPRT critical sections, but5419 * works in GC as well.5420 *5421 * @returns VBox status code.5422 * @param pDevIns Device instance.5423 * @param pCritSect Pointer to the critical section.5424 * @param pszName The name of the critical section (for statistics).5425 */5426 DECLR3CALLBACKMEMBER(int, pfnCritSectInit,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, const char *pszName));5427 5428 /**5429 * Get the real world UTC time adjusted for VM lag, user offset and warpdrive.5430 *5431 * @returns pTime.5432 * @param pDevIns Device instance.5433 * @param pTime Where to store the time.5434 */5435 DECLR3CALLBACKMEMBER(PRTTIMESPEC, pfnUTCNow,(PPDMDEVINS pDevIns, PRTTIMESPEC pTime));5436 5437 /** Space reserved for future members.5438 * @{ */5439 DECLR3CALLBACKMEMBER(void, pfnReserved1,(void));5440 DECLR3CALLBACKMEMBER(void, pfnReserved2,(void));5441 DECLR3CALLBACKMEMBER(void, pfnReserved3,(void));5442 DECLR3CALLBACKMEMBER(void, pfnReserved4,(void));5443 DECLR3CALLBACKMEMBER(void, pfnReserved5,(void));5444 DECLR3CALLBACKMEMBER(void, pfnReserved6,(void));5445 DECLR3CALLBACKMEMBER(void, pfnReserved7,(void));5446 DECLR3CALLBACKMEMBER(void, pfnReserved8,(void));5447 DECLR3CALLBACKMEMBER(void, pfnReserved9,(void));5448 DECLR3CALLBACKMEMBER(void, pfnReserved10,(void));5449 /** @} */5450 5451 5452 /** API available to trusted devices only.5453 *5454 * These APIs are providing unrestricted access to the guest and the VM,5455 * or they are interacting intimately with PDM.5456 *5457 * @{5458 */5459 /**5460 * Gets the VM handle. Restricted API.5461 *5462 * @returns VM Handle.5463 * @param pDevIns Device instance.5464 */5465 DECLR3CALLBACKMEMBER(PVM, pfnGetVM,(PPDMDEVINS pDevIns));5466 5467 /**5468 * Register the PCI Bus.5469 *5470 * @returns VBox status code.5471 * @param pDevIns Device instance.5472 * @param pPciBusReg Pointer to PCI bus registration structure.5473 * @param ppPciHlpR3 Where to store the pointer to the PCI Bus helpers.5474 */5475 DECLR3CALLBACKMEMBER(int, pfnPCIBusRegister,(PPDMDEVINS pDevIns, PPDMPCIBUSREG pPciBusReg, PCPDMPCIHLPR3 *ppPciHlpR3));5476 5477 /**5478 * Register the PIC device.5479 *5480 * @returns VBox status code.5481 * @param pDevIns Device instance.5482 * @param pPicReg Pointer to a PIC registration structure.5483 * @param ppPicHlpR3 Where to store the pointer to the PIC HC helpers.5484 */5485 DECLR3CALLBACKMEMBER(int, pfnPICRegister,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLPR3 *ppPicHlpR3));5486 5487 /**5488 * Register the APIC device.5489 *5490 * @returns VBox status code.5491 * @param pDevIns Device instance.5492 * @param pApicReg Pointer to a APIC registration structure.5493 * @param ppApicHlpR3 Where to store the pointer to the APIC helpers.5494 */5495 DECLR3CALLBACKMEMBER(int, pfnAPICRegister,(PPDMDEVINS pDevIns, PPDMAPICREG pApicReg, PCPDMAPICHLPR3 *ppApicHlpR3));5496 5497 /**5498 * Register the I/O APIC device.5499 *5500 * @returns VBox status code.5501 * @param pDevIns Device instance.5502 * @param pIoApicReg Pointer to a I/O APIC registration structure.5503 * @param ppIoApicHlpR3 Where to store the pointer to the IOAPIC helpers.5504 */5505 DECLR3CALLBACKMEMBER(int, pfnIOAPICRegister,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLPR3 *ppIoApicHlpR3));5506 5507 /**5508 * Register the DMA device.5509 *5510 * @returns VBox status code.5511 * @param pDevIns Device instance.5512 * @param pDmacReg Pointer to a DMAC registration structure.5513 * @param ppDmacHlp Where to store the pointer to the DMA helpers.5514 */5515 DECLR3CALLBACKMEMBER(int, pfnDMACRegister,(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp));5516 5517 /**5518 * Read physical memory.5519 *5520 * @param pDevIns Device instance.5521 * @param GCPhys Physical address start reading from.5522 * @param pvBuf Where to put the read bits.5523 * @param cbRead How many bytes to read.5524 * @thread Any thread, but the call may involve the emulation thread.5525 */5526 DECLR3CALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));5527 5528 /**5529 * Write to physical memory.5530 *5531 * @param pDevIns Device instance.5532 * @param GCPhys Physical address to write to.5533 * @param pvBuf What to write.5534 * @param cbWrite How many bytes to write.5535 * @thread Any thread, but the call may involve the emulation thread.5536 */5537 DECLR3CALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));5538 5539 /**5540 * Read guest physical memory by virtual address.5541 *5542 * @param pDevIns Device instance.5543 * @param pvDst Where to put the read bits.5544 * @param GCVirtSrc Guest virtual address to start reading from.5545 * @param cb How many bytes to read.5546 * @thread The emulation thread.5547 */5548 DECLR3CALLBACKMEMBER(int, pfnPhysReadGCVirt,(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb));5549 5550 /**5551 * Write to guest physical memory by virtual address.5552 *5553 * @param pDevIns Device instance.5554 * @param GCVirtDst Guest virtual address to write to.5555 * @param pvSrc What to write.5556 * @param cb How many bytes to write.5557 * @thread The emulation thread.5558 */5559 DECLR3CALLBACKMEMBER(int, pfnPhysWriteGCVirt,(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb));5560 5561 /**5562 * Reserve physical address space for ROM and MMIO ranges.5563 *5564 * @returns VBox status code.5565 * @param pDevIns Device instance.5566 * @param GCPhys Start physical address.5567 * @param cbRange The size of the range.5568 * @param pszDesc Description string.5569 * @thread The emulation thread.5570 */5571 DECLR3CALLBACKMEMBER(int, pfnPhysReserve,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const char *pszDesc));5572 5573 /**5574 * Convert a guest physical address to a host virtual address.5575 *5576 * @returns VBox status code.5577 * @param pDevIns Device instance.5578 * @param GCPhys Start physical address.5579 * @param cbRange The size of the range. Use 0 if you don't care about the range.5580 * @param ppvHC Where to store the HC pointer corresponding to GCPhys.5581 * @thread Any thread.5582 */5583 DECLR3CALLBACKMEMBER(int, pfnPhys2HCVirt,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, PRTHCPTR ppvHC));5584 5585 /**5586 * Convert a guest virtual address to a host virtual address.5587 *5588 * @returns VBox status code.5589 * @param pDevIns Device instance.5590 * @param GCPtr Guest virtual address.5591 * @param pHCPtr Where to store the HC pointer corresponding to GCPtr.5592 * @thread The emulation thread.5593 * @remark Careful with page boundraries.5594 */5595 DECLR3CALLBACKMEMBER(int, pfnPhysGCPtr2HCPtr,(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTHCPTR pHCPtr));5596 5597 /**5598 * Checks if the Gate A20 is enabled or not.5599 *5600 * @returns true if A20 is enabled.5601 * @returns false if A20 is disabled.5602 * @param pDevIns Device instance.5603 * @thread The emulation thread.5604 */5605 DECLR3CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));5606 5607 /**5608 * Enables or disables the Gate A20.5609 *5610 * @param pDevIns Device instance.5611 * @param fEnable Set this flag to enable the Gate A20; clear it to disable.5612 * @thread The emulation thread.5613 */5614 DECLR3CALLBACKMEMBER(void, pfnA20Set,(PPDMDEVINS pDevIns, bool fEnable));5615 5616 /**5617 * Resets the VM.5618 *5619 * @returns The appropriate VBox status code to pass around on reset.5620 * @param pDevIns Device instance.5621 * @thread The emulation thread.5622 */5623 DECLR3CALLBACKMEMBER(int, pfnVMReset,(PPDMDEVINS pDevIns));5624 5625 /**5626 * Suspends the VM.5627 *5628 * @returns The appropriate VBox status code to pass around on suspend.5629 * @param pDevIns Device instance.5630 * @thread The emulation thread.5631 */5632 DECLR3CALLBACKMEMBER(int, pfnVMSuspend,(PPDMDEVINS pDevIns));5633 5634 /**5635 * Power off the VM.5636 *5637 * @returns The appropriate VBox status code to pass around on power off.5638 * @param pDevIns Device instance.5639 * @thread The emulation thread.5640 */5641 DECLR3CALLBACKMEMBER(int, pfnVMPowerOff,(PPDMDEVINS pDevIns));5642 5643 /**5644 * Acquire global VM lock5645 *5646 * @returns VBox status code5647 * @param pDevIns Device instance.5648 */5649 DECLR3CALLBACKMEMBER(int , pfnLockVM,(PPDMDEVINS pDevIns));5650 5651 /**5652 * Release global VM lock5653 *5654 * @returns VBox status code5655 * @param pDevIns Device instance.5656 */5657 DECLR3CALLBACKMEMBER(int, pfnUnlockVM,(PPDMDEVINS pDevIns));5658 5659 /**5660 * Check that the current thread owns the global VM lock.5661 *5662 * @returns boolean5663 * @param pDevIns Device instance.5664 * @param pszFile Filename of the assertion location.5665 * @param iLine Linenumber of the assertion location.5666 * @param pszFunction Function of the assertion location.5667 */5668 DECLR3CALLBACKMEMBER(bool, pfnAssertVMLock,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction));5669 5670 /**5671 * Register transfer function for DMA channel.5672 *5673 * @returns VBox status code.5674 * @param pDevIns Device instance.5675 * @param uChannel Channel number.5676 * @param pfnTransferHandler Device specific transfer callback function.5677 * @param pvUser User pointer to pass to the callback.5678 * @thread EMT5679 */5680 DECLR3CALLBACKMEMBER(int, pfnDMARegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));5681 5682 /**5683 * Read memory.5684 *5685 * @returns VBox status code.5686 * @param pDevIns Device instance.5687 * @param uChannel Channel number.5688 * @param pvBuffer Pointer to target buffer.5689 * @param off DMA position.5690 * @param cbBlock Block size.5691 * @param pcbRead Where to store the number of bytes which was read. optional.5692 * @thread EMT5693 */5694 DECLR3CALLBACKMEMBER(int, pfnDMAReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbRead));5695 5696 /**5697 * Write memory.5698 *5699 * @returns VBox status code.5700 * @param pDevIns Device instance.5701 * @param uChannel Channel number.5702 * @param pvBuffer Memory to write.5703 * @param off DMA position.5704 * @param cbBlock Block size.5705 * @param pcbWritten Where to store the number of bytes which was written. optional.5706 * @thread EMT5707 */5708 DECLR3CALLBACKMEMBER(int, pfnDMAWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbWritten));5709 5710 /**5711 * Set the DREQ line.5712 *5713 * @returns VBox status code.5714 * @param pDevIns Device instance.5715 * @param uChannel Channel number.5716 * @param uLevel Level of the line.5717 * @thread EMT5718 */5719 DECLR3CALLBACKMEMBER(int, pfnDMASetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));5720 5721 /**5722 * Get channel mode.5723 *5724 * @returns Channel mode. See specs.5725 * @param pDevIns Device instance.5726 * @param uChannel Channel number.5727 * @thread EMT5728 */5729 DECLR3CALLBACKMEMBER(uint8_t, pfnDMAGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));5730 5731 /**5732 * Schedule DMA execution.5733 *5734 * @param pDevIns Device instance.5735 * @thread Any thread.5736 */5737 DECLR3CALLBACKMEMBER(void, pfnDMASchedule,(PPDMDEVINS pDevIns));5738 5739 /**5740 * Write CMOS value and update the checksum(s).5741 *5742 * @returns VBox status code.5743 * @param pDevIns Device instance.5744 * @param iReg The CMOS register index.5745 * @param u8Value The CMOS register value.5746 * @thread EMT5747 */5748 DECLR3CALLBACKMEMBER(int, pfnCMOSWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));5749 5750 /**5751 * Read CMOS value.5752 *5753 * @returns VBox status code.5754 * @param pDevIns Device instance.5755 * @param iReg The CMOS register index.5756 * @param pu8Value Where to store the CMOS register value.5757 * @thread EMT5758 */5759 DECLR3CALLBACKMEMBER(int, pfnCMOSRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));5760 5761 /**5762 * Query CPUID.5763 *5764 * @param pDevIns Device instance.5765 * @param iLeaf The CPUID leaf to get.5766 * @param pEax Where to store the EAX value.5767 * @param pEbx Where to store the EBX value.5768 * @param pEcx Where to store the ECX value.5769 * @param pEdx Where to store the EDX value.5770 */5771 DECLR3CALLBACKMEMBER(void, pfnGetCpuId,(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t *pEax, uint32_t *pEbx, uint32_t *pEcx, uint32_t *pEdx));5772 5773 /** @} */5774 5775 /** Just a safety precaution. (The value is 0.) */5776 uint32_t u32TheEnd;5777 } PDMDEVHLP;5778 #endif /* !IN_RING3 */5779 /** Pointer PDM Device API. */5780 typedef HCPTRTYPE(struct PDMDEVHLP *) PPDMDEVHLP;5781 /** Pointer PDM Device API. */5782 typedef HCPTRTYPE(const struct PDMDEVHLP *) PCPDMDEVHLP;5783 5784 /** Current PDMDEVHLP version number. */5785 #define PDM_DEVHLP_VERSION 0xf20400005786 5787 5788 /**5789 * PDM Device API - GC Variant.5790 */5791 typedef struct PDMDEVHLPGC5792 {5793 /** Structure version. PDM_DEVHLPGC_VERSION defines the current version. */5794 uint32_t u32Version;5795 5796 /**5797 * Set the IRQ for a PCI device.5798 *5799 * @param pDevIns Device instance.5800 * @param iIrq IRQ number to set.5801 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.5802 * @thread Any thread, but will involve the emulation thread.5803 */5804 DECLGCCALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));5805 5806 /**5807 * Set ISA IRQ for a device.5808 *5809 * @param pDevIns Device instance.5810 * @param iIrq IRQ number to set.5811 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.5812 * @thread Any thread, but will involve the emulation thread.5813 */5814 DECLGCCALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));5815 5816 /**5817 * Read physical memory.5818 *5819 * @param pDevIns Device instance.5820 * @param GCPhys Physical address start reading from.5821 * @param pvBuf Where to put the read bits.5822 * @param cbRead How many bytes to read.5823 */5824 DECLGCCALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));5825 5826 /**5827 * Write to physical memory.5828 *5829 * @param pDevIns Device instance.5830 * @param GCPhys Physical address to write to.5831 * @param pvBuf What to write.5832 * @param cbWrite How many bytes to write.5833 */5834 DECLGCCALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));5835 5836 /**5837 * Checks if the Gate A20 is enabled or not.5838 *5839 * @returns true if A20 is enabled.5840 * @returns false if A20 is disabled.5841 * @param pDevIns Device instance.5842 * @thread The emulation thread.5843 */5844 DECLGCCALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));5845 5846 /**5847 * Set the VM error message5848 *5849 * @returns rc.5850 * @param pDrvIns Driver instance.5851 * @param rc VBox status code.5852 * @param RT_SRC_POS_DECL Use RT_SRC_POS.5853 * @param pszFormat Error message format string.5854 * @param ... Error message arguments.5855 */5856 DECLGCCALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));5857 5858 /**5859 * Set the VM error message5860 *5861 * @returns rc.5862 * @param pDrvIns Driver instance.5863 * @param rc VBox status code.5864 * @param RT_SRC_POS_DECL Use RT_SRC_POS.5865 * @param pszFormat Error message format string.5866 * @param va Error message arguments.5867 */5868 DECLGCCALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));5869 5870 /**5871 * Set the VM runtime error message5872 *5873 * @returns VBox status code.5874 * @param pDevIns Device instance.5875 * @param fFatal Whether it is a fatal error or not.5876 * @param pszErrorID Error ID string.5877 * @param pszFormat Error message format string.5878 * @param ... Error message arguments.5879 */5880 DECLGCCALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));5881 5882 /**5883 * Set the VM runtime error message5884 *5885 * @returns VBox status code.5886 * @param pDevIns Device instance.5887 * @param fFatal Whether it is a fatal error or not.5888 * @param pszErrorID Error ID string.5889 * @param pszFormat Error message format string.5890 * @param va Error message arguments.5891 */5892 DECLGCCALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));5893 5894 /**5895 * Set parameters for pending MMIO patch operation5896 *5897 * @returns VBox status code.5898 * @param pDevIns Device instance.5899 * @param GCPhys MMIO physical address5900 * @param pCachedData GC pointer to cached data5901 */5902 DECLGCCALLBACKMEMBER(int, pfnPATMSetMMIOPatchInfo,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPTR pCachedData));5903 5904 /** Just a safety precaution. */5905 uint32_t u32TheEnd;5906 } PDMDEVHLPGC;5907 /** Pointer PDM Device GC API. */5908 typedef GCPTRTYPE(struct PDMDEVHLPGC *) PPDMDEVHLPGC;5909 /** Pointer PDM Device GC API. */5910 typedef GCPTRTYPE(const struct PDMDEVHLPGC *) PCPDMDEVHLPGC;5911 5912 /** Current PDMDEVHLP version number. */5913 #define PDM_DEVHLPGC_VERSION 0xfb0100005914 5915 5916 /**5917 * PDM Device API - R0 Variant.5918 */5919 typedef struct PDMDEVHLPR05920 {5921 /** Structure version. PDM_DEVHLPR0_VERSION defines the current version. */5922 uint32_t u32Version;5923 5924 /**5925 * Set the IRQ for a PCI device.5926 *5927 * @param pDevIns Device instance.5928 * @param iIrq IRQ number to set.5929 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.5930 * @thread Any thread, but will involve the emulation thread.5931 */5932 DECLR0CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));5933 5934 /**5935 * Set ISA IRQ for a device.5936 *5937 * @param pDevIns Device instance.5938 * @param iIrq IRQ number to set.5939 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.5940 * @thread Any thread, but will involve the emulation thread.5941 */5942 DECLR0CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));5943 5944 /**5945 * Read physical memory.5946 *5947 * @param pDevIns Device instance.5948 * @param GCPhys Physical address start reading from.5949 * @param pvBuf Where to put the read bits.5950 * @param cbRead How many bytes to read.5951 */5952 DECLR0CALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));5953 5954 /**5955 * Write to physical memory.5956 *5957 * @param pDevIns Device instance.5958 * @param GCPhys Physical address to write to.5959 * @param pvBuf What to write.5960 * @param cbWrite How many bytes to write.5961 */5962 DECLR0CALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));5963 5964 /**5965 * Checks if the Gate A20 is enabled or not.5966 *5967 * @returns true if A20 is enabled.5968 * @returns false if A20 is disabled.5969 * @param pDevIns Device instance.5970 * @thread The emulation thread.5971 */5972 DECLR0CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));5973 5974 /**5975 * Set the VM error message5976 *5977 * @returns rc.5978 * @param pDrvIns Driver instance.5979 * @param rc VBox status code.5980 * @param RT_SRC_POS_DECL Use RT_SRC_POS.5981 * @param pszFormat Error message format string.5982 * @param ... Error message arguments.5983 */5984 DECLR0CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));5985 5986 /**5987 * Set the VM error message5988 *5989 * @returns rc.5990 * @param pDrvIns Driver instance.5991 * @param rc VBox status code.5992 * @param RT_SRC_POS_DECL Use RT_SRC_POS.5993 * @param pszFormat Error message format string.5994 * @param va Error message arguments.5995 */5996 DECLR0CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));5997 5998 /**5999 * Set the VM runtime error message6000 *6001 * @returns VBox status code.6002 * @param pDevIns Device instance.6003 * @param fFatal Whether it is a fatal error or not.6004 * @param pszErrorID Error ID string.6005 * @param pszFormat Error message format string.6006 * @param ... Error message arguments.6007 */6008 DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));6009 6010 /**6011 * Set the VM runtime error message6012 *6013 * @returns VBox status code.6014 * @param pDevIns Device instance.6015 * @param fFatal Whether it is a fatal error or not.6016 * @param pszErrorID Error ID string.6017 * @param pszFormat Error message format string.6018 * @param va Error message arguments.6019 */6020 DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));6021 6022 /**6023 * Set parameters for pending MMIO patch operation6024 *6025 * @returns rc.6026 * @param pDevIns Device instance.6027 * @param GCPhys MMIO physical address6028 * @param pCachedData GC pointer to cached data6029 */6030 DECLR0CALLBACKMEMBER(int, pfnPATMSetMMIOPatchInfo,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPTR pCachedData));6031 6032 /** Just a safety precaution. */6033 uint32_t u32TheEnd;6034 } PDMDEVHLPR0;6035 /** Pointer PDM Device R0 API. */6036 typedef HCPTRTYPE(struct PDMDEVHLPR0 *) PPDMDEVHLPR0;6037 /** Pointer PDM Device GC API. */6038 typedef HCPTRTYPE(const struct PDMDEVHLPR0 *) PCPDMDEVHLPR0;6039 6040 /** Current PDMDEVHLP version number. */6041 #define PDM_DEVHLPR0_VERSION 0xfb0100006042 6043 6044 6045 /**6046 * PDM Device Instance.6047 */6048 typedef struct PDMDEVINS6049 {6050 /** Structure version. PDM_DEVINS_VERSION defines the current version. */6051 uint32_t u32Version;6052 /** Device instance number. */6053 RTUINT iInstance;6054 /** The base interface of the device.6055 * The device constructor initializes this if it has any6056 * device level interfaces to export. To obtain this interface6057 * call PDMR3QueryDevice(). */6058 PDMIBASE IBase;6059 6060 /** Internal data. */6061 union6062 {6063 #ifdef PDMDEVINSINT_DECLARED6064 PDMDEVINSINT s;6065 #endif6066 uint8_t padding[HC_ARCH_BITS == 32 ? 48 : 96];6067 } Internal;6068 6069 /** Pointer the HC PDM Device API. */6070 R3PTRTYPE(PCPDMDEVHLP) pDevHlp;6071 /** Pointer the R0 PDM Device API. */6072 R0PTRTYPE(PCPDMDEVHLPR0) pDevHlpR0;6073 /** Pointer to device registration structure. */6074 R3PTRTYPE(PCPDMDEVREG) pDevReg;6075 /** Configuration handle. */6076 R3PTRTYPE(PCFGMNODE) pCfgHandle;6077 /** Pointer to device instance data. */6078 R3PTRTYPE(void *) pvInstanceDataR3;6079 /** Pointer to device instance data. */6080 R0PTRTYPE(void *) pvInstanceDataR0;6081 /** Pointer the GC PDM Device API. */6082 GCPTRTYPE(PCPDMDEVHLPGC) pDevHlpGC;6083 /** Pointer to device instance data. */6084 GCPTRTYPE(void *) pvInstanceDataGC;6085 /* padding to make achInstanceData aligned at 32 byte boundrary. */6086 uint32_t au32Padding[HC_ARCH_BITS == 32 ? 1 : 6];6087 /** Device instance data. The size of this area is defined6088 * in the PDMDEVREG::cbInstanceData field. */6089 char achInstanceData[8];6090 } PDMDEVINS;6091 6092 /** Current DEVREG version number. */6093 #define PDM_DEVINS_VERSION 0xf30100006094 6095 /** Converts a pointer to the PDMDEVINS::IBase to a pointer to PDMDEVINS. */6096 #define PDMIBASE_2_PDMDEV(pInterface) ( (PPDMDEVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDEVINS, IBase)) )6097 6098 6099 /** @def PDMDEV_ASSERT_EMT6100 * Assert that the current thread is the emulation thread.6101 */6102 #ifdef VBOX_STRICT6103 # define PDMDEV_ASSERT_EMT(pDevIns) pDevIns->pDevHlp->pfnAssertEMT(pDevIns, __FILE__, __LINE__, __FUNCTION__)6104 #else6105 # define PDMDEV_ASSERT_EMT(pDevIns) do { } while (0)6106 #endif6107 6108 /** @def PDMDEV_ASSERT_OTHER6109 * Assert that the current thread is NOT the emulation thread.6110 */6111 #ifdef VBOX_STRICT6112 # define PDMDEV_ASSERT_OTHER(pDevIns) pDevIns->pDevHlp->pfnAssertOther(pDevIns, __FILE__, __LINE__, __FUNCTION__)6113 #else6114 # define PDMDEV_ASSERT_OTHER(pDevIns) do { } while (0)6115 #endif6116 6117 /** @def PDMDEV_ASSERT_VMLOCK_OWNER6118 * Assert that the current thread is owner of the VM lock.6119 */6120 #ifdef VBOX_STRICT6121 # define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) pDevIns->pDevHlp->pfnAssertVMLock(pDevIns, __FILE__, __LINE__, __FUNCTION__)6122 #else6123 # define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) do { } while (0)6124 #endif6125 6126 /** @def PDMDEV_SET_ERROR6127 * Set the VM error. See PDMDevHlpVMSetError() for printf like message formatting.6128 */6129 #define PDMDEV_SET_ERROR(pDevIns, rc, pszError) \6130 PDMDevHlpVMSetError(pDevIns, rc, RT_SRC_POS, "%s", pszError)6131 6132 /** @def PDMDEV_SET_RUNTIME_ERROR6133 * Set the VM runtime error. See PDMDevHlpVMSetRuntimeError() for printf like message formatting.6134 */6135 #define PDMDEV_SET_RUNTIME_ERROR(pDevIns, fFatal, pszErrorID, pszError) \6136 PDMDevHlpVMSetRuntimeError(pDevIns, fFatal, pszErrorID, "%s", pszError)6137 6138 /** @def PDMINS2DATA6139 * Converts a PDM Device or Driver instance pointer to a pointer to the instance data.6140 */6141 #define PDMINS2DATA(pIns, type) ( (type)(void *)&(pIns)->achInstanceData[0] )6142 6143 /** @def PDMINS2DATA_GCPTR6144 * Converts a PDM Device or Driver instance pointer to a GC pointer to the instance data.6145 */6146 #define PDMINS2DATA_GCPTR(pIns) ( (pIns)->pvInstanceDataGC )6147 6148 /** @def PDMINS2DATA_R3PTR6149 * Converts a PDM Device or Driver instance pointer to a HC pointer to the instance data.6150 */6151 #define PDMINS2DATA_R3PTR(pIns) ( (pIns)->pvInstanceDataR3 )6152 6153 /** @def PDMINS2DATA_R0PTR6154 * Converts a PDM Device or Driver instance pointer to a R0 pointer to the instance data.6155 */6156 #define PDMINS2DATA_R0PTR(pIns) ( (pIns)->pvInstanceDataR0 )6157 6158 /** @def PDMDEVINS_2_GCPTR6159 * Converts a PDM Device instance pointer a GC PDM Device instance pointer.6160 */6161 #define PDMDEVINS_2_GCPTR(pDevIns) ( (GCPTRTYPE(PPDMDEVINS))((RTGCUINTPTR)(pDevIns)->pvInstanceDataGC - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )6162 6163 /** @def PDMDEVINS_2_R3PTR6164 * Converts a PDM Device instance pointer a HC PDM Device instance pointer.6165 */6166 #define PDMDEVINS_2_R3PTR(pDevIns) ( (HCPTRTYPE(PPDMDEVINS))((RTHCUINTPTR)(pDevIns)->pvInstanceDataR3 - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )6167 6168 /** @def PDMDEVINS_2_R0PTR6169 * Converts a PDM Device instance pointer a R0 PDM Device instance pointer.6170 */6171 #define PDMDEVINS_2_R0PTR(pDevIns) ( (R0PTRTYPE(PPDMDEVINS))((RTR0UINTPTR)(pDevIns)->pvInstanceDataR0 - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )6172 6173 6174 /**6175 * VBOX_STRICT wrapper for pDevHlp->pfnDBGFStopV.6176 *6177 * @returns VBox status code which must be passed up to the VMM.6178 * @param pDevIns Device instance.6179 * @param RT_SRC_POS_DECL Use RT_SRC_POS.6180 * @param pszFormat Message. (optional)6181 * @param ... Message parameters.6182 */6183 DECLINLINE(int) PDMDeviceDBGFStop(PPDMDEVINS pDevIns, RT_SRC_POS_DECL, const char *pszFormat, ...)6184 {6185 #ifdef VBOX_STRICT6186 # ifdef IN_RING36187 int rc;6188 va_list args;6189 va_start(args, pszFormat);6190 rc = pDevIns->pDevHlp->pfnDBGFStopV(pDevIns, RT_SRC_POS_ARGS, pszFormat, args);6191 va_end(args);6192 return rc;6193 # else6194 return VINF_EM_DBG_STOP;6195 # endif6196 #else6197 return VINF_SUCCESS;6198 #endif6199 }6200 6201 6202 #ifdef IN_RING36203 /**6204 * @copydoc PDMDEVHLP::pfnIOPortRegister6205 */6206 DECLINLINE(int) PDMDevHlpIOPortRegister(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTHCPTR pvUser,6207 PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,6208 PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc)6209 {6210 return pDevIns->pDevHlp->pfnIOPortRegister(pDevIns, Port, cPorts, pvUser, pfnOut, pfnIn, pfnOutStr, pfnInStr, pszDesc);6211 }6212 6213 /**6214 * @copydoc PDMDEVHLP::pfnIOPortRegisterGC6215 */6216 DECLINLINE(int) PDMDevHlpIOPortRegisterGC(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTGCPTR pvUser,6217 const char *pszOut, const char *pszIn, const char *pszOutStr,6218 const char *pszInStr, const char *pszDesc)6219 {6220 return pDevIns->pDevHlp->pfnIOPortRegisterGC(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);6221 }6222 6223 /**6224 * @copydoc PDMDEVHLP::pfnIOPortRegisterR06225 */6226 DECLINLINE(int) PDMDevHlpIOPortRegisterR0(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTR0PTR pvUser,6227 const char *pszOut, const char *pszIn, const char *pszOutStr,6228 const char *pszInStr, const char *pszDesc)6229 {6230 return pDevIns->pDevHlp->pfnIOPortRegisterR0(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);6231 }6232 6233 /**6234 * @copydoc PDMDEVHLP::pfnMMIORegister6235 */6236 DECLINLINE(int) PDMDevHlpMMIORegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTHCPTR pvUser,6237 PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, PFNIOMMMIOFILL pfnFill,6238 const char *pszDesc)6239 {6240 return pDevIns->pDevHlp->pfnMMIORegister(pDevIns, GCPhysStart, cbRange, pvUser, pfnWrite, pfnRead, pfnFill, pszDesc);6241 }6242 6243 /**6244 * @copydoc PDMDEVHLP::pfnMMIORegisterGC6245 */6246 DECLINLINE(int) PDMDevHlpMMIORegisterGC(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTGCPTR pvUser,6247 const char *pszWrite, const char *pszRead, const char *pszFill, const char *pszDesc)6248 {6249 return pDevIns->pDevHlp->pfnMMIORegisterGC(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill, pszDesc);6250 }6251 6252 /**6253 * @copydoc PDMDEVHLP::pfnMMIORegisterR06254 */6255 DECLINLINE(int) PDMDevHlpMMIORegisterR0(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTR0PTR pvUser,6256 const char *pszWrite, const char *pszRead, const char *pszFill, const char *pszDesc)6257 {6258 return pDevIns->pDevHlp->pfnMMIORegisterR0(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill, pszDesc);6259 }6260 6261 /**6262 * @copydoc PDMDEVHLP::pfnROMRegister6263 */6264 DECLINLINE(int) PDMDevHlpROMRegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, const void *pvBinary, const char *pszDesc)6265 {6266 return pDevIns->pDevHlp->pfnROMRegister(pDevIns, GCPhysStart, cbRange, pvBinary, pszDesc);6267 }6268 6269 /**6270 * @copydoc PDMDEVHLP::pfnSSMRegister6271 */6272 DECLINLINE(int) PDMDevHlpSSMRegister(PPDMDEVINS pDevIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,6273 PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,6274 PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone)6275 {6276 return pDevIns->pDevHlp->pfnSSMRegister(pDevIns, pszName, u32Instance, u32Version, cbGuess,6277 pfnSavePrep, pfnSaveExec, pfnSaveDone,6278 pfnLoadPrep, pfnLoadExec, pfnLoadDone);6279 }6280 6281 /**6282 * @copydoc PDMDEVHLP::pfnTMTimerCreate6283 */6284 DECLINLINE(int) PDMDevHlpTMTimerCreate(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer)6285 {6286 return pDevIns->pDevHlp->pfnTMTimerCreate(pDevIns, enmClock, pfnCallback, pszDesc, ppTimer);6287 }6288 6289 /**6290 * @copydoc PDMDEVHLP::pfnPCIRegister6291 */6292 DECLINLINE(int) PDMDevHlpPCIRegister(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev)6293 {6294 return pDevIns->pDevHlp->pfnPCIRegister(pDevIns, pPciDev);6295 }6296 6297 /**6298 * @copydoc PDMDEVHLP::pfnPCIIORegionRegister6299 */6300 DECLINLINE(int) PDMDevHlpPCIIORegionRegister(PPDMDEVINS pDevIns, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback)6301 {6302 return pDevIns->pDevHlp->pfnPCIIORegionRegister(pDevIns, iRegion, cbRegion, enmType, pfnCallback);6303 }6304 6305 /**6306 * @copydoc PDMDEVHLP::pfnPCISetConfigCallbacks6307 */6308 DECLINLINE(void) PDMDevHlpPCISetConfigCallbacks(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,6309 PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld)6310 {6311 pDevIns->pDevHlp->pfnPCISetConfigCallbacks(pDevIns, pPciDev, pfnRead, ppfnReadOld, pfnWrite, ppfnWriteOld);6312 }6313 6314 /**6315 * @copydoc PDMDEVHLP::pfnDriverAttach6316 */6317 DECLINLINE(int) PDMDevHlpDriverAttach(PPDMDEVINS pDevIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE *ppBaseInterface, const char *pszDesc)6318 {6319 return pDevIns->pDevHlp->pfnDriverAttach(pDevIns, iLun, pBaseInterface, ppBaseInterface, pszDesc);6320 }6321 6322 /**6323 * @copydoc PDMDEVHLP::pfnMMHeapAlloc6324 */6325 DECLINLINE(void *) PDMDevHlpMMHeapAlloc(PPDMDEVINS pDevIns, size_t cb)6326 {6327 return pDevIns->pDevHlp->pfnMMHeapAlloc(pDevIns, cb);6328 }6329 6330 /**6331 * @copydoc PDMDEVHLP::pfnMMHeapAllocZ6332 */6333 DECLINLINE(void *) PDMDevHlpMMHeapAllocZ(PPDMDEVINS pDevIns, size_t cb)6334 {6335 return pDevIns->pDevHlp->pfnMMHeapAllocZ(pDevIns, cb);6336 }6337 6338 /**6339 * @copydoc PDMDEVHLP::pfnMMHeapFree6340 */6341 DECLINLINE(void) PDMDevHlpMMHeapFree(PPDMDEVINS pDevIns, void *pv)6342 {6343 pDevIns->pDevHlp->pfnMMHeapFree(pDevIns, pv);6344 }6345 6346 /**6347 * @copydoc PDMDEVHLP::pfnDBGFInfoRegister6348 */6349 DECLINLINE(int) PDMDevHlpDBGFInfoRegister(PPDMDEVINS pDevIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDEV pfnHandler)6350 {6351 return pDevIns->pDevHlp->pfnDBGFInfoRegister(pDevIns, pszName, pszDesc, pfnHandler);6352 }6353 6354 /**6355 * @copydoc PDMDEVHLP::pfnSTAMRegister6356 */6357 DECLINLINE(void) PDMDevHlpSTAMRegister(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)6358 {6359 pDevIns->pDevHlp->pfnSTAMRegister(pDevIns, pvSample, enmType, pszName, enmUnit, pszDesc);6360 }6361 6362 /**6363 * @copydoc PDMDEVHLP::pfnSTAMRegisterF6364 */6365 DECLINLINE(void) PDMDevHlpSTAMRegisterF(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,6366 const char *pszDesc, const char *pszName, ...)6367 {6368 va_list va;6369 va_start(va, pszName);6370 pDevIns->pDevHlp->pfnSTAMRegisterV(pDevIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);6371 va_end(va);6372 }6373 6374 /**6375 * @copydoc PDMDEVHLP::pfnPDMQueueCreate6376 */6377 DECLINLINE(int) PDMDevHlpPDMQueueCreate(PPDMDEVINS pDevIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,6378 PFNPDMQUEUEDEV pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue)6379 {6380 return pDevIns->pDevHlp->pfnPDMQueueCreate(pDevIns, cbItem, cItems, cMilliesInterval, pfnCallback, fGCEnabled, ppQueue);6381 }6382 6383 /**6384 * @copydoc PDMDEVHLP::pfnCritSectInit6385 */6386 DECLINLINE(int) PDMDevHlpCritSectInit(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, const char *pszName)6387 {6388 return pDevIns->pDevHlp->pfnCritSectInit(pDevIns, pCritSect, pszName);6389 }6390 6391 /**6392 * @copydoc PDMDEVHLP::pfnUTCNow6393 */6394 DECLINLINE(PRTTIMESPEC) PDMDevHlpUTCNow(PPDMDEVINS pDevIns, PRTTIMESPEC pTime)6395 {6396 return pDevIns->pDevHlp->pfnUTCNow(pDevIns, pTime);6397 }6398 6399 /**6400 * @copydoc PDMDEVHLP::pfnGetVM6401 */6402 DECLINLINE(PVM) PDMDevHlpGetVM(PPDMDEVINS pDevIns)6403 {6404 return pDevIns->pDevHlp->pfnGetVM(pDevIns);6405 }6406 6407 /**6408 * @copydoc PDMDEVHLP::pfnPhysReadGCVirt6409 */6410 DECLINLINE(int) PDMDevHlpPhysReadGCVirt(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb)6411 {6412 return pDevIns->pDevHlp->pfnPhysReadGCVirt(pDevIns, pvDst, GCVirtSrc, cb);6413 }6414 6415 /**6416 * @copydoc PDMDEVHLP::pfnPhysWriteGCVirt6417 */6418 DECLINLINE(int) PDMDevHlpPhysWriteGCVirt(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb)6419 {6420 return pDevIns->pDevHlp->pfnPhysWriteGCVirt(pDevIns, GCVirtDst, pvSrc, cb);6421 }6422 6423 /**6424 * @copydoc PDMDEVHLP::pfnPhysReserve6425 */6426 DECLINLINE(int) PDMDevHlpPhysReserve(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const char *pszDesc)6427 {6428 return pDevIns->pDevHlp->pfnPhysReserve(pDevIns, GCPhys, cbRange, pszDesc);6429 }6430 6431 /**6432 * @copydoc PDMDEVHLP::pfnPhys2HCVirt6433 */6434 DECLINLINE(int) PDMDevHlpPhys2HCVirt(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, PRTHCPTR ppvHC)6435 {6436 return pDevIns->pDevHlp->pfnPhys2HCVirt(pDevIns, GCPhys, cbRange, ppvHC);6437 }6438 6439 /**6440 * @copydoc PDMDEVHLP::pfnPhysGCPtr2HCPtr6441 */6442 DECLINLINE(int) PDMDevHlpPhysGCPtr2HCPtr(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTHCPTR pHCPtr)6443 {6444 return pDevIns->pDevHlp->pfnPhysGCPtr2HCPtr(pDevIns, GCPtr, pHCPtr);6445 }6446 6447 /**6448 * @copydoc PDMDEVHLP::pfnA20Set6449 */6450 DECLINLINE(void) PDMDevHlpA20Set(PPDMDEVINS pDevIns, bool fEnable)6451 {6452 pDevIns->pDevHlp->pfnA20Set(pDevIns, fEnable);6453 }6454 6455 /**6456 * @copydoc PDMDEVHLP::pfnVMReset6457 */6458 DECLINLINE(int) PDMDevHlpVMReset(PPDMDEVINS pDevIns)6459 {6460 return pDevIns->pDevHlp->pfnVMReset(pDevIns);6461 }6462 6463 /**6464 * @copydoc PDMDEVHLP::pfnVMSuspend6465 */6466 DECLINLINE(int) PDMDevHlpVMSuspend(PPDMDEVINS pDevIns)6467 {6468 return pDevIns->pDevHlp->pfnVMSuspend(pDevIns);6469 }6470 6471 /**6472 * @copydoc PDMDEVHLP::pfnVMPowerOff6473 */6474 DECLINLINE(int) PDMDevHlpVMPowerOff(PPDMDEVINS pDevIns)6475 {6476 return pDevIns->pDevHlp->pfnVMPowerOff(pDevIns);6477 }6478 6479 /**6480 * @copydoc PDMDEVHLP::pfnDMARegister6481 */6482 DECLINLINE(int) PDMDevHlpDMARegister(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser)6483 {6484 return pDevIns->pDevHlp->pfnDMARegister(pDevIns, uChannel, pfnTransferHandler, pvUser);6485 }6486 6487 /**6488 * @copydoc PDMDEVHLP::pfnDMAReadMemory6489 */6490 DECLINLINE(int) PDMDevHlpDMAReadMemory(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbRead)6491 {6492 return pDevIns->pDevHlp->pfnDMAReadMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbRead);6493 }6494 6495 /**6496 * @copydoc PDMDEVHLP::pfnDMAWriteMemory6497 */6498 DECLINLINE(int) PDMDevHlpDMAWriteMemory(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbWritten)6499 {6500 return pDevIns->pDevHlp->pfnDMAWriteMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbWritten);6501 }6502 6503 /**6504 * @copydoc PDMDEVHLP::pfnDMASetDREQ6505 */6506 DECLINLINE(int) PDMDevHlpDMASetDREQ(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel)6507 {6508 return pDevIns->pDevHlp->pfnDMASetDREQ(pDevIns, uChannel, uLevel);6509 }6510 6511 /**6512 * @copydoc PDMDEVHLP::pfnDMAGetChannelMode6513 */6514 DECLINLINE(uint8_t) PDMDevHlpDMAGetChannelMode(PPDMDEVINS pDevIns, unsigned uChannel)6515 {6516 return pDevIns->pDevHlp->pfnDMAGetChannelMode(pDevIns, uChannel);6517 }6518 6519 /**6520 * @copydoc PDMDEVHLP::pfnDMASchedule6521 */6522 DECLINLINE(void) PDMDevHlpDMASchedule(PPDMDEVINS pDevIns)6523 {6524 pDevIns->pDevHlp->pfnDMASchedule(pDevIns);6525 }6526 6527 /**6528 * @copydoc PDMDEVHLP::pfnCMOSWrite6529 */6530 DECLINLINE(int) PDMDevHlpCMOSWrite(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value)6531 {6532 return pDevIns->pDevHlp->pfnCMOSWrite(pDevIns, iReg, u8Value);6533 }6534 6535 /**6536 * @copydoc PDMDEVHLP::pfnCMOSRead6537 */6538 DECLINLINE(int) PDMDevHlpCMOSRead(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value)6539 {6540 return pDevIns->pDevHlp->pfnCMOSRead(pDevIns, iReg, pu8Value);6541 }6542 6543 /**6544 * @copydoc PDMDEVHLP::pfnGetCpuId6545 */6546 DECLINLINE(void) PDMDevHlpGetCpuId(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t *pEax, uint32_t *pEbx, uint32_t *pEcx, uint32_t *pEdx)6547 {6548 pDevIns->pDevHlp->pfnGetCpuId(pDevIns, iLeaf, pEax, pEbx, pEcx, pEdx);6549 }6550 #endif /* IN_RING3 */6551 6552 6553 /**6554 * @copydoc PDMDEVHLP::pfnPCISetIrq6555 */6556 DECLINLINE(void) PDMDevHlpPCISetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)6557 {6558 #ifdef IN_GC6559 pDevIns->pDevHlpGC->pfnPCISetIrq(pDevIns, iIrq, iLevel);6560 #elif defined(IN_RING0)6561 pDevIns->pDevHlpR0->pfnPCISetIrq(pDevIns, iIrq, iLevel);6562 #else6563 pDevIns->pDevHlp->pfnPCISetIrq(pDevIns, iIrq, iLevel);6564 #endif6565 }6566 6567 /**6568 * @copydoc PDMDEVHLP::pfnPCISetIrqNoWait6569 */6570 DECLINLINE(void) PDMDevHlpPCISetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)6571 {6572 #ifdef IN_GC6573 pDevIns->pDevHlpGC->pfnPCISetIrq(pDevIns, iIrq, iLevel);6574 #elif defined(IN_RING0)6575 pDevIns->pDevHlpR0->pfnPCISetIrq(pDevIns, iIrq, iLevel);6576 #else6577 pDevIns->pDevHlp->pfnPCISetIrqNoWait(pDevIns, iIrq, iLevel);6578 #endif6579 }6580 6581 /**6582 * @copydoc PDMDEVHLP::pfnISASetIrq6583 */6584 DECLINLINE(void) PDMDevHlpISASetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)6585 {6586 #ifdef IN_GC6587 pDevIns->pDevHlpGC->pfnISASetIrq(pDevIns, iIrq, iLevel);6588 #elif defined(IN_RING0)6589 pDevIns->pDevHlpR0->pfnISASetIrq(pDevIns, iIrq, iLevel);6590 #else6591 pDevIns->pDevHlp->pfnISASetIrq(pDevIns, iIrq, iLevel);6592 #endif6593 }6594 6595 /**6596 * @copydoc PDMDEVHLP::pfnISASetIrqNoWait6597 */6598 DECLINLINE(void) PDMDevHlpISASetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)6599 {6600 #ifdef IN_GC6601 pDevIns->pDevHlpGC->pfnISASetIrq(pDevIns, iIrq, iLevel);6602 #elif defined(IN_RING0)6603 pDevIns->pDevHlpR0->pfnISASetIrq(pDevIns, iIrq, iLevel);6604 #else6605 pDevIns->pDevHlp->pfnISASetIrqNoWait(pDevIns, iIrq, iLevel);6606 #endif6607 }6608 6609 /**6610 * @copydoc PDMDEVHLP::pfnPhysRead6611 */6612 DECLINLINE(void) PDMDevHlpPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)6613 {6614 #ifdef IN_GC6615 pDevIns->pDevHlpGC->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);6616 #elif defined(IN_RING0)6617 pDevIns->pDevHlpR0->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);6618 #else6619 pDevIns->pDevHlp->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);6620 #endif6621 }6622 6623 /**6624 * @copydoc PDMDEVHLP::pfnPhysWrite6625 */6626 DECLINLINE(void) PDMDevHlpPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)6627 {6628 #ifdef IN_GC6629 pDevIns->pDevHlpGC->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);6630 #elif defined(IN_RING0)6631 pDevIns->pDevHlpR0->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);6632 #else6633 pDevIns->pDevHlp->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);6634 #endif6635 }6636 6637 /**6638 * @copydoc PDMDEVHLP::pfnA20IsEnabled6639 */6640 DECLINLINE(bool) PDMDevHlpA20IsEnabled(PPDMDEVINS pDevIns)6641 {6642 #ifdef IN_GC6643 return pDevIns->pDevHlpGC->pfnA20IsEnabled(pDevIns);6644 #elif defined(IN_RING0)6645 return pDevIns->pDevHlpR0->pfnA20IsEnabled(pDevIns);6646 #else6647 return pDevIns->pDevHlp->pfnA20IsEnabled(pDevIns);6648 #endif6649 }6650 6651 /**6652 * @copydoc PDMDEVHLP::pfnVMSetError6653 */6654 DECLINLINE(int) PDMDevHlpVMSetError(PPDMDEVINS pDevIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)6655 {6656 va_list va;6657 va_start(va, pszFormat);6658 #ifdef IN_GC6659 pDevIns->pDevHlpGC->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);6660 #elif defined(IN_RING0)6661 pDevIns->pDevHlpR0->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);6662 #else6663 pDevIns->pDevHlp->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);6664 #endif6665 va_end(va);6666 return rc;6667 }6668 6669 /**6670 * @copydoc PDMDEVHLP::pfnVMSetRuntimeError6671 */6672 DECLINLINE(int) PDMDevHlpVMSetRuntimeError(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...)6673 {6674 va_list va;6675 int rc;6676 va_start(va, pszFormat);6677 #ifdef IN_GC6678 rc = pDevIns->pDevHlpGC->pfnVMSetRuntimeErrorV(pDevIns, fFatal, pszErrorID, pszFormat, va);6679 #elif defined(IN_RING0)6680 rc = pDevIns->pDevHlpR0->pfnVMSetRuntimeErrorV(pDevIns, fFatal, pszErrorID, pszFormat, va);6681 #else6682 rc = pDevIns->pDevHlp->pfnVMSetRuntimeErrorV(pDevIns, fFatal, pszErrorID, pszFormat, va);6683 #endif6684 va_end(va);6685 return rc;6686 }6687 6688 6689 6690 /** Pointer to callbacks provided to the VBoxDeviceRegister() call. */6691 typedef struct PDMDEVREGCB *PPDMDEVREGCB;6692 6693 /**6694 * Callbacks for VBoxDeviceRegister().6695 */6696 typedef struct PDMDEVREGCB6697 {6698 /** Interface version.6699 * This is set to PDM_DEVREG_CB_VERSION. */6700 uint32_t u32Version;6701 6702 /**6703 * Registers a device with the current VM instance.6704 *6705 * @returns VBox status code.6706 * @param pCallbacks Pointer to the callback table.6707 * @param pDevReg Pointer to the device registration record.6708 * This data must be permanent and readonly.6709 */6710 DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMDEVREGCB pCallbacks, PCPDMDEVREG pDevReg));6711 6712 /**6713 * Allocate memory which is associated with current VM instance6714 * and automatically freed on it's destruction.6715 *6716 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.6717 * @param pCallbacks Pointer to the callback table.6718 * @param cb Number of bytes to allocate.6719 */6720 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVREGCB pCallbacks, size_t cb));6721 } PDMDEVREGCB;6722 6723 /** Current version of the PDMDEVREGCB structure. */6724 #define PDM_DEVREG_CB_VERSION 0xf40100006725 6726 6727 /**6728 * The VBoxDevicesRegister callback function.6729 *6730 * PDM will invoke this function after loading a device module and letting6731 * the module decide which devices to register and how to handle conflicts.6732 *6733 * @returns VBox status code.6734 * @param pCallbacks Pointer to the callback table.6735 * @param u32Version VBox version number.6736 */6737 typedef DECLCALLBACK(int) FNPDMVBOXDEVICESREGISTER(PPDMDEVREGCB pCallbacks, uint32_t u32Version);6738 6739 /** @} */6740 6741 6742 6743 6744 /** @defgroup grp_pdm_services Services6745 * @ingroup grp_pdm6746 * @{ */6747 6748 6749 /**6750 * Construct a service instance for a VM.6751 *6752 * @returns VBox status.6753 * @param pSrvIns The service instance data.6754 * If the registration structure is needed, pSrvIns->pReg points to it.6755 * @param pCfg Configuration node handle for the service. Use this to obtain the configuration6756 * of the driver instance. It's also found in pSrvIns->pCfg, but since it's primary6757 * usage is expected in this function it is passed as a parameter.6758 */6759 typedef DECLCALLBACK(int) FNPDMSRVCONSTRUCT(PPDMSRVINS pSrvIns, PCFGMNODE pCfg);6760 /** Pointer to a FNPDMSRVCONSTRUCT() function. */6761 typedef FNPDMSRVCONSTRUCT *PFNPDMSRVCONSTRUCT;6762 6763 /**6764 * Destruct a driver instance.6765 *6766 * Most VM resources are freed by the VM. This callback is provided so that any non-VM6767 * resources can be freed correctly.6768 *6769 * @param pSrvIns The service instance data.6770 */6771 typedef DECLCALLBACK(void) FNPDMSRVDESTRUCT(PPDMSRVINS pSrvIns);6772 /** Pointer to a FNPDMSRVDESTRUCT() function. */6773 typedef FNPDMSRVDESTRUCT *PFNPDMSRVDESTRUCT;6774 6775 /**6776 * Power On notification.6777 *6778 * @param pSrvIns The service instance data.6779 */6780 typedef DECLCALLBACK(void) FNPDMSRVPOWERON(PPDMSRVINS pSrvIns);6781 /** Pointer to a FNPDMSRVPOWERON() function. */6782 typedef FNPDMSRVPOWERON *PFNPDMSRVPOWERON;6783 6784 /**6785 * Reset notification.6786 *6787 * @returns VBox status.6788 * @param pSrvIns The service instance data.6789 */6790 typedef DECLCALLBACK(void) FNPDMSRVRESET(PPDMSRVINS pSrvIns);6791 /** Pointer to a FNPDMSRVRESET() function. */6792 typedef FNPDMSRVRESET *PFNPDMSRVRESET;6793 6794 /**6795 * Suspend notification.6796 *6797 * @returns VBox status.6798 * @param pSrvIns The service instance data.6799 */6800 typedef DECLCALLBACK(void) FNPDMSRVSUSPEND(PPDMSRVINS pSrvIns);6801 /** Pointer to a FNPDMSRVSUSPEND() function. */6802 typedef FNPDMSRVSUSPEND *PFNPDMSRVSUSPEND;6803 6804 /**6805 * Resume notification.6806 *6807 * @returns VBox status.6808 * @param pSrvIns The service instance data.6809 */6810 typedef DECLCALLBACK(void) FNPDMSRVRESUME(PPDMSRVINS pSrvIns);6811 /** Pointer to a FNPDMSRVRESUME() function. */6812 typedef FNPDMSRVRESUME *PFNPDMSRVRESUME;6813 6814 /**6815 * Power Off notification.6816 *6817 * @param pSrvIns The service instance data.6818 */6819 typedef DECLCALLBACK(void) FNPDMSRVPOWEROFF(PPDMSRVINS pSrvIns);6820 /** Pointer to a FNPDMSRVPOWEROFF() function. */6821 typedef FNPDMSRVPOWEROFF *PFNPDMSRVPOWEROFF;6822 6823 /**6824 * Detach notification.6825 *6826 * This is called when a driver or device is detached from the service6827 *6828 * @param pSrvIns The service instance data.6829 */6830 typedef DECLCALLBACK(void) FNPDMSRVDETACH(PPDMSRVINS pSrvIns, PPDMDEVINS pDevIns, PPDMDRVINS pDrvIns);6831 /** Pointer to a FNPDMSRVDETACH() function. */6832 typedef FNPDMSRVDETACH *PFNPDMSRVDETACH;6833 6834 6835 6836 /** PDM Service Registration Structure,6837 * This structure is used when registering a driver from6838 * VBoxServicesRegister() (HC Ring-3). PDM will continue use till6839 * the VM is terminated.6840 */6841 typedef struct PDMSRVREG6842 {6843 /** Structure version. PDM_SRVREG_VERSION defines the current version. */6844 uint32_t u32Version;6845 /** Driver name. */6846 char szServiceName[32];6847 /** The description of the driver. The UTF-8 string pointed to shall, like this structure,6848 * remain unchanged from registration till VM destruction. */6849 const char *pszDescription;6850 6851 /** Flags, combination of the PDM_SRVREG_FLAGS_* \#defines. */6852 RTUINT fFlags;6853 /** Size of the instance data. */6854 RTUINT cbInstance;6855 6856 /** Construct instance - required. */6857 PFNPDMSRVCONSTRUCT pfnConstruct;6858 /** Destruct instance - optional. */6859 PFNPDMSRVDESTRUCT pfnDestruct;6860 /** Power on notification - optional. */6861 PFNPDMSRVPOWERON pfnPowerOn;6862 /** Reset notification - optional. */6863 PFNPDMSRVRESET pfnReset;6864 /** Suspend notification - optional. */6865 PFNPDMSRVSUSPEND pfnSuspend;6866 /** Resume notification - optional. */6867 PFNPDMSRVRESUME pfnResume;6868 /** Detach notification - optional. */6869 PFNPDMSRVDETACH pfnDetach;6870 /** Power off notification - optional. */6871 PFNPDMSRVPOWEROFF pfnPowerOff;6872 6873 } PDMSRVREG;6874 /** Pointer to a PDM Driver Structure. */6875 typedef PDMSRVREG *PPDMSRVREG;6876 /** Const pointer to a PDM Driver Structure. */6877 typedef PDMSRVREG const *PCPDMSRVREG;6878 6879 6880 6881 /**6882 * PDM Service API.6883 */6884 typedef struct PDMSRVHLP6885 {6886 /** Structure version. PDM_SRVHLP_VERSION defines the current version. */6887 uint32_t u32Version;6888 6889 /**6890 * Assert that the current thread is the emulation thread.6891 *6892 * @returns True if correct.6893 * @returns False if wrong.6894 * @param pSrvIns Service instance.6895 * @param pszFile Filename of the assertion location.6896 * @param iLine Linenumber of the assertion location.6897 * @param pszFunction Function of the assertion location.6898 */6899 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMSRVINS pSrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));6900 6901 /**6902 * Assert that the current thread is NOT the emulation thread.6903 *6904 * @returns True if correct.6905 * @returns False if wrong.6906 * @param pSrvIns Service instance.6907 * @param pszFile Filename of the assertion location.6908 * @param iLine Linenumber of the assertion location.6909 * @param pszFunction Function of the assertion location.6910 */6911 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMSRVINS pSrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));6912 6913 /**6914 * Creates a timer.6915 *6916 * @returns VBox status.6917 * @param pVM The VM to create the timer in.6918 * @param pSrvIns Service instance.6919 * @param enmClock The clock to use on this timer.6920 * @param pfnCallback Callback function.6921 * @param pszDesc Pointer to description string which must stay around6922 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).6923 * @param ppTimer Where to store the timer on success.6924 */6925 DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMSRVINS pSrvIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer));6926 6927 /**6928 * Query the virtual timer frequency.6929 *6930 * @returns Frequency in Hz.6931 * @param pSrvIns Service instance.6932 * @thread Any thread.6933 */6934 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualFreq,(PPDMSRVINS pSrvIns));6935 6936 /**6937 * Query the virtual time.6938 *6939 * @returns The current virtual time.6940 * @param pSrvIns Service instance.6941 * @thread Any thread.6942 */6943 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualTime,(PPDMSRVINS pSrvIns));6944 6945 } PDMSRVHLP;6946 /** Pointer PDM Service API. */6947 typedef PDMSRVHLP *PPDMSRVHLP;6948 /** Pointer const PDM Service API. */6949 typedef const PDMSRVHLP *PCPDMSRVHLP;6950 6951 /** Current SRVHLP version number. */6952 #define PDM_SRVHLP_VERSION 0xf90100006953 6954 6955 /**6956 * PDM Service Instance.6957 */6958 typedef struct PDMSRVINS6959 {6960 /** Structure version. PDM_SRVINS_VERSION defines the current version. */6961 uint32_t u32Version;6962 6963 /** Internal data. */6964 union6965 {6966 #ifdef PDMSRVINSINT_DECLARED6967 PDMSRVINSINT s;6968 #endif6969 uint8_t padding[HC_ARCH_BITS == 32 ? 32 : 32];6970 } Internal;6971 6972 /** Pointer the PDM Service API. */6973 HCPTRTYPE(PCPDMSRVHLP) pHlp;6974 /** Pointer to driver registration structure. */6975 HCPTRTYPE(PCPDMSRVREG) pReg;6976 /** Configuration handle. */6977 HCPTRTYPE(PCFGMNODE) pCfg;6978 /** The base interface of the service.6979 * The service constructor initializes this. */6980 PDMIBASE IBase;6981 /* padding to make achInstanceData aligned at 16 byte boundrary. */6982 uint32_t au32Padding[2];6983 /** Pointer to driver instance data. */6984 HCPTRTYPE(void *) pvInstanceData;6985 /** Driver instance data. The size of this area is defined6986 * in the PDMSRVREG::cbInstanceData field. */6987 char achInstanceData[4];6988 } PDMSRVINS;6989 6990 /** Current PDMSRVREG version number. */6991 #define PDM_SRVINS_VERSION 0xf70100006992 6993 /** Converts a pointer to the PDMSRVINS::IBase to a pointer to PDMSRVINS. */6994 #define PDMIBASE_2_PDMSRV(pInterface) ( (PPDMSRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMSRVINS, IBase)) )6995 6996 6997 6998 /** Pointer to callbacks provided to the VBoxServiceRegister() call. */6999 typedef struct PDMSRVREGCB *PPDMSRVREGCB;7000 7001 /**7002 * Callbacks for VBoxServiceRegister().7003 */7004 typedef struct PDMSRVREGCB7005 {7006 /** Interface version.7007 * This is set to PDM_SRVREG_CB_VERSION. */7008 uint32_t u32Version;7009 7010 /**7011 * Registers a service with the current VM instance.7012 *7013 * @returns VBox status code.7014 * @param pCallbacks Pointer to the callback table.7015 * @param pSrvReg Pointer to the device registration record.7016 * This data must be permanent and readonly.7017 */7018 DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMSRVREGCB pCallbacks, PCPDMSRVREG pSrvReg));7019 } PDMSRVREGCB;7020 7021 /** Current version of the PDMSRVREGCB structure. */7022 #define PDM_SRVREG_CB_VERSION 0xf80100007023 7024 7025 /**7026 * The VBoxServicesRegister callback function.7027 *7028 * PDM will invoke this function after loading a device module and letting7029 * the module decide which devices to register and how to handle conflicts.7030 *7031 * @returns VBox status code.7032 * @param pCallbacks Pointer to the callback table.7033 * @param u32Version VBox version number.7034 */7035 typedef DECLCALLBACK(int) FNPDMVBOXSERVICESREGISTER(PPDMSRVREGCB pCallbacks, uint32_t u32Version);7036 7037 7038 /** @} */7039 66 7040 67 /** … … 7329 356 * @param iInstance Device instance. 7330 357 * @param ppBase Where to store the pointer to the base device interface on success. 7331 * @remark We're doing any locking ATM, so don't try call this at times when the358 * @remark We're not doing any locking ATM, so don't try call this at times when the 7332 359 * device chain is known to be updated. 7333 360 */ … … 7346 373 * @param iLun The Logical Unit to obtain the interface of. 7347 374 * @param ppBase Where to store the base interface pointer. 7348 * @remark We're doing any locking ATM, so don't try call this at times when the375 * @remark We're not doing any locking ATM, so don't try call this at times when the 7349 376 * device chain is known to be updated. 7350 377 */ … … 7360 387 * @param iLun The Logical Unit to obtain the interface of. 7361 388 * @param ppBase Where to store the base interface pointer. 7362 * @remark We're doing any locking ATM, so don't try call this at times when the389 * @remark We're not doing any locking ATM, so don't try call this at times when the 7363 390 * device chain is known to be updated. 7364 391 */ -
Property svn:keywords
changed from
-
trunk/include/VBox/types.h
r3632 r3852 132 132 /** GC pointer to a PDM Device Instance. */ 133 133 typedef GCPTRTYPE(PPDMDEVINS) PPDMDEVINSGC; 134 135 /** Pointer to a PDM USB Device Instance. */ 136 typedef struct PDMUSBINS *PPDMUSBINS; 137 /** Pointer to a pointer to a PDM USB Device Instance. */ 138 typedef PPDMUSBINS *PPPDMUSBINS; 134 139 135 140 /** Pointer to a PDM Driver Instance. */ -
trunk/include/VBox/vusb.h
r3632 r3852 33 33 /** Frequency of USB bus (from spec). */ 34 34 #define VUSB_BUS_HZ 12000000 35 36 /** @name USB Standard version flags. 37 * @{ */ 38 /** Indicates USB 1.1 support. */ 39 #define VUSB_STDVER_11 BIT(1) 40 /** Indicates USB 2.0 support. */ 41 #define VUSB_STDVER_20 BIT(2) 42 /** @} */ 43 35 44 36 45
Note:
See TracChangeset
for help on using the changeset viewer.
