VirtualBox

source: vbox/trunk/include/VBox/pdmifs.h@ 6112

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

Rework asynchronous versions of the media interface and add a async transport interface
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 97.3 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, Interfaces.
3 */
4
5/*
6 * Copyright (C) 2006-2007 innotek GmbH
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___VBox_pdmifs_h
27#define ___VBox_pdmifs_h
28
29#include <VBox/types.h>
30#include <VBox/hgcmsvc.h>
31
32__BEGIN_DECLS
33
34/** @defgroup grp_pdm_interfaces Interfaces
35 * @ingroup grp_pdm
36 * @{
37 */
38
39/**
40 * Driver interface identficators.
41 *
42 * @remark All interfaces have to be declared here. There is no such thing as
43 * private interface identifiers since they must be unique.
44 *
45 * That said, interface structures and other stuff can be put elsewhere,
46 * actually, it is best if this file is not flooded with structures that
47 * could be put closer to home.
48 */
49typedef enum PDMINTERFACE
50{
51 /** PDMIBASE - The interface everyone supports. */
52 PDMINTERFACE_BASE = 1,
53 /** PDMIMOUSEPORT - The mouse port interface. (Down) Coupled with PDMINTERFACE_MOUSE_CONNECTOR. */
54 PDMINTERFACE_MOUSE_PORT,
55 /** PDMIMOUSECONNECTOR - The mouse connector interface. (Up) Coupled with PDMINTERFACE_MOUSE_PORT. */
56 PDMINTERFACE_MOUSE_CONNECTOR,
57 /** PDMIKEYBOARDPORT - The keyboard port interface. (Down) Coupled with PDMINTERFACE_KEYBOARD_CONNECTOR. */
58 PDMINTERFACE_KEYBOARD_PORT,
59 /** PDMIKEYBOARDCONNECTOR - The keyboard connector interface. (Up) Coupled with PDMINTERFACE_KEYBOARD_PORT. */
60 PDMINTERFACE_KEYBOARD_CONNECTOR,
61 /** PDMIDISPLAYPORT - The display port interface. (Down) Coupled with PDMINTERFACE_DISPLAY_CONNECTOR. */
62 PDMINTERFACE_DISPLAY_PORT,
63 /** PDMIDISPLAYCONNECTOR - The display connector interface. (Up) Coupled with PDMINTERFACE_DISPLAY_PORT. */
64 PDMINTERFACE_DISPLAY_CONNECTOR,
65 /** PDMICHARPORT - The char notify interface. (Down) Coupled with PDMINTERFACE_CHAR. */
66 PDMINTERFACE_CHAR_PORT,
67 /** PDMICHAR - The char driver interface. (Up) Coupled with PDMINTERFACE_CHAR_PORT. */
68 PDMINTERFACE_CHAR,
69 /** PDMISTREAM - The stream driver interface (Up) No coupling.
70 * Used by a char driver to implement PDMINTERFACE_CHAR. */
71 PDMINTERFACE_STREAM,
72 /** PDMIBLOCKPORT - The block notify interface (Down) Coupled with PDMINTERFACE_BLOCK. */
73 PDMINTERFACE_BLOCK_PORT,
74 /** PDMIBLOCK - The block driver interface (Up) Coupled with PDMINTERFACE_BLOCK_PORT. */
75 PDMINTERFACE_BLOCK,
76 /** PDMIBLOCKBIOS - The block bios interface. (External) */
77 PDMINTERFACE_BLOCK_BIOS,
78 /** PDMIMOUNTNOTIFY - The mountable notification interface. (Down) Coupled with PDMINTERFACE_MOUNT. */
79 PDMINTERFACE_MOUNT_NOTIFY,
80 /** PDMIMOUNT - The mountable interface. (Up) Coupled with PDMINTERFACE_MOUNT_NOTIFY. */
81 PDMINTERFACE_MOUNT,
82 /** PDMIMEDIA - The media interface. (Up) No coupling.
83 * Used by a block unit driver to implement PDMINTERFACE_BLOCK and PDMINTERFACE_BLOCK_BIOS. */
84 PDMINTERFACE_MEDIA,
85 /** PDMIISCSITRANSPORT - The iSCSI transport interface (Up) No coupling.
86 * used by the iSCSI media driver. */
87 PDMINTERFACE_ISCSITRANSPORT,
88 /** PDMIMEDIAASYNC - Asynchronous version of the media interface (Down) Coupled with PDMINTERFACE_MEDIA_ASYNC_PORT. */
89 PDMINTERFACE_MEDIA_ASYNC,
90 /** PDMIMEDIAASYNCPORT - Asynchronous version of the media interface (Up) Coupled with PDMINTERFACE_MEDIA_ASYNC. */
91 PDMINTERFACE_MEDIA_ASYNC_PORT,
92 /** PDMIBLOCKASYNC - Asynchronous version of the block interface (Down) Coupled with PDMINTERFACE_BLOCK_ASYNC_PORT. */
93 PDMINTERFACE_BLOCK_ASYNC,
94 /** PDMIBLOCKASYNCPORT - Asynchronous version of the block interface (Up) Coupled with PDMINTERFACE_BLOCK_ASYNC. */
95 PDMINTERFACE_BLOCK_ASYNC_PORT,
96 /** PDMITRANSPORTASYNC - Transport data asynchronous to their target (Down) Coupled with PDMINTERFACE_TRANSPORT_ASYNC_PORT. */
97 PDMINTERFACE_TRANSPORT_ASYNC,
98 /** PDMITRANSPORTASYNCPORT - Transport data asynchronous to their target (Up) Coupled with PDMINTERFACE_TRANSPORT_ASYNC. */
99 PDMINTERFACE_TRANSPORT_ASYNC_PORT,
100
101
102 /** PDMINETWORKPORT - The network port interface. (Down) Coupled with PDMINTERFACE_NETWORK_CONNECTOR. */
103 PDMINTERFACE_NETWORK_PORT,
104 /** PDMINETWORKPORT - The network connector interface. (Up) Coupled with PDMINTERFACE_NETWORK_PORT. */
105 PDMINTERFACE_NETWORK_CONNECTOR,
106 /** PDMINETWORKCONFIG - The network configuartion interface. (Main) Used by the managment api. */
107 PDMINTERFACE_NETWORK_CONFIG,
108
109 /** PDMIAUDIOCONNECTOR - The audio driver interface. (Up) No coupling. */
110 PDMINTERFACE_AUDIO_CONNECTOR,
111
112 /** PDMIAUDIOSNIFFERPORT - The Audio Sniffer Device port interface. */
113 PDMINTERFACE_AUDIO_SNIFFER_PORT,
114 /** PDMIAUDIOSNIFFERCONNECTOR - The Audio Sniffer Driver connector interface. */
115 PDMINTERFACE_AUDIO_SNIFFER_CONNECTOR,
116
117 /** PDMIVMMDEVPORT - The VMM Device port interface. */
118 PDMINTERFACE_VMMDEV_PORT,
119 /** PDMIVMMDEVCONNECTOR - The VMM Device connector interface. */
120 PDMINTERFACE_VMMDEV_CONNECTOR,
121
122 /** PDMILEDPORTS - The generic LED port interface. (Down) Coupled with PDMINTERFACE_LED_CONNECTORS. */
123 PDMINTERFACE_LED_PORTS,
124 /** PDMILEDCONNECTORS - The generic LED connector interface. (Up) Coupled with PDMINTERFACE_LED_PORTS. */
125 PDMINTERFACE_LED_CONNECTORS,
126
127 /** PDMIACPIPORT - ACPI port interface. (Down) Coupled with PDMINTERFACE_ACPI_CONNECTOR. */
128 PDMINTERFACE_ACPI_PORT,
129 /** PDMIACPICONNECTOR - ACPI connector interface. (Up) Coupled with PDMINTERFACE_ACPI_PORT. */
130 PDMINTERFACE_ACPI_CONNECTOR,
131
132 /** PDMIHGCMPORT - The Host-Guest communication manager port interface. Normally implemented by VMMDev. */
133 PDMINTERFACE_HGCM_PORT,
134 /** PDMIHGCMCONNECTOR - The Host-Guest communication manager connector interface. Normally implemented by Main::VMMDevInterface. */
135 PDMINTERFACE_HGCM_CONNECTOR,
136
137 /** VUSBIROOTHUBPORT - VUSB RootHub port interface. (Down) Coupled with PDMINTERFACE_USB_RH_CONNECTOR. */
138 PDMINTERFACE_VUSB_RH_PORT,
139 /** VUSBIROOTHUBCONNECTOR - VUSB RootHub connector interface. (Up) Coupled with PDMINTERFACE_USB_RH_PORT. */
140 PDMINTERFACE_VUSB_RH_CONNECTOR,
141 /** VUSBIRHCONFIG - VUSB RootHub configuration interface. (Main) Used by the managment api. */
142 PDMINTERFACE_VUSB_RH_CONFIG,
143
144 /** VUSBROOTHUBCONNECTOR - VUSB Device interface. (Up) No coupling. */
145 PDMINTERFACE_VUSB_DEVICE,
146
147 /** PDMIHOSTDEVICEPORT - The Host Device port interface. (Down) Coupled with PDMINTERFACE_HOST_DEVICE_CONNECTOR. */
148 PDMINTERFACE_HOST_DEVICE_PORT,
149 /** PDMIHOSTDEVICECONNECTOR - The Host device connector interface (Up) Coupled with PDMINTERFACE_HOST_DEVICE_PORT. */
150 PDMINTERFACE_HOST_DEVICE_CONNECTOR,
151
152 /** Maximum interface number. */
153 PDMINTERFACE_MAX
154} PDMINTERFACE;
155
156
157/**
158 * PDM Driver Base Interface.
159 */
160typedef struct PDMIBASE
161{
162 /**
163 * Queries an interface to the driver.
164 *
165 * @returns Pointer to interface.
166 * @returns NULL if the interface was not supported by the driver.
167 * @param pInterface Pointer to this interface structure.
168 * @param enmInterface The requested interface identification.
169 * @thread Any thread.
170 */
171 DECLR3CALLBACKMEMBER(void *, pfnQueryInterface,(struct PDMIBASE *pInterface, PDMINTERFACE enmInterface));
172} PDMIBASE;
173
174
175/**
176 * Dummy interface.
177 *
178 * This is used to typedef other dummy interfaces. The purpose of a dummy
179 * interface is to validate the logical function of a driver/device and
180 * full a natural interface pair.
181 */
182typedef struct PDMIDUMMY
183{
184 RTHCPTR pvDummy;
185} PDMIDUMMY;
186
187
188/** Pointer to a mouse port interface. */
189typedef struct PDMIMOUSEPORT *PPDMIMOUSEPORT;
190/**
191 * Mouse port interface.
192 * Pair with PDMIMOUSECONNECTOR.
193 */
194typedef struct PDMIMOUSEPORT
195{
196 /**
197 * Puts a mouse event.
198 * This is called by the source of mouse events. The event will be passed up until the
199 * topmost driver, which then calls the registered event handler.
200 *
201 * @returns VBox status code.
202 * @param pInterface Pointer to this interface structure.
203 * @param i32DeltaX The X delta.
204 * @param i32DeltaY The Y delta.
205 * @param i32DeltaZ The Z delta.
206 * @param fButtonStates The button states, see the PDMIMOUSEPORT_BUTTON_* \#defines.
207 * @thread The emulation thread.
208 */
209 DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIMOUSEPORT pInterface, int32_t i32DeltaX, int32_t i32DeltaY, int32_t i32DeltaZ, uint32_t fButtonStates));
210} PDMIMOUSEPORT;
211
212/** Mouse button defines for PDMIMOUSEPORT::pfnPutEvent.
213 * @{ */
214#define PDMIMOUSEPORT_BUTTON_LEFT RT_BIT(0)
215#define PDMIMOUSEPORT_BUTTON_RIGHT RT_BIT(1)
216#define PDMIMOUSEPORT_BUTTON_MIDDLE RT_BIT(2)
217/** @} */
218
219
220/**
221 * Mouse connector interface.
222 * Pair with PDMIMOUSEPORT.
223 */
224typedef PDMIDUMMY PDMIMOUSECONNECTOR;
225 /** Pointer to a mouse connector interface. */
226typedef PDMIMOUSECONNECTOR *PPDMIMOUSECONNECTOR;
227
228
229/** Pointer to a keyboard port interface. */
230typedef struct PDMIKEYBOARDPORT *PPDMIKEYBOARDPORT;
231/**
232 * Keyboard port interface.
233 * Pair with PDMIKEYBOARDCONNECTOR.
234 */
235typedef struct PDMIKEYBOARDPORT
236{
237 /**
238 * Puts a keyboard event.
239 * This is called by the source of keyboard events. The event will be passed up until the
240 * topmost driver, which then calls the registered event handler.
241 *
242 * @returns VBox status code.
243 * @param pInterface Pointer to this interface structure.
244 * @param u8KeyCode The keycode to queue.
245 * @thread The emulation thread.
246 */
247 DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIKEYBOARDPORT pInterface, uint8_t u8KeyCode));
248} PDMIKEYBOARDPORT;
249
250/**
251 * Keyboard LEDs.
252 */
253typedef enum PDMKEYBLEDS
254{
255 /** No leds. */
256 PDMKEYBLEDS_NONE = 0x0000,
257 /** Num Lock */
258 PDMKEYBLEDS_NUMLOCK = 0x0001,
259 /** Caps Lock */
260 PDMKEYBLEDS_CAPSLOCK = 0x0002,
261 /** Scroll Lock */
262 PDMKEYBLEDS_SCROLLLOCK = 0x0004
263} PDMKEYBLEDS;
264
265/** Pointer to keyboard connector interface. */
266typedef struct PDMIKEYBOARDCONNECTOR *PPDMIKEYBOARDCONNECTOR;
267
268
269/**
270 * Keyboard connector interface.
271 * Pair with PDMIKEYBOARDPORT
272 */
273typedef struct PDMIKEYBOARDCONNECTOR
274{
275 /**
276 * Notifies the the downstream driver about an LED change initiated by the guest.
277 *
278 * @param pInterface Pointer to the this interface.
279 * @param enmLeds The new led mask.
280 */
281 DECLR3CALLBACKMEMBER(void, pfnLedStatusChange,(PPDMIKEYBOARDCONNECTOR pInterface, PDMKEYBLEDS enmLeds));
282
283} PDMIKEYBOARDCONNECTOR;
284
285
286
287/** Pointer to a display port interface. */
288typedef struct PDMIDISPLAYPORT *PPDMIDISPLAYPORT;
289/**
290 * Display port interface.
291 * Pair with PDMIDISPLAYCONNECTOR.
292 */
293typedef struct PDMIDISPLAYPORT
294{
295 /**
296 * Update the display with any changed regions.
297 *
298 * Flushes any display changes to the memory pointed to by the
299 * PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect()
300 * while doing so.
301 *
302 * @returns VBox status code.
303 * @param pInterface Pointer to this interface.
304 * @thread The emulation thread.
305 */
306 DECLR3CALLBACKMEMBER(int, pfnUpdateDisplay,(PPDMIDISPLAYPORT pInterface));
307
308 /**
309 * Update the entire display.
310 *
311 * Flushes the entire display content to the memory pointed to by the
312 * PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect().
313 *
314 * @returns VBox status code.
315 * @param pInterface Pointer to this interface.
316 * @thread The emulation thread.
317 */
318 DECLR3CALLBACKMEMBER(int, pfnUpdateDisplayAll,(PPDMIDISPLAYPORT pInterface));
319
320 /**
321 * Return the current guest color depth in bits per pixel (bpp).
322 *
323 * As the graphics card is able to provide display updates with the bpp
324 * requested by the host, this method can be used to query the actual
325 * guest color depth.
326 *
327 * @returns VBox status code.
328 * @param pInterface Pointer to this interface.
329 * @param pcBits Where to store the current guest color depth.
330 * @thread Any thread.
331 */
332 DECLR3CALLBACKMEMBER(int, pfnQueryColorDepth,(PPDMIDISPLAYPORT pInterface, uint32_t *pcBits));
333
334 /**
335 * Sets the refresh rate and restart the timer.
336 * The rate is defined as the minimum interval between the return of
337 * one PDMIDISPLAYPORT::pfnRefresh() call to the next one.
338 *
339 * The interval timer will be restarted by this call. So at VM startup
340 * this function must be called to start the refresh cycle. The refresh
341 * rate is not saved, but have to be when resuming a loaded VM state.
342 *
343 * @returns VBox status code.
344 * @param pInterface Pointer to this interface.
345 * @param cMilliesInterval Number of millies between two refreshes.
346 * @thread Any thread.
347 */
348 DECLR3CALLBACKMEMBER(int, pfnSetRefreshRate,(PPDMIDISPLAYPORT pInterface, uint32_t cMilliesInterval));
349
350 /**
351 * Create a 32-bbp snapshot of the display.
352 *
353 * This will create a 32-bbp bitmap with dword aligned scanline length. Because
354 * of a wish for no locks in the graphics device, this must be called from the
355 * emulation thread.
356 *
357 * @param pInterface Pointer to this interface.
358 * @param pvData Pointer the buffer to copy the bits to.
359 * @param cbData Size of the buffer.
360 * @param pcx Where to store the width of the bitmap. (optional)
361 * @param pcy Where to store the height of the bitmap. (optional)
362 * @param pcbData Where to store the actual size of the bitmap. (optional)
363 * @thread The emulation thread.
364 */
365 DECLR3CALLBACKMEMBER(int, pfnSnapshot,(PPDMIDISPLAYPORT pInterface, void *pvData, size_t cbData, uint32_t *pcx, uint32_t *pcy, size_t *pcbData));
366
367 /**
368 * Copy bitmap to the display.
369 *
370 * This will convert and copy a 32-bbp bitmap (with dword aligned scanline length) to
371 * the memory pointed to by the PDMIDISPLAYCONNECTOR interface.
372 *
373 * @param pInterface Pointer to this interface.
374 * @param pvData Pointer to the bitmap bits.
375 * @param x The upper left corner x coordinate of the destination rectangle.
376 * @param y The upper left corner y coordinate of the destination rectangle.
377 * @param cx The width of the source and destination rectangles.
378 * @param cy The height of the source and destination rectangles.
379 * @thread The emulation thread.
380 * @remark This is just a convenience for using the bitmap conversions of the
381 * graphics device.
382 */
383 DECLR3CALLBACKMEMBER(int, pfnDisplayBlt,(PPDMIDISPLAYPORT pInterface, const void *pvData, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
384
385 /**
386 * Render a rectangle from guest VRAM to Framebuffer.
387 *
388 * @param pInterface Pointer to this interface.
389 * @param x The upper left corner x coordinate of the rectangle to be updated.
390 * @param y The upper left corner y coordinate of the rectangle to be updated.
391 * @param cx The width of the rectangle to be updated.
392 * @param cy The height of the rectangle to be updated.
393 * @thread The emulation thread.
394 */
395 DECLR3CALLBACKMEMBER(void, pfnUpdateDisplayRect,(PPDMIDISPLAYPORT pInterface, int32_t x, int32_t y, uint32_t cx, uint32_t cy));
396
397 /**
398 * Inform the VGA device whether the Display is directly using the guest VRAM and there is no need
399 * to render the VRAM to the framebuffer memory.
400 *
401 * @param pInterface Pointer to this interface.
402 * @param fRender Whether the VRAM content must be rendered to the framebuffer.
403 * @thread The emulation thread.
404 */
405 DECLR3CALLBACKMEMBER(void, pfnSetRenderVRAM,(PPDMIDISPLAYPORT pInterface, bool fRender));
406
407} PDMIDISPLAYPORT;
408
409
410/** Pointer to a display connector interface. */
411typedef struct PDMIDISPLAYCONNECTOR *PPDMIDISPLAYCONNECTOR;
412/**
413 * Display connector interface.
414 * Pair with PDMIDISPLAYPORT.
415 */
416typedef struct PDMIDISPLAYCONNECTOR
417{
418 /**
419 * Resize the display.
420 * This is called when the resolution changes. This usually happens on
421 * request from the guest os, but may also happen as the result of a reset.
422 * If the callback returns VINF_VGA_RESIZE_IN_PROGRESS, the caller (VGA device)
423 * must not access the connector and return.
424 *
425 * @returns VINF_SUCCESS if the framebuffer resize was completed,
426 * VINF_VGA_RESIZE_IN_PROGRESS if resize takes time and not yet finished.
427 * @param pInterface Pointer to this interface.
428 * @param cBits Color depth (bits per pixel) of the new video mode.
429 * @param pvVRAM Address of the guest VRAM.
430 * @param cbLine Size in bytes of a single scan line.
431 * @param cx New display width.
432 * @param cy New display height.
433 * @thread The emulation thread.
434 */
435 DECLR3CALLBACKMEMBER(int, pfnResize,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t cBits, void *pvVRAM, uint32_t cbLine, uint32_t cx, uint32_t cy));
436
437 /**
438 * Update a rectangle of the display.
439 * PDMIDISPLAYPORT::pfnUpdateDisplay is the caller.
440 *
441 * @param pInterface Pointer to this interface.
442 * @param x The upper left corner x coordinate of the rectangle.
443 * @param y The upper left corner y coordinate of the rectangle.
444 * @param cx The width of the rectangle.
445 * @param cy The height of the rectangle.
446 * @thread The emulation thread.
447 */
448 DECLR3CALLBACKMEMBER(void, pfnUpdateRect,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
449
450 /**
451 * Refresh the display.
452 *
453 * The interval between these calls is set by
454 * PDMIDISPLAYPORT::pfnSetRefreshRate(). The driver should call
455 * PDMIDISPLAYPORT::pfnUpdateDisplay() if it wishes to refresh the
456 * display. PDMIDISPLAYPORT::pfnUpdateDisplay calls pfnUpdateRect with
457 * the changed rectangles.
458 *
459 * @param pInterface Pointer to this interface.
460 * @thread The emulation thread.
461 */
462 DECLR3CALLBACKMEMBER(void, pfnRefresh,(PPDMIDISPLAYCONNECTOR pInterface));
463
464 /**
465 * Reset the display.
466 *
467 * Notification message when the graphics card has been reset.
468 *
469 * @param pInterface Pointer to this interface.
470 * @thread The emulation thread.
471 */
472 DECLR3CALLBACKMEMBER(void, pfnReset,(PPDMIDISPLAYCONNECTOR pInterface));
473
474 /**
475 * LFB video mode enter/exit.
476 *
477 * Notification message when LinearFrameBuffer video mode is enabled/disabled.
478 *
479 * @param pInterface Pointer to this interface.
480 * @param fEnabled false - LFB mode was disabled,
481 * true - an LFB mode was disabled
482 * @thread The emulation thread.
483 */
484 DECLR3CALLBACKMEMBER(void, pfnLFBModeChange, (PPDMIDISPLAYCONNECTOR pInterface, bool fEnabled));
485
486 /**
487 * Process the guest graphics adapter information.
488 *
489 * Direct notification from guest to the display connector.
490 *
491 * @param pInterface Pointer to this interface.
492 * @param pvVRAM Address of the guest VRAM.
493 * @param u32VRAMSize Size of the guest VRAM.
494 * @thread The emulation thread.
495 */
496 DECLR3CALLBACKMEMBER(void, pfnProcessAdapterData, (PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, uint32_t u32VRAMSize));
497
498 /**
499 * Process the guest display information.
500 *
501 * Direct notification from guest to the display connector.
502 *
503 * @param pInterface Pointer to this interface.
504 * @param pvVRAM Address of the guest VRAM.
505 * @param uScreenId The index of the guest display to be processed.
506 * @thread The emulation thread.
507 */
508 DECLR3CALLBACKMEMBER(void, pfnProcessDisplayData, (PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, unsigned uScreenId));
509
510
511 /** Read-only attributes.
512 * For preformance reasons some readonly attributes are kept in the interface.
513 * We trust the interface users to respect the readonlyness of these.
514 * @{
515 */
516 /** Pointer to the display data buffer. */
517 uint8_t *pu8Data;
518 /** Size of a scanline in the data buffer. */
519 uint32_t cbScanline;
520 /** The color depth (in bits) the graphics card is supposed to provide. */
521 uint32_t cBits;
522 /** The display width. */
523 uint32_t cx;
524 /** The display height. */
525 uint32_t cy;
526 /** @} */
527} PDMIDISPLAYCONNECTOR;
528
529
530
531/**
532 * Block drive type.
533 */
534typedef enum PDMBLOCKTYPE
535{
536 /** Error (for the query function). */
537 PDMBLOCKTYPE_ERROR = 1,
538 /** 360KB 5 1/4" floppy drive. */
539 PDMBLOCKTYPE_FLOPPY_360,
540 /** 720KB 3 1/2" floppy drive. */
541 PDMBLOCKTYPE_FLOPPY_720,
542 /** 1.2MB 5 1/4" floppy drive. */
543 PDMBLOCKTYPE_FLOPPY_1_20,
544 /** 1.44MB 3 1/2" floppy drive. */
545 PDMBLOCKTYPE_FLOPPY_1_44,
546 /** 2.88MB 3 1/2" floppy drive. */
547 PDMBLOCKTYPE_FLOPPY_2_88,
548 /** CDROM drive. */
549 PDMBLOCKTYPE_CDROM,
550 /** DVD drive. */
551 PDMBLOCKTYPE_DVD,
552 /** Hard disk drive. */
553 PDMBLOCKTYPE_HARD_DISK
554} PDMBLOCKTYPE;
555
556
557/**
558 * Block raw command data transfer direction.
559 */
560typedef enum PDMBLOCKTXDIR
561{
562 PDMBLOCKTXDIR_NONE = 0,
563 PDMBLOCKTXDIR_FROM_DEVICE,
564 PDMBLOCKTXDIR_TO_DEVICE
565} PDMBLOCKTXDIR;
566
567/**
568 * Block notify interface.
569 * Pair with PDMIBLOCK.
570 */
571typedef PDMIDUMMY PDMIBLOCKPORT;
572/** Pointer to a block notify interface (dummy). */
573typedef PDMIBLOCKPORT *PPDMIBLOCKPORT;
574
575/** Pointer to a block interface. */
576typedef struct PDMIBLOCK *PPDMIBLOCK;
577/**
578 * Block interface.
579 * Pair with PDMIBLOCKPORT.
580 */
581typedef struct PDMIBLOCK
582{
583 /**
584 * Read bits.
585 *
586 * @returns VBox status code.
587 * @param pInterface Pointer to the interface structure containing the called function pointer.
588 * @param off Offset to start reading from.
589 * @param pvBuf Where to store the read bits.
590 * @param cbRead Number of bytes to read.
591 * @thread Any thread.
592 */
593 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIBLOCK pInterface, uint64_t off, void *pvBuf, size_t cbRead));
594
595 /**
596 * Write bits.
597 *
598 * @returns VBox status code.
599 * @param pInterface Pointer to the interface structure containing the called function pointer.
600 * @param off Offset to start writing at.
601 * @param pvBuf Where to store the write bits.
602 * @param cbWrite Number of bytes to write.
603 * @thread Any thread.
604 */
605 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIBLOCK pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));
606
607 /**
608 * Make sure that the bits written are actually on the storage medium.
609 *
610 * @returns VBox status code.
611 * @param pInterface Pointer to the interface structure containing the called function pointer.
612 * @thread Any thread.
613 */
614 DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIBLOCK pInterface));
615
616 /**
617 * Send a raw command to the underlying device (CDROM).
618 * This method is optional (i.e. the function pointer may be NULL).
619 *
620 * @returns VBox status code.
621 * @param pInterface Pointer to the interface structure containing the called function pointer.
622 * @param pbCmd Offset to start reading from.
623 * @param enmTxDir Direction of transfer.
624 * @param pvBuf Pointer tp the transfer buffer.
625 * @param cbBuf Size of the transfer buffer.
626 * @param pbSenseKey Status of the command (when return value is VERR_DEV_IO_ERROR).
627 * @param cTimeoutMillies Command timeout in milliseconds.
628 * @thread Any thread.
629 */
630 DECLR3CALLBACKMEMBER(int, pfnSendCmd,(PPDMIBLOCK pInterface, const uint8_t *pbCmd, PDMBLOCKTXDIR enmTxDir, void *pvBuf, size_t *pcbBuf, uint8_t *pbSenseKey, uint32_t cTimeoutMillies));
631
632 /**
633 * Check if the media is readonly or not.
634 *
635 * @returns true if readonly.
636 * @returns false if read/write.
637 * @param pInterface Pointer to the interface structure containing the called function pointer.
638 * @thread Any thread.
639 */
640 DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIBLOCK pInterface));
641
642 /**
643 * Gets the media size in bytes.
644 *
645 * @returns Media size in bytes.
646 * @param pInterface Pointer to the interface structure containing the called function pointer.
647 * @thread Any thread.
648 */
649 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIBLOCK pInterface));
650
651 /**
652 * Gets the block drive type.
653 *
654 * @returns block drive type.
655 * @param pInterface Pointer to the interface structure containing the called function pointer.
656 * @thread Any thread.
657 */
658 DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCK pInterface));
659
660 /**
661 * Gets the UUID of the block drive.
662 * Don't return the media UUID if it's removable.
663 *
664 * @returns VBox status code.
665 * @param pInterface Pointer to the interface structure containing the called function pointer.
666 * @param pUuid Where to store the UUID on success.
667 * @thread Any thread.
668 */
669 DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIBLOCK pInterface, PRTUUID pUuid));
670} PDMIBLOCK;
671
672
673/** Pointer to a mount interface. */
674typedef struct PDMIMOUNTNOTIFY *PPDMIMOUNTNOTIFY;
675/**
676 * Block interface.
677 * Pair with PDMIMOUNT.
678 */
679typedef struct PDMIMOUNTNOTIFY
680{
681 /**
682 * Called when a media is mounted.
683 *
684 * @param pInterface Pointer to the interface structure containing the called function pointer.
685 * @thread The emulation thread.
686 */
687 DECLR3CALLBACKMEMBER(void, pfnMountNotify,(PPDMIMOUNTNOTIFY pInterface));
688
689 /**
690 * Called when a media is unmounted
691 * @param pInterface Pointer to the interface structure containing the called function pointer.
692 * @thread The emulation thread.
693 */
694 DECLR3CALLBACKMEMBER(void, pfnUnmountNotify,(PPDMIMOUNTNOTIFY pInterface));
695} PDMIMOUNTNOTIFY;
696
697
698/* Pointer to mount interface. */
699typedef struct PDMIMOUNT *PPDMIMOUNT;
700/**
701 * Mount interface.
702 * Pair with PDMIMOUNTNOTIFY.
703 */
704typedef struct PDMIMOUNT
705{
706 /**
707 * Mount a media.
708 *
709 * This will not unmount any currently mounted media!
710 *
711 * @returns VBox status code.
712 * @param pInterface Pointer to the interface structure containing the called function pointer.
713 * @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have
714 * constructed a configuration which can be attached to the bottom driver.
715 * @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.
716 * @thread The emulation thread.
717 */
718 DECLR3CALLBACKMEMBER(int, pfnMount,(PPDMIMOUNT pInterface, const char *pszFilename, const char *pszCoreDriver));
719
720 /**
721 * Unmount the media.
722 *
723 * The driver will validate and pass it on. On the rebounce it will decide whether or not to detach it self.
724 *
725 * @returns VBox status code.
726 * @param pInterface Pointer to the interface structure containing the called function pointer.
727 * @thread The emulation thread.
728 * @param fForce Force the unmount, even for locked media.
729 * @thread The emulation thread.
730 */
731 DECLR3CALLBACKMEMBER(int, pfnUnmount,(PPDMIMOUNT pInterface, bool fForce));
732
733 /**
734 * Checks if a media is mounted.
735 *
736 * @returns true if mounted.
737 * @returns false if not mounted.
738 * @param pInterface Pointer to the interface structure containing the called function pointer.
739 * @thread Any thread.
740 */
741 DECLR3CALLBACKMEMBER(bool, pfnIsMounted,(PPDMIMOUNT pInterface));
742
743 /**
744 * Locks the media, preventing any unmounting of it.
745 *
746 * @returns VBox status code.
747 * @param pInterface Pointer to the interface structure containing the called function pointer.
748 * @thread The emulation thread.
749 */
750 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMIMOUNT pInterface));
751
752 /**
753 * Unlocks the media, canceling previous calls to pfnLock().
754 *
755 * @returns VBox status code.
756 * @param pInterface Pointer to the interface structure containing the called function pointer.
757 * @thread The emulation thread.
758 */
759 DECLR3CALLBACKMEMBER(int, pfnUnlock,(PPDMIMOUNT pInterface));
760
761 /**
762 * Checks if a media is locked.
763 *
764 * @returns true if locked.
765 * @returns false if not locked.
766 * @param pInterface Pointer to the interface structure containing the called function pointer.
767 * @thread Any thread.
768 */
769 DECLR3CALLBACKMEMBER(bool, pfnIsLocked,(PPDMIMOUNT pInterface));
770} PDMIBLOCKMOUNT;
771
772/**
773 * BIOS translation mode.
774 */
775typedef enum PDMBIOSTRANSLATION
776{
777 /** No translation. */
778 PDMBIOSTRANSLATION_NONE = 1,
779 /** LBA translation. */
780 PDMBIOSTRANSLATION_LBA,
781 /** Automatic select mode. */
782 PDMBIOSTRANSLATION_AUTO
783} PDMBIOSTRANSLATION;
784
785/** Pointer to BIOS translation mode. */
786typedef PDMBIOSTRANSLATION *PPDMBIOSTRANSLATION;
787
788/** Pointer to a media interface. */
789typedef struct PDMIMEDIA *PPDMIMEDIA;
790/**
791 * Media interface.
792 * Makes up the fundation for PDMIBLOCK and PDMIBLOCKBIOS.
793 */
794typedef struct PDMIMEDIA
795{
796 /**
797 * Read bits.
798 *
799 * @returns VBox status code.
800 * @param pInterface Pointer to the interface structure containing the called function pointer.
801 * @param off Offset to start reading from.
802 * @param pvBuf Where to store the read bits.
803 * @param cbRead Number of bytes to read.
804 * @thread Any thread.
805 */
806 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIMEDIA pInterface, uint64_t off, void *pvBuf, size_t cbRead));
807
808 /**
809 * Write bits.
810 *
811 * @returns VBox status code.
812 * @param pInterface Pointer to the interface structure containing the called function pointer.
813 * @param off Offset to start writing at.
814 * @param pvBuf Where to store the write bits.
815 * @param cbWrite Number of bytes to write.
816 * @thread Any thread.
817 */
818 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIMEDIA pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));
819
820 /**
821 * Make sure that the bits written are actually on the storage medium.
822 *
823 * @returns VBox status code.
824 * @param pInterface Pointer to the interface structure containing the called function pointer.
825 * @thread Any thread.
826 */
827 DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIMEDIA pInterface));
828
829 /**
830 * Get the media size in bytes.
831 *
832 * @returns Media size in bytes.
833 * @param pInterface Pointer to the interface structure containing the called function pointer.
834 * @thread Any thread.
835 */
836 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIMEDIA pInterface));
837
838 /**
839 * Check if the media is readonly or not.
840 *
841 * @returns true if readonly.
842 * @returns false if read/write.
843 * @param pInterface Pointer to the interface structure containing the called function pointer.
844 * @thread Any thread.
845 */
846 DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIMEDIA pInterface));
847
848 /**
849 * Get stored media geometry - BIOS property.
850 * This is an optional feature of a media.
851 *
852 * @returns VBox status code.
853 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
854 * @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetGeometry() yet.
855 * @param pInterface Pointer to the interface structure containing the called function pointer.
856 * @param pcCylinders Number of cylinders.
857 * @param pcHeads Number of heads.
858 * @param pcSectors Number of sectors. This number is 1-based.
859 * @remark This have no influence on the read/write operations.
860 * @thread Any thread.
861 */
862 DECLR3CALLBACKMEMBER(int, pfnBiosGetGeometry,(PPDMIMEDIA pInterface, uint32_t *pcCylinders, uint32_t *pcHeads, uint32_t *pcSectors));
863
864 /**
865 * Store the media geometry - BIOS property.
866 * This is an optional feature of a media.
867 *
868 * @returns VBox status code.
869 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
870 * @param pInterface Pointer to the interface structure containing the called function pointer.
871 * @param cCylinders Number of cylinders.
872 * @param cHeads Number of heads.
873 * @param cSectors Number of sectors. This number is 1-based.
874 * @remark This have no influence on the read/write operations.
875 * @thread The emulation thread.
876 */
877 DECLR3CALLBACKMEMBER(int, pfnBiosSetGeometry,(PPDMIMEDIA pInterface, uint32_t cCylinders, uint32_t cHeads, uint32_t cSectors));
878
879 /**
880 * Get stored geometry translation mode - BIOS property.
881 * This is an optional feature of a media.
882 *
883 * @returns VBox status code.
884 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry translation mode.
885 * @returns VERR_PDM_TRANSLATION_NOT_SET if the translation hasn't been set using pfnBiosSetTranslation() yet.
886 * @param pInterface Pointer to the interface structure containing the called function pointer.
887 * @param penmTranslation Where to store the translation type.
888 * @remark This have no influence on the read/write operations.
889 * @thread Any thread.
890 */
891 DECLR3CALLBACKMEMBER(int, pfnBiosGetTranslation,(PPDMIMEDIA pInterface, PPDMBIOSTRANSLATION penmTranslation));
892
893 /**
894 * Store media geometry - BIOS property.
895 * This is an optional feature of a media.
896 *
897 * @returns VBox status code.
898 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
899 * @param pInterface Pointer to the interface structure containing the called function pointer.
900 * @param enmTranslation The translation type.
901 * @remark This have no influence on the read/write operations.
902 * @thread The emulation thread.
903 */
904 DECLR3CALLBACKMEMBER(int, pfnBiosSetTranslation,(PPDMIMEDIA pInterface, PDMBIOSTRANSLATION enmTranslation));
905
906 /**
907 * Gets the UUID of the media drive.
908 *
909 * @returns VBox status code.
910 * @param pInterface Pointer to the interface structure containing the called function pointer.
911 * @param pUuid Where to store the UUID on success.
912 * @thread Any thread.
913 */
914 DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIMEDIA pInterface, PRTUUID pUuid));
915
916} PDMIMEDIA;
917
918
919/** Pointer to a block BIOS interface. */
920typedef struct PDMIBLOCKBIOS *PPDMIBLOCKBIOS;
921/**
922 * Media BIOS interface.
923 * The interface the getting and setting properties which the BIOS/CMOS care about.
924 */
925typedef struct PDMIBLOCKBIOS
926{
927 /**
928 * Get stored media geometry - BIOS property.
929 * This is an optional feature of a media.
930 *
931 * @returns VBox status code.
932 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
933 * @param pInterface Pointer to the interface structure containing the called function pointer.
934 * @param pcCylinders Number of cylinders.
935 * @param pcHeads Number of heads.
936 * @param pcSectors Number of sectors. This number is 1-based.
937 * @remark This have no influence on the read/write operations.
938 * @thread Any thread.
939 */
940 DECLR3CALLBACKMEMBER(int, pfnGetGeometry,(PPDMIBLOCKBIOS pInterface, uint32_t *pcCylinders, uint32_t *pcHeads, uint32_t *pcSectors));
941
942 /**
943 * Store the media geometry - BIOS property.
944 * This is an optional feature of a media.
945 *
946 * @returns VBox status code.
947 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
948 * @param pInterface Pointer to the interface structure containing the called function pointer.
949 * @param cCylinders Number of cylinders.
950 * @param cHeads Number of heads.
951 * @param cSectors Number of sectors. This number is 1-based.
952 * @remark This have no influence on the read/write operations.
953 * @thread The emulation thread.
954 */
955 DECLR3CALLBACKMEMBER(int, pfnSetGeometry,(PPDMIBLOCKBIOS pInterface, uint32_t cCylinders, uint32_t cHeads, uint32_t cSectors));
956
957 /**
958 * Get stored geometry translation mode - BIOS property.
959 * This is an optional feature of a media.
960 *
961 * @returns VBox status code.
962 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry translation mode.
963 * @param pInterface Pointer to the interface structure containing the called function pointer.
964 * @param penmTranslation Where to store the translation type.
965 * @remark This have no influence on the read/write operations.
966 * @thread Any thread.
967 */
968 DECLR3CALLBACKMEMBER(int, pfnGetTranslation,(PPDMIBLOCKBIOS pInterface, PPDMBIOSTRANSLATION penmTranslation));
969
970 /**
971 * Store media geometry - BIOS property.
972 * This is an optional feature of a media.
973 *
974 * @returns VBox status code.
975 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
976 * @param pInterface Pointer to the interface structure containing the called function pointer.
977 * @param enmTranslation The translation type.
978 * @remark This have no influence on the read/write operations.
979 * @thread The emulation thread.
980 */
981 DECLR3CALLBACKMEMBER(int, pfnSetTranslation,(PPDMIBLOCKBIOS pInterface, PDMBIOSTRANSLATION enmTranslation));
982
983 /**
984 * Checks if the device should be visible to the BIOS or not.
985 *
986 * @returns true if the device is visible to the BIOS.
987 * @returns false if the device is not visible to the BIOS.
988 * @param pInterface Pointer to the interface structure containing the called function pointer.
989 * @thread Any thread.
990 */
991 DECLR3CALLBACKMEMBER(bool, pfnIsVisible,(PPDMIBLOCKBIOS pInterface));
992
993 /**
994 * Gets the block drive type.
995 *
996 * @returns block drive type.
997 * @param pInterface Pointer to the interface structure containing the called function pointer.
998 * @thread Any thread.
999 */
1000 DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCKBIOS pInterface));
1001
1002} PDMIBLOCKBIOS;
1003
1004
1005/** Pointer to a static block core driver interface. */
1006typedef struct PDMIMEDIASTATIC *PPDMIMEDIASTATIC;
1007/**
1008 * Static block core driver interface.
1009 */
1010typedef struct PDMIMEDIASTATIC
1011{
1012 /**
1013 * Check if the specified file is a format which the core driver can handle.
1014 *
1015 * @returns true / false accordingly.
1016 * @param pInterface Pointer to the interface structure containing the called function pointer.
1017 * @param pszFilename Name of the file to probe.
1018 */
1019 DECLR3CALLBACKMEMBER(bool, pfnCanHandle,(PPDMIMEDIASTATIC pInterface, const char *pszFilename));
1020} PDMIMEDIASTATIC;
1021
1022
1023/** Pointer to an iSCSI Request PDU buffer. */
1024typedef struct ISCSIREQ *PISCSIREQ;
1025/**
1026 * iSCSI Request PDU buffer (gather).
1027 */
1028typedef struct ISCSIREQ
1029{
1030 /** Length of PDU segment in bytes. */
1031 size_t cbSeg;
1032 /** Pointer to PDU segment. */
1033 const void *pcvSeg;
1034} ISCSIREQ;
1035
1036/** Pointer to an iSCSI Response PDU buffer. */
1037typedef struct ISCSIRES *PISCSIRES;
1038/**
1039 * iSCSI Response PDU buffer (scatter).
1040 */
1041typedef struct ISCSIRES
1042{
1043 /** Length of PDU segment. */
1044 size_t cbSeg;
1045 /** Pointer to PDU segment. */
1046 void *pvSeg;
1047} ISCSIRES;
1048
1049/** Pointer to an iSCSI transport driver interface. */
1050typedef struct PDMIISCSITRANSPORT *PPDMIISCSITRANSPORT;
1051/**
1052 * iSCSI transport driver interface.
1053 */
1054typedef struct PDMIISCSITRANSPORT
1055{
1056 /**
1057 * Read bytes from an iSCSI transport stream. If the connection fails, it is automatically
1058 * reopened on the next call after the error is signalled. Error recovery in this case is
1059 * the duty of the caller.
1060 *
1061 * @returns VBox status code.
1062 * @param pTransport Pointer to the interface structure containing the called function pointer.
1063 * @param pvBuf Where to store the read bits.
1064 * @param cbBuf Number of bytes to read.
1065 * @param pcbRead Actual number of bytes read.
1066 * @thread Any thread.
1067 * @todo Correct the docs.
1068 */
1069 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIISCSITRANSPORT pTransport, PISCSIRES prgResponse, unsigned int cnResponse));
1070
1071 /**
1072 * Write bytes to an iSCSI transport stream. Padding is performed when necessary. If the connection
1073 * fails, it is automatically reopened on the next call after the error is signalled. Error recovery
1074 * in this case is the duty of the caller.
1075 *
1076 * @returns VBox status code.
1077 * @param pTransport Pointer to the interface structure containing the called function pointer.
1078 * @param pvBuf Where the write bits are stored.
1079 * @param cbWrite Number of bytes to write.
1080 * @thread Any thread.
1081 * @todo Correct the docs.
1082 */
1083 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIISCSITRANSPORT pTransport, PISCSIREQ prgRequest, unsigned int cnRequest));
1084
1085 /**
1086 * Open the iSCSI transport stream.
1087 *
1088 * @returns VBox status code.
1089 * @param pTransport Pointer to the interface structure containing the called function pointer.
1090 * @param pszTargetAddress Pointer to string of the format address:port.
1091 * @thread Any thread.
1092 */
1093 DECLR3CALLBACKMEMBER(int, pfnOpen,(PPDMIISCSITRANSPORT pTransport, const char *pszTargetAddress));
1094
1095 /**
1096 * Close the iSCSI transport stream.
1097 *
1098 * @returns VBox status code.
1099 * @param pTransport Pointer to the interface structure containing the called function pointer.
1100 * @thread Any thread.
1101 */
1102 DECLR3CALLBACKMEMBER(int, pfnClose,(PPDMIISCSITRANSPORT pTransport));
1103} PDMIISCSITRANSPORT;
1104
1105/**
1106 * Block notify interface.
1107 * Pair with PDMIBLOCKASYNC.
1108 */
1109
1110/** Pointer to a asynchronous block notify interface. */
1111typedef struct PDMIBLOCKASYNCPORT *PPDMIBLOCKASYNCPORT;
1112
1113/**
1114 * Asynchronous block notify interface.
1115 * Pair with PDMIBLOCKASYNC.
1116 */
1117typedef struct PDMIBLOCKASYNCPORT
1118{
1119 /**
1120 * Notify completion of a read task.
1121 *
1122 * @returns VBox status code.
1123 * @param pInterface Pointer to the interface structure containing the called function pointer.
1124 * @param uOffset Offset the task read from.
1125 * @param pvBuf The buffer containig the read data.
1126 * @param cbRead Number of bytes read.
1127 * @param pvUser The user argument given in pfnStartRead.
1128 * @thread Any thread.
1129 */
1130 DECLR3CALLBACKMEMBER(int, pfnReadCompleteNotify, (PPDMIBLOCKASYNCPORT pInterface, uint64_t uOffset, void *pvBuf, size_t cbRead, void *pvUser));
1131
1132 /**
1133 * Notify completion of a write task.
1134 *
1135 * @returns VBox status code.
1136 * @param pInterface Pointer to the interface structure containing the called function pointer.
1137 * @param uOffset Offset the task has written to.
1138 * @param pvBuf The buffer containig the written data.
1139 * @param cbWrite Number of bytes actually written.
1140 * @param pvUser The user argument given in pfnStartWrite.
1141 * @thread Any thread.
1142 */
1143 DECLR3CALLBACKMEMBER(int, pfnWriteCompleteNotify, (PPDMIBLOCKASYNCPORT pInterface, uint64_t uOffset, void *pvBuf, size_t cbWrite, void *pvUser));
1144} PDMIBLOCKASYNCPORT;
1145
1146/** Pointer to a asynchronous block interface. */
1147typedef struct PDMIBLOCKASYNC *PPDMIBLOCKASYNC;
1148
1149/**
1150 * Asynchronous block interface.
1151 * Pair with PDMIBLOCKASYNCPORT.
1152 */
1153typedef struct PDMIBLOCKASYNC
1154{
1155 /**
1156 * Start reading task.
1157 *
1158 * @returns VBox status code.
1159 * @param pInterface Pointer to the interface structure containing the called function pointer.
1160 * @param off Offset to start reading from.
1161 * @param pvBuf Where to store the read bits.
1162 * @param cbRead Number of bytes to read.
1163 * @param pvUser User argument which is returned in completion callback.
1164 * @thread Any thread.
1165 */
1166 DECLR3CALLBACKMEMBER(int, pfnStartRead,(PPDMIBLOCKASYNC pInterface, uint64_t off, void *pvBuf, size_t cbRead, void *pvUser));
1167
1168 /**
1169 * Write bits.
1170 *
1171 * @returns VBox status code.
1172 * @param pInterface Pointer to the interface structure containing the called function pointer.
1173 * @param off Offset to start writing at.
1174 * @param pvBuf Where to store the write bits.
1175 * @param cbWrite Number of bytes to write.
1176 * @param pvUser User argument which is returned in completion callback.
1177 * @thread Any thread.
1178 */
1179 DECLR3CALLBACKMEMBER(int, pfnStartWrite,(PPDMIBLOCKASYNC pInterface, uint64_t off, const void *pvBuf, size_t cbWrite, void *pvUser));
1180
1181 /**
1182 * Make sure that the bits written are actually on the storage medium.
1183 *
1184 * @returns VBox status code.
1185 * @param pInterface Pointer to the interface structure containing the called function pointer.
1186 * @thread Any thread.
1187 */
1188 DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIBLOCKASYNC pInterface));
1189
1190 /**
1191 * Check if the media is readonly or not.
1192 *
1193 * @returns true if readonly.
1194 * @returns false if read/write.
1195 * @param pInterface Pointer to the interface structure containing the called function pointer.
1196 * @thread Any thread.
1197 */
1198 DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIBLOCKASYNC pInterface));
1199
1200 /**
1201 * Gets the media size in bytes.
1202 *
1203 * @returns Media size in bytes.
1204 * @param pInterface Pointer to the interface structure containing the called function pointer.
1205 * @thread Any thread.
1206 */
1207 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIBLOCKASYNC pInterface));
1208
1209 /**
1210 * Gets the block drive type.
1211 *
1212 * @returns block drive type.
1213 * @param pInterface Pointer to the interface structure containing the called function pointer.
1214 * @thread Any thread.
1215 */
1216 DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCKASYNC pInterface));
1217
1218 /**
1219 * Gets the UUID of the block drive.
1220 * Don't return the media UUID if it's removable.
1221 *
1222 * @returns VBox status code.
1223 * @param pInterface Pointer to the interface structure containing the called function pointer.
1224 * @param pUuid Where to store the UUID on success.
1225 * @thread Any thread.
1226 */
1227 DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIBLOCKASYNC pInterface, PRTUUID pUuid));
1228} PDMIBLOCKASYNC;
1229
1230/** Notification interface for completed I/O tasks.
1231 * Pair with PDMIMEDIAASYNC.
1232 */
1233
1234/** Pointer to a asynchronous notification interface. */
1235typedef struct PDMIMEDIAASYNCPORT *PPDMIMEDIAASYNCPORT;
1236
1237/**
1238 * Asynchronous media interface.
1239 * Makes up the fundation for PDMIBLOCKASYNC and PDMIBLOCKBIOS.
1240 */
1241typedef struct PDMIMEDIAASYNCPORT
1242{
1243 /**
1244 * Notify completion of a read task.
1245 *
1246 * @returns VBox status code.
1247 * @param pInterface Pointer to the interface structure containing the called function pointer.
1248 * @param uOffset Offset the task read from.
1249 * @param pvBuf The buffer containig the read data.
1250 * @param cbRead Number of bytes read.
1251 * @param pvUser The user argument given in pfnStartRead.
1252 * @thread Any thread.
1253 */
1254 DECLR3CALLBACKMEMBER(int, pfnReadCompleteNotify, (PPDMIMEDIAASYNCPORT pInterface, uint64_t uOffset, void *pvBuf, size_t cbRead, void *pvUser));
1255
1256 /**
1257 * Notify completion of a write task.
1258 *
1259 * @returns VBox status code.
1260 * @param pInterface Pointer to the interface structure containing the called function pointer.
1261 * @param uOffset Offset the task has written to.
1262 * @param pvBuf The buffer containig the written data.
1263 * @param cbWritten Number of bytes actually written.
1264 * @param pvUser The user argument given in pfnStartWrite.
1265 * @thread Any thread.
1266 */
1267 DECLR3CALLBACKMEMBER(int, pfnWriteCompleteNotify, (PPDMIMEDIAASYNCPORT pInterface, uint64_t uOffset, void *pvBuf, size_t cbWritten, void *pvUser));
1268} PDMIMEDIAASYNCPORT;
1269
1270/** Pointer to a asynchronous media interface. */
1271typedef struct PDMIMEDIAASYNC *PPDMIMEDIAASYNC;
1272
1273/**
1274 * Asynchronous media interface.
1275 * Makes up the fundation for PDMIBLOCKASYNC and PDMIBLOCKBIOS.
1276 */
1277typedef struct PDMIMEDIAASYNC
1278{
1279 /**
1280 * Start reading task.
1281 *
1282 * @returns VBox status code.
1283 * @param pInterface Pointer to the interface structure containing the called function pointer.
1284 * @param off Offset to start reading from.
1285 * @param pvBuf Where to store the read bits.
1286 * @param cbRead Number of bytes to read.
1287 * @param pvUser User data.
1288 * @thread Any thread.
1289 */
1290 DECLR3CALLBACKMEMBER(int, pfnStartRead,(PPDMIMEDIAASYNC pInterface, uint64_t off, void *pvBuf, size_t cbRead, void *pvUser));
1291
1292 /**
1293 * Start writing task.
1294 *
1295 * @returns VBox status code.
1296 * @param pInterface Pointer to the interface structure containing the called function pointer.
1297 * @param off Offset to start writing at.
1298 * @param pvBuf Where to store the write bits.
1299 * @param cbWrite Number of bytes to write.
1300 * @param pvUser User data.
1301 * @thread Any thread.
1302 */
1303 DECLR3CALLBACKMEMBER(int, pfnStartWrite,(PPDMIMEDIAASYNC pInterface, uint64_t off, const void *pvBuf, size_t cbWrite, void *pvUser));
1304
1305 /**
1306 * Make sure that the bits written are actually on the storage medium.
1307 *
1308 * @returns VBox status code.
1309 * @param pInterface Pointer to the interface structure containing the called function pointer.
1310 * @thread Any thread.
1311 */
1312 DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIMEDIAASYNC pInterface));
1313
1314 /**
1315 * Get the media size in bytes.
1316 *
1317 * @returns Media size in bytes.
1318 * @param pInterface Pointer to the interface structure containing the called function pointer.
1319 * @thread Any thread.
1320 */
1321 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIMEDIAASYNC pInterface));
1322
1323 /**
1324 * Check if the media is readonly or not.
1325 *
1326 * @returns true if readonly.
1327 * @returns false if read/write.
1328 * @param pInterface Pointer to the interface structure containing the called function pointer.
1329 * @thread Any thread.
1330 */
1331 DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIMEDIAASYNC pInterface));
1332
1333 /**
1334 * Get stored media geometry - BIOS property.
1335 * This is an optional feature of a media.
1336 *
1337 * @returns VBox status code.
1338 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1339 * @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetGeometry() yet.
1340 * @param pInterface Pointer to the interface structure containing the called function pointer.
1341 * @param pcCylinders Number of cylinders.
1342 * @param pcHeads Number of heads.
1343 * @param pcSectors Number of sectors. This number is 1-based.
1344 * @remark This have no influence on the read/write operations.
1345 * @thread Any thread.
1346 */
1347 DECLR3CALLBACKMEMBER(int, pfnBiosGetGeometry,(PPDMIMEDIAASYNC pInterface, uint32_t *pcCylinders, uint32_t *pcHeads, uint32_t *pcSectors));
1348
1349 /**
1350 * Store the media geometry - BIOS property.
1351 * This is an optional feature of a media.
1352 *
1353 * @returns VBox status code.
1354 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1355 * @param pInterface Pointer to the interface structure containing the called function pointer.
1356 * @param cCylinders Number of cylinders.
1357 * @param cHeads Number of heads.
1358 * @param cSectors Number of sectors. This number is 1-based.
1359 * @remark This have no influence on the read/write operations.
1360 * @thread The emulation thread.
1361 */
1362 DECLR3CALLBACKMEMBER(int, pfnBiosSetGeometry,(PPDMIMEDIAASYNC pInterface, uint32_t cCylinders, uint32_t cHeads, uint32_t cSectors));
1363
1364 /**
1365 * Get stored geometry translation mode - BIOS property.
1366 * This is an optional feature of a media.
1367 *
1368 * @returns VBox status code.
1369 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry translation mode.
1370 * @returns VERR_PDM_TRANSLATION_NOT_SET if the translation hasn't been set using pfnBiosSetTranslation() yet.
1371 * @param pInterface Pointer to the interface structure containing the called function pointer.
1372 * @param penmTranslation Where to store the translation type.
1373 * @remark This have no influence on the read/write operations.
1374 * @thread Any thread.
1375 */
1376 DECLR3CALLBACKMEMBER(int, pfnBiosGetTranslation,(PPDMIMEDIAASYNC pInterface, PPDMBIOSTRANSLATION penmTranslation));
1377
1378 /**
1379 * Store media geometry - BIOS property.
1380 * This is an optional feature of a media.
1381 *
1382 * @returns VBox status code.
1383 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1384 * @param pInterface Pointer to the interface structure containing the called function pointer.
1385 * @param enmTranslation The translation type.
1386 * @remark This have no influence on the read/write operations.
1387 * @thread The emulation thread.
1388 */
1389 DECLR3CALLBACKMEMBER(int, pfnBiosSetTranslation,(PPDMIMEDIAASYNC pInterface, PDMBIOSTRANSLATION enmTranslation));
1390
1391 /**
1392 * Gets the UUID of the media drive.
1393 *
1394 * @returns VBox status code.
1395 * @param pInterface Pointer to the interface structure containing the called function pointer.
1396 * @param pUuid Where to store the UUID on success.
1397 * @thread Any thread.
1398 */
1399 DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIMEDIAASYNC pInterface, PRTUUID pUuid));
1400
1401} PDMIMEDIAASYNC;
1402
1403/**
1404 * Pointer to a async media notify interface.
1405 * Pair with PDMITRANSPORTASYNC.
1406 */
1407typedef struct PDMITRANSPORTASYNCPORT *PPDMITRANSPORTASYNCPORT;
1408
1409/**
1410 * Notification interface for completed I/O tasks.
1411 * Pair with PDMITRANSPORTASYNC.
1412 */
1413typedef struct PDMITRANSPORTASYNCPORT
1414{
1415 /**
1416 * Notify completion of a read task.
1417 *
1418 * @returns VBox status code.
1419 * @param pInterface Pointer to the interface structure containing the called function pointer.
1420 * @param uOffset Offset the task read from.
1421 * @param pvBuf The buffer containig the read data.
1422 * @param cbRead Number of bytes read.
1423 * @param pvUser The user argument given in pfnStartRead.
1424 * @thread Any thread.
1425 */
1426 DECLR3CALLBACKMEMBER(int, pfnReadCompleteNotify, (PPDMITRANSPORTASYNCPORT pInterface, uint64_t uOffset, void *pvBuf, size_t cbRead, void *pvUser));
1427
1428 /**
1429 * Notify completion of a write task.
1430 *
1431 * @returns VBox status code.
1432 * @param pInterface Pointer to the interface structure containing the called function pointer.
1433 * @param uOffset Offset the task has written to.
1434 * @param pvBuf The buffer containig the written data.
1435 * @param cbWritten Number of bytes actually written.
1436 * @param pvUser The user argument given in pfnStartWrite.
1437 * @thread Any thread.
1438 */
1439 DECLR3CALLBACKMEMBER(int, pfnWriteCompleteNotify, (PPDMITRANSPORTASYNCPORT pInterface, uint64_t uOffset, void *pvBuf, size_t cbWritten, void *pvUser));
1440} PDMITRANSPORTASYNCPORT;
1441
1442/** Pointer to a async media interface. */
1443typedef struct PDMITRANSPORTASYNC *PPDMITRANSPORTASYNC;
1444/**
1445 * Asynchronous transport interface.
1446 * Makes up the fundation for PDMIMEDIAASYNC.
1447 */
1448typedef struct PDMITRANSPORTASYNC
1449{
1450 /**
1451 * Read bits synchronous.
1452 * Blocks until finished.
1453 *
1454 * @returns VBox status code.
1455 * @param pInterface Pointer to the interface structure containint the called function pointer.
1456 * @param uOffset Offset to start reading from.
1457 * @param pvBuf here to store the read bits.
1458 * @param cbRead Number of bytes to read.
1459 * @param pcbRead Where to store the number of bytes actually read.
1460 * @thread Any thread.
1461 */
1462 DECLR3CALLBACKMEMBER(int, pfnReadSynchronous, (PPDMITRANSPORTASYNC pInterface, uint64_t uOffset, void *pvBuf, size_t cbRead, size_t *pcbRead));
1463
1464 /**
1465 * Write bits synchronous.
1466 * Blocks until finished.
1467 *
1468 * @returns VBox status code.
1469 * @param pInterface Pointer to the interface structure containint the called function pointer.
1470 * @param uOffset Offset to start reading from.
1471 * @param pvBuf here to store the read bits.
1472 * @param cbWrite Number of bytes to read.
1473 * @param pcbWritten Where to store the number of bytes actually read.
1474 * @thread Any thread.
1475 */
1476 DECLR3CALLBACKMEMBER(int, pfnWriteSynchronous, (PPDMITRANSPORTASYNC pInterface, uint64_t uOffset, void *pvBuf, size_t cbWrite, size_t *pcbWritten));
1477
1478 /**
1479 * Start asynchronous read.
1480 *
1481 * @returns VBox status code.
1482 * @param pInterface Pointer to the interface structure containing the called function pointer.
1483 * @param off Offset to start reading from.
1484 * @param pvBuf Where to store the read bits.
1485 * @param cbRead Number of bytes to read.
1486 * @param pvUser User argument returned in completion callback.
1487 * @thread Any thread.
1488 */
1489 DECLR3CALLBACKMEMBER(int, pfnReadStartAsynchronous,(PPDMITRANSPORTASYNC pInterface, uint64_t off, void *pvBuf, size_t cbRead, void *pvUser));
1490
1491 /**
1492 * Start asynchronous write.
1493 *
1494 * @returns VBox status code.
1495 * @param pInterface Pointer to the interface structure containing the called function pointer.
1496 * @param off Offset to start writing at.
1497 * @param pvBuf Where to store the write bits.
1498 * @param cbWrite Number of bytes to write.
1499 * @param pvUser User argument returned in completion callback.
1500 * @thread Any thread.
1501 */
1502 DECLR3CALLBACKMEMBER(int, pfnWriteStartAsynchronous,(PPDMITRANSPORTASYNC pInterface, uint64_t off, const void *pvBuf, size_t cbWrite, void *pvUser));
1503
1504 /**
1505 * Make sure that the bits written are actually on the storage medium.
1506 * This is a synchronous task
1507 *
1508 * @returns VBox status code.
1509 * @param pInterface Pointer to the interface structure containing the called function pointer.
1510 * @thread Any thread.
1511 */
1512 DECLR3CALLBACKMEMBER(int, pfnFlushSynchronous,(PPDMITRANSPORTASYNC pInterface));
1513
1514 /**
1515 * Get the media size in bytes.
1516 *
1517 * @returns Media size in bytes.
1518 * @param pInterface Pointer to the interface structure containing the called function pointer.
1519 * @thread Any thread.
1520 */
1521 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMITRANSPORTASYNC pInterface));
1522
1523 /**
1524 * Check if the media is readonly or not.
1525 *
1526 * @returns true if readonly.
1527 * @returns false if read/write.
1528 * @param pInterface Pointer to the interface structure containing the called function pointer.
1529 * @thread Any thread.
1530 */
1531 DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMITRANSPORTASYNC pInterface));
1532
1533 /**
1534 * Opens the data source.
1535 *
1536 * @returns VBox status code.
1537 * @param pInterface Pointer to the interface structure containing the called function pointer.
1538 * @param pszPath The path to open.
1539 * @param fReadonly If the target shoudl opened readonly.
1540 * @thread Any thread.
1541 */
1542 DECLR3CALLBACKMEMBER(int, pfnOpen, (PPDMITRANSPORTASYNC pInterface, const char *pszTargetPath, bool fReadonly));
1543
1544 /**
1545 * Close the data source.
1546 *
1547 * @returns VBox status code.
1548 * @param pInterface Pointer to the interface structure containing the called function pointer.
1549 * @thread Any thread.
1550 */
1551 DECLR3CALLBACKMEMBER(int, pfnClose, (PPDMITRANSPORTASYNC pInterface));
1552
1553} PDMITRANSPORTASYNC;
1554
1555/** @name Bit mask definitions for status line type
1556 * @{ */
1557#define PDM_ICHAR_STATUS_LINES_DCD RT_BIT(0)
1558#define PDM_ICHAR_STATUS_LINES_RI RT_BIT(1)
1559#define PDM_ICHAR_STATUS_LINES_DSR RT_BIT(2)
1560#define PDM_ICHAR_STATUS_LINES_CTS RT_BIT(3)
1561/** @} */
1562
1563
1564/** Pointer to a char port interface. */
1565typedef struct PDMICHARPORT *PPDMICHARPORT;
1566/**
1567 * Char port interface.
1568 * Pair with PDMICHAR.
1569 */
1570typedef struct PDMICHARPORT
1571{
1572 /**
1573 * Deliver data read to the device/driver.
1574 *
1575 * @returns VBox status code.
1576 * @param pInterface Pointer to the interface structure containing the called function pointer.
1577 * @param pvBuf Where the read bits are stored.
1578 * @param pcbRead Number of bytes available for reading/having been read.
1579 * @thread Any thread.
1580 */
1581 DECLR3CALLBACKMEMBER(int, pfnNotifyRead,(PPDMICHARPORT pInterface, const void *pvBuf, size_t *pcbRead));
1582
1583 /**
1584 * Notify the device/driver when the status lines changed.
1585 *
1586 * @returns VBox status code.
1587 * @param pInterface Pointer to the interface structure containing the called function pointer.
1588 * @param fNewStatusLine New state of the status line pins.
1589 * @thread Any thread.
1590 */
1591 DECLR3CALLBACKMEMBER(int, pfnNotifyStatusLinesChanged,(PPDMICHARPORT pInterface, uint32_t fNewStatusLines));
1592} PDMICHARPORT;
1593
1594/** Pointer to a char interface. */
1595typedef struct PDMICHAR *PPDMICHAR;
1596/**
1597 * Char interface.
1598 * Pair with PDMICHARPORT.
1599 */
1600typedef struct PDMICHAR
1601{
1602 /**
1603 * Write bits.
1604 *
1605 * @returns VBox status code.
1606 * @param pInterface Pointer to the interface structure containing the called function pointer.
1607 * @param pvBuf Where to store the write bits.
1608 * @param cbWrite Number of bytes to write.
1609 * @thread Any thread.
1610 */
1611 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMICHAR pInterface, const void *pvBuf, size_t cbWrite));
1612
1613 /**
1614 * Set device parameters.
1615 *
1616 * @returns VBox status code.
1617 * @param pInterface Pointer to the interface structure containing the called function pointer.
1618 * @param Bps Speed of the serial connection. (bits per second)
1619 * @param chParity Parity method: 'E' - even, 'O' - odd, 'N' - none.
1620 * @param cDataBits Number of data bits.
1621 * @param cStopBits Number of stop bits.
1622 * @thread Any thread.
1623 */
1624 DECLR3CALLBACKMEMBER(int, pfnSetParameters,(PPDMICHAR pInterface, unsigned Bps, char chParity, unsigned cDataBits, unsigned cStopBits));
1625
1626 /**
1627 * Set the state of the modem lines.
1628 *
1629 * @returns VBox status code.
1630 * @param pInterface Pointer to the interface structure containing the called function pointer.
1631 * @param fRequestToSend Set to true to make the Request to Send line active otherwise to 0.
1632 * @param fDataTerminalReady Set to true to make the Data Terminal Ready line active otherwise 0.
1633 * @thread Any thread.
1634 */
1635 DECLR3CALLBACKMEMBER(int, pfnSetModemLines,(PPDMICHAR pInterface, bool fRequestToSend, bool fDataTerminalReady));
1636
1637} PDMICHAR;
1638
1639
1640/** Pointer to a stream interface. */
1641typedef struct PDMISTREAM *PPDMISTREAM;
1642/**
1643 * Stream interface.
1644 * Makes up the fundation for PDMICHAR.
1645 */
1646typedef struct PDMISTREAM
1647{
1648 /**
1649 * Read bits.
1650 *
1651 * @returns VBox status code.
1652 * @param pInterface Pointer to the interface structure containing the called function pointer.
1653 * @param pvBuf Where to store the read bits.
1654 * @param cbRead Number of bytes to read/bytes actually read.
1655 * @thread Any thread.
1656 */
1657 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMISTREAM pInterface, void *pvBuf, size_t *cbRead));
1658
1659 /**
1660 * Write bits.
1661 *
1662 * @returns VBox status code.
1663 * @param pInterface Pointer to the interface structure containing the called function pointer.
1664 * @param pvBuf Where to store the write bits.
1665 * @param cbWrite Number of bytes to write/bytes actually written.
1666 * @thread Any thread.
1667 */
1668 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMISTREAM pInterface, const void *pvBuf, size_t *cbWrite));
1669} PDMISTREAM;
1670
1671
1672/** Pointer to a host device port interface. */
1673typedef struct PDMIHOSTDEVICEPORT *PPDMIHOSTDEVICEPORT;
1674
1675/**
1676 * Char port interface.
1677 * Pair with PDMIHOSTDEVICECONNECTOR.
1678 */
1679typedef struct PDMIHOSTDEVICEPORT
1680{
1681 /**
1682 * Deliver data read to the device/driver.
1683 *
1684 * @returns VBox status code.
1685 * @param pInterface Pointer to the interface structure containing the called function pointer.
1686 * @param pvBuf Where the read bits are stored.
1687 * @param pcbRead Number of bytes available for reading/having been read.
1688 * @thread Any thread.
1689 */
1690 DECLR3CALLBACKMEMBER(int, pfnNotifyRead,(PPDMIHOSTDEVICEPORT pInterface, const void *pvBuf, size_t *pcbRead));
1691} PDMIHOSTDEVICEPORT;
1692
1693/** Pointer to a Host Device connector interface. */
1694typedef struct PDMIHOSTDEVICECONNECTOR *PPDMIHOSTDEVICECONNECTOR;
1695
1696/**
1697 * Host device connector interface
1698 * Pair with PDMIHOSTDEVICEPORT.
1699 */
1700typedef struct PDMIHOSTDEVICECONNECTOR
1701{
1702 /**
1703 * Write bits.
1704 *
1705 * @returns VBox status code.
1706 * @param pInterface Pointer to the interface structure containing the called function pointer.
1707 * @param pvBuf Where to store the write bits.
1708 * @param pcbWrite Number of bytes to write/bytes actually written.
1709 * @thread Any thread.
1710 */
1711 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIHOSTDEVICECONNECTOR pInterface, const void *pvBuf, size_t *pcbWrite));
1712
1713 /**
1714 * Read bits.
1715 *
1716 * @returns VBox status code.
1717 * @param pInterface Pointer to the interface structure containing the called function pointer.
1718 * @param pvBuf Where to store the read bits.
1719 * @param pcbRead Number of bytes to read/bytes actually read.
1720 * @thread Any thread.
1721 */
1722 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIHOSTDEVICECONNECTOR pInterface, void *pvBuf, size_t *pcbRead));
1723
1724 /**
1725 * Perform IO control on the host device.
1726 *
1727 * @returns VBox status code.
1728 * @param pInterface Pointer to the interface structure containing the called function pointer.
1729 * @param uCommand The number of the command to set or get data
1730 * @param pvData Where to store the command data.
1731 * @thread Any thread.
1732 */
1733 DECLR3CALLBACKMEMBER(int, pfnIOCtl,(PPDMIHOSTDEVICECONNECTOR pInterface, RTUINT uCommand, void *pvData));
1734} PDMIHOSTDEVICECONNECTOR;
1735
1736
1737/** ACPI power source identifier */
1738typedef enum PDMACPIPOWERSOURCE
1739{
1740 PDM_ACPI_POWER_SOURCE_UNKNOWN = 0,
1741 PDM_ACPI_POWER_SOURCE_OUTLET,
1742 PDM_ACPI_POWER_SOURCE_BATTERY
1743} PDMACPIPOWERSOURCE;
1744/** Pointer to ACPI battery state. */
1745typedef PDMACPIPOWERSOURCE *PPDMACPIPOWERSOURCE;
1746
1747/** ACPI battey capacity */
1748typedef enum PDMACPIBATCAPACITY
1749{
1750 PDM_ACPI_BAT_CAPACITY_MIN = 0,
1751 PDM_ACPI_BAT_CAPACITY_MAX = 100,
1752 PDM_ACPI_BAT_CAPACITY_UNKNOWN = 255
1753} PDMACPIBATCAPACITY;
1754/** Pointer to ACPI battery capacity. */
1755typedef PDMACPIBATCAPACITY *PPDMACPIBATCAPACITY;
1756
1757/** ACPI battery state. See ACPI 3.0 spec '_BST (Battery Status)' */
1758typedef enum PDMACPIBATSTATE
1759{
1760 PDM_ACPI_BAT_STATE_CHARGED = 0x00,
1761 PDM_ACPI_BAT_STATE_CHARGING = 0x01,
1762 PDM_ACPI_BAT_STATE_DISCHARGING = 0x02,
1763 PDM_ACPI_BAT_STATE_CRITICAL = 0x04
1764} PDMACPIBATSTATE;
1765/** Pointer to ACPI battery state. */
1766typedef PDMACPIBATSTATE *PPDMACPIBATSTATE;
1767
1768/** Pointer to an ACPI port interface. */
1769typedef struct PDMIACPIPORT *PPDMIACPIPORT;
1770/**
1771 * ACPI port interface.
1772 */
1773typedef struct PDMIACPIPORT
1774{
1775 /**
1776 * Send an ACPI power off event.
1777 *
1778 * @returns VBox status code
1779 * @param pInterface Pointer to the interface structure containing the called function pointer.
1780 */
1781 DECLR3CALLBACKMEMBER(int, pfnPowerButtonPress,(PPDMIACPIPORT pInterface));
1782} PDMIACPIPORT;
1783
1784/** Pointer to an ACPI connector interface. */
1785typedef struct PDMIACPICONNECTOR *PPDMIACPICONNECTOR;
1786/**
1787 * ACPI connector interface.
1788 */
1789typedef struct PDMIACPICONNECTOR
1790{
1791 /**
1792 * Get the current power source of the host system.
1793 *
1794 * @returns VBox status code
1795 * @param pInterface Pointer to the interface structure containing the called function pointer.
1796 * @param penmPowerSource Pointer to the power source result variable.
1797 */
1798 DECLR3CALLBACKMEMBER(int, pfnQueryPowerSource,(PPDMIACPICONNECTOR, PPDMACPIPOWERSOURCE penmPowerSource));
1799
1800 /**
1801 * Query the current battery status of the host system.
1802 *
1803 * @returns VBox status code?
1804 * @param pInterface Pointer to the interface structure containing the called function pointer.
1805 * @param pfPresent Is set to true if battery is present, false otherwise.
1806 * @param penmRemainingCapacity Pointer to the battery remaining capacity (0 - 100 or 255 for unknown).
1807 * @param penmBatteryState Pointer to the battery status.
1808 * @param pu32PresentRate Pointer to the present rate (0..1000 of the total capacity).
1809 */
1810 DECLR3CALLBACKMEMBER(int, pfnQueryBatteryStatus,(PPDMIACPICONNECTOR, bool *pfPresent, PPDMACPIBATCAPACITY penmRemainingCapacity,
1811 PPDMACPIBATSTATE penmBatteryState, uint32_t *pu32PresentRate));
1812} PDMIACPICONNECTOR;
1813
1814
1815/** Pointer to a VMMDevice port interface. */
1816typedef struct PDMIVMMDEVPORT *PPDMIVMMDEVPORT;
1817/**
1818 * VMMDevice port interface.
1819 */
1820typedef struct PDMIVMMDEVPORT
1821{
1822 /**
1823 * Return the current absolute mouse position in pixels
1824 *
1825 * @returns VBox status code
1826 * @param pAbsX Pointer of result value, can be NULL
1827 * @param pAbsY Pointer of result value, can be NULL
1828 */
1829 DECLR3CALLBACKMEMBER(int, pfnQueryAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, uint32_t *pAbsX, uint32_t *pAbsY));
1830
1831 /**
1832 * Set the new absolute mouse position in pixels
1833 *
1834 * @returns VBox status code
1835 * @param absX New absolute X position
1836 * @param absY New absolute Y position
1837 */
1838 DECLR3CALLBACKMEMBER(int, pfnSetAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, uint32_t absX, uint32_t absY));
1839
1840 /**
1841 * Return the current mouse capability flags
1842 *
1843 * @returns VBox status code
1844 * @param pCapabilities Pointer of result value
1845 */
1846 DECLR3CALLBACKMEMBER(int, pfnQueryMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t *pCapabilities));
1847
1848 /**
1849 * Set the current mouse capability flag (host side)
1850 *
1851 * @returns VBox status code
1852 * @param capabilities Capability mask
1853 */
1854 DECLR3CALLBACKMEMBER(int, pfnSetMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t capabilities));
1855
1856 /**
1857 * Issue a display resolution change request.
1858 *
1859 * Note that there can only one request in the queue and that in case the guest does
1860 * not process it, issuing another request will overwrite the previous.
1861 *
1862 * @returns VBox status code
1863 * @param cx Horizontal pixel resolution (0 = do not change).
1864 * @param cy Vertical pixel resolution (0 = do not change).
1865 * @param cBits Bits per pixel (0 = do not change).
1866 * @param display The display index.
1867 */
1868 DECLR3CALLBACKMEMBER(int, pfnRequestDisplayChange,(PPDMIVMMDEVPORT pInterface, uint32_t cx, uint32_t cy, uint32_t cBits, uint32_t display));
1869
1870 /**
1871 * Pass credentials to guest.
1872 *
1873 * Note that there can only be one set of credentials and the guest may or may not
1874 * query them and may do whatever it wants with them.
1875 *
1876 * @returns VBox status code
1877 * @param pszUsername User name, may be empty (UTF-8)
1878 * @param pszPassword Password, may be empty (UTF-8)
1879 * @param pszDomain Domain name, may be empty (UTF-8)
1880 * @param fFlags Bitflags
1881 */
1882 DECLR3CALLBACKMEMBER(int, pfnSetCredentials,(PPDMIVMMDEVPORT pInterface, const char *pszUsername,
1883 const char *pszPassword, const char *pszDomain,
1884 uint32_t fFlags));
1885
1886 /**
1887 * Notify the driver about a VBVA status change.
1888 *
1889 * @returns Nothing. Because it is informational callback.
1890 * @param fEnabled Current VBVA status.
1891 */
1892 DECLR3CALLBACKMEMBER(void, pfnVBVAChange, (PPDMIVMMDEVPORT pInterface, bool fEnabled));
1893
1894 /**
1895 * Issue a seamless mode change request.
1896 *
1897 * Note that there can only one request in the queue and that in case the guest does
1898 * not process it, issuing another request will overwrite the previous.
1899 *
1900 * @returns VBox status code
1901 * @param fEnabled Seamless mode enabled or not
1902 */
1903 DECLR3CALLBACKMEMBER(int, pfnRequestSeamlessChange,(PPDMIVMMDEVPORT pInterface, bool fEnabled));
1904
1905 /**
1906 * Issue a memory balloon change request.
1907 *
1908 * Note that there can only one request in the queue and that in case the guest does
1909 * not process it, issuing another request will overwrite the previous.
1910 *
1911 * @returns VBox status code
1912 * @param ulBalloonSize Balloon size in megabytes
1913 */
1914 DECLR3CALLBACKMEMBER(int, pfnSetMemoryBalloon,(PPDMIVMMDEVPORT pInterface, uint32_t ulBalloonSize));
1915
1916 /**
1917 * Issue a statistcs interval change request.
1918 *
1919 * Note that there can only one request in the queue and that in case the guest does
1920 * not process it, issuing another request will overwrite the previous.
1921 *
1922 * @returns VBox status code
1923 * @param ulStatInterval Statistics query interval in seconds (0=disable)
1924 */
1925 DECLR3CALLBACKMEMBER(int, pfnSetStatisticsInterval,(PPDMIVMMDEVPORT pInterface, uint32_t ulStatInterval));
1926
1927 /**
1928 * Notify the guest about a VRDP status change.
1929 *
1930 * @returns VBox status code
1931 * @param fVRDPEnabled Current VRDP status.
1932 * @param u32VRDPExperienceLevel Which visual effects to be disabled in the guest.
1933 */
1934 DECLR3CALLBACKMEMBER(int, pfnVRDPChange, (PPDMIVMMDEVPORT pInterface, bool fVRDPEnabled, uint32_t u32VRDPExperienceLevel));
1935
1936} PDMIVMMDEVPORT;
1937
1938/** Forward declaration of the video accelerator command memory. */
1939struct _VBVAMEMORY;
1940/** Forward declaration of the guest information structure. */
1941struct VBoxGuestInfo;
1942/** Forward declaration of the guest statistics structure */
1943struct VBoxGuestStatistics;
1944/** Pointer to video accelerator command memory. */
1945typedef struct _VBVAMEMORY *PVBVAMEMORY;
1946
1947/** Pointer to a VMMDev connector interface. */
1948typedef struct PDMIVMMDEVCONNECTOR *PPDMIVMMDEVCONNECTOR;
1949/**
1950 * VMMDev connector interface.
1951 * Pair with PDMIVMMDEVPORT.
1952 */
1953typedef struct PDMIVMMDEVCONNECTOR
1954{
1955 /**
1956 * Report guest OS version.
1957 * Called whenever the Additions issue a guest version report request.
1958 *
1959 * @param pInterface Pointer to this interface.
1960 * @param pGuestInfo Pointer to guest information structure
1961 * @thread The emulation thread.
1962 */
1963 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestVersion,(PPDMIVMMDEVCONNECTOR pInterface, struct VBoxGuestInfo *pGuestInfo));
1964
1965 /**
1966 * Update the guest additions capabilities.
1967 * This is called when the guest additions capabilities change. The new capabilities
1968 * are given and the connector should update its internal state.
1969 *
1970 * @param pInterface Pointer to this interface.
1971 * @param newCapabilities New capabilities.
1972 * @thread The emulation thread.
1973 */
1974 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
1975
1976 /**
1977 * Update the mouse capabilities.
1978 * This is called when the mouse capabilities change. The new capabilities
1979 * are given and the connector should update its internal state.
1980 *
1981 * @param pInterface Pointer to this interface.
1982 * @param newCapabilities New capabilities.
1983 * @thread The emulation thread.
1984 */
1985 DECLR3CALLBACKMEMBER(void, pfnUpdateMouseCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
1986
1987 /**
1988 * Update the pointer shape.
1989 * This is called when the mouse pointer shape changes. The new shape
1990 * is passed as a caller allocated buffer that will be freed after returning
1991 *
1992 * @param pInterface Pointer to this interface.
1993 * @param fVisible Visibility indicator (if false, the other parameters are undefined).
1994 * @param fAlpha Flag whether alpha channel is being passed.
1995 * @param xHot Pointer hot spot x coordinate.
1996 * @param yHot Pointer hot spot y coordinate.
1997 * @param x Pointer new x coordinate on screen.
1998 * @param y Pointer new y coordinate on screen.
1999 * @param cx Pointer width in pixels.
2000 * @param cy Pointer height in pixels.
2001 * @param cbScanline Size of one scanline in bytes.
2002 * @param pvShape New shape buffer.
2003 * @thread The emulation thread.
2004 */
2005 DECLR3CALLBACKMEMBER(void, pfnUpdatePointerShape,(PPDMIVMMDEVCONNECTOR pInterface, bool fVisible, bool fAlpha,
2006 uint32_t xHot, uint32_t yHot,
2007 uint32_t cx, uint32_t cy,
2008 void *pvShape));
2009
2010 /**
2011 * Enable or disable video acceleration on behalf of guest.
2012 *
2013 * @param pInterface Pointer to this interface.
2014 * @param fEnable Whether to enable acceleration.
2015 * @param pVbvaMemory Video accelerator memory.
2016
2017 * @return VBox rc. VINF_SUCCESS if VBVA was enabled.
2018 * @thread The emulation thread.
2019 */
2020 DECLR3CALLBACKMEMBER(int, pfnVideoAccelEnable,(PPDMIVMMDEVCONNECTOR pInterface, bool fEnable, PVBVAMEMORY pVbvaMemory));
2021
2022 /**
2023 * Force video queue processing.
2024 *
2025 * @param pInterface Pointer to this interface.
2026 * @thread The emulation thread.
2027 */
2028 DECLR3CALLBACKMEMBER(void, pfnVideoAccelFlush,(PPDMIVMMDEVCONNECTOR pInterface));
2029
2030 /**
2031 * Return whether the given video mode is supported/wanted by the host.
2032 *
2033 * @returns VBox status code
2034 * @param pInterface Pointer to this interface.
2035 * @param cy Video mode horizontal resolution in pixels.
2036 * @param cx Video mode vertical resolution in pixels.
2037 * @param cBits Video mode bits per pixel.
2038 * @param pfSupported Where to put the indicator for whether this mode is supported. (output)
2039 * @thread The emulation thread.
2040 */
2041 DECLR3CALLBACKMEMBER(int, pfnVideoModeSupported,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cx, uint32_t cy, uint32_t cBits, bool *pfSupported));
2042
2043 /**
2044 * Queries by how many pixels the height should be reduced when calculating video modes
2045 *
2046 * @returns VBox status code
2047 * @param pInterface Pointer to this interface.
2048 * @param pcyReduction Pointer to the result value.
2049 * @thread The emulation thread.
2050 */
2051 DECLR3CALLBACKMEMBER(int, pfnGetHeightReduction,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcyReduction));
2052
2053 /**
2054 * Informs about a credentials judgement result from the guest.
2055 *
2056 * @returns VBox status code
2057 * @param pInterface Pointer to this interface.
2058 * @param fFlags Judgement result flags.
2059 * @thread The emulation thread.
2060 */
2061 DECLR3CALLBACKMEMBER(int, pfnSetCredentialsJudgementResult,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t fFlags));
2062
2063 /**
2064 * Set the visible region of the display
2065 *
2066 * @returns VBox status code.
2067 * @param pInterface Pointer to this interface.
2068 * @param cRect Number of rectangles in pRect
2069 * @param pRect Rectangle array
2070 * @thread The emulation thread.
2071 */
2072 DECLR3CALLBACKMEMBER(int, pfnSetVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cRect, PRTRECT pRect));
2073
2074 /**
2075 * Query the visible region of the display
2076 *
2077 * @returns VBox status code.
2078 * @param pInterface Pointer to this interface.
2079 * @param pcRect Number of rectangles in pRect
2080 * @param pRect Rectangle array (set to NULL to query the number of rectangles)
2081 * @thread The emulation thread.
2082 */
2083 DECLR3CALLBACKMEMBER(int, pfnQueryVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcRect, PRTRECT pRect));
2084
2085 /**
2086 * Request the statistics interval
2087 *
2088 * @returns VBox status code.
2089 * @param pInterface Pointer to this interface.
2090 * @param pulInterval Pointer to interval in seconds
2091 * @thread The emulation thread.
2092 */
2093 DECLR3CALLBACKMEMBER(int, pfnQueryStatisticsInterval,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pulInterval));
2094
2095 /**
2096 * Report new guest statistics
2097 *
2098 * @returns VBox status code.
2099 * @param pInterface Pointer to this interface.
2100 * @param pGuestStats Guest statistics
2101 * @thread The emulation thread.
2102 */
2103 DECLR3CALLBACKMEMBER(int, pfnReportStatistics,(PPDMIVMMDEVCONNECTOR pInterface, struct VBoxGuestStatistics *pGuestStats));
2104
2105 /**
2106 * Inflate or deflate the memory balloon
2107 *
2108 * @returns VBox status code.
2109 * @param pInterface Pointer to this interface.
2110 * @param fInflate Inflate or deflate
2111 * @param cPages Number of physical pages (must be 256 as we allocate in 1 MB chunks)
2112 * @param aPhysPage Array of physical page addresses
2113 * @thread The emulation thread.
2114 */
2115 DECLR3CALLBACKMEMBER(int, pfnChangeMemoryBalloon, (PPDMIVMMDEVCONNECTOR pInterface, bool fInflate, uint32_t cPages, RTGCPHYS *aPhysPage));
2116
2117} PDMIVMMDEVCONNECTOR;
2118
2119
2120/**
2121 * MAC address.
2122 * (The first 24 bits are the 'company id', where the first bit seems to have a special meaning if set.)
2123 */
2124typedef union PDMMAC
2125{
2126 /** 8-bit view. */
2127 uint8_t au8[6];
2128 /** 16-bit view. */
2129 uint16_t au16[3];
2130} PDMMAC;
2131/** Pointer to a MAC address. */
2132typedef PDMMAC *PPDMMAC;
2133/** Pointer to a const MAC address. */
2134typedef const PDMMAC *PCPDMMAC;
2135
2136
2137/** Pointer to a network port interface */
2138typedef struct PDMINETWORKPORT *PPDMINETWORKPORT;
2139/**
2140 * Network port interface.
2141 */
2142typedef struct PDMINETWORKPORT
2143{
2144 /**
2145 * Check how much data the device/driver can receive data now.
2146 * This must be called before the pfnRecieve() method is called.
2147 *
2148 * @returns Number of bytes the device can receive now.
2149 * @param pInterface Pointer to the interface structure containing the called function pointer.
2150 * @thread EMT
2151 */
2152 DECLR3CALLBACKMEMBER(size_t, pfnCanReceive,(PPDMINETWORKPORT pInterface));
2153
2154 /**
2155 * Receive data from the network.
2156 *
2157 * @returns VBox status code.
2158 * @param pInterface Pointer to the interface structure containing the called function pointer.
2159 * @param pvBuf The available data.
2160 * @param cb Number of bytes available in the buffer.
2161 * @thread EMT
2162 */
2163 DECLR3CALLBACKMEMBER(int, pfnReceive,(PPDMINETWORKPORT pInterface, const void *pvBuf, size_t cb));
2164
2165} PDMINETWORKPORT;
2166
2167
2168/**
2169 * Network link state.
2170 */
2171typedef enum PDMNETWORKLINKSTATE
2172{
2173 /** Invalid state. */
2174 PDMNETWORKLINKSTATE_INVALID = 0,
2175 /** The link is up. */
2176 PDMNETWORKLINKSTATE_UP,
2177 /** The link is down. */
2178 PDMNETWORKLINKSTATE_DOWN,
2179 /** The link is temporarily down while resuming. */
2180 PDMNETWORKLINKSTATE_DOWN_RESUME
2181} PDMNETWORKLINKSTATE;
2182
2183
2184/** Pointer to a network connector interface */
2185typedef struct PDMINETWORKCONNECTOR *PPDMINETWORKCONNECTOR;
2186/**
2187 * Network connector interface.
2188 */
2189typedef struct PDMINETWORKCONNECTOR
2190{
2191 /**
2192 * Send data to the network.
2193 *
2194 * @returns VBox status code.
2195 * @param pInterface Pointer to the interface structure containing the called function pointer.
2196 * @param pvBuf Data to send.
2197 * @param cb Number of bytes to send.
2198 * @thread EMT
2199 */
2200 DECLR3CALLBACKMEMBER(int, pfnSend,(PPDMINETWORKCONNECTOR pInterface, const void *pvBuf, size_t cb));
2201
2202 /**
2203 * Set promiscuous mode.
2204 *
2205 * This is called when the promiscuous mode is set. This means that there doesn't have
2206 * to be a mode change when it's called.
2207 *
2208 * @param pInterface Pointer to the interface structure containing the called function pointer.
2209 * @param fPromiscuous Set if the adaptor is now in promiscuous mode. Clear if it is not.
2210 * @thread EMT
2211 */
2212 DECLR3CALLBACKMEMBER(void, pfnSetPromiscuousMode,(PPDMINETWORKCONNECTOR pInterface, bool fPromiscuous));
2213
2214 /**
2215 * Notification on link status changes.
2216 *
2217 * @param pInterface Pointer to the interface structure containing the called function pointer.
2218 * @param enmLinkState The new link state.
2219 * @thread EMT
2220 */
2221 DECLR3CALLBACKMEMBER(void, pfnNotifyLinkChanged,(PPDMINETWORKCONNECTOR pInterface, PDMNETWORKLINKSTATE enmLinkState));
2222
2223 /**
2224 * More receive buffer has become available.
2225 *
2226 * This is called when the NIC frees up receive buffers.
2227 *
2228 * @param pInterface Pointer to the interface structure containing the called function pointer.
2229 * @thread EMT
2230 */
2231 DECLR3CALLBACKMEMBER(void, pfnNotifyCanReceive,(PPDMINETWORKCONNECTOR pInterface));
2232
2233} PDMINETWORKCONNECTOR;
2234
2235
2236/** Pointer to a network config port interface */
2237typedef struct PDMINETWORKCONFIG *PPDMINETWORKCONFIG;
2238/**
2239 * Network config port interface.
2240 */
2241typedef struct PDMINETWORKCONFIG
2242{
2243 /**
2244 * Gets the current Media Access Control (MAC) address.
2245 *
2246 * @returns VBox status code.
2247 * @param pInterface Pointer to the interface structure containing the called function pointer.
2248 * @param pMac Where to store the MAC address.
2249 * @thread EMT
2250 */
2251 DECLR3CALLBACKMEMBER(int, pfnGetMac,(PPDMINETWORKCONFIG pInterface, PPDMMAC *pMac));
2252
2253 /**
2254 * Gets the new link state.
2255 *
2256 * @returns The current link state.
2257 * @param pInterface Pointer to the interface structure containing the called function pointer.
2258 * @thread EMT
2259 */
2260 DECLR3CALLBACKMEMBER(PDMNETWORKLINKSTATE, pfnGetLinkState,(PPDMINETWORKCONFIG pInterface));
2261
2262 /**
2263 * Sets the new link state.
2264 *
2265 * @returns VBox status code.
2266 * @param pInterface Pointer to the interface structure containing the called function pointer.
2267 * @param enmState The new link state
2268 * @thread EMT
2269 */
2270 DECLR3CALLBACKMEMBER(int, pfnSetLinkState,(PPDMINETWORKCONFIG pInterface, PDMNETWORKLINKSTATE enmState));
2271
2272} PDMINETWORKCONFIG;
2273
2274
2275/** Pointer to a network connector interface */
2276typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
2277/**
2278 * Audio connector interface.
2279 */
2280typedef struct PDMIAUDIOCONNECTOR
2281{
2282 DECLR3CALLBACKMEMBER(void, pfnRun,(PPDMIAUDIOCONNECTOR pInterface));
2283
2284/* DECLR3CALLBACKMEMBER(int, pfnSetRecordSource,(PPDMIAUDIOINCONNECTOR pInterface, AUDIORECSOURCE)); */
2285
2286} PDMIAUDIOCONNECTOR;
2287
2288
2289/** @todo r=bird: the two following interfaces are hacks to work around the missing audio driver
2290 * interface. This should be addressed rather than making more temporary hacks. */
2291
2292/** Pointer to a Audio Sniffer Device port interface. */
2293typedef struct PDMIAUDIOSNIFFERPORT *PPDMIAUDIOSNIFFERPORT;
2294
2295/**
2296 * Audio Sniffer port interface.
2297 */
2298typedef struct PDMIAUDIOSNIFFERPORT
2299{
2300 /**
2301 * Enables or disables sniffing. If sniffing is being enabled also sets a flag
2302 * whether the audio must be also left on the host.
2303 *
2304 * @returns VBox status code
2305 * @param pInterface Pointer to this interface.
2306 * @param fEnable 'true' for enable sniffing, 'false' to disable.
2307 * @param fKeepHostAudio Indicates whether host audio should also present
2308 * 'true' means that sound should not be played
2309 * by the audio device.
2310 */
2311 DECLR3CALLBACKMEMBER(int, pfnSetup,(PPDMIAUDIOSNIFFERPORT pInterface, bool fEnable, bool fKeepHostAudio));
2312
2313} PDMIAUDIOSNIFFERPORT;
2314
2315/** Pointer to a Audio Sniffer connector interface. */
2316typedef struct PDMIAUDIOSNIFFERCONNECTOR *PPDMIAUDIOSNIFFERCONNECTOR;
2317
2318/**
2319 * Audio Sniffer connector interface.
2320 * Pair with PDMIAUDIOSNIFFERPORT.
2321 */
2322typedef struct PDMIAUDIOSNIFFERCONNECTOR
2323{
2324 /**
2325 * AudioSniffer device calls this method when audio samples
2326 * are about to be played and sniffing is enabled.
2327 *
2328 * @param pInterface Pointer to this interface.
2329 * @param pvSamples Audio samples buffer.
2330 * @param cSamples How many complete samples are in the buffer.
2331 * @param iSampleHz The sample frequency in Hz.
2332 * @param cChannels Number of channels. 1 for mono, 2 for stereo.
2333 * @param cBits How many bits a sample for a single channel has. Normally 8 or 16.
2334 * @param fUnsigned Whether samples are unsigned values.
2335 * @thread The emulation thread.
2336 */
2337 DECLR3CALLBACKMEMBER(void, pfnAudioSamplesOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, void *pvSamples, uint32_t cSamples,
2338 int iSampleHz, int cChannels, int cBits, bool fUnsigned));
2339
2340 /**
2341 * AudioSniffer device calls this method when output volume is changed.
2342 *
2343 * @param pInterface Pointer to this interface.
2344 * @param u16LeftVolume 0..0xFFFF volume level for left channel.
2345 * @param u16RightVolume 0..0xFFFF volume level for right channel.
2346 * @thread The emulation thread.
2347 */
2348 DECLR3CALLBACKMEMBER(void, pfnAudioVolumeOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, uint16_t u16LeftVolume, uint16_t u16RightVolume));
2349
2350} PDMIAUDIOSNIFFERCONNECTOR;
2351
2352
2353/**
2354 * Generic status LED core.
2355 * Note that a unit doesn't have to support all the indicators.
2356 */
2357typedef union PDMLEDCORE
2358{
2359 /** 32-bit view. */
2360 uint32_t volatile u32;
2361 /** Bit view. */
2362 struct
2363 {
2364 /** Reading/Receiving indicator. */
2365 uint32_t fReading : 1;
2366 /** Writing/Sending indicator. */
2367 uint32_t fWriting : 1;
2368 /** Busy indicator. */
2369 uint32_t fBusy : 1;
2370 /** Error indicator. */
2371 uint32_t fError : 1;
2372 } s;
2373} PDMLEDCORE;
2374
2375/** LED bit masks for the u32 view.
2376 * @{ */
2377/** Reading/Receiving indicator. */
2378#define PDMLED_READING RT_BIT(0)
2379/** Writing/Sending indicator. */
2380#define PDMLED_WRITING RT_BIT(1)
2381/** Busy indicator. */
2382#define PDMLED_BUSY RT_BIT(2)
2383/** Error indicator. */
2384#define PDMLED_ERROR RT_BIT(3)
2385/** @} */
2386
2387
2388/**
2389 * Generic status LED.
2390 * Note that a unit doesn't have to support all the indicators.
2391 */
2392typedef struct PDMLED
2393{
2394 /** Just a magic for sanity checking. */
2395 uint32_t u32Magic;
2396 uint32_t u32Alignment; /**< structure size alignment. */
2397 /** The actual LED status.
2398 * Only the device is allowed to change this. */
2399 PDMLEDCORE Actual;
2400 /** The asserted LED status which is cleared by the reader.
2401 * The device will assert the bits but never clear them.
2402 * The driver clears them as it sees fit. */
2403 PDMLEDCORE Asserted;
2404} PDMLED;
2405
2406/** Pointer to an LED. */
2407typedef PDMLED *PPDMLED;
2408/** Pointer to a const LED. */
2409typedef const PDMLED *PCPDMLED;
2410
2411#define PDMLED_MAGIC ( 0x11335577 )
2412
2413/** Pointer to an LED ports interface. */
2414typedef struct PDMILEDPORTS *PPDMILEDPORTS;
2415/**
2416 * Interface for exporting LEDs.
2417 */
2418typedef struct PDMILEDPORTS
2419{
2420 /**
2421 * Gets the pointer to the status LED of a unit.
2422 *
2423 * @returns VBox status code.
2424 * @param pInterface Pointer to the interface structure containing the called function pointer.
2425 * @param iLUN The unit which status LED we desire.
2426 * @param ppLed Where to store the LED pointer.
2427 */
2428 DECLR3CALLBACKMEMBER(int, pfnQueryStatusLed,(PPDMILEDPORTS pInterface, unsigned iLUN, PPDMLED *ppLed));
2429
2430} PDMILEDPORTS;
2431
2432
2433/** Pointer to an LED connectors interface. */
2434typedef struct PDMILEDCONNECTORS *PPDMILEDCONNECTORS;
2435/**
2436 * Interface for reading LEDs.
2437 */
2438typedef struct PDMILEDCONNECTORS
2439{
2440 /**
2441 * Notification about a unit which have been changed.
2442 *
2443 * The driver must discard any pointers to data owned by
2444 * the unit and requery it.
2445 *
2446 * @param pInterface Pointer to the interface structure containing the called function pointer.
2447 * @param iLUN The unit number.
2448 */
2449 DECLR3CALLBACKMEMBER(void, pfnUnitChanged,(PPDMILEDCONNECTORS pInterface, unsigned iLUN));
2450} PDMILEDCONNECTORS;
2451
2452
2453/** The special status unit number */
2454#define PDM_STATUS_LUN 999
2455
2456
2457#ifdef VBOX_HGCM
2458
2459/** Abstract HGCM command structure. Used only to define a typed pointer. */
2460struct VBOXHGCMCMD;
2461
2462/** Pointer to HGCM command structure. This pointer is unique and identifies
2463 * the command being processed. The pointer is passed to HGCM connector methods,
2464 * and must be passed back to HGCM port when command is completed.
2465 */
2466typedef struct VBOXHGCMCMD *PVBOXHGCMCMD;
2467
2468/** Pointer to a HGCM port interface. */
2469typedef struct PDMIHGCMPORT *PPDMIHGCMPORT;
2470
2471/**
2472 * HGCM port interface. Normally implemented by VMMDev.
2473 */
2474typedef struct PDMIHGCMPORT
2475{
2476 /**
2477 * Notify the guest on a command completion.
2478 *
2479 * @param pInterface Pointer to this interface.
2480 * @param rc The return code (VBox error code).
2481 * @param pCmd A pointer that identifies the completed command.
2482 *
2483 * @returns VBox status code
2484 */
2485 DECLR3CALLBACKMEMBER(void, pfnCompleted,(PPDMIHGCMPORT pInterface, int32_t rc, PVBOXHGCMCMD pCmd));
2486
2487} PDMIHGCMPORT;
2488
2489
2490/** Pointer to a HGCM connector interface. */
2491typedef struct PDMIHGCMCONNECTOR *PPDMIHGCMCONNECTOR;
2492
2493/** Pointer to a HGCM service location structure. */
2494typedef struct HGCMSERVICELOCATION *PHGCMSERVICELOCATION;
2495
2496/**
2497 * HGCM connector interface.
2498 * Pair with PDMIHGCMPORT.
2499 */
2500typedef struct PDMIHGCMCONNECTOR
2501{
2502 /**
2503 * Locate a service and inform it about a client connection.
2504 *
2505 * @param pInterface Pointer to this interface.
2506 * @param pCmd A pointer that identifies the command.
2507 * @param pServiceLocation Pointer to the service location structure.
2508 * @param pu32ClientID Where to store the client id for the connection.
2509 * @return VBox status code.
2510 * @thread The emulation thread.
2511 */
2512 DECLR3CALLBACKMEMBER(int, pfnConnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, PHGCMSERVICELOCATION pServiceLocation, uint32_t *pu32ClientID));
2513
2514 /**
2515 * Disconnect from service.
2516 *
2517 * @param pInterface Pointer to this interface.
2518 * @param pCmd A pointer that identifies the command.
2519 * @param u32ClientID The client id returned by the pfnConnect call.
2520 * @return VBox status code.
2521 * @thread The emulation thread.
2522 */
2523 DECLR3CALLBACKMEMBER(int, pfnDisconnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID));
2524
2525 /**
2526 * Process a guest issued command.
2527 *
2528 * @param pInterface Pointer to this interface.
2529 * @param pCmd A pointer that identifies the command.
2530 * @param u32ClientID The client id returned by the pfnConnect call.
2531 * @param u32Function Function to be performed by the service.
2532 * @param cParms Number of parameters in the array pointed to by paParams.
2533 * @param paParms Pointer to an array of parameters.
2534 * @return VBox status code.
2535 * @thread The emulation thread.
2536 */
2537 DECLR3CALLBACKMEMBER(int, pfnCall,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID, uint32_t u32Function,
2538 uint32_t cParms, PVBOXHGCMSVCPARM paParms));
2539
2540} PDMIHGCMCONNECTOR;
2541
2542#endif
2543
2544/** @} */
2545
2546__END_DECLS
2547
2548#endif
Note: See TracBrowser for help on using the repository browser.

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