docs/vmware-guest.rst

   1 VMware SVGA3D Guest Driver
   2 ==========================
   3
   4 This page describes how to build, install and use the
   5 `VMware <https://www.vmware.com/>`__ guest GL driver (aka the SVGA or
   6 SVGA3D driver) for Linux using the latest source code. This driver gives
   7 a Linux virtual machine access to the host's GPU for
   8 hardware-accelerated 3D. VMware Workstation running on Linux or Windows
   9 and VMware Fusion running on MacOS are all supported.
  10
  11 With the August 2015 Workstation 12 / Fusion 8 releases, OpenGL 3.3 is
  12 supported 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
  20 Otherwise, OpenGL 2.1 is supported.
  21
  22 With the Fall 2018 Workstation 15 / Fusion 11 releases, additional
  23 features 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
  33 This requires version 2.15.0 or later of the vmwgfx kernel module and
  34 the VM must be configured for hardware version 16 or later.
  35
  36 OpenGL 3.3 support can be disabled by setting the environment variable
  37 SVGA_VGPU10=0. You will then have OpenGL 2.1 support. This may be useful
  38 to work around application bugs (such as incorrect use of the OpenGL 3.x
  39 core profile).
  40
  41 Most modern Linux distros include the SVGA3D driver so end users
  42 shouldn't be concerned with this information. But if your distro lacks
  43 the driver or you want to update to the latest code these instructions
  44 explain what to do.
  45
  46 For more information about the X components see these wiki pages at
  47 x.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
  53 Components
  54 ----------
  55
  56 The 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
  63 All of these components reside in the guest Linux virtual machine. On
  64 the 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
  68 Prerequisites
  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
  96 Depending on your Linux distro, other packages may be needed. Meson
  97 should tell you what's missing.
  98
  99 Getting the Latest Source Code
 100 ------------------------------
 101
 102 Begin 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
 144 Building 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
 271 Now try to load the kernel module by issuing
 272
 273 ::
 274
 275    sudo modprobe vmwgfx
 276
 277 Then type
 278
 279 ::
 280
 281    dmesg
 282
 283 to watch the debug output. It should contain a number of lines prefixed
 284 with "[vmwgfx]".
 285
 286 Then restart the Xserver (or reboot). The lines starting with
 287 "vmwlegacy" or "VMWARE" in the file /var/log/Xorg.0.log should now have
 288 been replaced with lines starting with "vmwgfx", indicating that the new
 289 Xorg driver is in use.
 290
 291 Running OpenGL Programs
 292 -----------------------
 293
 294 In a shell, run 'glxinfo' and look for the following to verify that the
 295 driver 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
 303 If you don't see this, try setting this environment variable:
 304
 305 ::
 306
 307    export LIBGL_DEBUG=verbose
 308
 309 then rerun glxinfo and examine the output for error messages.
 310
 311 If 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".