Loading...
1/**********************************************************
2 * Copyright 1998-2009 VMware, Inc. All rights reserved.
3 *
4 * Permission is hereby granted, free of charge, to any person
5 * obtaining a copy of this software and associated documentation
6 * files (the "Software"), to deal in the Software without
7 * restriction, including without limitation the rights to use, copy,
8 * modify, merge, publish, distribute, sublicense, and/or sell copies
9 * of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 *
24 **********************************************************/
25
26/*
27 * svga_reg.h --
28 *
29 * Virtual hardware definitions for the VMware SVGA II device.
30 */
31
32#ifndef _SVGA_REG_H_
33#define _SVGA_REG_H_
34
35/*
36 * PCI device IDs.
37 */
38#define PCI_VENDOR_ID_VMWARE 0x15AD
39#define PCI_DEVICE_ID_VMWARE_SVGA2 0x0405
40
41/*
42 * Legal values for the SVGA_REG_CURSOR_ON register in old-fashioned
43 * cursor bypass mode. This is still supported, but no new guest
44 * drivers should use it.
45 */
46#define SVGA_CURSOR_ON_HIDE 0x0 /* Must be 0 to maintain backward compatibility */
47#define SVGA_CURSOR_ON_SHOW 0x1 /* Must be 1 to maintain backward compatibility */
48#define SVGA_CURSOR_ON_REMOVE_FROM_FB 0x2 /* Remove the cursor from the framebuffer because we need to see what's under it */
49#define SVGA_CURSOR_ON_RESTORE_TO_FB 0x3 /* Put the cursor back in the framebuffer so the user can see it */
50
51/*
52 * The maximum framebuffer size that can traced for e.g. guests in VESA mode.
53 * The changeMap in the monitor is proportional to this number. Therefore, we'd
54 * like to keep it as small as possible to reduce monitor overhead (using
55 * SVGA_VRAM_MAX_SIZE for this increases the size of the shared area by over
56 * 4k!).
57 *
58 * NB: For compatibility reasons, this value must be greater than 0xff0000.
59 * See bug 335072.
60 */
61#define SVGA_FB_MAX_TRACEABLE_SIZE 0x1000000
62
63#define SVGA_MAX_PSEUDOCOLOR_DEPTH 8
64#define SVGA_MAX_PSEUDOCOLORS (1 << SVGA_MAX_PSEUDOCOLOR_DEPTH)
65#define SVGA_NUM_PALETTE_REGS (3 * SVGA_MAX_PSEUDOCOLORS)
66
67#define SVGA_MAGIC 0x900000UL
68#define SVGA_MAKE_ID(ver) (SVGA_MAGIC << 8 | (ver))
69
70/* Version 2 let the address of the frame buffer be unsigned on Win32 */
71#define SVGA_VERSION_2 2
72#define SVGA_ID_2 SVGA_MAKE_ID(SVGA_VERSION_2)
73
74/* Version 1 has new registers starting with SVGA_REG_CAPABILITIES so
75 PALETTE_BASE has moved */
76#define SVGA_VERSION_1 1
77#define SVGA_ID_1 SVGA_MAKE_ID(SVGA_VERSION_1)
78
79/* Version 0 is the initial version */
80#define SVGA_VERSION_0 0
81#define SVGA_ID_0 SVGA_MAKE_ID(SVGA_VERSION_0)
82
83/* "Invalid" value for all SVGA IDs. (Version ID, screen object ID, surface ID...) */
84#define SVGA_ID_INVALID 0xFFFFFFFF
85
86/* Port offsets, relative to BAR0 */
87#define SVGA_INDEX_PORT 0x0
88#define SVGA_VALUE_PORT 0x1
89#define SVGA_BIOS_PORT 0x2
90#define SVGA_IRQSTATUS_PORT 0x8
91
92/*
93 * Interrupt source flags for IRQSTATUS_PORT and IRQMASK.
94 *
95 * Interrupts are only supported when the
96 * SVGA_CAP_IRQMASK capability is present.
97 */
98#define SVGA_IRQFLAG_ANY_FENCE 0x1 /* Any fence was passed */
99#define SVGA_IRQFLAG_FIFO_PROGRESS 0x2 /* Made forward progress in the FIFO */
100#define SVGA_IRQFLAG_FENCE_GOAL 0x4 /* SVGA_FIFO_FENCE_GOAL reached */
101
102/*
103 * Registers
104 */
105
106enum {
107 SVGA_REG_ID = 0,
108 SVGA_REG_ENABLE = 1,
109 SVGA_REG_WIDTH = 2,
110 SVGA_REG_HEIGHT = 3,
111 SVGA_REG_MAX_WIDTH = 4,
112 SVGA_REG_MAX_HEIGHT = 5,
113 SVGA_REG_DEPTH = 6,
114 SVGA_REG_BITS_PER_PIXEL = 7, /* Current bpp in the guest */
115 SVGA_REG_PSEUDOCOLOR = 8,
116 SVGA_REG_RED_MASK = 9,
117 SVGA_REG_GREEN_MASK = 10,
118 SVGA_REG_BLUE_MASK = 11,
119 SVGA_REG_BYTES_PER_LINE = 12,
120 SVGA_REG_FB_START = 13, /* (Deprecated) */
121 SVGA_REG_FB_OFFSET = 14,
122 SVGA_REG_VRAM_SIZE = 15,
123 SVGA_REG_FB_SIZE = 16,
124
125 /* ID 0 implementation only had the above registers, then the palette */
126
127 SVGA_REG_CAPABILITIES = 17,
128 SVGA_REG_MEM_START = 18, /* (Deprecated) */
129 SVGA_REG_MEM_SIZE = 19,
130 SVGA_REG_CONFIG_DONE = 20, /* Set when memory area configured */
131 SVGA_REG_SYNC = 21, /* See "FIFO Synchronization Registers" */
132 SVGA_REG_BUSY = 22, /* See "FIFO Synchronization Registers" */
133 SVGA_REG_GUEST_ID = 23, /* Set guest OS identifier */
134 SVGA_REG_CURSOR_ID = 24, /* (Deprecated) */
135 SVGA_REG_CURSOR_X = 25, /* (Deprecated) */
136 SVGA_REG_CURSOR_Y = 26, /* (Deprecated) */
137 SVGA_REG_CURSOR_ON = 27, /* (Deprecated) */
138 SVGA_REG_HOST_BITS_PER_PIXEL = 28, /* (Deprecated) */
139 SVGA_REG_SCRATCH_SIZE = 29, /* Number of scratch registers */
140 SVGA_REG_MEM_REGS = 30, /* Number of FIFO registers */
141 SVGA_REG_NUM_DISPLAYS = 31, /* (Deprecated) */
142 SVGA_REG_PITCHLOCK = 32, /* Fixed pitch for all modes */
143 SVGA_REG_IRQMASK = 33, /* Interrupt mask */
144
145 /* Legacy multi-monitor support */
146 SVGA_REG_NUM_GUEST_DISPLAYS = 34,/* Number of guest displays in X/Y direction */
147 SVGA_REG_DISPLAY_ID = 35, /* Display ID for the following display attributes */
148 SVGA_REG_DISPLAY_IS_PRIMARY = 36,/* Whether this is a primary display */
149 SVGA_REG_DISPLAY_POSITION_X = 37,/* The display position x */
150 SVGA_REG_DISPLAY_POSITION_Y = 38,/* The display position y */
151 SVGA_REG_DISPLAY_WIDTH = 39, /* The display's width */
152 SVGA_REG_DISPLAY_HEIGHT = 40, /* The display's height */
153
154 /* See "Guest memory regions" below. */
155 SVGA_REG_GMR_ID = 41,
156 SVGA_REG_GMR_DESCRIPTOR = 42,
157 SVGA_REG_GMR_MAX_IDS = 43,
158 SVGA_REG_GMR_MAX_DESCRIPTOR_LENGTH = 44,
159
160 SVGA_REG_TRACES = 45, /* Enable trace-based updates even when FIFO is on */
161 SVGA_REG_TOP = 46, /* Must be 1 more than the last register */
162
163 SVGA_PALETTE_BASE = 1024, /* Base of SVGA color map */
164 /* Next 768 (== 256*3) registers exist for colormap */
165
166 SVGA_SCRATCH_BASE = SVGA_PALETTE_BASE + SVGA_NUM_PALETTE_REGS
167 /* Base of scratch registers */
168 /* Next reg[SVGA_REG_SCRATCH_SIZE] registers exist for scratch usage:
169 First 4 are reserved for VESA BIOS Extension; any remaining are for
170 the use of the current SVGA driver. */
171};
172
173
174/*
175 * Guest memory regions (GMRs):
176 *
177 * This is a new memory mapping feature available in SVGA devices
178 * which have the SVGA_CAP_GMR bit set. Previously, there were two
179 * fixed memory regions available with which to share data between the
180 * device and the driver: the FIFO ('MEM') and the framebuffer. GMRs
181 * are our name for an extensible way of providing arbitrary DMA
182 * buffers for use between the driver and the SVGA device. They are a
183 * new alternative to framebuffer memory, usable for both 2D and 3D
184 * graphics operations.
185 *
186 * Since GMR mapping must be done synchronously with guest CPU
187 * execution, we use a new pair of SVGA registers:
188 *
189 * SVGA_REG_GMR_ID --
190 *
191 * Read/write.
192 * This register holds the 32-bit ID (a small positive integer)
193 * of a GMR to create, delete, or redefine. Writing this register
194 * has no side-effects.
195 *
196 * SVGA_REG_GMR_DESCRIPTOR --
197 *
198 * Write-only.
199 * Writing this register will create, delete, or redefine the GMR
200 * specified by the above ID register. If this register is zero,
201 * the GMR is deleted. Any pointers into this GMR (including those
202 * currently being processed by FIFO commands) will be
203 * synchronously invalidated.
204 *
205 * If this register is nonzero, it must be the physical page
206 * number (PPN) of a data structure which describes the physical
207 * layout of the memory region this GMR should describe. The
208 * descriptor structure will be read synchronously by the SVGA
209 * device when this register is written. The descriptor need not
210 * remain allocated for the lifetime of the GMR.
211 *
212 * The guest driver should write SVGA_REG_GMR_ID first, then
213 * SVGA_REG_GMR_DESCRIPTOR.
214 *
215 * SVGA_REG_GMR_MAX_IDS --
216 *
217 * Read-only.
218 * The SVGA device may choose to support a maximum number of
219 * user-defined GMR IDs. This register holds the number of supported
220 * IDs. (The maximum supported ID plus 1)
221 *
222 * SVGA_REG_GMR_MAX_DESCRIPTOR_LENGTH --
223 *
224 * Read-only.
225 * The SVGA device may choose to put a limit on the total number
226 * of SVGAGuestMemDescriptor structures it will read when defining
227 * a single GMR.
228 *
229 * The descriptor structure is an array of SVGAGuestMemDescriptor
230 * structures. Each structure may do one of three things:
231 *
232 * - Terminate the GMR descriptor list.
233 * (ppn==0, numPages==0)
234 *
235 * - Add a PPN or range of PPNs to the GMR's virtual address space.
236 * (ppn != 0, numPages != 0)
237 *
238 * - Provide the PPN of the next SVGAGuestMemDescriptor, in order to
239 * support multi-page GMR descriptor tables without forcing the
240 * driver to allocate physically contiguous memory.
241 * (ppn != 0, numPages == 0)
242 *
243 * Note that each physical page of SVGAGuestMemDescriptor structures
244 * can describe at least 2MB of guest memory. If the driver needs to
245 * use more than one page of descriptor structures, it must use one of
246 * its SVGAGuestMemDescriptors to point to an additional page. The
247 * device will never automatically cross a page boundary.
248 *
249 * Once the driver has described a GMR, it is immediately available
250 * for use via any FIFO command that uses an SVGAGuestPtr structure.
251 * These pointers include a GMR identifier plus an offset into that
252 * GMR.
253 *
254 * The driver must check the SVGA_CAP_GMR bit before using the GMR
255 * registers.
256 */
257
258/*
259 * Special GMR IDs, allowing SVGAGuestPtrs to point to framebuffer
260 * memory as well. In the future, these IDs could even be used to
261 * allow legacy memory regions to be redefined by the guest as GMRs.
262 *
263 * Using the guest framebuffer (GFB) at BAR1 for general purpose DMA
264 * is being phased out. Please try to use user-defined GMRs whenever
265 * possible.
266 */
267#define SVGA_GMR_NULL ((uint32) -1)
268#define SVGA_GMR_FRAMEBUFFER ((uint32) -2) // Guest Framebuffer (GFB)
269
270typedef
271struct SVGAGuestMemDescriptor {
272 uint32 ppn;
273 uint32 numPages;
274} SVGAGuestMemDescriptor;
275
276typedef
277struct SVGAGuestPtr {
278 uint32 gmrId;
279 uint32 offset;
280} SVGAGuestPtr;
281
282
283/*
284 * SVGAGMRImageFormat --
285 *
286 * This is a packed representation of the source 2D image format
287 * for a GMR-to-screen blit. Currently it is defined as an encoding
288 * of the screen's color depth and bits-per-pixel, however, 16 bits
289 * are reserved for future use to identify other encodings (such as
290 * RGBA or higher-precision images).
291 *
292 * Currently supported formats:
293 *
294 * bpp depth Format Name
295 * --- ----- -----------
296 * 32 24 32-bit BGRX
297 * 24 24 24-bit BGR
298 * 16 16 RGB 5-6-5
299 * 16 15 RGB 5-5-5
300 *
301 */
302
303typedef
304struct SVGAGMRImageFormat {
305 union {
306 struct {
307 uint32 bitsPerPixel : 8;
308 uint32 colorDepth : 8;
309 uint32 reserved : 16; // Must be zero
310 };
311
312 uint32 value;
313 };
314} SVGAGMRImageFormat;
315
316/*
317 * SVGAColorBGRX --
318 *
319 * A 24-bit color format (BGRX), which does not depend on the
320 * format of the legacy guest framebuffer (GFB) or the current
321 * GMRFB state.
322 */
323
324typedef
325struct SVGAColorBGRX {
326 union {
327 struct {
328 uint32 b : 8;
329 uint32 g : 8;
330 uint32 r : 8;
331 uint32 x : 8; // Unused
332 };
333
334 uint32 value;
335 };
336} SVGAColorBGRX;
337
338
339/*
340 * SVGASignedRect --
341 * SVGASignedPoint --
342 *
343 * Signed rectangle and point primitives. These are used by the new
344 * 2D primitives for drawing to Screen Objects, which can occupy a
345 * signed virtual coordinate space.
346 *
347 * SVGASignedRect specifies a half-open interval: the (left, top)
348 * pixel is part of the rectangle, but the (right, bottom) pixel is
349 * not.
350 */
351
352typedef
353struct SVGASignedRect {
354 int32 left;
355 int32 top;
356 int32 right;
357 int32 bottom;
358} SVGASignedRect;
359
360typedef
361struct SVGASignedPoint {
362 int32 x;
363 int32 y;
364} SVGASignedPoint;
365
366
367/*
368 * Capabilities
369 *
370 * Note the holes in the bitfield. Missing bits have been deprecated,
371 * and must not be reused. Those capabilities will never be reported
372 * by new versions of the SVGA device.
373 */
374
375#define SVGA_CAP_NONE 0x00000000
376#define SVGA_CAP_RECT_COPY 0x00000002
377#define SVGA_CAP_CURSOR 0x00000020
378#define SVGA_CAP_CURSOR_BYPASS 0x00000040 // Legacy (Use Cursor Bypass 3 instead)
379#define SVGA_CAP_CURSOR_BYPASS_2 0x00000080 // Legacy (Use Cursor Bypass 3 instead)
380#define SVGA_CAP_8BIT_EMULATION 0x00000100
381#define SVGA_CAP_ALPHA_CURSOR 0x00000200
382#define SVGA_CAP_3D 0x00004000
383#define SVGA_CAP_EXTENDED_FIFO 0x00008000
384#define SVGA_CAP_MULTIMON 0x00010000 // Legacy multi-monitor support
385#define SVGA_CAP_PITCHLOCK 0x00020000
386#define SVGA_CAP_IRQMASK 0x00040000
387#define SVGA_CAP_DISPLAY_TOPOLOGY 0x00080000 // Legacy multi-monitor support
388#define SVGA_CAP_GMR 0x00100000
389#define SVGA_CAP_TRACES 0x00200000
390
391
392/*
393 * FIFO register indices.
394 *
395 * The FIFO is a chunk of device memory mapped into guest physmem. It
396 * is always treated as 32-bit words.
397 *
398 * The guest driver gets to decide how to partition it between
399 * - FIFO registers (there are always at least 4, specifying where the
400 * following data area is and how much data it contains; there may be
401 * more registers following these, depending on the FIFO protocol
402 * version in use)
403 * - FIFO data, written by the guest and slurped out by the VMX.
404 * These indices are 32-bit word offsets into the FIFO.
405 */
406
407enum {
408 /*
409 * Block 1 (basic registers): The originally defined FIFO registers.
410 * These exist and are valid for all versions of the FIFO protocol.
411 */
412
413 SVGA_FIFO_MIN = 0,
414 SVGA_FIFO_MAX, /* The distance from MIN to MAX must be at least 10K */
415 SVGA_FIFO_NEXT_CMD,
416 SVGA_FIFO_STOP,
417
418 /*
419 * Block 2 (extended registers): Mandatory registers for the extended
420 * FIFO. These exist if the SVGA caps register includes
421 * SVGA_CAP_EXTENDED_FIFO; some of them are valid only if their
422 * associated capability bit is enabled.
423 *
424 * Note that when originally defined, SVGA_CAP_EXTENDED_FIFO implied
425 * support only for (FIFO registers) CAPABILITIES, FLAGS, and FENCE.
426 * This means that the guest has to test individually (in most cases
427 * using FIFO caps) for the presence of registers after this; the VMX
428 * can define "extended FIFO" to mean whatever it wants, and currently
429 * won't enable it unless there's room for that set and much more.
430 */
431
432 SVGA_FIFO_CAPABILITIES = 4,
433 SVGA_FIFO_FLAGS,
434 // Valid with SVGA_FIFO_CAP_FENCE:
435 SVGA_FIFO_FENCE,
436
437 /*
438 * Block 3a (optional extended registers): Additional registers for the
439 * extended FIFO, whose presence isn't actually implied by
440 * SVGA_CAP_EXTENDED_FIFO; these exist if SVGA_FIFO_MIN is high enough to
441 * leave room for them.
442 *
443 * These in block 3a, the VMX currently considers mandatory for the
444 * extended FIFO.
445 */
446
447 // Valid if exists (i.e. if extended FIFO enabled):
448 SVGA_FIFO_3D_HWVERSION, /* See SVGA3dHardwareVersion in svga3d_reg.h */
449 // Valid with SVGA_FIFO_CAP_PITCHLOCK:
450 SVGA_FIFO_PITCHLOCK,
451
452 // Valid with SVGA_FIFO_CAP_CURSOR_BYPASS_3:
453 SVGA_FIFO_CURSOR_ON, /* Cursor bypass 3 show/hide register */
454 SVGA_FIFO_CURSOR_X, /* Cursor bypass 3 x register */
455 SVGA_FIFO_CURSOR_Y, /* Cursor bypass 3 y register */
456 SVGA_FIFO_CURSOR_COUNT, /* Incremented when any of the other 3 change */
457 SVGA_FIFO_CURSOR_LAST_UPDATED,/* Last time the host updated the cursor */
458
459 // Valid with SVGA_FIFO_CAP_RESERVE:
460 SVGA_FIFO_RESERVED, /* Bytes past NEXT_CMD with real contents */
461
462 /*
463 * Valid with SVGA_FIFO_CAP_SCREEN_OBJECT:
464 *
465 * By default this is SVGA_ID_INVALID, to indicate that the cursor
466 * coordinates are specified relative to the virtual root. If this
467 * is set to a specific screen ID, cursor position is reinterpreted
468 * as a signed offset relative to that screen's origin. This is the
469 * only way to place the cursor on a non-rooted screen.
470 */
471 SVGA_FIFO_CURSOR_SCREEN_ID,
472
473 /*
474 * XXX: The gap here, up until SVGA_FIFO_3D_CAPS, can be used for new
475 * registers, but this must be done carefully and with judicious use of
476 * capability bits, since comparisons based on SVGA_FIFO_MIN aren't
477 * enough to tell you whether the register exists: we've shipped drivers
478 * and products that used SVGA_FIFO_3D_CAPS but didn't know about some of
479 * the earlier ones. The actual order of introduction was:
480 * - PITCHLOCK
481 * - 3D_CAPS
482 * - CURSOR_* (cursor bypass 3)
483 * - RESERVED
484 * So, code that wants to know whether it can use any of the
485 * aforementioned registers, or anything else added after PITCHLOCK and
486 * before 3D_CAPS, needs to reason about something other than
487 * SVGA_FIFO_MIN.
488 */
489
490 /*
491 * 3D caps block space; valid with 3D hardware version >=
492 * SVGA3D_HWVERSION_WS6_B1.
493 */
494 SVGA_FIFO_3D_CAPS = 32,
495 SVGA_FIFO_3D_CAPS_LAST = 32 + 255,
496
497 /*
498 * End of VMX's current definition of "extended-FIFO registers".
499 * Registers before here are always enabled/disabled as a block; either
500 * the extended FIFO is enabled and includes all preceding registers, or
501 * it's disabled entirely.
502 *
503 * Block 3b (truly optional extended registers): Additional registers for
504 * the extended FIFO, which the VMX already knows how to enable and
505 * disable with correct granularity.
506 *
507 * Registers after here exist if and only if the guest SVGA driver
508 * sets SVGA_FIFO_MIN high enough to leave room for them.
509 */
510
511 // Valid if register exists:
512 SVGA_FIFO_GUEST_3D_HWVERSION, /* Guest driver's 3D version */
513 SVGA_FIFO_FENCE_GOAL, /* Matching target for SVGA_IRQFLAG_FENCE_GOAL */
514 SVGA_FIFO_BUSY, /* See "FIFO Synchronization Registers" */
515
516 /*
517 * Always keep this last. This defines the maximum number of
518 * registers we know about. At power-on, this value is placed in
519 * the SVGA_REG_MEM_REGS register, and we expect the guest driver
520 * to allocate this much space in FIFO memory for registers.
521 */
522 SVGA_FIFO_NUM_REGS
523};
524
525
526/*
527 * Definition of registers included in extended FIFO support.
528 *
529 * The guest SVGA driver gets to allocate the FIFO between registers
530 * and data. It must always allocate at least 4 registers, but old
531 * drivers stopped there.
532 *
533 * The VMX will enable extended FIFO support if and only if the guest
534 * left enough room for all registers defined as part of the mandatory
535 * set for the extended FIFO.
536 *
537 * Note that the guest drivers typically allocate the FIFO only at
538 * initialization time, not at mode switches, so it's likely that the
539 * number of FIFO registers won't change without a reboot.
540 *
541 * All registers less than this value are guaranteed to be present if
542 * svgaUser->fifo.extended is set. Any later registers must be tested
543 * individually for compatibility at each use (in the VMX).
544 *
545 * This value is used only by the VMX, so it can change without
546 * affecting driver compatibility; keep it that way?
547 */
548#define SVGA_FIFO_EXTENDED_MANDATORY_REGS (SVGA_FIFO_3D_CAPS_LAST + 1)
549
550
551/*
552 * FIFO Synchronization Registers
553 *
554 * This explains the relationship between the various FIFO
555 * sync-related registers in IOSpace and in FIFO space.
556 *
557 * SVGA_REG_SYNC --
558 *
559 * The SYNC register can be used in two different ways by the guest:
560 *
561 * 1. If the guest wishes to fully sync (drain) the FIFO,
562 * it will write once to SYNC then poll on the BUSY
563 * register. The FIFO is sync'ed once BUSY is zero.
564 *
565 * 2. If the guest wants to asynchronously wake up the host,
566 * it will write once to SYNC without polling on BUSY.
567 * Ideally it will do this after some new commands have
568 * been placed in the FIFO, and after reading a zero
569 * from SVGA_FIFO_BUSY.
570 *
571 * (1) is the original behaviour that SYNC was designed to
572 * support. Originally, a write to SYNC would implicitly
573 * trigger a read from BUSY. This causes us to synchronously
574 * process the FIFO.
575 *
576 * This behaviour has since been changed so that writing SYNC
577 * will *not* implicitly cause a read from BUSY. Instead, it
578 * makes a channel call which asynchronously wakes up the MKS
579 * thread.
580 *
581 * New guests can use this new behaviour to implement (2)
582 * efficiently. This lets guests get the host's attention
583 * without waiting for the MKS to poll, which gives us much
584 * better CPU utilization on SMP hosts and on UP hosts while
585 * we're blocked on the host GPU.
586 *
587 * Old guests shouldn't notice the behaviour change. SYNC was
588 * never guaranteed to process the entire FIFO, since it was
589 * bounded to a particular number of CPU cycles. Old guests will
590 * still loop on the BUSY register until the FIFO is empty.
591 *
592 * Writing to SYNC currently has the following side-effects:
593 *
594 * - Sets SVGA_REG_BUSY to TRUE (in the monitor)
595 * - Asynchronously wakes up the MKS thread for FIFO processing
596 * - The value written to SYNC is recorded as a "reason", for
597 * stats purposes.
598 *
599 * If SVGA_FIFO_BUSY is available, drivers are advised to only
600 * write to SYNC if SVGA_FIFO_BUSY is FALSE. Drivers should set
601 * SVGA_FIFO_BUSY to TRUE after writing to SYNC. The MKS will
602 * eventually set SVGA_FIFO_BUSY on its own, but this approach
603 * lets the driver avoid sending multiple asynchronous wakeup
604 * messages to the MKS thread.
605 *
606 * SVGA_REG_BUSY --
607 *
608 * This register is set to TRUE when SVGA_REG_SYNC is written,
609 * and it reads as FALSE when the FIFO has been completely
610 * drained.
611 *
612 * Every read from this register causes us to synchronously
613 * process FIFO commands. There is no guarantee as to how many
614 * commands each read will process.
615 *
616 * CPU time spent processing FIFO commands will be billed to
617 * the guest.
618 *
619 * New drivers should avoid using this register unless they
620 * need to guarantee that the FIFO is completely drained. It
621 * is overkill for performing a sync-to-fence. Older drivers
622 * will use this register for any type of synchronization.
623 *
624 * SVGA_FIFO_BUSY --
625 *
626 * This register is a fast way for the guest driver to check
627 * whether the FIFO is already being processed. It reads and
628 * writes at normal RAM speeds, with no monitor intervention.
629 *
630 * If this register reads as TRUE, the host is guaranteeing that
631 * any new commands written into the FIFO will be noticed before
632 * the MKS goes back to sleep.
633 *
634 * If this register reads as FALSE, no such guarantee can be
635 * made.
636 *
637 * The guest should use this register to quickly determine
638 * whether or not it needs to wake up the host. If the guest
639 * just wrote a command or group of commands that it would like
640 * the host to begin processing, it should:
641 *
642 * 1. Read SVGA_FIFO_BUSY. If it reads as TRUE, no further
643 * action is necessary.
644 *
645 * 2. Write TRUE to SVGA_FIFO_BUSY. This informs future guest
646 * code that we've already sent a SYNC to the host and we
647 * don't need to send a duplicate.
648 *
649 * 3. Write a reason to SVGA_REG_SYNC. This will send an
650 * asynchronous wakeup to the MKS thread.
651 */
652
653
654/*
655 * FIFO Capabilities
656 *
657 * Fence -- Fence register and command are supported
658 * Accel Front -- Front buffer only commands are supported
659 * Pitch Lock -- Pitch lock register is supported
660 * Video -- SVGA Video overlay units are supported
661 * Escape -- Escape command is supported
662 *
663 * XXX: Add longer descriptions for each capability, including a list
664 * of the new features that each capability provides.
665 *
666 * SVGA_FIFO_CAP_SCREEN_OBJECT --
667 *
668 * Provides dynamic multi-screen rendering, for improved Unity and
669 * multi-monitor modes. With Screen Object, the guest can
670 * dynamically create and destroy 'screens', which can represent
671 * Unity windows or virtual monitors. Screen Object also provides
672 * strong guarantees that DMA operations happen only when
673 * guest-initiated. Screen Object deprecates the BAR1 guest
674 * framebuffer (GFB) and all commands that work only with the GFB.
675 *
676 * New registers:
677 * FIFO_CURSOR_SCREEN_ID, VIDEO_DATA_GMRID, VIDEO_DST_SCREEN_ID
678 *
679 * New 2D commands:
680 * DEFINE_SCREEN, DESTROY_SCREEN, DEFINE_GMRFB, BLIT_GMRFB_TO_SCREEN,
681 * BLIT_SCREEN_TO_GMRFB, ANNOTATION_FILL, ANNOTATION_COPY
682 *
683 * New 3D commands:
684 * BLIT_SURFACE_TO_SCREEN
685 *
686 * New guarantees:
687 *
688 * - The host will not read or write guest memory, including the GFB,
689 * except when explicitly initiated by a DMA command.
690 *
691 * - All DMA, including legacy DMA like UPDATE and PRESENT_READBACK,
692 * is guaranteed to complete before any subsequent FENCEs.
693 *
694 * - All legacy commands which affect a Screen (UPDATE, PRESENT,
695 * PRESENT_READBACK) as well as new Screen blit commands will
696 * all behave consistently as blits, and memory will be read
697 * or written in FIFO order.
698 *
699 * For example, if you PRESENT from one SVGA3D surface to multiple
700 * places on the screen, the data copied will always be from the
701 * SVGA3D surface at the time the PRESENT was issued in the FIFO.
702 * This was not necessarily true on devices without Screen Object.
703 *
704 * This means that on devices that support Screen Object, the
705 * PRESENT_READBACK command should not be necessary unless you
706 * actually want to read back the results of 3D rendering into
707 * system memory. (And for that, the BLIT_SCREEN_TO_GMRFB
708 * command provides a strict superset of functionality.)
709 *
710 * - When a screen is resized, either using Screen Object commands or
711 * legacy multimon registers, its contents are preserved.
712 */
713
714#define SVGA_FIFO_CAP_NONE 0
715#define SVGA_FIFO_CAP_FENCE (1<<0)
716#define SVGA_FIFO_CAP_ACCELFRONT (1<<1)
717#define SVGA_FIFO_CAP_PITCHLOCK (1<<2)
718#define SVGA_FIFO_CAP_VIDEO (1<<3)
719#define SVGA_FIFO_CAP_CURSOR_BYPASS_3 (1<<4)
720#define SVGA_FIFO_CAP_ESCAPE (1<<5)
721#define SVGA_FIFO_CAP_RESERVE (1<<6)
722#define SVGA_FIFO_CAP_SCREEN_OBJECT (1<<7)
723
724
725/*
726 * FIFO Flags
727 *
728 * Accel Front -- Driver should use front buffer only commands
729 */
730
731#define SVGA_FIFO_FLAG_NONE 0
732#define SVGA_FIFO_FLAG_ACCELFRONT (1<<0)
733#define SVGA_FIFO_FLAG_RESERVED (1<<31) // Internal use only
734
735/*
736 * FIFO reservation sentinel value
737 */
738
739#define SVGA_FIFO_RESERVED_UNKNOWN 0xffffffff
740
741
742/*
743 * Video overlay support
744 */
745
746#define SVGA_NUM_OVERLAY_UNITS 32
747
748
749/*
750 * Video capabilities that the guest is currently using
751 */
752
753#define SVGA_VIDEO_FLAG_COLORKEY 0x0001
754
755
756/*
757 * Offsets for the video overlay registers
758 */
759
760enum {
761 SVGA_VIDEO_ENABLED = 0,
762 SVGA_VIDEO_FLAGS,
763 SVGA_VIDEO_DATA_OFFSET,
764 SVGA_VIDEO_FORMAT,
765 SVGA_VIDEO_COLORKEY,
766 SVGA_VIDEO_SIZE, // Deprecated
767 SVGA_VIDEO_WIDTH,
768 SVGA_VIDEO_HEIGHT,
769 SVGA_VIDEO_SRC_X,
770 SVGA_VIDEO_SRC_Y,
771 SVGA_VIDEO_SRC_WIDTH,
772 SVGA_VIDEO_SRC_HEIGHT,
773 SVGA_VIDEO_DST_X, // Signed int32
774 SVGA_VIDEO_DST_Y, // Signed int32
775 SVGA_VIDEO_DST_WIDTH,
776 SVGA_VIDEO_DST_HEIGHT,
777 SVGA_VIDEO_PITCH_1,
778 SVGA_VIDEO_PITCH_2,
779 SVGA_VIDEO_PITCH_3,
780 SVGA_VIDEO_DATA_GMRID, // Optional, defaults to SVGA_GMR_FRAMEBUFFER
781 SVGA_VIDEO_DST_SCREEN_ID, // Optional, defaults to virtual coords (SVGA_ID_INVALID)
782 SVGA_VIDEO_NUM_REGS
783};
784
785
786/*
787 * SVGA Overlay Units
788 *
789 * width and height relate to the entire source video frame.
790 * srcX, srcY, srcWidth and srcHeight represent subset of the source
791 * video frame to be displayed.
792 */
793
794typedef struct SVGAOverlayUnit {
795 uint32 enabled;
796 uint32 flags;
797 uint32 dataOffset;
798 uint32 format;
799 uint32 colorKey;
800 uint32 size;
801 uint32 width;
802 uint32 height;
803 uint32 srcX;
804 uint32 srcY;
805 uint32 srcWidth;
806 uint32 srcHeight;
807 int32 dstX;
808 int32 dstY;
809 uint32 dstWidth;
810 uint32 dstHeight;
811 uint32 pitches[3];
812 uint32 dataGMRId;
813 uint32 dstScreenId;
814} SVGAOverlayUnit;
815
816
817/*
818 * SVGAScreenObject --
819 *
820 * This is a new way to represent a guest's multi-monitor screen or
821 * Unity window. Screen objects are only supported if the
822 * SVGA_FIFO_CAP_SCREEN_OBJECT capability bit is set.
823 *
824 * If Screen Objects are supported, they can be used to fully
825 * replace the functionality provided by the framebuffer registers
826 * (SVGA_REG_WIDTH, HEIGHT, etc.) and by SVGA_CAP_DISPLAY_TOPOLOGY.
827 *
828 * The screen object is a struct with guaranteed binary
829 * compatibility. New flags can be added, and the struct may grow,
830 * but existing fields must retain their meaning.
831 *
832 */
833
834#define SVGA_SCREEN_HAS_ROOT (1 << 0) // Screen is present in the virtual coord space
835#define SVGA_SCREEN_IS_PRIMARY (1 << 1) // Guest considers this screen to be 'primary'
836#define SVGA_SCREEN_FULLSCREEN_HINT (1 << 2) // Guest is running a fullscreen app here
837
838typedef
839struct SVGAScreenObject {
840 uint32 structSize; // sizeof(SVGAScreenObject)
841 uint32 id;
842 uint32 flags;
843 struct {
844 uint32 width;
845 uint32 height;
846 } size;
847 struct {
848 int32 x;
849 int32 y;
850 } root; // Only used if SVGA_SCREEN_HAS_ROOT is set.
851} SVGAScreenObject;
852
853
854/*
855 * Commands in the command FIFO:
856 *
857 * Command IDs defined below are used for the traditional 2D FIFO
858 * communication (not all commands are available for all versions of the
859 * SVGA FIFO protocol).
860 *
861 * Note the holes in the command ID numbers: These commands have been
862 * deprecated, and the old IDs must not be reused.
863 *
864 * Command IDs from 1000 to 1999 are reserved for use by the SVGA3D
865 * protocol.
866 *
867 * Each command's parameters are described by the comments and
868 * structs below.
869 */
870
871typedef enum {
872 SVGA_CMD_INVALID_CMD = 0,
873 SVGA_CMD_UPDATE = 1,
874 SVGA_CMD_RECT_COPY = 3,
875 SVGA_CMD_DEFINE_CURSOR = 19,
876 SVGA_CMD_DEFINE_ALPHA_CURSOR = 22,
877 SVGA_CMD_UPDATE_VERBOSE = 25,
878 SVGA_CMD_FRONT_ROP_FILL = 29,
879 SVGA_CMD_FENCE = 30,
880 SVGA_CMD_ESCAPE = 33,
881 SVGA_CMD_DEFINE_SCREEN = 34,
882 SVGA_CMD_DESTROY_SCREEN = 35,
883 SVGA_CMD_DEFINE_GMRFB = 36,
884 SVGA_CMD_BLIT_GMRFB_TO_SCREEN = 37,
885 SVGA_CMD_BLIT_SCREEN_TO_GMRFB = 38,
886 SVGA_CMD_ANNOTATION_FILL = 39,
887 SVGA_CMD_ANNOTATION_COPY = 40,
888 SVGA_CMD_MAX
889} SVGAFifoCmdId;
890
891#define SVGA_CMD_MAX_ARGS 64
892
893
894/*
895 * SVGA_CMD_UPDATE --
896 *
897 * This is a DMA transfer which copies from the Guest Framebuffer
898 * (GFB) at BAR1 + SVGA_REG_FB_OFFSET to any screens which
899 * intersect with the provided virtual rectangle.
900 *
901 * This command does not support using arbitrary guest memory as a
902 * data source- it only works with the pre-defined GFB memory.
903 * This command also does not support signed virtual coordinates.
904 * If you have defined screens (using SVGA_CMD_DEFINE_SCREEN) with
905 * negative root x/y coordinates, the negative portion of those
906 * screens will not be reachable by this command.
907 *
908 * This command is not necessary when using framebuffer
909 * traces. Traces are automatically enabled if the SVGA FIFO is
910 * disabled, and you may explicitly enable/disable traces using
911 * SVGA_REG_TRACES. With traces enabled, any write to the GFB will
912 * automatically act as if a subsequent SVGA_CMD_UPDATE was issued.
913 *
914 * Traces and SVGA_CMD_UPDATE are the only supported ways to render
915 * pseudocolor screen updates. The newer Screen Object commands
916 * only support true color formats.
917 *
918 * Availability:
919 * Always available.
920 */
921
922typedef
923struct {
924 uint32 x;
925 uint32 y;
926 uint32 width;
927 uint32 height;
928} SVGAFifoCmdUpdate;
929
930
931/*
932 * SVGA_CMD_RECT_COPY --
933 *
934 * Perform a rectangular DMA transfer from one area of the GFB to
935 * another, and copy the result to any screens which intersect it.
936 *
937 * Availability:
938 * SVGA_CAP_RECT_COPY
939 */
940
941typedef
942struct {
943 uint32 srcX;
944 uint32 srcY;
945 uint32 destX;
946 uint32 destY;
947 uint32 width;
948 uint32 height;
949} SVGAFifoCmdRectCopy;
950
951
952/*
953 * SVGA_CMD_DEFINE_CURSOR --
954 *
955 * Provide a new cursor image, as an AND/XOR mask.
956 *
957 * The recommended way to position the cursor overlay is by using
958 * the SVGA_FIFO_CURSOR_* registers, supported by the
959 * SVGA_FIFO_CAP_CURSOR_BYPASS_3 capability.
960 *
961 * Availability:
962 * SVGA_CAP_CURSOR
963 */
964
965typedef
966struct {
967 uint32 id; // Reserved, must be zero.
968 uint32 hotspotX;
969 uint32 hotspotY;
970 uint32 width;
971 uint32 height;
972 uint32 andMaskDepth; // Value must be 1 or equal to BITS_PER_PIXEL
973 uint32 xorMaskDepth; // Value must be 1 or equal to BITS_PER_PIXEL
974 /*
975 * Followed by scanline data for AND mask, then XOR mask.
976 * Each scanline is padded to a 32-bit boundary.
977 */
978} SVGAFifoCmdDefineCursor;
979
980
981/*
982 * SVGA_CMD_DEFINE_ALPHA_CURSOR --
983 *
984 * Provide a new cursor image, in 32-bit BGRA format.
985 *
986 * The recommended way to position the cursor overlay is by using
987 * the SVGA_FIFO_CURSOR_* registers, supported by the
988 * SVGA_FIFO_CAP_CURSOR_BYPASS_3 capability.
989 *
990 * Availability:
991 * SVGA_CAP_ALPHA_CURSOR
992 */
993
994typedef
995struct {
996 uint32 id; // Reserved, must be zero.
997 uint32 hotspotX;
998 uint32 hotspotY;
999 uint32 width;
1000 uint32 height;
1001 /* Followed by scanline data */
1002} SVGAFifoCmdDefineAlphaCursor;
1003
1004
1005/*
1006 * SVGA_CMD_UPDATE_VERBOSE --
1007 *
1008 * Just like SVGA_CMD_UPDATE, but also provide a per-rectangle
1009 * 'reason' value, an opaque cookie which is used by internal
1010 * debugging tools. Third party drivers should not use this
1011 * command.
1012 *
1013 * Availability:
1014 * SVGA_CAP_EXTENDED_FIFO
1015 */
1016
1017typedef
1018struct {
1019 uint32 x;
1020 uint32 y;
1021 uint32 width;
1022 uint32 height;
1023 uint32 reason;
1024} SVGAFifoCmdUpdateVerbose;
1025
1026
1027/*
1028 * SVGA_CMD_FRONT_ROP_FILL --
1029 *
1030 * This is a hint which tells the SVGA device that the driver has
1031 * just filled a rectangular region of the GFB with a solid
1032 * color. Instead of reading these pixels from the GFB, the device
1033 * can assume that they all equal 'color'. This is primarily used
1034 * for remote desktop protocols.
1035 *
1036 * Availability:
1037 * SVGA_FIFO_CAP_ACCELFRONT
1038 */
1039
1040#define SVGA_ROP_COPY 0x03
1041
1042typedef
1043struct {
1044 uint32 color; // In the same format as the GFB
1045 uint32 x;
1046 uint32 y;
1047 uint32 width;
1048 uint32 height;
1049 uint32 rop; // Must be SVGA_ROP_COPY
1050} SVGAFifoCmdFrontRopFill;
1051
1052
1053/*
1054 * SVGA_CMD_FENCE --
1055 *
1056 * Insert a synchronization fence. When the SVGA device reaches
1057 * this command, it will copy the 'fence' value into the
1058 * SVGA_FIFO_FENCE register. It will also compare the fence against
1059 * SVGA_FIFO_FENCE_GOAL. If the fence matches the goal and the
1060 * SVGA_IRQFLAG_FENCE_GOAL interrupt is enabled, the device will
1061 * raise this interrupt.
1062 *
1063 * Availability:
1064 * SVGA_FIFO_FENCE for this command,
1065 * SVGA_CAP_IRQMASK for SVGA_FIFO_FENCE_GOAL.
1066 */
1067
1068typedef
1069struct {
1070 uint32 fence;
1071} SVGAFifoCmdFence;
1072
1073
1074/*
1075 * SVGA_CMD_ESCAPE --
1076 *
1077 * Send an extended or vendor-specific variable length command.
1078 * This is used for video overlay, third party plugins, and
1079 * internal debugging tools. See svga_escape.h
1080 *
1081 * Availability:
1082 * SVGA_FIFO_CAP_ESCAPE
1083 */
1084
1085typedef
1086struct {
1087 uint32 nsid;
1088 uint32 size;
1089 /* followed by 'size' bytes of data */
1090} SVGAFifoCmdEscape;
1091
1092
1093/*
1094 * SVGA_CMD_DEFINE_SCREEN --
1095 *
1096 * Define or redefine an SVGAScreenObject. See the description of
1097 * SVGAScreenObject above. The video driver is responsible for
1098 * generating new screen IDs. They should be small positive
1099 * integers. The virtual device will have an implementation
1100 * specific upper limit on the number of screen IDs
1101 * supported. Drivers are responsible for recycling IDs. The first
1102 * valid ID is zero.
1103 *
1104 * - Interaction with other registers:
1105 *
1106 * For backwards compatibility, when the GFB mode registers (WIDTH,
1107 * HEIGHT, PITCHLOCK, BITS_PER_PIXEL) are modified, the SVGA device
1108 * deletes all screens other than screen #0, and redefines screen
1109 * #0 according to the specified mode. Drivers that use
1110 * SVGA_CMD_DEFINE_SCREEN should destroy or redefine screen #0.
1111 *
1112 * If you use screen objects, do not use the legacy multi-mon
1113 * registers (SVGA_REG_NUM_GUEST_DISPLAYS, SVGA_REG_DISPLAY_*).
1114 *
1115 * Availability:
1116 * SVGA_FIFO_CAP_SCREEN_OBJECT
1117 */
1118
1119typedef
1120struct {
1121 SVGAScreenObject screen; // Variable-length according to version
1122} SVGAFifoCmdDefineScreen;
1123
1124
1125/*
1126 * SVGA_CMD_DESTROY_SCREEN --
1127 *
1128 * Destroy an SVGAScreenObject. Its ID is immediately available for
1129 * re-use.
1130 *
1131 * Availability:
1132 * SVGA_FIFO_CAP_SCREEN_OBJECT
1133 */
1134
1135typedef
1136struct {
1137 uint32 screenId;
1138} SVGAFifoCmdDestroyScreen;
1139
1140
1141/*
1142 * SVGA_CMD_DEFINE_GMRFB --
1143 *
1144 * This command sets a piece of SVGA device state called the
1145 * Guest Memory Region Framebuffer, or GMRFB. The GMRFB is a
1146 * piece of light-weight state which identifies the location and
1147 * format of an image in guest memory or in BAR1. The GMRFB has
1148 * an arbitrary size, and it doesn't need to match the geometry
1149 * of the GFB or any screen object.
1150 *
1151 * The GMRFB can be redefined as often as you like. You could
1152 * always use the same GMRFB, you could redefine it before
1153 * rendering from a different guest screen, or you could even
1154 * redefine it before every blit.
1155 *
1156 * There are multiple ways to use this command. The simplest way is
1157 * to use it to move the framebuffer either to elsewhere in the GFB
1158 * (BAR1) memory region, or to a user-defined GMR. This lets a
1159 * driver use a framebuffer allocated entirely out of normal system
1160 * memory, which we encourage.
1161 *
1162 * Another way to use this command is to set up a ring buffer of
1163 * updates in GFB memory. If a driver wants to ensure that no
1164 * frames are skipped by the SVGA device, it is important that the
1165 * driver not modify the source data for a blit until the device is
1166 * done processing the command. One efficient way to accomplish
1167 * this is to use a ring of small DMA buffers. Each buffer is used
1168 * for one blit, then we move on to the next buffer in the
1169 * ring. The FENCE mechanism is used to protect each buffer from
1170 * re-use until the device is finished with that buffer's
1171 * corresponding blit.
1172 *
1173 * This command does not affect the meaning of SVGA_CMD_UPDATE.
1174 * UPDATEs always occur from the legacy GFB memory area. This
1175 * command has no support for pseudocolor GMRFBs. Currently only
1176 * true-color 15, 16, and 24-bit depths are supported. Future
1177 * devices may expose capabilities for additional framebuffer
1178 * formats.
1179 *
1180 * The default GMRFB value is undefined. Drivers must always send
1181 * this command at least once before performing any blit from the
1182 * GMRFB.
1183 *
1184 * Availability:
1185 * SVGA_FIFO_CAP_SCREEN_OBJECT
1186 */
1187
1188typedef
1189struct {
1190 SVGAGuestPtr ptr;
1191 uint32 bytesPerLine;
1192 SVGAGMRImageFormat format;
1193} SVGAFifoCmdDefineGMRFB;
1194
1195
1196/*
1197 * SVGA_CMD_BLIT_GMRFB_TO_SCREEN --
1198 *
1199 * This is a guest-to-host blit. It performs a DMA operation to
1200 * copy a rectangular region of pixels from the current GMRFB to
1201 * one or more Screen Objects.
1202 *
1203 * The destination coordinate may be specified relative to a
1204 * screen's origin (if a screen ID is specified) or relative to the
1205 * virtual coordinate system's origin (if the screen ID is
1206 * SVGA_ID_INVALID). The actual destination may span zero or more
1207 * screens, in the case of a virtual destination rect or a rect
1208 * which extends off the edge of the specified screen.
1209 *
1210 * This command writes to the screen's "base layer": the underlying
1211 * framebuffer which exists below any cursor or video overlays. No
1212 * action is necessary to explicitly hide or update any overlays
1213 * which exist on top of the updated region.
1214 *
1215 * The SVGA device is guaranteed to finish reading from the GMRFB
1216 * by the time any subsequent FENCE commands are reached.
1217 *
1218 * This command consumes an annotation. See the
1219 * SVGA_CMD_ANNOTATION_* commands for details.
1220 *
1221 * Availability:
1222 * SVGA_FIFO_CAP_SCREEN_OBJECT
1223 */
1224
1225typedef
1226struct {
1227 SVGASignedPoint srcOrigin;
1228 SVGASignedRect destRect;
1229 uint32 destScreenId;
1230} SVGAFifoCmdBlitGMRFBToScreen;
1231
1232
1233/*
1234 * SVGA_CMD_BLIT_SCREEN_TO_GMRFB --
1235 *
1236 * This is a host-to-guest blit. It performs a DMA operation to
1237 * copy a rectangular region of pixels from a single Screen Object
1238 * back to the current GMRFB.
1239 *
1240 * Usage note: This command should be used rarely. It will
1241 * typically be inefficient, but it is necessary for some types of
1242 * synchronization between 3D (GPU) and 2D (CPU) rendering into
1243 * overlapping areas of a screen.
1244 *
1245 * The source coordinate is specified relative to a screen's
1246 * origin. The provided screen ID must be valid. If any parameters
1247 * are invalid, the resulting pixel values are undefined.
1248 *
1249 * This command reads the screen's "base layer". Overlays like
1250 * video and cursor are not included, but any data which was sent
1251 * using a blit-to-screen primitive will be available, no matter
1252 * whether the data's original source was the GMRFB or the 3D
1253 * acceleration hardware.
1254 *
1255 * Note that our guest-to-host blits and host-to-guest blits aren't
1256 * symmetric in their current implementation. While the parameters
1257 * are identical, host-to-guest blits are a lot less featureful.
1258 * They do not support clipping: If the source parameters don't
1259 * fully fit within a screen, the blit fails. They must originate
1260 * from exactly one screen. Virtual coordinates are not directly
1261 * supported.
1262 *
1263 * Host-to-guest blits do support the same set of GMRFB formats
1264 * offered by guest-to-host blits.
1265 *
1266 * The SVGA device is guaranteed to finish writing to the GMRFB by
1267 * the time any subsequent FENCE commands are reached.
1268 *
1269 * Availability:
1270 * SVGA_FIFO_CAP_SCREEN_OBJECT
1271 */
1272
1273typedef
1274struct {
1275 SVGASignedPoint destOrigin;
1276 SVGASignedRect srcRect;
1277 uint32 srcScreenId;
1278} SVGAFifoCmdBlitScreenToGMRFB;
1279
1280
1281/*
1282 * SVGA_CMD_ANNOTATION_FILL --
1283 *
1284 * This is a blit annotation. This command stores a small piece of
1285 * device state which is consumed by the next blit-to-screen
1286 * command. The state is only cleared by commands which are
1287 * specifically documented as consuming an annotation. Other
1288 * commands (such as ESCAPEs for debugging) may intervene between
1289 * the annotation and its associated blit.
1290 *
1291 * This annotation is a promise about the contents of the next
1292 * blit: The video driver is guaranteeing that all pixels in that
1293 * blit will have the same value, specified here as a color in
1294 * SVGAColorBGRX format.
1295 *
1296 * The SVGA device can still render the blit correctly even if it
1297 * ignores this annotation, but the annotation may allow it to
1298 * perform the blit more efficiently, for example by ignoring the
1299 * source data and performing a fill in hardware.
1300 *
1301 * This annotation is most important for performance when the
1302 * user's display is being remoted over a network connection.
1303 *
1304 * Availability:
1305 * SVGA_FIFO_CAP_SCREEN_OBJECT
1306 */
1307
1308typedef
1309struct {
1310 SVGAColorBGRX color;
1311} SVGAFifoCmdAnnotationFill;
1312
1313
1314/*
1315 * SVGA_CMD_ANNOTATION_COPY --
1316 *
1317 * This is a blit annotation. See SVGA_CMD_ANNOTATION_FILL for more
1318 * information about annotations.
1319 *
1320 * This annotation is a promise about the contents of the next
1321 * blit: The video driver is guaranteeing that all pixels in that
1322 * blit will have the same value as those which already exist at an
1323 * identically-sized region on the same or a different screen.
1324 *
1325 * Note that the source pixels for the COPY in this annotation are
1326 * sampled before applying the anqnotation's associated blit. They
1327 * are allowed to overlap with the blit's destination pixels.
1328 *
1329 * The copy source rectangle is specified the same way as the blit
1330 * destination: it can be a rectangle which spans zero or more
1331 * screens, specified relative to either a screen or to the virtual
1332 * coordinate system's origin. If the source rectangle includes
1333 * pixels which are not from exactly one screen, the results are
1334 * undefined.
1335 *
1336 * Availability:
1337 * SVGA_FIFO_CAP_SCREEN_OBJECT
1338 */
1339
1340typedef
1341struct {
1342 SVGASignedPoint srcOrigin;
1343 uint32 srcScreenId;
1344} SVGAFifoCmdAnnotationCopy;
1345
1346#endif
1/**********************************************************
2 * Copyright 1998-2009 VMware, Inc. All rights reserved.
3 *
4 * Permission is hereby granted, free of charge, to any person
5 * obtaining a copy of this software and associated documentation
6 * files (the "Software"), to deal in the Software without
7 * restriction, including without limitation the rights to use, copy,
8 * modify, merge, publish, distribute, sublicense, and/or sell copies
9 * of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 *
24 **********************************************************/
25
26/*
27 * svga_reg.h --
28 *
29 * Virtual hardware definitions for the VMware SVGA II device.
30 */
31
32#ifndef _SVGA_REG_H_
33#define _SVGA_REG_H_
34
35/*
36 * PCI device IDs.
37 */
38#define PCI_VENDOR_ID_VMWARE 0x15AD
39#define PCI_DEVICE_ID_VMWARE_SVGA2 0x0405
40
41/*
42 * SVGA_REG_ENABLE bit definitions.
43 */
44#define SVGA_REG_ENABLE_DISABLE 0
45#define SVGA_REG_ENABLE_ENABLE 1
46#define SVGA_REG_ENABLE_HIDE 2
47#define SVGA_REG_ENABLE_ENABLE_HIDE (SVGA_REG_ENABLE_ENABLE |\
48 SVGA_REG_ENABLE_HIDE)
49
50/*
51 * Legal values for the SVGA_REG_CURSOR_ON register in old-fashioned
52 * cursor bypass mode. This is still supported, but no new guest
53 * drivers should use it.
54 */
55#define SVGA_CURSOR_ON_HIDE 0x0 /* Must be 0 to maintain backward compatibility */
56#define SVGA_CURSOR_ON_SHOW 0x1 /* Must be 1 to maintain backward compatibility */
57#define SVGA_CURSOR_ON_REMOVE_FROM_FB 0x2 /* Remove the cursor from the framebuffer because we need to see what's under it */
58#define SVGA_CURSOR_ON_RESTORE_TO_FB 0x3 /* Put the cursor back in the framebuffer so the user can see it */
59
60/*
61 * The maximum framebuffer size that can traced for e.g. guests in VESA mode.
62 * The changeMap in the monitor is proportional to this number. Therefore, we'd
63 * like to keep it as small as possible to reduce monitor overhead (using
64 * SVGA_VRAM_MAX_SIZE for this increases the size of the shared area by over
65 * 4k!).
66 *
67 * NB: For compatibility reasons, this value must be greater than 0xff0000.
68 * See bug 335072.
69 */
70#define SVGA_FB_MAX_TRACEABLE_SIZE 0x1000000
71
72#define SVGA_MAX_PSEUDOCOLOR_DEPTH 8
73#define SVGA_MAX_PSEUDOCOLORS (1 << SVGA_MAX_PSEUDOCOLOR_DEPTH)
74#define SVGA_NUM_PALETTE_REGS (3 * SVGA_MAX_PSEUDOCOLORS)
75
76#define SVGA_MAGIC 0x900000UL
77#define SVGA_MAKE_ID(ver) (SVGA_MAGIC << 8 | (ver))
78
79/* Version 2 let the address of the frame buffer be unsigned on Win32 */
80#define SVGA_VERSION_2 2
81#define SVGA_ID_2 SVGA_MAKE_ID(SVGA_VERSION_2)
82
83/* Version 1 has new registers starting with SVGA_REG_CAPABILITIES so
84 PALETTE_BASE has moved */
85#define SVGA_VERSION_1 1
86#define SVGA_ID_1 SVGA_MAKE_ID(SVGA_VERSION_1)
87
88/* Version 0 is the initial version */
89#define SVGA_VERSION_0 0
90#define SVGA_ID_0 SVGA_MAKE_ID(SVGA_VERSION_0)
91
92/* "Invalid" value for all SVGA IDs. (Version ID, screen object ID, surface ID...) */
93#define SVGA_ID_INVALID 0xFFFFFFFF
94
95/* Port offsets, relative to BAR0 */
96#define SVGA_INDEX_PORT 0x0
97#define SVGA_VALUE_PORT 0x1
98#define SVGA_BIOS_PORT 0x2
99#define SVGA_IRQSTATUS_PORT 0x8
100
101/*
102 * Interrupt source flags for IRQSTATUS_PORT and IRQMASK.
103 *
104 * Interrupts are only supported when the
105 * SVGA_CAP_IRQMASK capability is present.
106 */
107#define SVGA_IRQFLAG_ANY_FENCE 0x1 /* Any fence was passed */
108#define SVGA_IRQFLAG_FIFO_PROGRESS 0x2 /* Made forward progress in the FIFO */
109#define SVGA_IRQFLAG_FENCE_GOAL 0x4 /* SVGA_FIFO_FENCE_GOAL reached */
110
111/*
112 * Registers
113 */
114
115enum {
116 SVGA_REG_ID = 0,
117 SVGA_REG_ENABLE = 1,
118 SVGA_REG_WIDTH = 2,
119 SVGA_REG_HEIGHT = 3,
120 SVGA_REG_MAX_WIDTH = 4,
121 SVGA_REG_MAX_HEIGHT = 5,
122 SVGA_REG_DEPTH = 6,
123 SVGA_REG_BITS_PER_PIXEL = 7, /* Current bpp in the guest */
124 SVGA_REG_PSEUDOCOLOR = 8,
125 SVGA_REG_RED_MASK = 9,
126 SVGA_REG_GREEN_MASK = 10,
127 SVGA_REG_BLUE_MASK = 11,
128 SVGA_REG_BYTES_PER_LINE = 12,
129 SVGA_REG_FB_START = 13, /* (Deprecated) */
130 SVGA_REG_FB_OFFSET = 14,
131 SVGA_REG_VRAM_SIZE = 15,
132 SVGA_REG_FB_SIZE = 16,
133
134 /* ID 0 implementation only had the above registers, then the palette */
135
136 SVGA_REG_CAPABILITIES = 17,
137 SVGA_REG_MEM_START = 18, /* (Deprecated) */
138 SVGA_REG_MEM_SIZE = 19,
139 SVGA_REG_CONFIG_DONE = 20, /* Set when memory area configured */
140 SVGA_REG_SYNC = 21, /* See "FIFO Synchronization Registers" */
141 SVGA_REG_BUSY = 22, /* See "FIFO Synchronization Registers" */
142 SVGA_REG_GUEST_ID = 23, /* Set guest OS identifier */
143 SVGA_REG_CURSOR_ID = 24, /* (Deprecated) */
144 SVGA_REG_CURSOR_X = 25, /* (Deprecated) */
145 SVGA_REG_CURSOR_Y = 26, /* (Deprecated) */
146 SVGA_REG_CURSOR_ON = 27, /* (Deprecated) */
147 SVGA_REG_HOST_BITS_PER_PIXEL = 28, /* (Deprecated) */
148 SVGA_REG_SCRATCH_SIZE = 29, /* Number of scratch registers */
149 SVGA_REG_MEM_REGS = 30, /* Number of FIFO registers */
150 SVGA_REG_NUM_DISPLAYS = 31, /* (Deprecated) */
151 SVGA_REG_PITCHLOCK = 32, /* Fixed pitch for all modes */
152 SVGA_REG_IRQMASK = 33, /* Interrupt mask */
153
154 /* Legacy multi-monitor support */
155 SVGA_REG_NUM_GUEST_DISPLAYS = 34,/* Number of guest displays in X/Y direction */
156 SVGA_REG_DISPLAY_ID = 35, /* Display ID for the following display attributes */
157 SVGA_REG_DISPLAY_IS_PRIMARY = 36,/* Whether this is a primary display */
158 SVGA_REG_DISPLAY_POSITION_X = 37,/* The display position x */
159 SVGA_REG_DISPLAY_POSITION_Y = 38,/* The display position y */
160 SVGA_REG_DISPLAY_WIDTH = 39, /* The display's width */
161 SVGA_REG_DISPLAY_HEIGHT = 40, /* The display's height */
162
163 /* See "Guest memory regions" below. */
164 SVGA_REG_GMR_ID = 41,
165 SVGA_REG_GMR_DESCRIPTOR = 42,
166 SVGA_REG_GMR_MAX_IDS = 43,
167 SVGA_REG_GMR_MAX_DESCRIPTOR_LENGTH = 44,
168
169 SVGA_REG_TRACES = 45, /* Enable trace-based updates even when FIFO is on */
170 SVGA_REG_GMRS_MAX_PAGES = 46, /* Maximum number of 4KB pages for all GMRs */
171 SVGA_REG_MEMORY_SIZE = 47, /* Total dedicated device memory excluding FIFO */
172 SVGA_REG_COMMAND_LOW = 48, /* Lower 32 bits and submits commands */
173 SVGA_REG_COMMAND_HIGH = 49, /* Upper 32 bits of command buffer PA */
174 SVGA_REG_MAX_PRIMARY_BOUNDING_BOX_MEM = 50, /* Max primary memory */
175 SVGA_REG_SUGGESTED_GBOBJECT_MEM_SIZE_KB = 51, /* Suggested limit on mob mem */
176 SVGA_REG_DEV_CAP = 52, /* Write dev cap index, read value */
177 SVGA_REG_CMD_PREPEND_LOW = 53,
178 SVGA_REG_CMD_PREPEND_HIGH = 54,
179 SVGA_REG_SCREENTARGET_MAX_WIDTH = 55,
180 SVGA_REG_SCREENTARGET_MAX_HEIGHT = 56,
181 SVGA_REG_MOB_MAX_SIZE = 57,
182 SVGA_REG_TOP = 58, /* Must be 1 more than the last register */
183
184 SVGA_PALETTE_BASE = 1024, /* Base of SVGA color map */
185 /* Next 768 (== 256*3) registers exist for colormap */
186
187 SVGA_SCRATCH_BASE = SVGA_PALETTE_BASE + SVGA_NUM_PALETTE_REGS
188 /* Base of scratch registers */
189 /* Next reg[SVGA_REG_SCRATCH_SIZE] registers exist for scratch usage:
190 First 4 are reserved for VESA BIOS Extension; any remaining are for
191 the use of the current SVGA driver. */
192};
193
194
195/*
196 * Guest memory regions (GMRs):
197 *
198 * This is a new memory mapping feature available in SVGA devices
199 * which have the SVGA_CAP_GMR bit set. Previously, there were two
200 * fixed memory regions available with which to share data between the
201 * device and the driver: the FIFO ('MEM') and the framebuffer. GMRs
202 * are our name for an extensible way of providing arbitrary DMA
203 * buffers for use between the driver and the SVGA device. They are a
204 * new alternative to framebuffer memory, usable for both 2D and 3D
205 * graphics operations.
206 *
207 * Since GMR mapping must be done synchronously with guest CPU
208 * execution, we use a new pair of SVGA registers:
209 *
210 * SVGA_REG_GMR_ID --
211 *
212 * Read/write.
213 * This register holds the 32-bit ID (a small positive integer)
214 * of a GMR to create, delete, or redefine. Writing this register
215 * has no side-effects.
216 *
217 * SVGA_REG_GMR_DESCRIPTOR --
218 *
219 * Write-only.
220 * Writing this register will create, delete, or redefine the GMR
221 * specified by the above ID register. If this register is zero,
222 * the GMR is deleted. Any pointers into this GMR (including those
223 * currently being processed by FIFO commands) will be
224 * synchronously invalidated.
225 *
226 * If this register is nonzero, it must be the physical page
227 * number (PPN) of a data structure which describes the physical
228 * layout of the memory region this GMR should describe. The
229 * descriptor structure will be read synchronously by the SVGA
230 * device when this register is written. The descriptor need not
231 * remain allocated for the lifetime of the GMR.
232 *
233 * The guest driver should write SVGA_REG_GMR_ID first, then
234 * SVGA_REG_GMR_DESCRIPTOR.
235 *
236 * SVGA_REG_GMR_MAX_IDS --
237 *
238 * Read-only.
239 * The SVGA device may choose to support a maximum number of
240 * user-defined GMR IDs. This register holds the number of supported
241 * IDs. (The maximum supported ID plus 1)
242 *
243 * SVGA_REG_GMR_MAX_DESCRIPTOR_LENGTH --
244 *
245 * Read-only.
246 * The SVGA device may choose to put a limit on the total number
247 * of SVGAGuestMemDescriptor structures it will read when defining
248 * a single GMR.
249 *
250 * The descriptor structure is an array of SVGAGuestMemDescriptor
251 * structures. Each structure may do one of three things:
252 *
253 * - Terminate the GMR descriptor list.
254 * (ppn==0, numPages==0)
255 *
256 * - Add a PPN or range of PPNs to the GMR's virtual address space.
257 * (ppn != 0, numPages != 0)
258 *
259 * - Provide the PPN of the next SVGAGuestMemDescriptor, in order to
260 * support multi-page GMR descriptor tables without forcing the
261 * driver to allocate physically contiguous memory.
262 * (ppn != 0, numPages == 0)
263 *
264 * Note that each physical page of SVGAGuestMemDescriptor structures
265 * can describe at least 2MB of guest memory. If the driver needs to
266 * use more than one page of descriptor structures, it must use one of
267 * its SVGAGuestMemDescriptors to point to an additional page. The
268 * device will never automatically cross a page boundary.
269 *
270 * Once the driver has described a GMR, it is immediately available
271 * for use via any FIFO command that uses an SVGAGuestPtr structure.
272 * These pointers include a GMR identifier plus an offset into that
273 * GMR.
274 *
275 * The driver must check the SVGA_CAP_GMR bit before using the GMR
276 * registers.
277 */
278
279/*
280 * Special GMR IDs, allowing SVGAGuestPtrs to point to framebuffer
281 * memory as well. In the future, these IDs could even be used to
282 * allow legacy memory regions to be redefined by the guest as GMRs.
283 *
284 * Using the guest framebuffer (GFB) at BAR1 for general purpose DMA
285 * is being phased out. Please try to use user-defined GMRs whenever
286 * possible.
287 */
288#define SVGA_GMR_NULL ((uint32) -1)
289#define SVGA_GMR_FRAMEBUFFER ((uint32) -2) /* Guest Framebuffer (GFB) */
290
291typedef
292struct SVGAGuestMemDescriptor {
293 uint32 ppn;
294 uint32 numPages;
295} SVGAGuestMemDescriptor;
296
297typedef
298struct SVGAGuestPtr {
299 uint32 gmrId;
300 uint32 offset;
301} SVGAGuestPtr;
302
303
304/*
305 * SVGAGMRImageFormat --
306 *
307 * This is a packed representation of the source 2D image format
308 * for a GMR-to-screen blit. Currently it is defined as an encoding
309 * of the screen's color depth and bits-per-pixel, however, 16 bits
310 * are reserved for future use to identify other encodings (such as
311 * RGBA or higher-precision images).
312 *
313 * Currently supported formats:
314 *
315 * bpp depth Format Name
316 * --- ----- -----------
317 * 32 24 32-bit BGRX
318 * 24 24 24-bit BGR
319 * 16 16 RGB 5-6-5
320 * 16 15 RGB 5-5-5
321 *
322 */
323
324typedef
325struct SVGAGMRImageFormat {
326 union {
327 struct {
328 uint32 bitsPerPixel : 8;
329 uint32 colorDepth : 8;
330 uint32 reserved : 16; /* Must be zero */
331 };
332
333 uint32 value;
334 };
335} SVGAGMRImageFormat;
336
337typedef
338struct SVGAGuestImage {
339 SVGAGuestPtr ptr;
340
341 /*
342 * A note on interpretation of pitch: This value of pitch is the
343 * number of bytes between vertically adjacent image
344 * blocks. Normally this is the number of bytes between the first
345 * pixel of two adjacent scanlines. With compressed textures,
346 * however, this may represent the number of bytes between
347 * compression blocks rather than between rows of pixels.
348 *
349 * XXX: Compressed textures currently must be tightly packed in guest memory.
350 *
351 * If the image is 1-dimensional, pitch is ignored.
352 *
353 * If 'pitch' is zero, the SVGA3D device calculates a pitch value
354 * assuming each row of blocks is tightly packed.
355 */
356 uint32 pitch;
357} SVGAGuestImage;
358
359/*
360 * SVGAColorBGRX --
361 *
362 * A 24-bit color format (BGRX), which does not depend on the
363 * format of the legacy guest framebuffer (GFB) or the current
364 * GMRFB state.
365 */
366
367typedef
368struct SVGAColorBGRX {
369 union {
370 struct {
371 uint32 b : 8;
372 uint32 g : 8;
373 uint32 r : 8;
374 uint32 x : 8; /* Unused */
375 };
376
377 uint32 value;
378 };
379} SVGAColorBGRX;
380
381
382/*
383 * SVGASignedRect --
384 * SVGASignedPoint --
385 *
386 * Signed rectangle and point primitives. These are used by the new
387 * 2D primitives for drawing to Screen Objects, which can occupy a
388 * signed virtual coordinate space.
389 *
390 * SVGASignedRect specifies a half-open interval: the (left, top)
391 * pixel is part of the rectangle, but the (right, bottom) pixel is
392 * not.
393 */
394
395typedef
396struct SVGASignedRect {
397 int32 left;
398 int32 top;
399 int32 right;
400 int32 bottom;
401} SVGASignedRect;
402
403typedef
404struct SVGASignedPoint {
405 int32 x;
406 int32 y;
407} SVGASignedPoint;
408
409
410/*
411 * Capabilities
412 *
413 * Note the holes in the bitfield. Missing bits have been deprecated,
414 * and must not be reused. Those capabilities will never be reported
415 * by new versions of the SVGA device.
416 *
417 * SVGA_CAP_GMR2 --
418 * Provides asynchronous commands to define and remap guest memory
419 * regions. Adds device registers SVGA_REG_GMRS_MAX_PAGES and
420 * SVGA_REG_MEMORY_SIZE.
421 *
422 * SVGA_CAP_SCREEN_OBJECT_2 --
423 * Allow screen object support, and require backing stores from the
424 * guest for each screen object.
425 */
426
427#define SVGA_CAP_NONE 0x00000000
428#define SVGA_CAP_RECT_COPY 0x00000002
429#define SVGA_CAP_CURSOR 0x00000020
430#define SVGA_CAP_CURSOR_BYPASS 0x00000040 /* Legacy (Use Cursor Bypass 3 instead) */
431#define SVGA_CAP_CURSOR_BYPASS_2 0x00000080 /* Legacy (Use Cursor Bypass 3 instead) */
432#define SVGA_CAP_8BIT_EMULATION 0x00000100
433#define SVGA_CAP_ALPHA_CURSOR 0x00000200
434#define SVGA_CAP_3D 0x00004000
435#define SVGA_CAP_EXTENDED_FIFO 0x00008000
436#define SVGA_CAP_MULTIMON 0x00010000 /* Legacy multi-monitor support */
437#define SVGA_CAP_PITCHLOCK 0x00020000
438#define SVGA_CAP_IRQMASK 0x00040000
439#define SVGA_CAP_DISPLAY_TOPOLOGY 0x00080000 /* Legacy multi-monitor support */
440#define SVGA_CAP_GMR 0x00100000
441#define SVGA_CAP_TRACES 0x00200000
442#define SVGA_CAP_GMR2 0x00400000
443#define SVGA_CAP_SCREEN_OBJECT_2 0x00800000
444#define SVGA_CAP_COMMAND_BUFFERS 0x01000000
445#define SVGA_CAP_DEAD1 0x02000000
446#define SVGA_CAP_CMD_BUFFERS_2 0x04000000
447#define SVGA_CAP_GBOBJECTS 0x08000000
448
449/*
450 * FIFO register indices.
451 *
452 * The FIFO is a chunk of device memory mapped into guest physmem. It
453 * is always treated as 32-bit words.
454 *
455 * The guest driver gets to decide how to partition it between
456 * - FIFO registers (there are always at least 4, specifying where the
457 * following data area is and how much data it contains; there may be
458 * more registers following these, depending on the FIFO protocol
459 * version in use)
460 * - FIFO data, written by the guest and slurped out by the VMX.
461 * These indices are 32-bit word offsets into the FIFO.
462 */
463
464enum {
465 /*
466 * Block 1 (basic registers): The originally defined FIFO registers.
467 * These exist and are valid for all versions of the FIFO protocol.
468 */
469
470 SVGA_FIFO_MIN = 0,
471 SVGA_FIFO_MAX, /* The distance from MIN to MAX must be at least 10K */
472 SVGA_FIFO_NEXT_CMD,
473 SVGA_FIFO_STOP,
474
475 /*
476 * Block 2 (extended registers): Mandatory registers for the extended
477 * FIFO. These exist if the SVGA caps register includes
478 * SVGA_CAP_EXTENDED_FIFO; some of them are valid only if their
479 * associated capability bit is enabled.
480 *
481 * Note that when originally defined, SVGA_CAP_EXTENDED_FIFO implied
482 * support only for (FIFO registers) CAPABILITIES, FLAGS, and FENCE.
483 * This means that the guest has to test individually (in most cases
484 * using FIFO caps) for the presence of registers after this; the VMX
485 * can define "extended FIFO" to mean whatever it wants, and currently
486 * won't enable it unless there's room for that set and much more.
487 */
488
489 SVGA_FIFO_CAPABILITIES = 4,
490 SVGA_FIFO_FLAGS,
491 /* Valid with SVGA_FIFO_CAP_FENCE: */
492 SVGA_FIFO_FENCE,
493
494 /*
495 * Block 3a (optional extended registers): Additional registers for the
496 * extended FIFO, whose presence isn't actually implied by
497 * SVGA_CAP_EXTENDED_FIFO; these exist if SVGA_FIFO_MIN is high enough to
498 * leave room for them.
499 *
500 * These in block 3a, the VMX currently considers mandatory for the
501 * extended FIFO.
502 */
503
504 /* Valid if exists (i.e. if extended FIFO enabled): */
505 SVGA_FIFO_3D_HWVERSION, /* See SVGA3dHardwareVersion in svga3d_reg.h */
506 /* Valid with SVGA_FIFO_CAP_PITCHLOCK: */
507 SVGA_FIFO_PITCHLOCK,
508
509 /* Valid with SVGA_FIFO_CAP_CURSOR_BYPASS_3: */
510 SVGA_FIFO_CURSOR_ON, /* Cursor bypass 3 show/hide register */
511 SVGA_FIFO_CURSOR_X, /* Cursor bypass 3 x register */
512 SVGA_FIFO_CURSOR_Y, /* Cursor bypass 3 y register */
513 SVGA_FIFO_CURSOR_COUNT, /* Incremented when any of the other 3 change */
514 SVGA_FIFO_CURSOR_LAST_UPDATED,/* Last time the host updated the cursor */
515
516 /* Valid with SVGA_FIFO_CAP_RESERVE: */
517 SVGA_FIFO_RESERVED, /* Bytes past NEXT_CMD with real contents */
518
519 /*
520 * Valid with SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2:
521 *
522 * By default this is SVGA_ID_INVALID, to indicate that the cursor
523 * coordinates are specified relative to the virtual root. If this
524 * is set to a specific screen ID, cursor position is reinterpreted
525 * as a signed offset relative to that screen's origin.
526 */
527 SVGA_FIFO_CURSOR_SCREEN_ID,
528
529 /*
530 * Valid with SVGA_FIFO_CAP_DEAD
531 *
532 * An arbitrary value written by the host, drivers should not use it.
533 */
534 SVGA_FIFO_DEAD,
535
536 /*
537 * Valid with SVGA_FIFO_CAP_3D_HWVERSION_REVISED:
538 *
539 * Contains 3D HWVERSION (see SVGA3dHardwareVersion in svga3d_reg.h)
540 * on platforms that can enforce graphics resource limits.
541 */
542 SVGA_FIFO_3D_HWVERSION_REVISED,
543
544 /*
545 * XXX: The gap here, up until SVGA_FIFO_3D_CAPS, can be used for new
546 * registers, but this must be done carefully and with judicious use of
547 * capability bits, since comparisons based on SVGA_FIFO_MIN aren't
548 * enough to tell you whether the register exists: we've shipped drivers
549 * and products that used SVGA_FIFO_3D_CAPS but didn't know about some of
550 * the earlier ones. The actual order of introduction was:
551 * - PITCHLOCK
552 * - 3D_CAPS
553 * - CURSOR_* (cursor bypass 3)
554 * - RESERVED
555 * So, code that wants to know whether it can use any of the
556 * aforementioned registers, or anything else added after PITCHLOCK and
557 * before 3D_CAPS, needs to reason about something other than
558 * SVGA_FIFO_MIN.
559 */
560
561 /*
562 * 3D caps block space; valid with 3D hardware version >=
563 * SVGA3D_HWVERSION_WS6_B1.
564 */
565 SVGA_FIFO_3D_CAPS = 32,
566 SVGA_FIFO_3D_CAPS_LAST = 32 + 255,
567
568 /*
569 * End of VMX's current definition of "extended-FIFO registers".
570 * Registers before here are always enabled/disabled as a block; either
571 * the extended FIFO is enabled and includes all preceding registers, or
572 * it's disabled entirely.
573 *
574 * Block 3b (truly optional extended registers): Additional registers for
575 * the extended FIFO, which the VMX already knows how to enable and
576 * disable with correct granularity.
577 *
578 * Registers after here exist if and only if the guest SVGA driver
579 * sets SVGA_FIFO_MIN high enough to leave room for them.
580 */
581
582 /* Valid if register exists: */
583 SVGA_FIFO_GUEST_3D_HWVERSION, /* Guest driver's 3D version */
584 SVGA_FIFO_FENCE_GOAL, /* Matching target for SVGA_IRQFLAG_FENCE_GOAL */
585 SVGA_FIFO_BUSY, /* See "FIFO Synchronization Registers" */
586
587 /*
588 * Always keep this last. This defines the maximum number of
589 * registers we know about. At power-on, this value is placed in
590 * the SVGA_REG_MEM_REGS register, and we expect the guest driver
591 * to allocate this much space in FIFO memory for registers.
592 */
593 SVGA_FIFO_NUM_REGS
594};
595
596
597/*
598 * Definition of registers included in extended FIFO support.
599 *
600 * The guest SVGA driver gets to allocate the FIFO between registers
601 * and data. It must always allocate at least 4 registers, but old
602 * drivers stopped there.
603 *
604 * The VMX will enable extended FIFO support if and only if the guest
605 * left enough room for all registers defined as part of the mandatory
606 * set for the extended FIFO.
607 *
608 * Note that the guest drivers typically allocate the FIFO only at
609 * initialization time, not at mode switches, so it's likely that the
610 * number of FIFO registers won't change without a reboot.
611 *
612 * All registers less than this value are guaranteed to be present if
613 * svgaUser->fifo.extended is set. Any later registers must be tested
614 * individually for compatibility at each use (in the VMX).
615 *
616 * This value is used only by the VMX, so it can change without
617 * affecting driver compatibility; keep it that way?
618 */
619#define SVGA_FIFO_EXTENDED_MANDATORY_REGS (SVGA_FIFO_3D_CAPS_LAST + 1)
620
621
622/*
623 * FIFO Synchronization Registers
624 *
625 * This explains the relationship between the various FIFO
626 * sync-related registers in IOSpace and in FIFO space.
627 *
628 * SVGA_REG_SYNC --
629 *
630 * The SYNC register can be used in two different ways by the guest:
631 *
632 * 1. If the guest wishes to fully sync (drain) the FIFO,
633 * it will write once to SYNC then poll on the BUSY
634 * register. The FIFO is sync'ed once BUSY is zero.
635 *
636 * 2. If the guest wants to asynchronously wake up the host,
637 * it will write once to SYNC without polling on BUSY.
638 * Ideally it will do this after some new commands have
639 * been placed in the FIFO, and after reading a zero
640 * from SVGA_FIFO_BUSY.
641 *
642 * (1) is the original behaviour that SYNC was designed to
643 * support. Originally, a write to SYNC would implicitly
644 * trigger a read from BUSY. This causes us to synchronously
645 * process the FIFO.
646 *
647 * This behaviour has since been changed so that writing SYNC
648 * will *not* implicitly cause a read from BUSY. Instead, it
649 * makes a channel call which asynchronously wakes up the MKS
650 * thread.
651 *
652 * New guests can use this new behaviour to implement (2)
653 * efficiently. This lets guests get the host's attention
654 * without waiting for the MKS to poll, which gives us much
655 * better CPU utilization on SMP hosts and on UP hosts while
656 * we're blocked on the host GPU.
657 *
658 * Old guests shouldn't notice the behaviour change. SYNC was
659 * never guaranteed to process the entire FIFO, since it was
660 * bounded to a particular number of CPU cycles. Old guests will
661 * still loop on the BUSY register until the FIFO is empty.
662 *
663 * Writing to SYNC currently has the following side-effects:
664 *
665 * - Sets SVGA_REG_BUSY to TRUE (in the monitor)
666 * - Asynchronously wakes up the MKS thread for FIFO processing
667 * - The value written to SYNC is recorded as a "reason", for
668 * stats purposes.
669 *
670 * If SVGA_FIFO_BUSY is available, drivers are advised to only
671 * write to SYNC if SVGA_FIFO_BUSY is FALSE. Drivers should set
672 * SVGA_FIFO_BUSY to TRUE after writing to SYNC. The MKS will
673 * eventually set SVGA_FIFO_BUSY on its own, but this approach
674 * lets the driver avoid sending multiple asynchronous wakeup
675 * messages to the MKS thread.
676 *
677 * SVGA_REG_BUSY --
678 *
679 * This register is set to TRUE when SVGA_REG_SYNC is written,
680 * and it reads as FALSE when the FIFO has been completely
681 * drained.
682 *
683 * Every read from this register causes us to synchronously
684 * process FIFO commands. There is no guarantee as to how many
685 * commands each read will process.
686 *
687 * CPU time spent processing FIFO commands will be billed to
688 * the guest.
689 *
690 * New drivers should avoid using this register unless they
691 * need to guarantee that the FIFO is completely drained. It
692 * is overkill for performing a sync-to-fence. Older drivers
693 * will use this register for any type of synchronization.
694 *
695 * SVGA_FIFO_BUSY --
696 *
697 * This register is a fast way for the guest driver to check
698 * whether the FIFO is already being processed. It reads and
699 * writes at normal RAM speeds, with no monitor intervention.
700 *
701 * If this register reads as TRUE, the host is guaranteeing that
702 * any new commands written into the FIFO will be noticed before
703 * the MKS goes back to sleep.
704 *
705 * If this register reads as FALSE, no such guarantee can be
706 * made.
707 *
708 * The guest should use this register to quickly determine
709 * whether or not it needs to wake up the host. If the guest
710 * just wrote a command or group of commands that it would like
711 * the host to begin processing, it should:
712 *
713 * 1. Read SVGA_FIFO_BUSY. If it reads as TRUE, no further
714 * action is necessary.
715 *
716 * 2. Write TRUE to SVGA_FIFO_BUSY. This informs future guest
717 * code that we've already sent a SYNC to the host and we
718 * don't need to send a duplicate.
719 *
720 * 3. Write a reason to SVGA_REG_SYNC. This will send an
721 * asynchronous wakeup to the MKS thread.
722 */
723
724
725/*
726 * FIFO Capabilities
727 *
728 * Fence -- Fence register and command are supported
729 * Accel Front -- Front buffer only commands are supported
730 * Pitch Lock -- Pitch lock register is supported
731 * Video -- SVGA Video overlay units are supported
732 * Escape -- Escape command is supported
733 *
734 * XXX: Add longer descriptions for each capability, including a list
735 * of the new features that each capability provides.
736 *
737 * SVGA_FIFO_CAP_SCREEN_OBJECT --
738 *
739 * Provides dynamic multi-screen rendering, for improved Unity and
740 * multi-monitor modes. With Screen Object, the guest can
741 * dynamically create and destroy 'screens', which can represent
742 * Unity windows or virtual monitors. Screen Object also provides
743 * strong guarantees that DMA operations happen only when
744 * guest-initiated. Screen Object deprecates the BAR1 guest
745 * framebuffer (GFB) and all commands that work only with the GFB.
746 *
747 * New registers:
748 * FIFO_CURSOR_SCREEN_ID, VIDEO_DATA_GMRID, VIDEO_DST_SCREEN_ID
749 *
750 * New 2D commands:
751 * DEFINE_SCREEN, DESTROY_SCREEN, DEFINE_GMRFB, BLIT_GMRFB_TO_SCREEN,
752 * BLIT_SCREEN_TO_GMRFB, ANNOTATION_FILL, ANNOTATION_COPY
753 *
754 * New 3D commands:
755 * BLIT_SURFACE_TO_SCREEN
756 *
757 * New guarantees:
758 *
759 * - The host will not read or write guest memory, including the GFB,
760 * except when explicitly initiated by a DMA command.
761 *
762 * - All DMA, including legacy DMA like UPDATE and PRESENT_READBACK,
763 * is guaranteed to complete before any subsequent FENCEs.
764 *
765 * - All legacy commands which affect a Screen (UPDATE, PRESENT,
766 * PRESENT_READBACK) as well as new Screen blit commands will
767 * all behave consistently as blits, and memory will be read
768 * or written in FIFO order.
769 *
770 * For example, if you PRESENT from one SVGA3D surface to multiple
771 * places on the screen, the data copied will always be from the
772 * SVGA3D surface at the time the PRESENT was issued in the FIFO.
773 * This was not necessarily true on devices without Screen Object.
774 *
775 * This means that on devices that support Screen Object, the
776 * PRESENT_READBACK command should not be necessary unless you
777 * actually want to read back the results of 3D rendering into
778 * system memory. (And for that, the BLIT_SCREEN_TO_GMRFB
779 * command provides a strict superset of functionality.)
780 *
781 * - When a screen is resized, either using Screen Object commands or
782 * legacy multimon registers, its contents are preserved.
783 *
784 * SVGA_FIFO_CAP_GMR2 --
785 *
786 * Provides new commands to define and remap guest memory regions (GMR).
787 *
788 * New 2D commands:
789 * DEFINE_GMR2, REMAP_GMR2.
790 *
791 * SVGA_FIFO_CAP_3D_HWVERSION_REVISED --
792 *
793 * Indicates new register SVGA_FIFO_3D_HWVERSION_REVISED exists.
794 * This register may replace SVGA_FIFO_3D_HWVERSION on platforms
795 * that enforce graphics resource limits. This allows the platform
796 * to clear SVGA_FIFO_3D_HWVERSION and disable 3D in legacy guest
797 * drivers that do not limit their resources.
798 *
799 * Note this is an alias to SVGA_FIFO_CAP_GMR2 because these indicators
800 * are codependent (and thus we use a single capability bit).
801 *
802 * SVGA_FIFO_CAP_SCREEN_OBJECT_2 --
803 *
804 * Modifies the DEFINE_SCREEN command to include a guest provided
805 * backing store in GMR memory and the bytesPerLine for the backing
806 * store. This capability requires the use of a backing store when
807 * creating screen objects. However if SVGA_FIFO_CAP_SCREEN_OBJECT
808 * is present then backing stores are optional.
809 *
810 * SVGA_FIFO_CAP_DEAD --
811 *
812 * Drivers should not use this cap bit. This cap bit can not be
813 * reused since some hosts already expose it.
814 */
815
816#define SVGA_FIFO_CAP_NONE 0
817#define SVGA_FIFO_CAP_FENCE (1<<0)
818#define SVGA_FIFO_CAP_ACCELFRONT (1<<1)
819#define SVGA_FIFO_CAP_PITCHLOCK (1<<2)
820#define SVGA_FIFO_CAP_VIDEO (1<<3)
821#define SVGA_FIFO_CAP_CURSOR_BYPASS_3 (1<<4)
822#define SVGA_FIFO_CAP_ESCAPE (1<<5)
823#define SVGA_FIFO_CAP_RESERVE (1<<6)
824#define SVGA_FIFO_CAP_SCREEN_OBJECT (1<<7)
825#define SVGA_FIFO_CAP_GMR2 (1<<8)
826#define SVGA_FIFO_CAP_3D_HWVERSION_REVISED SVGA_FIFO_CAP_GMR2
827#define SVGA_FIFO_CAP_SCREEN_OBJECT_2 (1<<9)
828#define SVGA_FIFO_CAP_DEAD (1<<10)
829
830
831/*
832 * FIFO Flags
833 *
834 * Accel Front -- Driver should use front buffer only commands
835 */
836
837#define SVGA_FIFO_FLAG_NONE 0
838#define SVGA_FIFO_FLAG_ACCELFRONT (1<<0)
839#define SVGA_FIFO_FLAG_RESERVED (1<<31) /* Internal use only */
840
841/*
842 * FIFO reservation sentinel value
843 */
844
845#define SVGA_FIFO_RESERVED_UNKNOWN 0xffffffff
846
847
848/*
849 * Video overlay support
850 */
851
852#define SVGA_NUM_OVERLAY_UNITS 32
853
854
855/*
856 * Video capabilities that the guest is currently using
857 */
858
859#define SVGA_VIDEO_FLAG_COLORKEY 0x0001
860
861
862/*
863 * Offsets for the video overlay registers
864 */
865
866enum {
867 SVGA_VIDEO_ENABLED = 0,
868 SVGA_VIDEO_FLAGS,
869 SVGA_VIDEO_DATA_OFFSET,
870 SVGA_VIDEO_FORMAT,
871 SVGA_VIDEO_COLORKEY,
872 SVGA_VIDEO_SIZE, /* Deprecated */
873 SVGA_VIDEO_WIDTH,
874 SVGA_VIDEO_HEIGHT,
875 SVGA_VIDEO_SRC_X,
876 SVGA_VIDEO_SRC_Y,
877 SVGA_VIDEO_SRC_WIDTH,
878 SVGA_VIDEO_SRC_HEIGHT,
879 SVGA_VIDEO_DST_X, /* Signed int32 */
880 SVGA_VIDEO_DST_Y, /* Signed int32 */
881 SVGA_VIDEO_DST_WIDTH,
882 SVGA_VIDEO_DST_HEIGHT,
883 SVGA_VIDEO_PITCH_1,
884 SVGA_VIDEO_PITCH_2,
885 SVGA_VIDEO_PITCH_3,
886 SVGA_VIDEO_DATA_GMRID, /* Optional, defaults to SVGA_GMR_FRAMEBUFFER */
887 SVGA_VIDEO_DST_SCREEN_ID, /* Optional, defaults to virtual coords (SVGA_ID_INVALID) */
888 SVGA_VIDEO_NUM_REGS
889};
890
891
892/*
893 * SVGA Overlay Units
894 *
895 * width and height relate to the entire source video frame.
896 * srcX, srcY, srcWidth and srcHeight represent subset of the source
897 * video frame to be displayed.
898 */
899
900typedef struct SVGAOverlayUnit {
901 uint32 enabled;
902 uint32 flags;
903 uint32 dataOffset;
904 uint32 format;
905 uint32 colorKey;
906 uint32 size;
907 uint32 width;
908 uint32 height;
909 uint32 srcX;
910 uint32 srcY;
911 uint32 srcWidth;
912 uint32 srcHeight;
913 int32 dstX;
914 int32 dstY;
915 uint32 dstWidth;
916 uint32 dstHeight;
917 uint32 pitches[3];
918 uint32 dataGMRId;
919 uint32 dstScreenId;
920} SVGAOverlayUnit;
921
922
923/*
924 * SVGAScreenObject --
925 *
926 * This is a new way to represent a guest's multi-monitor screen or
927 * Unity window. Screen objects are only supported if the
928 * SVGA_FIFO_CAP_SCREEN_OBJECT capability bit is set.
929 *
930 * If Screen Objects are supported, they can be used to fully
931 * replace the functionality provided by the framebuffer registers
932 * (SVGA_REG_WIDTH, HEIGHT, etc.) and by SVGA_CAP_DISPLAY_TOPOLOGY.
933 *
934 * The screen object is a struct with guaranteed binary
935 * compatibility. New flags can be added, and the struct may grow,
936 * but existing fields must retain their meaning.
937 *
938 * Added with SVGA_FIFO_CAP_SCREEN_OBJECT_2 are required fields of
939 * a SVGAGuestPtr that is used to back the screen contents. This
940 * memory must come from the GFB. The guest is not allowed to
941 * access the memory and doing so will have undefined results. The
942 * backing store is required to be page aligned and the size is
943 * padded to the next page boundry. The number of pages is:
944 * (bytesPerLine * size.width * 4 + PAGE_SIZE - 1) / PAGE_SIZE
945 *
946 * The pitch in the backingStore is required to be at least large
947 * enough to hold a 32bbp scanline. It is recommended that the
948 * driver pad bytesPerLine for a potential performance win.
949 *
950 * The cloneCount field is treated as a hint from the guest that
951 * the user wants this display to be cloned, countCount times. A
952 * value of zero means no cloning should happen.
953 */
954
955#define SVGA_SCREEN_MUST_BE_SET (1 << 0) /* Must be set or results undefined */
956#define SVGA_SCREEN_HAS_ROOT SVGA_SCREEN_MUST_BE_SET /* Deprecated */
957#define SVGA_SCREEN_IS_PRIMARY (1 << 1) /* Guest considers this screen to be 'primary' */
958#define SVGA_SCREEN_FULLSCREEN_HINT (1 << 2) /* Guest is running a fullscreen app here */
959
960/*
961 * Added with SVGA_FIFO_CAP_SCREEN_OBJECT_2. When the screen is
962 * deactivated the base layer is defined to lose all contents and
963 * become black. When a screen is deactivated the backing store is
964 * optional. When set backingPtr and bytesPerLine will be ignored.
965 */
966#define SVGA_SCREEN_DEACTIVATE (1 << 3)
967
968/*
969 * Added with SVGA_FIFO_CAP_SCREEN_OBJECT_2. When this flag is set
970 * the screen contents will be outputted as all black to the user
971 * though the base layer contents is preserved. The screen base layer
972 * can still be read and written to like normal though the no visible
973 * effect will be seen by the user. When the flag is changed the
974 * screen will be blanked or redrawn to the current contents as needed
975 * without any extra commands from the driver. This flag only has an
976 * effect when the screen is not deactivated.
977 */
978#define SVGA_SCREEN_BLANKING (1 << 4)
979
980typedef
981struct SVGAScreenObject {
982 uint32 structSize; /* sizeof(SVGAScreenObject) */
983 uint32 id;
984 uint32 flags;
985 struct {
986 uint32 width;
987 uint32 height;
988 } size;
989 struct {
990 int32 x;
991 int32 y;
992 } root;
993
994 /*
995 * Added and required by SVGA_FIFO_CAP_SCREEN_OBJECT_2, optional
996 * with SVGA_FIFO_CAP_SCREEN_OBJECT.
997 */
998 SVGAGuestImage backingStore;
999 uint32 cloneCount;
1000} SVGAScreenObject;
1001
1002
1003/*
1004 * Commands in the command FIFO:
1005 *
1006 * Command IDs defined below are used for the traditional 2D FIFO
1007 * communication (not all commands are available for all versions of the
1008 * SVGA FIFO protocol).
1009 *
1010 * Note the holes in the command ID numbers: These commands have been
1011 * deprecated, and the old IDs must not be reused.
1012 *
1013 * Command IDs from 1000 to 1999 are reserved for use by the SVGA3D
1014 * protocol.
1015 *
1016 * Each command's parameters are described by the comments and
1017 * structs below.
1018 */
1019
1020typedef enum {
1021 SVGA_CMD_INVALID_CMD = 0,
1022 SVGA_CMD_UPDATE = 1,
1023 SVGA_CMD_RECT_COPY = 3,
1024 SVGA_CMD_DEFINE_CURSOR = 19,
1025 SVGA_CMD_DEFINE_ALPHA_CURSOR = 22,
1026 SVGA_CMD_UPDATE_VERBOSE = 25,
1027 SVGA_CMD_FRONT_ROP_FILL = 29,
1028 SVGA_CMD_FENCE = 30,
1029 SVGA_CMD_ESCAPE = 33,
1030 SVGA_CMD_DEFINE_SCREEN = 34,
1031 SVGA_CMD_DESTROY_SCREEN = 35,
1032 SVGA_CMD_DEFINE_GMRFB = 36,
1033 SVGA_CMD_BLIT_GMRFB_TO_SCREEN = 37,
1034 SVGA_CMD_BLIT_SCREEN_TO_GMRFB = 38,
1035 SVGA_CMD_ANNOTATION_FILL = 39,
1036 SVGA_CMD_ANNOTATION_COPY = 40,
1037 SVGA_CMD_DEFINE_GMR2 = 41,
1038 SVGA_CMD_REMAP_GMR2 = 42,
1039 SVGA_CMD_MAX
1040} SVGAFifoCmdId;
1041
1042#define SVGA_CMD_MAX_ARGS 64
1043
1044
1045/*
1046 * SVGA_CMD_UPDATE --
1047 *
1048 * This is a DMA transfer which copies from the Guest Framebuffer
1049 * (GFB) at BAR1 + SVGA_REG_FB_OFFSET to any screens which
1050 * intersect with the provided virtual rectangle.
1051 *
1052 * This command does not support using arbitrary guest memory as a
1053 * data source- it only works with the pre-defined GFB memory.
1054 * This command also does not support signed virtual coordinates.
1055 * If you have defined screens (using SVGA_CMD_DEFINE_SCREEN) with
1056 * negative root x/y coordinates, the negative portion of those
1057 * screens will not be reachable by this command.
1058 *
1059 * This command is not necessary when using framebuffer
1060 * traces. Traces are automatically enabled if the SVGA FIFO is
1061 * disabled, and you may explicitly enable/disable traces using
1062 * SVGA_REG_TRACES. With traces enabled, any write to the GFB will
1063 * automatically act as if a subsequent SVGA_CMD_UPDATE was issued.
1064 *
1065 * Traces and SVGA_CMD_UPDATE are the only supported ways to render
1066 * pseudocolor screen updates. The newer Screen Object commands
1067 * only support true color formats.
1068 *
1069 * Availability:
1070 * Always available.
1071 */
1072
1073typedef
1074struct SVGAFifoCmdUpdate {
1075 uint32 x;
1076 uint32 y;
1077 uint32 width;
1078 uint32 height;
1079} SVGAFifoCmdUpdate;
1080
1081
1082/*
1083 * SVGA_CMD_RECT_COPY --
1084 *
1085 * Perform a rectangular DMA transfer from one area of the GFB to
1086 * another, and copy the result to any screens which intersect it.
1087 *
1088 * Availability:
1089 * SVGA_CAP_RECT_COPY
1090 */
1091
1092typedef
1093struct SVGAFifoCmdRectCopy {
1094 uint32 srcX;
1095 uint32 srcY;
1096 uint32 destX;
1097 uint32 destY;
1098 uint32 width;
1099 uint32 height;
1100} SVGAFifoCmdRectCopy;
1101
1102
1103/*
1104 * SVGA_CMD_DEFINE_CURSOR --
1105 *
1106 * Provide a new cursor image, as an AND/XOR mask.
1107 *
1108 * The recommended way to position the cursor overlay is by using
1109 * the SVGA_FIFO_CURSOR_* registers, supported by the
1110 * SVGA_FIFO_CAP_CURSOR_BYPASS_3 capability.
1111 *
1112 * Availability:
1113 * SVGA_CAP_CURSOR
1114 */
1115
1116typedef
1117struct SVGAFifoCmdDefineCursor {
1118 uint32 id; /* Reserved, must be zero. */
1119 uint32 hotspotX;
1120 uint32 hotspotY;
1121 uint32 width;
1122 uint32 height;
1123 uint32 andMaskDepth; /* Value must be 1 or equal to BITS_PER_PIXEL */
1124 uint32 xorMaskDepth; /* Value must be 1 or equal to BITS_PER_PIXEL */
1125 /*
1126 * Followed by scanline data for AND mask, then XOR mask.
1127 * Each scanline is padded to a 32-bit boundary.
1128 */
1129} SVGAFifoCmdDefineCursor;
1130
1131
1132/*
1133 * SVGA_CMD_DEFINE_ALPHA_CURSOR --
1134 *
1135 * Provide a new cursor image, in 32-bit BGRA format.
1136 *
1137 * The recommended way to position the cursor overlay is by using
1138 * the SVGA_FIFO_CURSOR_* registers, supported by the
1139 * SVGA_FIFO_CAP_CURSOR_BYPASS_3 capability.
1140 *
1141 * Availability:
1142 * SVGA_CAP_ALPHA_CURSOR
1143 */
1144
1145typedef
1146struct SVGAFifoCmdDefineAlphaCursor {
1147 uint32 id; /* Reserved, must be zero. */
1148 uint32 hotspotX;
1149 uint32 hotspotY;
1150 uint32 width;
1151 uint32 height;
1152 /* Followed by scanline data */
1153} SVGAFifoCmdDefineAlphaCursor;
1154
1155
1156/*
1157 * SVGA_CMD_UPDATE_VERBOSE --
1158 *
1159 * Just like SVGA_CMD_UPDATE, but also provide a per-rectangle
1160 * 'reason' value, an opaque cookie which is used by internal
1161 * debugging tools. Third party drivers should not use this
1162 * command.
1163 *
1164 * Availability:
1165 * SVGA_CAP_EXTENDED_FIFO
1166 */
1167
1168typedef
1169struct SVGAFifoCmdUpdateVerbose {
1170 uint32 x;
1171 uint32 y;
1172 uint32 width;
1173 uint32 height;
1174 uint32 reason;
1175} SVGAFifoCmdUpdateVerbose;
1176
1177
1178/*
1179 * SVGA_CMD_FRONT_ROP_FILL --
1180 *
1181 * This is a hint which tells the SVGA device that the driver has
1182 * just filled a rectangular region of the GFB with a solid
1183 * color. Instead of reading these pixels from the GFB, the device
1184 * can assume that they all equal 'color'. This is primarily used
1185 * for remote desktop protocols.
1186 *
1187 * Availability:
1188 * SVGA_FIFO_CAP_ACCELFRONT
1189 */
1190
1191#define SVGA_ROP_COPY 0x03
1192
1193typedef
1194struct SVGAFifoCmdFrontRopFill {
1195 uint32 color; /* In the same format as the GFB */
1196 uint32 x;
1197 uint32 y;
1198 uint32 width;
1199 uint32 height;
1200 uint32 rop; /* Must be SVGA_ROP_COPY */
1201} SVGAFifoCmdFrontRopFill;
1202
1203
1204/*
1205 * SVGA_CMD_FENCE --
1206 *
1207 * Insert a synchronization fence. When the SVGA device reaches
1208 * this command, it will copy the 'fence' value into the
1209 * SVGA_FIFO_FENCE register. It will also compare the fence against
1210 * SVGA_FIFO_FENCE_GOAL. If the fence matches the goal and the
1211 * SVGA_IRQFLAG_FENCE_GOAL interrupt is enabled, the device will
1212 * raise this interrupt.
1213 *
1214 * Availability:
1215 * SVGA_FIFO_FENCE for this command,
1216 * SVGA_CAP_IRQMASK for SVGA_FIFO_FENCE_GOAL.
1217 */
1218
1219typedef
1220struct {
1221 uint32 fence;
1222} SVGAFifoCmdFence;
1223
1224
1225/*
1226 * SVGA_CMD_ESCAPE --
1227 *
1228 * Send an extended or vendor-specific variable length command.
1229 * This is used for video overlay, third party plugins, and
1230 * internal debugging tools. See svga_escape.h
1231 *
1232 * Availability:
1233 * SVGA_FIFO_CAP_ESCAPE
1234 */
1235
1236typedef
1237struct SVGAFifoCmdEscape {
1238 uint32 nsid;
1239 uint32 size;
1240 /* followed by 'size' bytes of data */
1241} SVGAFifoCmdEscape;
1242
1243
1244/*
1245 * SVGA_CMD_DEFINE_SCREEN --
1246 *
1247 * Define or redefine an SVGAScreenObject. See the description of
1248 * SVGAScreenObject above. The video driver is responsible for
1249 * generating new screen IDs. They should be small positive
1250 * integers. The virtual device will have an implementation
1251 * specific upper limit on the number of screen IDs
1252 * supported. Drivers are responsible for recycling IDs. The first
1253 * valid ID is zero.
1254 *
1255 * - Interaction with other registers:
1256 *
1257 * For backwards compatibility, when the GFB mode registers (WIDTH,
1258 * HEIGHT, PITCHLOCK, BITS_PER_PIXEL) are modified, the SVGA device
1259 * deletes all screens other than screen #0, and redefines screen
1260 * #0 according to the specified mode. Drivers that use
1261 * SVGA_CMD_DEFINE_SCREEN should destroy or redefine screen #0.
1262 *
1263 * If you use screen objects, do not use the legacy multi-mon
1264 * registers (SVGA_REG_NUM_GUEST_DISPLAYS, SVGA_REG_DISPLAY_*).
1265 *
1266 * Availability:
1267 * SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
1268 */
1269
1270typedef
1271struct {
1272 SVGAScreenObject screen; /* Variable-length according to version */
1273} SVGAFifoCmdDefineScreen;
1274
1275
1276/*
1277 * SVGA_CMD_DESTROY_SCREEN --
1278 *
1279 * Destroy an SVGAScreenObject. Its ID is immediately available for
1280 * re-use.
1281 *
1282 * Availability:
1283 * SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
1284 */
1285
1286typedef
1287struct {
1288 uint32 screenId;
1289} SVGAFifoCmdDestroyScreen;
1290
1291
1292/*
1293 * SVGA_CMD_DEFINE_GMRFB --
1294 *
1295 * This command sets a piece of SVGA device state called the
1296 * Guest Memory Region Framebuffer, or GMRFB. The GMRFB is a
1297 * piece of light-weight state which identifies the location and
1298 * format of an image in guest memory or in BAR1. The GMRFB has
1299 * an arbitrary size, and it doesn't need to match the geometry
1300 * of the GFB or any screen object.
1301 *
1302 * The GMRFB can be redefined as often as you like. You could
1303 * always use the same GMRFB, you could redefine it before
1304 * rendering from a different guest screen, or you could even
1305 * redefine it before every blit.
1306 *
1307 * There are multiple ways to use this command. The simplest way is
1308 * to use it to move the framebuffer either to elsewhere in the GFB
1309 * (BAR1) memory region, or to a user-defined GMR. This lets a
1310 * driver use a framebuffer allocated entirely out of normal system
1311 * memory, which we encourage.
1312 *
1313 * Another way to use this command is to set up a ring buffer of
1314 * updates in GFB memory. If a driver wants to ensure that no
1315 * frames are skipped by the SVGA device, it is important that the
1316 * driver not modify the source data for a blit until the device is
1317 * done processing the command. One efficient way to accomplish
1318 * this is to use a ring of small DMA buffers. Each buffer is used
1319 * for one blit, then we move on to the next buffer in the
1320 * ring. The FENCE mechanism is used to protect each buffer from
1321 * re-use until the device is finished with that buffer's
1322 * corresponding blit.
1323 *
1324 * This command does not affect the meaning of SVGA_CMD_UPDATE.
1325 * UPDATEs always occur from the legacy GFB memory area. This
1326 * command has no support for pseudocolor GMRFBs. Currently only
1327 * true-color 15, 16, and 24-bit depths are supported. Future
1328 * devices may expose capabilities for additional framebuffer
1329 * formats.
1330 *
1331 * The default GMRFB value is undefined. Drivers must always send
1332 * this command at least once before performing any blit from the
1333 * GMRFB.
1334 *
1335 * Availability:
1336 * SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
1337 */
1338
1339typedef
1340struct {
1341 SVGAGuestPtr ptr;
1342 uint32 bytesPerLine;
1343 SVGAGMRImageFormat format;
1344} SVGAFifoCmdDefineGMRFB;
1345
1346
1347/*
1348 * SVGA_CMD_BLIT_GMRFB_TO_SCREEN --
1349 *
1350 * This is a guest-to-host blit. It performs a DMA operation to
1351 * copy a rectangular region of pixels from the current GMRFB to
1352 * one or more Screen Objects.
1353 *
1354 * The destination coordinate may be specified relative to a
1355 * screen's origin (if a screen ID is specified) or relative to the
1356 * virtual coordinate system's origin (if the screen ID is
1357 * SVGA_ID_INVALID). The actual destination may span zero or more
1358 * screens, in the case of a virtual destination rect or a rect
1359 * which extends off the edge of the specified screen.
1360 *
1361 * This command writes to the screen's "base layer": the underlying
1362 * framebuffer which exists below any cursor or video overlays. No
1363 * action is necessary to explicitly hide or update any overlays
1364 * which exist on top of the updated region.
1365 *
1366 * The SVGA device is guaranteed to finish reading from the GMRFB
1367 * by the time any subsequent FENCE commands are reached.
1368 *
1369 * This command consumes an annotation. See the
1370 * SVGA_CMD_ANNOTATION_* commands for details.
1371 *
1372 * Availability:
1373 * SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
1374 */
1375
1376typedef
1377struct {
1378 SVGASignedPoint srcOrigin;
1379 SVGASignedRect destRect;
1380 uint32 destScreenId;
1381} SVGAFifoCmdBlitGMRFBToScreen;
1382
1383
1384/*
1385 * SVGA_CMD_BLIT_SCREEN_TO_GMRFB --
1386 *
1387 * This is a host-to-guest blit. It performs a DMA operation to
1388 * copy a rectangular region of pixels from a single Screen Object
1389 * back to the current GMRFB.
1390 *
1391 * Usage note: This command should be used rarely. It will
1392 * typically be inefficient, but it is necessary for some types of
1393 * synchronization between 3D (GPU) and 2D (CPU) rendering into
1394 * overlapping areas of a screen.
1395 *
1396 * The source coordinate is specified relative to a screen's
1397 * origin. The provided screen ID must be valid. If any parameters
1398 * are invalid, the resulting pixel values are undefined.
1399 *
1400 * This command reads the screen's "base layer". Overlays like
1401 * video and cursor are not included, but any data which was sent
1402 * using a blit-to-screen primitive will be available, no matter
1403 * whether the data's original source was the GMRFB or the 3D
1404 * acceleration hardware.
1405 *
1406 * Note that our guest-to-host blits and host-to-guest blits aren't
1407 * symmetric in their current implementation. While the parameters
1408 * are identical, host-to-guest blits are a lot less featureful.
1409 * They do not support clipping: If the source parameters don't
1410 * fully fit within a screen, the blit fails. They must originate
1411 * from exactly one screen. Virtual coordinates are not directly
1412 * supported.
1413 *
1414 * Host-to-guest blits do support the same set of GMRFB formats
1415 * offered by guest-to-host blits.
1416 *
1417 * The SVGA device is guaranteed to finish writing to the GMRFB by
1418 * the time any subsequent FENCE commands are reached.
1419 *
1420 * Availability:
1421 * SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
1422 */
1423
1424typedef
1425struct {
1426 SVGASignedPoint destOrigin;
1427 SVGASignedRect srcRect;
1428 uint32 srcScreenId;
1429} SVGAFifoCmdBlitScreenToGMRFB;
1430
1431
1432/*
1433 * SVGA_CMD_ANNOTATION_FILL --
1434 *
1435 * This is a blit annotation. This command stores a small piece of
1436 * device state which is consumed by the next blit-to-screen
1437 * command. The state is only cleared by commands which are
1438 * specifically documented as consuming an annotation. Other
1439 * commands (such as ESCAPEs for debugging) may intervene between
1440 * the annotation and its associated blit.
1441 *
1442 * This annotation is a promise about the contents of the next
1443 * blit: The video driver is guaranteeing that all pixels in that
1444 * blit will have the same value, specified here as a color in
1445 * SVGAColorBGRX format.
1446 *
1447 * The SVGA device can still render the blit correctly even if it
1448 * ignores this annotation, but the annotation may allow it to
1449 * perform the blit more efficiently, for example by ignoring the
1450 * source data and performing a fill in hardware.
1451 *
1452 * This annotation is most important for performance when the
1453 * user's display is being remoted over a network connection.
1454 *
1455 * Availability:
1456 * SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
1457 */
1458
1459typedef
1460struct {
1461 SVGAColorBGRX color;
1462} SVGAFifoCmdAnnotationFill;
1463
1464
1465/*
1466 * SVGA_CMD_ANNOTATION_COPY --
1467 *
1468 * This is a blit annotation. See SVGA_CMD_ANNOTATION_FILL for more
1469 * information about annotations.
1470 *
1471 * This annotation is a promise about the contents of the next
1472 * blit: The video driver is guaranteeing that all pixels in that
1473 * blit will have the same value as those which already exist at an
1474 * identically-sized region on the same or a different screen.
1475 *
1476 * Note that the source pixels for the COPY in this annotation are
1477 * sampled before applying the anqnotation's associated blit. They
1478 * are allowed to overlap with the blit's destination pixels.
1479 *
1480 * The copy source rectangle is specified the same way as the blit
1481 * destination: it can be a rectangle which spans zero or more
1482 * screens, specified relative to either a screen or to the virtual
1483 * coordinate system's origin. If the source rectangle includes
1484 * pixels which are not from exactly one screen, the results are
1485 * undefined.
1486 *
1487 * Availability:
1488 * SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
1489 */
1490
1491typedef
1492struct {
1493 SVGASignedPoint srcOrigin;
1494 uint32 srcScreenId;
1495} SVGAFifoCmdAnnotationCopy;
1496
1497
1498/*
1499 * SVGA_CMD_DEFINE_GMR2 --
1500 *
1501 * Define guest memory region v2. See the description of GMRs above.
1502 *
1503 * Availability:
1504 * SVGA_CAP_GMR2
1505 */
1506
1507typedef
1508struct {
1509 uint32 gmrId;
1510 uint32 numPages;
1511} SVGAFifoCmdDefineGMR2;
1512
1513
1514/*
1515 * SVGA_CMD_REMAP_GMR2 --
1516 *
1517 * Remap guest memory region v2. See the description of GMRs above.
1518 *
1519 * This command allows guest to modify a portion of an existing GMR by
1520 * invalidating it or reassigning it to different guest physical pages.
1521 * The pages are identified by physical page number (PPN). The pages
1522 * are assumed to be pinned and valid for DMA operations.
1523 *
1524 * Description of command flags:
1525 *
1526 * SVGA_REMAP_GMR2_VIA_GMR: If enabled, references a PPN list in a GMR.
1527 * The PPN list must not overlap with the remap region (this can be
1528 * handled trivially by referencing a separate GMR). If flag is
1529 * disabled, PPN list is appended to SVGARemapGMR command.
1530 *
1531 * SVGA_REMAP_GMR2_PPN64: If set, PPN list is in PPN64 format, otherwise
1532 * it is in PPN32 format.
1533 *
1534 * SVGA_REMAP_GMR2_SINGLE_PPN: If set, PPN list contains a single entry.
1535 * A single PPN can be used to invalidate a portion of a GMR or
1536 * map it to to a single guest scratch page.
1537 *
1538 * Availability:
1539 * SVGA_CAP_GMR2
1540 */
1541
1542typedef enum {
1543 SVGA_REMAP_GMR2_PPN32 = 0,
1544 SVGA_REMAP_GMR2_VIA_GMR = (1 << 0),
1545 SVGA_REMAP_GMR2_PPN64 = (1 << 1),
1546 SVGA_REMAP_GMR2_SINGLE_PPN = (1 << 2),
1547} SVGARemapGMR2Flags;
1548
1549typedef
1550struct {
1551 uint32 gmrId;
1552 SVGARemapGMR2Flags flags;
1553 uint32 offsetPages; /* offset in pages to begin remap */
1554 uint32 numPages; /* number of pages to remap */
1555 /*
1556 * Followed by additional data depending on SVGARemapGMR2Flags.
1557 *
1558 * If flag SVGA_REMAP_GMR2_VIA_GMR is set, single SVGAGuestPtr follows.
1559 * Otherwise an array of page descriptors in PPN32 or PPN64 format
1560 * (according to flag SVGA_REMAP_GMR2_PPN64) follows. If flag
1561 * SVGA_REMAP_GMR2_SINGLE_PPN is set, array contains a single entry.
1562 */
1563} SVGAFifoCmdRemapGMR2;
1564
1565#endif