Logo Search packages:      
Sourcecode: virtualbox-ose version File versions

VBoxGuest.h File Reference


Detailed Description

VBoxGuest - VirtualBox Guest Additions interface

Definition in file VBoxGuest.h.

#include <iprt/cdefs.h>
#include <iprt/types.h>
#include <iprt/assert.h>
#include <VBox/err.h>
#include <VBox/ostypes.h>

Go to the source code of this file.

Classes

struct  _VBoxGuestFilterMaskInfo
struct  _VBoxGuestPortInfo
struct  _VBoxGuestWaitEventInfo
struct  _VBVACMDHDR
struct  _VBVAMEMORY
struct  _VBVARECORD
struct  _VMMDevCredentials
struct  _VMMDevVideoAccelEnable
struct  _VMMDevVideoAccelFlush
struct  _VMMDevVideoSetVisibleRegion
struct  VBGLBIGREQ
struct  VBoxGuestInfo
struct  VBoxGuestStatistics
struct  VMMDevChangeMemBalloon
struct  VMMDevCtlGuestFilterMask
struct  VMMDevDisplayChangeRequest
struct  VMMDevDisplayChangeRequest2
struct  VMMDevEvents
struct  VMMDevGetHeightReductionRequest
struct  VMMDevGetMemBalloonChangeRequest
struct  VMMDevGetStatisticsChangeRequest
struct  VMMDevMemory
struct  VMMDevPowerStateRequest
struct  VMMDevReportGuestInfo
struct  VMMDevReportGuestStats
struct  VMMDevReqGuestCapabilities
struct  VMMDevReqGuestCapabilities2
struct  VMMDevReqHostTime
struct  VMMDevReqHostVersion
struct  VMMDevReqHypervisorInfo
struct  VMMDevReqIdle
struct  VMMDevReqLogString
struct  VMMDevReqMousePointer
struct  VMMDevReqMouseStatus
struct  VMMDevRequestHeader
struct  VMMDevSeamlessChangeRequest
struct  VMMDevVideoModeSupportedRequest
struct  VMMDevVRDPChangeRequest
#define HYPERVISOR_PHYSICAL_START   0xf8000000
#define PORT_VMMDEV_REQUEST_OFFSET   0
#define VBOX_GUEST_STAT_CPU_LOAD_IDLE   RT_BIT(0)
#define VBOX_GUEST_STAT_CPU_LOAD_KERNEL   RT_BIT(1)
#define VBOX_GUEST_STAT_CPU_LOAD_USER   RT_BIT(2)
#define VBOX_GUEST_STAT_HANDLES   RT_BIT(5)
#define VBOX_GUEST_STAT_MEM_COMMIT_TOTAL   RT_BIT(10)
#define VBOX_GUEST_STAT_MEM_KERNEL_NONPAGED   RT_BIT(13)
#define VBOX_GUEST_STAT_MEM_KERNEL_PAGED   RT_BIT(12)
#define VBOX_GUEST_STAT_MEM_KERNEL_TOTAL   RT_BIT(11)
#define VBOX_GUEST_STAT_MEM_SYSTEM_CACHE   RT_BIT(14)
#define VBOX_GUEST_STAT_MEMORY_LOAD   RT_BIT(6)
#define VBOX_GUEST_STAT_PAGE_FILE_SIZE   RT_BIT(15)
#define VBOX_GUEST_STAT_PHYS_MEM_AVAIL   RT_BIT(8)
#define VBOX_GUEST_STAT_PHYS_MEM_BALLOON   RT_BIT(9)
#define VBOX_GUEST_STAT_PHYS_MEM_TOTAL   RT_BIT(7)
#define VBOX_GUEST_STAT_PROCESSES   RT_BIT(4)
#define VBOX_GUEST_STAT_THREADS   RT_BIT(3)
#define VBOX_MOUSE_POINTER_ALPHA   (0x0002)
#define VBOX_MOUSE_POINTER_SHAPE   (0x0004)
#define VBOX_MOUSE_POINTER_VISIBLE   (0x0001)
#define VBOXGUEST_MOUSE_GUEST_CAN_ABSOLUTE   RT_BIT(0)
#define VBOXGUEST_MOUSE_GUEST_NEEDS_HOST_CURSOR   RT_BIT(2)
#define VBOXGUEST_MOUSE_HOST_CAN_ABSOLUTE   RT_BIT(1)
#define VBOXGUEST_MOUSE_HOST_CANNOT_HWPOINTER   RT_BIT(3)
#define VBVA_F_MODE_ENABLED   (0x00000001)
#define VBVA_F_MODE_VRDP   (0x00000002)
#define VBVA_F_MODE_VRDP_ORDER_MASK   (0x00000008)
#define VBVA_F_MODE_VRDP_RESET   (0x00000004)
#define VBVA_F_RECORD_PARTIAL   (0x80000000)
#define VBVA_F_STATUS_ACCEPTED   (0x01)
#define VBVA_F_STATUS_ENABLED   (0x02)
#define VBVA_MAX_RECORDS   (64)
#define VBVA_RING_BUFFER_SIZE   (_4M - _1K)
#define VBVA_RING_BUFFER_THRESHOLD   (4 * _1K)
#define VMMDEV_MAX_MEMORY_BALLOON(PhysMemTotal)   ((90*PhysMemTotal)/100)
#define VMMDEV_MAX_VMMDEVREQ_SIZE   _1M
#define VMMDEV_MEMORY_BALLOON_CHUNK_PAGES   (_1M/4096)
#define VMMDEV_MEMORY_BALLOON_CHUNK_SIZE   (VMMDEV_MEMORY_BALLOON_CHUNK_PAGES*4096)
#define VMMDEV_REQUEST_HEADER_VERSION   (0x10001)
#define VMMDEV_VERSION   0x00010004
#define VMMDEV_VERSION_MAJOR   (VMMDEV_VERSION >> 16)
#define VMMDEV_VERSION_MINOR   (VMMDEV_VERSION & 0xffff)
#define VRDP_EXPERIENCE_LEVEL_FULL   4
#define VRDP_EXPERIENCE_LEVEL_HIGH   3
#define VRDP_EXPERIENCE_LEVEL_LOW   1
#define VRDP_EXPERIENCE_LEVEL_MEDIUM   2
#define VRDP_EXPERIENCE_LEVEL_ZERO   0
enum  VMMDevPowerState {
  VMMDevPowerState_Invalid = 0, VMMDevPowerState_Pause = 1, VMMDevPowerState_PowerOff = 2, VMMDevPowerState_SaveState = 3,
  VMMDevPowerState_SizeHack = 0x7fffffff
}
enum  VMMDevRequestType {
  VMMDevReq_InvalidRequest = 0, VMMDevReq_GetMouseStatus = 1, VMMDevReq_SetMouseStatus = 2, VMMDevReq_SetPointerShape = 3,
  VMMDevReq_GetHostVersion = 4, VMMDevReq_Idle = 5, VMMDevReq_GetHostTime = 10, VMMDevReq_GetHypervisorInfo = 20,
  VMMDevReq_SetHypervisorInfo = 21, VMMDevReq_SetPowerStatus = 30, VMMDevReq_AcknowledgeEvents = 41, VMMDevReq_CtlGuestFilterMask = 42,
  VMMDevReq_ReportGuestInfo = 50, VMMDevReq_GetDisplayChangeRequest = 51, VMMDevReq_VideoModeSupported = 52, VMMDevReq_GetHeightReduction = 53,
  VMMDevReq_GetDisplayChangeRequest2 = 54, VMMDevReq_ReportGuestCapabilities = 55, VMMDevReq_SetGuestCapabilities = 56, VMMDevReq_VideoAccelEnable = 70,
  VMMDevReq_VideoAccelFlush = 71, VMMDevReq_VideoSetVisibleRegion = 72, VMMDevReq_GetSeamlessChangeRequest = 73, VMMDevReq_QueryCredentials = 100,
  VMMDevReq_ReportCredentialsJudgement = 101, VMMDevReq_ReportGuestStats = 110, VMMDevReq_GetMemBalloonChangeRequest = 111, VMMDevReq_GetStatisticsChangeRequest = 112,
  VMMDevReq_ChangeMemBalloon = 113, VMMDevReq_GetVRDPChangeRequest = 150, VMMDevReq_LogString = 200, VMMDevReq_SizeHack = 0x7fffffff
}
enum  VMMDevSeamlessMode { VMMDev_Seamless_Disabled = 0, VMMDev_Seamless_Visible_Region = 1, VMMDev_Seamless_Host_Window = 2 }
typedef struct _VBVACMDHDR VBVACMDHDR
typedef struct _VBVAMEMORY VBVAMEMORY
typedef struct _VBVARECORD VBVARECORD
typedef struct
_VMMDevVideoAccelEnable 
VMMDevVideoAccelEnable
typedef struct
_VMMDevVideoAccelFlush 
VMMDevVideoAccelFlush
typedef struct
_VMMDevVideoSetVisibleRegion 
VMMDevVideoSetVisibleRegion
 AssertCompileSize (VMMDevRequestHeader, 24)

