• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /* SPDX-License-Identifier: GPL-2.0 OR MIT */
2 /**********************************************************
3  * Copyright 1998-2015 VMware, Inc.
4  *
5  * Permission is hereby granted, free of charge, to any person
6  * obtaining a copy of this software and associated documentation
7  * files (the "Software"), to deal in the Software without
8  * restriction, including without limitation the rights to use, copy,
9  * modify, merge, publish, distribute, sublicense, and/or sell copies
10  * of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be
14  * included in all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
20  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
21  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23  * SOFTWARE.
24  *
25  **********************************************************/
26 
27 /*
28  * svga_reg.h --
29  *
30  *    Virtual hardware definitions for the VMware SVGA II device.
31  */
32 
33 #ifndef _SVGA_REG_H_
34 #define _SVGA_REG_H_
35 #include <linux/pci_ids.h>
36 
37 #define INCLUDE_ALLOW_MODULE
38 #define INCLUDE_ALLOW_USERLEVEL
39 
40 #define INCLUDE_ALLOW_VMCORE
41 #include "includeCheck.h"
42 
43 #include "svga_types.h"
44 
45 /*
46  * SVGA_REG_ENABLE bit definitions.
47  */
48 typedef enum {
49    SVGA_REG_ENABLE_DISABLE = 0,
50    SVGA_REG_ENABLE_ENABLE = (1 << 0),
51    SVGA_REG_ENABLE_HIDE = (1 << 1),
52 } SvgaRegEnable;
53 
54 typedef uint32 SVGAMobId;
55 
56 /*
57  * Arbitrary and meaningless limits. Please ignore these when writing
58  * new drivers.
59  */
60 #define SVGA_MAX_WIDTH                  2560
61 #define SVGA_MAX_HEIGHT                 1600
62 
63 
64 #define SVGA_MAX_BITS_PER_PIXEL         32
65 #define SVGA_MAX_DEPTH                  24
66 #define SVGA_MAX_DISPLAYS               10
67 #define SVGA_MAX_SCREEN_SIZE            8192
68 #define SVGA_SCREEN_ROOT_LIMIT (SVGA_MAX_SCREEN_SIZE * SVGA_MAX_DISPLAYS)
69 
70 
71 /*
72  * Legal values for the SVGA_REG_CURSOR_ON register in old-fashioned
73  * cursor bypass mode.
74  */
75 #define SVGA_CURSOR_ON_HIDE            0x0
76 #define SVGA_CURSOR_ON_SHOW            0x1
77 
78 /*
79  * Remove the cursor from the framebuffer
80  * because we need to see what's under it
81  */
82 #define SVGA_CURSOR_ON_REMOVE_FROM_FB  0x2
83 
84 /* Put the cursor back in the framebuffer so the user can see it */
85 #define SVGA_CURSOR_ON_RESTORE_TO_FB   0x3
86 
87 /*
88  * The maximum framebuffer size that can traced for guests unless the
89  * SVGA_CAP_GBOBJECTS is set in SVGA_REG_CAPABILITIES.  In that case
90  * the full framebuffer can be traced independent of this limit.
91  */
92 #define SVGA_FB_MAX_TRACEABLE_SIZE      0x1000000
93 
94 #define SVGA_MAX_PSEUDOCOLOR_DEPTH      8
95 #define SVGA_MAX_PSEUDOCOLORS           (1 << SVGA_MAX_PSEUDOCOLOR_DEPTH)
96 #define SVGA_NUM_PALETTE_REGS           (3 * SVGA_MAX_PSEUDOCOLORS)
97 
98 #define SVGA_MAGIC         0x900000UL
99 #define SVGA_MAKE_ID(ver)  (SVGA_MAGIC << 8 | (ver))
100 
101 /* Version 2 let the address of the frame buffer be unsigned on Win32 */
102 #define SVGA_VERSION_2     2
103 #define SVGA_ID_2          SVGA_MAKE_ID(SVGA_VERSION_2)
104 
105 /* Version 1 has new registers starting with SVGA_REG_CAPABILITIES so
106    PALETTE_BASE has moved */
107 #define SVGA_VERSION_1     1
108 #define SVGA_ID_1          SVGA_MAKE_ID(SVGA_VERSION_1)
109 
110 /* Version 0 is the initial version */
111 #define SVGA_VERSION_0     0
112 #define SVGA_ID_0          SVGA_MAKE_ID(SVGA_VERSION_0)
113 
114 /*
115  * "Invalid" value for all SVGA IDs.
116  * (Version ID, screen object ID, surface ID...)
117  */
118 #define SVGA_ID_INVALID    0xFFFFFFFF
119 
120 /* Port offsets, relative to BAR0 */
121 #define SVGA_INDEX_PORT         0x0
122 #define SVGA_VALUE_PORT         0x1
123 #define SVGA_BIOS_PORT          0x2
124 #define SVGA_IRQSTATUS_PORT     0x8
125 
126 /*
127  * Interrupt source flags for IRQSTATUS_PORT and IRQMASK.
128  *
129  * Interrupts are only supported when the
130  * SVGA_CAP_IRQMASK capability is present.
131  */
132 #define SVGA_IRQFLAG_ANY_FENCE            0x1    /* Any fence was passed */
133 #define SVGA_IRQFLAG_FIFO_PROGRESS        0x2    /* Made forward progress in the FIFO */
134 #define SVGA_IRQFLAG_FENCE_GOAL           0x4    /* SVGA_FIFO_FENCE_GOAL reached */
135 #define SVGA_IRQFLAG_COMMAND_BUFFER       0x8    /* Command buffer completed */
136 #define SVGA_IRQFLAG_ERROR                0x10   /* Error while processing commands */
137 
138 /*
139  * The byte-size is the size of the actual cursor data,
140  * possibly after expanding it to the current bit depth.
141  *
142  * 40K is sufficient memory for two 32-bit planes for a 64 x 64 cursor.
143  *
144  * The dimension limit is a bound on the maximum width or height.
145  */
146 #define SVGA_MAX_CURSOR_CMD_BYTES  (40 * 1024)
147 #define SVGA_MAX_CURSOR_CMD_DIMENSION 1024
148 
149 /*
150  * Registers
151  */
152 
153 enum {
154    SVGA_REG_ID = 0,
155    SVGA_REG_ENABLE = 1,
156    SVGA_REG_WIDTH = 2,
157    SVGA_REG_HEIGHT = 3,
158    SVGA_REG_MAX_WIDTH = 4,
159    SVGA_REG_MAX_HEIGHT = 5,
160    SVGA_REG_DEPTH = 6,
161    SVGA_REG_BITS_PER_PIXEL = 7,       /* Current bpp in the guest */
162    SVGA_REG_PSEUDOCOLOR = 8,
163    SVGA_REG_RED_MASK = 9,
164    SVGA_REG_GREEN_MASK = 10,
165    SVGA_REG_BLUE_MASK = 11,
166    SVGA_REG_BYTES_PER_LINE = 12,
167    SVGA_REG_FB_START = 13,            /* (Deprecated) */
168    SVGA_REG_FB_OFFSET = 14,
169    SVGA_REG_VRAM_SIZE = 15,
170    SVGA_REG_FB_SIZE = 16,
171 
172    /* ID 0 implementation only had the above registers, then the palette */
173    SVGA_REG_ID_0_TOP = 17,
174 
175    SVGA_REG_CAPABILITIES = 17,
176    SVGA_REG_MEM_START = 18,           /* (Deprecated) */
177    SVGA_REG_MEM_SIZE = 19,
178    SVGA_REG_CONFIG_DONE = 20,         /* Set when memory area configured */
179    SVGA_REG_SYNC = 21,                /* See "FIFO Synchronization Registers" */
180    SVGA_REG_BUSY = 22,                /* See "FIFO Synchronization Registers" */
181    SVGA_REG_GUEST_ID = 23,            /* (Deprecated) */
182    SVGA_REG_DEAD = 24,                /* Drivers should never write this. */
183    SVGA_REG_CURSOR_X = 25,            /* (Deprecated) */
184    SVGA_REG_CURSOR_Y = 26,            /* (Deprecated) */
185    SVGA_REG_CURSOR_ON = 27,           /* (Deprecated) */
186    SVGA_REG_HOST_BITS_PER_PIXEL = 28, /* (Deprecated) */
187    SVGA_REG_SCRATCH_SIZE = 29,        /* Number of scratch registers */
188    SVGA_REG_MEM_REGS = 30,            /* Number of FIFO registers */
189    SVGA_REG_NUM_DISPLAYS = 31,        /* (Deprecated) */
190    SVGA_REG_PITCHLOCK = 32,           /* Fixed pitch for all modes */
191    SVGA_REG_IRQMASK = 33,             /* Interrupt mask */
192 
193    /* Legacy multi-monitor support */
194    SVGA_REG_NUM_GUEST_DISPLAYS = 34,/* Number of guest displays in X/Y direction */
195    SVGA_REG_DISPLAY_ID = 35,        /* Display ID for the following display attributes */
196    SVGA_REG_DISPLAY_IS_PRIMARY = 36,/* Whether this is a primary display */
197    SVGA_REG_DISPLAY_POSITION_X = 37,/* The display position x */
198    SVGA_REG_DISPLAY_POSITION_Y = 38,/* The display position y */
199    SVGA_REG_DISPLAY_WIDTH = 39,     /* The display's width */
200    SVGA_REG_DISPLAY_HEIGHT = 40,    /* The display's height */
201 
202    /* See "Guest memory regions" below. */
203    SVGA_REG_GMR_ID = 41,
204    SVGA_REG_GMR_DESCRIPTOR = 42,
205    SVGA_REG_GMR_MAX_IDS = 43,
206    SVGA_REG_GMR_MAX_DESCRIPTOR_LENGTH = 44,
207 
208    SVGA_REG_TRACES = 45,            /* Enable trace-based updates even when FIFO is on */
209    SVGA_REG_GMRS_MAX_PAGES = 46,    /* Maximum number of 4KB pages for all GMRs */
210    SVGA_REG_MEMORY_SIZE = 47,       /* Total dedicated device memory excluding FIFO */
211    SVGA_REG_COMMAND_LOW = 48,       /* Lower 32 bits and submits commands */
212    SVGA_REG_COMMAND_HIGH = 49,      /* Upper 32 bits of command buffer PA */
213 
214    /*
215     * Max primary memory.
216     * See SVGA_CAP_NO_BB_RESTRICTION.
217     */
218    SVGA_REG_MAX_PRIMARY_MEM = 50,
219    SVGA_REG_MAX_PRIMARY_BOUNDING_BOX_MEM = 50,
220 
221    /*
222     * Legacy version of SVGA_REG_GBOBJECT_MEM_SIZE_KB for drivers that
223     * don't know how to convert to a 64-bit byte value without overflowing.
224     * (See SVGA_REG_GBOBJECT_MEM_SIZE_KB).
225     */
226    SVGA_REG_SUGGESTED_GBOBJECT_MEM_SIZE_KB = 51,
227 
228    SVGA_REG_DEV_CAP = 52,           /* Write dev cap index, read value */
229    SVGA_REG_CMD_PREPEND_LOW = 53,
230    SVGA_REG_CMD_PREPEND_HIGH = 54,
231    SVGA_REG_SCREENTARGET_MAX_WIDTH = 55,
232    SVGA_REG_SCREENTARGET_MAX_HEIGHT = 56,
233    SVGA_REG_MOB_MAX_SIZE = 57,
234    SVGA_REG_BLANK_SCREEN_TARGETS = 58,
235    SVGA_REG_CAP2 = 59,
236    SVGA_REG_DEVEL_CAP = 60,
237 
238    /*
239     * Allow the guest to hint to the device which driver is running.
240     *
241     * This should not generally change device behavior, but might be
242     * convenient to work-around specific bugs in guest drivers.
243     *
244     * Drivers should first write their id value into SVGA_REG_GUEST_DRIVER_ID,
245     * and then fill out all of the version registers that they have defined.
246     *
247     * After the driver has written all of the registers, they should
248     * then write the value SVGA_REG_GUEST_DRIVER_ID_SUBMIT to the
249     * SVGA_REG_GUEST_DRIVER_ID register, to signal that they have finished.
250     *
251     * The SVGA_REG_GUEST_DRIVER_ID values are defined below by the
252     * SVGARegGuestDriverId enum.
253     *
254     * The SVGA_REG_GUEST_DRIVER_VERSION fields are driver-specific,
255     * but ideally should encode a monotonically increasing number that allows
256     * the device to perform inequality checks against ranges of driver versions.
257     */
258    SVGA_REG_GUEST_DRIVER_ID = 61,
259    SVGA_REG_GUEST_DRIVER_VERSION1 = 62,
260    SVGA_REG_GUEST_DRIVER_VERSION2 = 63,
261    SVGA_REG_GUEST_DRIVER_VERSION3 = 64,
262    SVGA_REG_CURSOR_MOBID = 65,
263    SVGA_REG_CURSOR_MAX_BYTE_SIZE = 66,
264    SVGA_REG_CURSOR_MAX_DIMENSION = 67,
265 
266    SVGA_REG_FIFO_CAPS = 68,
267    SVGA_REG_FENCE = 69,
268 
269    SVGA_REG_RESERVED1 = 70,
270    SVGA_REG_RESERVED2 = 71,
271    SVGA_REG_RESERVED3 = 72,
272    SVGA_REG_RESERVED4 = 73,
273    SVGA_REG_RESERVED5 = 74,
274    SVGA_REG_SCREENDMA = 75,
275 
276    /*
277     * The maximum amount of guest-backed objects that the device can have
278     * resident at a time. Guest-drivers should keep their working set size
279     * below this limit for best performance.
280     *
281     * Note that this value is in kilobytes, and not bytes, because the actual
282     * number of bytes might be larger than can fit in a 32-bit register.
283     *
284     * PLEASE USE A 64-BIT VALUE WHEN CONVERTING THIS INTO BYTES.
285     * (See SVGA_REG_SUGGESTED_GBOBJECT_MEM_SIZE_KB).
286     */
287    SVGA_REG_GBOBJECT_MEM_SIZE_KB = 76,
288 
289    SVGA_REG_TOP = 77,               /* Must be 1 more than the last register */
290 
291    SVGA_PALETTE_BASE = 1024,        /* Base of SVGA color map */
292    /* Next 768 (== 256*3) registers exist for colormap */
293    SVGA_SCRATCH_BASE = SVGA_PALETTE_BASE + SVGA_NUM_PALETTE_REGS
294                                     /* Base of scratch registers */
295    /* Next reg[SVGA_REG_SCRATCH_SIZE] registers exist for scratch usage:
296       First 4 are reserved for VESA BIOS Extension; any remaining are for
297       the use of the current SVGA driver. */
298 };
299 
300 
301 /*
302  * Values for SVGA_REG_GUEST_DRIVER_ID.
303  */
304 typedef enum SVGARegGuestDriverId {
305    SVGA_REG_GUEST_DRIVER_ID_UNKNOWN = 0,
306    SVGA_REG_GUEST_DRIVER_ID_WDDM    = 1,
307    SVGA_REG_GUEST_DRIVER_ID_LINUX   = 2,
308    SVGA_REG_GUEST_DRIVER_ID_MAX,
309 
310    SVGA_REG_GUEST_DRIVER_ID_SUBMIT  = MAX_UINT32,
311 } SVGARegGuestDriverId;
312 
313 
314 /*
315  * Guest memory regions (GMRs):
316  *
317  * This is a new memory mapping feature available in SVGA devices
318  * which have the SVGA_CAP_GMR bit set. Previously, there were two
319  * fixed memory regions available with which to share data between the
320  * device and the driver: the FIFO ('MEM') and the framebuffer. GMRs
321  * are our name for an extensible way of providing arbitrary DMA
322  * buffers for use between the driver and the SVGA device. They are a
323  * new alternative to framebuffer memory, usable for both 2D and 3D
324  * graphics operations.
325  *
326  * Since GMR mapping must be done synchronously with guest CPU
327  * execution, we use a new pair of SVGA registers:
328  *
329  *   SVGA_REG_GMR_ID --
330  *
331  *     Read/write.
332  *     This register holds the 32-bit ID (a small positive integer)
333  *     of a GMR to create, delete, or redefine. Writing this register
334  *     has no side-effects.
335  *
336  *   SVGA_REG_GMR_DESCRIPTOR --
337  *
338  *     Write-only.
339  *     Writing this register will create, delete, or redefine the GMR
340  *     specified by the above ID register. If this register is zero,
341  *     the GMR is deleted. Any pointers into this GMR (including those
342  *     currently being processed by FIFO commands) will be
343  *     synchronously invalidated.
344  *
345  *     If this register is nonzero, it must be the physical page
346  *     number (PPN) of a data structure which describes the physical
347  *     layout of the memory region this GMR should describe. The
348  *     descriptor structure will be read synchronously by the SVGA
349  *     device when this register is written. The descriptor need not
350  *     remain allocated for the lifetime of the GMR.
351  *
352  *     The guest driver should write SVGA_REG_GMR_ID first, then
353  *     SVGA_REG_GMR_DESCRIPTOR.
354  *
355  *   SVGA_REG_GMR_MAX_IDS --
356  *
357  *     Read-only.
358  *     The SVGA device may choose to support a maximum number of
359  *     user-defined GMR IDs. This register holds the number of supported
360  *     IDs. (The maximum supported ID plus 1)
361  *
362  *   SVGA_REG_GMR_MAX_DESCRIPTOR_LENGTH --
363  *
364  *     Read-only.
365  *     The SVGA device may choose to put a limit on the total number
366  *     of SVGAGuestMemDescriptor structures it will read when defining
367  *     a single GMR.
368  *
369  * The descriptor structure is an array of SVGAGuestMemDescriptor
370  * structures. Each structure may do one of three things:
371  *
372  *   - Terminate the GMR descriptor list.
373  *     (ppn==0, numPages==0)
374  *
375  *   - Add a PPN or range of PPNs to the GMR's virtual address space.
376  *     (ppn != 0, numPages != 0)
377  *
378  *   - Provide the PPN of the next SVGAGuestMemDescriptor, in order to
379  *     support multi-page GMR descriptor tables without forcing the
380  *     driver to allocate physically contiguous memory.
381  *     (ppn != 0, numPages == 0)
382  *
383  * Note that each physical page of SVGAGuestMemDescriptor structures
384  * can describe at least 2MB of guest memory. If the driver needs to
385  * use more than one page of descriptor structures, it must use one of
386  * its SVGAGuestMemDescriptors to point to an additional page.  The
387  * device will never automatically cross a page boundary.
388  *
389  * Once the driver has described a GMR, it is immediately available
390  * for use via any FIFO command that uses an SVGAGuestPtr structure.
391  * These pointers include a GMR identifier plus an offset into that
392  * GMR.
393  *
394  * The driver must check the SVGA_CAP_GMR bit before using the GMR
395  * registers.
396  */
397 
398 /*
399  * Special GMR IDs, allowing SVGAGuestPtrs to point to framebuffer
400  * memory as well.  In the future, these IDs could even be used to
401  * allow legacy memory regions to be redefined by the guest as GMRs.
402  *
403  * Using the guest framebuffer (GFB) at BAR1 for general purpose DMA
404  * is being phased out. Please try to use user-defined GMRs whenever
405  * possible.
406  */
407 #define SVGA_GMR_NULL         ((uint32) -1)
408 #define SVGA_GMR_FRAMEBUFFER  ((uint32) -2)  /* Guest Framebuffer (GFB) */
409 
410 typedef
411 #include "vmware_pack_begin.h"
412 struct SVGAGuestMemDescriptor {
413    uint32 ppn;
414    uint32 numPages;
415 }
416 #include "vmware_pack_end.h"
417 SVGAGuestMemDescriptor;
418 
419 typedef
420 #include "vmware_pack_begin.h"
421 struct SVGAGuestPtr {
422    uint32 gmrId;
423    uint32 offset;
424 }
425 #include "vmware_pack_end.h"
426 SVGAGuestPtr;
427 
428 /*
429  * Register based command buffers --
430  *
431  * Provide an SVGA device interface that allows the guest to submit
432  * command buffers to the SVGA device through an SVGA device register.
433  * The metadata for each command buffer is contained in the
434  * SVGACBHeader structure along with the return status codes.
435  *
436  * The SVGA device supports command buffers if
437  * SVGA_CAP_COMMAND_BUFFERS is set in the device caps register.  The
438  * fifo must be enabled for command buffers to be submitted.
439  *
440  * Command buffers are submitted when the guest writing the 64 byte
441  * aligned physical address into the SVGA_REG_COMMAND_LOW and
442  * SVGA_REG_COMMAND_HIGH.  SVGA_REG_COMMAND_HIGH contains the upper 32
443  * bits of the physical address.  SVGA_REG_COMMAND_LOW contains the
444  * lower 32 bits of the physical address, since the command buffer
445  * headers are required to be 64 byte aligned the lower 6 bits are
446  * used for the SVGACBContext value.  Writing to SVGA_REG_COMMAND_LOW
447  * submits the command buffer to the device and queues it for
448  * execution.  The SVGA device supports at least
449  * SVGA_CB_MAX_QUEUED_PER_CONTEXT command buffers that can be queued
450  * per context and if that limit is reached the device will write the
451  * status SVGA_CB_STATUS_QUEUE_FULL to the status value of the command
452  * buffer header synchronously and not raise any IRQs.
453  *
454  * It is invalid to submit a command buffer without a valid physical
455  * address and results are undefined.
456  *
457  * The device guarantees that command buffers of size SVGA_CB_MAX_SIZE
458  * will be supported.  If a larger command buffer is submitted results
459  * are unspecified and the device will either complete the command
460  * buffer or return an error.
461  *
462  * The device guarantees that any individual command in a command
463  * buffer can be up to SVGA_CB_MAX_COMMAND_SIZE in size which is
464  * enough to fit a 64x64 color-cursor definition.  If the command is
465  * too large the device is allowed to process the command or return an
466  * error.
467  *
468  * The device context is a special SVGACBContext that allows for
469  * synchronous register like accesses with the flexibility of
470  * commands.  There is a different command set defined by
471  * SVGADeviceContextCmdId.  The commands in each command buffer is not
472  * allowed to straddle physical pages.
473  *
474  * The offset field which is available starting with the
475  * SVGA_CAP_CMD_BUFFERS_2 cap bit can be set by the guest to bias the
476  * start of command processing into the buffer.  If an error is
477  * encountered the errorOffset will still be relative to the specific
478  * PA, not biased by the offset.  When the command buffer is finished
479  * the guest should not read the offset field as there is no guarantee
480  * what it will set to.
481  *
482  * When the SVGA_CAP_HP_CMD_QUEUE cap bit is set a new command queue
483  * SVGA_CB_CONTEXT_1 is available.  Commands submitted to this queue
484  * will be executed as quickly as possible by the SVGA device
485  * potentially before already queued commands on SVGA_CB_CONTEXT_0.
486  * The SVGA device guarantees that any command buffers submitted to
487  * SVGA_CB_CONTEXT_0 will be executed after any _already_ submitted
488  * command buffers to SVGA_CB_CONTEXT_1.
489  */
490 
491 #define SVGA_CB_MAX_SIZE (512 * 1024)  /* 512 KB */
492 #define SVGA_CB_MAX_QUEUED_PER_CONTEXT 32
493 #define SVGA_CB_MAX_COMMAND_SIZE (32 * 1024) /* 32 KB */
494 
495 #define SVGA_CB_CONTEXT_MASK 0x3f
496 typedef enum {
497    SVGA_CB_CONTEXT_DEVICE = 0x3f,
498    SVGA_CB_CONTEXT_0      = 0x0,
499    SVGA_CB_CONTEXT_1      = 0x1, /* Supported with SVGA_CAP_HP_CMD_QUEUE */
500    SVGA_CB_CONTEXT_MAX    = 0x2,
501 } SVGACBContext;
502 
503 
504 typedef enum {
505    /*
506     * The guest is supposed to write SVGA_CB_STATUS_NONE to the status
507     * field before submitting the command buffer header, the host will
508     * change the value when it is done with the command buffer.
509     */
510    SVGA_CB_STATUS_NONE             = 0,
511 
512    /*
513     * Written by the host when a command buffer completes successfully.
514     * The device raises an IRQ with SVGA_IRQFLAG_COMMAND_BUFFER unless
515     * the SVGA_CB_FLAG_NO_IRQ flag is set.
516     */
517    SVGA_CB_STATUS_COMPLETED        = 1,
518 
519    /*
520     * Written by the host synchronously with the command buffer
521     * submission to indicate the command buffer was not submitted.  No
522     * IRQ is raised.
523     */
524    SVGA_CB_STATUS_QUEUE_FULL       = 2,
525 
526    /*
527     * Written by the host when an error was detected parsing a command
528     * in the command buffer, errorOffset is written to contain the
529     * offset to the first byte of the failing command.  The device
530     * raises the IRQ with both SVGA_IRQFLAG_ERROR and
531     * SVGA_IRQFLAG_COMMAND_BUFFER.  Some of the commands may have been
532     * processed.
533     */
534    SVGA_CB_STATUS_COMMAND_ERROR    = 3,
535 
536    /*
537     * Written by the host if there is an error parsing the command
538     * buffer header.  The device raises the IRQ with both
539     * SVGA_IRQFLAG_ERROR and SVGA_IRQFLAG_COMMAND_BUFFER.  The device
540     * did not processes any of the command buffer.
541     */
542    SVGA_CB_STATUS_CB_HEADER_ERROR  = 4,
543 
544    /*
545     * Written by the host if the guest requested the host to preempt
546     * the command buffer.  The device will not raise any IRQs and the
547     * command buffer was not processed.
548     */
549    SVGA_CB_STATUS_PREEMPTED        = 5,
550 
551    /*
552     * Written by the host synchronously with the command buffer
553     * submission to indicate the the command buffer was not submitted
554     * due to an error.  No IRQ is raised.
555     */
556    SVGA_CB_STATUS_SUBMISSION_ERROR = 6,
557 
558    /*
559     * Written by the host when the host finished a
560     * SVGA_DC_CMD_ASYNC_STOP_QUEUE request for this command buffer
561     * queue.  The offset of the first byte not processed is stored in
562     * the errorOffset field of the command buffer header.  All guest
563     * visible side effects of commands till that point are guaranteed
564     * to be finished before this is written.  The
565     * SVGA_IRQFLAG_COMMAND_BUFFER IRQ is raised as long as the
566     * SVGA_CB_FLAG_NO_IRQ is not set.
567     */
568    SVGA_CB_STATUS_PARTIAL_COMPLETE = 7,
569 } SVGACBStatus;
570 
571 typedef enum {
572    SVGA_CB_FLAG_NONE       = 0,
573    SVGA_CB_FLAG_NO_IRQ     = 1 << 0,
574    SVGA_CB_FLAG_DX_CONTEXT = 1 << 1,
575    SVGA_CB_FLAG_MOB        = 1 << 2,
576 } SVGACBFlags;
577 
578 typedef
579 #include "vmware_pack_begin.h"
580 struct {
581    volatile SVGACBStatus status; /* Modified by device. */
582    volatile uint32 errorOffset;  /* Modified by device. */
583    uint64 id;
584    SVGACBFlags flags;
585    uint32 length;
586    union {
587       PA pa;
588       struct {
589          SVGAMobId mobid;
590          uint32 mobOffset;
591       } mob;
592    } ptr;
593    uint32 offset; /* Valid if CMD_BUFFERS_2 cap set, must be zero otherwise,
594                    * modified by device.
595                    */
596    uint32 dxContext; /* Valid if DX_CONTEXT flag set, must be zero otherwise */
597    uint32 mustBeZero[6];
598 }
599 #include "vmware_pack_end.h"
600 SVGACBHeader;
601 
602 typedef enum {
603    SVGA_DC_CMD_NOP                   = 0,
604    SVGA_DC_CMD_START_STOP_CONTEXT    = 1,
605    SVGA_DC_CMD_PREEMPT               = 2,
606    SVGA_DC_CMD_START_QUEUE           = 3, /* Requires SVGA_CAP_HP_CMD_QUEUE */
607    SVGA_DC_CMD_ASYNC_STOP_QUEUE      = 4, /* Requires SVGA_CAP_HP_CMD_QUEUE */
608    SVGA_DC_CMD_EMPTY_CONTEXT_QUEUE   = 5, /* Requires SVGA_CAP_HP_CMD_QUEUE */
609    SVGA_DC_CMD_MAX                   = 6,
610 } SVGADeviceContextCmdId;
611 
612 /*
613  * Starts or stops both SVGA_CB_CONTEXT_0 and SVGA_CB_CONTEXT_1.
614  */
615 
616 typedef struct SVGADCCmdStartStop {
617    uint32 enable;
618    SVGACBContext context; /* Must be zero */
619 } SVGADCCmdStartStop;
620 
621 /*
622  * SVGADCCmdPreempt --
623  *
624  * This command allows the guest to request that all command buffers
625  * on SVGA_CB_CONTEXT_0 be preempted that can be.  After execution
626  * of this command all command buffers that were preempted will
627  * already have SVGA_CB_STATUS_PREEMPTED written into the status
628  * field.  The device might still be processing a command buffer,
629  * assuming execution of it started before the preemption request was
630  * received.  Specifying the ignoreIDZero flag to TRUE will cause the
631  * device to not preempt command buffers with the id field in the
632  * command buffer header set to zero.
633  */
634 
635 typedef struct SVGADCCmdPreempt {
636    SVGACBContext context; /* Must be zero */
637    uint32 ignoreIDZero;
638 } SVGADCCmdPreempt;
639 
640 /*
641  * Starts the requested command buffer processing queue.  Valid only
642  * if the SVGA_CAP_HP_CMD_QUEUE cap is set.
643  *
644  * For a command queue to be considered runnable it must be enabled
645  * and any corresponding higher priority queues must also be enabled.
646  * For example in order for command buffers to be processed on
647  * SVGA_CB_CONTEXT_0 both SVGA_CB_CONTEXT_0 and SVGA_CB_CONTEXT_1 must
648  * be enabled.  But for commands to be runnable on SVGA_CB_CONTEXT_1
649  * only that queue must be enabled.
650  */
651 
652 typedef struct SVGADCCmdStartQueue {
653    SVGACBContext context;
654 } SVGADCCmdStartQueue;
655 
656 /*
657  * Requests the SVGA device to stop processing the requested command
658  * buffer queue as soon as possible.  The guest knows the stop has
659  * completed when one of the following happens.
660  *
661  * 1) A command buffer status of SVGA_CB_STATUS_PARTIAL_COMPLETE is returned
662  * 2) A command buffer error is encountered with would stop the queue
663  *    regardless of the async stop request.
664  * 3) All command buffers that have been submitted complete successfully.
665  * 4) The stop completes synchronously if no command buffers are
666  *    active on the queue when it is issued.
667  *
668  * If the command queue is not in a runnable state there is no
669  * guarentee this async stop will finish.  For instance if the high
670  * priority queue is not enabled and a stop is requested on the low
671  * priority queue, the high priority queue must be reenabled to
672  * guarantee that the async stop will finish.
673  *
674  * This command along with SVGA_DC_CMD_EMPTY_CONTEXT_QUEUE can be used
675  * to implement mid command buffer preemption.
676  *
677  * Valid only if the SVGA_CAP_HP_CMD_QUEUE cap is set.
678  */
679 
680 typedef struct SVGADCCmdAsyncStopQueue {
681    SVGACBContext context;
682 } SVGADCCmdAsyncStopQueue;
683 
684 /*
685  * Requests the SVGA device to throw away any full command buffers on
686  * the requested command queue that have not been started.  For a
687  * driver to know which command buffers were thrown away a driver
688  * should only issue this command when the queue is stopped, for
689  * whatever reason.
690  */
691 
692 typedef struct SVGADCCmdEmptyQueue {
693    SVGACBContext context;
694 } SVGADCCmdEmptyQueue;
695 
696 
697 /*
698  * SVGAGMRImageFormat --
699  *
700  *    This is a packed representation of the source 2D image format
701  *    for a GMR-to-screen blit. Currently it is defined as an encoding
702  *    of the screen's color depth and bits-per-pixel, however, 16 bits
703  *    are reserved for future use to identify other encodings (such as
704  *    RGBA or higher-precision images).
705  *
706  *    Currently supported formats:
707  *
708  *       bpp depth  Format Name
709  *       --- -----  -----------
710  *        32    24  32-bit BGRX
711  *        24    24  24-bit BGR
712  *        16    16  RGB 5-6-5
713  *        16    15  RGB 5-5-5
714  *
715  */
716 
717 typedef struct SVGAGMRImageFormat {
718    union {
719       struct {
720          uint32 bitsPerPixel : 8;
721          uint32 colorDepth   : 8;
722          uint32 reserved     : 16;  /* Must be zero */
723       };
724 
725       uint32 value;
726    };
727 } SVGAGMRImageFormat;
728 
729 typedef
730 #include "vmware_pack_begin.h"
731 struct SVGAGuestImage {
732    SVGAGuestPtr         ptr;
733 
734    /*
735     * A note on interpretation of pitch: This value of pitch is the
736     * number of bytes between vertically adjacent image
737     * blocks. Normally this is the number of bytes between the first
738     * pixel of two adjacent scanlines. With compressed textures,
739     * however, this may represent the number of bytes between
740     * compression blocks rather than between rows of pixels.
741     *
742     * XXX: Compressed textures currently must be tightly packed in guest memory.
743     *
744     * If the image is 1-dimensional, pitch is ignored.
745     *
746     * If 'pitch' is zero, the SVGA3D device calculates a pitch value
747     * assuming each row of blocks is tightly packed.
748     */
749    uint32 pitch;
750 }
751 #include "vmware_pack_end.h"
752 SVGAGuestImage;
753 
754 /*
755  * SVGAColorBGRX --
756  *
757  *    A 24-bit color format (BGRX), which does not depend on the
758  *    format of the legacy guest framebuffer (GFB) or the current
759  *    GMRFB state.
760  */
761 
762 typedef struct SVGAColorBGRX {
763    union {
764       struct {
765          uint32 b : 8;
766          uint32 g : 8;
767          uint32 r : 8;
768 	 uint32 x : 8;  /* Unused */
769       };
770 
771       uint32 value;
772    };
773 } SVGAColorBGRX;
774 
775 
776 /*
777  * SVGASignedRect --
778  * SVGASignedPoint --
779  *
780  *    Signed rectangle and point primitives. These are used by the new
781  *    2D primitives for drawing to Screen Objects, which can occupy a
782  *    signed virtual coordinate space.
783  *
784  *    SVGASignedRect specifies a half-open interval: the (left, top)
785  *    pixel is part of the rectangle, but the (right, bottom) pixel is
786  *    not.
787  */
788 
789 typedef
790 #include "vmware_pack_begin.h"
791 struct {
792    int32  left;
793    int32  top;
794    int32  right;
795    int32  bottom;
796 }
797 #include "vmware_pack_end.h"
798 SVGASignedRect;
799 
800 typedef
801 #include "vmware_pack_begin.h"
802 struct {
803    int32  x;
804    int32  y;
805 }
806 #include "vmware_pack_end.h"
807 SVGASignedPoint;
808 
809 
810 /*
811  * SVGA Device Capabilities
812  *
813  * Note the holes in the bitfield. Missing bits have been deprecated,
814  * and must not be reused. Those capabilities will never be reported
815  * by new versions of the SVGA device.
816  *
817  * SVGA_CAP_IRQMASK --
818  *    Provides device interrupts.  Adds device register SVGA_REG_IRQMASK
819  *    to set interrupt mask and direct I/O port SVGA_IRQSTATUS_PORT to
820  *    set/clear pending interrupts.
821  *
822  * SVGA_CAP_GMR --
823  *    Provides synchronous mapping of guest memory regions (GMR).
824  *    Adds device registers SVGA_REG_GMR_ID, SVGA_REG_GMR_DESCRIPTOR,
825  *    SVGA_REG_GMR_MAX_IDS, and SVGA_REG_GMR_MAX_DESCRIPTOR_LENGTH.
826  *
827  * SVGA_CAP_TRACES --
828  *    Allows framebuffer trace-based updates even when FIFO is enabled.
829  *    Adds device register SVGA_REG_TRACES.
830  *
831  * SVGA_CAP_GMR2 --
832  *    Provides asynchronous commands to define and remap guest memory
833  *    regions.  Adds device registers SVGA_REG_GMRS_MAX_PAGES and
834  *    SVGA_REG_MEMORY_SIZE.
835  *
836  * SVGA_CAP_SCREEN_OBJECT_2 --
837  *    Allow screen object support, and require backing stores from the
838  *    guest for each screen object.
839  *
840  * SVGA_CAP_COMMAND_BUFFERS --
841  *    Enable register based command buffer submission.
842  *
843  * SVGA_CAP_DEAD1 --
844  *    This cap was incorrectly used by old drivers and should not be
845  *    reused.
846  *
847  * SVGA_CAP_CMD_BUFFERS_2 --
848  *    Enable support for the prepend command buffer submision
849  *    registers.  SVGA_REG_CMD_PREPEND_LOW and
850  *    SVGA_REG_CMD_PREPEND_HIGH.
851  *
852  * SVGA_CAP_GBOBJECTS --
853  *    Enable guest-backed objects and surfaces.
854  *
855  * SVGA_CAP_DX --
856  *    Enable support for DX commands, and command buffers in a mob.
857  *
858  * SVGA_CAP_HP_CMD_QUEUE --
859  *    Enable support for the high priority command queue, and the
860  *    ScreenCopy command.
861  *
862  * SVGA_CAP_NO_BB_RESTRICTION --
863  *    Allow ScreenTargets to be defined without regard to the 32-bpp
864  *    bounding-box memory restrictions. ie:
865  *
866  *    The summed memory usage of all screens (assuming they were defined as
867  *    32-bpp) must always be less than the value of the
868  *    SVGA_REG_MAX_PRIMARY_MEM register.
869  *
870  *    If this cap is not present, the 32-bpp bounding box around all screens
871  *    must additionally be under the value of the SVGA_REG_MAX_PRIMARY_MEM
872  *    register.
873  *
874  *    If the cap is present, the bounding box restriction is lifted (and only
875  *    the screen-sum limit applies).
876  *
877  *    (Note that this is a slight lie... there is still a sanity limit on any
878  *     dimension of the topology to be less than SVGA_SCREEN_ROOT_LIMIT, even
879  *     when SVGA_CAP_NO_BB_RESTRICTION is present, but that should be
880  *     large enough to express any possible topology without holes between
881  *     monitors.)
882  *
883  * SVGA_CAP_CAP2_REGISTER --
884  *    If this cap is present, the SVGA_REG_CAP2 register is supported.
885  */
886 
887 #define SVGA_CAP_NONE               0x00000000
888 #define SVGA_CAP_RECT_COPY          0x00000002
889 #define SVGA_CAP_CURSOR             0x00000020
890 #define SVGA_CAP_CURSOR_BYPASS      0x00000040
891 #define SVGA_CAP_CURSOR_BYPASS_2    0x00000080
892 #define SVGA_CAP_8BIT_EMULATION     0x00000100
893 #define SVGA_CAP_ALPHA_CURSOR       0x00000200
894 #define SVGA_CAP_3D                 0x00004000
895 #define SVGA_CAP_EXTENDED_FIFO      0x00008000
896 #define SVGA_CAP_MULTIMON           0x00010000
897 #define SVGA_CAP_PITCHLOCK          0x00020000
898 #define SVGA_CAP_IRQMASK            0x00040000
899 #define SVGA_CAP_DISPLAY_TOPOLOGY   0x00080000
900 #define SVGA_CAP_GMR                0x00100000
901 #define SVGA_CAP_TRACES             0x00200000
902 #define SVGA_CAP_GMR2               0x00400000
903 #define SVGA_CAP_SCREEN_OBJECT_2    0x00800000
904 #define SVGA_CAP_COMMAND_BUFFERS    0x01000000
905 #define SVGA_CAP_DEAD1              0x02000000
906 #define SVGA_CAP_CMD_BUFFERS_2      0x04000000
907 #define SVGA_CAP_GBOBJECTS          0x08000000
908 #define SVGA_CAP_DX                 0x10000000
909 #define SVGA_CAP_HP_CMD_QUEUE       0x20000000
910 #define SVGA_CAP_NO_BB_RESTRICTION  0x40000000
911 #define SVGA_CAP_CAP2_REGISTER      0x80000000
912 
913 /*
914  * The SVGA_REG_CAP2 register is an additional set of SVGA capability bits.
915  *
916  * SVGA_CAP2_GROW_OTABLE --
917  *      Allow the GrowOTable/DXGrowCOTable commands.
918  *
919  * SVGA_CAP2_INTRA_SURFACE_COPY --
920  *      Allow the IntraSurfaceCopy command.
921  *
922  * SVGA_CAP2_DX2 --
923  *      Allow the DefineGBSurface_v3, WholeSurfaceCopy, WriteZeroSurface, and
924  *      HintZeroSurface commands, and the SVGA_REG_GUEST_DRIVER_ID register.
925  *
926  * SVGA_CAP2_GB_MEMSIZE_2 --
927  *      Allow the SVGA_REG_GBOBJECT_MEM_SIZE_KB register.
928  *
929  * SVGA_CAP2_SCREENDMA_REG --
930  *      Allow the SVGA_REG_SCREENDMA register.
931  *
932  * SVGA_CAP2_OTABLE_PTDEPTH_2 --
933  *      Allow 2 level page tables for OTable commands.
934  *
935  * SVGA_CAP2_NON_MS_TO_MS_STRETCHBLT --
936  *      Allow a stretch blt from a non-multisampled surface to a multisampled
937  *      surface.
938  *
939  * SVGA_CAP2_CURSOR_MOB --
940  *      Allow the SVGA_REG_CURSOR_MOBID register.
941  *
942  * SVGA_CAP2_MSHINT --
943  *      Allow the SVGA_REG_MSHINT register.
944  *
945  * SVGA_CAP2_DX3 --
946  *      Allows the DefineGBSurface_v4 command.
947  *      Allows the DXDefineDepthStencilView_v2, DXDefineStreamOutputWithMob,
948  *      and DXBindStreamOutput commands if 3D is also available.
949  *      Allows the DXPredStagingCopy and DXStagingCopy commands if SM41
950  *      is also available.
951  *
952  * SVGA_CAP2_RESERVED --
953  *      Reserve the last bit for extending the SVGA capabilities to some
954  *      future mechanisms.
955  */
956 #define SVGA_CAP2_NONE                    0x00000000
957 #define SVGA_CAP2_GROW_OTABLE             0x00000001
958 #define SVGA_CAP2_INTRA_SURFACE_COPY      0x00000002
959 #define SVGA_CAP2_DX2                     0x00000004
960 #define SVGA_CAP2_GB_MEMSIZE_2            0x00000008
961 #define SVGA_CAP2_SCREENDMA_REG           0x00000010
962 #define SVGA_CAP2_OTABLE_PTDEPTH_2        0x00000020
963 #define SVGA_CAP2_NON_MS_TO_MS_STRETCHBLT 0x00000040
964 #define SVGA_CAP2_CURSOR_MOB              0x00000080
965 #define SVGA_CAP2_MSHINT                  0x00000100
966 #define SVGA_CAP2_DX3                     0x00000400
967 #define SVGA_CAP2_RESERVED                0x80000000
968 
969 
970 /*
971  * The Guest can optionally read some SVGA device capabilities through
972  * the backdoor with command BDOOR_CMD_GET_SVGA_CAPABILITIES before
973  * the SVGA device is initialized.  The type of capability the guest
974  * is requesting from the SVGABackdoorCapType enum should be placed in
975  * the upper 16 bits of the backdoor command id (ECX).  On success the
976  * the value of EBX will be set to BDOOR_MAGIC and EAX will be set to
977  * the requested capability.  If the command is not supported then EBX
978  * will be left unchanged and EAX will be set to -1.  Because it is
979  * possible that -1 is the value of the requested cap the correct way
980  * to check if the command was successful is to check if EBX was changed
981  * to BDOOR_MAGIC making sure to initialize the register to something
982  * else first.
983  */
984 
985 typedef enum {
986    SVGABackdoorCapDeviceCaps = 0,
987    SVGABackdoorCapFifoCaps = 1,
988    SVGABackdoorCap3dHWVersion = 2,
989    SVGABackdoorCapDeviceCaps2 = 3,
990    SVGABackdoorCapDevelCaps = 4,
991    SVGABackdoorDevelRenderer = 5,
992    SVGABackdoorCapMax = 6,
993 } SVGABackdoorCapType;
994 
995 
996 /*
997  * FIFO register indices.
998  *
999  * The FIFO is a chunk of device memory mapped into guest physmem.  It
1000  * is always treated as 32-bit words.
1001  *
1002  * The guest driver gets to decide how to partition it between
1003  * - FIFO registers (there are always at least 4, specifying where the
1004  *   following data area is and how much data it contains; there may be
1005  *   more registers following these, depending on the FIFO protocol
1006  *   version in use)
1007  * - FIFO data, written by the guest and slurped out by the VMX.
1008  * These indices are 32-bit word offsets into the FIFO.
1009  */
1010 
1011 enum {
1012    /*
1013     * Block 1 (basic registers): The originally defined FIFO registers.
1014     * These exist and are valid for all versions of the FIFO protocol.
1015     */
1016 
1017    SVGA_FIFO_MIN = 0,
1018    SVGA_FIFO_MAX,       /* The distance from MIN to MAX must be at least 10K */
1019    SVGA_FIFO_NEXT_CMD,
1020    SVGA_FIFO_STOP,
1021 
1022    /*
1023     * Block 2 (extended registers): Mandatory registers for the extended
1024     * FIFO.  These exist if the SVGA caps register includes
1025     * SVGA_CAP_EXTENDED_FIFO; some of them are valid only if their
1026     * associated capability bit is enabled.
1027     *
1028     * Note that when originally defined, SVGA_CAP_EXTENDED_FIFO implied
1029     * support only for (FIFO registers) CAPABILITIES, FLAGS, and FENCE.
1030     * This means that the guest has to test individually (in most cases
1031     * using FIFO caps) for the presence of registers after this; the VMX
1032     * can define "extended FIFO" to mean whatever it wants, and currently
1033     * won't enable it unless there's room for that set and much more.
1034     */
1035 
1036    SVGA_FIFO_CAPABILITIES = 4,
1037    SVGA_FIFO_FLAGS,
1038    /* Valid with SVGA_FIFO_CAP_FENCE: */
1039    SVGA_FIFO_FENCE,
1040 
1041    /*
1042     * Block 3a (optional extended registers): Additional registers for the
1043     * extended FIFO, whose presence isn't actually implied by
1044     * SVGA_CAP_EXTENDED_FIFO; these exist if SVGA_FIFO_MIN is high enough to
1045     * leave room for them.
1046     *
1047     * These in block 3a, the VMX currently considers mandatory for the
1048     * extended FIFO.
1049     */
1050 
1051    /* Valid if exists (i.e. if extended FIFO enabled): */
1052    SVGA_FIFO_3D_HWVERSION,       /* See SVGA3dHardwareVersion in svga3d_reg.h */
1053    /* Valid with SVGA_FIFO_CAP_PITCHLOCK: */
1054    SVGA_FIFO_PITCHLOCK,
1055 
1056    /* Valid with SVGA_FIFO_CAP_CURSOR_BYPASS_3: */
1057    SVGA_FIFO_CURSOR_ON,          /* Cursor bypass 3 show/hide register */
1058    SVGA_FIFO_CURSOR_X,           /* Cursor bypass 3 x register */
1059    SVGA_FIFO_CURSOR_Y,           /* Cursor bypass 3 y register */
1060    SVGA_FIFO_CURSOR_COUNT,       /* Incremented when any of the other 3 change */
1061    SVGA_FIFO_CURSOR_LAST_UPDATED,/* Last time the host updated the cursor */
1062 
1063    /* Valid with SVGA_FIFO_CAP_RESERVE: */
1064    SVGA_FIFO_RESERVED,           /* Bytes past NEXT_CMD with real contents */
1065 
1066    /*
1067     * Valid with SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2:
1068     *
1069     * By default this is SVGA_ID_INVALID, to indicate that the cursor
1070     * coordinates are specified relative to the virtual root. If this
1071     * is set to a specific screen ID, cursor position is reinterpreted
1072     * as a signed offset relative to that screen's origin.
1073     */
1074    SVGA_FIFO_CURSOR_SCREEN_ID,
1075 
1076    /*
1077     * Valid with SVGA_FIFO_CAP_DEAD
1078     *
1079     * An arbitrary value written by the host, drivers should not use it.
1080     */
1081    SVGA_FIFO_DEAD,
1082 
1083    /*
1084     * Valid with SVGA_FIFO_CAP_3D_HWVERSION_REVISED:
1085     *
1086     * Contains 3D HWVERSION (see SVGA3dHardwareVersion in svga3d_reg.h)
1087     * on platforms that can enforce graphics resource limits.
1088     */
1089    SVGA_FIFO_3D_HWVERSION_REVISED,
1090 
1091    /*
1092     * XXX: The gap here, up until SVGA_FIFO_3D_CAPS, can be used for new
1093     * registers, but this must be done carefully and with judicious use of
1094     * capability bits, since comparisons based on SVGA_FIFO_MIN aren't
1095     * enough to tell you whether the register exists: we've shipped drivers
1096     * and products that used SVGA_FIFO_3D_CAPS but didn't know about some of
1097     * the earlier ones.  The actual order of introduction was:
1098     * - PITCHLOCK
1099     * - 3D_CAPS
1100     * - CURSOR_* (cursor bypass 3)
1101     * - RESERVED
1102     * So, code that wants to know whether it can use any of the
1103     * aforementioned registers, or anything else added after PITCHLOCK and
1104     * before 3D_CAPS, needs to reason about something other than
1105     * SVGA_FIFO_MIN.
1106     */
1107 
1108    /*
1109     * 3D caps block space; valid with 3D hardware version >=
1110     * SVGA3D_HWVERSION_WS6_B1.
1111     */
1112    SVGA_FIFO_3D_CAPS      = 32,
1113    SVGA_FIFO_3D_CAPS_LAST = 32 + 255,
1114 
1115    /*
1116     * End of VMX's current definition of "extended-FIFO registers".
1117     * Registers before here are always enabled/disabled as a block; either
1118     * the extended FIFO is enabled and includes all preceding registers, or
1119     * it's disabled entirely.
1120     *
1121     * Block 3b (truly optional extended registers): Additional registers for
1122     * the extended FIFO, which the VMX already knows how to enable and
1123     * disable with correct granularity.
1124     *
1125     * Registers after here exist if and only if the guest SVGA driver
1126     * sets SVGA_FIFO_MIN high enough to leave room for them.
1127     */
1128 
1129    /* Valid if register exists: */
1130    SVGA_FIFO_GUEST_3D_HWVERSION, /* Guest driver's 3D version */
1131    SVGA_FIFO_FENCE_GOAL,         /* Matching target for SVGA_IRQFLAG_FENCE_GOAL */
1132    SVGA_FIFO_BUSY,               /* See "FIFO Synchronization Registers" */
1133 
1134    /*
1135     * Always keep this last.  This defines the maximum number of
1136     * registers we know about.  At power-on, this value is placed in
1137     * the SVGA_REG_MEM_REGS register, and we expect the guest driver
1138     * to allocate this much space in FIFO memory for registers.
1139     */
1140     SVGA_FIFO_NUM_REGS
1141 };
1142 
1143 
1144 /*
1145  * Definition of registers included in extended FIFO support.
1146  *
1147  * The guest SVGA driver gets to allocate the FIFO between registers
1148  * and data.  It must always allocate at least 4 registers, but old
1149  * drivers stopped there.
1150  *
1151  * The VMX will enable extended FIFO support if and only if the guest
1152  * left enough room for all registers defined as part of the mandatory
1153  * set for the extended FIFO.
1154  *
1155  * Note that the guest drivers typically allocate the FIFO only at
1156  * initialization time, not at mode switches, so it's likely that the
1157  * number of FIFO registers won't change without a reboot.
1158  *
1159  * All registers less than this value are guaranteed to be present if
1160  * svgaUser->fifo.extended is set. Any later registers must be tested
1161  * individually for compatibility at each use (in the VMX).
1162  *
1163  * This value is used only by the VMX, so it can change without
1164  * affecting driver compatibility; keep it that way?
1165  */
1166 #define SVGA_FIFO_EXTENDED_MANDATORY_REGS  (SVGA_FIFO_3D_CAPS_LAST + 1)
1167 
1168 
1169 /*
1170  * FIFO Synchronization Registers
1171  *
1172  *  SVGA_REG_SYNC --
1173  *
1174  *       The SYNC register can be used by the guest driver to signal to the
1175  *       device that the guest driver is waiting for previously submitted
1176  *       commands to complete.
1177  *
1178  *       When the guest driver writes to the SYNC register, the device sets
1179  *       the BUSY register to TRUE, and starts processing the submitted commands
1180  *       (if it was not already doing so).  When all previously submitted
1181  *       commands are finished and the device is idle again, it sets the BUSY
1182  *       register back to FALSE.  (If the guest driver submits new commands
1183  *       after writing the SYNC register, the new commands are not guaranteed
1184  *       to have been procesesd.)
1185  *
1186  *       When guest drivers are submitting commands using the FIFO, the device
1187  *       periodically polls to check for new FIFO commands when idle, which may
1188  *       introduce a delay in command processing.  If the guest-driver wants
1189  *       the commands to be processed quickly (which it typically does), it
1190  *       should write SYNC after each batch of commands is committed to the
1191  *       FIFO to immediately wake up the device.  For even better performance,
1192  *       the guest can use the SVGA_FIFO_BUSY register to avoid these extra
1193  *       SYNC writes if the device is already active, using the technique known
1194  *       as "Ringing the Doorbell" (described below).  (Note that command
1195  *       buffer submission implicitly wakes up the device, and so doesn't
1196  *       suffer from this problem.)
1197  *
1198  *       The SYNC register can also be used in combination with BUSY to
1199  *       synchronously ensure that all SVGA commands are processed (with both
1200  *       the FIFO and command-buffers).  To do this, the guest driver should
1201  *       write to SYNC, and then loop reading BUSY until BUSY returns FALSE.
1202  *       This technique is known as a "Legacy Sync".
1203  *
1204  *  SVGA_REG_BUSY --
1205  *
1206  *       This register is set to TRUE when SVGA_REG_SYNC is written,
1207  *       and is set back to FALSE when the device has finished processing
1208  *       all commands and is idle again.
1209  *
1210  *       Every read from the BUSY reigster will block for an undefined
1211  *       amount of time (normally until the device finishes some interesting
1212  *       work unit), or the device is idle.
1213  *
1214  *       Guest drivers can also do a partial Legacy Sync to check for some
1215  *       particular condition, for instance by stopping early when a fence
1216  *       passes before BUSY has been set back to FALSE.  This is particularly
1217  *       useful if the guest-driver knows that it is blocked waiting on the
1218  *       device, because it will yield CPU time back to the host.
1219  *
1220  *  SVGA_FIFO_BUSY --
1221  *
1222  *       The SVGA_FIFO_BUSY register is a fast way for the guest driver to check
1223  *       whether the device is actively processing FIFO commands before writing
1224  *       the more expensive SYNC register.
1225  *
1226  *       If this register reads as TRUE, the device is actively processing
1227  *       FIFO commands.
1228  *
1229  *       If this register reads as FALSE, the device may not be actively
1230  *       processing commands, and the guest driver should try
1231  *       "Ringing the Doorbell".
1232  *
1233  *       To Ring the Doorbell, the guest should:
1234  *
1235  *       1. Have already written their batch of commands into the FIFO.
1236  *       2. Check if the SVGA_FIFO_BUSY register is available by reading
1237  *          SVGA_FIFO_MIN.
1238  *       3. Read SVGA_FIFO_BUSY.  If it reads as TRUE, the device is actively
1239  *          processing FIFO commands, and no further action is necessary.
1240  *       4. If SVGA_FIFO_BUSY was FALSE, write TRUE to SVGA_REG_SYNC.
1241  *
1242  *       For maximum performance, this procedure should be followed after
1243  *       every meaningful batch of commands has been written into the FIFO.
1244  *       (Normally when the underlying application signals it's finished a
1245  *       meaningful work unit by calling Flush.)
1246  */
1247 
1248 
1249 /*
1250  * FIFO Capabilities
1251  *
1252  *      Fence -- Fence register and command are supported
1253  *      Accel Front -- Front buffer only commands are supported
1254  *      Pitch Lock -- Pitch lock register is supported
1255  *      Video -- SVGA Video overlay units are supported
1256  *      Escape -- Escape command is supported
1257  *
1258  * SVGA_FIFO_CAP_SCREEN_OBJECT --
1259  *
1260  *    Provides dynamic multi-screen rendering, for improved Unity and
1261  *    multi-monitor modes. With Screen Object, the guest can
1262  *    dynamically create and destroy 'screens', which can represent
1263  *    Unity windows or virtual monitors. Screen Object also provides
1264  *    strong guarantees that DMA operations happen only when
1265  *    guest-initiated. Screen Object deprecates the BAR1 guest
1266  *    framebuffer (GFB) and all commands that work only with the GFB.
1267  *
1268  *    New registers:
1269  *       FIFO_CURSOR_SCREEN_ID, VIDEO_DATA_GMRID, VIDEO_DST_SCREEN_ID
1270  *
1271  *    New 2D commands:
1272  *       DEFINE_SCREEN, DESTROY_SCREEN, DEFINE_GMRFB, BLIT_GMRFB_TO_SCREEN,
1273  *       BLIT_SCREEN_TO_GMRFB, ANNOTATION_FILL, ANNOTATION_COPY
1274  *
1275  *    New 3D commands:
1276  *       BLIT_SURFACE_TO_SCREEN
1277  *
1278  *    New guarantees:
1279  *
1280  *       - The host will not read or write guest memory, including the GFB,
1281  *         except when explicitly initiated by a DMA command.
1282  *
1283  *       - All DMA, including legacy DMA like UPDATE and PRESENT_READBACK,
1284  *         is guaranteed to complete before any subsequent FENCEs.
1285  *
1286  *       - All legacy commands which affect a Screen (UPDATE, PRESENT,
1287  *         PRESENT_READBACK) as well as new Screen blit commands will
1288  *         all behave consistently as blits, and memory will be read
1289  *         or written in FIFO order.
1290  *
1291  *         For example, if you PRESENT from one SVGA3D surface to multiple
1292  *         places on the screen, the data copied will always be from the
1293  *         SVGA3D surface at the time the PRESENT was issued in the FIFO.
1294  *         This was not necessarily true on devices without Screen Object.
1295  *
1296  *         This means that on devices that support Screen Object, the
1297  *         PRESENT_READBACK command should not be necessary unless you
1298  *         actually want to read back the results of 3D rendering into
1299  *         system memory. (And for that, the BLIT_SCREEN_TO_GMRFB
1300  *         command provides a strict superset of functionality.)
1301  *
1302  *       - When a screen is resized, either using Screen Object commands or
1303  *         legacy multimon registers, its contents are preserved.
1304  *
1305  * SVGA_FIFO_CAP_GMR2 --
1306  *
1307  *    Provides new commands to define and remap guest memory regions (GMR).
1308  *
1309  *    New 2D commands:
1310  *       DEFINE_GMR2, REMAP_GMR2.
1311  *
1312  * SVGA_FIFO_CAP_3D_HWVERSION_REVISED --
1313  *
1314  *    Indicates new register SVGA_FIFO_3D_HWVERSION_REVISED exists.
1315  *    This register may replace SVGA_FIFO_3D_HWVERSION on platforms
1316  *    that enforce graphics resource limits.  This allows the platform
1317  *    to clear SVGA_FIFO_3D_HWVERSION and disable 3D in legacy guest
1318  *    drivers that do not limit their resources.
1319  *
1320  *    Note this is an alias to SVGA_FIFO_CAP_GMR2 because these indicators
1321  *    are codependent (and thus we use a single capability bit).
1322  *
1323  * SVGA_FIFO_CAP_SCREEN_OBJECT_2 --
1324  *
1325  *    Modifies the DEFINE_SCREEN command to include a guest provided
1326  *    backing store in GMR memory and the bytesPerLine for the backing
1327  *    store.  This capability requires the use of a backing store when
1328  *    creating screen objects.  However if SVGA_FIFO_CAP_SCREEN_OBJECT
1329  *    is present then backing stores are optional.
1330  *
1331  * SVGA_FIFO_CAP_DEAD --
1332  *
1333  *    Drivers should not use this cap bit.  This cap bit can not be
1334  *    reused since some hosts already expose it.
1335  */
1336 
1337 #define SVGA_FIFO_CAP_NONE                  0
1338 #define SVGA_FIFO_CAP_FENCE             (1<<0)
1339 #define SVGA_FIFO_CAP_ACCELFRONT        (1<<1)
1340 #define SVGA_FIFO_CAP_PITCHLOCK         (1<<2)
1341 #define SVGA_FIFO_CAP_VIDEO             (1<<3)
1342 #define SVGA_FIFO_CAP_CURSOR_BYPASS_3   (1<<4)
1343 #define SVGA_FIFO_CAP_ESCAPE            (1<<5)
1344 #define SVGA_FIFO_CAP_RESERVE           (1<<6)
1345 #define SVGA_FIFO_CAP_SCREEN_OBJECT     (1<<7)
1346 #define SVGA_FIFO_CAP_GMR2              (1<<8)
1347 #define SVGA_FIFO_CAP_3D_HWVERSION_REVISED  SVGA_FIFO_CAP_GMR2
1348 #define SVGA_FIFO_CAP_SCREEN_OBJECT_2   (1<<9)
1349 #define SVGA_FIFO_CAP_DEAD              (1<<10)
1350 
1351 
1352 /*
1353  * FIFO Flags
1354  *
1355  *      Accel Front -- Driver should use front buffer only commands
1356  */
1357 
1358 #define SVGA_FIFO_FLAG_NONE                 0
1359 #define SVGA_FIFO_FLAG_ACCELFRONT       (1<<0)
1360 #define SVGA_FIFO_FLAG_RESERVED        (1<<31) /* Internal use only */
1361 
1362 /*
1363  * FIFO reservation sentinel value
1364  */
1365 
1366 #define SVGA_FIFO_RESERVED_UNKNOWN      0xffffffff
1367 
1368 
1369 /*
1370  * ScreenDMA Register Values
1371  */
1372 
1373 #define SVGA_SCREENDMA_REG_UNDEFINED    0
1374 #define SVGA_SCREENDMA_REG_NOT_PRESENT  1
1375 #define SVGA_SCREENDMA_REG_PRESENT      2
1376 #define SVGA_SCREENDMA_REG_MAX          3
1377 
1378 /*
1379  * Video overlay support
1380  */
1381 
1382 #define SVGA_NUM_OVERLAY_UNITS 32
1383 
1384 
1385 /*
1386  * Video capabilities that the guest is currently using
1387  */
1388 
1389 #define SVGA_VIDEO_FLAG_COLORKEY        0x0001
1390 
1391 
1392 /*
1393  * Offsets for the video overlay registers
1394  */
1395 
1396 enum {
1397    SVGA_VIDEO_ENABLED = 0,
1398    SVGA_VIDEO_FLAGS,
1399    SVGA_VIDEO_DATA_OFFSET,
1400    SVGA_VIDEO_FORMAT,
1401    SVGA_VIDEO_COLORKEY,
1402    SVGA_VIDEO_SIZE,          /* Deprecated */
1403    SVGA_VIDEO_WIDTH,
1404    SVGA_VIDEO_HEIGHT,
1405    SVGA_VIDEO_SRC_X,
1406    SVGA_VIDEO_SRC_Y,
1407    SVGA_VIDEO_SRC_WIDTH,
1408    SVGA_VIDEO_SRC_HEIGHT,
1409    SVGA_VIDEO_DST_X,         /* Signed int32 */
1410    SVGA_VIDEO_DST_Y,         /* Signed int32 */
1411    SVGA_VIDEO_DST_WIDTH,
1412    SVGA_VIDEO_DST_HEIGHT,
1413    SVGA_VIDEO_PITCH_1,
1414    SVGA_VIDEO_PITCH_2,
1415    SVGA_VIDEO_PITCH_3,
1416    SVGA_VIDEO_DATA_GMRID,    /* Optional, defaults to SVGA_GMR_FRAMEBUFFER */
1417    SVGA_VIDEO_DST_SCREEN_ID, /* Optional, defaults to virtual coords */
1418                              /* (SVGA_ID_INVALID) */
1419    SVGA_VIDEO_NUM_REGS
1420 };
1421 
1422 
1423 /*
1424  * SVGA Overlay Units
1425  *
1426  *      width and height relate to the entire source video frame.
1427  *      srcX, srcY, srcWidth and srcHeight represent subset of the source
1428  *      video frame to be displayed.
1429  */
1430 
1431 typedef
1432 #include "vmware_pack_begin.h"
1433 struct SVGAOverlayUnit {
1434    uint32 enabled;
1435    uint32 flags;
1436    uint32 dataOffset;
1437    uint32 format;
1438    uint32 colorKey;
1439    uint32 size;
1440    uint32 width;
1441    uint32 height;
1442    uint32 srcX;
1443    uint32 srcY;
1444    uint32 srcWidth;
1445    uint32 srcHeight;
1446    int32  dstX;
1447    int32  dstY;
1448    uint32 dstWidth;
1449    uint32 dstHeight;
1450    uint32 pitches[3];
1451    uint32 dataGMRId;
1452    uint32 dstScreenId;
1453 }
1454 #include "vmware_pack_end.h"
1455 SVGAOverlayUnit;
1456 
1457 
1458 /*
1459  * Guest display topology
1460  *
1461  * XXX: This structure is not part of the SVGA device's interface, and
1462  * doesn't really belong here.
1463  */
1464 #define SVGA_INVALID_DISPLAY_ID ((uint32)-1)
1465 
1466 typedef struct SVGADisplayTopology {
1467    uint16 displayId;
1468    uint16 isPrimary;
1469    uint32 width;
1470    uint32 height;
1471    uint32 positionX;
1472    uint32 positionY;
1473 } SVGADisplayTopology;
1474 
1475 
1476 /*
1477  * SVGAScreenObject --
1478  *
1479  *    This is a new way to represent a guest's multi-monitor screen or
1480  *    Unity window. Screen objects are only supported if the
1481  *    SVGA_FIFO_CAP_SCREEN_OBJECT capability bit is set.
1482  *
1483  *    If Screen Objects are supported, they can be used to fully
1484  *    replace the functionality provided by the framebuffer registers
1485  *    (SVGA_REG_WIDTH, HEIGHT, etc.) and by SVGA_CAP_DISPLAY_TOPOLOGY.
1486  *
1487  *    The screen object is a struct with guaranteed binary
1488  *    compatibility. New flags can be added, and the struct may grow,
1489  *    but existing fields must retain their meaning.
1490  *
1491  *    Added with SVGA_FIFO_CAP_SCREEN_OBJECT_2 are required fields of
1492  *    a SVGAGuestPtr that is used to back the screen contents.  This
1493  *    memory must come from the GFB.  The guest is not allowed to
1494  *    access the memory and doing so will have undefined results.  The
1495  *    backing store is required to be page aligned and the size is
1496  *    padded to the next page boundry.  The number of pages is:
1497  *       (bytesPerLine * size.width * 4 + PAGE_SIZE - 1) / PAGE_SIZE
1498  *
1499  *    The pitch in the backingStore is required to be at least large
1500  *    enough to hold a 32bbp scanline.  It is recommended that the
1501  *    driver pad bytesPerLine for a potential performance win.
1502  *
1503  *    The cloneCount field is treated as a hint from the guest that
1504  *    the user wants this display to be cloned, countCount times.  A
1505  *    value of zero means no cloning should happen.
1506  */
1507 
1508 #define SVGA_SCREEN_MUST_BE_SET     (1 << 0)
1509 #define SVGA_SCREEN_HAS_ROOT SVGA_SCREEN_MUST_BE_SET /* Deprecated */
1510 #define SVGA_SCREEN_IS_PRIMARY      (1 << 1)
1511 #define SVGA_SCREEN_FULLSCREEN_HINT (1 << 2)
1512 
1513 /*
1514  * Added with SVGA_FIFO_CAP_SCREEN_OBJECT_2.  When the screen is
1515  * deactivated the base layer is defined to lose all contents and
1516  * become black.  When a screen is deactivated the backing store is
1517  * optional.  When set backingPtr and bytesPerLine will be ignored.
1518  */
1519 #define SVGA_SCREEN_DEACTIVATE  (1 << 3)
1520 
1521 /*
1522  * Added with SVGA_FIFO_CAP_SCREEN_OBJECT_2.  When this flag is set
1523  * the screen contents will be outputted as all black to the user
1524  * though the base layer contents is preserved.  The screen base layer
1525  * can still be read and written to like normal though the no visible
1526  * effect will be seen by the user.  When the flag is changed the
1527  * screen will be blanked or redrawn to the current contents as needed
1528  * without any extra commands from the driver.  This flag only has an
1529  * effect when the screen is not deactivated.
1530  */
1531 #define SVGA_SCREEN_BLANKING (1 << 4)
1532 
1533 typedef
1534 #include "vmware_pack_begin.h"
1535 struct {
1536    uint32 structSize;   /* sizeof(SVGAScreenObject) */
1537    uint32 id;
1538    uint32 flags;
1539    struct {
1540       uint32 width;
1541       uint32 height;
1542    } size;
1543    struct {
1544       int32 x;
1545       int32 y;
1546    } root;
1547 
1548    /*
1549     * Added and required by SVGA_FIFO_CAP_SCREEN_OBJECT_2, optional
1550     * with SVGA_FIFO_CAP_SCREEN_OBJECT.
1551     */
1552    SVGAGuestImage backingStore;
1553 
1554    /*
1555     * The cloneCount field is treated as a hint from the guest that
1556     * the user wants this display to be cloned, cloneCount times.
1557     *
1558     * A value of zero means no cloning should happen.
1559     */
1560    uint32 cloneCount;
1561 }
1562 #include "vmware_pack_end.h"
1563 SVGAScreenObject;
1564 
1565 
1566 /*
1567  *  Commands in the command FIFO:
1568  *
1569  *  Command IDs defined below are used for the traditional 2D FIFO
1570  *  communication (not all commands are available for all versions of the
1571  *  SVGA FIFO protocol).
1572  *
1573  *  Note the holes in the command ID numbers: These commands have been
1574  *  deprecated, and the old IDs must not be reused.
1575  *
1576  *  Command IDs from 1000 to 2999 are reserved for use by the SVGA3D
1577  *  protocol.
1578  *
1579  *  Each command's parameters are described by the comments and
1580  *  structs below.
1581  */
1582 
1583 typedef enum {
1584    SVGA_CMD_INVALID_CMD           = 0,
1585    SVGA_CMD_UPDATE                = 1,
1586    SVGA_CMD_RECT_COPY             = 3,
1587    SVGA_CMD_RECT_ROP_COPY         = 14,
1588    SVGA_CMD_DEFINE_CURSOR         = 19,
1589    SVGA_CMD_DEFINE_ALPHA_CURSOR   = 22,
1590    SVGA_CMD_UPDATE_VERBOSE        = 25,
1591    SVGA_CMD_FRONT_ROP_FILL        = 29,
1592    SVGA_CMD_FENCE                 = 30,
1593    SVGA_CMD_ESCAPE                = 33,
1594    SVGA_CMD_DEFINE_SCREEN         = 34,
1595    SVGA_CMD_DESTROY_SCREEN        = 35,
1596    SVGA_CMD_DEFINE_GMRFB          = 36,
1597    SVGA_CMD_BLIT_GMRFB_TO_SCREEN  = 37,
1598    SVGA_CMD_BLIT_SCREEN_TO_GMRFB  = 38,
1599    SVGA_CMD_ANNOTATION_FILL       = 39,
1600    SVGA_CMD_ANNOTATION_COPY       = 40,
1601    SVGA_CMD_DEFINE_GMR2           = 41,
1602    SVGA_CMD_REMAP_GMR2            = 42,
1603    SVGA_CMD_DEAD                  = 43,
1604    SVGA_CMD_DEAD_2                = 44,
1605    SVGA_CMD_NOP                   = 45,
1606    SVGA_CMD_NOP_ERROR             = 46,
1607    SVGA_CMD_MAX
1608 } SVGAFifoCmdId;
1609 
1610 #define SVGA_CMD_MAX_DATASIZE       (256 * 1024)
1611 #define SVGA_CMD_MAX_ARGS           64
1612 
1613 
1614 /*
1615  * SVGA_CMD_UPDATE --
1616  *
1617  *    This is a DMA transfer which copies from the Guest Framebuffer
1618  *    (GFB) at BAR1 + SVGA_REG_FB_OFFSET to any screens which
1619  *    intersect with the provided virtual rectangle.
1620  *
1621  *    This command does not support using arbitrary guest memory as a
1622  *    data source- it only works with the pre-defined GFB memory.
1623  *    This command also does not support signed virtual coordinates.
1624  *    If you have defined screens (using SVGA_CMD_DEFINE_SCREEN) with
1625  *    negative root x/y coordinates, the negative portion of those
1626  *    screens will not be reachable by this command.
1627  *
1628  *    This command is not necessary when using framebuffer
1629  *    traces. Traces are automatically enabled if the SVGA FIFO is
1630  *    disabled, and you may explicitly enable/disable traces using
1631  *    SVGA_REG_TRACES. With traces enabled, any write to the GFB will
1632  *    automatically act as if a subsequent SVGA_CMD_UPDATE was issued.
1633  *
1634  *    Traces and SVGA_CMD_UPDATE are the only supported ways to render
1635  *    pseudocolor screen updates. The newer Screen Object commands
1636  *    only support true color formats.
1637  *
1638  * Availability:
1639  *    Always available.
1640  */
1641 
1642 typedef
1643 #include "vmware_pack_begin.h"
1644 struct {
1645    uint32 x;
1646    uint32 y;
1647    uint32 width;
1648    uint32 height;
1649 }
1650 #include "vmware_pack_end.h"
1651 SVGAFifoCmdUpdate;
1652 
1653 
1654 /*
1655  * SVGA_CMD_RECT_COPY --
1656  *
1657  *    Perform a rectangular DMA transfer from one area of the GFB to
1658  *    another, and copy the result to any screens which intersect it.
1659  *
1660  * Availability:
1661  *    SVGA_CAP_RECT_COPY
1662  */
1663 
1664 typedef
1665 #include "vmware_pack_begin.h"
1666 struct {
1667    uint32 srcX;
1668    uint32 srcY;
1669    uint32 destX;
1670    uint32 destY;
1671    uint32 width;
1672    uint32 height;
1673 }
1674 #include "vmware_pack_end.h"
1675 SVGAFifoCmdRectCopy;
1676 
1677 
1678 /*
1679  * SVGA_CMD_RECT_ROP_COPY --
1680  *
1681  *    Perform a rectangular DMA transfer from one area of the GFB to
1682  *    another, and copy the result to any screens which intersect it.
1683  *    The value of ROP may only be SVGA_ROP_COPY, and this command is
1684  *    only supported for backwards compatibility reasons.
1685  *
1686  * Availability:
1687  *    SVGA_CAP_RECT_COPY
1688  */
1689 
1690 typedef
1691 #include "vmware_pack_begin.h"
1692 struct {
1693    uint32 srcX;
1694    uint32 srcY;
1695    uint32 destX;
1696    uint32 destY;
1697    uint32 width;
1698    uint32 height;
1699    uint32 rop;
1700 }
1701 #include "vmware_pack_end.h"
1702 SVGAFifoCmdRectRopCopy;
1703 
1704 
1705 /*
1706  * SVGA_CMD_DEFINE_CURSOR --
1707  *
1708  *    Provide a new cursor image, as an AND/XOR mask.
1709  *
1710  *    The recommended way to position the cursor overlay is by using
1711  *    the SVGA_FIFO_CURSOR_* registers, supported by the
1712  *    SVGA_FIFO_CAP_CURSOR_BYPASS_3 capability.
1713  *
1714  * Availability:
1715  *    SVGA_CAP_CURSOR
1716  */
1717 
1718 typedef
1719 #include "vmware_pack_begin.h"
1720 struct {
1721    uint32 id;             /* Reserved, must be zero. */
1722    uint32 hotspotX;
1723    uint32 hotspotY;
1724    uint32 width;
1725    uint32 height;
1726    uint32 andMaskDepth;   /* Value must be 1 or equal to BITS_PER_PIXEL */
1727    uint32 xorMaskDepth;   /* Value must be 1 or equal to BITS_PER_PIXEL */
1728    /*
1729     * Followed by scanline data for AND mask, then XOR mask.
1730     * Each scanline is padded to a 32-bit boundary.
1731    */
1732 }
1733 #include "vmware_pack_end.h"
1734 SVGAFifoCmdDefineCursor;
1735 
1736 
1737 /*
1738  * SVGA_CMD_DEFINE_ALPHA_CURSOR --
1739  *
1740  *    Provide a new cursor image, in 32-bit BGRA format.
1741  *
1742  *    The recommended way to position the cursor overlay is by using
1743  *    the SVGA_FIFO_CURSOR_* registers, supported by the
1744  *    SVGA_FIFO_CAP_CURSOR_BYPASS_3 capability.
1745  *
1746  * Availability:
1747  *    SVGA_CAP_ALPHA_CURSOR
1748  */
1749 
1750 typedef
1751 #include "vmware_pack_begin.h"
1752 struct {
1753    uint32 id;             /* Reserved, must be zero. */
1754    uint32 hotspotX;
1755    uint32 hotspotY;
1756    uint32 width;
1757    uint32 height;
1758    /* Followed by scanline data */
1759 }
1760 #include "vmware_pack_end.h"
1761 SVGAFifoCmdDefineAlphaCursor;
1762 
1763 
1764 /*
1765  *    Provide a new large cursor image, as an AND/XOR mask.
1766  *
1767  *    Should only be used for CursorMob functionality
1768  */
1769 
1770 typedef
1771 #include "vmware_pack_begin.h"
1772 struct {
1773    uint32 hotspotX;
1774    uint32 hotspotY;
1775    uint32 width;
1776    uint32 height;
1777    uint32 andMaskDepth;
1778    uint32 xorMaskDepth;
1779    /*
1780     * Followed by scanline data for AND mask, then XOR mask.
1781     * Each scanline is padded to a 32-bit boundary.
1782    */
1783 }
1784 #include "vmware_pack_end.h"
1785 SVGAGBColorCursorHeader;
1786 
1787 
1788 /*
1789  *    Provide a new large cursor image, in 32-bit BGRA format.
1790  *
1791  *    Should only be used for CursorMob functionality
1792  */
1793 
1794 typedef
1795 #include "vmware_pack_begin.h"
1796 struct {
1797    uint32 hotspotX;
1798    uint32 hotspotY;
1799    uint32 width;
1800    uint32 height;
1801    /* Followed by scanline data */
1802 }
1803 #include "vmware_pack_end.h"
1804 SVGAGBAlphaCursorHeader;
1805 
1806  /*
1807   * Define the SVGA guest backed cursor types
1808   */
1809 
1810 typedef enum {
1811    SVGA_COLOR_CURSOR       = 0,
1812    SVGA_ALPHA_CURSOR       = 1,
1813 } SVGAGBCursorType;
1814 
1815 /*
1816  *    Provide a new large cursor image.
1817  *
1818  *    Should only be used for CursorMob functionality
1819  */
1820 
1821 typedef
1822 #include "vmware_pack_begin.h"
1823 struct {
1824    SVGAGBCursorType type;
1825    union {
1826       SVGAGBColorCursorHeader colorHeader;
1827       SVGAGBAlphaCursorHeader alphaHeader;
1828    } header;
1829    uint32 sizeInBytes;
1830    /*
1831     * Followed by the cursor data
1832     */
1833 }
1834 #include "vmware_pack_end.h"
1835 SVGAGBCursorHeader;
1836 
1837 
1838 /*
1839  * SVGA_CMD_UPDATE_VERBOSE --
1840  *
1841  *    Just like SVGA_CMD_UPDATE, but also provide a per-rectangle
1842  *    'reason' value, an opaque cookie which is used by internal
1843  *    debugging tools. Third party drivers should not use this
1844  *    command.
1845  *
1846  * Availability:
1847  *    SVGA_CAP_EXTENDED_FIFO
1848  */
1849 
1850 typedef
1851 #include "vmware_pack_begin.h"
1852 struct {
1853    uint32 x;
1854    uint32 y;
1855    uint32 width;
1856    uint32 height;
1857    uint32 reason;
1858 }
1859 #include "vmware_pack_end.h"
1860 SVGAFifoCmdUpdateVerbose;
1861 
1862 
1863 /*
1864  * SVGA_CMD_FRONT_ROP_FILL --
1865  *
1866  *    This is a hint which tells the SVGA device that the driver has
1867  *    just filled a rectangular region of the GFB with a solid
1868  *    color. Instead of reading these pixels from the GFB, the device
1869  *    can assume that they all equal 'color'. This is primarily used
1870  *    for remote desktop protocols.
1871  *
1872  * Availability:
1873  *    SVGA_FIFO_CAP_ACCELFRONT
1874  */
1875 
1876 #define  SVGA_ROP_COPY                    0x03
1877 
1878 typedef
1879 #include "vmware_pack_begin.h"
1880 struct {
1881    uint32 color;     /* In the same format as the GFB */
1882    uint32 x;
1883    uint32 y;
1884    uint32 width;
1885    uint32 height;
1886    uint32 rop;       /* Must be SVGA_ROP_COPY */
1887 }
1888 #include "vmware_pack_end.h"
1889 SVGAFifoCmdFrontRopFill;
1890 
1891 
1892 /*
1893  * SVGA_CMD_FENCE --
1894  *
1895  *    Insert a synchronization fence.  When the SVGA device reaches
1896  *    this command, it will copy the 'fence' value into the
1897  *    SVGA_FIFO_FENCE register. It will also compare the fence against
1898  *    SVGA_FIFO_FENCE_GOAL. If the fence matches the goal and the
1899  *    SVGA_IRQFLAG_FENCE_GOAL interrupt is enabled, the device will
1900  *    raise this interrupt.
1901  *
1902  * Availability:
1903  *    SVGA_FIFO_FENCE for this command,
1904  *    SVGA_CAP_IRQMASK for SVGA_FIFO_FENCE_GOAL.
1905  */
1906 
1907 typedef
1908 #include "vmware_pack_begin.h"
1909 struct {
1910    uint32 fence;
1911 }
1912 #include "vmware_pack_end.h"
1913 SVGAFifoCmdFence;
1914 
1915 
1916 /*
1917  * SVGA_CMD_ESCAPE --
1918  *
1919  *    Send an extended or vendor-specific variable length command.
1920  *    This is used for video overlay, third party plugins, and
1921  *    internal debugging tools. See svga_escape.h
1922  *
1923  * Availability:
1924  *    SVGA_FIFO_CAP_ESCAPE
1925  */
1926 
1927 typedef
1928 #include "vmware_pack_begin.h"
1929 struct {
1930    uint32 nsid;
1931    uint32 size;
1932    /* followed by 'size' bytes of data */
1933 }
1934 #include "vmware_pack_end.h"
1935 SVGAFifoCmdEscape;
1936 
1937 
1938 /*
1939  * SVGA_CMD_DEFINE_SCREEN --
1940  *
1941  *    Define or redefine an SVGAScreenObject. See the description of
1942  *    SVGAScreenObject above.  The video driver is responsible for
1943  *    generating new screen IDs. They should be small positive
1944  *    integers. The virtual device will have an implementation
1945  *    specific upper limit on the number of screen IDs
1946  *    supported. Drivers are responsible for recycling IDs. The first
1947  *    valid ID is zero.
1948  *
1949  *    - Interaction with other registers:
1950  *
1951  *    For backwards compatibility, when the GFB mode registers (WIDTH,
1952  *    HEIGHT, PITCHLOCK, BITS_PER_PIXEL) are modified, the SVGA device
1953  *    deletes all screens other than screen #0, and redefines screen
1954  *    #0 according to the specified mode. Drivers that use
1955  *    SVGA_CMD_DEFINE_SCREEN should destroy or redefine screen #0.
1956  *
1957  *    If you use screen objects, do not use the legacy multi-mon
1958  *    registers (SVGA_REG_NUM_GUEST_DISPLAYS, SVGA_REG_DISPLAY_*).
1959  *
1960  * Availability:
1961  *    SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
1962  */
1963 
1964 typedef
1965 #include "vmware_pack_begin.h"
1966 struct {
1967    SVGAScreenObject screen;   /* Variable-length according to version */
1968 }
1969 #include "vmware_pack_end.h"
1970 SVGAFifoCmdDefineScreen;
1971 
1972 
1973 /*
1974  * SVGA_CMD_DESTROY_SCREEN --
1975  *
1976  *    Destroy an SVGAScreenObject. Its ID is immediately available for
1977  *    re-use.
1978  *
1979  * Availability:
1980  *    SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
1981  */
1982 
1983 typedef
1984 #include "vmware_pack_begin.h"
1985 struct {
1986    uint32 screenId;
1987 }
1988 #include "vmware_pack_end.h"
1989 SVGAFifoCmdDestroyScreen;
1990 
1991 
1992 /*
1993  * SVGA_CMD_DEFINE_GMRFB --
1994  *
1995  *    This command sets a piece of SVGA device state called the
1996  *    Guest Memory Region Framebuffer, or GMRFB. The GMRFB is a
1997  *    piece of light-weight state which identifies the location and
1998  *    format of an image in guest memory or in BAR1. The GMRFB has
1999  *    an arbitrary size, and it doesn't need to match the geometry
2000  *    of the GFB or any screen object.
2001  *
2002  *    The GMRFB can be redefined as often as you like. You could
2003  *    always use the same GMRFB, you could redefine it before
2004  *    rendering from a different guest screen, or you could even
2005  *    redefine it before every blit.
2006  *
2007  *    There are multiple ways to use this command. The simplest way is
2008  *    to use it to move the framebuffer either to elsewhere in the GFB
2009  *    (BAR1) memory region, or to a user-defined GMR. This lets a
2010  *    driver use a framebuffer allocated entirely out of normal system
2011  *    memory, which we encourage.
2012  *
2013  *    Another way to use this command is to set up a ring buffer of
2014  *    updates in GFB memory. If a driver wants to ensure that no
2015  *    frames are skipped by the SVGA device, it is important that the
2016  *    driver not modify the source data for a blit until the device is
2017  *    done processing the command. One efficient way to accomplish
2018  *    this is to use a ring of small DMA buffers. Each buffer is used
2019  *    for one blit, then we move on to the next buffer in the
2020  *    ring. The FENCE mechanism is used to protect each buffer from
2021  *    re-use until the device is finished with that buffer's
2022  *    corresponding blit.
2023  *
2024  *    This command does not affect the meaning of SVGA_CMD_UPDATE.
2025  *    UPDATEs always occur from the legacy GFB memory area. This
2026  *    command has no support for pseudocolor GMRFBs. Currently only
2027  *    true-color 15, 16, and 24-bit depths are supported. Future
2028  *    devices may expose capabilities for additional framebuffer
2029  *    formats.
2030  *
2031  *    The default GMRFB value is undefined. Drivers must always send
2032  *    this command at least once before performing any blit from the
2033  *    GMRFB.
2034  *
2035  * Availability:
2036  *    SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
2037  */
2038 
2039 typedef
2040 #include "vmware_pack_begin.h"
2041 struct {
2042    SVGAGuestPtr        ptr;
2043    uint32              bytesPerLine;
2044    SVGAGMRImageFormat  format;
2045 }
2046 #include "vmware_pack_end.h"
2047 SVGAFifoCmdDefineGMRFB;
2048 
2049 
2050 /*
2051  * SVGA_CMD_BLIT_GMRFB_TO_SCREEN --
2052  *
2053  *    This is a guest-to-host blit. It performs a DMA operation to
2054  *    copy a rectangular region of pixels from the current GMRFB to
2055  *    a ScreenObject.
2056  *
2057  *    The destination coordinate may be specified relative to a
2058  *    screen's origin.  The provided screen ID must be valid.
2059  *
2060  *    The SVGA device is guaranteed to finish reading from the GMRFB
2061  *    by the time any subsequent FENCE commands are reached.
2062  *
2063  *    This command consumes an annotation. See the
2064  *    SVGA_CMD_ANNOTATION_* commands for details.
2065  *
2066  * Availability:
2067  *    SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
2068  */
2069 
2070 typedef
2071 #include "vmware_pack_begin.h"
2072 struct {
2073    SVGASignedPoint  srcOrigin;
2074    SVGASignedRect   destRect;
2075    uint32           destScreenId;
2076 }
2077 #include "vmware_pack_end.h"
2078 SVGAFifoCmdBlitGMRFBToScreen;
2079 
2080 
2081 /*
2082  * SVGA_CMD_BLIT_SCREEN_TO_GMRFB --
2083  *
2084  *    This is a host-to-guest blit. It performs a DMA operation to
2085  *    copy a rectangular region of pixels from a single ScreenObject
2086  *    back to the current GMRFB.
2087  *
2088  *    The source coordinate is specified relative to a screen's
2089  *    origin.  The provided screen ID must be valid. If any parameters
2090  *    are invalid, the resulting pixel values are undefined.
2091  *
2092  *    The SVGA device is guaranteed to finish writing to the GMRFB by
2093  *    the time any subsequent FENCE commands are reached.
2094  *
2095  * Availability:
2096  *    SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
2097  */
2098 
2099 typedef
2100 #include "vmware_pack_begin.h"
2101 struct {
2102    SVGASignedPoint  destOrigin;
2103    SVGASignedRect   srcRect;
2104    uint32           srcScreenId;
2105 }
2106 #include "vmware_pack_end.h"
2107 SVGAFifoCmdBlitScreenToGMRFB;
2108 
2109 
2110 /*
2111  * SVGA_CMD_ANNOTATION_FILL --
2112  *
2113  *    The annotation commands have been deprecated, should not be used
2114  *    by new drivers.  They used to provide performance hints to the SVGA
2115  *    device about the content of screen updates, but newer SVGA devices
2116  *    ignore these.
2117  *
2118  * Availability:
2119  *    SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
2120  */
2121 
2122 typedef
2123 #include "vmware_pack_begin.h"
2124 struct {
2125    SVGAColorBGRX  color;
2126 }
2127 #include "vmware_pack_end.h"
2128 SVGAFifoCmdAnnotationFill;
2129 
2130 
2131 /*
2132  * SVGA_CMD_ANNOTATION_COPY --
2133  *
2134  *    The annotation commands have been deprecated, should not be used
2135  *    by new drivers.  They used to provide performance hints to the SVGA
2136  *    device about the content of screen updates, but newer SVGA devices
2137  *    ignore these.
2138  *
2139  * Availability:
2140  *    SVGA_FIFO_CAP_SCREEN_OBJECT or SVGA_FIFO_CAP_SCREEN_OBJECT_2
2141  */
2142 
2143 typedef
2144 #include "vmware_pack_begin.h"
2145 struct {
2146    SVGASignedPoint  srcOrigin;
2147    uint32           srcScreenId;
2148 }
2149 #include "vmware_pack_end.h"
2150 SVGAFifoCmdAnnotationCopy;
2151 
2152 
2153 /*
2154  * SVGA_CMD_DEFINE_GMR2 --
2155  *
2156  *    Define guest memory region v2.  See the description of GMRs above.
2157  *
2158  * Availability:
2159  *    SVGA_CAP_GMR2
2160  */
2161 
2162 typedef
2163 #include "vmware_pack_begin.h"
2164 struct {
2165    uint32 gmrId;
2166    uint32 numPages;
2167 }
2168 #include "vmware_pack_end.h"
2169 SVGAFifoCmdDefineGMR2;
2170 
2171 
2172 /*
2173  * SVGA_CMD_REMAP_GMR2 --
2174  *
2175  *    Remap guest memory region v2.  See the description of GMRs above.
2176  *
2177  *    This command allows guest to modify a portion of an existing GMR by
2178  *    invalidating it or reassigning it to different guest physical pages.
2179  *    The pages are identified by physical page number (PPN).  The pages
2180  *    are assumed to be pinned and valid for DMA operations.
2181  *
2182  *    Description of command flags:
2183  *
2184  *    SVGA_REMAP_GMR2_VIA_GMR: If enabled, references a PPN list in a GMR.
2185  *       The PPN list must not overlap with the remap region (this can be
2186  *       handled trivially by referencing a separate GMR).  If flag is
2187  *       disabled, PPN list is appended to SVGARemapGMR command.
2188  *
2189  *    SVGA_REMAP_GMR2_PPN64: If set, PPN list is in PPN64 format, otherwise
2190  *       it is in PPN32 format.
2191  *
2192  *    SVGA_REMAP_GMR2_SINGLE_PPN: If set, PPN list contains a single entry.
2193  *       A single PPN can be used to invalidate a portion of a GMR or
2194  *       map it to to a single guest scratch page.
2195  *
2196  * Availability:
2197  *    SVGA_CAP_GMR2
2198  */
2199 
2200 typedef enum {
2201    SVGA_REMAP_GMR2_PPN32         = 0,
2202    SVGA_REMAP_GMR2_VIA_GMR       = (1 << 0),
2203    SVGA_REMAP_GMR2_PPN64         = (1 << 1),
2204    SVGA_REMAP_GMR2_SINGLE_PPN    = (1 << 2),
2205 } SVGARemapGMR2Flags;
2206 
2207 typedef
2208 #include "vmware_pack_begin.h"
2209 struct {
2210    uint32 gmrId;
2211    SVGARemapGMR2Flags flags;
2212    uint32 offsetPages; /* offset in pages to begin remap */
2213    uint32 numPages; /* number of pages to remap */
2214    /*
2215     * Followed by additional data depending on SVGARemapGMR2Flags.
2216     *
2217     * If flag SVGA_REMAP_GMR2_VIA_GMR is set, single SVGAGuestPtr follows.
2218     * Otherwise an array of page descriptors in PPN32 or PPN64 format
2219     * (according to flag SVGA_REMAP_GMR2_PPN64) follows.  If flag
2220     * SVGA_REMAP_GMR2_SINGLE_PPN is set, array contains a single entry.
2221     */
2222 }
2223 #include "vmware_pack_end.h"
2224 SVGAFifoCmdRemapGMR2;
2225 
2226 
2227 /*
2228  * Size of SVGA device memory such as frame buffer and FIFO.
2229  */
2230 #define SVGA_VRAM_MIN_SIZE             (4 * 640 * 480) /* bytes */
2231 #define SVGA_VRAM_MIN_SIZE_3D       (16 * 1024 * 1024)
2232 #define SVGA_VRAM_MAX_SIZE         (128 * 1024 * 1024)
2233 #define SVGA_MEMORY_SIZE_MAX      (1024 * 1024 * 1024)
2234 #define SVGA_FIFO_SIZE_MAX           (2 * 1024 * 1024)
2235 #define SVGA_GRAPHICS_MEMORY_KB_MIN     (32 * 1024)
2236 #define SVGA_GRAPHICS_MEMORY_KB_MAX_2GB (2 * 1024 * 1024)
2237 #define SVGA_GRAPHICS_MEMORY_KB_MAX_3GB (3 * 1024 * 1024)
2238 #define SVGA_GRAPHICS_MEMORY_KB_MAX_4GB (4 * 1024 * 1024)
2239 #define SVGA_GRAPHICS_MEMORY_KB_MAX_8GB (8 * 1024 * 1024)
2240 #define SVGA_GRAPHICS_MEMORY_KB_DEFAULT (256 * 1024)
2241 
2242 #define SVGA_VRAM_SIZE_W2K          (64 * 1024 * 1024) /* 64 MB */
2243 
2244 #if defined(VMX86_SERVER)
2245 #define SVGA_VRAM_SIZE               (4 * 1024 * 1024)
2246 #define SVGA_VRAM_SIZE_3D           (64 * 1024 * 1024)
2247 #define SVGA_FIFO_SIZE                    (256 * 1024)
2248 #define SVGA_FIFO_SIZE_3D                 (516 * 1024)
2249 #define SVGA_MEMORY_SIZE_DEFAULT   (160 * 1024 * 1024)
2250 #define SVGA_AUTODETECT_DEFAULT                  FALSE
2251 #else
2252 #define SVGA_VRAM_SIZE              (16 * 1024 * 1024)
2253 #define SVGA_VRAM_SIZE_3D           SVGA_VRAM_MAX_SIZE
2254 #define SVGA_FIFO_SIZE               (2 * 1024 * 1024)
2255 #define SVGA_FIFO_SIZE_3D               SVGA_FIFO_SIZE
2256 #define SVGA_MEMORY_SIZE_DEFAULT   (768 * 1024 * 1024)
2257 #define SVGA_AUTODETECT_DEFAULT                   TRUE
2258 #endif
2259 
2260 #define SVGA_FIFO_SIZE_GBOBJECTS          (256 * 1024)
2261 #define SVGA_VRAM_SIZE_GBOBJECTS     (4 * 1024 * 1024)
2262 
2263 #define SVGA_PCI_REGS_PAGES                        (1)
2264 
2265 #endif
2266