bbswitch-g14/README.md

*Migrated from https://github.com/Lekensteyn/acpi-stuff*

About
-----

bbswitch is a kernel module which automatically detects the required ACPI calls
for two kinds of Optimus laptops. It has been verified to work with "real"
Optimus and "legacy" Optimus laptops (at least, that is how I call them). The
machines on which these tests has performed are:

- Clevo B7130 - GT 425M ("real" Optimus, Lekensteyns laptop)
- Dell Vostro 3500 - GT 310M ("legacy" Optimus, Samsagax' laptop)

(note: there is no need to add more supported laptops here as the universal
calls should work for every laptop model supporting either Optimus calls)

It's preferred over manually hacking with the acpi_call module because it can
detect the correct handle preceding _DSM and has some built-in safeguards:

- You're not allowed to disable a card if a driver (nouveau, nvidia) is loaded.
- Before suspend, the card is automatically enabled. When resuming, it's
  disabled again if that was the case before suspending. Hibernation should
  work, but it not tested.

Build
-----

Build the module (kernel headers are required):

    make
Then load it (requires root privileges, i.e. `sudo`):

    make load
If your card is supported, there should be no error. Otherwise, you get a "No
such device" (ENODEV) error. Check your kernel log (dmesg) for more
information.

DKMS support
------------

If you have DKMS installed, you can install bbswitch in such a way that it
survives kernel upgrades. It is recommended to remove older versions of bbswitch
by running `dkms remove bbswitch/OLDVERSION --all` as root. To install the new
version, simply run:

    # make -f Makefile.dkms

To uninstall it, run:

    # make -f Makefile.dkms uninstall

Lenovo IdeaPad Y470/Y570 and Toshiba SATELLITE P870
---------------------------------------------------
Until [this kernel bug](https://bugzilla.kernel.org/show_bug.cgi?id=42696) is
fixed, you need to apply an ugly hack on these laptops to make bbswitch and the
driver (both nouveau and nvidia) work. For now I have decided not to put the
hack in the bbswitch module since it is a very ugly hack that is comparable to
writing a maximum allowable speed of 130 km/h on a traffic sign for a road
where 120 km/h is allowed just because the radar gun does not work properly.

The module has been tested on a Lenovo IdeaPad Y570 running an up-to-date
version of Ubuntu 11.10 Oneiric (64-bit) with Bumblebee 3.0 (3.0-1~oneiricppa2)
installed using the nvidia driver.

To make use of it, use the `hack-lenovo` branch. An example using DKMS:

    $ git clone git://github.com/Bumblebee-Project/bbswitch.git -b hack-lenovo
    $ cd bbswitch
    $ mkdir /usr/src/acpi-handle-hack-0.0.1
    # cp Makefile acpi-handle-hack.c /usr/src/acpi-handle-hack-0.0.1
    # cp dkms/acpi-handle-hack.conf /usr/src/acpi-handle-hack-0.0.1/dkms.conf
    # dkms add acpi-handle-hack/0.0.1
    # dkms build acpi-handle-hack/0.0.1
    # dkms install acpi-handle-hack/0.0.1
If everything goes well, you now need to get the hack loaded on boot. On
Ubuntu and Debian, this can be done with:

    echo acpi-handle-hack | sudo tee -a /etc/modules
    sudo update-initramfs -u
For other systems, adopt the instructions from the *Disable card on boot*
section below. Please do not copy these instructions to blogs/forums/whatever
without warning that the method is a hack (you can refer to the metaphore above)
and that it may crash the machine if incorrectly applied. To apply these
changes, you have to reboot (technically, unloading nvidia/nouveau, bbswitch and
stopping bumblebeed, `modprobe acpi-handle-hack` and starting bumblebeed should
work as well, but saying reboot is shorter)

Usage
-----

bbswitch has three commands to check the card status and switching 
(`#` means "run with root privileges, i.e. run it prefixed with `sudo `):

### Get the status:

    # cat /proc/acpi/bbswitch  
    0000:01:00.0 ON

### Turn the card off, respectively on:

    # tee /proc/acpi/bbswitch <<<OFF
    # tee /proc/acpi/bbswitch <<<ON
If the card stays on when trying to disable it, you've probably forgotten to
unload the driver,

    $ dmesg |tail -1
    bbswitch: device 0000:01:00.0 is in use by driver 'nouveau', refusing OFF

Do **not** attempt to load a driver while the card is off or the card won't be
usable until the PCI configuration space has been recovered (for example, after
writing the contents manually or rebooting).

### Module options

The module has some options that control the behavior on loading and unloading:
`load_state` and `unload_state`. Valid values are `-1`, `0` and `1` meaning "do
not change the card state", "turn the card off" and "turn the card on"
respectively. For example, if you want to have `bbswitch` disable the card
immediately when loading the module while disabling the card on unload, load the
module with:

    # modprobe bbswitch load_state=0 unload_state=1

The `unload_state` value can be changed on runtime, the above command yields the
same behavior as:

    # modprobe bbswitch load_state=0
    # echo 1 | tee /sys/module/bbswitch/parameters/unload_state

If not explictly set, the default behavior is not to change the power state of
the discrete video card which equals to `load_state=-1 unload_state=-1`.

### Disable card on boot

These options can be useful to disable the card on boot time. Depending on your
distribution, `/etc/modules`, `/etc/modules.conf` or some other file can be used
to load modules on boot time. Adding the below line to the file makes the card
get disabled on boot:

    bbswitch load_state=0

You have to update your initial ramdisk (initrd) for the changes propagate to
the boot process. On Debian and Ubuntu, this can performed by running
`update-initramfs -u` as root.

Reporting bugs
--------------

This module has been integrated in Bumblebee "Tumbleweed". Please report any
issues on this module in the issue tracker and provide the following details:

- The output of `dmesg | grep -C 10 bbswitch:`
- The kernel version `uname -a`
- Your distribution and version (if applicable)
- The version of your Xorg and the driver
- Submit your machine information on https://bugs.launchpad.net/bugs/752542;
  the instructions are listed in the bug description. Summary: install the
  packages containing `dmidecode`, `acpidump` and `iasl` and then run:

        wget http://lekensteyn.nl/files/get-acpi-info.sh
        sh get-acpi-info.sh
- Information about the ACPI handles associated with PCI devices. Since this is
  a kernel module, you'll need kernel headers, gcc and automake. Commands:

        git clone git://github.com/Lekensteyn/acpi-stuff.git --depth 1
        cd acpi-stuff/acpi_dump_info
        make
        sudo make load
        cat /proc/acpi/dump_info

Upload the generated tarball on the above Launchpad URL and provide a link to
the comment containing your report.