diff options
Diffstat (limited to 'README.patches')
| -rw-r--r-- | README.patches | 483 |
1 files changed, 448 insertions, 35 deletions
diff --git a/README.patches b/README.patches index 5d045c1c5..9b81a75be 100644 --- a/README.patches +++ b/README.patches @@ -1,58 +1,471 @@ -Mauro Carvalho Chehab 2005 Dec 02 +Mauro Carvalho Chehab <mchehab at infradead dot org> +2007 Jun 22 - The master copy of the video4linux and dvb kernel subsystem is now -maintained jointly at http://linuxtv.org/ +This file describes the general procedures used by the LinuxTV team (*) +and by the v4l-dvb community. -=== v4l-dvb snapshots available at linuxtv.org +(*) This is just an aka for the main developers involved in V4L/DVB +drivers. They are a volunteer and unremunerated group of people that +have the common interest of providing a good support on Linux for +receiving and capturing video streams from Web cams, Analog TV, Digital +TV and radio broadcast AM/FM. - We are now publishing periodic snapshots (about once a month or -before rellevant changes) at linuxtv.org. The main idea is to have -"stable" snapshots on Linuxtv. You can check it at: + CONTENTS + ======== -http://linuxtv.org/downloads/snapshots + 1. A Brief introduction about patch management + 2. Git trees' relationships with v4l/dvb development + 3. Mercurial trees used for v4l/dvb development + 4. Community best practices + 5. Knowing about newer patches committed at master hg repository + 6. Patch handling for kernel submission + 7. Patch submission from the community + 8. Identifying regressions with Mercurial -=== v4l-dvb quilt available at linuxtv.org +1. A Brief introduction about patch management + ========================================== - It is also available patches against latest development kernel at: -http://linuxtv.org/downloads/quilt +Current V4L/DVB development is based on a modern SCM system that +fits better into kernel development model, called Mercurial (aka hg). - patches/series shows the correct order to apply. +Kernel development model is based on a similar SCM, called git. While +very powerful for distributed development, git usage is not simple for +final users. That's the reason why hg was selected for V4L/DVB +development. -== Getting the latest Snapshot +There are some tutorials, FAQs and other valuable information at +http://selenic.com/mercurial about hg usage. - You must have mercurial installed in order to access the -repository. To get the latest sources from Hg you need to issue the -following command: +Mercurial is a distributed SCM, which means every developer gets his +own full copy of the repository (including the complete revision +history), and can work and commit locally without network connection. +The resulting changesets can then be exchanged between repositories and +finally merged into a common repository on linuxtv.org. -hg clone http://linuxtv.org/hg/v4l-dvb +A list of current available repositories is available at: + http://linuxtv.org/hg -* Patches should be built against v4l-dvb master Hg repository. +2. Git trees' relationships with v4l/dvb development + ================================================= -=== How to get your changes into the mainline tree? +The main kernel trees are hosted at http://git.kernel.org. Each tree +is owned by a maintainer. -1. Post your patches to the corresponding mailing list for review and -testing by other people. For analog or core changes, the mailing list is -video4linux-list@redhat.com. For DVB changes, the mailing list -is linux-dvb@linuxtv.org. The latest requires subscription. -http://linuxtv.org/lists.php +The main kernel trees is owned by Linus Torvalds, being located at: + http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git -2. Using [PATCH] at subject will help maintainers to better handle it. +The subsystem master tree is owned by the subsystem maintainer (Mauro +Carvalho Chehab) being located at: + http://git.kernel.org/?p=linux/kernel/git/mchehab/v4l-dvb.git -3. Please include a ChangeLog description in the headers of your patch. +Before committing into the master -git tree, the finished patches from +each maintainers tree are added on a staging tree, owned by the +subsystem maintainer, at: + http://linuxtv.org/hg/v4l-dvb -4. Every patch shall have a Developers Certificate of Origin like +The main function of this tree is to merge patches from other +repositories and to test the entire subsystem with the finished patches. -Signed-off-by: Your name <name@yoursite.com> +Users are welcome to use, test and report any issues via the mailing +lists or via the Kernel's bugzilla, available at: + http://bugzilla.kernel.org -with name of people envolving on making it. +Michael Krufky maintains a backport tree, containing a subset of the +patches from the subsystem tree that are meant to be sent to kernel +-stable team, at: + http://git.kernel.org/http://git.kernel.org/?p=linux/kernel/git/mkrufky/v4l-dvb-2.6.x.y.git - This should be a real name and address. The exact meaning of the -signed-off-by is postulated at linux source code, at file: +3. Mercurial trees used for v4l/dvb development + ============================================ + +V4L/DVB driver development is hosted at http://linuxtv.org. There are a +number of trees there each owned by a developer of the LinuxTV team. + +When a developer believes that he has patches done to be merged, he +sends a request the developers' mailing list and to the subsystem +maintainer. The patches are analyzed and, if they look ok, merged into +the master repository. + +It is good practice that each developer will have at least one tree +called 'v4l-dvb', which keeps their patches, and periodically update +this tree with the master tree's patches. + +4. Community best practices + ======================== + +From accumulated experience, there are some basic rules that should +be followed by the community: + +a) Every developer should follow the "rules of thumb" of kernel development + stated at Linux source code, especially those stated at kernel, + under: + Documentation/HOWTO Documentation/SubmittingPatches + Documentation/SubmittingDrivers + Documentation/SubmitChecklist + Documentation/CodingStyle + +b) All commits at mercurial trees should have a consistent message, + describing the patch. This is done by using: + + make commit + + This will run some scripts that check changed files, correct + bad whitespace and prepare the last Signed-off-by: field, as + described below. A good comment will have a brief + description at the first line, up to 68 characters wide, a blank + line, the patch author's name on the third line, a blank line, and + then a brief description, with no more than 80 chars per line, e. g.: + + This patch does nothing + + From: nowhere <nowhere@noplace.org> + + This is just a sample commit comment, just for reference purposes. + + This "patch" does nothing. + + Signed-off-by: nowhere <nowhere@noplace.org> + + All lines starting with # and all lines starting with HG: will be + removed from the mercurial commit log. + + *WARNING* Be careful not to leave the first line blank, otherwise hg + will leave subject blank. + + From: line shouldn't be omitted, since it will be used for the + patch author when converting to -git. + +c) For "make commit" to work properly, the HGUSER shell environment var + should be defined (replacing the names at the left): + + HGUSER="My Name <myemail@mysite.com>" + + If HGUSER is not set, then, if present, the username defined in the + user's ~/.hgrc file will be used. Use of the .hgrc file is preferred + over the HGUSER variable according to the hg man page. + + This name will be used for both the user metadata in the Hg commit + log and the initial values of the "From:" and "Signed-off-by:" lines + in the pre-made commit message. + + It is also possible to use a different login name at the site + hosting the repository, by using: + + CHANGE_LOG_LOGIN=my_log_name + + With this, "make push" will use my_log_name, instead of the name for + the current Unix user. + + Don't forget to export the vars at shell, with something like: + + export CHANGE_LOG_LOGIN HGUSER + + It is strongly recommended to have those lines in .bashrc or .profile. + +d) All patches shall have a Developers Certificate of Origin + version 1.1 in the commit log or the email description, signed by the + patch authors, as postulated in the Linux Kernel source at: + + Documentation/SubmittingPatches + + This is done by adding Signed-off-by: fields to the commit message. + + It is not acceptable to use fake signatures, e.g.: + + Signed-off-by: Fake me <me@snakeoilcompany.com> + + The email must be a valid one. + The author that is submitting the email should be at the button of + the author's signed-off-by (SOB) block. Other SOBs or Acked-by: will be + added at the bottom, marking that somebody else reviewed the patch. + + Each person who is in the kernel patch submission chain (driver author + and/or driver maintainer, subsystem/core maintainers, etc) will + review each patch. If they agree, the patch will be added to their + trees and signed. Otherwise, they may comment on the patch, asking + for some review. + +e) Although not documented at kernel's Documentation/, a common kernel + practice is to use Acked-by: tag. + + An Acked-by: tag usually means that the acked person didn't write the + patch, nor is in the chain responsible for sending the patch to + kernel, but tested or reviewed the patch and agreed that it was good. + + A patch acked-by can be added at hg trees, if received by each tree + maintainer. It is also common to receive acks after having a patch + inserted at master repository. In this case, the ack will be added + only at -git tree. + +f) If the patch also affects other parts of kernel (like Alsa + or i2c), it is required that, when submitting upstream, the patch + also goes to the maintainers of that subsystem. To do this, the + developer shall copy the interested parties. + + At mercurial tree, this can be handled automatically by the LinuxTV + scripts, by using the cc: meta tag, together with the Signed-off-by + lines. Something like: + + CC: someotherkerneldeveloper@someplace + Signed-off-by: nowhere <nowhere@noplace.org> + + This way, when a patch arrives mercurial hg tree, a mailbomb script + will copy the proper interested parties. + + When submitting a patch via e-mail, it is better to copy all interested + parties directly, by adding them as cc's to the email itself. + + Please note that those changes generally require ack from the + other subsystem maintainers. So, the best practice is to first ask + for their acks, then commit to the development tree or send the + patch via email with their Acked-by: already included. + +g) Sometimes, mainstream changes affect the v4l-dvb tree, and mast be + backported to the v4l-dvb tree. This kind of commit to the mercurial + tree should follow the rules above and should also have the line: + + kernel-sync: + + Patches with this line will not be submitted upstream. + +h) Sometimes it is necessary to introduce some testing code inside a + module or remove parts that are not yet finished. Also, compatibility + tests may be required to provide backporting. + + To allow compatibility tests, linux/version.h is automatically + included by the building system. This allows adding tests like: + + #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,5,0) + #include <linux/kthread.h> + #endif + + It should be noticed, however, that an explicit inclusion of + linux/version.h is required if it is needed to use KERNEL_VERSION() + macro (this is required, for example, by V4L2 VIDIOC_QUERYCAP + ioctl), otherwise, the driver won't compile when submitted to kernel. + + There are several compatibility procedures already defined + in "compat.h" file. If needed, it is better to include it after all + other kernel standard headers, and before any specific header + for that file. Something like: + + #include <linux/kernel.h> + #include <linux/module.h> + ... + #include <linux/videodev2.h> + #include <media/v4l2-common.h> + + #include "compat.h" + + #include "mydriver-header.h" + +should be included at the + files under v4l-dvb tree. This header also includes linux/version.h. + + To include testing code, #if 0 or #if 1 may be used. If this code + is meant to go also to kernel, a comment with the word "keep" should + be used, e.g: + + #if 0 /* keep */ + or + #if 1 /* keep */ + + The kernel submit scripts will remove the compatibility codes, the + tests for specific kernel versions and the #if 0/1 that doesn't have + the "keep meta tag". + + See the file v4l/scripts/gentree.pl for a more complete description + of what kind of code will be kept and what kind will be removed. + +i) To import contributed stuff to a developer's, a script is provided. + This allows an easy import of mbox-based patch emails. + This is done with: + + ./mailimport <mbox file> + + For it to work properly, git tools need to be installed on the local + machine, since git has a gitimport script that is used by mailimport. + Also, hg has a feature, called mqueue, that allows having several patches + that can be applied/unapplied for testing. mailimport trusts on it to work, + so, this extension should be enabled for mailimport script to work. + +j) By submitting a patch to the subsystem maintainer, either via email + or via pull request, the patch author(s) are agreeing that the + submitted code will be added on Kernel, and that the submitted code + are being released as GPLv2. The author may grant additional licenses + to the submitted code (for example, using dual GPL/BSD) or GPLv2 or + later. If no specific clause are added, the added code will be + assumed as GPLv2 only. + +5. Knowing about newer patches committed at master hg repository + ============================================================ + +There's a patchbomb script at linuxtv.org that will send one copy of +each patch applied to -hg tree to: + +1) The subscribers of the linuxtv-commits mailing list, hosted on + linuxtv.org; + +2) The patch author (as stated on the From: field in the patch comments); + +3) The patch committer (the "user" at hg metadata); + +4) All people with Signed-off-by:, Acked-by:, or CC: metadata clause + in the patch's comment. + +If, for some reason, there's no "From:" metatag (or it is on the first +line, instead of the second one), sometimes the script may fail, maybe +filling patch authorship wrongly. So people should take care to properly +commit patches with "From:". + +6. Patch handling for kernel submission + ==================================== + +The subsystem maintainer, when preparing the kernel patches to be sent +to mainstream (or to -mm series), uses some scripts and a manual +procedure, based on a quilt-like procedure, where a patch series file is +generated, and patches can be handled one by one. This means that -git +patches can be properly fixed, when required, if not already sent to +mainstream, to fulfill the best practices and resolve conflicts with +other patches directly merged in mainstream. + +There's a delay between updating a patch at master and sending it to +mainstream. During this period, it is possible to review a patch. The +common situations are: + +1) If a patch at master tree receives an Acked-by:, this can be added at +-git tree; + +2) If somebody fully nacks a patch applied at -hg, A reverse patch +can be applied at -hg, and the original patch can be removed -git; + +3) If somebody partially nacks a patch or sends a reviewing patch, +the -git patch may be a result of the merger of the two patches. + +By merging both patches at -git will allow avoiding storing unnecessary +patch history details at -git and at Mainstream. + +Those changes will require some manual sync between -git and -hg, it is +better to avoid those circumstances. + +During the procedure of generating kernel patches, the maintainer uses +to do a diff between the kernel tree and v4l-dvb mercurial tree +(without any backport code there). If there are discrepancies, a +backport patch from mainstream to v4l-dvb is generally applied by the +maintainer. + +7. Patch submission from the community + =================================== + +Patch submission is open to all the Free Software community. The general +procedure to have a patch accepted in the v4l/dvb subsystem and in the +kernel is the following: + +a. Post your patches to the corresponding mailing list for review and + test by other people. + + For analog or core changes, the V4L mailing list is + video4linux-list on redhat.com + + For DVB changes, the mailing list is + linux-dvb on linuxtv.org + + PS.: Sending emails to DVB Mailing List requires subscription via + http://linuxtv.org/lists.php + + V4L mailing list doesn't require subscription, although + subscription is recommended. + +b. Use [PATCH] and a brief description in the email's subject. + This will help the LinuxTV team to better handle it. + +c. Please include a brief description in the headers of your + patch, like described above. Something like: + + This is just a sample commit comment, just for reference purposes. + This does nothing. + + Signed-off-by nowhere <nowere@noplace.org> + +d. Every patch shall have a Developers Certificate of Origin and should + be submitted by one of its authors. All the patch authors should sign + it. + +e. People will eventually comment about the patch. In this case, + please fix problems and repeat until everyone is happy ;) + +f. If the patch is fixing an existing maintained driver, the + low-level driver maintainer will apply to his tree, and at some later + time, ask the subsystem maintainer to pull it. + +g. If it is a newer driver (not yet in one of the development trees), + please copy the subsystem maintainer. + +8. Identifying regressions with Mercurial + ====================================== + + The better way for you to identify regressions with Mercurial is to + use hg bisect. This is an extension provided with the current + mercurial versions. For it to work, you need to have the proper setup + at an hgrc file. To test if bisect is working, you can do: + hg bisect help + + If Mercurial answers with + hg: unknown command 'bisect' + + You will need to add the following lines to your ~/.hgrc file: + [extensions] + hgext.hbisect=/usr/lib/python2.5/site-packages/hgext/hbisect.py + + (assuming that hbisect.py is installed under python2.5 default dir) + + The first step is to initialize bisect for a newer regression testing + session. This is done with: + hg bisect init + + If the bisect were previously initialized, you should, instead do: + hg bisect reset + + Supposing that the latest kernel version have some regression, you + should do something like: + hg update -C + + (This will clean any changes you had on your tree, and will update to + the latest patch) + + Then, you will mark the latest version as "bad": + hg bisect bad + + The next step is to find one version where the your board is properly + working. Supposing that review "4000" is ok, you would do: + hg update 4000 + + Test if the review is really ok. If so, you should mark it as good: + hg bisect good + + If everything is ok, it should print something like: + + Testing changeset 4481:a53c7904e47d (944 changesets remaining, ~9 tests) + 405 files updated, 0 files merged, 8 files removed, 0 files unresolved + + The above line shows that Mercurial selected another revision for you + to test. Redo your tests. If this version is ok, you would do: + + hg bisect good + + otherwise, if the version is broken, you should do: + + hg bisect bad -5. Fix problems and repeat until everyone is happy ;) + This should be repeated until you have an answer like: -6. Maintainers will periodically submit changes to mainstream. + The first bad revision is: + changeset: 4593:26d1ce012c5e + user: Someone <Someone@somewhere> + date: Thu Feb 31 17:52:53 2006 -0300 + summary: This is the broken patch that we should find -Mauro -Mauro Carvalho Chehab <mchehab .at. linuxtv .dot. org> + If, in the middle of the process, you need to know on what revision + you are, you can do something like: + hg log -r `hg id|cut -d' ' -f 1` |