% HybridGraphics -- Support for hybrid graphics laptops. % % Please check the Psychtoolbox website and Wiki for up to date % information about the state of HybridGraphics. This document % may contain obsolete information quite quickly on this fast % changing topic, especially on Linux. % % BACKGROUND: % ----------- % % Hybrid graphics laptops are laptops which have two built-in % graphics cards (GPUs). One card is usually an integrated % graphics chip (iGPU) which has a low power consumption and % heat production, allowing for a cool laptop and long battery % runtime, but it also has relatively low performance. This chip % is sufficient for typical desktop GUI use, watching videos and % other light graphics applications. The 2nd card, called discrete % GPU (dGPU), provides much higher performance but consumes more % power and produces more heat, so the laptop runs hotter and/or % needs more cooling, all resulting in shorter battery runtimes. % % The idea is to use the dGPU for performance hungry graphics % intense applications, and the iGPU for day to day tasks, % selecting either for high performance or long battery runtimes. % % These laptops come in two basic flavors, hardware multiplexed % (muxed) and non-multiplexed (muxless). Muxed laptops have an % electronic switch that can connect the iGPU or dGPU to the video % outputs (internal flat panel and external video connectors like % MiniDisplayPort or HDMI or DVI or VGA). The switch is software % controlled and allows selection of which gpu is driving the % displays, the other gpu is powered down for maximum power saving. % % OSX, Linux on Apple hardware and on other muxed Laptops: % -------------------------------------------------------- % % As of 2016, all past and current laptops from Apple (MacBookPro % line) are muxed. When using Mac OSX, the operating system controls % the mux to select an appropriate gpu. For light desktop and 2D use, % the iGPU is active. Whenever a 3D application starts up, e.g., % Psychtoolbox, the iGPU gets disconnected and powered down and the % dGPU gets powered up and connected. From the perspective of % Psychtoolbox there essentially is only one GPU, which is the dGPU, % either a NVidia or AMD graphics card. Apart from a couple of rather % horrible bugs, e.g., for the 2010 MacBookPro with some recent versions % of OSX, this means that hybrid graphics under OSX usually "just works". % % If one uses an Apple MacBookPro under Linux then the machine will run % with either the dGPU active and the Laptop behaves like a machine with % one gpu, or the active gpu can be switched via the Linux "vgaswitcheroo" % mechanism. The same applies for other PC laptops which are equipped % with a mux. Iow. one can manually select the performance vs. power % consumption tradeoff. % % Most modern common PC laptops are muxless though. The iGPU is hard-wired to % the video outputs, both to the laptop flat panel and the external outputs. % The iGPU is always active and drives the displays and takes care of drawing % the GUI and handling 2D applications. The dGPU can be powered up as needed % to handle GPGPU computations and the rendering for more demanding 2D, Video % and 3D applications. As the dGPU is not connected to the display outputs, it % has to copy its rendered images into the RAM of the iGPU and the iGPU then % displays the images on behalf of the dGPU. This involves some significant % overhead: Multiple milliseconds of time are needed for each Screen('Flip') to % copy image data from the dGPU to the iGPU, and converting the data into a format % the iGPU can display. For this reason, display latency on a muxless laptop % will always be longer and absolute graphics performance lower than on a laptop % which only has a dGPU, or on a muxless laptop. A big problem is the need to % properly synchronize the rendering of the dGPU with the display of the iGPU. % Depending on how this synchronization or handshake is implemented, visual % stimulus onset timing and timestamping can be highly unreliable and inaccurate. % % WINDOWS: % -------- % % On Microsoft Windows a handshake method is used which maintains good framerates % for video games and similar applications, but causes visual stimulus onset timing % and timestamping to be almost always completely wrong, with observed errors in % the range of +/- 33 msecs on a 60 Hz panel. That means that the dGPU is unuseable % if visual timing matters in any way. The best you can do on a muxless laptop under % Microsoft Windows is to configure the driver to disable the dGPU and only use the % iGPU for all rendering, and then hope that the iGPU graphics driver isn't too buggy, % a hope that is often unjustified, especially if the iGPU is an Intel graphics chip. % Intel graphics has timing bugs itself quite often on MS-Windows, even on regular % single gpu laptops. % % LINUX: % ------ % % On Linux, as of August 2017, good progress has been made in implementing methods % which provide both good performance *and* reliable, trustworthy, accurate visual % timing and timestamping. Some - but not all! - types of Laptop hardware should % work well, but for all of them some special configuration or software upgrades % are needed. % % We recommend XServer version 1.19.3 or later, and Mesa version 13 or later, and % Linux 4.10 or later, as this combination provides best performance and ease of % setup for all supported types of hybrid graphics laptops. Users of Ubuntu Linux % can simply install Ubuntu 16.04.6 LTS (or Ubuntu 18.04-LTS and later) from fresh % installation media, or upgrade to 16.04.6 LTS from earlier Ubuntu releases and then % install the new hardware enablement stack (HWE) via ... % % sudo apt install --install-recommends linux-lowlatency-hwe-16.04 xserver-xorg-hwe-16.04 % % ... if it isn't already automatically installed after an upgrade to 16.04.4 LTS. % % The following sections describe the current level and quality of support for different % types of hybrid graphics laptops, and required configuration steps, assuming you have % sufficiently up to date kernel, X-Server and Mesa as explained in the previous paragraph. % Psychtoolbox would tell you if you need to upgrade your kernel, if you'd run it on a % muxless hybrid graphics Laptop. % % % * Laptops with an Intel iGPU combined with a NVidia dGPU ("NVidia Optimus" models): % % These should work perfectly if you use the "nouveau" open-source graphics driver, % at least as far as testing with three different laptops went. Stimuli are displayed % without any artifacts, and timing and timestamping is accurate and trustworthy. % Performance is highly dependent on the model of NVidia gpu though, with the latest % generations currently providing only relatively low performance, and ongoing work % to improve the performance for recent models. % % If you want to use the NVidia proprietary display driver for Linux instead, there % now exists a solution which works with correct timing and timestamping, as verified % on two Optimus Laptops, a Lenovo Lenovo Ideapad Z50-70 with GeForce 840M and a Razer % Blade 2016 with GeForce 1060M. However, the solution is less flexible and power-efficient % than use of the "nouveau" open-source driver. It requires some setup work, and it needs % a NVidia proprietary driver of at least version 375.66. If you can't select a recent % enough driver of at least version 375.66, you need to enable the proprietary graphics % driver ppa to get a convenient update to NVidia driver version 375.66 or later versions. % Also, you must use a X-Server of the 1.19.x series, the v1.20 servers are not yet supported. % Follow the following steps to get Optimus set up: % % 1. Install the proprietary graphics drivers ppa by typing in a terminal: % sudo add-apt-repository ppa:graphics-drivers/ppa % sudo apt-get update % % 2. Then launch the 3rd party driver manager GUI to select the NVidia proprietary driver % for use on your system. You must select a NVidia proprietary driver of the 375 series, % with a version number of 375.66 or later. This will also automatically setup standard % Optimus / PRIME support for tear-free stimulus display, but getting proper visual % stimulation timing and timestamping for Psychtoolbox requires some more steps. % % 3. Edit the file /etc/modprobe.d/nvidia-graphics-drivers.conf. Modify the last line % in that file and replace the assignment modeset=0 with modeset=1 to enable drm % modesetting support. % % 4. Execute "sudo update-initramfs -u -k all" in a terminal. % NOTE: You may need to repeat both steps 3 and 4 every time after a significant upgrade % of your distributions software. Otherwise Psychtoolbox may complain about timing and % synchronization problems after such an upgrade. % % 5. Copy the custom Psychtoolbox modesetting driver into the system driver directory. % There are two variants, the nolag variant and the highlag variant. In theory, the % nolag variant would be preferrable, but it sometimes gives inconsistent performance: % % sudo cp /pathto/Psychtoolbox/PsychHardware/LinuxDrivers/NVidiaOptimus/modesetting_drv.so /usr/lib/xorg/extra-modules/modesetting_drv.so % % For use of the variant with higher lag but consistent performance, use the highlag driver % instead: % % sudo cp /pathto/Psychtoolbox/PsychHardware/LinuxDrivers/NVidiaOptimus/modesetting_drv.so_highlag /usr/lib/xorg/extra-modules/modesetting_drv.so % % 6. Reboot. Now your system should be ready for research compatible Optimus. % % On Ubuntu, the "nvidia-settings" GUI tool allows you to switch between Optimus (PRIME) and % standard Intel graphics. The section "PRIME profiles" allows to click on a toggle button % to switch between "NVidia" gpu for power hungry but fast Optimus, and "Intel" for low power % consumption lower performance mode. % % If you want to use a different distribution than Ubuntu, "Fedora 25" and later, "Debian unstable", % "Arch Linux" and "SuSE Tumbleweed" are known to ship required X-Server, Linux kernel and NVidia % driver options for Optimus. However, these are not tested with PTB, and setup may be different % from Ubuntu's approach. Alternatively you could also download and compile your own X-Server 1.19 % if you are not afraid of compilers and Makefiles and willing to spend a workday doing this. The % following paragraph assumes you are not using Ubuntu 17.04: % % Once you have a X-Server 1.19 up and running, you will need the NVidia proprietary % display drivers of version 375.66 or later for 64-Bit Intel processors. Then you need % to copy various configuration files into various places, and adapt some of these files % to your specific system. Finally you need to install a custom xf86-video-modesetting % display driver onto your system. This modesetting driver is specifically made to % interoperate with Psychtoolbox to provide research grade precision timing and % timestamping. Then, after a reboot, you may be rewarded with a NVidia Optimus laptop % which can efficiently use your discrete high-performance NVidia gpu with research grade % timing. However, research grade timing is only provided for pure single-display setups, % not for any kind of multi-display operation. That means your Laptop can have exactly % one display enabled, either the Laptop internal flat-panel, or one externally connected % display. Also timing is only reliable and trustworthy for a Psychtoolbox fullscreen % window. You will find all the needed config files and custom made display driver and % setup instructions in the Psychtoolbox subdirectory Psychtoolbox/PsychHardware/LinuxDrivers/NVidiaOptimus/ % % See the following thread for the current state of the NVidia proprietary implementation % and for some more nice background info on the challenges of proper handshaking and % synchronization on muxless laptops: % % https://devtalk.nvidia.com/default/topic/957814/linux/prime-and-prime-synchronization % % % * Laptops with an Intel iGPU combined with an AMD dGPU ("AMD Enduro" models): % % These should work very well out of the box on Ubuntu 16.04.3 LTS and later, as explained % above. % % On other Linux distributions make sure to install Linux 4.8.11 or later versions of the Linux % kernel, together with X-Server 1.18 or later, and Mesa version 17.0 or later. % % AMD Enduro hybrid graphics was tested with two PC setups: % % - Intel HD "Haswell desktop" graphics chip + AMD Radeon R9 380 Tonga Pro. % - Intel HD "Ivybridge desktop" graphics chip + AMD FireGL "Cedar". % % Stimuli are displayed without any artifacts and timing and timestamping is accurate and % trustworthy. % % % * Laptops with dual NVidia gpus NVidia iGPU + NVidia dGPU: % % Muxless would not work with any current official solution [1]. However, i am not aware of % any recent muxless laptops - or any such muxless laptops actually - which use dual-NVidia % gpus. All known dual-NVidia laptops are rather old and use a hardware mux, so Linux % "vgaswitcheroo" mechanism can be used to switch between gpus for perfect results. % % % * Laptops with dual AMD gpus AMD iGPU + AMD dGPU ("AMD Enduro" models): % % Muxless won't work with any current official solution, so you can only use the % AMD iGPU [1]. % % % For those combinations that should work (Intel iGPU + NVidia/AMD dGPU "Optimus/Enduro"), % after you've upgraded to all the required software, the following setup steps are % needed for muxless PRIME mode. Note that these *do not apply* to Optimus with the proprietary % graphics driver from NVidia: % % 1. Run the "XOrgConfCreator" script to create a proper XOrg configuration file, % and then "XOrgConfSelector" to switch to that configuration file, logout and % login again. % % 2. Tell Matlab or Octave to use the dGPU for rendering with Psychtoolbox: % % - Either use the setenv('DRI_PRIME','1'); command before calling the first Screen() % command, e.g., by adding it to Matlabs startup.m script or Octaves ~/.octaverc % startup script. % % - Or copy the Psychtoolbox/PsychHardware/LinuxX11ExampleXorgConfs/_.drirc to the file % ~/.drirc and then customize it for your hardware to always select the dGPU for % rendering with Octave or Matlab. The file itself contains customization instructions. % The ... <\device> section in that file can also be included into the % global /etc/drirc file if it should apply to all users on a machine. % % 3. Optionally verify the handshaking and synchronization actually works. Psychtoolbox must not % report any timing or timestamping related errors or warnings, or other warnings % relating to hybrid graphics problems. Typical tests like PerceptualVBLSyncTest or % VBLSyncTest must work correctly. All demos should display without any visual artifacts, % tearing artifacts etc. % % Additionally you can use the Linux ftrace script i915_optimus_trace.sh in the % Psychtoolbox/PsychHardware/ folder. Instructions on how to use it are inside the % script. Running it while a Psychtoolbox stimulation script runs will measure the % timing of functions relevant for proper timing. The printout after 20 seconds should % show the function "reservation_object_wait_timeout_rcu" using a significant amount of % time, e.g., multiple thousand microseconds (usecs), e.g., % % 3) | intel_mmio_flip_work_func [i915]() { % 3) # 3060.318 us | reservation_object_wait_timeout_rcu(); % 3) # 3070.039 us | } % % Here the iGPU waited for 3060.318 usecs until the dGPU was done with its part % of the job. That's a realistic waiting time for simple visual stimuli, although % numbers could easily go up into the > 9 msecs range for more demanding stimuli or % slower gpus. Just to give you a perspective on the potential performance loss or % added latency compared to a single gpu laptop. % % [1] There also exist some muxless Laptop models where the iGPU is hard-wired to the internal % Laptop flat panel, whereas the dGPU is hard-wired to (some of) the external video outputs. % On these models one can configure a dual-x-screen setup for visual stimulation and then % assign the iGPU to drive X-Screen 0 on the internal panel and assign the dGPU to drive % X-Screen 1 on the external video outputs. % % This would work with high performance and timing precision even on hybrid graphics laptops % which otherwise wouldn't work, e.g., dual NVidia or dual AMD laptops. Such a setup % wouldn't require any of the setup steps mentioned above. Instead it would require to % create a dual-x-screen setup via XOrgConfCreator, but then to manually customize the % created config file, as XOrgConfCreator can't automatically handle such dual-gpu setups % yet. Ask for assistance on the Psychtoolbox user forum if you happen to have such a % laptop. One example xorg.conf file for handling such a setup (Intel iGPU + AMD dGPU) % can be found under the name xorg.conf_SeparateScreensDualGPUIntelAndAMD in the % Psychtoolbox/PsychHardware/LinuxX11ExampleXorgConfs/ folder. It would need customization % though for a given Laptop, specifically adapting the "BusID" parameter for your hardware. % % Another example X-Config file for such a laptop can be found for year 2016 Razer Blade gaming % laptop with Intel HD-530 Skylake iGPU + NVidia GeForce 1060M Pascal dGPU, where the Intel % iGPU is hardwired to the laptop panel and USB-C output, whereas the NVidia dGPU is hardwired % to a HDMI output. The filename in the Psychtoolbox/PsychHardware/LinuxX11ExampleXorgConfs/ % folder is xorg.conf_RazerBlade-2-XScreens-intel+nouveau % % Another X-Config example file for the Razer Blade 2016 is the file ... % xorg.conf_RazerBlade-2-XScreens-NVidiaProprietary_iGPUPrime+dGPUHDMInative.conf % ... This file is for use with the NVidia proprietary driver instead of the nouveau open-source % driver. It uses the NVidia gpu to drive two separate X-Screens 0 and 1. X-Screen 0 is driven % via Optimus PRIME output, displaying via the Intel HD 530 iGPU on either the laptop flatpanel % or the USB-C video output, but not both at the same time if visual stimulation timing matters. % X-Screen 1 is driven directly via the HDMI output connected to the NVidia dGPU. % % NOTE: If you copy these files into the /etc/X11/xorg.conf.d/ folder you must rename them to % end with the suffix .conf otherwise they won't be actually used!