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 492
