diff options
| author | Konstantin Ryabitsev <konstantin@linuxfoundation.org> | 2024-10-08 15:24:36 -0400 |
|---|---|---|
| committer | Konstantin Ryabitsev <konstantin@linuxfoundation.org> | 2024-10-08 15:24:36 -0400 |
| commit | f3216be1efae259f0551c744f03f7195640573e5 (patch) | |
| tree | 5d97f6604a3f16ad1d5439126665f0ff12bed59c /source/documentation/compat-drivers.rst | |
| parent | 96836ca0c23f0f5eb766cfe0a39a72a3bc216f2a (diff) | |
| download | backports-master.tar.gz | |
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Diffstat (limited to 'source/documentation/compat-drivers.rst')
| -rw-r--r-- | source/documentation/compat-drivers.rst | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/source/documentation/compat-drivers.rst b/source/documentation/compat-drivers.rst new file mode 100644 index 0000000..dc0c4a7 --- /dev/null +++ b/source/documentation/compat-drivers.rst @@ -0,0 +1,212 @@ +Documentation/compat-drivers +============================ + +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. + +Supported Linux kernel releases +------------------------------- + +The `kernel.org <http://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 +<http://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 :doc:`releases page <../releases>`. 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 :doc:`legend of additional patches +<compat-drivers/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 +<http://git.kernel.org/?p=linux/kernel/git/firmware/linux-firmware.git;a=summary>`__. + +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 <http://wireless.kernel.org/en/developers/Regulatory#The_regulatory_database>`__ +- `CRDA <http://wireless.kernel.org/en/developers/Regulatory/CRDA>`__ +- `iw <http://wireless.kernel.org/en/users/Documentation/iw>`__ +- `rfkill <http://wireless.kernel.org/en/users/Documentation/rfkill>`__ +- `linux-firmware <http://git.kernel.org/?p=linux/kernel/git/firmware/linux-firmware.git;a=summary>`__ +- `wpa_supplicant <http://wireless.kernel.org/en/users/Documentation/wpa_supplicant>`__ +- `hostapd <http://wireless.kernel.org/en/users/Documentation/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 xvf 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 :doc:`additional patches <compat-drivers/additional-patches>` +section for details of how **emergency** or **critical** fixes are dealt +with while still **prioritizing** Linux upstream development. + +Bugs +---- + +Please see the :doc:`reporting bugs section <../bugs>`. 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 :doc:`hacking compat-drivers page <compat-drivers/hacking>`. + |