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         /** IN: Requestor information (VMMDEV_REQUESTOR_*) */
 102         u32 requestor;
 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 /* The mask of valid capabilities, for sanity checking. */
 210 #define VMMDEV_GUEST_CAPABILITIES_MASK                      0x00000007U
 211
 212 /** struct vmmdev_hypervisorinfo - Hypervisor info structure. */
 213 struct vmmdev_hypervisorinfo {
 214         /** Header. */
 215         struct vmmdev_request_header header;
 216         /**
 217          * Guest virtual address of proposed hypervisor start.
 218          * Not used by VMMDEVREQ_GET_HYPERVISOR_INFO.
 219          */
 220         u32 hypervisor_start;
 221         /** Hypervisor size in bytes. */
 222         u32 hypervisor_size;
 223 };
 224 VMMDEV_ASSERT_SIZE(vmmdev_hypervisorinfo, 24 + 8);
 225
 226 /** struct vmmdev_events - Pending events structure. */
 227 struct vmmdev_events {
 228         /** Header. */
 229         struct vmmdev_request_header header;
 230         /** OUT: Pending event mask. */
 231         u32 events;
 232 };
 233 VMMDEV_ASSERT_SIZE(vmmdev_events, 24 + 4);
 234
 235 #define VMMDEV_OSTYPE_LINUX26           0x53000
 236 #define VMMDEV_OSTYPE_X64               BIT(8)
 237
 238 /** struct vmmdev_guestinfo - Guest information report. */
 239 struct vmmdev_guest_info {
 240         /** Header. */
 241         struct vmmdev_request_header header;
 242         /**
 243          * The VMMDev interface version expected by additions.
 244          * *Deprecated*, do not use anymore! Will be removed.
 245          */
 246         u32 interface_version;
 247         /** Guest OS type. */
 248         u32 os_type;
 249 };
 250 VMMDEV_ASSERT_SIZE(vmmdev_guest_info, 24 + 8);
 251
 252 #define VMMDEV_GUEST_INFO2_ADDITIONS_FEATURES_REQUESTOR_INFO    BIT(0)
 253
 254 /** struct vmmdev_guestinfo2 - Guest information report, version 2. */
 255 struct vmmdev_guest_info2 {
 256         /** Header. */
 257         struct vmmdev_request_header header;
 258         /** Major version. */
 259         u16 additions_major;
 260         /** Minor version. */
 261         u16 additions_minor;
 262         /** Build number. */
 263         u32 additions_build;
 264         /** SVN revision. */
 265         u32 additions_revision;
 266         /** Feature mask. */
 267         u32 additions_features;
 268         /**
 269          * The intentional meaning of this field was:
 270          * Some additional information, for example 'Beta 1' or something like
 271          * that.
 272          *
 273          * The way it was implemented was implemented: VBG_VERSION_STRING.
 274          *
 275          * This means the first three members are duplicated in this field (if
 276          * the guest build config is sane). So, the user must check this and
 277          * chop it off before usage. There is, because of the Main code's blind
 278          * trust in the field's content, no way back.
 279          */
 280         char name[128];
 281 };
 282 VMMDEV_ASSERT_SIZE(vmmdev_guest_info2, 24 + 144);
 283
 284 enum vmmdev_guest_facility_type {
 285         VBOXGUEST_FACILITY_TYPE_UNKNOWN          = 0,
 286         VBOXGUEST_FACILITY_TYPE_VBOXGUEST_DRIVER = 20,
 287         /* VBoxGINA / VBoxCredProv / pam_vbox. */
 288         VBOXGUEST_FACILITY_TYPE_AUTO_LOGON       = 90,
 289         VBOXGUEST_FACILITY_TYPE_VBOX_SERVICE     = 100,
 290         /* VBoxTray (Windows), VBoxClient (Linux, Unix). */
 291         VBOXGUEST_FACILITY_TYPE_VBOX_TRAY_CLIENT = 101,
 292         VBOXGUEST_FACILITY_TYPE_SEAMLESS         = 1000,
 293         VBOXGUEST_FACILITY_TYPE_GRAPHICS         = 1100,
 294         VBOXGUEST_FACILITY_TYPE_ALL              = 0x7ffffffe,
 295         /* Ensure the enum is a 32 bit data-type */
 296         VBOXGUEST_FACILITY_TYPE_SIZEHACK         = 0x7fffffff
 297 };
 298
 299 enum vmmdev_guest_facility_status {
 300         VBOXGUEST_FACILITY_STATUS_INACTIVE    = 0,
 301         VBOXGUEST_FACILITY_STATUS_PAUSED      = 1,
 302         VBOXGUEST_FACILITY_STATUS_PRE_INIT    = 20,
 303         VBOXGUEST_FACILITY_STATUS_INIT        = 30,
 304         VBOXGUEST_FACILITY_STATUS_ACTIVE      = 50,
 305         VBOXGUEST_FACILITY_STATUS_TERMINATING = 100,
 306         VBOXGUEST_FACILITY_STATUS_TERMINATED  = 101,
 307         VBOXGUEST_FACILITY_STATUS_FAILED      = 800,
 308         VBOXGUEST_FACILITY_STATUS_UNKNOWN     = 999,
 309         /* Ensure the enum is a 32 bit data-type */
 310         VBOXGUEST_FACILITY_STATUS_SIZEHACK    = 0x7fffffff
 311 };
 312
 313 /** struct vmmdev_guest_status - Guest Additions status structure. */
 314 struct vmmdev_guest_status {
 315         /** Header. */
 316         struct vmmdev_request_header header;
 317         /** Facility the status is indicated for. */
 318         enum vmmdev_guest_facility_type facility;
 319         /** Current guest status. */
 320         enum vmmdev_guest_facility_status status;
 321         /** Flags, not used at the moment. */
 322         u32 flags;
 323 };
 324 VMMDEV_ASSERT_SIZE(vmmdev_guest_status, 24 + 12);
 325
 326 #define VMMDEV_MEMORY_BALLOON_CHUNK_SIZE             (1048576)
 327 #define VMMDEV_MEMORY_BALLOON_CHUNK_PAGES            (1048576 / 4096)
 328
 329 /** struct vmmdev_memballoon_info - Memory-balloon info structure. */
 330 struct vmmdev_memballoon_info {
 331         /** Header. */
 332         struct vmmdev_request_header header;
 333         /** Balloon size in megabytes. */
 334         u32 balloon_chunks;
 335         /** Guest ram size in megabytes. */
 336         u32 phys_mem_chunks;
 337         /**
 338          * Setting this to VMMDEV_EVENT_BALLOON_CHANGE_REQUEST indicates that
 339          * the request is a response to that event.
 340          * (Don't confuse this with VMMDEVREQ_ACKNOWLEDGE_EVENTS.)
 341          */
 342         u32 event_ack;
 343 };
 344 VMMDEV_ASSERT_SIZE(vmmdev_memballoon_info, 24 + 12);
 345
 346 /** struct vmmdev_memballoon_change - Change the size of the balloon. */
 347 struct vmmdev_memballoon_change {
 348         /** Header. */
 349         struct vmmdev_request_header header;
 350         /** The number of pages in the array. */
 351         u32 pages;
 352         /** true = inflate, false = deflate.  */
 353         u32 inflate;
 354         /** Physical address (u64) of each page. */
 355         u64 phys_page[VMMDEV_MEMORY_BALLOON_CHUNK_PAGES];
 356 };
 357
 358 /** struct vmmdev_write_core_dump - Write Core Dump request data. */
 359 struct vmmdev_write_core_dump {
 360         /** Header. */
 361         struct vmmdev_request_header header;
 362         /** Flags (reserved, MBZ). */
 363         u32 flags;
 364 };
 365 VMMDEV_ASSERT_SIZE(vmmdev_write_core_dump, 24 + 4);
 366
 367 /** struct vmmdev_heartbeat - Heart beat check state structure. */
 368 struct vmmdev_heartbeat {
 369         /** Header. */
 370         struct vmmdev_request_header header;
 371         /** OUT: Guest heartbeat interval in nanosec. */
 372         u64 interval_ns;
 373         /** Heartbeat check flag. */
 374         u8 enabled;
 375         /** Explicit padding, MBZ. */
 376         u8 padding[3];
 377 } __packed;
 378 VMMDEV_ASSERT_SIZE(vmmdev_heartbeat, 24 + 12);
 379
 380 #define VMMDEV_HGCM_REQ_DONE      BIT(0)
 381 #define VMMDEV_HGCM_REQ_CANCELLED BIT(1)
 382
 383 /** struct vmmdev_hgcmreq_header - vmmdev HGCM requests header. */
 384 struct vmmdev_hgcmreq_header {
 385         /** Request header. */
 386         struct vmmdev_request_header header;
 387
 388         /** HGCM flags. */
 389         u32 flags;
 390
 391         /** Result code. */
 392         s32 result;
 393 };
 394 VMMDEV_ASSERT_SIZE(vmmdev_hgcmreq_header, 24 + 8);
 395
 396 /** struct vmmdev_hgcm_connect - HGCM connect request structure. */
 397 struct vmmdev_hgcm_connect {
 398         /** HGCM request header. */
 399         struct vmmdev_hgcmreq_header header;
 400
 401         /** IN: Description of service to connect to. */
 402         struct vmmdev_hgcm_service_location loc;
 403
 404         /** OUT: Client identifier assigned by local instance of HGCM. */
 405         u32 client_id;
 406 };
 407 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_connect, 32 + 132 + 4);
 408
 409 /** struct vmmdev_hgcm_disconnect - HGCM disconnect request structure. */
 410 struct vmmdev_hgcm_disconnect {
 411         /** HGCM request header. */
 412         struct vmmdev_hgcmreq_header header;
 413
 414         /** IN: Client identifier. */
 415         u32 client_id;
 416 };
 417 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_disconnect, 32 + 4);
 418
 419 #define VMMDEV_HGCM_MAX_PARMS 32
 420
 421 /** struct vmmdev_hgcm_call - HGCM call request structure. */
 422 struct vmmdev_hgcm_call {
 423         /* request header */
 424         struct vmmdev_hgcmreq_header header;
 425
 426         /** IN: Client identifier. */
 427         u32 client_id;
 428         /** IN: Service function number. */
 429         u32 function;
 430         /** IN: Number of parameters. */
 431         u32 parm_count;
 432         /** Parameters follow in form: HGCMFunctionParameter32|64 parms[X]; */
 433 };
 434 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_call, 32 + 12);
 435
 436 /**
 437  * struct vmmdev_hgcm_cancel2 - HGCM cancel request structure, version 2.
 438  *
 439  * After the request header.rc will be:
 440  *
 441  * VINF_SUCCESS when cancelled.
 442  * VERR_NOT_FOUND if the specified request cannot be found.
 443  * VERR_INVALID_PARAMETER if the address is invalid valid.
 444  */
 445 struct vmmdev_hgcm_cancel2 {
 446         /** Header. */
 447         struct vmmdev_request_header header;
 448         /** The physical address of the request to cancel. */
 449         u32 phys_req_to_cancel;
 450 };
 451 VMMDEV_ASSERT_SIZE(vmmdev_hgcm_cancel2, 24 + 4);
 452
 453 #endif