1VMware SVGA3D Guest Driver
2==========================
3
4This page describes how to build, install and use the
5`VMware <https://www.vmware.com/>`__ guest GL driver (aka the SVGA or
6SVGA3D driver) for Linux using the latest source code. This driver gives
7a Linux virtual machine access to the host's GPU for
8hardware-accelerated 3D. VMware Workstation running on Linux or Windows
9and VMware Fusion running on MacOS are all supported.
10
11With the August 2015 Workstation 12 / Fusion 8 releases, OpenGL 3.3 is
12supported in the guest. This requires:
13
14-  The VM is configured for virtual hardware version 12.
15-  The host OS, GPU and graphics driver supports DX11 (Windows) or
16   OpenGL 4.0 (Linux, Mac)
17-  On Linux, the vmwgfx kernel module must be version 2.9.0 or later.
18-  A recent version of Mesa with the updated svga gallium driver.
19
20Otherwise, OpenGL 2.1 is supported.
21
22With the Fall 2018 Workstation 15 / Fusion 11 releases, additional
23features are supported in the driver:
24
25-  Multisample antialiasing (2x, 4x)
26-  GL_ARB/AMD_draw_buffers_blend
27-  GL_ARB_sample_shading
28-  GL_ARB_texture_cube_map_array
29-  GL_ARB_texture_gather
30-  GL_ARB_texture_query_lod
31-  GL_EXT/OES_draw_buffers_indexed
32
33This requires version 2.15.0 or later of the vmwgfx kernel module and
34the VM must be configured for hardware version 16 or later.
35
36OpenGL 3.3 support can be disabled by setting the environment variable
37SVGA_VGPU10=0. You will then have OpenGL 2.1 support. This may be useful
38to work around application bugs (such as incorrect use of the OpenGL 3.x
39core profile).
40
41Most modern Linux distros include the SVGA3D driver so end users
42shouldn't be concerned with this information. But if your distro lacks
43the driver or you want to update to the latest code these instructions
44explain what to do.
45
46For more information about the X components see these wiki pages at
47x.org:
48
49-  `Driver Overview <https://wiki.x.org/wiki/vmware>`__
50-  `xf86-video-vmware
51   Details <https://wiki.x.org/wiki/vmware/vmware3D>`__
52
53Components
54----------
55
56The components involved in this include:
57
58-  Linux kernel module: vmwgfx
59-  X server 2D driver: xf86-video-vmware
60-  User-space libdrm library
61-  Mesa/gallium OpenGL driver: "svga"
62
63All of these components reside in the guest Linux virtual machine. On
64the host, all you're doing is running VMware
65`Workstation <https://www.vmware.com/products/workstation/>`__ or
66`Fusion <https://www.vmware.com/products/fusion/>`__.
67
68Prerequisites
69-------------
70
71-  Kernel version at least 2.6.25
72-  Xserver version at least 1.7
73-  Ubuntu: For ubuntu you need to install a number of build
74   dependencies.
75
76   ::
77
78      sudo apt-get install git-core
79      sudo apt-get install ninja-build meson libpthread-stubs0-dev
80      sudo apt-get install xserver-xorg-dev x11proto-xinerama-dev libx11-xcb-dev
81      sudo apt-get install libxcb-glx0-dev libxrender-dev
82      sudo apt-get build-dep libgl1-mesa-dri libxcb-glx0-dev
83
84
85-  Fedora: For Fedora you also need to install a number of build
86   dependencies.
87
88   ::
89
90      sudo yum install mesa-libGL-devel xorg-x11-server-devel xorg-x11-util-macros
91      sudo yum install libXrender-devel.i686
92      sudo yum install ninja-build meson gcc expat-devel kernel-devel git-core
93      sudo yum install makedepend flex bison
94
95
96Depending on your Linux distro, other packages may be needed. Meson
97should tell you what's missing.
98
99Getting the Latest Source Code
100------------------------------
101
102Begin by saving your current directory location:
103
104::
105
106   export TOP=$PWD
107
108
109-  Mesa/Gallium master branch. This code is used to build libGL, and the
110   direct rendering svga driver for libGL, vmwgfx_dri.so, and the X
111   acceleration library libxatracker.so.x.x.x.
112
113   ::
114
115      git clone https://gitlab.freedesktop.org/mesa/mesa.git
116
117
118-  VMware Linux guest kernel module. Note that this repo contains the
119   complete DRM and TTM code. The vmware-specific driver is really only
120   the files prefixed with vmwgfx.
121
122   ::
123
124      git clone git://anongit.freedesktop.org/git/mesa/vmwgfx
125
126
127-  libdrm, a user-space library that interfaces with drm. Most distros
128   ship with this but it's safest to install a newer version. To get the
129   latest code from git:
130
131   ::
132
133      git clone https://gitlab.freedesktop.org/mesa/drm.git
134
135
136-  xf86-video-vmware. The chainloading driver, vmware_drv.so, the legacy
137   driver vmwlegacy_drv.so, and the vmwgfx driver vmwgfx_drv.so.
138
139   ::
140
141      git clone git://anongit.freedesktop.org/git/xorg/driver/xf86-video-vmware
142
143
144Building the Code
145-----------------
146
147-  Determine where the GL-related libraries reside on your system and
148   set the LIBDIR environment variable accordingly.
149
150   For 32-bit Ubuntu systems:
151
152   ::
153
154      export LIBDIR=/usr/lib/i386-linux-gnu
155
156   For 64-bit Ubuntu systems:
157
158   ::
159
160      export LIBDIR=/usr/lib/x86_64-linux-gnu
161
162   For 32-bit Fedora systems:
163
164   ::
165
166      export LIBDIR=/usr/lib
167
168   For 64-bit Fedora systems:
169
170   ::
171
172      export LIBDIR=/usr/lib64
173
174-  Build libdrm:
175
176   ::
177
178      cd $TOP/drm
179      meson builddir --prefix=/usr --libdir=${LIBDIR}
180      ninja -C builddir
181      sudo ninja -C builddir install
182
183
184-  Build Mesa and the vmwgfx_dri.so driver, the vmwgfx_drv.so xorg
185   driver, the X acceleration library libxatracker. The vmwgfx_dri.so is
186   used by the OpenGL libraries during direct rendering, and by the Xorg
187   server during accelerated indirect GL rendering. The libxatracker
188   library is used exclusively by the X server to do render, copy and
189   video acceleration:
190
191   The following configure options doesn't build the EGL system.
192
193   ::
194
195      cd $TOP/mesa
196      meson builddir --prefix=/usr --libdir=${LIBDIR} -Dgallium-drivers=svga -Ddri-drivers=swrast -Dgallium-xa=true -Ddri3=false
197      ninja -C builddir
198      sudo ninja -C builddir install
199
200
201   Note that you may have to install other packages that Mesa depends
202   upon if they're not installed in your system. You should be told
203   what's missing.
204
205-  xf86-video-vmware: Now, once libxatracker is installed, we proceed
206   with building and replacing the current Xorg driver. First check if
207   your system is 32- or 64-bit.
208
209   ::
210
211      cd $TOP/xf86-video-vmware
212      ./autogen.sh --prefix=/usr --libdir=${LIBDIR}
213      make
214      sudo make install
215
216
217-  vmwgfx kernel module. First make sure that any old version of this
218   kernel module is removed from the system by issuing
219
220   ::
221
222      sudo rm /lib/modules/`uname -r`/kernel/drivers/gpu/drm/vmwgfx.ko*
223
224   Build and install:
225
226   ::
227
228      cd $TOP/vmwgfx
229      make
230      sudo make install
231      sudo depmod -a
232
233   If you're using a Ubuntu OS:
234
235   ::
236
237      sudo update-initramfs -u
238
239   If you're using a Fedora OS:
240
241   ::
242
243      sudo dracut --force
244
245   Add 'vmwgfx' to the /etc/modules file:
246
247   ::
248
249      echo vmwgfx | sudo tee -a /etc/modules
250
251   .. note::
252
253      some distros put DRM kernel drivers in different directories.
254      For example, sometimes vmwgfx.ko might be found in
255      ``/lib/modules/{version}/extra/vmwgfx.ko`` or in
256      ``/lib/modules/{version}/kernel/drivers/gpu/drm/vmwgfx/vmwgfx.ko``.
257
258      After installing vmwgfx.ko you might want to run the following
259      command to check that the new kernel module is in the expected place:
260
261      ::
262
263         find /lib/modules -name vmwgfx.ko -exec ls -l '{}' \;
264
265      If you see the kernel module listed in more than one place, you may
266      need to move things around.
267
268   Finally, if you update your kernel you'll probably have to rebuild
269   and reinstall the vmwgfx.ko module again.
270
271Now try to load the kernel module by issuing
272
273::
274
275   sudo modprobe vmwgfx
276
277Then type
278
279::
280
281   dmesg
282
283to watch the debug output. It should contain a number of lines prefixed
284with "[vmwgfx]".
285
286Then restart the Xserver (or reboot). The lines starting with
287"vmwlegacy" or "VMWARE" in the file /var/log/Xorg.0.log should now have
288been replaced with lines starting with "vmwgfx", indicating that the new
289Xorg driver is in use.
290
291Running OpenGL Programs
292-----------------------
293
294In a shell, run 'glxinfo' and look for the following to verify that the
295driver is working:
296
297::
298
299   OpenGL vendor string: VMware, Inc.
300   OpenGL renderer string: Gallium 0.4 on SVGA3D; build: RELEASE;
301   OpenGL version string: 2.1 Mesa 8.0
302
303If you don't see this, try setting this environment variable:
304
305::
306
307   export LIBGL_DEBUG=verbose
308
309then rerun glxinfo and examine the output for error messages.
310
311If OpenGL 3.3 is not working (you only get OpenGL 2.1):
312
313-  Make sure the VM uses hardware version 12.
314-  Make sure the vmwgfx kernel module is version 2.9.0 or later.
315-  Check the vmware.log file for errors.
316-  Run 'dmesg \| grep vmwgfx' and look for "DX: yes".
317