pdmifs.h@ 6076

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: