Final tweaks before publishingHEAD master

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
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
parent: 96836ca0c23f0f5eb766cfe0a39a72a3bc216f2a (diff)
download: backports-master.tar.gz
8 files changed, 1893 insertions, 0 deletions
diff --git a/source/documentation/backports/hacking.rst b/source/documentation/backports/hacking.rst
new file mode 100644
index 0000000..72c64a1
--- /dev/null
+++ b/source/documentation/backports/hacking.rst
@@ -0,0 +1,406 @@
+Documentation/backports/hacking
+===============================
+
+.. note::
+
+   the backports project's process is being reworked and redefined.
+   Some of the information in this page may be outdated and will be
+   updated when the changes in the process are finalized.
+
+The project has a :doc:`To-Do List <hacking/todo>` and a :doc:`License
+<../../license>`.
+
+Philosophy
+----------
+
+The project aims to optimize the backporting process by not only
+providing backported drivers but by also aiming to `automatically
+backport the Linux kernel
+<http://www.do-not-panic.com/2012/08/automatically-backporting-linux-kernel.html>`__
+by `optimizing backporting collateral evolutions
+<http://www.do-not-panic.com/2012/08/optimizing-backporting-collateral.html>`__.
+
+Backports development flow
+--------------------------
+
+#. The `backports.git
+   <https://git.kernel.org/cgit/linux/kernel/git/backports/backports.git>`__
+   "master" development branch always tracks "linux-next", allowing it
+   to track all the development trees.
+
+   - This ensures that, at the close of each merge window, the state of
+     the backports will be very close to the state of the first release
+     candidate.
+
+#. At the close of each merge window, the Backports Project creates a new branch.
+
+   - This new branch tracks the progress of the impending release
+     throughout the release candidate evaluation period, to the major
+     release, and on to its lifetime as a stable kernel.
+
+The backports project thus makes three kinds of backports releases possible:
+
+- those derived from linux-next
+- those derived from the most recent release candidate (if any)
+- those derived from recent stable kernels.
+
+Backports git tree tags and branches
+------------------------------------
+
+The project uses two types of git tags:
+
+- daily tags following linux-next
+- stable tags following either Linus' tree for rc releases or Greg's
+  stable tree for stable extra version releases
+
+The project uses a master branch and a series of stable branches, a
+stable branch to track each stable release of the kernel. The master
+branch always tags linux-next, for example the backports tag
+backports-20141114 supports using linux-next tag next-20141114. Once
+Linus makes a release candidate of the kernel a respective *stable
+backports branch* is created based on the version of Linux Linus
+released, this backports branch will be based on a recent backports tag
+which was tracking linux-next. Future release candidates of the same
+version of Linux as well as stable release of Linux under the same
+version will be backported using the respective *backports stable
+branch* created.
+
+If any of this is fuzzy please refer to the `Increasing Automation in
+the Backporting of Linux Drivers Using Coccinelle
+<https://github.com/mcgrof/paper-backports/raw/master/paper.pdf>`__
+paper, in particular the sections:
+
+- 1A - A. The Linux kernel development model
+- 1B - A brief history of the Linux kernel backports project
+
+Git trees you will need
+=======================
+
+The project backports a few subsystems down to older kernels. To be able
+to synchronize backporting the latest and greatest the `linux-next.git
+<https://git.kernel.org/cgit/linux/kernel/git/next/linux-next.git>`__
+tree is used as its main source for kernel updates. backports brings a
+general kernel compatibility part containing some backported c functions
+and header files in addition to patches for code in linux-next to make
+it work on older kernel versions and with the general kernel
+compatibility part. You will need first the `backports.git
+<https://git.kernel.org/cgit/linux/kernel/git/backports/backports.git>`__
+tree. Once cloned you can run::
+
+    ./devel/backports-update-manager
+
+That will get you all other trees and sources required for development,
+which are:
+
+- linux-next - Stephen Rothwell's tree which tracks all development trees daily
+- linux - Linus' tree
+- linux-stable - Greg's stable tree for stable extra version releases
+
+This will use git clone --reference to minimize disk usage.
+
+You can generate backports based on different trees depending on your
+needs. We are supporting build based on `linux-next.git
+<https://git.kernel.org/cgit/linux/kernel/git/next/linux-next.git/>`__,
+`linux.git
+<https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/>`__
+and `linux-stable.git
+<https://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/>`__.
+You can also generate builds based on your own tree, but then you
+probably have to patch backports yourself to add support for that.
+
+Tool prerequisites
+------------------
+
+git, python patch and coccinelle are needed to generate a backports
+release. The tools will complain if you do not have any of the required
+dependencies.
+
+Generate new release
+--------------------
+
+To generate a own backport release based on linux-next you need the
+following git trees::
+
+   git://git.kernel.org/pub/scm/linux/kernel/git/backports/backports.git
+   git://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git
+
+As linux-next changes often you should start with a working version by
+using a tagged version from linux-next.git and backports.git with the
+same date in it like backports-20130607 and next-20130607. This is a
+combination where someone already tested that the patches are still
+applying.
+
+After you have checked out some version of these git trees, you can
+start generating a tar by running ./gentree.py in the backports tree.
+This will take the path to the already checked out linux-next kernel as
+the second last argument and the path to a directory where the newly
+created release should be written to as the last parameter. The releases
+are not created in place any more, but in a new path specified in the
+last parameter::
+
+   ./gentree.py --clean --git-revision v3.x /path/to/your/linux-next /path/to/your/newly/created/release
+
+Adding new driver
+=================
+
+This is a list of steps to be done when adding a new driver. Not all
+steps are needed for every new driver it depends on what type of driver
+is added. You can take the patch adding support for the ieee802154
+subsystem as a reference:
+https://git.kernel.org/cgit/linux/kernel/git/backports/backports.git/commit/?id=a42aa4d474e5859164a00bf451970fb58b676fcf
+
+You should target the master branch of the backports repository.
+
+#. Add directories and files that should be copied from the mainline kernel to ``copy-list``
+#. Add patches to ``patches/collateral-evolutions/`` if needed, it is better to add or modify a header file in ``backport/backport-include/`` than adding a patch.
+#. Add reference to the newly added driver directory in ``backport/Makefile.kernel`` if needed (just needed for new substems)
+#. Add reference to the newly added driver directory in ``backport/Kconfig.sources`` if needed (just needed for new subsystems)
+#. Add a defconfig file for this driver in ``backport/defconfigs/`` and modify other defconfig files if appropriate, e.g. if you add a wifi driver add it to ``backport/defconfigs/wifi``
+#. If the driver does not build on all kernel versions specify a minimum kernel version in ``dependencies``
+
+Backports currently supports the latest minor version of every mainline
+kernel starting from 2.6.24. You should check that backports still
+builds after making your changes. To do so you should install all
+supported kernel with the script in ``devel/get-compat-kernels`` and
+then run ``devel/ckmake`` to build backports against every kernel
+version.
+
+Backporting a kernel feature
+----------------------------
+
+Features being backported should either be backported into a respective
+backports-3.x.c file under backports/compat/ and/or their respective
+header file under backport/backport-include/.
+
+Backports Kconfig operation
+---------------------------
+
+Go read the `backports kconfig operation
+<https://git.kernel.org/cgit/linux/kernel/git/backports/backports.git/tree/devel/doc/kconfig-operation>`__
+documentation.
+
+Backports Makefile operation
+----------------------------
+
+Go read the `backports Makefile operation
+<https://git.kernel.org/cgit/linux/kernel/git/backports/backports.git/tree/devel/doc/makefile-operation>`__
+documentation.
+
+Sending patches
+---------------
+
+backports contributions follow the contribution model implemented by the
+Linux kernel. Patches or pull requests for backports must have be
+signed-offed. If you don't sign off on them **they will not accepted**.
+This means adding a line that says "Signed-off-by: Name " at the end of
+each commit, indicating that you wrote the code and have the right to
+pass it on as an open source patch. For exact definition of what the
+Signed-off-by tag is you can read the definition of the "**Developer's
+Certificate of Origin 1.1**", which you can read here:
+
+http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html
+
+Remember there are three trees. linux-next itself is a conglomeration of
+kernel git trees itself, so patches for linux-next.git should be sent to
+each respective subsystem for which the patches are targeted for. So for
+example for 802.11 you will want to send them to John Linville and cc
+linux-wireless, for further guidelines on this see the `Submitting
+Patches guidelines for 802.11
+<http://wireless.kernel.org/en/developers/Documentation/SubmittingPatches>`__.
+As another example, for bluetooth you will want to send them to Gustavo
+Padovan and cc the linux-bluetooth mailing list. If your patch touches
+on others areas of the kernel refer to the MAINTAINERS file on the
+kernel.
+
+For backports.git please send patches against to::
+
+   To: hauke@hauke-m.de, mcgrof@kernel.org
+   CC: backports@vger.kernel.org
+   Subject: [PATCH] backports: fix foo
+
+Patches are preferred sent with a clear commit log entry, if unfamiliar
+with how to send patches please refer to `a git guide
+<http://wireless.kernel.org/en/developers/Documentation/git-guide>`__.
+
+Requirements for contributions
+------------------------------
+
+The code quality, and coding style is precisely the same as followed by
+the Linux kernel, for that refer to `the Linux kernel SubmittingPatches
+<https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches>`__
+guide. Other than this, since we a supporting backporting you are
+expected to refer to the respective upstream commit which you are
+providing a backport for. This should describe both the git commit
+sha1sum on Linux, and the commit description. The description should
+also include the Linux kernel version which merged the commit upstream
+first, this can be used to help understand what target kernels the
+backport work was for. An example of good commit log follows::
+
+   commit 54584122b3279700f5ef2ba4f260a84273215947
+   Author: Stefan Assmann <sassmann@kpanic.de>
+   Date:   Fri May 16 13:21:19 2014 +0200
+
+       backports: handle new get_module_info and get_module_eeprom pointers in struct ethtool_ops
+       
+       In kernel 3.5 struct ethtool_ops received 2 new function pointers
+       get_module_info and get_module_eeprom. Address this by putting ifdef around
+       the code.
+       
+       commit 41c3cb6d20f0252308e9796fa4f3dacb4960de91
+       Author: Stuart Hodgson <smhodgson@solarflare.com>
+       Date:   Thu Apr 19 09:44:42 2012 +0100
+       
+           ethtool: Extend the ethtool API to obtain plugin module eeprom data
+       
+       git describe --contains 41c3cb6d20f0252308e9796fa4f3dacb4960de91
+       v3.5-rc1~109^2~124^2~2
+       
+       Signed-off-by: Stefan Assmann <sassmann@kpanic.de>
+       Signed-off-by: Hauke Mehrtens <hauke@hauke-m.de>
+
+Backporting preference for EXPORT_SYMBOL_GPL() and proprietary drivers
+----------------------------------------------------------------------
+
+This framework was designed by intent since its inception **only** for
+*upstream* Linux kernel drivers to avoid excuses about the difficulty to
+support **upstream** Linux kernel development while also supporting
+**users on older kernels**. To ensure the intent is respected currently
+all symbols that we do work on to backport are exported via
+**EXPORT_SYMBOL_GPL()** as we do work to backport them for the supported
+kernels. By using EXPORT_SYMBOL_GPL() we make it **clear** through the
+only current technical means we have that if you use the backported
+symbols your software **is considered derivative works of the Linux
+kernel**.
+
+Backporting more subsystems
+---------------------------
+
+Feel free to any backport subsystems. The requirement is you at least
+list its kernel dependency and also that you have tested compilation
+success with ckmake. If you are adding a new subsystem we are in hopes
+you will also help maintain it.
+
+Generating backports stats
+--------------------------
+
+To help backports developers evaluate the gains of use of Coccinelle
+SmPL a tool has been written as part of the work done towards the
+`Increasing Automation in the Backporting of Linux Drivers Using
+Coccinelle paper
+<http://coccinelle.lip6.fr/papers/backport_edcc15.pdf>`__, the tool has
+a temporary git tree on github, integration of the tool into the
+upstream backports tree is desirable but porting of the tool to Python
+must be done first. Below are instructions on how to use the tool to get
+stats on the latest tree. The statistics give a slew of metrics over the
+gains of using of Coccinelle towards automatically backporting the Linux
+kernel on each release.
+
+First git clone upstream backports git tree, and have a linux-next tree
+available (using Linus' tree is possible as well, you just need to use
+the respective stable backports branch). Then generate a backports
+release using --gitdebug so that each step of the backports process
+creates a commit. This lets the tool evaluate the impact of using
+Coccinelle at each step. Assuming you have backports cloned on
+~/backports/ and the latest linux-next tree with the respective
+linux-next tag associated with the latest backports tree tag you would
+do::
+
+    cd linux-next git reset --hard next-20151218
+    cd ~/backports/
+    mkdir -p ~/build/ rm -rf ~/build/backports-20151218 ./gentree.py --gitdebug ~/linux-next ~/build/backports-20151218
+
+Now go get the temporary backports stats tool and copy over the required
+binary and script::
+
+    cd ~/ git clone https://github.com/mcgrof/backports-cocci-stats.git cd backports-cocci-stats make
+    cp gen-cocci-stats.sh ~/build/backports-20151218/ cp clean ~/build/backports-20151218/
+
+Now generate the stats, you should see something like this::
+
+    mcgrof@ergon ~/build/backports-20151218 (git::master)$ ./gen-cocci-stats.sh
+    Development and Maintenance efficiency metrics:
+
+       dev-efficiency    maint-efficiency   diff-wc      diffstat       clean       SmPL-Patch
+             0.555556             2.33333        21             5           9  0065-ndisc_send_na-argument.cocci
+                 2.75 ��                 8        64            22           8  0062-iff-no-queue.cocci
+             0.666667             1.88889        17             6           9  skb_no_xmit_more.cocci
+              1.16667             2.79167        67            28          24  ptp_getsettime64.cocci
+             0.142857                   1        14             2          14  features_check.cocci
+              1.18182             5.45455        60            13          11  0055-netdev-tstats.cocci
+              1.55906             3.55118       451           198         127  0054-struct-proto_ops-sig.cocci
+             0.666667             1.88889        17             6           9  no-pfmemalloc.cocci
+             0.634146              1.4878        61            26          41  set_vf_rate.cocci
+                 3.75              10.625        85            30           8  igb_pci_error_handlers.cocci
+              1.07692             4.23077        55            14          13  ethtool_cmd_mdix.cocci
+             0.588235             1.23529        21            10          17      rxnfc.cocci
+             0.285714             1.53571        43             8          28  get_module.cocci
+             0.285714             1.53571        43             8          28  ethtool_eee.cocci
+             0.714286             2.28571        16             5           7  skb_no_fcs.cocci
+                 0.25             1.59375        51             8          32  set_vf_spoofchk.cocci
+             0.428571             2.85714        40             6          14  sriov_configure.cocci
+              0.87037              2.7037       146            47          54  0031-sk_data_ready.cocci
+                  4.4                17.9       179            44          10  genl-const.cocci
+              7.11111             49.6667       447            64           9  0019-usb_driver_lpm.cocci
+             0.571429             4.14286        58             8          14  get_ts_info.cocci
+              11.5333                45.4       681           173          15  0001-netlink-portid.cocci
+              2.96667               16.35       981           178          60  0002-no_dmabuf.cocci
+             0.444444             1.77778        32             8          18  0002-gpio-parent.cocci
+             0.512821             1.89744        74            20          39  0002-group_attr_bus.cocci
+             0.769231             2.79487       109            30          39  0001-group_attr_class.cocci
+              1.47184              5.6484      3711           967         657   all-SmPL.cocci
+
+    Patch total diff wc -l: 3075 SmPL total diff wc -l: 3711 Total total diff wc -l: 6786
+    Patch diff % contribution: 45.3139 SmPL diff % contribution: 54.6861
+
+Now say you wanted to generate stats for a newer release, say for stats
+based on linux-next tag next-20160122, you would do::
+
+    cd ~/linux-next/
+    git reset --hard next-20160122
+    cd ~/backports/
+    ./gentree.py --gitdebug ~/linux-next/ ~/build/backports-20160122
+    cd ~/build/backports-20160122
+    cp ~/backports-cocci-stats/gen-cocci-stats.sh .
+    cp ~/backports-cocci-stats/clean .
+    ./gen-cocci-stats.sh
+
+    Development and Maintenance efficiency metrics:
+
+       dev-efficiency    maint-efficiency   diff-wc      diffstat       clean       SmPL-Patch
+                  0.4                 2.6        13             2           5  0067-mdio-addr.cocci
+             0.555556             2.33333        21             5           9  0065-ndisc_send_na-argument.cocci
+                 2.75                   8        64            22           8  0062-iff-no-queue.cocci
+             0.666667             1.88889        17             6           9  skb_no_xmit_more.cocci
+              1.16667             2.79167        67            28          24  ptp_getsettime64.cocci
+             0.142857                   1        14             2          14  features_check.cocci
+              1.18182             5.45455        60            13          11  0055-netdev-tstats.cocci
+              1.55906             3.55118       451           198         127  0054-struct-proto_ops-sig.cocci
+             0.666667             1.88889        17             6           9  no-pfmemalloc.cocci
+             0.634146              1.4878        61            26          41  set_vf_rate.cocci
+                 3.75              10.625        85            30           8  igb_pci_error_handlers.cocci
+              1.07692             4.23077        55            14          13  ethtool_cmd_mdix.cocci
+             0.588235             1.23529        21            10          17      rxnfc.cocci
+             0.285714             1.53571        43             8          28  get_module.cocci
+             0.285714             1.53571        43             8          28  ethtool_eee.cocci
+             0.714286             2.28571        16             5           7  skb_no_fcs.cocci
+                 0.25             1.59375        51             8          32  set_vf_spoofchk.cocci
+             0.428571             2.85714        40             6          14  sriov_configure.cocci
+              0.87037              2.7037       146            47          54  0031-sk_data_ready.cocci
+                  4.4                17.9       179            44          10  genl-const.cocci
+              7.11111             49.6667       447            64           9  0019-usb_driver_lpm.cocci
+             0.571429             4.14286        58             8          14  get_ts_info.cocci
+              11.5333                45.4       681           173          15  0001-netlink-portid.cocci
+              2.96667               16.35       981           178          60  0002-no_dmabuf.cocci
+             0.444444             1.77778        32             8          18  0002-gpio-parent.cocci
+             0.512821             1.89744        74            20          39  0002-group_attr_bus.cocci
+             0.769231             2.79487       109            30          39  0001-group_attr_class.cocci
+              1.46375             5.62538      3724           969         662   all-SmPL.cocci
+
+    Patch total diff wc -l: 3087 SmPL total diff wc -l: 3724 Total total diff wc -l: 6811
+    Patch diff % contribution: 45.3237 SmPL diff % contribution: 54.6763
+
+See also
+--------
+
+- :doc:`To-Do List <hacking/todo>`
+- :doc:`License <../../license>`
diff --git a/source/documentation/backports/hacking/todo.rst b/source/documentation/backports/hacking/todo.rst
new file mode 100644
index 0000000..07244b0
--- /dev/null
+++ b/source/documentation/backports/hacking/todo.rst
@@ -0,0 +1,120 @@
+Documentation/backports/hacking/todo
+====================================
+
+The Linux kernel backports TODO list.
+
+make localmodconfig support
+---------------------------
+
+The Linux kernel has *make localmodconfig* support, random users
+shouldn't be expected to know what modules they need, so in order to
+allow users to get only the drivers they need built we'd need something
+similar to *make localmodconfig*. There are a few ways to do this. The
+best way would be to get upstream a mapping of a kernel object of a
+device to list its respective Kconfig. We'd also need a map of Kconfig
+changes over time as the kernel advances so that if a user is on an
+older system their old kobject Kconfig could be mapped to a new one.
+This should require changes upstream.
+
+Other simpler solutions are to rely on 'lspci -k' output and map this to
+respective device drivers but this solution would be PCI bus specific.
+We should review how the upstream *make localmodconfig* currently works
+and improve upon that to enable support for it on backports.
+
+Who's working on this?
+~~~~~~~~~~~~~~~~~~~~~~
+
+No one.
+
+Module namespaces
+-----------------
+
+Module namespace can consist of either adding prefixes to existing
+symbols or modifying the Linux kernel module data structure so that upon
+request for a symbol it's own namespace can be inspected for its
+requested namespace. The Linux kernel backports project embraces
+prefixing backported versions of symbols by prefixing backported
+versions of symbols with *backports\_*. A macro LINUX_BACKPORT() was
+added to help with this. For example::
+
+    #define crc8 LINUX_BACKPORT(crc8)
+
+Andi Kleen introduced the modular structure modification version of
+`module namespaces
+<http://thread.gmane.org/gmane.linux.network/78674>`__ back in 2007 but
+`Rusty Russell nacked these patches
+<http://article.gmane.org/gmane.linux.kernel/606885>`__. Because of this
+we're left with remapping modules to their own namespaces without
+modifying the in-kernel module structure. It **may** be possible to
+somehow provide module namespaces without requiring modifications to the
+in-kernel module structure, but such mechanisms would end up being
+hacks. We need to evaluate if we can figure a clever way to support this
+that is not so error prone or if we want to respinning Andi's patches
+with the intent to help support kernel backporting.
+
+Original motivation for module namespaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here's a brain dump from Andi about the original motivation behind
+module namespaces:
+
+The original intent was to provide a cleaner export symbol API.
+
+There are roughly two classes of exported symbols:
+
+- Generally usable, well designed, interfaces intended to be used by
+  multiple modules (e.g. functions for drivers to register themselves or
+  library functions)
+- Special purpose exports that are only really for a single module, but
+  are not intended as a general interface. These interfaces are usually
+  not really clean and reusable.
+
+The idea was to mark the later special purpose exports with the name of
+the module that is supposed to them. They wouldn't be available to
+everybody else and wouldn't become part of the general kernel module
+API.
+
+Motivations
+~~~~~~~~~~~
+
+At times Linux distributions may choose, for whatever support-nightmare
+reasons, to support two versions of a subsystem module and have two
+separate device drivers use a different version of that subsystem. The
+reason this is ill-advised is we stand to gain by having development
+done on the upstream and latest versions of each subsystem and drivers;
+that backports framework allows you to get that. An example helps to
+clarify here. Suppose a distribution wants to ship with an old version
+of mac80211 and have the iwlwifi driver use it, but for ath9k they'd
+want to ship the newer version of mac80211 and new version of ath9k.
+This cannot be supported unless module namespaces are created.
+
+Another more reasonable motivation is to avoid regressions with features
+/ symbols being updated only for backported drivers. Non-backported
+drivers will use the non-backported version of the routine. This should
+avoid regressions with non-backported drivers using these routines.
+
+Who's working on this?
+~~~~~~~~~~~~~~~~~~~~~~
+
+No one.
+
+DKMS support
+------------
+
+Someone seems to want add support for `DKMS
+<https://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support>`__. Who
+was that? What benefits does this bring? Isn't DKMS for proprietary
+modules? If so we don't want this support. We don't want proprietary
+drivers using the Linux kernel backports framework.
+
+DKMS is for proprietary modules only because all proprietary modules are
+out-of-tree, and DKMS is for all out-of-tree modules, whether they are
+proprietary or not. Since Linux kernel backports are out-of-tree, DKMS
+brings the benefit of automagically keeping existing backports active
+when a new kernel is installed, rather than going back to the in-tree
+modules with every new kernel.
+
+Who's working on this?
+~~~~~~~~~~~~~~~~~~~~~~
+
+No one
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>`.
+
diff --git a/source/documentation/compat-drivers/additional-patches.rst b/source/documentation/compat-drivers/additional-patches.rst
new file mode 100644
index 0000000..f0cf027
--- /dev/null
+++ b/source/documentation/compat-drivers/additional-patches.rst
@@ -0,0 +1,225 @@
+Documentation/compat-drivers/additional-patches
+===============================================
+
+This is now deprecated use :doc:`hacking on backports <../backports/hacking>`.
+
+Additional patches to stable releases
+-------------------------------------
+
+compat-drivers **prioritizes** pushing software to be **upstreamed**
+into *respective* Linux subsystem development trees. The stable
+compat-drivers releases are based on vanilla stable kernels and extra
+version stable (3.x.y) releases as published through the
+`linux-stable.git
+<http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git;a=summary>`__
+tree. Stable fixes are propagated through the `stable kernel fix
+propagation mechanism
+<http://wireless.kernel.org/en/users/Documentation/Fix_Propagation>`__.
+At times however the `stable kernel fix propagation mechanism
+<http://wireless.kernel.org/en/users/Documentation/Fix_Propagation>`__
+may not allow OEMs/OSVs/users to get the latest stable patches in time
+for their own needs. Other times, some patches which are not necessarily
+*"stable"* fixes may be desired to be integrated into a stable release
+by a hardware manufacturer, for one reason or another. At times, a
+subsystem maintainer may be on vacation and stable fix patches may take
+a while to get to users. In the worst case scenario some patches may not
+have been submitted for public review yet, for whatever reason, but it
+may be desired to merge some temporary patches on a stable release.
+Because of all these reasons compat-drivers has extended the `stable
+kernel fix propagation mechanism
+<http://wireless.kernel.org/en/users/Documentation/Fix_Propagation>`__
+by enabling additional types of patches to be merged into a stable
+release. **Upstream first** is still prioritized by categorizing these
+patches.
+
+There are five categories to compat-wireless' extra patches:
+
+- pending-stable
+- linux-next-cherry-picks
+- linux-next-pending
+- crap
+- unified-drivers
+
+We document these below.
+
+Legend of additional patches
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Releases can either be vanilla releases or have a series of additional
+patches applied to the release on top of the vanilla release. A flag is
+appeneded at the end of a release to annotate patches from a specific
+directory have been applied to this release. The appended extra flag
+meanings follows::
+
+    * -s - get and apply pending-stable/ from linux-next.git
+    * -n - apply the patches linux-next-cherry-picks/ directory
+    * -p - apply the patches on the linux-next-pending/ directory
+    * -c - apply the patches on the crap/ directory
+    * -u - apply the patches on the unified-drivers/ directory
+
+Release with no extra flags are simply vanilla releases of the kernel.
+Users / Linux distributions are encouraged to use the *-uspn* releases
+if they are available, otherwise the *-spn* relases as these releases
+will have extra fixes not yet propagated. The *-s* flag for example
+indicates that the release has patches marked as stable which will be
+released by the next 3.x.y release of the kernel so you might as well
+get them now. Linux distributions are encouraged to use the extra
+flagged releases as well. We provide the vanilla releases for those
+Linux distributions which just want vanilla for whatever reason.
+
+Each category is documented below.
+
+Annotating cherry pick preference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to annotate that a patch should be considered for inclusion
+into the stable releases of compat-drivers under
+linux-next-cherry-picks/ you can annotate it by adding a tag on the
+commit log line, *Cc: backports@vger.kernel.org*. An example follows. By
+annotating these patch a script can be used to scrape linux-next for
+extracting these patches when building a stable release::
+
+   commit 061acaae76dfb760f4f3fddf0cde43915b7d673c
+   Author: Luis R. Rodriguez <rodrigue@qca.qualcomm.com>
+   Date:   Wed Dec 7 21:50:07 2011 +0530
+
+       cfg80211: allow following country IE power for custom regdom cards
+       
+       By definition WIPHY_FLAG_STRICT_REGULATORY was intended to allow the
+       wiphy to adjust itself to the country IE power information if the
+       card had no regulatory data but we had no way to tell cfg80211 that if
+       the card also had its own custom regulatory domain (these are typically
+       custom world regulatory domains) that we want to follow the country IE's
+       noted values for power for each channel. We add support for this and
+       document it.
+       
+       This is not a critical fix but a performance optimization for cards
+       with custom regulatory domains that associate to an AP with sends
+       out country IEs with a higher EIRP than the one on the custom
+       regulatory domain. In practice the only driver affected right now
+       are the Atheros drivers as they are the only drivers using both
+       WIPHY_FLAG_STRICT_REGULATORY and WIPHY_FLAG_CUSTOM_REGULATORY --
+       used on cards that have an Atheros world regulatory domain. Cards
+       that have been programmed to follow a country specifically will not
+       follow the country IE power. So although not a stable fix distributions
+       should consider cherry picking this.
+       
+       Cc: backports@vger.kernel.org
+       Cc: Paul Stewart <pstew@google.com>
+       Cc: Rajkumar Manoharan <rmanohar@qca.qualcomm.com>
+       Cc: Senthilkumar Balasubramanian <senthilb@qca.qualcomm.com>
+       Reported-by: Rajkumar Manoharan <rmanohar@qca.qualcomm.com>
+       Signed-off-by: Luis R. Rodriguez <mcgrof@qca.qualcomm.com>
+       Signed-off-by: John W. Linville <linville@tuxdriver.com>
+
+pending-stable patches
+~~~~~~~~~~~~~~~~~~~~~~
+
+These are patches merged into linux-next.git but that have not yet been
+merged into the linux-stable.git tree.
+
+From the pending-stable/README::
+
+   Often right before the merge window we get a block on non
+   oops/regression fixes for stable fixes. Some stable fixes
+   often get propagated afterwards during the extraversion
+   maintenance of the kernels. Right before the merge window
+   circa rc4 and rc5 subsystem maintainers get pegged if they
+   throw in non oops/regression fixes for Linus or their
+   respective upstream maintainer. While this makes sense
+   for tree management and stable release considerations we
+   still need to get users some stable patches propagated.
+
+   This directory is there to help with that. Only patches
+   which have been merged into linux-next.git will be included
+   in this directory which means you must post it and the maintainer
+   should have merged it and Stephen would have picked it up.
+
+   This directory will always be empty for bleeding edge
+   releases as bleeding edge releases are always based on
+   linux-next already. This directory only makes sense for
+   stable release of the kernel, and it we will always try
+   to use it, in case there are stable fixes not yet propagated.
+
+linux-next-cherry-picks patches
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From the linux-next-cherry-picks/README::
+
+   We work hard to get patches in time onto the stable
+   tree but sometimes a few things slip out, and sometimes a
+   stable fix is simply too big in size to be merged into
+   stable. In such cases though we do believe some of these
+   patches are still relatively important to either enable new
+   hardware which escaped the late rc cycles or to correct some
+   behaviour which might be too late for stable. We apply
+   these patches by default as they will be supported on these
+   releases.
+
+   The larger the number of patches you see in this directory
+   the more we should be ashamed. We should strive to reduce this
+   to 0 all the time.
+
+   This directory will always be empty for bleeding edge
+   releases as bleeding edge releases are always based on
+   linux-next already.
+
+linux-next-pending patches
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From the linux-next-pending/README::
+
+   You must have a really good reason to be adding files
+   in this directory. The requirement is your patches must have
+   been posted to a public mailing list for the subsystem you are
+   working on. Each patch you add here must have a really good
+   explanation on the top of the file which clarifies why the
+   patch has not yet been merged OR specify it on the commit log
+   when you add it on compat-wireless.
+
+   We try to avoid having patch files because but we understand
+   if you might because you need to test code posted but not yet
+   merged into linux-next or a stable kernel release. This can happen
+   often during the merge window, when the maintainers are unavailable,
+   on vacation, suck at what they do, or for any other uncontrollable
+   reasons.
+
+crap patches
+~~~~~~~~~~~~
+
+From the crap/README::
+
+   If you are including patches into this directory you
+   must be fixing some critical bug for a customer which needs
+   immediate release or immediate testing.
+
+   Alternatively you would use this to apply some sort of
+   crap code you are maintaining.
+
+   You must have a really good reason to be adding files
+   in this directory. If possible you should explain your
+   reasoning of why the patch is getting included here and
+   not upstream and why it hasn't even yet been posted.
+
+   You should avoid these patches at all costs.
+
+unified-drivers patches
+~~~~~~~~~~~~~~~~~~~~~~~
+
+From the unified-drivers/README.md::
+
+   compat-drivers supports developers to supply a unified
+   driver git tree which is being used to target support
+   for getting the driver in line with requirements for
+   linux-next. Once the driver gets upstream the driver
+   gets removed and we cherry pick updated version of the
+   driver directly from linux upstream.
+
+   The code provided on this tree must try to adhere to
+   conventions for targetting inclusion into linux-next.
+   The compat-drivers patches/unified-drivers/ directory
+   allows for any additional required backport delta to
+   be addressed for the supplied driver. This allows
+   development and transformation of the driver to always
+   be targetting linux-next and allows for backporting
+   to be dealt with separately.
diff --git a/source/documentation/compat-drivers/hacking.rst b/source/documentation/compat-drivers/hacking.rst
new file mode 100644
index 0000000..03aa979
--- /dev/null
+++ b/source/documentation/compat-drivers/hacking.rst
@@ -0,0 +1,248 @@
+Documentation/compat-drivers/hacking
+====================================
+
+This is now deprecated use :doc:`hacking on backports <../backports/hacking>`.
+
+This section deals with development details of compat / compat-drivers
+and the other trees it uses. If you want to make your own compat-drivers
+tarballs, or if you see something busted with compat-drivers or just
+want to add something new or an enhancement this is the guide for you.
+
+Git trees you will need
+-----------------------
+
+compat-drivers backports a few subsystems down to older kernels. To be
+able to synchronize backporting the latest and greatest the
+`linux-next.git
+<http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git;a=summary>`__
+tree is used as its main source for kernel updates. General Linux kernel
+compatibility is addressed through a general kernel compatibility tree,
+`compat.git <https://github.com/mcgrof/compat>`__. compat-drivers then
+has its own tree for specific subystem target backports. You will then
+need to checkout a few trees to start hacking on compat-drivers, you can
+use the :doc:`instructions on getting all required code <../../code>`
+to get all trees but below we provide the list of the git trees used.
+
+::
+
+    git://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git
+    git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
+    git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+    git://github.com/mcgrof/compat.git
+    git://github.com/mcgrof/compat-drivers.git
+
+Linux next
+----------
+
+The `linux-next.git
+<http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git;a=summary>`__
+tree brings all subsystems being worked on for the **next kernel
+release** into one tree. So if the current rc kernel is v3.6-rc1, this
+means linux-next will have what people today are working on for the 3.7
+kernel release.
+
+backports components
+--------------------
+
+Go read the :doc:`backports documentation <../../documentation>` for a list of
+backport components and ensure you understand what each one is supposed
+to do. Below is a quick description though for the big picture.
+
+compat.git
+~~~~~~~~~~
+
+The compat git tree is a general kernel compatibility layer which can be
+shared amongst different compatibility projects, or drivers.
+compat-drivers is just one of the kernel compatibility projects using
+compat.git. compat.git builds a general compatibility module, compat,
+and any additional modules to let you get new general kernel updates
+from future kernels on your old kernels.
+
+compat-drivers.git
+~~~~~~~~~~~~~~~~~~
+
+Anything that is not general kernel compatibility but instead specific
+to a subsystem goes into compat-drivers.git. After you've cloned all
+three trees, linux-next.git, compat.git and compat-wireless.git you need
+to change into the compat-drivers directory and tell compat-drivers
+where you linux-next and compat.git trees are. You do this with
+environment variables GIT_TREE and GIT_COMPAT_TREE. You can do for
+example::
+
+   export GIT_TREE=/home/user/linux-next/
+   export GIT_COMPAT_TREE=/home/users/compat/
+
+Then you can then update your local sources based on these
+linux-next.git and compat.git trees::
+
+   scripts/admin-clean.sh   - Cleans the compat-drivers tree
+   scripts/admin-update.sh  - Updates compat-drivers with your git tree
+   scripts/admin-refresh.sh - Does the above two
+
+Adding new drivers
+------------------
+
+Most new drivers are enabled for compilation. If see a driver you would
+like enabled try adding it into the mix, test them and if they work
+enable them and send the respective patches.
+
+Generating stable releases
+--------------------------
+
+You can make stable releases yourself by checking out the specific
+branch for the target stable kernel release you want on each git tree:
+
+- `linux-stable.git <http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git;a=summary>`__
+- `compat-drivers.git <https://github.com/mcgrof/compat-drivers>`__
+- `compat.git <https://github.com/mcgrof/compat>`__
+
+You will also want an updated `linux-next.git
+<http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git;a=summary>`__,
+you want to ensure that the tag for the target kernel you want is
+present if you want to cherry pick out stable patches from it. So for
+example if v3.5.1 was released you want to ensure the `linux-next.git
+<http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git;a=summary>`__
+tree you have is updated with the v3.5.1 tag. The `linux-next.git
+<http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git;a=summary>`__
+tree however is **not** carry the extra version stable releases however
+though so to add these tags you can add the both the linux.git and
+linux-stable.git as remotes to your **linux-next/.git/config** file::
+
+   [remote "next"]
+           fetch = +refs/heads/*:refs/remotes/origin/*
+           url = /home/mcgrof/linux/.git
+   [remote "stable"]
+           fetch = +refs/heads/*:refs/remotes/origin/*
+           url = /home/mcgrof/linux-stable/.git
+
+Then do on your linux-next directory::
+
+   git fetch next
+   git fetch -t next
+   git fetch stable
+   git fetch -t stable
+
+Now, for example if you wanted to make a v3.5.y stable release, you
+would do::
+
+   # On linux-next.git:
+   mcgrof@tux ~/linux-next (git::master)$ git fetch
+   remote: Counting objects: 43056, done.
+   ... etc ...
+   mcgrof@tux ~/linux-next (git::master)$ git reset --hard origin
+   HEAD is now at 74bdbee Add linux-next specific files for 20110329
+   # Now get kernel extraversions on linux-next.git, this allows you
+   # to extract stable patches from linux-next.git when the linux-2.6-allstable
+   # tree moves to a new extraversion release.
+   mcgrof@tux ~/linux-next (git::master)$ git fetch stable
+   mcgrof@tux ~/linux-next (git::master)$ git fetch -t stable
+
+   # For compat-drivers.git:
+   mcgrof@tux ~/devel/compat-drivers (git::master)$ git checkout -b linux-3.5.y origin/linux-3.5.y
+   Branch linux-3.5.y set up to track remote branch linux-3.5.y from origin.
+   Switched to a new branch 'linux-3.5.y'
+   mcgrof@tux ~/devel/compat-drivers (git::linux-3.5.y)$
+
+   # For compat.git:
+   mcgrof@tux ~/compat (git::master)$ git checkout -b linux-3.5.y origin/linux-3.5.y
+   Branch linux-3.5.y set up to track remote branch linux-3.5.y from origin.
+   Switched to a new branch 'linux-3.5.y'
+   mcgrof@tux ~/compat (git::linux-3.5.y)$ 
+
+   # For linux-stable.git:
+   mcgrof@tux ~/linux-stable (git::master)$ git checkout -b linux-3.5.y origin/linux-3.5.y
+   Branch linux-3.5.y set up to track remote branch linux-3.5.y from origin.
+   Switched to a new branch 'linux-3.5.y'
+
+Once you have the appropriate branches checked out, you can use a script
+designed to let you make a release:
+
+#. First tell compat-wireless scripts your target GIT_TREE
+#. from where you want to suck out code from is the stable tree::
+
+        mcgrof@tux ~/devel/compat-drivers (git::linux-3.5.y)$ export GIT_TREE=/home/mcgrof/linux-stable/
+
+#. Then generate a stable release::
+
+    mcgrof@tux ~/devel/compat-drivers (git::linux-3.5.y)$ ./scripts/gen-stable-release.sh -s -n
+    Skipping linux-stable git tree update checks for branch: linux-3.5.y
+    On linux-stable: linux-2.3.5.y
+    You said to use git tree at: /home/mcgrof/linux-stable for linux-next
+    Copying /home/mcgrof/linux-stable/include/linux/ieee80211.h
+    Copying /home/mcgrof/linux-stable/include/linux/ieee80211.h
+    Copying /home/mcgrof/linux-stable/include/linux/nl80211.h
+    Copying /home/mcgrof/linux-stable/include/linux/pci_ids.h
+    ... Creating compat-wireless-3.5.1-1-sn.tar.bz2 ...
+
+    Compat-wireles release: compat-wireless-v3.5.1-1-sn Size: 4.3M
+    compat-wireless-v3.5.1-1-sn.tar.bz2 sha1sum: b0ca93dbda466b22ed76a8e4792c89931090d7b3 compat-wireless-v3.5.1-1-sn.tar.bz2
+    Release: /tmp/staging/compat-wireless/compat-wireless-v3.5.1-1-sn.tar.bz2
+
+Note that if you supplied the -s flag you will want to review the output
+for the place where it generates the pending-stable patches. If the
+respective target upstream tag was not found on linux-next.git it will
+tell you.
+
+If you want to add additional non-upstream patches you can use the crap/
+directory and use the -c flag as well. When people review your tarball
+they can then find your delta easily. If you submit patches upstream you
+can stuff them into linux-next-pending/ and use -p. If your patch is
+upstream on linux-next.git you can cherry pick it out and stuff it into
+linux-next-cherry-picks/ and use -n. The purpose of all this effort is
+to enable customizations but to also allow reviewers to quickly find
+deltas and ensure code gets upstream properly. Check each respective
+directory README for a review of the directories intent and content.
+
+Sending patches
+---------------
+
+compat and compat-drivers contributions follow the contribution model
+implemented by the Linux kernel. Patches or pull requests for compat and
+compat-drivers must have be signed-offed. If you don't sign off on them
+**they will not accepted**. This means adding a line that says
+"Signed-off-by: Name " at the end of each commit, indicating that you
+wrote the code and have the right to pass it on as an open source patch.
+For exact definition of what the Signed-off-by tag is you can read the
+definition of the "**Developer's Certificate of Origin 1.1**", which you
+can read here:
+
+http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html
+
+Remember there are three trees. linux-next itself is a conglomeration of
+kernel git trees itself, so patches for linux-next.git should be sent to
+each respective subsystem for which the patches are targeted for. So for
+example for 802.11 you will want to send them to John Linville and cc
+linux-wireless, for further guidelines on this see the `Submitting
+Patches guidelines for 802.11
+<http://wireless.kernel.org/en/developers/Documentation/SubmittingPatches>`__.
+As another example, for bluetooth you will want to send them to Gustavo
+Padovan and cc the linux-bluetooth mailing list. If your patch touches
+on others areas of the kernel refer to the MAINTAINERS file on the
+kernel.
+
+For compat.git and compat-drivers.git please send patches against to::
+
+   To: Luis R. Rodriguez <mcgrof@kernel.org>
+   CC: backports@vger.kernel.org
+   Subject: [PATCH] compat-2.6: fix foo
+
+For patches for compat.git please use a subject like the following::
+
+   Subject: [PATCH] compat: fix foo
+
+For compat-drivers.git please use a subject like the following::
+
+   Subject: [PATCH] compat-drivers: fix foo
+
+Patches are preferred sent with a clear commit log entry, if unfamiliar
+with how to send patches please refer to `a git guide
+<http://wireless.kernel.org/en/developers/Documentation/git-guide>`__.
+
+TODO
+----
+
+- Dialog (make menuconfig) option for this package -- :doc:`../../config-brainstorming`
+- Add support for `DKMS <https://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support>`__
+- Add more subsystems
+- media (e.g. DVB-T devices)
+
diff --git a/source/documentation/compat.rst b/source/documentation/compat.rst
new file mode 100644
index 0000000..b804edc
--- /dev/null
+++ b/source/documentation/compat.rst
@@ -0,0 +1,336 @@
+Documentation/compat
+====================
+
+This is now deprecated, use :doc:`hacking on backports <backports/hacking>`.
+
+This page is dedicated to compat, a generic Linux kernel backport
+compatibility module that has been brewing since 2009. The compat module
+provides functionality introduced in newer kernels to older kernels
+through a set of header files and exported symbols. The compat module
+allows code from newer kernel releases to be used on older kernels
+without modifications with a few exceptions. Exceptions to achieve
+automatically backporting kernel code through the compat module are
+dealt with through specific mechanisms documented in the :doc:`compat-drivers
+project page <compat-drivers>` and most recently through the `slides
+used at the 2011 Linux Plumbers presentation on automatically
+backporting the kernel
+<http://www.linuxplumbersconf.com/2011/ocw/system/presentations/771/original/kernel-backport-for-good.odp>`__
+and its `follow up presentation
+<https://docs.google.com/presentation/d/1axVNEGwKZjnzG1ocdd289WMqPxzJ3qfMv70ghGcnUKc/edit>`__
+at the 2012 Linux Collaboration summit in San Francisco.
+
+By using compat and frameworks such as :doc:`compat-drivers
+<compat-drivers>`, and techniques to integrate `additional patches
+<http://wireless.kernel.org/en/users/Download/stable/#Additional_patches_to_stable_releases>`__
+into upstream releases that prefer and push for upstream, we hope to
+ensure developers can prioritize working directly upstream on the Linux
+kernel and provide deliverables to end users and customers for any
+target kernel.
+
+compat-drivers today automatically backports the `Wireless
+<http://wireless.kernel.org/>`__, `Bluetooth <http://www.bluez.org/>`__
+and `Ethernet
+<https://www.linuxfoundation.org/collaborate/workgroups/networking/ethernet>`__
+drivers directly from the Linux kernel on a daily basis by using
+`linux-next.git
+<http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git;a=summary>`__.
+We also make `stable backport releases
+<http://wireless.kernel.org/en/users/Download/stable/>`__ by using the
+`linux-stable.git
+<http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git;a=summary>`__
+tree. We are considering expanding this framework to automatically
+backport more drivers -- patches are welcomed, otherwise, you'll have to
+wait until someone decides to integrate other subsystems.
+
+Supported kernels
+-----------------
+
+The goal is to backport new kernel functionality at least down to the
+oldest stable supported kernel listed on `kernel.org
+<https://kernel.org>`__, but backporting code further is certainly
+welcomed. Currently this means supporting backporting down to the 2.6.27
+Linux kernel release. Although our goal is to at least support backport
+efforts down to 2.6.27 the compat module currently has code to support
+even older kernels, and we welcome code to support older kernels as
+well.
+
+Mailing list
+------------
+
+See the :doc:`Backports mailing list <../mailing_list>` page.
+
+Presentations
+-------------
+
+Metrics explaining the amount of code saved by automatically backporting
+the kernel using compat and current research are explained.
+
+- `2011 Linux plumbers kernel backport presentation <http://linuxplumbersconf.org/2011/ocw/proposals/771>`__ (`slides <http://www.linuxplumbersconf.com/2011/ocw/system/presentations/771/original/kernel-backport-for-good.odp>`__)
+- `follow up presentation Automatically backporting the Linux kernel - 2012 Linux Collaboration summit <https://docs.google.com/presentation/d/1axVNEGwKZjnzG1ocdd289WMqPxzJ3qfMv70ghGcnUKc/edit>`__
+
+Estimating deliverables
+-----------------------
+
+Once you use compat and kernel framework integrators such as
+:doc:`compat-drivers <compat-drivers>` you should have no excuse to work
+outside of the upstream Linux kernel. In order to help guestimate when
+your upstream code will be available through a stable release such as
+the :doc:`compat-drivers stable releases <../releases>` you can rely on
+the `phb-crystall-ball <http://phb-crystal-ball.org/>`__.
+
+Tracking down when a feature went upstream
+------------------------------------------
+
+The compat module expect you to put functionality into either header
+files for defines and static inlines or into c files. This functionality
+must be tucked away under a file for the kernel release that introduced
+the functionality. To help aid you with your scavenger hunt on tracing
+down when a specific functionality was introduced into the upstream
+Linux kernel you can use several techniques. This section documents
+those techniques.
+
+Git tree setup for backporting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to understand how to track a feature in the Linux kernel you
+must first understand how the development of the Linux kernel happens.
+Below we provide a basic description of how this works.
+
+Greg Kroah-Hartman maintained the stable series of the Linux kernel.
+Linus hands off kernel maintainership to Greg after he blesses the first
+release of a stable kernel. Greg maintains the stable kernel via through
+the `linux-stable.git
+<http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git;a=summary>`__
+tree. Each stable release of the kernel has a respective
+origin/linux-3.x.y branch, where x is the current release number. The
+"y" here is literal, so for the 3.2 release there is an
+origin/linux-3.2.y branch that keeps track of the 3.2.1, 3.2.2 and
+future extra version releases of the 3.2 release. You can use the
+`linux-stable.git
+<http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git;a=summary>`__
+tree to verify if code is present on a stable release of a kernel.
+
+Linus maintains the release candidates of the Linux kernel (RC) up to
+the point he blesses away the first release of a kernel release. So for
+example Linus maintained the 3.2 kernel from the inception of 3.2-r1
+down to 3.2-rc7. During the 3.2-rc1 to 3.2-rc7 release Linus is supposed
+to only accept regression fixes. After that he releases the first
+blessed release of 3.2 and handed off maintainership to Greg. All the
+magic that went into 3.2-rc1 though happens in what we call the
+development cycle of the Linux kernel. The development cycle of the
+Linux kernel varies subsystem to subsystem but the idea can be best
+described in terms of the usage of two subsystem git trees. Subsystem
+maintainers typically have to maintain two git trees, a subsystem.git
+tree and a subsystem-next.git tree. The subsystem.git tree contains code
+that should go into Linus' tree during the regression testing of the RC
+release of the kernel. The subsystem-next.git contains code is being
+queued up for the next release of the Linux kernel, hence the "-next"
+postfix. All code in the subsystem-next.git trees is ephemeral, that is,
+what you see there today does not mean that it will be present tomorrow,
+it is code that is simply accepted on that day by the subsystem
+maintainer, but a lot of it can simply be dropped, and in fact Linus can
+reject merging it eventually. Linus will start merging all
+subsystem-next.git trees into his own tree during what we call, the
+merge window. This typically consists of a 2-3 week window period. For
+example the merge window for the 3.2 kernel started after Linus released
+the v3.1 kernel release on Mon Oct 24, 2011, and ended when Linus
+released the v3.2-rc1 release on Mon Nov 7, 2011, the merge window in
+this case lasted exactly 2 weeks.
+
+The merge window can often be painful though and to aid with this
+Stephen Rothwell has decided to take up merging all subsystem-next.git
+trees into one tree, `linux-next.git
+<http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git;a=summary>`__
+on a daily basis. He rants to each subsystem maintainer on any issues
+during his merge, including build breakage and general insanity.
+
+The implications here are that we can not only track code that is
+already released, but we can also predict what likely will go into the
+next release of the Linux kernel by using `linux-next.git
+<http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git;a=summary>`__.
+This means we can backport the Linux kernel proactively through every
+subsystem development cycle by using `linux-next.git
+<http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git;a=summary>`__.
+
+If this is still a bit fuzzy you can review the `wireless development
+process <http://wireless.kernel.org/en/developers/process>`__ for a
+review of how that specific subsystem development works. The development
+process there even includes a shiny diagram.
+
+Using git grep to identify what file adds new functionality
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First you want to identify what file added the functionality you seek to
+backport. Suppose you want to identify what file adds a new function,
+foobar(). To do this you can use::
+
+   git grep foobar\(
+
+to identify where foobar() is used in the entire Linux kernel. git grep
+will use the indexed data and at times can often run faster than a
+regular grep, as it will also skip object file in a regular grep search.
+Given that the point of compat is to backport functionality and that
+this functionality is typically shared between modules and subsystems,
+you can rest assured most functionality has a declaration in the header
+files of the Linux kernel. You can typically save yourself git grep time
+by starting to search through the include/ directory of the Linux
+kernel.
+
+::
+
+   git grep foobar\( include/
+
+Using git blame to identify introduction of a commit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Typically compat will have a lot of features already backported for
+older kernels, so to help backport new functionality you should be using
+`linux-next.git
+<http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git;a=summary>`__.
+To identify at what point a specific feature was added into the Linux
+kernel you can use git blame to identify the sha1sum of the commit that
+added the functionality you want to backport. At times though such
+functionality may have not been introduced via that commit but instead
+it may have simply been moved from one place to another. You can use::
+
+   git blame sha1sum~1
+
+to review if the functionality was present before the last commit you identified added that functionality to a file.
+
+Using git describe to identify where an commit was introduced
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you have identified the commit that introduced a specific
+functionality you can use git describe --contains sha1sum to give you
+the first commit tag that contains the commit. You can use the base of
+the tag to help you figure out the first kernel release that added the
+commit.
+
+For example, commit 600715dcdf567c86f8b2c6173fcfb4b873e25a19, or short,
+600715dc added to the Linux kernel the CONFIG_PHYS_ADDR_T_64BIT feature.
+We can determine that it was added on the v2.6.28 release by reviewing
+the results of using::
+
+   git describe --contains 600715dc
+
+which yields: v2.6.28-rc1~271^2^4~6. This means that in order to
+backport 600715dc we can edit two files on compat:
+
+- include/linux/compat-2.6.28.h
+- compat/compat-2.6.28.c
+
+Since this functionality can be dealt with header files the c file is
+not touched to backport this functionality. You can review the
+respective `compat CONFIG_PHYS_ADDR_T_64BIT backport via gitweb
+<https://github.com/mcgrof/compat/commit/4ec0edbd1cc2e6165e29f8ba466324e975e1cd73#include>`__.
+
+Testing across kernels
+----------------------
+
+The goal behind compat is to add features to provide backport but to
+older kernels but to do this successfully we must also ensure that each
+new patch added does not break building against a supported kernel. It
+may be a daunting task to get all supported kernels to and also to build
+against then, which is why we have started adding support to do all of
+this for you. Under the bin/ directory you will find two scripts which
+we document below:
+
+- get-compat-kernels
+- ckmake
+
+get-compat-kernels
+~~~~~~~~~~~~~~~~~~
+
+You can run this script to install all known supported kernels.
+Currently this will only work for Ubuntu, but `work is being considered
+<https://lkml.org/lkml/2012/2/6/85>`__ to standardize on the same
+kernels for any Linux distribution.
+
+ckmake
+~~~~~~
+
+You can run this to test compiling compat against supported kernels
+available. Although initially designed to support Ubuntu only the goal
+is to make this Linux distribution agnostic.
+
+compat modules
+--------------
+
+compat.git provides a few modules and headers to help with general
+kernel compatibility.
+
+compat module
+~~~~~~~~~~~~~
+
+Provides all exported symbols implemented in each respective kernel
+compat-2.6.xy.c files. Upon module load it just initializes the Linux
+kernel's *power management Quality Of Service* (aka **pm-qos**)
+Interface interface added as of the 2.6.24 kernel. No other things are
+initialized, the rest of the compat module just acts as a library of
+exported symbols.
+
+compat_firmware_class module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Another module which compat.git provides is a backport of the
+firmware_class module which got updated recently newer with a new
+request_firmware_nowait() to allow better asynchronous firmware
+uploading. This was added as of the 2.6.33 kernel. The firmware_class
+module has been backported into a new module called
+compat_firmware_class. A separate module has been defined instead of a
+direct replacement for firmware_class since your system may have old
+drivers which use the old request_firmware_nowait() and would bust if
+they used the new request_firmware_nowait(). The compat_firmware_class
+module registers its own sysfs subsystem and as such also gets udev
+events sent through a separate subsystem. Because of this a new udev
+rules file is required and provided.
+
+Research
+--------
+
+Active research is ongoing which could enhance automatically backporting
+the Linux kernel further. For details please read up on:
+
+- `Jesper Andersen & Julia L. Lawall - Generic Patch Inference <http://www.diku.dk/~julia/andersen_ase08.pdf>`__
+- `Coccinelle spatch <http://coccinelle.lip6.fr/>`__
+
+Consider one set of diffs that can be read by spdiff to produce an
+spatch. This could in theory allow us to backport all functionality on a
+kernel if only two or three sets of files were patched and interpreted
+by spdiff.
+
+Contributions
+-------------
+
+Contributions to compat follow the same mechanisms as used in the Linux
+kernel, this means you should provide as Singed-off-by tag as documented
+on the `Developer's Certificate of Origin 1.1
+<http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html>`__.
+
+Submitting patches
+------------------
+
+compat and compat-drivers contributions follow the contribution model
+implemented by the Linux kernel. Patches or pull requests for compat and
+compat-drivers must have be signed-offed. If you don't sign off on them
+they will not accepted. This means adding a line that says
+"Signed-off-by: Name email" at the end of each commit, indicating that
+you wrote the code and have the right to pass it on as an open source
+patch. For exact definition of what the Signed-off-by tag is you can
+read the definition of the "Developer's Certificate of Origin 1.1",
+which you can read here:
+
+http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html
+
+You can send patches as follows::
+
+   To: mcgrof@kernel.org
+   Cc: backports@vger.kernel.org
+   Subject: compat: foo
+
+License
+-------
+
+The compat module and code is all licensed under the same license as the
+Linux kernel and is considered a complete derivative work of the Linux
+kernel. For more information refer to the COPYRIGHT file.
diff --git a/source/documentation/integration.rst b/source/documentation/integration.rst
new file mode 100644
index 0000000..f6c4dac
--- /dev/null
+++ b/source/documentation/integration.rst
@@ -0,0 +1,247 @@
+Documentation/integration
+=========================
+
+The backports project first started out by supporting making releases as
+`packaged tarballs <Documentation/packaging>`__ whereby users can
+compile future versions of device drivers on older versions of Linux. As
+of tag backports-20141114 (first release branch will be based on
+origin/linux-3.19.y) backports supports **kernel integration** support.
+
+Kernel integration support allows you to:
+
+- **atomically integrate** future versions of device drivers
+- apply required patches to backport them
+- add hooks into kconfig to make them visible and usable
+- deal with conflicts with older versions of these same drivers
+
+By supporting kernel integration, the backports project can now support
+enabling use of automatically backported subsystems and drivers on older
+kernels without requiring modules, everything can be **built-in**.
+
+Kernel integration summary
+--------------------------
+
+In order to understand how kernel integration works familiarize yourself
+first :doc:`the backports development flow <backports/hacking>` and
+:doc:`the backports git tags and branches <backports/hacking>`.
+Usage of integration involves a *kernel source* and *kernel target*. As
+with :doc:`backports packaging <packaging>` each tag has a
+respective upstream linux-next or linux stable respective tag which can
+be used as a *kernel source*. The *kernel target* is a kernel tree of an
+older Linux release. For example if you want to integrate linux-next tag
+next-20141114 onto v3.15 you may want will want to use the tag
+backports-20141114 on the backports tree; the *kernel source* will be
+the linux-next tree tag next-20141114 (you can either reset the tree to
+that tag or use --git-revision tag to ./gentree.py) and the *kernel
+target* can be a linux git tree reset to the v3.15 tag. Each backports
+tag should be usable on all older supported kernels, this means you
+could have used as a *kernel target* a tree set to v3.0, v3.1.. up to
+today's latest release.
+
+Kernel integration use case
+---------------------------
+
+**Kernel integration** is an advanced technique part of the backports
+project which should make automate the task of completely integrating a
+specific version of a device driver based on future / current upstream
+releases on older kernel trees. This is typically more important where
+products are being supported using old kernels but the required device
+driver is only available on a future version of Linux. Linux
+distributions which want to make releases based on slightly older
+version of Linux but need newer device drivers can also make use of
+this. Kernel integration support enables two new important features when
+using backports now:
+
+- built-in support (non modular)
+- support for backporting features / components which the kernel only
+  supported via built-in
+
+*How you use integration is up to you*, we provide tools to help with
+the process and at least for now **make the first integration
+seamless**. If you are resetting your tree every time you base your
+release on a new version of Linux you can use kernel integration to bump
+the supported device drivers up to the latest known stable release for
+example, thereby minimizing the amount of manual cherry picks required.
+The backports project only provides patches required to backport device
+drivers from a future version of Linux down to a specific release of
+Linux, although it does not maintain specific cherry picks outside of
+what is required to get the driver to work on older versions of Linux
+specific cherry picks can easily be aggregated on top of the carried set
+of patches. Use of backports for cherry picking it outside of the scope
+of support for the project but it simply consists of adding your patches
+onto the patches/ directory, either in legacy patch form or SmPL form,
+if this strategy is followed its recommended a new directory be used to
+track these patches and a way to know if they need to be carried over
+when moving to a new version of Linux / backports.
+
+Integrating a release
+---------------------
+
+The same script that is used for generating :doc:`backports packaged
+tarballs <packaging>` is used for kernel integration, gentree.py as
+there is a lot of code to share between both strategies. An example will
+be provided of how to integrate a future set of supported device drivers
+onto an older release tree of the Linux kernel. Any kernel tree >= 3.0
+can be used as a *kernel target*, the *kernel source* will be any tag
+after next-20141114 from linux-next and backports-20141114, as well as
+any Linux release after v3.19 using the respective backports stable
+branch for that release. The example we provide here integrates
+linux-next next-20141114 onto the Linux kernel tree reset to v3.15.
+
+To backport linux-next tag next-20141114 onto a Linux tree reset to
+v3.15 do, you must first ensure your backports tree is on
+backports-20141114 and then you can use::
+
+    $./gentree.py --integrate --clean --gitdebug --git-revision next-20141114 ~/linux-next/ ~/linux/
+
+This assumes that ~/linux/ is a git tree reset to the tag v3.15. This
+should take 1-2 minutes on a typical laptop / system.
+
+Kernel integration menuconfig
+-----------------------------
+
+After kernel integration you will see an entry like the one that follows
+on your 'make menuconfig' menu::
+
+    [*] Backport Linux next-20141114-0-gd7e5a72 (backports backports-20141114-0-gded96b2)  --->
+
+.. image:: ../media/integration-menuconfig-start-3.15.png
+
+Under that menu you will see device drivers taken from linux-next tag
+next-20141114 and backported for you for use on v3.15. Enabling one
+device driver from a future version of Linux will require using only the
+latest version of the subsystem modules and other subsystem drivers. For
+example enabling cfg80211 and mac80211 from a future version of Linux
+will require you to only use future version of the respective device
+drivers. In order to enable the backported version of 802.11 drivers for
+example, you will have to enable first::
+
+       Networking support -->
+         Wireless -->
+
+But under that menu disable all options. You will also need to now
+disable all 802.11 device drivers under (including CONFIG_WLAN)::
+
+   Device Drivers  ---> 
+     Network device support  ---> 
+       [ ]   Wireless LAN  ---->
+
+Now to enable 802.11 drivers jump to the backports submenu to now enable
+backported 802.11 drivers::
+
+       Backports -->
+         cfg80211
+         mac80211
+         Wireless LAN  --->
+           etc
+
+You should now be able to enable any backports 802.11 device driver.
+Here's an example of full list of things you should see as of
+backports-20141114::
+
+.. figure:: Integration-menuconfig-drivers-3.15.png
+
+Audit kernel integration work
+-----------------------------
+
+Backports takes advantage of the previously supported --gitdebug flag
+for backport packaging in order to allow atomically tracking each atomic
+operation done when integrating all pieces of software from a future
+kernel to be supported on the *target kernel*. For this particular
+integration, for example, it generates 92 commits. Ordered with the last
+commit first, these are::
+
+   $ git log v3.15~1.. --pretty=oneline
+   c066a39ad047947dafbc4418ff10dadd3ad07921 apply integration patch 001-enable-backports/0001-enable-backports-built-in.patch
+   000658cb018b781a08f174df3b5521b4385de759 hooked backport to top level Kconfig
+   d78c278758a81a16d5f7d3dfd0782600cf5376ed disable unsatisfied Makefile parts
+   e9d0f1fbfa6ce67feb1cff978bca40875277c47f add kernel version dependencies
+   f5b738e65019fd51201688e3080d71c9ad5e8477 disable impossible kconfig symbols
+   7de02203cd5a501bd69ea6c98eac126f1eb57b61 rename config symbol / srctree usage
+   f70c7f185ca87d2f52ad72732fda3f1fa70f0891 add (useful) defconfig files
+   697ece5caa7e38f3ef34811b4440637c6d8fa080 convert select to depends on
+   9bf64ce6127ef2abfa2463b1063a236863e14f7b adjust backports config symbols we port
+   b42e104c94ab0d30967dc5a31062335370b10a4f prune Kconfig tree
+   b52feb5fef8a887170eee04383e1986a153dccd9 verify sources on top level backports Kconfig
+   61d328ea565d3f03573b3a99dd3f3896efef727b generate kernel version requirement Kconfig file
+   900a22cca078a7a5793d7c3b2bb444066677539a apply backport SmPL patch collateral-evolutions/network/0031-sk_data_ready.cocci
+   ef6d48763eb52f65bcd0eabfd8ae9e9f16e5074f apply backport SmPL patch collateral-evolutions/network/0019-usb_driver_lpm.cocci
+   f14786714aff5c94ae49b6f0acc3af095f5fbf5f apply backport SmPL patch collateral-evolutions/network/0001-netlink-portid.cocci
+   9f88ec9628756758132fe7c189c82575127ed838 apply backport SmPL patch collateral-evolutions/generic/0001-group-attr/0002-group_attr_bus.cocci
+   93b0c05507001c338a4efc4d9f3699bfee286b85 apply backport SmPL patch collateral-evolutions/generic/0001-group-attr/0001-group_attr_class.cocci
+   be4fb7cdd961f3d336086253712381190d7f8316 apply backport patch collateral-evolutions/network/0049-no-pfmemalloc/igb.patch
+   d048c6abbaa4a17eeed64b75bf071dd83e575959 apply backport patch collateral-evolutions/network/0048-no_ndo_xmit_flush/igb.patch
+   c606a1727efa4fb0aaddb103fc0ace9e7340110d apply backport patch collateral-evolutions/network/0047-write_iter/bluetooth.patch
+   09a99346f1625aa0ce203de1134145be750d6dc7 apply backport patch collateral-evolutions/network/0046-mmc_rescan_entered/mwifiex.patch
+   9fb5b3de864d7fa049ff0e304e2c04931351adbd apply backport patch collateral-evolutions/network/0044-no_user_ns_in_net/ieee802154.patch
+   a79ce2806e10dc7ac13c0f0f00b43e08454a8c29 apply backport patch collateral-evolutions/network/0043-ndo_set_vf_rate/igb.patch
+   01de0cf6c40dae21404e5fcf0f0e622a7cc4364c apply backport patch collateral-evolutions/network/0042-pci_error_handlers/ngene.patch
+   f6a578dd6050dfb76b0c9e79b6e7e9fc1539697f apply backport patch collateral-evolutions/network/0042-pci_error_handlers/igb_pci_error_handlers.patch
+   69c972277125ce73ca22d5436311c5718449669d apply backport patch collateral-evolutions/network/0042-pci_error_handlers/atl1e.patch
+   87664cd587c14623c386ac583f7dfebedfd07469 apply backport patch collateral-evolutions/network/0042-pci_error_handlers/atl1c.patch
+   102f85e8d0b698528bd05adb1fad73004330ca9e apply backport patch collateral-evolutions/network/0042-pci_error_handlers/alx.patch
+   807d99b29a7186a398a3895df8c22911a46c5686 apply backport patch collateral-evolutions/network/0041-devm_hwmon_device_register_with_groups/igb-devm_hwmon_device_register_with_groups.patch
+   5e399498c589af4f144a78590d6303bada824183 apply backport patch collateral-evolutions/network/0040-ethtool_cmd_mdix/igb_ethtool_cmd_mdix.patch
+   041bb3abc060f04b0924e2c313479430257a0b8a apply backport patch collateral-evolutions/network/0039-ethtool_rxnfc/igb_rxnfc.patch
+   91bc49e12a2c302eb6e264eeb6944806caaa2714 apply backport patch collateral-evolutions/network/0038-ethtool_rxfh_indir/igb_rxfh_indir.patch
+   24fe54661213f4d82642dd7eaeae92314ee2ca55 apply backport patch collateral-evolutions/network/0037-ethtool_get_module/igb_get_module.patch
+   5a8c3bf1e10a9dcd31f50c3acd3a42d6a4a5b3ac apply backport patch collateral-evolutions/network/0036-ethtool_eee/igb_ethtool_eee.patch
+   237294691d58ec7ff6e41fc6f48587bd7d6c1f7c apply backport patch collateral-evolutions/network/0035-skb_no_fcs/igb_skb_no_fcs.patch
+   fb1cb2e44c89847b04e2d021328ea548cbe05fa6 apply backport patch collateral-evolutions/network/0034-ndo_set_vf_spoofchk/igb_ndo_set_vf_spoofchk.patch
+   f24bb572ee690b3aac0e89fa2d04888e8a036d7c apply backport patch collateral-evolutions/network/0033-ndo_vlan_rx_vid/igb_ndo_vlan_rx_vid.patch
+   3878c64fc254f7acbd86e3539bf330b04730abb8 apply backport patch collateral-evolutions/network/0033-ndo_vlan_rx_vid/cdc_mbim.patch
+   c888e6433a8b2ac7c3e0058a4936836ab15c3f6d apply backport patch collateral-evolutions/network/0032-sriov_configure/igb_sriov_configure.patch
+   59ac89cb5e1fa8876555639bab09bc4a97673db5 apply backport patch collateral-evolutions/network/0030-qdisc_tx_busylock/ieee802154.patch
+   506736ea6f59fed1d323f77cf03915ebc6df3358 apply backport patch collateral-evolutions/network/0030-qdisc_tx_busylock/bluetooth.patch
+   5131db4cbec4ac8d7a6fb69246910644e0a8087d apply backport patch collateral-evolutions/network/0029-struct_hid_ll_driver-extensions/net_bluetooth_hidp_core.patch
+   9575c214edcc921e75910b881d3db6a69cd4b577 apply backport patch collateral-evolutions/network/0028-select_queue/mwifiex.patch
+   eafd9157010633a1cc7b025382b72f9bea8bfe8b apply backport patch collateral-evolutions/network/0028-select_queue/mac80211.patch
+   4b7d5be3639ec2178a398c6a0730a8a9098f067e apply backport patch collateral-evolutions/network/0027-genl-const/nl80211.patch
+   2283432684181d75e6288b2bd4d9f502c713087d apply backport patch collateral-evolutions/network/0027-genl-const/nfc.patch
+   e5fec49c6b5c59dffe06f11a099e8df2c38de2cd apply backport patch collateral-evolutions/network/0027-genl-const/ieee802154.patch
+   7b0bd1c47c0a22240593c3860ea78e87310531db apply backport patch collateral-evolutions/network/0027-genl-const/hwsim.patch
+   3156a48fc2aa1eb028d5074d0f15f02a2a784366 apply backport patch collateral-evolutions/network/0026-ipv6_stub/cdc_mbim.patch
+   ab5ca0e7db55e7a68bae27c278dc159be531caf7 apply backport patch collateral-evolutions/network/0025-usb-sg/usbnet.patch
+   18634861a944029a6623f5dc582482d7fdd87bba apply backport patch collateral-evolutions/network/0024-led-blink-api/mac80211.patch
+   6895c3c9fefe90302577ccc0207e574dab5db4fb apply backport patch collateral-evolutions/network/0022-define-tracing/wil6210.patch
+   61b12eb789add8ea4f42343ba5754a2003f9ff85 apply backport patch collateral-evolutions/network/0022-define-tracing/cfg80211.patch
+   4d362e9144e6189248976e83b797e93b5be2210a apply backport patch collateral-evolutions/network/0022-define-tracing/ath6kl.patch
+   a7a3cebf434a294ef089823eedf7c2db8b41a042 apply backport patch collateral-evolutions/network/0021-umode_t-api-change/ath10k.patch
+   a25e701fe08b1f124307c17cfa1eb1879b26693d apply backport patch collateral-evolutions/network/0020-tty-termios/net_bluetooth_rfcomm_tty.patch
+   829c2477a533e03c8df4f64d60d3acbc260f2090 apply backport patch collateral-evolutions/network/0020-tty-termios/drivers_bluetooth_hci_ath.patch
+   4793ad2d27a5a98b99f1af0cc4369f4d2dc67a78 apply backport patch collateral-evolutions/network/0018-pv-trace-fixes/net_mac80211_trace.patch
+   cc3fcdfcd106be170937111f5b1e9282ea8b2f43 apply backport patch collateral-evolutions/network/0018-pv-trace-fixes/drivers_net_wireless_iwlwifi_iwl-debug.patch
+   77b4d3a92296542ada9af173729c29ff8edaa4f0 apply backport patch collateral-evolutions/network/0017-get_ts_info/igb_get_ts_info.patch
+   3a1b78fee0ed903f167f2038ce3f7b34b80fff31 apply backport patch collateral-evolutions/network/0017-get_ts_info/drivers_net_usb_usbnet.patch
+   7af04292e12cd6a3bd4933cbc2db33f678935985 apply backport patch collateral-evolutions/network/0017-get_ts_info/cdc_ncm.patch
+   c9c75a56434fa88c3b5387964d390c957109bb0e apply backport patch collateral-evolutions/network/0016-libertas-olpc-ec-wakeup/drivers_net_wireless_libertas_if_usb.patch
+   63959daeafbac9ff38dbc847cbbb9a61501be851 apply backport patch collateral-evolutions/network/0015-rename_pm_qos_request/drivers_net_wireless_ipw2x00_ipw2100.patch
+   5e7f8f9b32dcb984445bde43f69656c97b31c7e7 apply backport patch collateral-evolutions/network/0014-netlink_seq/net_wireless_nl80211.patch
+   35d5785bfdcdf579493f3076f3ac9bc397ce9597 apply backport patch collateral-evolutions/network/0013-fix-makefile-includes/net_wireless_Makefile.patch
+   5adbb25691d4745f5f47ffc493bfd32a063480ca apply backport patch collateral-evolutions/network/0013-fix-makefile-includes/bluetooth.patch
+   2258d123aec87c0a11515130d9297587633fdafc apply backport patch collateral-evolutions/network/0012-driver-quirks/drivers_net_wireless_cw1200_sdio.patch
+   d1f6fc792d3fba9ee20f31562c04e34af0f6daab apply backport patch collateral-evolutions/network/0011-mac80211-disable-tx-status/net_mac80211_tx.patch
+   a146dcd4c0db925dc8a3fec1ee93074b0a192c67 apply backport patch collateral-evolutions/network/0010-add-wext-handlers-to-netdev/net_wireless_core.patch
+   5e1b6f56f043608ee68cef35d7deda383b78fd01 apply backport patch collateral-evolutions/network/0008-net-user-ns.patch
+   5000b38d3dcc9434b19eaccde8aca21f0b271e12 apply backport patch collateral-evolutions/network/0007-lowpan-inet_frag_lru_move.patch
+   2ae7bbbdb7eb2c02058327dfc057ad841aede913 apply backport patch collateral-evolutions/network/0006-ieee802154-6lowpan-namespace.patch
+   fc28048373ae3c6637cedab606919e7817f6ffad apply backport patch collateral-evolutions/network/0005-disable-usb-net-asix.patch
+   50e3e5f2151ed76aef9a1ac7352959a806e55e6f apply backport patch collateral-evolutions/network/0004-disable-wext-kconfig.patch
+   98b551a9316154702270ac7164916e49180c0046 apply backport patch collateral-evolutions/network/0003-cfg80211-wext-padding/net_wireless_core.patch
+   0f5f1ae4483b16f187f074b676d19212dab814f8 apply backport patch collateral-evolutions/network/0003-cfg80211-wext-padding/include_net_cfg80211.patch
+   8cfeb3d0bdec62cccb0cf76f44ca2e7e5c5e9ff0 apply backport patch collateral-evolutions/network/0002-disable-dump-adjust-on-old-kernels.patch
+   166003e19c7a9ff28a43004ad27d68af3a3aace0 apply backport patch collateral-evolutions/media/0004-missing-include/ir-hix5hd2.patch
+   f1152ca58d2400a956a969ae88b80c35c449d6dc apply backport patch collateral-evolutions/media/0004-missing-include/hackrf.patch
+   94f80b0f595162569b70684d7ed87612b31a764f apply backport patch collateral-evolutions/media/0004-missing-include/airspy.patch
+   6d974050060a1d74d61b1927ac0f18ca0267e3d5 apply backport patch collateral-evolutions/media/0003-devnode_param_type/rc.patch
+   2678364bc96c15c9e39bdf901f60fb8bef5d9851 apply backport patch collateral-evolutions/media/0003-devnode_param_type/dvb-core.patch
+   04361b3134ed2cd078920eb651ec1a15c038a307 apply backport patch collateral-evolutions/media/0003-devnode_param_type/ddbridge.patch
+   b0a68f9e7b235ad44f64686a7657d65ededaeb87 apply backport patch collateral-evolutions/media/0002-no_dmabuf/v4l2.patch
+   102162ef4bda228fc2de08826f8c304001503b67 apply backport patch collateral-evolutions/media/0001-dma_mmap_coherent-revert.patch
+   780d84bd410b4252cfc4df431b5c0e8c6133fcef apply backport patch 0000-upstream-backport-changes/0005-uapi-compromise/mwifiex.patch
+   6a77c4dc3c16907373648a774678c0bf63b1f786 Add automatic backports
+   6e8820dfdd11eb2ef361f344ece8170e6776a151 modify top level backports/Kconfig with backports identity
+   c1e39709cfde12068fa3b693d71f72fc536d4df4 verify sources for automatic backports
+   9b34df472df8dbf0c3b518eab7a5e378c966fa3f Add driver sources
+   5b8285fa632ad085753da8e930c0ec2275c191ff Copied backport
+   1860e379875dfe7271c649058aeddffe5afd9d0d Linux 3.15
diff --git a/source/documentation/packaging.rst b/source/documentation/packaging.rst
new file mode 100644
index 0000000..2f3921e
--- /dev/null
+++ b/source/documentation/packaging.rst
@@ -0,0 +1,99 @@
+Documentation/packaging
+=======================
+
+The backports project makes release of two types of **packages** which
+provides device drivers from future versions of Linux usable on older
+Linux kernel releases.
+
+Backports package release types
+-------------------------------
+
+Both daily snapshots based on `linux-next
+<http://git.kernel.org/cgit/linux/kernel/git/next/linux-next.git>`__,
+and stable releases based `Linux's stable releases
+<http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git>`__
+are provided. Always use the latest *stable* available release unless
+you need a feature / fix only currently available on the linux-next
+based release. A backports-3.x release means device drivers from the
+Linux v3.x release have been taken, backported and made available for
+you to use on any kernel version prior to the release version.
+
+Usage guide
+-----------
+
+Building backports follows the same build mechanism as building the
+Linux kernel::
+
+   # as a user
+   make menuconfig
+   make -j4
+   # as root
+   make install
+   # reboot and enjoy
+
+Its understood users may not know how to configure the backports
+package, just like they may not know how to configure the Linux kernel,
+so a short cut is provided with default configuration files that can be
+used to only build their drivers / subsystems of interest. You can also
+just query the regular help menu::
+
+   make help
+   make defconfig-help
+
+If you use this option just use the 'make defconf-option' in replacement
+for *make menuconfig* above. For example to compile all wifi drivers::
+
+   # as a user
+   make defconfig-wifi
+   make -j4
+   # as root
+   make install
+
+Note that there are only default configuration files written for a few
+drivers while the project actually backports a lot of device drivers,
+the reason we have default configuration files for a few drivers is
+simply because developer have provided a default config options for
+them. What we really need is a 'make localmodconfig' support but that
+will take a while given that it involves mapping older kernel configs to
+newer kernel configs (which likely would be welcomed upstream as well).
+
+Cross compiling
+---------------
+
+To cross compile::
+
+    set -a
+    CROSS_COMPILE=${CROSS_COMPILE}
+    ARCH=${TARGET_CPU}
+    KLIB_BUILD=${DEV_PATH}/${LINUX_DIR}
+    KLIB=${TARGET_ROOT_ON_HOST}
+    set +a
+    make oldconfig  # menuconfig worked here too
+    make
+    make install
+
+The 'make install' target isn't currently sane for cross-builds due to
+the bacport_firmware_install script not respecting prefixes. For now you
+can comment out that script few others like initrd updates, from being
+run out of the Makefiles.
+
+Cross compile with Freescale's LTIB
+-----------------------------------
+
+To get backports happy in LTIB, use UNSPOOF/SPOOF_PATH to switch between
+host and cross environment. Example Build section in backports.spec::
+
+     %Build
+     export PATH=$UNSPOOF_PATH
+     
+     make menuconfig prefix=%{_prefix} \
+       CROSS_COMPILE=${TOOLCHAIN_PATH}/bin/${TOOLCHAIN_PREFIX} \
+       ARCH=$LINTARCH KLIB=${TOP}/rootfs/lib/modules/%{kversion} \
+       KLIB_BUILD=${TOP}/rpm/BUILD/linux
+     
+     export PATH=$SPOOF_PATH
+     
+     make prefix=%{_prefix} \
+       CROSS_COMPILE=${TOOLCHAIN_PATH}/bin/${TOOLCHAIN_PREFIX} \
+       ARCH=$LINTARCH KLIB=${TOP}/rootfs/lib/modules/%{kversion} \
+       KLIB_BUILD=${TOP}/rpm/BUILD/linux
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
parent	96836ca0c23f0f5eb766cfe0a39a72a3bc216f2a (diff)
download	backports-master.tar.gz