Documentation/backports/hacking

From Driver Backports Wiki
(Difference between revisions)
Jump to: navigation, search
Line 95: Line 95:
 
ensure the intent is respected currently all symbols that we do work on 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
 
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''' that
+
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
 
if you use the backported symbols your software '''is considered derivative
 
works of the Linux kernel'''.
 
works of the Linux kernel'''.

Revision as of 17:02, 1 August 2013

Contents

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 by optimizing backporting collateral evolutions.

Git trees you will need

backports backports a few subsystems down to older kernels. To be able to synchronize backporting the latest and greatest the 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. This is now in one repository backports.git and not spitted over two any more.

You can generate backports based on different trees depending on your needs. We are supporting build based on linux-next.git, linux.git and 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.

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/mcgrof/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 [1].

You should target the master branch of the backports repository.

  1. Add directories and files that should be copied from the mainline kernel to copy-list
  2. 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.
  3. Add reference to the newly added driver directory in backport/Makefile.kernel if needed (just needed for new substems)
  4. Add reference to the newly added driver directory in backport/Kconfig if needed (just needed for new subsystems)
  5. 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
  6. 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 documentation.

Backports Makefile operation

Go read the backports Makefile operation documentation.

Sending patches

backports contributions follow the contribution model implemented by the Linux kernel. Patches or pull requests for backprots 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

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. 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: Luis R. Rodriguez <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.

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.

TODO

Go read the full TODO list on its own page.


88x31.png - This text is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

Personal tools