VBoxGuest IOCTL codes and structures.

The range 0..15 is for basic driver communication. The range 16..31 is for HGCM communcation. The range 32..47 is reserved for future use. The range 48..63 is for OS specific communcation. The 7th bit is reserved for future hacks. The 8th bit is reserved for distinguishing between 32-bit and 64-bit processes in future 64-bit guest additions.

While windows IOCTL function number has to start at 2048 and stop at 4096 there never was any need to do this for everyone. A simple ((Function) | 0x800) would have sufficed. On Linux we're now intruding upon the type field. Fortunately this hasn't caused any trouble because the FILE_DEVICE_UNKNOWN value was set to 0x22 (if it were 0x2C it would not have worked soo smoothly). The situation would've been the same for *BSD and Darwin since they seems to share common _IOC() heritage.

However, on good old OS/2 we only have 8-bit handy for the function number. The result from using the old IOCTL function numbers her would've been overlapping between the two ranges.

To fix this problem and get rid of all the unnecessary windowsy crap that I bet was copied from my SUPDRVIOC.h once upon a time (although the concept of prefixing macros with the purpose of avoid clashes with system stuff and to indicate exactly how owns them seems to have been lost somewhere along the way), I've introduced a VBOXGUEST_IOCTL_CODE for defining generic IN/OUT IOCtls on new ports of the additions.

