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