quick-docs/en-US/bumblebee.adoc

= Bumblebee

'''

[IMPORTANT]
======

This page was automatically converted from https://fedoraproject.org/wiki/Bumblebee

It is probably

* Badly formatted
* Missing graphics and tables that do not convert well from mediawiki
* Out-of-date
* In need of other love

Pull requests accepted at https://pagure.io/fedora-docs/quick-docs

Once you've fixed this page, remove this notice, and update
`_topic_map.yml`.

Once the document is live, go to the original wiki page and replace its text
with the following macro:

....
{{#fedoradocs: https://docs.fedoraproject.org/whatever-the-of-this-new-page}}
....

======

'''


[[description]]
Description
~~~~~~~~~~~

Nvidia Optimus is an optimization technology created by Nvidia which,
depending on the resource load generated by client software
applications, will transparently and seamlessly switch between two
graphics adapters within a computer system in order to provide either
maximum performance or minimum power draw from the system's graphics
rendering hardware. From
https://github.com/Bumblebee-Project/Bumblebee/wiki/FAQ[Bumblebee's
FAQ]: Bumblebee is a effort to make Nvidia Optimus enabled laptops work
in GNU/Linux systems. Such feature involves two graphics cards with two
different power consumption profiles plugged in a layered way sharing a
single framebuffer.

The discrete GPU (NVidia) is turned off when not in use and activated
and turned on though ACPI calls when demanding OpenGL applications
require the extra power the discrete GPU can give. Demanding OpenGL
applications might include such things as 3D games or 3D rendering
software but would not include such things as a web browser or a video
playback program like mplayer or VLC.

[[how-can-you-tell-if-you-have-an-optimus-notebook-computer]]
How can you tell if you have an optimus notebook computer?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you purchased a notebook with an NVidia sticker on it, you _might_
have a optimus computer. If you don’t have an optimus technology
computer nothing in this documentation is relevant to your PC. (Optimus
was slated at one point to go in desktop PCs but the industry ended up
rejecting that concept…)

To tell, after you have installed the OS, open a terminal window and
type:

....
$ lspci | grep 'VGA\|3D'
....

If you see two video cards in the output like:

....
$ lspci | grep 'VGA\|3D'
00:02.0 VGA compatible controller: Intel Corporation HD Graphics 530 (rev 06)
02:00.0 3D controller: NVIDIA Corporation GM108M [GeForce 940MX] (rev a2)
....

And one is a Intel “Integrated Graphics Controller” and the other is a
“NVIDIA Corporation” chip, then you probably have an optimus notebook.

To further verify, if you have the two VGA devices with one as Intel
Integrated and other as NVIDIA, as root look for the
/sys/kernel/debug/vgaswitcheroo/switch file. If it exists, then you have
an optimus PC. If its missing, then you might not. (It might be that you
have a card that nouveau can’t use yet because it is too new…)

[[before-you-get-started]]
Before you get started
~~~~~~~~~~~~~~~~~~~~~~

Most users will want to turn off “Secure boot” in the bios or UEFI
screen when you need nvidia drivers or bbswitch-dkms. If you want to
make your own public / private keys for kernel module signing you can
look
https://docs.fedoraproject.org/en-US/Fedora/22/html/System_Administrators_Guide/sect-signing-kernel-module-with-the-private-key.html[here]
or
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System_Administrators_Guide/sect-signing-kernel-modules-for-secure-boot.html[here]
for more information on the subject. If you end up doing that and use
the closed source NVidia driver, you will need to edit the
/etc/bumblebee/bumblebee-nvidia-sign.conf file.

Next, do a dnf update before you begin. And just to be safe, reboot your
PC so that you are booted into the newest kernel. The reason for this is
that you want the kernel-devel package to match the kernel you are
running under. If you don’t reboot after a dnf update these versions may
differ which will cause compiling problems.

[[installation]]
Installation
~~~~~~~~~~~~

[[for-free-or-open-source-solution]]
For free or open source solution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Some users http://www.kroah.com/log/linux/stable_api_nonsense.html[feel
strongly] that they should not use closed source kernel modules. This is
understandable. In all cases,
http://nouveau.freedesktop.org/wiki/Optimus/[PRIME] will work better
then using bumblebee.

In fact, you can no longer use the bumblebee software with nouveau any
longer even if you want to. See
https://github.com/Bumblebee-Project/Bumblebee/issues/773[issue 773] for
further information about this subject. You *MUST USE PRIME*. The
nouveau driver already handles power saving nowadays so bumblebee would
just be superfluous…

[[for-closed-source-solution]]
For closed source solution
^^^^^^^^^^^^^^^^^^^^^^^^^^