Remarks:
When creating new IOCtl interfaces keep in mind that not all OSes supports reporting back the output size. (This got messed up a little bit in VBoxDrv.)
The request size is also a little bit tricky as it's passed as part of the request code on unix. The size field is 14 bits on Linux, 12 bits on *BSD, 13 bits Darwin, and 8-bits on Solaris. All the BSDs and Darwin kernels will make use of the size field, while Linux and Solaris will not. We're of course using the size to validate and/or map/lock the request, so it has to be valid.

For Solaris we will have to do something special though, 255 isn't sufficent for all we need. A 4KB restriction (BSD) is probably not too problematic (yet) as a general one.

More info can be found in SUPDRVIOC.h and related sources.

Remarks:
If adding interfaces that only has input or only has output, some new macros needs to be created so the most efficient IOCtl data buffering method can be used.


#define VBGLBIGREQ_MAGIC   0x19520219
#define VBOXGUEST_IOCTL_CANCEL_ALL_WAITEVENTS   VBOXGUEST_IOCTL_CODE_(5, 0)
#define VBOXGUEST_IOCTL_CODE(Function, Size)   VBOXGUEST_IOCTL_CODE_((Function) | VBOXGUEST_IOCTL_FLAG, Size)
#define VBOXGUEST_IOCTL_CODE_FAST(Function)   VBOXGUEST_IOCTL_CODE_FAST_((Function) | VBOXGUEST_IOCTL_FLAG)
#define VBOXGUEST_IOCTL_GETVMMDEVPORT   VBOXGUEST_IOCTL_CODE(1, sizeof(VBoxGuestPortInfo))
#define VBOXGUEST_IOCTL_WAITEVENT   VBOXGUEST_IOCTL_CODE_(2, sizeof(VBoxGuestWaitEventInfo))
typedef const VBGLBIGREQPCVBGLBIGREQ
typedef VBGLBIGREQPVBGLBIGREQ
typedef struct _VBoxGuestPortInfo VBoxGuestPortInfo

Defines

