Initial revisionXORG-STABLE

1 files changed, 542 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..883d311
--- /dev/null
+++ b/README
@@ -0,0 +1,542 @@
+
+Copyright (C) 1999-2002 VMware, Inc.
+All Rights Reserved
+
+The code here may be used/distributed under the terms of the standard
+XFree86 license.
+
+
+	VMware SVGA Device Interface and Programming Model
+	--------------------------------------------------
+
+
+Include Files
+-------------
+
+svga_reg.h
+    SVGA register definitions, SVGA capabilities, and FIFO command definitions.
+
+svga_limits.h
+    Included by svga_reg.h, defines maximum frame buffer and memory region
+    sizes.
+
+guest_os.h
+    Values for the GUEST_ID register.
+
+vm_basic_types.h
+    Common type definitions.
+
+vm_device_version.h
+    PCI vendor ID's and related information.
+
+
+Programming the VMware SVGA Device
+----------------------------------
+
+1. Reading/writing a register:
+
+    The SVGA registers are addressed by an index/value pair of 32 bit
+    registers in the IO address space.
+    
+    The 0710 VMware SVGA chipset (PCI device ID PCI_DEVICE_ID_VMWARE_SVGA) has
+    its index and value ports hardcoded at:
+    
+    	index: SVGA_LEGACY_BASE_PORT + 4 * SVGA_INDEX_PORT
+    	value: SVGA_LEGACY_BASE_PORT + 4 * SVGA_VALUE_PORT
+    
+    The 0405 VMware SVGA chipset (PCI device ID PCI_DEVICE_ID_VMWARE_SVGA2)
+    determines its index and value ports as a function of the first base
+    address register in its PCI configuration space as:
+
+    	index: <Base Address Register 0> + SVGA_INDEX_PORT
+    	value: <Base Address Register 0> + SVGA_VALUE_PORT
+
+    To read a register:
+	Set the index port to the index of the register, using a dword OUT
+	Do a dword IN from the value port
+
+    To write a register:
+	Set the index port to the index of the register, using a dword OUT
+	Do a dword OUT to the value port
+
+    Example, setting the width to 1024:
+
+	mov	eax, SVGA_REG_WIDTH
+	mov	edx, <SVGA Address Port>
+	out	dx, eax
+    	mov	eax, 1024
+	mov	edx, <SVGA Value Port>
+	out	dx, eax
+
+2. Initialization
+    Check the version number
+     loop:
+      Write into SVGA_REG_ID the maximum SVGA_ID_* the driver supports.
+      Read from SVGA_REG_ID.
+       Check if it is the value you wrote.
+	If yes, VMware SVGA device supports it
+	If no, decrement SVGA_ID_* and goto loop
+     This algorithm converges.
+
+    Map the frame buffer and the command FIFO
+	Read SVGA_REG_FB_START, SVGA_REG_FB_SIZE, SVGA_REG_MEM_START,
+	SVGA_REG_MEM_SIZE.
+	Map the frame buffer (FB) and the FIFO memory (MEM)
+
+    Get the device capabilities and frame buffer dimensions
+	Read SVGA_REG_CAPABILITIES, SVGA_REG_MAX_WIDTH, SVGA_REG_MAX_HEIGHT,
+	and SVGA_REG_HOST_BITS_PER_PIXEL / SVGA_REG_BITS_PER_PIXEL.
+
+	Note: The capabilities can and do change without the PCI device ID
+	changing or the SVGA_REG_ID changing.  A driver should always check
+	the capabilities register when loading before expecting any
+	capabilities-determined feature to be available.  See below for a list
+	of capabilities as of this writing.
+
+	Note: If SVGA_CAP_8BIT_EMULATION is not set, then it is possible that
+	SVGA_REG_HOST_BITS_PER_PIXEL does not exist and
+	SVGA_REG_BITS_PER_PIXEL should be read instead.
+
+    Report the Guest Operating System
+    	Write SVGA_REG_GUEST_ID with the appropriate value from <guest_os.h>.
+	While not required in any way, this is useful information for the
+	virtual machine to have available for reporting and sanity checking
+	purposes.
+
+    SetMode
+	Set SVGA_REG_WIDTH, SVGA_REG_HEIGHT, SVGA_REG_BITS_PER_PIXEL
+	Read SVGA_REG_FB_OFFSET
+	(SVGA_REG_FB_OFFSET is the offset from SVGA_REG_FB_START of the
+	 visible portion of the frame buffer)
+	Read SVGA_REG_BYTES_PER_LINE, SVGA_REG_DEPTH, SVGA_REG_PSEUDOCOLOR,
+	SVGA_REG_RED_MASK, SVGA_REG_GREEN_MASK, SVGA_REG_BLUE_MASK
+
+	Note: SVGA_REG_BITS_PER_PIXEL is readonly if
+	SVGA_CAP_8BIT_EMULATION is not set in the capabilities register.  Even
+	if it is set, values other than 8 and SVGA_REG_HOST_BITS_PER_PIXEL
+	will be ignored.
+
+    Enable SVGA
+	Set SVGA_REG_ENABLE to 1
+	(to disable SVGA, set SVGA_REG_ENABLE to 0.  Setting SVGA_REG_ENABLE
+	to 0 also enables VGA.)
+
+    Initialize the command FIFO
+	The FIFO is exclusively dword (32-bit) aligned.  The first four
+	dwords define the portion of the MEM area that is used for the
+	command FIFO.  These are values are all in byte offsets from the
+	start of the MEM area.
+
+	A minimum sized FIFO would have these values:
+	    mem[SVGA_FIFO_MIN] = 16;
+	    mem[SVGA_FIFO_MAX] = 16 + (10 * 1024);
+	    mem[SVGA_FIFO_NEXT_CMD] = 16;
+	    mem[SVGA_FIFO_STOP] = 16;
+
+	Set SVGA_REG_CONFIG_DONE to 1 after these values have been set.
+	
+	Note: Setting SVGA_REG_CONFIG_DONE to 0 will stop the device from
+	reading the FIFO until it is reinitialized and SVGA_REG_CONFIG_DONE is
+	set to 1 again.
+
+3. SVGA command FIFO protocol
+    The FIFO is empty when SVGA_FIFO_NEXT_CMD == SVGA_FIFO_STOP.  The
+    driver writes commands to the FIFO starting at the offset specified
+    by SVGA_FIFO_NEXT_CMD, and then increments SVGA_FIFO_NEXT_CMD.
+
+    The FIFO is full when SVGA_FIFO_NEXT_CMD is one word before SVGA_FIFO_STOP.
+
+    When the FIFO becomes full, the FIFO should be sync'd
+
+    To sync the FIFO
+	Write SVGA_REG_SYNC
+	Read SVGA_REG_BUSY
+	Wait for the value in SVGA_REG_BUSY to be 0
+
+    The FIFO should be sync'd before the driver touches the frame buffer, to
+    guarantee that any outstanding BLT's are completed.
+
+4. Cursor
+    When SVGA_CAP_CURSOR is set, hardware cursor support is available.  In
+    practice, SVGA_CAP_CURSOR will only be set when SVGA_CAP_CURSOR_BYPASS is
+    also set and drivers supporting a hardware cursor should only worry about
+    SVGA_CAP_CURSOR_BYPASS and only use the FIFO to define the cursor.  See
+    below for more information.
+
+5. Pseudocolor
+    When the read-only register SVGA_REG_PSEUDOCOLOR is 1, the device is in a
+    colormapped mode whose index width and color width are both SVGA_REG_DEPTH.
+    Thus far, 8 is the only depth at which pseudocolor is ever used.
+
+    In pseudocolor, the colormap is programmed by writing to the SVGA palette
+    registers.  These start at SVGA_PALETTE_BASE and are interpreted as
+    follows:
+
+    	SVGA_PALETTE_BASE + 3*n		- The nth red component
+    	SVGA_PALETTE_BASE + 3*n + 1	- The nth green component
+    	SVGA_PALETTE_BASE + 3*n + 2	- The nth blue component
+    
+    And n ranges from 0 to ((1<<SVGA_REG_DEPTH) - 1).
+    
+
+Drawing to the Screen
+---------------------
+
+After initialization, the driver can write directly to the frame buffer.  The
+updated frame buffer is not displayed immediately, but only when an update
+command is sent.  The update command (SVGA_CMD_UPDATE) defines the rectangle
+in the frame buffer that has been modified by the driver, and causes that
+rectangle to be updated on the screen.
+
+A complete driver can be developed this way.  For increased performance,
+additional commands are available to accelerate common operations.  The two
+most useful are SVGA_CMD_RECT_FILL and SVGA_CMD_RECT_COPY.
+
+After issuing an accelerated command, the FIFO should be sync'd, as described
+above, before writing to the frame buffer.
+
+Addendum on 7/11/2000
+---------------------
+
+SVGA_REG_FB_OFFSET and SVGA_REG_BYTES_PER_LINE may change after SVGA_REG_WIDTH
+or SVGA_REG_HEIGHT is set.  Also the VGA registers must be written to after
+setting SVGA_REG_ENABLE to 0 to change the display to a VGA mode.
+
+Addendum on 11/29/2001
+---------------------
+
+Actually, after changing any of SVGA_REG_WIDTH, SVGA_REG_HEIGHT, and
+SVGA_REG_BITS_PER_PIXEL, all of the registers listed in the 'SetMode'
+initialization section above should be reread.  Additionally, when changing
+modes, it can be convenient to set SVGA_REG_ENABLE to 0, change
+SVGA_REG_WIDTH, SVGA_REG_HEIGHT, and SVGA_REG_BITS_PER_PIXEL (if available),
+and then set SVGA_REG_ENABLE to 1 again.
+
+
+Capabilities
+------------
+
+The capabilities register (SVGA_REG_CAPABILITIES) is an array of bits that
+indicates the capabilities of the SVGA emulation.  A driver should check
+SVGA_REG_CAPABILITIES every time it loads before relying on any feature that
+is only optionally available.
+
+Some of the capabilities determine which FIFO commands are available.  This
+table shows which capability indicates support for which command.
+
+    FIFO Command			Capability
+    ------------			----------
+
+    SVGA_CMD_RECT_FILL			SVGA_CAP_RECT_FILL
+    SVGA_CMD_RECT_COPY			SVGA_CAP_RECT_COPY
+    SVGA_CMD_DEFINE_BITMAP		SVGA_CAP_OFFSCREEN
+    SVGA_CMD_DEFINE_BITMAP_SCANLINE	SVGA_CAP_OFFSCREEN
+    SVGA_CMD_DEFINE_PIXMAP		SVGA_CAP_OFFSCREEN
+    SVGA_CMD_DEFINE_PIXMAP_SCANLINE	SVGA_CAP_OFFSCREEN
+    SVGA_CMD_RECT_BITMAP_FILL		SVGA_CAP_RECT_PAT_FILL
+    SVGA_CMD_RECT_PIXMAP_FILL		SVGA_CAP_RECT_PAT_FILL
+    SVGA_CMD_RECT_BITMAP_COPY		SVGA_CAP_RECT_PAT_FILL
+    SVGA_CMD_RECT_PIXMAP_COPY		SVGA_CAP_RECT_PAT_FILL
+    SVGA_CMD_FREE_OBJECT		SVGA_CAP_OFFSCREEN
+    SVGA_CMD_RECT_ROP_FILL		SVGA_CAP_RECT_FILL +
+					    SVGA_CAP_RASTER_OP
+    SVGA_CMD_RECT_ROP_COPY		SVGA_CAP_RECT_COPY +
+					    SVGA_CAP_RASTER_OP
+    SVGA_CMD_RECT_ROP_BITMAP_FILL	SVGA_CAP_RECT_PAT_FILL +
+					    SVGA_CAP_RASTER_OP
+    SVGA_CMD_RECT_ROP_PIXMAP_FILL	SVGA_CAP_RECT_PAT_FILL +
+					    SVGA_CAP_RASTER_OP
+    SVGA_CMD_RECT_ROP_BITMAP_COPY	SVGA_CAP_RECT_PAT_FILL +
+					    SVGA_CAP_RASTER_OP
+    SVGA_CMD_RECT_ROP_PIXMAP_COPY	SVGA_CAP_RECT_PAT_FILL +
+					    SVGA_CAP_RASTER_OP
+    SVGA_CMD_DEFINE_CURSOR		SVGA_CAP_CURSOR
+    SVGA_CMD_DISPLAY_CURSOR		SVGA_CAP_CURSOR
+    SVGA_CMD_MOVE_CURSOR		SVGA_CAP_CURSOR
+    SVGA_CMD_DEFINE_ALPHA_CURSOR	SVGA_CAP_ALPHA_CURSOR
+    SVGA_CMD_DRAW_GLYPH                 SVGA_CAP_GLYPH
+    SVGA_CMD_DRAW_GLYPH_CLIPPED         SVGA_CAP_GLYPH_CLIPPING
+
+Note:  SVGA_CMD_DISPLAY_CURSOR and SVGA_CMD_MOVE_CURSOR should not be used.
+Drivers wishing hardware cursor support should use cursor bypass (see below).
+
+Other capabilities indicate other functionality as described below:
+
+    SVGA_CAP_CURSOR_BYPASS
+	The hardware cursor can be drawn via SVGA Registers (without requiring
+	the FIFO be synchronized and will be drawn potentially before any
+	outstanding unprocessed FIFO commands).
+
+	Note:  Without SVGA_CAP_CURSOR_BYPASS_2, cursors drawn this way still
+	appear in the guest's framebuffer and need to be turned off before any
+	save under / overlapping drawing and turned back on after.  This can
+	cause very noticeable cursor flicker.
+
+    SVGA_CAP_CURSOR_BYPASS_2
+    	Instead of turning the cursor off and back on around any overlapping
+	drawing, the driver can write SVGA_CURSOR_ON_REMOVE_FROM_FB and
+	SVGA_CURSOR_ON_RESTORE_TO_FB to SVGA_REG_CURSOR_ON.  In almost all
+	cases these are NOPs and the cursor will be remain visible without
+	appearing in the guest framebuffer.  In 'direct graphics' modes like
+	Linux host fullscreen local displays, however, the cursor will still
+	be drawn in the framebuffer, still flicker, and be drawn incorrectly
+	if a driver does not use SVGA_CURSOR_ON_REMOVE_FROM_FB / RESTORE_TO_FB.
+
+    SVGA_CAP_8BIT_EMULATION
+    	SVGA_REG_BITS_PER_PIXEL is writable and can be set to either 8 or
+	SVGA_REG_HOST_BITS_PER_PIXEL.  Otherwise the only SVGA modes available
+	inside a virtual machine must match the host's bits per pixel.
+	
+	Note: Some versions which lack SVGA_CAP_8BIT_EMULATION also lack the
+	SVGA_REG_HOST_BITS_PER_PIXEL and a driver should assume
+	SVGA_REG_BITS_PER_PIXEL is both read-only and initialized to the only
+	available value if SVGA_CAP_8BIT_EMULATION is not set.
+        
+    SVGA_CAP_OFFSCREEN_1
+        SVGA_CMD_RECT_FILL, SVGA_CMD_RECT_COPY, SVGA_CMD_RECT_ROP_FILL,
+        SVGA_CMD_RECT_ROP_COPY can operate with a source or destination (or
+        both) in offscreen memory. 
+        
+        Usable offscreen memory is a rectangle located below the last scanline
+        of the visible memory:
+        x1 = 0
+        y1 = (SVGA_REG_FB_SIZE + SVGA_REG_BYTES_PER_LINE - 1) / 
+             SVGA_REG_BYTES_PER_LINE
+        x2 = SVGA_REG_BYTES_PER_LINE / SVGA_REG_DEPTH
+        y2 = SVGA_REG_VRAM_SIZE / SVGA_REG_BYTES_PER_LINE
+
+
+Cursor Handling
+---------------
+
+Starting with GSX Server Beta 3 (after 11/15/2000), hardware cursor support
+was added.  Actually, both a hardware cursor via the FIFO (SVGA_CAP_CURSOR)
+and a hardware cursor via the SVGA registers (SVGA_CAP_CURSOR_BYPASS) were
+added.  SVGA_CAP_CURSOR was never available without SVGA_CAP_CURSOR_BYPASS and
+the FIFO hardware cursor should never be used and may be removed without
+warning in the future.
+
+Cursor bypass is programmed using the two FIFO commands SVGA_CMD_DEFINE_CURSOR
+and SVGA_CMD_DEFINE_ALPHA_CURSOR in conjunction with the SVGA registers
+SVGA_REG_CURSOR_ID, SVGA_REG_CURSOR_X, SVGA_REG_CURSOR_Y, and
+SVGA_REG_CURSOR_ON.
+
+A driver defines an AND/XOR hardware cursor using SVGA_CMD_DEFINE_CURSOR to
+assign an ID and establish the AND and XOR masks with the hardware.  A driver
+uses SVGA_CMD_DEFINE_ALPHA_CURSOR to define a 32 bit mask whose top 8 bits are
+used to blend the cursor image with the pixels it covers.  Alpha cursor
+support is only available when SVGA_CAP_ALPHA_CURSOR is set.
+
+Once a cursor is defined, a driver can draw it to the screen at any time by
+writing the SVGA_REG_CURSOR_ID register with the ID used when the cursor was
+defined, writing SVGA_REG_CURSOR_X and SVGA_REG_CURSOR_Y with the location of
+the cursor, and SVGA_CURSOR_ON_SHOW to SVGA_REG_CURSOR_ON.  The drawing occurs
+when SVGA_REG_CURSOR_ON is written.
+
+Writing SVGA_CURSOR_ON_HIDE to SVGA_REG_CURSOR_ON will turn the cursor off and
+make it vanish from the display and, if present, from the framebuffer.
+SVGA_CURSOR_ON_REMOVE_FROM_FB will ensure the cursor is not in the
+framebuffer, but will only turn it off if there's no other way to remove it.
+SVGA_CURSOR_ON_RESTORE_TO_FB is the complement to
+SVGA_CURSOR_ON_REMOVE_FROM_FB.  Whenever possible, the device will not put the
+cursor in the framebuffer and Remove From / Restore To will be NOPs.
+
+Note: The cursor must be out of the frame buffer before the driver (or any
+agent in the virtual machine) touches an overlapping portion of the frame
+buffer, because it is actually drawn into the frame buffer memory in the
+case of direct graphics mode (e.g. full screen mode on Linux).  The cursor
+does not have to be touched before issuing an accelerated command via the
+command FIFO, this case is handled by the SVGA device.
+
+Note: If SVGA_CAP_CURSOR_BYPASS2 is not present, the driver must use
+SVGA_CURSOR_ON_HIDE and SVGA_CURSOR_ON_HIDE to be certain the cursor is out of
+the framebuffer.
+
+
+Driver Version Numbers
+----------------------
+
+The SVGA drivers use the following convention for their version numbers:
+
+Version 10.0 - The first version that uses the FIFO
+Version 10.1 - The version that uses the hardware cursor emulation via the FIFO
+Version 10.2 - The version that uses the cursor that bypasses the FIFO
+Version 10.3 - The version that can also support the 0405 chipset
+Version 10.4 - The version that knows about SVGA_CAP_CURSOR_BYPASS2
+Version 10.5 - [Never released or well defined]
+Version 10.6 - The version that knows about SVGA_CAP_8BIT_EMULATION
+Version 10.7 - The version that knows about SVGA_CAP_ALPHA_CURSOR
+Version 10.8 - The version that knows about SVGA_CAP_GLYPH
+Version 10.9 - The version that knows about SVGA_CAP_OFFSCREEN_1
+
+Note that this is merely the convention used by SVGA drivers written and
+maintained by VMware, Inc. and describes the capabilities of the driver, not
+the virtual hardware.  An SVGA driver can only use the intersection of the
+functionality it supports and the functionality available in the virtual SVGA
+hardware.
+
+
+Frequently Asked Questions
+--------------------------
+
+1.  My driver doesn't display anything, what's going on?
+
+First check if you are issuing an SVGA_CMD_UPDATE after drawing to
+the screen.  Another check you can do is to run your driver in full
+screen mode on a Linux host.  In this case you are drawing directly
+on the frame buffer, so what you draw to the screen will be immediately
+visible.  If nothing is visible in this case, then most likely your
+driver hasn't mapped the frame buffer correctly.
+
+A discrepancy between what you get in full screen mode and what you
+get in window mode indicates that you have a missing or incorrect
+update command.
+
+
+2.  What's the difference between bitmaps and pixmaps?
+
+Pixmaps have the same depth as the screen, while bitmaps have depth one.
+When a bitmap is drawn, the command also takes two colors, foreground and
+background.  The set bits in the bitmap are replaced with the foreground
+color, and the unset bits are replaced with the background color.
+
+Pixmaps, on the other hand, can be directly copied to the screen.
+
+
+3.  What's the significance of the ROP in the commands SVGA_CMD_RECT_ROP_FILL,
+SVGA_CMD_RECT_ROP_BITMAP_COPY, etc. ?
+
+The ROP in the ...ROP... commands is a raster operation.  It has the same
+significance (and encoding) as it does in X.  The ROP value SVGA_ROP_COPY
+means the source is copied to the destination, which makes these commands the
+same as their non-ROP counterparts.  The most commonly used raster operation
+other than copy is probably SVGA_ROP_XOR, which combines the source and
+destination using exclusive-or.
+
+
+4.  Tell me more about bitmaps and pixmaps.  For example, the macro
+SVGA_CMD_DEFINE_BITMAP has a field <scanlines>.  What should this be
+set to?  Likewise with SVGA_CMD_DEFINE_PIXMAP.  And when should the
+SCANLINE macros be used?
+
+OK, I'll use pixmaps as an example.  First you have to define the pixmap:
+
+#define  SVGA_CMD_DEFINE_PIXMAP		6
+	 /* FIFO layout:
+	    Pixmap ID, Width, Height, Depth, <scanlines> */
+
+The ID is something you choose, which you subsequently use to refer to
+this pixmap.  It must be an integer between 0 and SVGA_MAX_ID.
+
+The width and height and depth are the dimensions of the pixmap.  For now,
+the depth of the pixmap has to match the depth of the screen.
+
+The scanlines are the pixels that make up the pixmap, arranged one row
+at a time.  Each row is required to be 32-bit aligned.  The macros
+SVGA_PIXMAP_SCANLINE_SIZE and SVGA_PIXMAP_SIZE give the size of a
+single scanline, and the size of the entire pixmap, respectively, in
+32-bit words.
+
+The second step is to use it:
+
+#define  SVGA_CMD_RECT_PIXMAP_FILL	9
+	 /* FIFO layout:
+	    Pixmap ID, X, Y, Width, Height */
+
+The ID here is the one you chose when defining the pixmap.  X, Y,
+Width, and Height define a rectangle on the screen that is to be filled
+with the pixmap.  The pixmap is screen aligned, which means that the
+coordinates in the pixmap are defined by the screen coordinates modulo
+the pixmap dimensions.
+
+If you want a different alignment between the screen and the pixmap,
+then you can use this command, which allows the pixmap coordinates to
+be defined:
+
+#define  SVGA_CMD_RECT_PIXMAP_COPY	11
+	 /* FIFO layout:
+	    Pixmap ID, Source X, Source Y, Dest X, Dest Y, Width,
+	    Height */
+
+The Source X and Source Y are pixmap coordinates, and the Dest X and
+Dest Y are screen coordinates.
+
+
+5.  OK, now it works briefly, then stops displaying anything.  Also,
+my log file is filled with lines like:
+  Unknown Command 0xff in SVGA command FIFO
+What's happening?
+
+The most common problem at this point is that the FIFO gets out
+of sync.  This can happen if the amount of data in the FIFO doesn't
+match what the VMware SVGA device expects.  To track this down, try
+to isolate the particular command which causes the problem.
+
+Another way this can happen is if the wraparound in the FIFO isn't
+done correctly.  Here is some example code for writing to the FIFO
+(mem is an array of 32-bit integers that points to the FIFO memory
+region):
+
+while (TRUE) {
+    fifo_min = mem[SVGA_FIFO_MIN] / 4;
+    fifo_max = mem[SVGA_FIFO_MAX] / 4;
+    fifo_next = mem[SVGA_FIFO_NEXT_CMD] / 4;
+    fifo_stop = mem[SVGA_FIFO_STOP] / 4;
+
+    tmp_next = fifo_next+1;
+    if (tmp_next == fifo_max)
+	tmp_next = fifo_min;    // Wraparound
+
+    if (tmp_next == fifo_stop) {
+	sync_fifo();		// FIFO full
+	continue;		// retry
+    }
+
+    mem[fifo_next] = item;
+    mem[SVGA_FIFO_NEXT_CMD] = tmp_next * 4;
+    break;
+}
+
+This isn't the most efficient code, but it should work.  It's important
+to do the increment with wraparound before the FIFO full check, and to
+check FIFO full before updating the next command pointer.
+
+
+6. My driver tries to switch modes and either nothing happens or the
+display becomes completely garbled.  What's going on?
+
+When you change modes, make very sure you reread all of the registers listed
+above under SetMode.  Getting the pitch (SVGA_REG_BYTES_PER_LINE) incorrect
+will cause a heavily garbled display.  Also, if you change
+SVGA_REG_BITS_PER_PIXEL, make certain that SVGA_CAP_8BIT_EMULATION is present
+in the SVGA_REG_CAPABILITIES register.  Also, even with 8 bit emulation, the
+driver must still use either 8 bpp or SVGA_REG_HOST_BITS_PER_PIXEL bpp,
+nothing else.
+
+
+7. Why does my driver's hardware cursor work when my virtual machine is in
+window mode, but draw/erase incorrectly or in garbled locations in fullscreen
+mode?
+
+You need to make sure you use SVGA_CURSOR_ON_REMOVE_FROM_FB and
+SVGA_CURSOR_ON_RESTORE_TO_FB _every_ time your driver or the virtual machine
+touches a region of the framebuffer that overlaps the cursor.  If you forget
+to remove it then it can show up when doing save-under operations or get mixed
+in with other drawing.  If you forget to restore it then can disappear.  You
+also need to make sure SVGA_CAP_CURSOR_BYPASS2 is available, or else you will
+have to use SVGA_CURSOR_ON_SHOW and SVGA_CURSOR_ON_HIDE (which will flicker,
+even in window mode), or else a software cursor.  Newer version of the virtual
+SVGA hardware will never put the hardware cursor in the framebuffer while in
+window mode, so everything will appear to work correctly there.
+
+
+8. Why do my accelerated glyphs look funny?  OR  Why does the fifo complain
+about invalid commands when I draw accelerated glyphs?
+
+The bitmap data passed to SVGA_CMD_DRAW_GLYPH_* must not have any per-scanline
+alignment.  If there are any remaining bits left in the last byte of a scanline,
+the first bits of the next scanline should use them.  
+
+The bitmap data as a whole must be 4 byte aligned.
+
+$XFree86: xc/programs/Xserver/hw/xfree86/drivers/vmware/README,v 1.5 2002/10/16 22:12:53 alanh Exp $