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