diff options
Diffstat (limited to 'source/documentation/compat-drivers')
| -rw-r--r-- | source/documentation/compat-drivers/additional-patches.rst | 225 | ||||
| -rw-r--r-- | source/documentation/compat-drivers/hacking.rst | 248 |
2 files changed, 473 insertions, 0 deletions
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) + |