
Copyright (C) 1999-2001 VMware, Inc.
All Rights Reserved

VMware Proprietary


	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.


Programming the VMware SVGA Device
----------------------------------

1. Reading/writing a register:
    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

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 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 frame buffer dimensions
	Read SVGA_REG_MAX_WIDTH, SVGA_REG_MAX_HEIGHT, SVGA_REG_BITS_PER_PIXEL

    SetMode
	Set SVGA_REG_WIDTH, SVGA_REG_HEIGHT
	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_PSEUDOCOLOR, SVGA_REG_GREEN_MASK,
	SVGA_REG_RED_MASK

    Enable SVGA
	Set SVGA_REG_ENABLE to 1
	(to disable SVGA, set SVGA_REG_ENABLE to 0)

    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;

	Write SVGA_REG_CONFIG_DONE after these values have been set.

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. Capabilities
    The capabilities of the SVGA device can be queried by reading
    SVGA_REG_CAPABILITIES.


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_REB_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.


Capabilities
------------

The capabilities register (SVGA_REG_CAPABILITIES) is an array of
bits that indicates the capabilities of the SVGA emulation.
This table shows what commands are available, depending on the
capabilities:

    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

The ability to program the cursor directly through the registers
(described in the next section) is indicated by the capability
SVGA_CAP_CURSOR_BYPASS.


Cursor Handling
---------------

Starting with GSX Server Beta 3 (after 11/15/2000), a new cursor interface
was added that bypasses the FIFO.  This is programmed using the
registers SVGA_REG_CURSOR_ID, SVGA_REG_CURSOR_X, SVGA_REG_CURSOR_Y,
and SVGA_REG_CURSOR_ON.

First, the cursor must be defined using the FIFO command
SVGA_CMD_DEFINE_CURSOR.  This command allocates a cursor ID and
associates two pixmaps with the cursor, the AND mask and the XOR mask.

To display the cursor, the ID must be written to SVGA_REG_CURSOR_ID,
the coordinates written to SVGA_REG_CURSOR_X and SVGA_REG_CURSOR_Y,
then the value 1 must be written to SVGA_REG_CURSOR_ON.  No display
occurs until SVGA_REG_CURSOR_ON is written.  The same sequence is used
to move the cursor.

To turn the cursor off, the ID must be written to SVGA_REG_CURSOR_ID,
and the value 0 must be written to SVGA_REG_CURSOR_ON.

NOTE:  The cursor must be turned off before touching 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 turned off before issuing an accelerated command
via the command FIFO, this case is handled by the SVGA device.


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

