Documentation/compat-drivers

From Driver Backports Wiki
(Difference between revisions)
Jump to: navigation, search
 
(7 intermediate revisions by one user not shown)
Line 7: Line 7:
 
<h1>Release types</h1>
 
<h1>Release types</h1>
  
There are two release types, linux-stable and linux-next releases, for details refer to the [[Releases|releases page]].
+
There are two release types, linux-stable and linux-next releases, for details refer to the [[Releases|releases page]]. There are also modifications to releases and an extra set of flags are appended to releases depending on the series of types of patches applied to them. For details on these different type of patches that can be applied onto a release refer to the [[Documentation/compat-drivers/additional-patches#Legend_of_additional_patches|legend of additional patches]] section.
  
<h1>Requirements</h1>
+
<h1>Backported subsystems</h1>
 +
 
 +
There are three subsystems currently backported through this framework.
 +
 
 +
  * Ethernet
 +
  * Wireless
 +
  * Bluetooth
 +
 
 +
The video drivers are currently on their way to being integrated.
 +
 
 +
<h2>Subsystem requirements</h2>
  
 
In order to compile and install modules from the compat-drivers releases you will need to have your kernel headers installed on your system. As you get new drivers though you may need to install newer firmware as well so be sure to always have in synch your '''/lib/firmware/''' directly with the latest firmware from the [http://git.kernel.org/?p=linux/kernel/git/firmware/linux-firmware.git;a=summary linux-firmware.git tree].
 
In order to compile and install modules from the compat-drivers releases you will need to have your kernel headers installed on your system. As you get new drivers though you may need to install newer firmware as well so be sure to always have in synch your '''/lib/firmware/''' directly with the latest firmware from the [http://git.kernel.org/?p=linux/kernel/git/firmware/linux-firmware.git;a=summary linux-firmware.git tree].
Line 15: Line 25:
 
Each backported subsystem may also take advantage of newer userspace APIs and as such you should upgrade each subsystem's recommended userspace as documented here.
 
Each backported subsystem may also take advantage of newer userspace APIs and as such you should upgrade each subsystem's recommended userspace as documented here.
  
<h2>Userspace upgrade for wireless</h2>
+
<h3>Userspace upgrade for wireless</h3>
  
 
We recommend these the following 802.11 wireless userspace applications should be upgraded:
 
We recommend these the following 802.11 wireless userspace applications should be upgraded:
Line 27: Line 37:
 
  * [http://wireless.kernel.org/en/users/Documentation/hostapd hostapd]
 
  * [http://wireless.kernel.org/en/users/Documentation/hostapd hostapd]
  
<h2>Userspace upgrade for bluetooth</h2>
+
<h3>Userspace upgrade for bluetooth</h3>
  
 
Someone should edit this and update this.
 
Someone should edit this and update this.
  
<h2>Userspace upgrade for ethernet</h2>
+
<h3>Userspace upgrade for ethernet</h3>
  
 
Someone should edit this and update this.
 
Someone should edit this and update this.
  
<h1>Selecting your driver</h1>
+
<h1>Building and installing</h1>
 +
 
 +
This section covers how to use build and install compat-drivers.
 +
 
 +
<h2>Selecting your driver</h2>
  
 
compat-drivers allows you to selectively build only one driver instead of building all backported drivers.
 
compat-drivers allows you to selectively build only one driver instead of building all backported drivers.
  
<h1>Extracting compat-drivers</h1>
+
<h2>Extracting compat-drivers</h2>
  
 
Extract the content of the package:
 
Extract the content of the package:
Line 61: Line 75:
 
If you do not see your driver in the supported list it means care has not been taken to ensure it works with driver-select and you must just build compat-drivers as a whole.
 
If you do not see your driver in the supported list it means care has not been taken to ensure it works with driver-select and you must just build compat-drivers as a whole.
  
<h1>Building and installing</h1>
+
<h2>Building and installing</h2>
  
 
This section documents how to build and install compat-drivers.
 
This section documents how to build and install compat-drivers.
  
<h1>Building compat-drivers</h1>
+
<h2>Building compat-drivers</h2>
  
 
Build the latest backported Linux subsystems:
 
Build the latest backported Linux subsystems:
Line 74: Line 88:
 
</pre>
 
</pre>
  
<h1>Installing compat-drivers</h1>
+
<h2>Installing compat-drivers</h2>
  
 
We use the updates/ directory so your distribution's drivers are left intact. By default depmod will search for this directory first, but if you find that it does not then check that your depmod.conf file lists the search order correctly with ''updates'' appearing first (before ''built-in''). the package should automatically detect this for you and deploy an update for you.
 
We use the updates/ directory so your distribution's drivers are left intact. By default depmod will search for this directory first, but if you find that it does not then check that your depmod.conf file lists the search order correctly with ''updates'' appearing first (before ''built-in''). the package should automatically detect this for you and deploy an update for you.
Line 82: Line 96:
 
</pre>
 
</pre>
  
<h1>Uninstalling compat-drivers</h1>
+
<h2>Uninstalling compat-drivers</h2>
  
 
This nukes our changes to updates/ so you can go back to using your distribution's supported drivers.
 
This nukes our changes to updates/ so you can go back to using your distribution's supported drivers.
Line 100: Line 114:
 
If unsure just reboot.
 
If unsure just reboot.
  
<h1>Loading compat-drivers</h1>
+
<h2>Loading compat-drivers</h2>
  
 
Before loading modules you must first unload your old subsystem modules. Read above how to do this. If you know what module you need you can simply load the module using modprobe. If you are not sure you can just reboot the box.
 
Before loading modules you must first unload your old subsystem modules. Read above how to do this. If you know what module you need you can simply load the module using modprobe. If you are not sure you can just reboot the box.
  
<h1>Building for external kernels</h1>
+
<h2>Building for external kernels</h2>
  
 
If you have a kernel you do not have installed but yet want to build the compat-drivers for it you can use this syntax:
 
If you have a kernel you do not have installed but yet want to build the compat-drivers for it you can use this syntax:
Line 112: Line 126:
 
   KLIB_BUILD=/home/mcgrof/kernels/linux-2.6.27.22
 
   KLIB_BUILD=/home/mcgrof/kernels/linux-2.6.27.22
 
</pre>
 
</pre>
 +
 +
<h1>Additional patches</h1>
 +
 +
Read the [[Documentation/compat-drivers/additional-patches|additional patches]] section for details of how '''emergency''' or '''critical''' fixes are dealt with while still '''prioritizing''' Linux upstream development.
  
 
<h1>Bugs</h1>
 
<h1>Bugs</h1>
  
Please see the [[Documentation/compat-drivers/reporting-bugs|reporting bugs section]]. This cannot be stressed enough: '''to date we have only have identified 2 backport related bugs''', all other reported bugs''' were real bugs in actual upstream code''' so be sure to report any bugs found '''ASAP'''!
+
Please see the [[Documentation/reporting-bugs|reporting bugs section]]. This cannot be stressed enough: '''to date we have only have identified 2 backport related bugs''', all other reported bugs''' were real bugs in actual upstream code''' so be sure to report any bugs found '''ASAP'''!
  
 
<h1>License</h1>
 
<h1>License</h1>

Latest revision as of 20:58, 25 September 2012

compat-drivers is the framework that pulls code from Linux kernel releases and strives to backport them automatically for usage on older Linux kernel releases. compat-drivers allows us to make releases of code from newer Linux kernel releases and get the latest drivers to users without having to recompile their entire kernel.

Contents

Supported Linux kernel releases

The kernel.org archive hosts all kernel releases. As the Linux kernel development moves on older kernels get deprecated and a few kernels remain supported. It is imperative that end users / system integrators / Linux distributions upgrade to newer supported kernels regularly otherwise they may end up being stuck on unsupported kernels. The compat-drivers project aims at always providing support of newer drivers down to at least all supported Linux kernel releases as listed on kernel.org. As it is though the project currently takes backporting further and it does support a large amount of older unsupported and deprecated Linux kernel releases. As it is right now all 21 older kernels are supported: 2.6.24 - 3.6.

Release types

There are two release types, linux-stable and linux-next releases, for details refer to the releases page. There are also modifications to releases and an extra set of flags are appended to releases depending on the series of types of patches applied to them. For details on these different type of patches that can be applied onto a release refer to the legend of additional patches section.

Backported subsystems

There are three subsystems currently backported through this framework.

 * Ethernet
 * Wireless
 * Bluetooth

The video drivers are currently on their way to being integrated.

Subsystem requirements

In order to compile and install modules from the compat-drivers releases you will need to have your kernel headers installed on your system. As you get new drivers though you may need to install newer firmware as well so be sure to always have in synch your /lib/firmware/ directly with the latest firmware from the linux-firmware.git tree.

Each backported subsystem may also take advantage of newer userspace APIs and as such you should upgrade each subsystem's recommended userspace as documented here.

Userspace upgrade for wireless

We recommend these the following 802.11 wireless userspace applications should be upgraded:

* wireless-regdb
* CRDA
* iw
* rfkill
* linux-firmware
* wpa_supplicant
* hostapd

Userspace upgrade for bluetooth

Someone should edit this and update this.

Userspace upgrade for ethernet

Someone should edit this and update this.

Building and installing

This section covers how to use build and install compat-drivers.

Selecting your driver

compat-drivers allows you to selectively build only one driver instead of building all backported drivers.

Extracting compat-drivers

Extract the content of the package:

tar jxvf compat-drivers-$(date -I).tar.bz2

If you know what driver you want you can use driver-select:

./scripts/driver-select

Selecting your driver can reduce the amount of time to compile compat-drivers. It may also enable kernel compatibility down to older kernels. If you want to restore compat-drivers to enable all drivers again you can use:

./scripts/driver-select restore

If you do not see your driver in the supported list it means care has not been taken to ensure it works with driver-select and you must just build compat-drivers as a whole.

Building and installing

This section documents how to build and install compat-drivers.

Building compat-drivers

Build the latest backported Linux subsystems:

cd compat-wireless-$(date -I)
make

Installing compat-drivers

We use the updates/ directory so your distribution's drivers are left intact. By default depmod will search for this directory first, but if you find that it does not then check that your depmod.conf file lists the search order correctly with updates appearing first (before built-in). the package should automatically detect this for you and deploy an update for you.

sudo make install

Uninstalling compat-drivers

This nukes our changes to updates/ so you can go back to using your distribution's supported drivers.

sudo make uninstall

Unloading your old distribution drivers

Since you might be replacing your old subsystem drivers you should first try to unload all existing related drivers. We provide a mechanism to unload all drivers:

sudo make unload

If unsure just reboot.

Loading compat-drivers

Before loading modules you must first unload your old subsystem modules. Read above how to do this. If you know what module you need you can simply load the module using modprobe. If you are not sure you can just reboot the box.

Building for external kernels

If you have a kernel you do not have installed but yet want to build the compat-drivers for it you can use this syntax:

make KLIB=/home/mcgrof/kernels/linux-2.6.27.22 \
   KLIB_BUILD=/home/mcgrof/kernels/linux-2.6.27.22

Additional patches

Read the additional patches section for details of how emergency or critical fixes are dealt with while still prioritizing Linux upstream development.

Bugs

Please see the reporting bugs section. This cannot be stressed enough: to date we have only have identified 2 backport related bugs, all other reported bugs were real bugs in actual upstream code so be sure to report any bugs found ASAP!

License

This work is a subset of the Linux kernel as such we keep the kernel's Copyright practice. Some files have their own copyright and in those cases the license is mentioned in the file. All additional work made to building this package is licensed under the GPLv2.

Hacking compat-wireless

If you'd like to hack on compat-drivers or make your own releases refer to the hacking compat-drivers page.

Administrative

The way compat-drivers releases are made, where they are kept are detailed in the compat-drivers admin page.

Personal tools