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