Do not use the NVidia video drivers from *http://rpmfusion.org/*,
*http://negativo17.org/*. I’m sure they are fine drivers and I am not
trying to criticize them at all. But they *DO NOT support or work* with
bumblebee without modifications. I have created a pair of drivers
packages you may use that require no modifications to work. There is a
managed version which contains a reasonably recent “long lived branch”
driver blob. There is also a unmanaged repo which contains an empty
drivers package. The unmanaged version requires you to download a “blob”
from http://www.nvidia.com/object/unix.html[here] and then copy the file
manually to the /etc/sysconfig/nvidia/ directory as root. You might need
the “unmanaged” version if your laptop requires a “legacy” driver
version or if you need the “short lived branch” driver for some reason.
Do not install both the managed and unmanaged repos. You should pick one
or the other depending on your needs. If you are unsure which to use,
use the managed repo.

*Special note concerning versions 355.11-375.10:*

There is a bug which prevents certain versions from working with the
unmanaged version of the bumblebee-nvidia shell script wrapper. I have
opened a discussion thread
https://devtalk.nvidia.com/default/topic/885657/linux/can-t-install-driver-to-work-with-bumblebee-with-version-355-11/[here]
concerning this problem. See also
https://github.com/NVIDIA/nvidia-installer/issues/1[this issue] on
github.com. If you use a version older then 355.11 or newer then 375.10
you should be ok. If you need one in between those you’ll have to patch
and compile the nvidia-installer program yourself to get it to work.
You’d need to disable the symlink check and the runtime check within the
c code which is what we did for a while there with the “managed”
version.

[[for-closed-source-solution-fedora]]
For closed source solution fedora
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Add bumblebee repo:

....
# dnf -y --nogpgcheck install http://install.linux.ncsu.edu/pub/yum/itecs/public/bumblebee/fedora$(rpm -E %fedora)/noarch/bumblebee-release-1.2-1.noarch.rpm
....

Managed NVidia repo:

....
# dnf -y --nogpgcheck install http://install.linux.ncsu.edu/pub/yum/itecs/public/bumblebee-nonfree/fedora$(rpm -E %fedora)/noarch/bumblebee-nonfree-release-1.2-1.noarch.rpm
....

or Unmanaged NVidia repo:

....
# dnf -y --nogpgcheck install http://install.linux.ncsu.edu/pub/yum/itecs/public/bumblebee-nonfree-unmanaged/fedora$(rpm -E %fedora)/noarch/bumblebee-nonfree-unmanaged-release-1.2-1.noarch.rpm
....

'''Remember, you do not want to install both the managed and unmanaged
repos. Pick one or the other but not both! '''

No multilib fedora 23+:

....
# dnf install bumblebee-nvidia bbswitch-dkms primus kernel-devel
....

Multilib on a 64 bit install fedora 23+: (You may need to add additional
32 bit packages to get your 32 bit applications to work with
bumblebee/primus)

....
# dnf install bumblebee-nvidia bbswitch-dkms VirtualGL.x86_64 VirtualGL.i686 primus.x86_64 primus.i686 kernel-devel
....

You will need to reboot before you can test if its working. *If you used
the “unmanaged” repo don’t forget to copy the NVidia “blob” to
/etc/sysconfig/nvidia/ before you reboot!* Most folks will want the
“managed” version rather then the “unmanaged” version.

[[using-bumblebee-software]]
Using bumblebee software
~~~~~~~~~~~~~~~~~~~~~~~~

*General usage*

....
$ optirun [options] application [application-parameters]
....

For example, start a Windows applications with optimus named
application.exe:

....
$ optirun wine application.exe
....

For another example, open NVidia settings panel with optimus:

....
$ optirun -b none nvidia-settings -c :8
....

For another example, open the java based Minecraft with primus bridge:

....
$ optirun -b primus java -jar /PATH/TO/Minecraft.jar
....

For a list of the options for optirun, view its manual page:

....
$ man optirun
....

In general, using the primus bridge gives better performance then using
the default VirtualGL bridge. In bumblebee 4.0 (coming soon) primus will
become the default bridge and VirtuaGL will need to be called explicitly
if you still want it. Also beginning with bumblebee 4.0 (coming soon)
the VirtuaGL dependency will be replaced with a primus dependency
instead. So you might not even have VirtuaGL installed by default in the
future.

For primus, there is a separate shell script you can use to invoke it
called “primusrun.”

For a list of the options for primusrun, view its manual page:

....
$ man primusrun
....

....
$ primusrun java -jar /PATH/TO/Minecraft.jar
....

