Development: How to submit patches: Difference between revisions

From LinuxTVWiki
Jump to navigation Jump to search
m (umm. spell much? not me!)
(47 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This article provides an overview for submitting patches against the [[What is V4L or DVB?|V4L-DVB source code]] (for either new or existing kernel driver modules and/or documentation), and as well as for the [[LinuxTV dvb-apps|dvb-apps]] source. For general references in regards as to how to develop support for a particular device or in writing a new device driver, see [[Development: How to add support for a device|here]].
=== Patch Preparation ===


== Patch Preparation ==
Patches should be created against the V4L-DVB mercurial tree; see [[How to build from Mercurial]].
For V4L-DVB driver modules and/or documentation, patches should be created against the [http://git.linuxtv.org/media_tree.git master linux-media git tree]; for instructions on obtaining and building these sources, see the "[[How to Obtain, Build and Install V4L-DVB Device Drivers]]" article. Similarly, for submissions related to the dvb-apps, one should patch against the [http://linuxtv.org/hg/dvb-apps dvb-apps ''mercurial'' tree].


For references on how to develop a driver, take a look at [http://jungla.dit.upm.es/%7Ejmseyas/linux/kernel/hackers-docs.html Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel].


The patch should contain an unified diff between the latest code at the tree and the code you modified. The best way to do it is by running the command ''git diff'' or ''hg diff''. Before submitting your patch, please run ''make checkpatch''. This will tell the build system to run a script that checks for coding style violations.
Post your patches to the [mailto:majordomo@vger.kernel.org?body=subscribe%20linux-media linux-media] Mailing List for review and testing.

Post your patches to the [mailto:majordomo@vger.kernel.org?body=subscribe%20linux-media Linux-Media Mailing List] for review and testing. [http://vger.kernel.org/vger-lists.html#linux-media Subscription to the mailing list] is recommended, though it is not required.


Follow the guidelines in [[Development: Submitting Patches|Submitting Patches]] (cf. [http://linux.yyz.us/patch-format.html jgarzik's version]), including:
Follow the guidelines in [[Development: Submitting Patches|Submitting Patches]] (cf. [http://linux.yyz.us/patch-format.html jgarzik's version]), including:
:* Verify best-practice [[Development: Coding Style|kernel coding style]]
:* Verify best-practice [[Development: Coding Style|kernel coding style]]
:* Use [PATCH] in the subject line to get attention ... '''Note''': the patchwork tool (discussed below) actually does NOT rely upon this label for detection of patches; rather, patchwork utilizes logic algorithms to detect for the presence of a patch within an email message. That being the case, the "[PATCH]" flag serves only to alert your human counterparts/peers on the mailing list of your submission
:* Use [PATCH] in the subject line to get attention
:* Explain what the patch does and what hardware it applies to
:* Explain what the patch does and to what hardware it applies. Note: All comments you add on your patch will be part of the commit message (except for the meta-tags)
:* Document your work where appropriate, in the form of patches to the Documentation/video4linux or Documentation/dvb files (which ever is appropriate)
:* Document your work where appropriate (i.e. in the form of patches to the Documentation/video4linux or Documentation/dvb files)
:* Add a '''Signed-off-by: Your name <name@yoursite.com>''' as a [[Development: Submitting Patches#Developer.27s_Certificate_of_Origin_1.1|Developer's Certificate of Origin 1.1 ]]
:* Add a '''Signed-off-by: Your name <name@yoursite.com>''' as a [[Development: Submitting Patches#Developer.27s_Certificate_of_Origin_1.1|Developer's Certificate of Origin 1.1 ]]
:* Send the patch inline, not as an attachment (unless otherwise asked to do so) ... patches presented in the form of inline text in the body of an email are easier to deal with from the perspective of a peer review process (for more information, see the <code>/usr/src/linux/Documentation/email-clients.txt</code> file; a current copy of which can also be found online [http://lxr.linux.no/linux+v2.6.28.5/Documentation/email-clients.txt here]).
:* Fix any problems and repeat until everyone is happy ;)
:* '''Note''': various web mail interfaces seem to be problematic for patch submission, in that:
:* Send the patch inline, not as an attachment
:** they may break the patch (e.g. line wrapping it) or
:** in the case where you have sent the patch as an attachment, the emailer may use the wrong mime encoding type ... (web mailers often wrongly use "application/octet-stream" for diffs, whereas the proper type is "text/x-patch" ... Note: the patchwork tool (discussed below) is robust in that it supports both mime types "text/x-patch" and "text/plain", but if the emailer has sent it with a different type, the attachment will be disregarded/discarded.

Hint: There is also a [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]


== Example of a good patch submission email ==

The following example (based on a real patch submission) shows, in practice, how
a good patch should look like:

From: Patch Developer
Date: Thu, 27 Sep 2012 05:32:52 -0300
Subject: [PATCH] davinci: vpif: capture/display: fix race condition
channel_first_int[][] variable is used as a flag for the ISR,
This flag was being set after enabling the interrupts, There
where situations when the isr occurred even before the flag was set
due to which it was causing the application hang.
This patch sets channel_first_int[][] flag just before enabling the
interrupt.
Reported-by: Some User
Signed-off-by: Patch Developer
Reviewed-by: Patch Reviewer

---
v2: Coding Style fixed, as per-review.
drivers/media/platform/davinci/vpif_capture.c | 1 +
1 file changed, 1 insertion(+)

diff --git a/drivers/media/platform/davinci/vpif_capture.c b/drivers/media/platform/davinci/vpif_capture.c
index 13aa46d..0bafeca 100644
--- a/drivers/media/platform/davinci/vpif_capture.c
+++ b/drivers/media/platform/davinci/vpif_capture.c
@@ -339,6 +339,7 @@ static int vpif_start_streaming(struct vb2_queue *vq, unsigned int count)
* Set interrupt for both the fields in VPIF Register enable channel in
* VPIF register
*/
+ channel_first_int[VPIF_VIDEO_INDEX][ch->channel_id] = 1;
if ((VPIF_CHANNEL0_VIDEO == ch->channel_id)) {
channel0_intr_assert();
channel0_intr_enable(1);

*The fist part contains the email header and the first part of the email body, with the patch description, followed by Signed-off/Reviewed-by/Acked-By tags.

Note: For patches submitted by one person, but authored by another one, the '''first line''' of the email body should contain a ''From:'' tag with the name and email of the original author. For example, if the above e-mail was sent by ''Patch Reviewer'', it would contain, instead:

From: Patch Reviewer
Date: Thu, 27 Sep 2012 05:32:52 -0300
Subject: [PATCH] davinci: vpif: capture/display: fix race condition
From: Patch Developer
channel_first_int[][] variable is used as a flag for the ISR,
This flag was being set after enabling the interrupts, There
where situations when the isr occurred even before the flag was set
due to which it was causing the application hang.
This patch sets channel_first_int[][] flag just before enabling the
interrupt.
Reported-by: Some User
Signed-off-by: Patch Developer
Signed-off-by: Patch Reviewer

*The second part is optional, separated by "---", contains the patch diffstat. It can also contain any notice for the patch reviewers to read. The second part won't be merged at the patch commit.

*The third part is the diff, using unified diff, -p1 format. It is typically generated by a "git diff" command.

Note: on the above, ''Some User'', ''Patch Developer'' and ''Patch Reviewer'' should be the full email of real persons, in the form: ''some name <some email>''.

== Firmware submission ==

Some devices may require [[Firmware|firmware(s)]] in order for the device drivers to work properly. In such cases, if the firmware is not already available, some sort of procedure is needed so that end users may make use of the driver.

In the spirit of Open Source Software (OSS) development and distribution, it is most preferable if the firmware can be provided by submitting it as open source code, licenced under the GPL. Making the firmware open source facilitates tremendous advantages when it comes to debugging problems (i.e. the concept of many eyes to spot the trouble spots). Unfortunately, very few firmwares are submitted with sources, and, to be sure, this is certainly not a mandatory requirement. Indeed, as it currently stands, most firmware are instead provided in a binary format. However, there is an associated problem with distributing firmware as a closed source "binary blob" -- namely, for it to be made available within Linux distributions, it is required that each firmware should be provided with the distribution and redistribution rights, given specifically by the device or chipset manufacturer.

Therefore, if you are a device vendor or original chipset manufacturer and wish to submit the requisite firmware for inclusion within Linux distributions, in order to do so, please email the [mailto://linux-media@vger.kernel.org Linux Media Mailing List (LMML)], and/or to [mailto:mchehab@infradead.org Mauro (the V4L/DVB Maintainer)], sending copies of the firmware files and the appropriate license terms.

If the licensing terms are deemed acceptable for legally permitting wide redistribution of the firmware software, then the firmware files will be added at the [http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-firmware.git V4L/DVB Linux-firmware git tree] and submitted to the upstream Linux-firmware tree.

Note that there is no unique model for firmware licensing, but there are some examples provided within the [http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-firmware.git;a=blob_plain;f=WHENCE;hb=HEAD WHENCE] file and within the several LICENCE files avaiable at the tree. The most common models for non GPL'd firmwares are:
:* [[firmware model1]]
:* [[firmware model2]]
There are also some existing examples of firmwares released as Open Source Software:
:* [[GPL model]]
:* [[Cinergy T2 license]]

== After you've Submitted: What happens Next? ==
In conjunction with the move to the new Linux-media mailing list, V4L-DVB is now using the [http://patchwork.linuxtv.org/project/linux-media/list/ Patchwork tool] for aggregating patches sent into the list (you can read more about it [http://www.linuxtv.org/news.php?entry=2009-01-06.mchehab here] and [http://www.linuxtv.org/news.php?entry=2011-09-18.mchehab here]). In the past, it was, unfortunately, not uncommon for patches to be overlooked and become lost on the V4L-DVB mailing lists; thus making the adoption of the patchwork tool a very welcome addition. So, provided you have correctly submitted your patch (as discussed above), the steps towards having your code adopted will have automatically been put into motion. You can, of course, check to see the status of your submission from the [http://patchwork.kernel.org/project/linux-media/list/ Patchwork webpage]. If patchwork has not picked up your patch (after a reasonable period of time has elapsed), it is quite probable that your submission was incorrect for some reason; please review the information contained in the above section and try again.


<div style="border: solid 1px; border-color: blue; margin: 1em; padding: 0.5em; background-color: Lavender;">"The most difficult problem isn't fixing bugs, but fixing bugs without breaking other configurations. There are many: different cards, different TV norms, whereas most of the developers can test only one TV norm." - Gerd Knorr</div>
Hint: [[Development: Linux Kernel patch submittal checklist|There's a checklist for patch submission ]]


After being picked up by patchwork, the first thing you should expect next is that a [[Development: Code Review|code review]] will be performed, and often this is by various parties. This may lead to a series of requests for you to fix any observed problems and require you to then resubmit your work, by repeating the same steps outlined above, until everyone is happy with the submission. In other words: wash, rinse, repeat ;)
Subscription to the [http://vger.kernel.org/vger-lists.html#linux-media linux-media mailing list] is recommended but not required.


The patch will be applied to the main mercurial tree. Once tested and integrated, patches are merged into a git tree by the V4L-DVB maintainer and periodically pulled by Linus.
Then, when your patch is accepted, it will initially be applied to the main linux-media git tree. Once tested and integrated, such patches are later merged into a git tree by the V4L-DVB maintainer and, upon request, periodically pulled by Linus into one of his own git trees in an intermediate step towards final inclusion into the Linux kernel.


[[Category:Development]]
[[Category:Development]]

Revision as of 08:59, 27 September 2012

This article provides an overview for submitting patches against the V4L-DVB source code (for either new or existing kernel driver modules and/or documentation), and as well as for the dvb-apps source. For general references in regards as to how to develop support for a particular device or in writing a new device driver, see here.

Patch Preparation

For V4L-DVB driver modules and/or documentation, patches should be created against the master linux-media git tree; for instructions on obtaining and building these sources, see the "How to Obtain, Build and Install V4L-DVB Device Drivers" article. Similarly, for submissions related to the dvb-apps, one should patch against the dvb-apps mercurial tree.


The patch should contain an unified diff between the latest code at the tree and the code you modified. The best way to do it is by running the command git diff or hg diff. Before submitting your patch, please run make checkpatch. This will tell the build system to run a script that checks for coding style violations.

Post your patches to the Linux-Media Mailing List for review and testing. Subscription to the mailing list is recommended, though it is not required.

Follow the guidelines in Submitting Patches (cf. jgarzik's version), including:

  • Verify best-practice kernel coding style
  • Use [PATCH] in the subject line to get attention ... Note: the patchwork tool (discussed below) actually does NOT rely upon this label for detection of patches; rather, patchwork utilizes logic algorithms to detect for the presence of a patch within an email message. That being the case, the "[PATCH]" flag serves only to alert your human counterparts/peers on the mailing list of your submission
  • Explain what the patch does and to what hardware it applies. Note: All comments you add on your patch will be part of the commit message (except for the meta-tags)
  • Document your work where appropriate (i.e. in the form of patches to the Documentation/video4linux or Documentation/dvb files)
  • Add a Signed-off-by: Your name <name@yoursite.com> as a Developer's Certificate of Origin 1.1
  • Send the patch inline, not as an attachment (unless otherwise asked to do so) ... patches presented in the form of inline text in the body of an email are easier to deal with from the perspective of a peer review process (for more information, see the /usr/src/linux/Documentation/email-clients.txt file; a current copy of which can also be found online here).
  • Note: various web mail interfaces seem to be problematic for patch submission, in that:
    • they may break the patch (e.g. line wrapping it) or
    • in the case where you have sent the patch as an attachment, the emailer may use the wrong mime encoding type ... (web mailers often wrongly use "application/octet-stream" for diffs, whereas the proper type is "text/x-patch" ... Note: the patchwork tool (discussed below) is robust in that it supports both mime types "text/x-patch" and "text/plain", but if the emailer has sent it with a different type, the attachment will be disregarded/discarded.

Hint: There is also a checklist for patch submission


Example of a good patch submission email

The following example (based on a real patch submission) shows, in practice, how a good patch should look like:

 From: Patch Developer
 Date: Thu, 27 Sep 2012 05:32:52 -0300
 Subject: [PATCH] davinci: vpif: capture/display: fix race condition
 
 channel_first_int[][] variable is used as a flag for the ISR,
 This flag was being set after enabling the interrupts, There
 where situations when the isr occurred even before the flag was set
 due to which it was causing the application hang.
 This patch sets  channel_first_int[][] flag just before enabling the
 interrupt.
 
 Reported-by: Some User
 Signed-off-by: Patch Developer
 Reviewed-by: Patch Reviewer
 ---
 
  v2: Coding Style fixed, as per-review.
 
  drivers/media/platform/davinci/vpif_capture.c |    1 +
  1 file changed, 1 insertion(+)
 diff --git a/drivers/media/platform/davinci/vpif_capture.c b/drivers/media/platform/davinci/vpif_capture.c
 index 13aa46d..0bafeca 100644
 --- a/drivers/media/platform/davinci/vpif_capture.c
 +++ b/drivers/media/platform/davinci/vpif_capture.c
 @@ -339,6 +339,7 @@ static int vpif_start_streaming(struct vb2_queue *vq, unsigned int count)
  	 * Set interrupt for both the fields in VPIF Register enable channel in
  	 * VPIF register
  	 */
 +	channel_first_int[VPIF_VIDEO_INDEX][ch->channel_id] = 1;
  	if ((VPIF_CHANNEL0_VIDEO == ch->channel_id)) {
  		channel0_intr_assert();
  		channel0_intr_enable(1);
  • The fist part contains the email header and the first part of the email body, with the patch description, followed by Signed-off/Reviewed-by/Acked-By tags.

Note: For patches submitted by one person, but authored by another one, the first line of the email body should contain a From: tag with the name and email of the original author. For example, if the above e-mail was sent by Patch Reviewer, it would contain, instead:

 From: Patch Reviewer
 Date: Thu, 27 Sep 2012 05:32:52 -0300
 Subject: [PATCH] davinci: vpif: capture/display: fix race condition
   
 From: Patch Developer
 
 channel_first_int[][] variable is used as a flag for the ISR,
 This flag was being set after enabling the interrupts, There
 where situations when the isr occurred even before the flag was set
 due to which it was causing the application hang.
 This patch sets  channel_first_int[][] flag just before enabling the
 interrupt.
 
 Reported-by: Some User
 Signed-off-by: Patch Developer
 Signed-off-by: Patch Reviewer
  • The second part is optional, separated by "---", contains the patch diffstat. It can also contain any notice for the patch reviewers to read. The second part won't be merged at the patch commit.
  • The third part is the diff, using unified diff, -p1 format. It is typically generated by a "git diff" command.

Note: on the above, Some User, Patch Developer and Patch Reviewer should be the full email of real persons, in the form: some name <some email>.

Firmware submission

Some devices may require firmware(s) in order for the device drivers to work properly. In such cases, if the firmware is not already available, some sort of procedure is needed so that end users may make use of the driver.

In the spirit of Open Source Software (OSS) development and distribution, it is most preferable if the firmware can be provided by submitting it as open source code, licenced under the GPL. Making the firmware open source facilitates tremendous advantages when it comes to debugging problems (i.e. the concept of many eyes to spot the trouble spots). Unfortunately, very few firmwares are submitted with sources, and, to be sure, this is certainly not a mandatory requirement. Indeed, as it currently stands, most firmware are instead provided in a binary format. However, there is an associated problem with distributing firmware as a closed source "binary blob" -- namely, for it to be made available within Linux distributions, it is required that each firmware should be provided with the distribution and redistribution rights, given specifically by the device or chipset manufacturer.

Therefore, if you are a device vendor or original chipset manufacturer and wish to submit the requisite firmware for inclusion within Linux distributions, in order to do so, please email the Linux Media Mailing List (LMML), and/or to Mauro (the V4L/DVB Maintainer), sending copies of the firmware files and the appropriate license terms.

If the licensing terms are deemed acceptable for legally permitting wide redistribution of the firmware software, then the firmware files will be added at the V4L/DVB Linux-firmware git tree and submitted to the upstream Linux-firmware tree.

Note that there is no unique model for firmware licensing, but there are some examples provided within the WHENCE file and within the several LICENCE files avaiable at the tree. The most common models for non GPL'd firmwares are:

There are also some existing examples of firmwares released as Open Source Software:

After you've Submitted: What happens Next?

In conjunction with the move to the new Linux-media mailing list, V4L-DVB is now using the Patchwork tool for aggregating patches sent into the list (you can read more about it here and here). In the past, it was, unfortunately, not uncommon for patches to be overlooked and become lost on the V4L-DVB mailing lists; thus making the adoption of the patchwork tool a very welcome addition. So, provided you have correctly submitted your patch (as discussed above), the steps towards having your code adopted will have automatically been put into motion. You can, of course, check to see the status of your submission from the Patchwork webpage. If patchwork has not picked up your patch (after a reasonable period of time has elapsed), it is quite probable that your submission was incorrect for some reason; please review the information contained in the above section and try again.

"The most difficult problem isn't fixing bugs, but fixing bugs without breaking other configurations. There are many: different cards, different TV norms, whereas most of the developers can test only one TV norm." - Gerd Knorr

After being picked up by patchwork, the first thing you should expect next is that a code review will be performed, and often this is by various parties. This may lead to a series of requests for you to fix any observed problems and require you to then resubmit your work, by repeating the same steps outlined above, until everyone is happy with the submission. In other words: wash, rinse, repeat ;)

Then, when your patch is accepted, it will initially be applied to the main linux-media git tree. Once tested and integrated, such patches are later merged into a git tree by the V4L-DVB maintainer and, upon request, periodically pulled by Linus into one of his own git trees in an intermediate step towards final inclusion into the Linux kernel.