drivers/staging/vboxvideo/vboxvideo.h

   1 /*
   2  * Copyright (C) 2006-2016 Oracle Corporation
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a
   5  * copy of this software and associated documentation files (the
   6  * "Software"), to deal in the Software without restriction, including
   7  * without limitation the rights to use, copy, modify, merge, publish,
   8  * distribute, sub license, and/or sell copies of the Software, and to
   9  * permit persons to whom the Software is furnished to do so, subject to
  10  * the following conditions:
  11  *
  12  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  13  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  14  * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
  15  * THE COPYRIGHT HOLDERS, AUTHORS AND/OR ITS SUPPLIERS BE LIABLE FOR ANY CLAIM,
  16  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  17  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
  18  * USE OR OTHER DEALINGS IN THE SOFTWARE.
  19  *
  20  * The above copyright notice and this permission notice shall be included in
  21  * all copies or substantial portions of the Software.
  22  */
  23
  24 #ifndef __VBOXVIDEO_H__
  25 #define __VBOXVIDEO_H__
  26
  27 /*
  28  * This should be in sync with monitorCount <xsd:maxInclusive value="64"/> in
  29  * src/VBox/Main/xml/VirtualBox-settings-common.xsd
  30  */
  31 #define VBOX_VIDEO_MAX_SCREENS 64
  32
  33 /*
  34  * The last 4096 bytes of the guest VRAM contains the generic info for all
  35  * DualView chunks: sizes and offsets of chunks. This is filled by miniport.
  36  *
  37  * Last 4096 bytes of each chunk contain chunk specific data: framebuffer info,
  38  * etc. This is used exclusively by the corresponding instance of a display
  39  * driver.
  40  *
  41  * The VRAM layout:
  42  *   Last 4096 bytes - Adapter information area.
  43  *   4096 bytes aligned miniport heap (value specified in the config rouded up).
  44  *   Slack - what left after dividing the VRAM.
  45  *   4096 bytes aligned framebuffers:
  46  *     last 4096 bytes of each framebuffer is the display information area.
  47  *
  48  * The Virtual Graphics Adapter information in the guest VRAM is stored by the
  49  * guest video driver using structures prepended by VBOXVIDEOINFOHDR.
  50  *
  51  * When the guest driver writes dword 0 to the VBE_DISPI_INDEX_VBOX_VIDEO
  52  * the host starts to process the info. The first element at the start of
  53  * the 4096 bytes region should be normally be a LINK that points to
  54  * actual information chain. That way the guest driver can have some
  55  * fixed layout of the information memory block and just rewrite
  56  * the link to point to relevant memory chain.
  57  *
  58  * The processing stops at the END element.
  59  *
  60  * The host can access the memory only when the port IO is processed.
  61  * All data that will be needed later must be copied from these 4096 bytes.
  62  * But other VRAM can be used by host until the mode is disabled.
  63  *
  64  * The guest driver writes dword 0xffffffff to the VBE_DISPI_INDEX_VBOX_VIDEO
  65  * to disable the mode.
  66  *
  67  * VBE_DISPI_INDEX_VBOX_VIDEO is used to read the configuration information
  68  * from the host and issue commands to the host.
  69  *
  70  * The guest writes the VBE_DISPI_INDEX_VBOX_VIDEO index register, the the
  71  * following operations with the VBE data register can be performed:
  72  *
  73  * Operation            Result
  74  * write 16 bit value   NOP
  75  * read 16 bit value    count of monitors
  76  * write 32 bit value   set the vbox cmd value and the cmd processed by the host
  77  * read 32 bit value    result of the last vbox command is returned
  78  */
  79
  80 /**
  81  * VBVA command header.
  82  *
  83  * @todo Where does this fit in?
  84  */
  85 struct vbva_cmd_hdr {
  86    /** Coordinates of affected rectangle. */
  87         s16 x;
  88         s16 y;
  89         u16 w;
  90         u16 h;
  91 } __packed;
  92
  93 /** @name VBVA ring defines.
  94  *
  95  * The VBVA ring buffer is suitable for transferring large (< 2GB) amount of
  96  * data. For example big bitmaps which do not fit to the buffer.
  97  *
  98  * Guest starts writing to the buffer by initializing a record entry in the
  99  * records queue. VBVA_F_RECORD_PARTIAL indicates that the record is being
 100  * written. As data is written to the ring buffer, the guest increases
 101  * free_offset.
 102  *
 103  * The host reads the records on flushes and processes all completed records.
 104  * When host encounters situation when only a partial record presents and
 105  * len_and_flags & ~VBVA_F_RECORD_PARTIAL >= VBVA_RING_BUFFER_SIZE -
 106  * VBVA_RING_BUFFER_THRESHOLD, the host fetched all record data and updates
 107  * data_offset. After that on each flush the host continues fetching the data
 108  * until the record is completed.
 109  *
 110  */
 111 #define VBVA_RING_BUFFER_SIZE        (4194304 - 1024)
 112 #define VBVA_RING_BUFFER_THRESHOLD   (4096)
 113
 114 #define VBVA_MAX_RECORDS (64)
 115
 116 #define VBVA_F_MODE_ENABLED         0x00000001u
 117 #define VBVA_F_MODE_VRDP            0x00000002u
 118 #define VBVA_F_MODE_VRDP_RESET      0x00000004u
 119 #define VBVA_F_MODE_VRDP_ORDER_MASK 0x00000008u
 120
 121 #define VBVA_F_STATE_PROCESSING     0x00010000u
 122
 123 #define VBVA_F_RECORD_PARTIAL       0x80000000u
 124
 125 /**
 126  * VBVA record.
 127  */
 128 struct vbva_record {
 129         /** The length of the record. Changed by guest. */
 130         u32 len_and_flags;
 131 } __packed;
 132
 133 /*
 134  * The minimum HGSMI heap size is PAGE_SIZE (4096 bytes) and is a restriction of
 135  * the runtime heapsimple API. Use minimum 2 pages here, because the info area
 136  * also may contain other data (for example hgsmi_host_flags structure).
 137  */
 138 #define VBVA_ADAPTER_INFORMATION_SIZE 65536
 139 #define VBVA_MIN_BUFFER_SIZE          65536
 140
 141 /* The value for port IO to let the adapter to interpret the adapter memory. */
 142 #define VBOX_VIDEO_DISABLE_ADAPTER_MEMORY        0xFFFFFFFF
 143
 144 /* The value for port IO to let the adapter to interpret the adapter memory. */
 145 #define VBOX_VIDEO_INTERPRET_ADAPTER_MEMORY      0x00000000
 146
 147 /* The value for port IO to let the adapter to interpret the display memory.
 148  * The display number is encoded in low 16 bits.
 149  */
 150 #define VBOX_VIDEO_INTERPRET_DISPLAY_MEMORY_BASE 0x00010000
 151
 152 struct vbva_host_flags {
 153         u32 host_events;
 154         u32 supported_orders;
 155 } __packed;
 156
 157 struct vbva_buffer {
 158         struct vbva_host_flags host_flags;
 159
 160         /* The offset where the data start in the buffer. */
 161         u32 data_offset;
 162         /* The offset where next data must be placed in the buffer. */
 163         u32 free_offset;
 164
 165         /* The queue of record descriptions. */
 166         struct vbva_record records[VBVA_MAX_RECORDS];
 167         u32 record_first_index;
 168         u32 record_free_index;
 169
 170         /* Space to leave free when large partial records are transferred. */
 171         u32 partial_write_tresh;
 172
 173         u32 data_len;
 174         /* variable size for the rest of the vbva_buffer area in VRAM. */
 175         u8 data[0];
 176 } __packed;
 177
 178 #define VBVA_MAX_RECORD_SIZE (128 * 1024 * 1024)
 179
 180 /* guest->host commands */
 181 #define VBVA_QUERY_CONF32                        1
 182 #define VBVA_SET_CONF32                          2
 183 #define VBVA_INFO_VIEW                           3
 184 #define VBVA_INFO_HEAP                           4
 185 #define VBVA_FLUSH                               5
 186 #define VBVA_INFO_SCREEN                         6
 187 #define VBVA_ENABLE                              7
 188 #define VBVA_MOUSE_POINTER_SHAPE                 8
 189 /* informs host about HGSMI caps. see vbva_caps below */
 190 #define VBVA_INFO_CAPS                          12
 191 /* configures scanline, see VBVASCANLINECFG below */
 192 #define VBVA_SCANLINE_CFG                       13
 193 /* requests scanline info, see VBVASCANLINEINFO below */
 194 #define VBVA_SCANLINE_INFO                      14
 195 /* inform host about VBVA Command submission */
 196 #define VBVA_CMDVBVA_SUBMIT                     16
 197 /* inform host about VBVA Command submission */
 198 #define VBVA_CMDVBVA_FLUSH                      17
 199 /* G->H DMA command */
 200 #define VBVA_CMDVBVA_CTL                        18
 201 /* Query most recent mode hints sent */
 202 #define VBVA_QUERY_MODE_HINTS                   19
 203 /**
 204  * Report the guest virtual desktop position and size for mapping host and
 205  * guest pointer positions.
 206  */
 207 #define VBVA_REPORT_INPUT_MAPPING               20
 208 /** Report the guest cursor position and query the host position. */
 209 #define VBVA_CURSOR_POSITION                    21
 210
 211 /* host->guest commands */
 212 #define VBVAHG_EVENT                            1
 213 #define VBVAHG_DISPLAY_CUSTOM                   2
 214
 215 /* vbva_conf32::index */
 216 #define VBOX_VBVA_CONF32_MONITOR_COUNT          0
 217 #define VBOX_VBVA_CONF32_HOST_HEAP_SIZE         1
 218 /**
 219  * Returns VINF_SUCCESS if the host can report mode hints via VBVA.
 220  * Set value to VERR_NOT_SUPPORTED before calling.
 221  */
 222 #define VBOX_VBVA_CONF32_MODE_HINT_REPORTING    2
 223 /**
 224  * Returns VINF_SUCCESS if the host can report guest cursor enabled status via
 225  * VBVA.  Set value to VERR_NOT_SUPPORTED before calling.
 226  */
 227 #define VBOX_VBVA_CONF32_GUEST_CURSOR_REPORTING 3
 228 /**
 229  * Returns the currently available host cursor capabilities.  Available if
 230  * vbva_conf32::VBOX_VBVA_CONF32_GUEST_CURSOR_REPORTING returns success.
 231  * @see VMMDevReqMouseStatus::mouseFeatures.
 232  */
 233 #define VBOX_VBVA_CONF32_CURSOR_CAPABILITIES    4
 234 /** Returns the supported flags in vbva_infoscreen::flags. */
 235 #define VBOX_VBVA_CONF32_SCREEN_FLAGS           5
 236 /** Returns the max size of VBVA record. */
 237 #define VBOX_VBVA_CONF32_MAX_RECORD_SIZE        6
 238
 239 struct vbva_conf32 {
 240         u32 index;
 241         u32 value;
 242 } __packed;
 243
 244 /** Reserved for historical reasons. */
 245 #define VBOX_VBVA_CURSOR_CAPABILITY_RESERVED0   BIT(0)
 246 /**
 247  * Guest cursor capability: can the host show a hardware cursor at the host
 248  * pointer location?
 249  */
 250 #define VBOX_VBVA_CURSOR_CAPABILITY_HARDWARE    BIT(1)
 251 /** Reserved for historical reasons. */
 252 #define VBOX_VBVA_CURSOR_CAPABILITY_RESERVED2   BIT(2)
 253 /** Reserved for historical reasons.  Must always be unset. */
 254 #define VBOX_VBVA_CURSOR_CAPABILITY_RESERVED3   BIT(3)
 255 /** Reserved for historical reasons. */
 256 #define VBOX_VBVA_CURSOR_CAPABILITY_RESERVED4   BIT(4)
 257 /** Reserved for historical reasons. */
 258 #define VBOX_VBVA_CURSOR_CAPABILITY_RESERVED5   BIT(5)
 259
 260 struct vbva_infoview {
 261         /* Index of the screen, assigned by the guest. */
 262         u32 view_index;
 263
 264         /* The screen offset in VRAM, the framebuffer starts here. */
 265         u32 view_offset;
 266
 267         /* The size of the VRAM memory that can be used for the view. */
 268         u32 view_size;
 269
 270         /* The recommended maximum size of the VRAM memory for the screen. */
 271         u32 max_screen_size;
 272 } __packed;
 273
 274 struct vbva_flush {
 275         u32 reserved;
 276 } __packed;
 277
 278 /* vbva_infoscreen::flags */
 279 #define VBVA_SCREEN_F_NONE                      0x0000
 280 #define VBVA_SCREEN_F_ACTIVE                    0x0001
 281 /**
 282  * The virtual monitor has been disabled by the guest and should be removed
 283  * by the host and ignored for purposes of pointer position calculation.
 284  */
 285 #define VBVA_SCREEN_F_DISABLED                  0x0002
 286 /**
 287  * The virtual monitor has been blanked by the guest and should be blacked
 288  * out by the host using width, height, etc values from the vbva_infoscreen
 289  * request.
 290  */
 291 #define VBVA_SCREEN_F_BLANK                     0x0004
 292 /**
 293  * The virtual monitor has been blanked by the guest and should be blacked
 294  * out by the host using the previous mode values for width. height, etc.
 295  */
 296 #define VBVA_SCREEN_F_BLANK2                    0x0008
 297
 298 struct vbva_infoscreen {
 299         /* Which view contains the screen. */
 300         u32 view_index;
 301
 302         /* Physical X origin relative to the primary screen. */
 303         s32 origin_x;
 304
 305         /* Physical Y origin relative to the primary screen. */
 306         s32 origin_y;
 307
 308         /* Offset of visible framebuffer relative to the framebuffer start. */
 309         u32 start_offset;
 310
 311         /* The scan line size in bytes. */
 312         u32 line_size;
 313
 314         /* Width of the screen. */
 315         u32 width;
 316
 317         /* Height of the screen. */
 318         u32 height;
 319
 320         /* Color depth. */
 321         u16 bits_per_pixel;
 322
 323         /* VBVA_SCREEN_F_* */
 324         u16 flags;
 325 } __packed;
 326
 327 /* vbva_enable::flags */
 328 #define VBVA_F_NONE                             0x00000000
 329 #define VBVA_F_ENABLE                           0x00000001
 330 #define VBVA_F_DISABLE                          0x00000002
 331 /* extended VBVA to be used with WDDM */
 332 #define VBVA_F_EXTENDED                         0x00000004
 333 /* vbva offset is absolute VRAM offset */
 334 #define VBVA_F_ABSOFFSET                        0x00000008
 335
 336 struct vbva_enable {
 337         u32 flags;
 338         u32 offset;
 339         s32 result;
 340 } __packed;
 341
 342 struct vbva_enable_ex {
 343         struct vbva_enable base;
 344         u32 screen_id;
 345 } __packed;
 346
 347 struct vbva_mouse_pointer_shape {
 348         /* The host result. */
 349         s32 result;
 350
 351         /* VBOX_MOUSE_POINTER_* bit flags. */
 352         u32 flags;
 353
 354         /* X coordinate of the hot spot. */
 355         u32 hot_X;
 356
 357         /* Y coordinate of the hot spot. */
 358         u32 hot_y;
 359
 360         /* Width of the pointer in pixels. */
 361         u32 width;
 362
 363         /* Height of the pointer in scanlines. */
 364         u32 height;
 365
 366         /* Pointer data.
 367          *
 368          ****
 369          * The data consists of 1 bpp AND mask followed by 32 bpp XOR (color)
 370          * mask.
 371          *
 372          * For pointers without alpha channel the XOR mask pixels are 32 bit
 373          * values: (lsb)BGR0(msb). For pointers with alpha channel the XOR mask
 374          * consists of (lsb)BGRA(msb) 32 bit values.
 375          *
 376          * Guest driver must create the AND mask for pointers with alpha chan.,
 377          * so if host does not support alpha, the pointer could be displayed as
 378          * a normal color pointer. The AND mask can be constructed from alpha
 379          * values. For example alpha value >= 0xf0 means bit 0 in the AND mask.
 380          *
 381          * The AND mask is 1 bpp bitmap with byte aligned scanlines. Size of AND
 382          * mask, therefore, is and_len = (width + 7) / 8 * height. The padding
 383          * bits at the end of any scanline are undefined.
 384          *
 385          * The XOR mask follows the AND mask on the next 4 bytes aligned offset:
 386          * u8 *xor = and + (and_len + 3) & ~3
 387          * Bytes in the gap between the AND and the XOR mask are undefined.
 388          * XOR mask scanlines have no gap between them and size of XOR mask is:
 389          * xor_len = width * 4 * height.
 390          ****
 391          *
 392          * Preallocate 4 bytes for accessing actual data as p->data.
 393          */
 394         u8 data[4];
 395 } __packed;
 396
 397 /**
 398  * @name vbva_mouse_pointer_shape::flags
 399  * @note The VBOX_MOUSE_POINTER_* flags are used in the guest video driver,
 400  *       values must be <= 0x8000 and must not be changed. (try make more sense
 401  *       of this, please).
 402  * @{
 403  */
 404
 405 /** pointer is visible */
 406 #define VBOX_MOUSE_POINTER_VISIBLE              0x0001
 407 /** pointer has alpha channel */
 408 #define VBOX_MOUSE_POINTER_ALPHA                0x0002
 409 /** pointerData contains new pointer shape */
 410 #define VBOX_MOUSE_POINTER_SHAPE                0x0004
 411
 412 /** @} */
 413
 414 /*
 415  * The guest driver can handle asynch guest cmd completion by reading the
 416  * command offset from io port.
 417  */
 418 #define VBVACAPS_COMPLETEGCMD_BY_IOREAD         0x00000001
 419 /* the guest driver can handle video adapter IRQs */
 420 #define VBVACAPS_IRQ                            0x00000002
 421 /** The guest can read video mode hints sent via VBVA. */
 422 #define VBVACAPS_VIDEO_MODE_HINTS               0x00000004
 423 /** The guest can switch to a software cursor on demand. */
 424 #define VBVACAPS_DISABLE_CURSOR_INTEGRATION     0x00000008
 425 /** The guest does not depend on host handling the VBE registers. */
 426 #define VBVACAPS_USE_VBVA_ONLY                  0x00000010
 427
 428 struct vbva_caps {
 429         s32 rc;
 430         u32 caps;
 431 } __packed;
 432
 433 /** Query the most recent mode hints received from the host. */
 434 struct vbva_query_mode_hints {
 435         /** The maximum number of screens to return hints for. */
 436         u16 hints_queried_count;
 437         /** The size of the mode hint structures directly following this one. */
 438         u16 hint_structure_guest_size;
 439         /** Return code for the operation. Initialise to VERR_NOT_SUPPORTED. */
 440         s32 rc;
 441 } __packed;
 442
 443 /**
 444  * Structure in which a mode hint is returned. The guest allocates an array
 445  * of these immediately after the vbva_query_mode_hints structure.
 446  * To accommodate future extensions, the vbva_query_mode_hints structure
 447  * specifies the size of the vbva_modehint structures allocated by the guest,
 448  * and the host only fills out structure elements which fit into that size. The
 449  * host should fill any unused members (e.g. dx, dy) or structure space on the
 450  * end with ~0. The whole structure can legally be set to ~0 to skip a screen.
 451  */
 452 struct vbva_modehint {
 453         u32 magic;
 454         u32 cx;
 455         u32 cy;
 456         u32 bpp;                /* Which has never been used... */
 457         u32 display;
 458         u32 dx;                 /**< X offset into the virtual frame-buffer. */
 459         u32 dy;                 /**< Y offset into the virtual frame-buffer. */
 460         u32 enabled;            /* Not flags. Add new members for new flags. */
 461 } __packed;
 462
 463 #define VBVAMODEHINT_MAGIC 0x0801add9u
 464
 465 /**
 466  * Report the rectangle relative to which absolute pointer events should be
 467  * expressed. This information remains valid until the next VBVA resize event
 468  * for any screen, at which time it is reset to the bounding rectangle of all
 469  * virtual screens and must be re-set.
 470  * @see VBVA_REPORT_INPUT_MAPPING.
 471  */
 472 struct vbva_report_input_mapping {
 473         s32 x;  /**< Upper left X co-ordinate relative to the first screen. */
 474         s32 y;  /**< Upper left Y co-ordinate relative to the first screen. */
 475         u32 cx; /**< Rectangle width. */
 476         u32 cy; /**< Rectangle height. */
 477 } __packed;
 478
 479 /**
 480  * Report the guest cursor position and query the host one. The host may wish
 481  * to use the guest information to re-position its own cursor (though this is
 482  * currently unlikely).
 483  * @see VBVA_CURSOR_POSITION
 484  */
 485 struct vbva_cursor_position {
 486         u32 report_position;    /**< Are we reporting a position? */
 487         u32 x;                  /**< Guest cursor X position */
 488         u32 y;                  /**< Guest cursor Y position */
 489 } __packed;
 490
 491 #endif