and

....
$ optirun -b primus java -jar /PATH/TO/Minecraft.jar
....

are functionally equivalent commands.

It may become tedious to always use the optirun program in a terminal to
launch 3D games or other 3D opengl applications. You may wish to create
desktop launchers which use the optirun or primusrun commands in order
to streamline this process.

For example, in MATE desktop environment, when you right click on an
empty space in the desktop a popup menu is displayed. One option on this
menu is “Create launcher..” which allows you to create a graphical
launcher icon for your apps which can be left on the desktop or moved
into some folder. Other desktop environments also offer this
functionality though the methods differ from desktop to desktop.

[[multi-monitor-setup-with-closed-driver]]
Multi monitor setup with closed driver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Optimus laptops have two video chips: an integrated Intel and a discrete
NVidia one. If the port (DisplayPort / HDMI / VGA) is wired to the Intel
chip, you do not need to do anything special to get external monitors to
work.

When the external port is wired into the NVidia chip, you cannot
currently expand the screen over monitors without extra effort. Read on
if you fall into this category…

Install the intel-gpu-tools package.

....
# dnf install intel-gpu-tools
....

Running ‘intel-virtual-output’ (from the intel-gpu-tools rpm) without
any extra parameters will daemonize itself and detect attached displays
in the background. It will then perform all the trickery of virtualizing
and cloning so that the newly attached screen can be used via
conventional screen management methods, such as cloning/extending with
xrandr.

For example, if your laptop’s display is called eDP1, and your using a
external adapter called HDMI1, and you wanted the display to be
1920×1080 resolution, you could run the following commands:

To have your HDMI screen to the right of your desktop, run:

....
$ xrandr –output eDP1 –mode 1920×1080 –output HDMI1 –mode 1920×1080 –right-of eDP1
....

To clone your desktop, run:

....
$ xrandr –output eDP1 –mode 1920×1080 –output HDMI1 –mode 1920×1080 –same-as eDP1
....

There are many different possibilities. Type xrandr with no arguments to
see what displays you have attached. See
https://github.com/Bumblebee-Project/Bumblebee/wiki/Multi-monitor-setup[this
web page] for further information on this subject. Read the manual page
for xrandr for even more information on the possibilities this command
provides.

If intel-virtual-output works ok running by hand you could add it to
your startup automatically if you desire. One way would be to create a
/etc/rc.d/rc.local script and add it into there. Another way might be to
create a systemd unit file as Type=oneshot. A third way might be to run
it at login using whatever mechanism your desktop environment supports
for doing such things. For example, in MATE desktop environment, there
is a mate-session-properties program (System -> Preferences -> Personal
-> Startup Applications) that you can run programs from when you login.
Most desktop environments offer similar functionality though the methods
differ from desktop to desktop.

[[troubleshooting]]
Troubleshooting
~~~~~~~~~~~~~~~

When you are using the closed source NVidia drivers, there is a checking
system you can run. To test, type this command:

....
$ bumblebee-nvidia --check
....

This will tell you if the NVidia driver and bbswitch-dkms compiled into
the current kernel ok. It works with both the managed and unmanaged
driver packages.

Some other errors you may encounter form the output from
bumblebee-nvidia –check

....
Error: Too many NVidia blobs in /etc/sysconfig/nvidia/
Blob count = 2.
....

This means that there are too many NVidia “blobs” in
/etc/sysconfig/nvidia/ and the solution is to delete one of them.

....
Error: No Nvidia blob in /etc/sysconfig/nvidia/
....

This means there is no blob in /etc/sysconfig/nvidia/ and you should
copy one there if using the unmanaged repo or re-install
bumblebee-nvidia if using the managed repo. (dnf reinstall
bumblebee-nvidia)

If the module did not compile, you can run:

....
# bumblebee-nvidia --debug
....

as root or via sudo. This may give you clues as to why the nvidia
installer was unable to work.

Type

....
$ bumblebee-nvidia --help
....

to see a full list of options the wrapper script provides.

If you see this error:

....
[ERROR]You've no permission to communicate with the Bumblebee daemon. Try adding yourself to the 'bumblebee' group
[ERROR]Could not connect to bumblebee daemon - is it running?
....

It could be caused by adding another user account to your notebook after
you have already installed the various bumblebee packages. The solution
is to run:

....
# usermod -a -G bumblebee USERNAME
....

where *USERNAME* is your account name to add to the bumblebee group. You
MUST be in the bumblebee group for primusrun or optirun to work.

*Primusrun mouse delay/disable VSYNC*

