From 86c7cfe589a51e1dd61b51879a2df46fe5de0691 Mon Sep 17 00:00:00 2001 From: Jonathan Rubenstein Date: Tue, 25 May 2021 05:43:34 -0400 Subject: [PATCH] [doc] Rerganize content into install and build pages --- doc/build.rst | 236 ++++++++++++++++++++++++++++++++++++ doc/conf.py | 3 + doc/faq.rst | 103 +++++++++++++++- doc/host.rst | 160 ------------------------ doc/index.rst | 1 + doc/install.rst | 309 +++++++++++++++-------------------------------- doc/obs.rst | 2 +- doc/tech_faq.rst | 15 --- 8 files changed, 438 insertions(+), 391 deletions(-) create mode 100644 doc/build.rst delete mode 100644 doc/host.rst diff --git a/doc/build.rst b/doc/build.rst new file mode 100644 index 00000000..6f2335b3 --- /dev/null +++ b/doc/build.rst @@ -0,0 +1,236 @@ +.. _building: + +Building +######## + +The following instructions will help you build Looking Glass for yourself +from source code. Before you attempt to do this, you should have a basic +understanding of how to use the shell. + +.. _download_source: + +Downloading +----------- + +Either visit the Looking Glass website's `Download +Page `_, or pull the lastest **bleeding-edge +version** with ``git``. + +.. code:: bash + + git clone --recursive https://github.com/gnif/LookingGlass.git + +.. warning:: + + Please only clone from Git if you're a developer, and know what you're + doing. Looking Glass requires git submodules that must be setup and updated + when building. Source code downloads from the website come bundled with the + necessary submodules. + +.. note:: + + When using the latest bleeding-edge client version, + you *MUST* download and install the corresponding host application. + +.. _build_client_section: + +Client +------ + +.. _installing_build_dependencies: + +Installing Build Dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These required libraries and tools should be installed first. + +.. _client_dependencies: + +Required Dependencies +^^^^^^^^^^^^^^^^^^^^^ + +- cmake +- gcc \| clang +- fonts-freefont-ttf +- libegl-dev +- libgl-dev +- libfontconfig1-dev +- libgmp-dev +- libsdl2-dev +- libsdl2-ttf-dev +- libspice-protocol-dev +- make +- nettle-dev +- pkg-config + +.. _may_be_disabled: + +May be disabled +<<<<<<<<<<<<<<< + +These dependencies are required by default, but may be omitted if their +feature is disabled when running :ref:`cmake `. + +- Disable with ``cmake -DENABLE_BACKTRACE=no`` + + - binutils-dev + +- Disable with ``cmake -DENABLE_X11=no`` + + - libx11-dev + - libxfixes-dev + - libxi-dev + - libxss-dev + +- Disable with ``cmake -DENABLE_WAYLAND=no`` + + - libwayland-bin + - libwayland-dev + - wayland-protocols + +You can fetch these dependencies on Debian systems with the following command: + +``apt-get install binutils-dev cmake fonts-freefont-ttf libfontconfig1-dev +libsdl2-dev libsdl2-ttf-dev libspice-protocol-dev libx11-dev nettle-dev +wayland-protocols`` + + +.. _client_building: + +Building +~~~~~~~~ + +If you've downloaded the source code as a zip file, simply unzip and cd into the +new directory. If you've cloned the repo with ``git``, then ``cd`` into the +'LookingGlass' directory. + +.. code:: bash + + mkdir client/build + cd client/build + cmake ../ + make + +Should this all go well, you will build the **looking-glass-client**. + +.. seealso:: + + :ref:`Installing the Client ` + +.. note:: + + The most common compile error is related to backtrace support. This can be + disabled by adding the following option to the cmake command: + **-DENABLE_BACKTRACE=0**, however, if you disable this and need support for a + crash please be sure to use gdb to obtain a backtrace manually or there is + nothing that can be done to help you. + +.. _host_building: + +Host +---- + +These instructions help you build the host yourself from the :ref:`downloaded +source code `. + +.. warning:: + Building the host from source code is not recommended for most purposes, + and should only be attempted by users who are prepared to handle issues + on their own. Please download the pre-built binary installers from + https://looking-glass.io/downloads for stability, and increased support. + +.. note:: + The pre-built binaries also include NvFBC support built in, which is + only available to current Nvidia SDK license holders, and cannot + be enabled when building the host without also having a license. + +.. _host_win_on_win: + +For Windows on Windows +~~~~~~~~~~~~~~~~~~~~~~ + +1. Download and install msys2 x86_64 from + `http://www.msys2.org/ `__ following the setup + instructions provided +2. Run the MSYS2 shell. +3. Download build dependencies with pacman + +.. code:: bash + + pacman -Fy + pacman -Sy git make mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake + +4. Checkout the project + +.. code:: bash + + git clone https://github.com/gnif/LookingGlass.git + +5. Configure the project and build it + +.. code:: bash + + mkdir LookingGlass/host/build + cd LookingGlass/host/build + cmake -G "MSYS Makefiles" .. + make + +.. _host_linux_on_linux: + +For Linux on Linux +~~~~~~~~~~~~~~~~~~ + +Make a ``host/build`` direstory, then run ``cmake`` + +.. code:: bash + + cd host + mkdir build + cd build + cmake .. + make + +.. _host_win_cross_on_linux: + +For Windows cross compiling on Linux +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Like :ref:`host_linux_on_linux`, but specifying the mingw64 toolchain in cmake +for building. + +.. code:: bash + + cd host + mkdir build + cd build + cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-mingw64.cmake .. + make + +.. _host_build_installer: + +Building the Windows installer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. :ref:`Build ` the host for Linux. + +2. Install ``nsis`` + +.. code:: bash + + apt-get install nsis + +3. Use ``makensis`` to build the installer. + +.. code:: bash + + cd host/build/platform/Windows + makensis installer.nsi + +.. _host_questions: + +This will build ``looking-glass-host-setup.exe`` under +``host/build/platform/Windows/looking-glass-host-setup.exe`` + +.. seealso:: + + :ref:`Installing the Host ` diff --git a/doc/conf.py b/doc/conf.py index ace1041a..a04aff11 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -24,6 +24,9 @@ author = 'Geoffrey McRae and the Looking Glass team' # The full version, including alpha/beta/rc tags release = 'B4' +rst_prolog = """ +.. |license| replace:: GPLv2 +""" # -- General configuration --------------------------------------------------- diff --git a/doc/faq.rst b/doc/faq.rst index 8a34c0ac..dd1ddedb 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -150,8 +150,7 @@ Another popular solution is to use pipes audio through the network. A guide for setting up scream is available on the wiki: https://looking-glass.io/wiki/Using_Scream_over_LAN - - +.. _faq_win: Windows ------- @@ -171,3 +170,103 @@ The screen stops updating when left idle for a time Windows is likely turning off the display to save power, you can prevent this by adjusting the \`Power Options\` in the control panel. + +.. _faq_host: + +Host +---- + +Where is the log? +~~~~~~~~~~~~~~~~~ + +The log file for the host application is located at:: + + %ProgramData%\Looking Glass (host)\looking-glass-host.txt + +You can also find out where the file is by right clicking on the tray +icon and selecting "Log File Location". + +The log file for the looking glass service is located at:: + + %ProgramData%\Looking Glass (host)\looking-glass-host-service.txt + +This is useful for troubleshooting errors related to the host +application not starting. + +High priority capture using DXGI and Secure Desktop (UAC) capture support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default Windows gives priority to the foreground application for any +GPU work which causes issues with capture if the foreground application +is consuming 100% of the available GPU resources. The looking glass host +application is able to increase the kernel GPU thread to realtime +priority which fixes this, but in order to do so it must run as the +``SYSTEM`` user account. To do this, Looking Glass needs to run as a +service. This can be accomplished by either using the NSIS installer +which will do this for you, or you can use the following command to +Install the service manually: + +:: + + looking-glass-host.exe InstallService + +To remove the service use the following command: + +:: + + looking-glass-host.exe UninstallService + +This will also enable the host application to capture the secure desktop +which includes things like the lock screen and UAC prompts. + +.. _faq_host_admin_privs: + +Why does the host require Administrator privileges? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is intentional for several reasons. + +1. NvFBC requires a system wide hook to correctly obtain the cursor + position as NVIDIA decided to not provide this as part of the cursor + updates. +2. NvFBC requires administrator level access to enable the interface in + the first place. (WIP) +3. DXGI performance can be improved if we have this. (WIP) + +NvFBC (NVIDIA Frame Buffer Capture) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Why can't I compile NvFBC support into the host? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You must download and install the NVidia Capture SDK. Please note that +by doing so you will be agreeing to NVIDIA's SDK License agreement. + +*-Geoff* + +.. _a_note_about_ivshmem_and_scream_audio: + +Why doesn't Looking Glass work with Scream over IVSHMEM? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. warning:: + Using IVSHMEM with Scream may interfere with Looking Glass, as they may try + to use the same device. + +Please do not use the IVSHMEM plugin for Scream. +To fix this issue, use the default network transfer method. +The IVSHMEM method induces additional latency that is built into its +implementation. When using VirtIO for a network device the VM is already using +a highly optimized memory copy anyway so there is no need to make another one. + +If you insist on using IVSHMEM for Scream—despite its inferiority to the +default network implementation—the Windows Host Application can be told +what device to use. Create a ``looking-glass-host.ini`` file in the same +directory as the looking-glass-host.exe file. In it, you can use the +``os:shmDevice`` option like so: + +.. code:: INI + + [os] + shmDevice=1 + diff --git a/doc/host.rst b/doc/host.rst deleted file mode 100644 index 036511b9..00000000 --- a/doc/host.rst +++ /dev/null @@ -1,160 +0,0 @@ -Looking Glass Host -################## - -.. _host_building: - -Building --------- - -For Windows on Windows -~~~~~~~~~~~~~~~~~~~~~~ - -1. Download and install msys2 x86_64 from - `http://www.msys2.org/ `__ following the setup - instructions provided -2. Run the MSYS2 shell. -3. Download build dependencies with pacman - -.. code:: bash - - pacman -Fy - pacman -Sy git make mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake - -4. Checkout the project - -.. code:: bash - - git clone https://github.com/gnif/LookingGlass.git - -5. Configure the project and build it - -.. code:: bash - - mkdir LookingGlass/host/build - cd LookingGlass/host/build - cmake -G "MSYS Makefiles" .. - make - -.. _host_linux_on_linux: - -For Linux on Linux -~~~~~~~~~~~~~~~~~~ - -Make a ``host/build`` direstory, then run ``cmake`` - -.. code:: bash - - cd host - mkdir build - cd build - cmake .. - make - -.. _host_win_cross_on_linux: - -For Windows cross compiling on Linux -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Like :ref:`host_linux_on_linux`, but specifying the mingw64 toolchain in cmake -for building. - -.. code:: bash - - cd host - mkdir build - cd build - cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-mingw64.cmake .. - make - -Building the Windows installer ------------------------------- - -1. :ref:`Build ` the host for Linux. - -2. Install ``nsis`` - -.. code:: bash - - apt-get install nsis - -3. Use ``makensis`` to build the installer. - -.. code:: bash - - cd host/build/platform/Windows - makensis installer.nsi - -.. _host_questions: - -This will build ``looking-glass-host-setup.exe`` under -``host/build/platform/Windows/looking-glass-host-setup.exe`` - -Questions and Answers ---------------------- - -Where is the log? -~~~~~~~~~~~~~~~~~ - -The log file for the host application is located at:: - - %ProgramData%\Looking Glass (host)\looking-glass-host.txt - -You can also find out where the file is by right clicking on the tray -icon and selecting "Log File Location". - -The log file for the looking glass service is located at:: - - %ProgramData%\Looking Glass (host)\looking-glass-host-service.txt - -This is useful for troubleshooting errors related to the host -application not starting. - -High priority capture using DXGI and Secure Desktop (UAC) capture support -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default Windows gives priority to the foreground application for any -GPU work which causes issues with capture if the foreground application -is consuming 100% of the available GPU resources. The looking glass host -application is able to increase the kernel GPU thread to realtime -priority which fixes this, but in order to do so it must run as the -``SYSTEM`` user account. To do this, Looking Glass needs to run as a -service. This can be accomplished by either using the NSIS installer -which will do this for you, or you can use the following command to -Install the service manually: - -:: - - looking-glass-host.exe InstallService - -To remove the service use the following command: - -:: - - looking-glass-host.exe UninstallService - -This will also enable the host application to capture the secure desktop -which includes things like the lock screen and UAC prompts. - -Why does this version require Administrator privileges? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is intentional for several reasons. - -1. NvFBC requires a system wide hook to correctly obtain the cursor - position as NVIDIA decided to not provide this as part of the cursor - updates. -2. NvFBC requires administrator level access to enable the interface in - the first place. (WIP) -3. DXGI performance can be improved if we have this. (WIP) - -NvFBC (NVIDIA Frame Buffer Capture) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Why can't I compile NvFBC support into the host? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You must download and install the NVidia Capture SDK. Please note that -by doing so you will be agreeing to NVIDIA's SDK License agreement. - -*-Geoff* - diff --git a/doc/index.rst b/doc/index.rst index 520a2d93..6eb2d09a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -11,6 +11,7 @@ systems for legacy programs that require high-performance graphics. :maxdepth: 2 install + build troubleshooting obs module diff --git a/doc/install.rst b/doc/install.rst index d9537b6f..7d2b2aec 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -1,130 +1,23 @@ +.. _installing: + Installation ############ -.. _looking_glass_client: +.. _client_install: -Looking Glass Client --------------------- +Client +------ -This guide will step you through building the looking glass client from -source, before you attempt to do this you should have a basic -understanding of how to use the shell. +The Looking Glass Client recieves frames from the :ref:`host_install` to +display on your screen. It also handles input, and can optionally share the +system clipboard with your guest OS through Spice. -.. _building_the_application: +First you must build the client from source code, see :ref:`building`. -Building the Application -~~~~~~~~~~~~~~~~~~~~~~~~ +After this, you may move the client into a directory in your path, some may +allow ``~/.local/bin``, or run it directly from the build directory. -.. _installing_build_dependencies: - -Installing Build Dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -These required libraries and tools should be installed first. - -.. _required_dependencies: - -Required Dependencies -''''''''''''''''''''' - -- cmake -- gcc \| clang -- fonts-freefont-ttf -- libegl-dev -- libgl-dev -- libfontconfig1-dev -- libgmp-dev -- libsdl2-dev -- libsdl2-ttf-dev -- libspice-protocol-dev -- make -- nettle-dev -- pkg-config - -.. _may_be_disabled: - -May be disabled -<<<<<<<<<<<<<<< - -These dependencies are required by default, but may be omitted if their -feature is disabled when running :ref:`cmake `. - -- Disable with ``cmake -DENABLE_BACKTRACE=no`` - - - binutils-dev - -- Disable with ``cmake -DENABLE_X11=no`` - - - libx11-dev - - libxfixes-dev - - libxi-dev - - libxss-dev - -- Disable with ``cmake -DENABLE_WAYLAND=no`` - - - libwayland-bin - - libwayland-dev - - wayland-protocols - -You can fetch these dependencies on Debian systems with the following command: - -``apt-get install binutils-dev cmake fonts-freefont-ttf libfontconfig1-dev -libsdl2-dev libsdl2-ttf-dev libspice-protocol-dev libx11-dev nettle-dev -wayland-protocols`` - -Downloading -^^^^^^^^^^^ - -Either visit the Looking Glass website's `Download -Page `_, or pull the lastest **bleeding-edge -version** with ``git``. - -.. code:: bash - - git clone --recursive https://github.com/gnif/LookingGlass.git - -.. warning:: - - Please only clone from Git if you're a developer, and know what you're - doing. Looking Glass requires git submodules that must be setup and updated - when building. Source code downloads from the website come bundled with the - necessary submodules. - -.. note:: - - When using the latest bleeding-edge client version, - you *MUST* download and install the corresponding host application. - -.. _client_building: - -Building -^^^^^^^^ - -If you've downloaded the source code as a zip file, simply unzip and cd into the -new directory. If you've cloned the repo with ``git``, then ``cd`` into the -'LookingGlass' directory. - -.. code:: bash - - mkdir client/build - cd client/build - cmake ../ - make - -.. note:: - - The most common compile error is related to backtrace support. This can be - disabled by adding the following option to the cmake command: - **-DENABLE_BACKTRACE=0**, however, if you disable this and need support for a - crash please be sure to use gdb to obtain a backtrace manually or there is - nothing that can be done to help you. - -Should this all go well, you will build the **looking-glass-client**. -Before you run the client, you will first need -to configure either libvirt, or QEMU (whichever you prefer) then set -up the **looking-glass-host** service in your VM. - -.. _libvirt_configuration: +.. _client_libvirt_configuration: libvirt Configuration ~~~~~~~~~~~~~~~~~~~~~ @@ -149,9 +42,9 @@ your virtual machine. The memory size (show as 32 in the example above) may need to be -adjusted as per the :ref:`Determining Memory ` section. +adjusted as per the :ref:`Determining Memory ` section. -.. _spice_server: +.. _client_spice_server: Spice Server ^^^^^^^^^^^^ @@ -179,6 +72,8 @@ along with clipboard sync support, make sure you have a If you want clipboard synchronization please see :ref:`how_to_enable_clipboard_synchronization_via_spice` +.. _client_apparmor: + AppArmor ^^^^^^^^ @@ -189,7 +84,7 @@ can be done by adding the following to ``/dev/shm/looking-glass rw,`` -.. _qemu_commands: +.. _client_qemu_commands: Qemu Commands ~~~~~~~~~~~~~ @@ -205,9 +100,9 @@ the ``bus`` parameter to suit your particular configuration: -object memory-backend-file,id=ivshmem,share=on,mem-path=/dev/shm/looking-glass,size=32M The memory size (shown as 32M in the example above) may need to be -adjusted as per :ref:`Determining Memory ` section. +adjusted as per :ref:`Determining Memory ` section. -.. _determining_memory: +.. _client_determining_memory: Determining Memory ~~~~~~~~~~~~~~~~~~ @@ -228,7 +123,7 @@ For example, for a resolution of 1920x1080 (1080p): You must round this value up to the nearest power of two, which for the provided example is 32MB. -.. _shared_memory_file_permissions: +.. _client_shmfile_permissions: Shared Memory File Permissions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -251,94 +146,6 @@ with the following:: Change ``UID`` to the user name you will run Looking Glass with, usually your own. -.. _looking_glass_service_windows: - -Looking Glass Service (Windows) -------------------------------- - -You must first run the Windows VM with the changes noted above in either -the :ref:`libvirt_configuration` or :ref:`qemu_commands` sections. - -.. _installing_the_ivshmem_driver: - -Installing the IVSHMEM Driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Windows will not prompt for a driver for the IVSHMEM device, instead, it -will use a default null (do nothing) driver for the device. To install -the IVSHMEM driver you will need to go into the device manager and -update the driver for the device "PCI standard RAM Controller" under the -"System Devices" node. - -A signed Windows 10 driver can be obtained from Red Hat for this device -from the below address: - -https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/upstream-virtio/ - -Please note that you must obtain version 0.1.161 or later. - -If you encounter warnings or errors about driver signatures, ensure secure boot -is turned off in the bios/uefi settings of your virtual machine. - -.. _a_note_about_ivshmem_and_scream_audio: - -A note about IVSHMEM and Scream Audio -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. warning:: - Using IVSHMEM with Scream may interfere with Looking Glass, as they may try - to use the same device. - -Please do not use the IVSHMEM plugin for Scream. -Use the default network transfer method. The IVSHMEM method induces -additional latency that is built into its implementation. When using -VirtIO for a network device the VM is already using a highly optimized -memory copy anyway so there is no need to make another one. - -If you insist on using IVSHMEM for Scream—despite its inferiority to the -default network implementation—the Windows Host Application can be told -what device to use. Create a ``looking-glass-host.ini`` file in the same -directory as the looking-glass-host.exe file. In it, you can use the -``os:shmDevice`` option like so: - -.. code:: INI - - [os] - shmDevice=1 - -.. _using_the_windows_host_application: - -Using the Windows Host Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Start by downloading the correct version for your release from -https://looking-glass.io/downloads. You can either choose between -**Official Releases**, which are stable; or **Release Candidates**, new versions -about to be stable, but haven't passed validation. - -.. note:: - If your **looking-glass-client** was created by building from the **master - branch** you have to pick the **Bleeding Edge** version. - -Next, extract the zip archive using the commit hash for the password. -Then, run the ``looking-glass-host-setup.exe`` installer and install the host. -By default, the installer will install a service that -automatically starts the host application at boot. The installer can -also be installed in silent mode with the ``/S`` switch. You can find other -command line options with the ``/h`` switch. - -The windows host application captures the windows desktop and stuffs the -frames into the shared memory via the shared memory virtual device, -without this Looking Glass will not function. It is critical that the -version of the host application matches the version of the client -application, as differing versions can be, and usually are, -incompatible. - -.. note:: - As of 2020-10-23, Microsoft Defender is known to mark the - Looking-Glass host executable as a virus and in some cases will - automatically delete the file. - .. _client_usage: Usage @@ -607,3 +414,79 @@ The following is a complete list of options accepted by this application +=====================+=======+=======+=======================+ | wayland:warpSupport | | yes | Enable cursor warping | +---------------------+-------+-------+-----------------------+ + +.. _host_install: + +Host +---- + +The Looking Glass Host captures frames from the guest OS using a capture API, +and sends these frames to the :ref:`client_install`, be it on the host OS +(hypervisor) or another Virtual Machine, through a low-latency transfer +protocol over shared memory. + +You can get the host program in two ways: + +- Download a pre-built binary from https://looking-glass.io/downloads + (**recommended**) + +- Download the source code as described in :ref:`building`, then + :ref:`build the host `. + +.. _host_install_windows: + +Windows +~~~~~~~ + +To begin, you must first run the Windows VM with the changes noted above in +either the :ref:`client_libvirt_configuration` or :ref:`client_qemu_commands` +sections. + +.. _installing_the_ivshmem_driver: + +Installing the IVSHMEM Driver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Windows will not prompt for a driver for the IVSHMEM device, instead, it +will use a default null (do nothing) driver for the device. To install +the IVSHMEM driver you will need to go into the device manager and +update the driver for the device "PCI standard RAM Controller" under the +"System Devices" node. + +A signed Windows 10 driver can be obtained from Red Hat for this device +from the below address: + +https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/upstream-virtio/ + +Please note that you must obtain version 0.1.161 or later. + +If you encounter warnings or errors about driver signatures, ensure secure boot +is turned off in the bios/uefi settings of your virtual machine. + +.. _host_install_service: + +Installing the Looking Glass Service +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After installing your IVSHMEM driver, we can now install the Looking Glass Host +onto our Windows Virtual Machine. + +1. First, run ``looking-glass-host-setup.exe`` as an administrator + (:ref:`Why? `) +2. You will be greeted by an intro screen. Press ``Next`` to continue. +3. You are presented with the |license| license. Please read and agree to the + license by pressing ``Agree``. +4. You can change the install path if you wish, otherwise press ``Next`` to + continue. +5. You may enable or disable options on this screen to configure the + installation. The default values are recommended for most users. + Press ``Install`` to begin installation. +6. After a few moments, installation will complete, and you will have a + running instance of Looking Glass. If you experience failures, you can + see them in the install log appearing in the middle of the window. +7. Press ``Close`` to exit the installer. + +Command line users can run ``looking-glass-host-setup.exe /S`` to execute a +silent install with default options selected. Further configuration from the +command line can be done with flags. You can list all available flags by +running ``looking-glass-host-setup.exe /?``. diff --git a/doc/obs.rst b/doc/obs.rst index 550c9563..8f0ec049 100644 --- a/doc/obs.rst +++ b/doc/obs.rst @@ -14,7 +14,7 @@ Build Instructions The OBS plugin is included in the main source tree of Looking Glass. The building process is very similar to the -:ref:`client's `. +:ref:`client's `. Dependencies ^^^^^^^^^^^^ diff --git a/doc/tech_faq.rst b/doc/tech_faq.rst index f1090842..3c0a8726 100644 --- a/doc/tech_faq.rst +++ b/doc/tech_faq.rst @@ -64,18 +64,3 @@ Initially, we were using interrupts in early designs however it became clear that the performance, especially for high update rate mice was extremely poor. This may have improved in recent QEMU versions and perhaps should be re-evaluated at some point. - -.. _how_do_i_build_the_host: - -How do I build the looking-glass-host? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is not recommended to build the looking-glass-host program, and instead -download it from the `website `_. However, -if you know what you're doing, you can follow the -:doc:`build instructions `. - -.. toctree:: - :hidden: - - host