drivers/virt/vboxguest/vmmdev.h

   1 /* SPDX-License-Identifier: (GPL-2.0 OR CDDL-1.0) */
   2 /*
   3  * Virtual Device for Guest <-> VMM/Host communication interface
   4  *
   5  * Copyright (C) 2006-2016 Oracle Corporation
   6  */
   7
   8 #ifndef __VBOX_VMMDEV_H__
   9 #define __VBOX_VMMDEV_H__
  10
  11 #include <asm/bitsperlong.h>
  12 #include <linux/sizes.h>
  13 #include <linux/types.h>
  14 #include <linux/vbox_vmmdev_types.h>
  15
  16 /* Port for generic request interface (relative offset). */
  17 #define VMMDEV_PORT_OFF_REQUEST                             0
  18
  19 /** Layout of VMMDEV RAM region that contains information for guest. */
  20 struct vmmdev_memory {
  21         /** The size of this structure. */
  22         u32 size;
  23         /** The structure version. (VMMDEV_MEMORY_VERSION) */
  24         u32 version;
  25
  26         union {
  27                 struct {
  28                         /** Flag telling that VMMDev has events pending. */
  29                         u8 have_events;
  30                         /** Explicit padding, MBZ. */
  31                         u8 padding[3];
  32                 } V1_04;
  33
  34                 struct {
  35                         /** Pending events flags, set by host. */
  36                         u32 host_events;
  37                         /** Mask of events the guest wants, set by guest. */
  38                         u32 guest_event_mask;
  39                 } V1_03;
  40         } V;
  41
  42         /* struct vbva_memory, not used */
  43 };
  44 VMMDEV_ASSERT_SIZE(vmmdev_memory, 8 + 8);
  45
  46 /** Version of vmmdev_memory structure (vmmdev_memory::version). */
  47 #define VMMDEV_MEMORY_VERSION   (1)
  48
  49 /* Host mouse capabilities has been changed. */
  50 #define VMMDEV_EVENT_MOUSE_CAPABILITIES_CHANGED             BIT(0)
  51 /* HGCM event. */
  52 #define VMMDEV_EVENT_HGCM                                   BIT(1)
  53 /* A display change request has been issued. */
  54 #define VMMDEV_EVENT_DISPLAY_CHANGE_REQUEST                 BIT(2)
  55 /* Credentials are available for judgement. */
  56 #define VMMDEV_EVENT_JUDGE_CREDENTIALS                      BIT(3)
  57 /* The guest has been restored. */
  58 #define VMMDEV_EVENT_RESTORED                               BIT(4)
  59 /* Seamless mode state changed. */
  60 #define VMMDEV_EVENT_SEAMLESS_MODE_CHANGE_REQUEST           BIT(5)
  61 /* Memory balloon size changed. */
  62 #define VMMDEV_EVENT_BALLOON_CHANGE_REQUEST                 BIT(6)
  63 /* Statistics interval changed. */
  64 #define VMMDEV_EVENT_STATISTICS_INTERVAL_CHANGE_REQUEST     BIT(7)
  65 /* VRDP status changed. */
  66 #define VMMDEV_EVENT_VRDP                                   BIT(8)
  67 /* New mouse position data available. */
  68 #define VMMDEV_EVENT_MOUSE_POSITION_CHANGED                 BIT(9)
  69 /* CPU hotplug event occurred. */
  70 #define VMMDEV_EVENT_CPU_HOTPLUG                            BIT(10)
  71 /* The mask of valid events, for sanity checking. */
  72 #define VMMDEV_EVENT_VALID_EVENT_MASK                       0x000007ffU
  73
  74 /*
  75  * Additions are allowed to work only if additions_major == vmmdev_current &&
  76  * additions_minor <= vmmdev_current. Additions version is reported to host
  77  * (VMMDev) by VMMDEVREQ_REPORT_GUEST_INFO.
  78  */
  79 #define VMMDEV_VERSION                      0x00010004
  80 #define VMMDEV_VERSION_MAJOR                (VMMDEV_VERSION >> 16)
  81 #define VMMDEV_VERSION_MINOR                (VMMDEV_VERSION & 0xffff)
  82
  83 /* Maximum request packet size. */
  84 #define VMMDEV_MAX_VMMDEVREQ_SIZE           1048576
  85
  86 /* Version of vmmdev_request_header structure. */
  87 #define VMMDEV_REQUEST_HEADER_VERSION       0x10001
  88
  89 /** struct vmmdev_request_header - Generic VMMDev request header. */
  90 struct vmmdev_request_header {
  91         /** IN: Size of the structure in bytes (including body). */
  92         u32 size;
  93         /** IN: Version of the structure.  */
  94         u32 version;
  95         /** IN: Type of the request. */
  96         enum vmmdev_request_type request_type;
  97         /** OUT: Return code. */
  98         s32 rc;
  99         /** Reserved field no.1. MBZ. */
 100         u32 reserved1;
 101         /** Reserved field no.2. MBZ. */
 102         u32 reserved2;
 103 };
 104 VMMDEV_ASSERT_SIZE(vmmdev_request_header, 24);
 105
 106 /**
 107  * struct vmmdev_mouse_status - Mouse status request structure.
 108  *
 109  * Used by VMMDEVREQ_GET_MOUSE_STATUS and VMMDEVREQ_SET_MOUSE_STATUS.
 110  */
 111 struct vmmdev_mouse_status {
 112         /** header */
 113         struct vmmdev_request_header header;
 114         /** Mouse feature mask. See VMMDEV_MOUSE_*. */
 115         u32 mouse_features;
 116         /** Mouse x position. */
 117         s32 pointer_pos_x;
 118         /** Mouse y position. */
 119         s32 pointer_pos_y;
 120 };
 121 VMMDEV_ASSERT_SIZE(vmmdev_mouse_status, 24 + 12);
 122
 123 /* The guest can (== wants to) handle absolute coordinates.  */
 124 #define VMMDEV_MOUSE_GUEST_CAN_ABSOLUTE                     BIT(0)
 125 /*
 126  * The host can (== wants to) send absolute coordinates.
 127  * (Input not captured.)
 128  */
 129 #define VMMDEV_MOUSE_HOST_WANTS_ABSOLUTE                    BIT(1)
 130 /*
 131  * The guest can *NOT* switch to software cursor and therefore depends on the
 132  * host cursor.
 133  *
 134  * When guest additions are installed and the host has promised to display the
 135  * cursor itself, the guest installs a hardware mouse driver. Don't ask the
 136  * guest to switch to a software cursor then.
 137  */
 138 #define VMMDEV_MOUSE_GUEST_NEEDS_HOST_CURSOR                BIT(2)
 139 /* The host does NOT provide support for drawing the cursor itself. */
 140 #define VMMDEV_MOUSE_HOST_CANNOT_HWPOINTER                  BIT(3)
 141 /* The guest can read VMMDev events to find out about pointer movement */
 142 #define VMMDEV_MOUSE_NEW_PROTOCOL                           BIT(4)
 143 /*
 144  * If the guest changes the status of the VMMDEV_MOUSE_GUEST_NEEDS_HOST_CURSOR
 145  * bit, the host will honour this.
 146  */
 147 #define VMMDEV_MOUSE_HOST_RECHECKS_NEEDS_HOST_CURSOR        BIT(5)
 148 /*
 149  * The host supplies an absolute pointing device.  The Guest Additions may
 150  * wish to use this to decide whether to install their own driver.
 151  */
 152 #define VMMDEV_MOUSE_HOST_HAS_ABS_DEV                       BIT(6)
 153
 154 /* The minimum value our pointing device can return. */
 155 #define VMMDEV_MOUSE_RANGE_MIN 0
 156 /* The maximum value our pointing device can return. */
 157 #define VMMDEV_MOUSE_RANGE_MAX 0xFFFF
 158
 159 /**
 160  * struct vmmdev_host_version - VirtualBox host version request structure.
 161  *
 162  * VBG uses this to detect the precense of new features in the interface.
 163  */
 164 struct vmmdev_host_version {
 165         /** Header. */
 166         struct vmmdev_request_header header;
 167         /** Major version. */
 168         u16 major;
 169         /** Minor version. */
 170         u16 minor;
 171         /** Build number. */
 172         u32 build;
 173         /** SVN revision. */
 174         u32 revision;
 175         /** Feature mask. */
 176         u32 features;
 177 };
 178 VMMDEV_ASSERT_SIZE(vmmdev_host_version, 24 + 16);
 179
 180 /* Physical page lists are supported by HGCM. */
 181 #define VMMDEV_HVF_HGCM_PHYS_PAGE_LIST  BIT(0)
 182
 183 /**
 184  * struct vmmdev_mask - Structure to set / clear bits in a mask used for
 185  * VMMDEVREQ_SET_GUEST_CAPABILITIES and VMMDEVREQ_CTL_GUEST_FILTER_MASK.
 186  */
 187 struct vmmdev_mask {
 188         /** Header. */
 189         struct vmmdev_request_header header;
 190         /** Mask of bits to be set. */
 191         u32 or_mask;
 192         /** Mask of bits to be cleared. */
 193         u32 not_mask;
 194 };
 195 VMMDEV_ASSERT_SIZE(vmmdev_mask, 24 + 8);
 196
 197 /* The guest supports seamless display rendering. */
 198 #define VMMDEV_GUEST_SUPPORTS_SEAMLESS                      BIT(0)
 199 /* The guest supports mapping guest to host windows. */
 200 #define VMMDEV_GUEST_SUPPORTS_GUEST_HOST_WINDOW_MAPPING     BIT(1)
 201 /*
 202  * The guest graphical additions are active.
 203  * Used for fast activation and deactivation of certain graphical operations
 204  * (e.g. resizing & seamless). The legacy VMMDEVREQ_REPORT_GUEST_CAPABILITIES
 205  * request sets this automatically, but VMMDEVREQ_SET_GUEST_CAPABILITIES does
 206  * not.
 207  */
 208 #define VMMDEV_GUEST_SUPPORTS_GRAPHICS                      BIT(2)
 209
 210 /** struct vmmdev_hypervisorinfo - Hypervisor info structure. */
 211 struct vmmdev_hypervisorinfo {
 212         /** Header. */
 213         struct vmmdev_request_header header;
 214         /**
 215          * Guest virtual address of proposed hypervisor start.
 216          * Not used by VMMDEVREQ_GET_HYPERVISOR_INFO.
 217          */
 218         u32 hypervisor_start;
 219         /** Hypervisor size in bytes. */
 220         u32 hypervisor_size;
 221 };
 222 VMMDEV_ASSERT_SIZE(vmmdev_hypervisorinfo, 24 + 8);
 223
 224 /** struct vmmdev_events - Pending events structure. */
 225 struct vmmdev_events {
 226         /** Header. */
 227         struct vmmdev_request_header header;
 228         /** OUT: Pending event mask. */
 229         u32 events;
 230 };
 231 VMMDEV_ASSERT_SIZE(vmmdev_events, 24 + 4);
 232
 233 #define VMMDEV_OSTYPE_LINUX26           0x53000
 234 #define VMMDEV_OSTYPE_X64               BIT(8)
 235
 236 /** struct vmmdev_guestinfo - Guest information report. */
 237 struct vmmdev_guest_info {
 238         /** Header. */
 239         struct vmmdev_request_header header;
 240         /**
 241          * The VMMDev interface version expected by additions.
 242          * *Deprecated*, do not use anymore! Will be removed.
 243          */
 244         u32 interface_version;
 245         /** Guest OS type. */
 246         u32 os_type;
 247 };
 248 VMMDEV_ASSERT_SIZE(vmmdev_guest_info, 24 + 8);
 249
 250 /** struct vmmdev_guestinfo2 - Guest information report, version 2. */
 251 struct vmmdev_guest_info2 {
 252         /** Header. */
 253         struct vmmdev_request_header header;
 254         /** Major version. */
 255         u16 additions_major;
 256         /** Minor version. */
 257         u16 additions_minor;
 258         /** Build number. */
 259         u32 additions_build;
 260         /** SVN revision. */
 261         u32 additions_revision;
 262         /** Feature mask, currently unused. */
 263         u32 additions_features;
 264         /**
 265          * The intentional meaning of this field was:
 266          * Some additional information, for example 'Beta 1' or something like
 267          * that.
 268          *
 269          * The way it was implemented was implemented: VBG_VERSION_STRING.
 270          *
 271          * This means the first three members are duplicated in this field (if
 272          * the guest build config is sane). So, the user must check this and
 273          * chop it off before usage. There is, because of the Main code's blind
 274          * trust in the field's content, no way back.
 275          */
 276         char name[128];
 277 };
 278 VMMDEV_ASSERT_SIZE(vmmdev_guest_info2, 24 + 144);
 279
 280 enum vmmdev_guest_facility_type {
 281         VBOXGUEST_FACILITY_TYPE_UNKNOWN          = 0,
 282         VBOXGUEST_FACILITY_TYPE_VBOXGUEST_DRIVER = 20,
 283         /* VBoxGINA / VBoxCredProv / pam_vbox. */
 284         VBOXGUEST_FACILITY_TYPE_AUTO_LOGON       = 90,
 285         VBOXGUEST_FACILITY_TYPE_VBOX_SERVICE     = 100,
 286         /* VBoxTray (Windows), VBoxClient (Linux, Unix). */
 287         VBOXGUEST_FACILITY_TYPE_VBOX_TRAY_CLIENT = 101,
 288         VBOXGUEST_FACILITY_TYPE_SEAMLESS         = 1000,
 289         VBOXGUEST_FACILITY_TYPE_GRAPHICS         = 1100,
 290         VBOXGUEST_FACILITY_TYPE_ALL              = 0x7ffffffe,
 291         /* Ensure the enum is a 32 bit data-type */
 292         VBOXGUEST_FACILITY_TYPE_SIZEHACK         = 0x7fffffff
 293 };
 294
 295 enum vmmdev_guest_facility_status {
 296         VBOXGUEST_FACILITY_STATUS_INACTIVE    = 0,
 297         VBOXGUEST_FACILITY_STATUS_PAUSED      = 1,
 298         VBOXGUEST_FACILITY_STATUS_PRE_INIT    = 20,
 299         VBOXGUEST_FACILITY_STATUS_INIT        = 30,
 300         VBOXGUEST_FACILITY_STATUS_ACTIVE      = 50,
 301         VBOXGUEST_FACILITY_STATUS_TERMINATING = 100,
 302         VBOXGUEST_FACILITY_STATUS_TERMINATED  = 101,
 303         VBOXGUEST_FACILITY_STATUS_FAILED      = 800,
 304         VBOXGUEST_FACILITY_STATUS_UNKNOWN     = 999,
 305         /* Ensure the enum is a 32 bit data-type */
 306         VBOXGUEST_FACILITY_STATUS_SIZEHACK    = 0x7fffffff
 307 };
 308
 309 /** struct vmmdev_guest_status - Guest Additions status structure. */
 310 struct vmmdev_guest_status {
 311         /** Header. */
 312         struct vmmdev_request_header header;
 313         /** Facility the status is indicated for. */
 314         enum vmmdev_guest_facility_type facility;
 315         /** Current guest status. */
 316         enum vmmdev_guest_facility_status status;
 317         /** Flags, not used at the moment. */
 318         u32 flags;
 319 };
 320 VMMDEV_ASSERT_SIZE(vmmdev_guest_status, 24 + 12);
 321
 322 #define VMMDEV_MEMORY_BALLOON_CHUNK_SIZE             (1048576)
 323 #define VMMDEV_MEMORY_BALLOON_CHUNK_PAGES            (1048576 / 4096)
 324
 325 /** struct vmmdev_memballoon_info - Memory-balloon info structure. */
 326 struct vmmdev_memballoon_info {
 327         /** Header. */
 328         struct vmmdev_request_header header;
 329         /** Balloon size in megabytes. */
 330         u32 balloon_chunks;
 331         /** Guest ram size in megabytes. */
 332         u32 phys_mem_chunks;
 333         /**
 334          * Setting this to VMMDEV_EVENT_BALLOON_CHANGE_REQUEST indicates that
 335          * the request is a response to that event.
 336          * (Don't confuse this with VMMDEVREQ_ACKNOWLEDGE_EVENTS.)
 337          */
 338         u32 event_ack;
 339 };
 340 VMMDEV_ASSERT_SIZE(vmmdev_memballoon_info, 24 + 12);
 341
 342 /** struct vmmdev_memballoon_change - Change the size of the balloon. */
 343 struct vmmdev_memballoon_change {
 344         /** Header. */
 345         struct vmmdev_request_header header;
 346         /** The number of pages in the array. */
 347         u32 pages;
 348         /** true = inflate, false = deflate.  */
 349         u32 inflate;
 350         /** Physical address (u64) of each page. */
 351         u64 phys_page[VMMDEV_MEMORY_BALLOON_CHUNK_PAGES];
 352 };
 353
 354 /** struct vmmdev_write_core_dump - Write Core Dump request data. */
 355 struct vmmdev_write_core_dump {
 356         /** Header. */
 357         struct vmmdev_request_header header;
 358         /** Flags (reserved, MBZ). */
 359         u32 flags;
 360 };
 361 VMMDEV_ASSERT_SIZE(vmmdev_write_core_dump, 24 + 4);
 362
 363 /** struct vmmdev_heartbeat - Heart beat check state structure. */
 364 struct vmmdev_heartbeat {
 365         /** Header. */
 366         struct vmmdev_request_header header;
 367         /** OUT: Guest heartbeat interval in nanosec. */
 368         u64 interval_ns;
 369         /** Heartbeat check flag. */
 370         u8 enabled;
 371         /** Explicit padding, MBZ. */
 372         u8 padding[3];
 373 } __packed;
 374 VMMDEV_ASSERT_SIZE(vmmdev_heartbeat, 24 + 12);
 375
 376 #define VMMDEV_HGCM_REQ_DONE      BIT(0)
 377 #define VMMDEV_HGCM_REQ_CANCELLED BIT(1)
 378
 379 /** struct vmmdev_hgcmreq_header - vmmdev HGCM requests header. */
 380 struct vmmdev_hgcmreq_header {
 381         /** Request header. */
 382         struct vmmdev_request_header header;
 383
 384         /** HGCM flags. */
 385         u32 flags;
 386
 387         /** Result code. */
 388         s32 result;
 389 };
 390 VMMDEV_ASSERT_SIZE(vmmdev_hgcmreq_header, 24 + 8);
 391
 392 /** struct vmmdev_hgcm_connect - HGCM connect request structure. */
 393 struct vmmdev_hgcm_connect {
 394         /** HGCM request header. */
 395         struct vmmdev_hgcmreq_header header;
 396
 397         /** IN: Description of service to connect to. */
 398         struct vmmdev_hgcm_service_location loc;
 399
 400         /** OUT: Client identifier assigned by local instance of HGCM. */
 401         u32 client_id;
 402 };
 403 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_connect, 32 + 132 + 4);
 404
 405 /** struct vmmdev_hgcm_disconnect - HGCM disconnect request structure. */
 406 struct vmmdev_hgcm_disconnect {
 407         /** HGCM request header. */
 408         struct vmmdev_hgcmreq_header header;
 409
 410         /** IN: Client identifier. */
 411         u32 client_id;
 412 };
 413 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_disconnect, 32 + 4);
 414
 415 #define VMMDEV_HGCM_MAX_PARMS 32
 416
 417 /** struct vmmdev_hgcm_call - HGCM call request structure. */
 418 struct vmmdev_hgcm_call {
 419         /* request header */
 420         struct vmmdev_hgcmreq_header header;
 421
 422         /** IN: Client identifier. */
 423         u32 client_id;
 424         /** IN: Service function number. */
 425         u32 function;
 426         /** IN: Number of parameters. */
 427         u32 parm_count;
 428         /** Parameters follow in form: HGCMFunctionParameter32|64 parms[X]; */
 429 };
 430 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_call, 32 + 12);
 431
 432 /**
 433  * struct vmmdev_hgcm_cancel2 - HGCM cancel request structure, version 2.
 434  *
 435  * After the request header.rc will be:
 436  *
 437  * VINF_SUCCESS when cancelled.
 438  * VERR_NOT_FOUND if the specified request cannot be found.
 439  * VERR_INVALID_PARAMETER if the address is invalid valid.
 440  */
 441 struct vmmdev_hgcm_cancel2 {
 442         /** Header. */
 443         struct vmmdev_request_header header;
 444         /** The physical address of the request to cancel. */
 445         u32 phys_req_to_cancel;
 446 };
 447 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_cancel2, 24 + 4);
 448
 449 #endif