For primusrun, VSYNC is enabled by default and as a result, it could
make mouse input delay lag or even slightly decrease performance. Test
primusrun without VSYNC:

....
$ vblank_mode=0 primusrun glxgears
....

*Primus issues under compositing window managers*

Since compositing hurts performance, invoking primus when a compositing
WM is active is
https://github.com/amonakov/primus#issues-under-compositing-wms[not
recommended]. If you need to use primus with compositing and see
flickering or bad performance, synchronizing primus’ display thread with
the application’s rendering thread may help:

....
$ PRIMUS_SYNC=1 primusrun ...
....

*optirun crashes after you boot into “Troubleshooting -> Start Fedora
Live in basic graphics mode” and do an install that way.*

If you did an install under “Troubleshooting -> Start Fedora Live in
basic graphics mode.” bumblebee will not work. You can tell by examining
the /var/log/Xorg.8.log log file and looking for Kernel command line:
and seeing nomodeset on that line. When you use “Start Fedora Live in
basic graphics mode.” it adds “nomodeset” to your kernel command line
which will cause your machine to use the VESA driver and make bumblebee
not work. (It will just crash when you try) To fix that, edit
/etc/default/grub and on the GRUB_CMDLINE_LINUX= line, remove the word
nomodeset and then save the file, next, either run

....
# grub2-mkconfig -o /boot/grub2/grub.cfg
....

on a BIOS based notebook or

....
# grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg
....

on a UEFI based notebook. Then reboot. After that
bumblebee/optirun/primusrun should start working.

[[compatibility-with-recent-laptops-that-have-american-megatrend-bioses]]
Compatibility with recent laptops that have American Megatrend BIOSes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some recent laptop models featuring AMI bioses have some compatibility
issues with bbswitch and Optimus, making them unable to load into
graphics mode and crashing every time it is attempted, as discussed in
further details in this post on the Bumblebee's github:
https://github.com/Bumblebee-Project/Bumblebee/issues/764#issuecomment-234494238
.

If you are trying to use Linux on a recent Optimus laptop and it crashes
every time you try to enter a graphics environment, please try adding
the following parameters to your boot loader (Fedora users usually have
GRUB installed):

....
acpi_osi=! acpi_osi='Windows 2009'
....

This seems to work on most laptop models facing this issue, but bear in
mind that this workaround has not been tested in every laptop model ever
made – so your mileage may vary. If the problems persist, you could try
updating your BIOS or look for more info in the Bumblebee documentation
and their community.

[[broken-power-management-with-kernel-4.8]]
Broken power management with kernel 4.8
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have a newer laptop (BIOS date 2015 or newer), then Linux 4.8
might break bbswitch since bbswitch does not support the newer,
recommended power management method. As a result, the dGPU may fail to
power on, fail to power off or worse.

See https://github.com/Bumblebee-Project/bbswitch/issues/140[Issue 140]
for further information about this problem.

As a workaround, add pcie_port_pm=off to your kernel parameters.

Alternatively, if you are only interested in power saving (and perhaps
use of external monitors), remove bumblebee / bbswitch and rely on
Nouveau runtime power-management (which supports the new method).

[[mesa-13.0.3-6-and-libglvnd-issues]]
mesa-13.0.3-6 and libglvnd issues
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In fedora 25 and 26 a new library called libglvnd was added which
initially caused some issues.

primus-1.1.03282015-4 and newer, bumblebee-3.2.1-13 and newer, and
(managed version) bumblebee-nvidia-375.26-2 and newer, and (un-managed
version) bumblebee-nvidia-3.0-2 and newer will work with the newer mesa
and new libglvnd library.

When you first upgrade to mesa-13.0.3-6 or newer bumblebee-nvidia
doesn't know that it needs to rebuild the shim. So you can force that by
running the command:

....
bumblebee-nvidia --force
....

via `su` as root or via `sudo`. And the primus bridge should work after
that. You can track this issue upstream
https://github.com/amonakov/primus/issues/193[here].

[[useful-links]]
Useful links
~~~~~~~~~~~~

* http://bumblebee-project.org/
* https://github.com/Bumblebee-Project/Bumblebee/wiki
* https://github.com/Bumblebee-Project/Bumblebee/
* https://github.com/Bumblebee-Project/bbswitch
* https://github.com/amonakov/primus
* https://www.linux.ncsu.edu/bumblebee/

http://www.thelinuxrain.com/articles/the-state-of-nvidia-optimus-on-linux[The
State of NVIDIA Optimus on Linux]
'''

See a typo, something missing or out of date, or anything else which can be
improved? Edit this document at https://pagure.io/fedora-docs/quick-docs.