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