#define VBOX_DEVICEID   (0xbeef)
#define VBOX_PCI_VENDORID   (0x80ee)
#define VBOX_VENDORID   VBOX_PCI_VENDORID
#define VBOX_VESA_DEVICEID   (0xbeef)
#define VBOX_VESA_VENDORID   VBOX_PCI_VENDORID
#define VBOXGUEST_IOCTL_CTL_CHECK_BALLOON_MASK   VBOXGUEST_IOCTL_CODE_(7, 100)
#define VBOXGUEST_IOCTL_CTL_FILTER_MASK   VBOXGUEST_IOCTL_CODE_(4, sizeof(VBoxGuestFilterMaskInfo))
#define VBOXGUEST_IOCTL_LOG(Size)   VBOXGUEST_IOCTL_CODE_(6, (Size))
#define VBOXGUEST_IOCTL_VMMREQUEST(Size)   VBOXGUEST_IOCTL_CODE_(3, (Size))
#define VMMDEV_CREDENTIALS_CLEAR   RT_BIT(3)
#define VMMDEV_CREDENTIALS_CLEARJUDGE   RT_BIT(9)
#define VMMDEV_CREDENTIALS_JUDGE_DENY   RT_BIT(11)
#define VMMDEV_CREDENTIALS_JUDGE_NOJUDGEMENT   RT_BIT(12)
#define VMMDEV_CREDENTIALS_JUDGE_OK   RT_BIT(10)
#define VMMDEV_CREDENTIALS_NOLOCALLOGON   RT_BIT(17)
#define VMMDEV_CREDENTIALS_PRESENT   RT_BIT(16)
#define VMMDEV_CREDENTIALS_QUERYPRESENCE   RT_BIT(1)
#define VMMDEV_CREDENTIALS_READ   RT_BIT(2)
#define VMMDEV_CREDENTIALS_READJUDGE   RT_BIT(8)
#define VMMDEV_CREDENTIALS_STRLEN   128
#define VMMDEV_DEVICEID   (0xcafe)
#define VMMDEV_VENDORID   VBOX_PCI_VENDORID
#define VMMDEVHYPPHYS   VMMDEVHYPPHYS32
#define VMMDEVHYPPTR   VMMDEVHYPPTR32
Result codes for VBoxGuestWaitEventInfo::u32Result
#define VBOXGUEST_WAITEVENT_ERROR   (3)
#define VBOXGUEST_WAITEVENT_INTERRUPTED   (2)
#define VBOXGUEST_WAITEVENT_OK   (0)
#define VBOXGUEST_WAITEVENT_TIMEOUT   (1)
#define VMMDEV_EVENT_BALLOON_CHANGE_REQUEST   RT_BIT(6)
#define VMMDEV_EVENT_DISPLAY_CHANGE_REQUEST   RT_BIT(2)
#define VMMDEV_EVENT_HGCM   RT_BIT(1)
#define VMMDEV_EVENT_JUDGE_CREDENTIALS   RT_BIT(3)
#define VMMDEV_EVENT_MOUSE_CAPABILITIES_CHANGED   RT_BIT(0)
#define VMMDEV_EVENT_MOUSE_POSITION_CHANGED   RT_BIT(9)
#define VMMDEV_EVENT_RESTORED   RT_BIT(4)
#define VMMDEV_EVENT_SEAMLESS_MODE_CHANGE_REQUEST   RT_BIT(5)
#define VMMDEV_EVENT_STATISTICS_INTERVAL_CHANGE_REQUEST   RT_BIT(7)
#define VMMDEV_EVENT_VRDP   RT_BIT(8)
#define VMMDEV_MEMORY_VERSION   (1)

Typedefs

typedef struct
_VBoxGuestFilterMaskInfo 
VBoxGuestFilterMaskInfo
typedef struct
_VBoxGuestWaitEventInfo 
VBoxGuestWaitEventInfo
typedef struct _VMMDevCredentials VMMDevCredentials
typedef RTGCPHYS32 VMMDEVHYPPHYS32
typedef RTGCPHYS64 VMMDEVHYPPHYS64
typedef RTGCPTR32 VMMDEVHYPPTR32
typedef RTGCPTR64 VMMDEVHYPPTR64

Functions

 AssertCompileSize (VBoxGuestFilterMaskInfo, 8)
 AssertCompileSize (VBoxGuestWaitEventInfo, 16)
 DECLINLINE (int) vmmdevInitRequest(VMMDevRequestHeader *req
 DECLINLINE (size_t) vmmdevGetRequestSize(VMMDevRequestType requestType)


Generated by  Doxygen 1.6.0   Back to index