virt/vboxguest/vmmdev.h

0001 /* SPDX-License-Identifier: (GPL-2.0 OR CDDL-1.0) */
0002 /*
0003  * Virtual Device for Guest <-> VMM/Host communication interface
0004  *
0005  * Copyright (C) 2006-2016 Oracle Corporation
0006  */
0007
0008 #ifndef __VBOX_VMMDEV_H__
0009 #define __VBOX_VMMDEV_H__
0010
0011 #include <asm/bitsperlong.h>
0012 #include <linux/sizes.h>
0013 #include <linux/types.h>
0014 #include <linux/vbox_vmmdev_types.h>
0015
0016 /* Port for generic request interface (relative offset). */
0017 #define VMMDEV_PORT_OFF_REQUEST                             0
0018
0019 /** Layout of VMMDEV RAM region that contains information for guest. */
0020 struct vmmdev_memory {
0021     /** The size of this structure. */
0022     u32 size;
0023     /** The structure version. (VMMDEV_MEMORY_VERSION) */
0024     u32 version;
0025
0026     union {
0027         struct {
0028             /** Flag telling that VMMDev has events pending. */
0029             u8 have_events;
0030             /** Explicit padding, MBZ. */
0031             u8 padding[3];
0032         } V1_04;
0033
0034         struct {
0035             /** Pending events flags, set by host. */
0036             u32 host_events;
0037             /** Mask of events the guest wants, set by guest. */
0038             u32 guest_event_mask;
0039         } V1_03;
0040     } V;
0041
0042     /* struct vbva_memory, not used */
0043 };
0044 VMMDEV_ASSERT_SIZE(vmmdev_memory, 8 + 8);
0045
0046 /** Version of vmmdev_memory structure (vmmdev_memory::version). */
0047 #define VMMDEV_MEMORY_VERSION   (1)
0048
0049 /* Host mouse capabilities has been changed. */
0050 #define VMMDEV_EVENT_MOUSE_CAPABILITIES_CHANGED             BIT(0)
0051 /* HGCM event. */
0052 #define VMMDEV_EVENT_HGCM                                   BIT(1)
0053 /* A display change request has been issued. */
0054 #define VMMDEV_EVENT_DISPLAY_CHANGE_REQUEST                 BIT(2)
0055 /* Credentials are available for judgement. */
0056 #define VMMDEV_EVENT_JUDGE_CREDENTIALS                      BIT(3)
0057 /* The guest has been restored. */
0058 #define VMMDEV_EVENT_RESTORED                               BIT(4)
0059 /* Seamless mode state changed. */
0060 #define VMMDEV_EVENT_SEAMLESS_MODE_CHANGE_REQUEST           BIT(5)
0061 /* Memory balloon size changed. */
0062 #define VMMDEV_EVENT_BALLOON_CHANGE_REQUEST                 BIT(6)
0063 /* Statistics interval changed. */
0064 #define VMMDEV_EVENT_STATISTICS_INTERVAL_CHANGE_REQUEST     BIT(7)
0065 /* VRDP status changed. */
0066 #define VMMDEV_EVENT_VRDP                                   BIT(8)
0067 /* New mouse position data available. */
0068 #define VMMDEV_EVENT_MOUSE_POSITION_CHANGED                 BIT(9)
0069 /* CPU hotplug event occurred. */
0070 #define VMMDEV_EVENT_CPU_HOTPLUG                            BIT(10)
0071 /* The mask of valid events, for sanity checking. */
0072 #define VMMDEV_EVENT_VALID_EVENT_MASK                       0x000007ffU
0073
0074 /*
0075  * Additions are allowed to work only if additions_major == vmmdev_current &&
0076  * additions_minor <= vmmdev_current. Additions version is reported to host
0077  * (VMMDev) by VMMDEVREQ_REPORT_GUEST_INFO.
0078  */
0079 #define VMMDEV_VERSION                      0x00010004
0080 #define VMMDEV_VERSION_MAJOR                (VMMDEV_VERSION >> 16)
0081 #define VMMDEV_VERSION_MINOR                (VMMDEV_VERSION & 0xffff)
0082
0083 /* Maximum request packet size. */
0084 #define VMMDEV_MAX_VMMDEVREQ_SIZE           1048576
0085
0086 /* Version of vmmdev_request_header structure. */
0087 #define VMMDEV_REQUEST_HEADER_VERSION       0x10001
0088
0089 /** struct vmmdev_request_header - Generic VMMDev request header. */
0090 struct vmmdev_request_header {
0091     /** IN: Size of the structure in bytes (including body). */
0092     u32 size;
0093     /** IN: Version of the structure.  */
0094     u32 version;
0095     /** IN: Type of the request. */
0096     enum vmmdev_request_type request_type;
0097     /** OUT: Return code. */
0098     s32 rc;
0099     /** Reserved field no.1. MBZ. */
0100     u32 reserved1;
0101     /** IN: Requestor information (VMMDEV_REQUESTOR_*) */
0102     u32 requestor;
0103 };
0104 VMMDEV_ASSERT_SIZE(vmmdev_request_header, 24);
0105
0106 /**
0107  * struct vmmdev_mouse_status - Mouse status request structure.
0108  *
0109  * Used by VMMDEVREQ_GET_MOUSE_STATUS and VMMDEVREQ_SET_MOUSE_STATUS.
0110  */
0111 struct vmmdev_mouse_status {
0112     /** header */
0113     struct vmmdev_request_header header;
0114     /** Mouse feature mask. See VMMDEV_MOUSE_*. */
0115     u32 mouse_features;
0116     /** Mouse x position. */
0117     s32 pointer_pos_x;
0118     /** Mouse y position. */
0119     s32 pointer_pos_y;
0120 };
0121 VMMDEV_ASSERT_SIZE(vmmdev_mouse_status, 24 + 12);
0122
0123 /* The guest can (== wants to) handle absolute coordinates.  */
0124 #define VMMDEV_MOUSE_GUEST_CAN_ABSOLUTE                     BIT(0)
0125 /*
0126  * The host can (== wants to) send absolute coordinates.
0127  * (Input not captured.)
0128  */
0129 #define VMMDEV_MOUSE_HOST_WANTS_ABSOLUTE                    BIT(1)
0130 /*
0131  * The guest can *NOT* switch to software cursor and therefore depends on the
0132  * host cursor.
0133  *
0134  * When guest additions are installed and the host has promised to display the
0135  * cursor itself, the guest installs a hardware mouse driver. Don't ask the
0136  * guest to switch to a software cursor then.
0137  */
0138 #define VMMDEV_MOUSE_GUEST_NEEDS_HOST_CURSOR                BIT(2)
0139 /* The host does NOT provide support for drawing the cursor itself. */
0140 #define VMMDEV_MOUSE_HOST_CANNOT_HWPOINTER                  BIT(3)
0141 /* The guest can read VMMDev events to find out about pointer movement */
0142 #define VMMDEV_MOUSE_NEW_PROTOCOL                           BIT(4)
0143 /*
0144  * If the guest changes the status of the VMMDEV_MOUSE_GUEST_NEEDS_HOST_CURSOR
0145  * bit, the host will honour this.
0146  */
0147 #define VMMDEV_MOUSE_HOST_RECHECKS_NEEDS_HOST_CURSOR        BIT(5)
0148 /*
0149  * The host supplies an absolute pointing device.  The Guest Additions may
0150  * wish to use this to decide whether to install their own driver.
0151  */
0152 #define VMMDEV_MOUSE_HOST_HAS_ABS_DEV                       BIT(6)
0153
0154 /* The minimum value our pointing device can return. */
0155 #define VMMDEV_MOUSE_RANGE_MIN 0
0156 /* The maximum value our pointing device can return. */
0157 #define VMMDEV_MOUSE_RANGE_MAX 0xFFFF
0158
0159 /**
0160  * struct vmmdev_host_version - VirtualBox host version request structure.
0161  *
0162  * VBG uses this to detect the precense of new features in the interface.
0163  */
0164 struct vmmdev_host_version {
0165     /** Header. */
0166     struct vmmdev_request_header header;
0167     /** Major version. */
0168     u16 major;
0169     /** Minor version. */
0170     u16 minor;
0171     /** Build number. */
0172     u32 build;
0173     /** SVN revision. */
0174     u32 revision;
0175     /** Feature mask. */
0176     u32 features;
0177 };
0178 VMMDEV_ASSERT_SIZE(vmmdev_host_version, 24 + 16);
0179
0180 /* Physical page lists are supported by HGCM. */
0181 #define VMMDEV_HVF_HGCM_PHYS_PAGE_LIST  BIT(0)
0182
0183 /**
0184  * struct vmmdev_mask - Structure to set / clear bits in a mask used for
0185  * VMMDEVREQ_SET_GUEST_CAPABILITIES and VMMDEVREQ_CTL_GUEST_FILTER_MASK.
0186  */
0187 struct vmmdev_mask {
0188     /** Header. */
0189     struct vmmdev_request_header header;
0190     /** Mask of bits to be set. */
0191     u32 or_mask;
0192     /** Mask of bits to be cleared. */
0193     u32 not_mask;
0194 };
0195 VMMDEV_ASSERT_SIZE(vmmdev_mask, 24 + 8);
0196
0197 /* The guest supports seamless display rendering. */
0198 #define VMMDEV_GUEST_SUPPORTS_SEAMLESS                      BIT(0)
0199 /* The guest supports mapping guest to host windows. */
0200 #define VMMDEV_GUEST_SUPPORTS_GUEST_HOST_WINDOW_MAPPING     BIT(1)
0201 /*
0202  * The guest graphical additions are active.
0203  * Used for fast activation and deactivation of certain graphical operations
0204  * (e.g. resizing & seamless). The legacy VMMDEVREQ_REPORT_GUEST_CAPABILITIES
0205  * request sets this automatically, but VMMDEVREQ_SET_GUEST_CAPABILITIES does
0206  * not.
0207  */
0208 #define VMMDEV_GUEST_SUPPORTS_GRAPHICS                      BIT(2)
0209 /* The mask of valid capabilities, for sanity checking. */
0210 #define VMMDEV_GUEST_CAPABILITIES_MASK                      0x00000007U
0211
0212 /** struct vmmdev_hypervisorinfo - Hypervisor info structure. */
0213 struct vmmdev_hypervisorinfo {
0214     /** Header. */
0215     struct vmmdev_request_header header;
0216     /**
0217      * Guest virtual address of proposed hypervisor start.
0218      * Not used by VMMDEVREQ_GET_HYPERVISOR_INFO.
0219      */
0220     u32 hypervisor_start;
0221     /** Hypervisor size in bytes. */
0222     u32 hypervisor_size;
0223 };
0224 VMMDEV_ASSERT_SIZE(vmmdev_hypervisorinfo, 24 + 8);
0225
0226 /** struct vmmdev_events - Pending events structure. */
0227 struct vmmdev_events {
0228     /** Header. */
0229     struct vmmdev_request_header header;
0230     /** OUT: Pending event mask. */
0231     u32 events;
0232 };
0233 VMMDEV_ASSERT_SIZE(vmmdev_events, 24 + 4);
0234
0235 #define VMMDEV_OSTYPE_LINUX26       0x53000
0236 #define VMMDEV_OSTYPE_X64       BIT(8)
0237
0238 /** struct vmmdev_guestinfo - Guest information report. */
0239 struct vmmdev_guest_info {
0240     /** Header. */
0241     struct vmmdev_request_header header;
0242     /**
0243      * The VMMDev interface version expected by additions.
0244      * *Deprecated*, do not use anymore! Will be removed.
0245      */
0246     u32 interface_version;
0247     /** Guest OS type. */
0248     u32 os_type;
0249 };
0250 VMMDEV_ASSERT_SIZE(vmmdev_guest_info, 24 + 8);
0251
0252 #define VMMDEV_GUEST_INFO2_ADDITIONS_FEATURES_REQUESTOR_INFO    BIT(0)
0253
0254 /** struct vmmdev_guestinfo2 - Guest information report, version 2. */
0255 struct vmmdev_guest_info2 {
0256     /** Header. */
0257     struct vmmdev_request_header header;
0258     /** Major version. */
0259     u16 additions_major;
0260     /** Minor version. */
0261     u16 additions_minor;
0262     /** Build number. */
0263     u32 additions_build;
0264     /** SVN revision. */
0265     u32 additions_revision;
0266     /** Feature mask. */
0267     u32 additions_features;
0268     /**
0269      * The intentional meaning of this field was:
0270      * Some additional information, for example 'Beta 1' or something like
0271      * that.
0272      *
0273      * The way it was implemented was implemented: VBG_VERSION_STRING.
0274      *
0275      * This means the first three members are duplicated in this field (if
0276      * the guest build config is sane). So, the user must check this and
0277      * chop it off before usage. There is, because of the Main code's blind
0278      * trust in the field's content, no way back.
0279      */
0280     char name[128];
0281 };
0282 VMMDEV_ASSERT_SIZE(vmmdev_guest_info2, 24 + 144);
0283
0284 enum vmmdev_guest_facility_type {
0285     VBOXGUEST_FACILITY_TYPE_UNKNOWN          = 0,
0286     VBOXGUEST_FACILITY_TYPE_VBOXGUEST_DRIVER = 20,
0287     /* VBoxGINA / VBoxCredProv / pam_vbox. */
0288     VBOXGUEST_FACILITY_TYPE_AUTO_LOGON       = 90,
0289     VBOXGUEST_FACILITY_TYPE_VBOX_SERVICE     = 100,
0290     /* VBoxTray (Windows), VBoxClient (Linux, Unix). */
0291     VBOXGUEST_FACILITY_TYPE_VBOX_TRAY_CLIENT = 101,
0292     VBOXGUEST_FACILITY_TYPE_SEAMLESS         = 1000,
0293     VBOXGUEST_FACILITY_TYPE_GRAPHICS         = 1100,
0294     VBOXGUEST_FACILITY_TYPE_ALL              = 0x7ffffffe,
0295     /* Ensure the enum is a 32 bit data-type */
0296     VBOXGUEST_FACILITY_TYPE_SIZEHACK         = 0x7fffffff
0297 };
0298
0299 enum vmmdev_guest_facility_status {
0300     VBOXGUEST_FACILITY_STATUS_INACTIVE    = 0,
0301     VBOXGUEST_FACILITY_STATUS_PAUSED      = 1,
0302     VBOXGUEST_FACILITY_STATUS_PRE_INIT    = 20,
0303     VBOXGUEST_FACILITY_STATUS_INIT        = 30,
0304     VBOXGUEST_FACILITY_STATUS_ACTIVE      = 50,
0305     VBOXGUEST_FACILITY_STATUS_TERMINATING = 100,
0306     VBOXGUEST_FACILITY_STATUS_TERMINATED  = 101,
0307     VBOXGUEST_FACILITY_STATUS_FAILED      = 800,
0308     VBOXGUEST_FACILITY_STATUS_UNKNOWN     = 999,
0309     /* Ensure the enum is a 32 bit data-type */
0310     VBOXGUEST_FACILITY_STATUS_SIZEHACK    = 0x7fffffff
0311 };
0312
0313 /** struct vmmdev_guest_status - Guest Additions status structure. */
0314 struct vmmdev_guest_status {
0315     /** Header. */
0316     struct vmmdev_request_header header;
0317     /** Facility the status is indicated for. */
0318     enum vmmdev_guest_facility_type facility;
0319     /** Current guest status. */
0320     enum vmmdev_guest_facility_status status;
0321     /** Flags, not used at the moment. */
0322     u32 flags;
0323 };
0324 VMMDEV_ASSERT_SIZE(vmmdev_guest_status, 24 + 12);
0325
0326 #define VMMDEV_MEMORY_BALLOON_CHUNK_SIZE             (1048576)
0327 #define VMMDEV_MEMORY_BALLOON_CHUNK_PAGES            (1048576 / 4096)
0328
0329 /** struct vmmdev_memballoon_info - Memory-balloon info structure. */
0330 struct vmmdev_memballoon_info {
0331     /** Header. */
0332     struct vmmdev_request_header header;
0333     /** Balloon size in megabytes. */
0334     u32 balloon_chunks;
0335     /** Guest ram size in megabytes. */
0336     u32 phys_mem_chunks;
0337     /**
0338      * Setting this to VMMDEV_EVENT_BALLOON_CHANGE_REQUEST indicates that
0339      * the request is a response to that event.
0340      * (Don't confuse this with VMMDEVREQ_ACKNOWLEDGE_EVENTS.)
0341      */
0342     u32 event_ack;
0343 };
0344 VMMDEV_ASSERT_SIZE(vmmdev_memballoon_info, 24 + 12);
0345
0346 /** struct vmmdev_memballoon_change - Change the size of the balloon. */
0347 struct vmmdev_memballoon_change {
0348     /** Header. */
0349     struct vmmdev_request_header header;
0350     /** The number of pages in the array. */
0351     u32 pages;
0352     /** true = inflate, false = deflate.  */
0353     u32 inflate;
0354     /** Physical address (u64) of each page. */
0355     u64 phys_page[VMMDEV_MEMORY_BALLOON_CHUNK_PAGES];
0356 };
0357
0358 /** struct vmmdev_write_core_dump - Write Core Dump request data. */
0359 struct vmmdev_write_core_dump {
0360     /** Header. */
0361     struct vmmdev_request_header header;
0362     /** Flags (reserved, MBZ). */
0363     u32 flags;
0364 };
0365 VMMDEV_ASSERT_SIZE(vmmdev_write_core_dump, 24 + 4);
0366
0367 /** struct vmmdev_heartbeat - Heart beat check state structure. */
0368 struct vmmdev_heartbeat {
0369     /** Header. */
0370     struct vmmdev_request_header header;
0371     /** OUT: Guest heartbeat interval in nanosec. */
0372     u64 interval_ns;
0373     /** Heartbeat check flag. */
0374     u8 enabled;
0375     /** Explicit padding, MBZ. */
0376     u8 padding[3];
0377 } __packed;
0378 VMMDEV_ASSERT_SIZE(vmmdev_heartbeat, 24 + 12);
0379
0380 #define VMMDEV_HGCM_REQ_DONE      BIT(0)
0381 #define VMMDEV_HGCM_REQ_CANCELLED BIT(1)
0382
0383 /** struct vmmdev_hgcmreq_header - vmmdev HGCM requests header. */
0384 struct vmmdev_hgcmreq_header {
0385     /** Request header. */
0386     struct vmmdev_request_header header;
0387
0388     /** HGCM flags. */
0389     u32 flags;
0390
0391     /** Result code. */
0392     s32 result;
0393 };
0394 VMMDEV_ASSERT_SIZE(vmmdev_hgcmreq_header, 24 + 8);
0395
0396 /** struct vmmdev_hgcm_connect - HGCM connect request structure. */
0397 struct vmmdev_hgcm_connect {
0398     /** HGCM request header. */
0399     struct vmmdev_hgcmreq_header header;
0400
0401     /** IN: Description of service to connect to. */
0402     struct vmmdev_hgcm_service_location loc;
0403
0404     /** OUT: Client identifier assigned by local instance of HGCM. */
0405     u32 client_id;
0406 };
0407 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_connect, 32 + 132 + 4);
0408
0409 /** struct vmmdev_hgcm_disconnect - HGCM disconnect request structure. */
0410 struct vmmdev_hgcm_disconnect {
0411     /** HGCM request header. */
0412     struct vmmdev_hgcmreq_header header;
0413
0414     /** IN: Client identifier. */
0415     u32 client_id;
0416 };
0417 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_disconnect, 32 + 4);
0418
0419 #define VMMDEV_HGCM_MAX_PARMS 32
0420
0421 /** struct vmmdev_hgcm_call - HGCM call request structure. */
0422 struct vmmdev_hgcm_call {
0423     /* request header */
0424     struct vmmdev_hgcmreq_header header;
0425
0426     /** IN: Client identifier. */
0427     u32 client_id;
0428     /** IN: Service function number. */
0429     u32 function;
0430     /** IN: Number of parameters. */
0431     u32 parm_count;
0432     /** Parameters follow in form: HGCMFunctionParameter32|64 parms[X]; */
0433 };
0434 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_call, 32 + 12);
0435
0436 /**
0437  * struct vmmdev_hgcm_cancel2 - HGCM cancel request structure, version 2.
0438  *
0439  * After the request header.rc will be:
0440  *
0441  * VINF_SUCCESS when cancelled.
0442  * VERR_NOT_FOUND if the specified request cannot be found.
0443  * VERR_INVALID_PARAMETER if the address is invalid valid.
0444  */
0445 struct vmmdev_hgcm_cancel2 {
0446     /** Header. */
0447     struct vmmdev_request_header header;
0448     /** The physical address of the request to cancel. */
0449     u32 phys_req_to_cancel;
0450 };
0451 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_cancel2, 24 + 4);
0452
0453 #endif