68478eab4b
but couldn't release immediately since they depended on virtual GPU features which were not yet publicly released in any products. This checkin moves those features from our internal repository to the open source repository. Future development on these tests and examples will take place directly in the open source repository. The primary feature added by this patch is 'Screen Object', a new dynamic display management extension supported by Workstation 7.0 and Fusion 3.0. See the README for a quick explanation.
186 lines
7.1 KiB
Plaintext
186 lines
7.1 KiB
Plaintext
--------------------------------
|
|
VMware SVGA Device Developer Kit
|
|
--------------------------------
|
|
|
|
The "VMware SVGA II" device is the virtual graphics card implemented
|
|
by all VMware virtualization products. It is a virtual PCI device,
|
|
which implements a basic 2D framebuffer, as well as 3D acceleration,
|
|
video overlay acceleration, and hardware cursor support.
|
|
|
|
This is a package of documentation and example code for the VMware
|
|
SVGA device's programming model. Currently it consists of some very
|
|
basic documentation, and a collection of examples which illustrate the
|
|
more advanced features of the device. These examples are written to
|
|
run on the "virtual bare metal", without an operating system.
|
|
|
|
This package is intended for educational purposes, or for people who
|
|
are developing 3D drivers. This code won't help you if you're writing
|
|
normal user-level apps that you'd like to run inside a virtual
|
|
machine. It's for driver authors, and it assumes a reasonable amount
|
|
of prior knowledge about graphics hardware.
|
|
|
|
Requirements
|
|
------------
|
|
|
|
To compile the example code, you'll need a few basic open source tools:
|
|
|
|
- A recent version of GCC. I use 4.2. Older versions may
|
|
require tweaking the Makefile.rules file slightly.)
|
|
- binutils
|
|
- GNU Make
|
|
- Python
|
|
|
|
To run the examples, you'll need a recent version of VMware
|
|
Workstation, Player, or Fusion. Some of the examples will work on
|
|
older versions, but Workstation 6.5.x or Fusion 2.0.x is strongly
|
|
recommended.
|
|
|
|
Screen Object
|
|
-------------
|
|
|
|
Any of the examples that begin with "screen-" make use of a new virtual
|
|
hardware feature called "Screen Object". This feature first appears in
|
|
Workstation 7.0 and Fusion 3.0, and it is enabled by default only for
|
|
Windows 7, Windows Server 2008, Windows Vista, and Mac OS guests. To
|
|
use Screen Object, you can pick one of those guest OS types or you can
|
|
add a configuration option to your VM's VMX file or to your per-user
|
|
VMware config file:
|
|
|
|
svga.enableScreenObject = TRUE
|
|
|
|
We plan to enable Screen Object by default in a future virtual machine
|
|
hardware version. Screen Object is enabled conditionally for the above
|
|
guest OS types on hardware version 7 (the current hardware version
|
|
for Workstation 6.5 and 7.0, Fusion 2.x and 3.0) in order to provide
|
|
better support to the WDDM and Mac OS video drivers on VMware's desktop
|
|
products. Screen Object is never available on hardware version 6 and
|
|
earlier.
|
|
|
|
Screen Object allows several new capabilities including more efficient
|
|
management of framebuffer memory, dynamic creation and destruction of
|
|
virtual monitors, and it is leading up to the deprecation of BAR1
|
|
memory in favor of guest system memory.
|
|
|
|
To see the new Screen Object capabilities in action, try the
|
|
screen-multimon test. Note that not all Screen Object features are
|
|
fully supported on all host OSes. Currently, only Fusion 3.0 supports
|
|
the following features:
|
|
|
|
- Rendering and reading back from non-rooted screens.
|
|
- Preserving contents of screens which overlap in the
|
|
virtual coordinate space.
|
|
- Hardware-accelerated scaling for the new SVGA3D-to-screen blit.
|
|
|
|
These are relatively minor edge cases, though. If you design a
|
|
multi-monitor driver using Screen Object, it should run correctly on
|
|
all hosts that support Screen Object.
|
|
|
|
Contents
|
|
--------
|
|
|
|
* bin/
|
|
|
|
Precompiled binaries and .vmx files for all examples. These can be
|
|
loaded directly into VMware Workstation, Player, or Fusion.
|
|
|
|
* doc/
|
|
|
|
Basic SVGA hardware documentation. This includes a text file with
|
|
information about the programming model, plus it includes a copy of
|
|
a WIOV paper which describes our 3D acceleration architecture.
|
|
|
|
* lib/metalkit/
|
|
|
|
Metalkit is a very simple open source OS, which bootstraps the
|
|
examples and provides basic hardware support.
|
|
|
|
* lib/refdriver/
|
|
|
|
The SVGA "Reference Driver". This is a sample implementation of a
|
|
driver for our device, which is used by the examples. It provides
|
|
device initialiation, an implementation of the low-level FIFO
|
|
protocol, and wrappers around common FIFO commands.
|
|
|
|
If you're writing a driver for the VMware SVGA device, "svga.c"
|
|
from this directory is required reading. The FIFO protocol has
|
|
many subtle gotchas, and this source file is the only place
|
|
where they're publicly documented.
|
|
|
|
* lib/vmware/
|
|
|
|
Header files which define VMware's protocols and virtual hardware.
|
|
The svga_reg.h and svga3d_reg.h files are (in places, at least)
|
|
commented with more information on the programming model.
|
|
|
|
If you can't find specific documentation or an example on a feature,
|
|
this is the next place to look. This is also where to get a complete
|
|
list of the supported registers and commands.
|
|
|
|
* lib/util/
|
|
|
|
Higher-level utilities built on top of the refdriver layer. This
|
|
directory won't contain any novel information about the virtual
|
|
hardware, but it does contain some higher-level abstractions used
|
|
by the examples, and these abstractions demonstrate some useful
|
|
idioms for programming the SVGA device.
|
|
|
|
* examples/
|
|
|
|
Each example has a separate subdirectory. You can run "make" in the
|
|
top-level directory to compile all examples, or you can build them
|
|
individually.
|
|
|
|
Many of the examples are self-explanatory, but some of them are
|
|
not. See the comments at the beginning of the 'main.c' file in each
|
|
example.
|
|
|
|
Development
|
|
-----------
|
|
|
|
This project isn't intended to be a one-time "code drop" from VMware.
|
|
Our intent is for the examples in this package to be maintained out in
|
|
the open. If we have a bugfix, or a new example that works on released
|
|
VMware products, we'll check it in directly to the public repository.
|
|
|
|
For examples of not-yet-released features, we will be developing on an
|
|
internal branch. This branch will be merged to the public repository
|
|
shortly after the first release which has working versions of these
|
|
features.
|
|
|
|
License
|
|
-------
|
|
|
|
Except where noted in individual source files, the whole package is
|
|
Copyright (C) 1998-2009 VMware, Inc. It is released under the MIT
|
|
license:
|
|
|
|
Permission is hereby granted, free of charge, to any person
|
|
obtaining a copy of this software and associated documentation files
|
|
(the "Software"), to deal in the Software without restriction,
|
|
including without limitation the rights to use, copy, modify, merge,
|
|
publish, distribute, sublicense, and/or sell copies of the Software,
|
|
and to permit persons to whom the Software is furnished to do so,
|
|
subject to the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be
|
|
included in all copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
|
|
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
|
|
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
SOFTWARE.
|
|
|
|
Contact
|
|
-------
|
|
|
|
This project is provided as-is, with no official support from
|
|
VMware. However, I will try to answer questions as time permits.
|
|
If you have questions or you'd like to submit a patch, feel free
|
|
to email me at: micah at vmware.com
|
|
|
|
--
|