LinuxTVWiki - User contributions [en]

Development: How to submit patches

2012-09-27T08:59:32Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:56:33Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:55:09Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[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 is 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:54:16Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission email ==

The following example (part of 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 is 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:53:18Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission email ==

The following example (part of 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
Signed-off-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 is 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:52:16Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission email ==

The following example (part of 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
Signed-off-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 is 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:51:25Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission email ==

The following example (part of 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
Signed-off-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 is 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:46:08Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission email ==

The following example (part of 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
Signed-off-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 is 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.

== 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:35:55Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission email ==

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

From: Patch Developer <patch@developer.com>
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 <some@user.com>
Signed-off-by: Patch Developer <patch@developer.com>
Signed-off-by: Patch Reviewer <patch@reviewer.com>

---

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 is sent by Patch Reviewer, it would contain, instead:

From: Patch Reviewer <patch@reviewer.com>
Date: Thu, 27 Sep 2012 05:32:52 -0300
Subject: [PATCH] davinci: vpif: capture/display: fix race condition

From: Patch Developer <patch@developer.com>

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 <some@user.com>
Signed-off-by: Patch Developer <patch@developer.com>
Signed-off-by: Patch Reviewer <patch@reviewer.com>

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.

== 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:26:31Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission email ==

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

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: David Oleszkiewicz <doleszki@adsyscontrols.com>
Signed-off-by: Lad, Prabhakar <prabhakar.lad@ti.com>
Signed-off-by: Manjunath Hadli <manjunath.hadli@ti.com>

---

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 subject, and the patch description, followed by Signed-off/Reviewed-by/Acked-By tags. 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 (like ''From: someone <at@some.addr>'').

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.

== 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:25:42Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission email ==

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

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: David Oleszkiewicz <doleszki@adsyscontrols.com>
Signed-off-by: Lad, Prabhakar <prabhakar.lad@ti.com>
Signed-off-by: Manjunath Hadli <manjunath.hadli@ti.com>

---

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 subject, and the patch description, followed by Signed-off/Reviewed-by/Acked-By tags. 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 (like "From: someone <at@some.addr>").

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.

== 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:22:26Z

Mauro Carvalho Chehab: /* Example of a good patch submission email */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission email ==

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

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: David Oleszkiewicz <doleszki@adsyscontrols.com>
Signed-off-by: Lad, Prabhakar <prabhakar.lad@ti.com>
Signed-off-by: Manjunath Hadli <manjunath.hadli@ti.com>

---

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 subject, and the patch description, followed by Signed-off/Reviewed-by/Acked-By tags.

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.

== 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:16:41Z

Mauro Carvalho Chehab: /* Example of a good patch submission */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission email ==
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: David Oleszkiewicz <doleszki@adsyscontrols.com>
Signed-off-by: Lad, Prabhakar <prabhakar.lad@ti.com>
Signed-off-by: Manjunath Hadli <manjunath.hadli@ti.com>

---

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);

== 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:13:12Z

Mauro Carvalho Chehab: /* Example of a good patch submission */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission ==
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: David Oleszkiewicz <doleszki@adsyscontrols.com>
Signed-off-by: Lad, Prabhakar <prabhakar.lad@ti.com>
Signed-off-by: Manjunath Hadli <manjunath.hadli@ti.com>

== 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>

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 ;)

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]]

Development: How to submit patches

2012-09-27T08:12:48Z

Mauro Carvalho Chehab: /* Patch Preparation */

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 ==
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].

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. [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:
:* 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
:* 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 [[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]).
:* '''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 [[Development: Linux Kernel patch submittal checklist|checklist for patch submission]]

== Example of a good patch submission ==
Subject: [PATCH] [media] 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: David Oleszkiewicz <doleszki@adsyscontrols.com>
Signed-off-by: Lad, Prabhakar <prabhakar.lad@ti.com>
Signed-off-by: Manjunath Hadli <manjunath.hadli@ti.com>

== 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>

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 ;)

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]]

How to Obtain, Build and Install V4L-DVB Device Drivers

2012-04-11T19:34:05Z

Mauro Carvalho Chehab: /* Retrieving and Building/Compiling the Latest V4L-DVB Source Code */

The LinuxTV project hosts the latest set of Linux kernel driver modules for [[What is V4L or DVB?|V4L-DVB devices]]. This page contains information to help an "end user" install these device drivers in a GNU/Linux system.

{{Note|This article assumes that:
* your device is actually supported by the drivers -- Just because your board happens to have a chip on it that corresponds to some existing driver does NOT mean your product is supported. The driver has to be aware that it's related to some hardware (typically through the [[Supported_Hardware#Determining_the_Device's_Identity|subsystem ID from the USB ID or PCI ID]]). If the driver doesn't recognize/bind to your particular hardware, then the module will probably load but then proceed to not do anything. In other words, support for your device would have to be added to the driver.
* you have already physically installed the hardware device into, or connected it to, your system. (Refer to the manufacturer's instructions for such details)}}.

== Software Requirements ==
===Kernel Support===
The LinuxTV V4L-DVB drivers will work only in conjunction with relatively modern 2.6 kernels; specifically,

{{Note|CityK here: I have no clue as to where the current backwards compatibility status stands. Suffice to say, more modern kernels (which I'd define as ~2.6.32 and newer) are much more likely to work with the new media_build snapshots of the git tree. When the situation is more clear, please update this section accordingly.}}

===Additional Software Requrirements===
In order to be able to build the V4L-DVB kernel driver modules, you will need:
* kernel-source or kernel-headers
* (OpenSuSE and fedora only) kernel-devel
* (Debian) libdigest-sha1-perl
* make
* gcc
* git
* patch
* patchutils
* libproc-processtable-perl ("perl-Proc-ProcessTable")
If these packages are not currently installed on your system, you should do so now.

==Retrieving and Building/Compiling the Latest V4L-DVB Source Code==
There are a couple of different methods by which you can obtain and build the latest source code. Regardless of which route you take, all are performed from the command line within a console. The "basic" method is likely appropriate for most end users, though, in some cases, some users will have to use the slightly more "manually intensive" approach. This second approach is effectively, for all intents and purposes, really just the same as the "basic" method, but performing the steps in a piecemeal fashion affords you the opportunity to tailor the source code or the "make"/build process as might be required in your particular situation. Again, before proceeding with either approach, make sure you have installed all the prerequisite software listed above.

{{Note|If you are using Ubuntu, you were previously very likely to run into a fatal compilation error within the v4l-dvb build process when it reaches the firedtv module. The reason for this is because Ubuntu had a bug in their packaging of the kernel headers. <b>This seems to be fixed</b> on a fully updated systtem (5 July 2011) This was a long standing issue, and one of the most frequently reported on the mailing list. <br>
If you still have the problem, you should be able to correct this compilation problem by following the more manual procedure listed below. In particular, before proceeding to build the modules, you will have to edit the file ''v4l/.config'' and change the line for the firedtv driver from <nowiki>"firedtv=m" to "firedtv=n"</nowiki>.}}

{{Note|If you are having build failures like "implicit declaration of function 'mfd_get_data'" try editing v4l/Makefile.media, and just comment out anything related to CONFIG_*_TIMBERALE. [[http://sourceforge.net/mailarchive/message.php?msg_id=27353778 Source]] }}

{| class="wikitable"
|+'''Retreiving the Source Code & Building/Compiling the Modules'''
|-
! "Basic" Approach !! Developer's Approach !! More "Manually Intensive" Approach

|-
| valign=top |
git clone git://linuxtv.org/media_build.git
cd media_build
./build

These commands will download the newest tarball of the source code from linuxtv.org, apply the backport patches to it and then build/compile the source via the included script build.sh.

NB: to add a patch copy the .patch file to the backports directory, and add the patch file as a line to the {kernel-version}_series file in the packports dir.
| valign=top |
~ $ git clone git://linuxtv.org/media_build.git
~ $ cd media_build
~/media_build $./build --main-git
{{Note|'''The build script will clone the entire media-tree.git, with will take some time'''}}

In order to modify a driver foo.c:

~/media_build $ cd media
~/media $ gedit drivers/media/video/foo.c
~/media $ make -C ../v4l
~/media $ make -C ../ install
~/media $ make -C .. rmmod
~/media $ modprobe foo

(some procedure to test the "foo" driver)

To generate a patch, use:

~/media $ git commit -as

Then submit the patch upstream. If your sendmail is properly configured, you can easily send the patch upstream with:

~/media $ git send-email HEAD^1

or, to send a patch series:

~/media $ git send-email ''initial_branch''

Where ''initial_branch'' is the name of a branch of a changeset number for the last patch before your changes.

|
git clone git://linuxtv.org/media_build.git
cd media_build/linux
make tar DIR=<some dir with media -git tree>
make untar
cd ..

If you need to make any sort of change or modification to the source code, now is the time.

<div style="border: solid 1px; border-color: blue; margin: 1em; padding: 1em; background-color: Lavender;">
'''Optional Pre-Compilation Steps'''<br>
These optional command steps are applicable only in certain situations approaching a new build of the driver set, or for experienced users wishing to streamline the build process to consist of only those components they want to install.
* <code>make rminstall</code> ... you would use this to remove the currently installed driver set (located within the relevant ''/lib/modules/["kernel version"]/kernel/drivers/media'' directory to which they were installed)
* <code>make distclean</code> ... cleans up the build configuration environment ... noteworthy is that it will set things up such that a following "make" build process will be against "''/usr/src/[uname -r]''” kernel source
* <code>make menuconfig</code> ... this will open up the ncurses based menu that allows you to select only those components you wish to build and install

The building system offers some other make targets that may be useful for advanced users or developers. For listing the supported targets, please use <code>make help</code>.</div>

Next, build/compile the modules from the source code with the command:
make
{{Note|For multi-core processor systems, the ''make'' command has available options that can be beneficial in terms of the reducing the amount of time required for the process' completion. Specifically, you can run "''make -jN''" (where "''N''" <nowiki>=</nowiki> 1 + the number of cores your cpu has ... i.e. if you have a dual core cpu use: ''make -j3'' )}}

|}
===Information Regarding the Build Process===
Generally, this step will tend to take a while to complete; being dependent upon both the number of modules being built and your system's processing power.

You can monitor the build progress via the console output. You will notice that a ''/v4l'' directory will have been created and within which the completed *.ko module files are written. Some drivers included within the snapshot may have their own requirements in regards to the kernel that you must be running in order for the module to be built; such cases can be found listed at the beginning of the build process' console output.

The entire build process should complete without error. If any errors are encountered, the compilation will be halted and, at this point, you should not attempt to proceed any further (unless you really, really enjoy experiencing the outcome of a preordained failure). Errors that prevent building a particular V4L-DVB snapshot do indeed surface from time to time, but these are usually corrected quickly upon notification from an end user submitted [[Bug Report|bug report]], or upon detection from the daily automated build tests (see note below). If you have run into a build error via the "basic" approach outlined above, you may wish to see if you can remedy the error and attempt a module build via the more "manually intensive" approach also outlined above.

{{Note|'''The Daily Automated Build Tests'''<br>
Hans Verkuil has set up an automated daily build of the V4L-DVB source code upon all supported kernels, as well as testing that very same upon several CPU architectures. A brief synopsis of the results from those tests is published each day on the Linux-Media Mailing List (LMML) under a message subject heading prefix of "''[cron job] v4l-dvb daily build ...''". A link to more detailed results of these tests is also provided within that message or can be found directly from [http://www.xs4all.nl/~hverkuil/logs/ here].}}

If you do run into any problems during the build step, you should:
* first, see whether the issue is already known or not -- consult the results of the daily automated build tests (see note above)
* if it appears that this is a new issue, please [[Bug Report|inform the developers of the bug via the LMML]] (preferred) or thorough one of the irc.freenode.net irc channels (#v4l or #linuxtv or #dvb).
* you may also wish to consult any errata that might be found on this article's talk page

In general, if the source builds correctly, it is likely that the drivers will work, though this is not a guarantee.

== Installing the Compiled Driver Modules ==
The next step is to install the kernel driver modules by executing:
sudo make install
The command above will prompt you for your root password, and will then copy the *.ko module files you built in the above step into the ''/lib/modules/[kernel version]/kernel/drivers/media'' directories.

{{Note|If your distribution doesn't support the sudo command (i.e the command line returns ''"bash: sudo: command not found"''), use the "su" command instead. "su" will prompt you for the root password, and after which entering, you can then proceed with the command. Ex.:
su
make install
}}
<br>
{{Note|In the case where you have more then one kernel installed but have used the pre-compilation option of "make distclean", the new modules will be installed only into the ''/lib/modules/[uname -r]/kernel/drivers/media'' directory}} <br>

== First Use: Out with the Old, In with the New==
{|
| valign=top |
Before trying to use the device with your newly installed driver set, you should remove from system memory any older versions of related modules that may have been loaded by the running kernel; otherwise, you will likely run into various fatal mismatch errors -- typified by an "unknown symbol" or "unknown parameter" -- as a result of your system trying to work from a mixture of old and new modules.

To achieve a [[Wikipedia:Tabula rasa |clean slate]] state, you could either: <br>

'''1. Reboot:''' Perhaps the most straightforward thing to do at this point, particularly for Linux newbies, is to just restart your system; the reboot will, obviously, clear out the old modules loaded into memory and, as an added bonus, create a fresh running environment under which the new modules should have been automagically loaded into system memory.

Or, on the other hand,

'''2. Take care of business yourself:''' More experienced users might prefer to use more eloquent approaches. For example, using
sudo make unload
will essentially (and similar as to manually using "rmmod" commands) remove all older modules for the device that might be currently loaded in memory by the running kernel. After which, one can then load, from the newly installed device driver set, the appropriate modules for the device using relevant
modprobe ''driver_name''
commands.

| valign=top halign=right width=30% |
<div style="border: solid 1px; border-color: blue; margin: 1em; padding: 1em; background-color: Lavender;">
'''For Advanced Users'''<br>
The following information is likely useful only for developers. After building the modules as per usual ("make"), and without needing to install them, you can:
* remove all older modules from memory at once using "make unload" and
* then insert all the newly built modules into memory for the running kernel with "make load"
Alternatively, to perform the previous two commands ("make unload" and "make load") in a single step, you can use "make reload"

Note, however, that it is highly recommended that you avoid using either the make load or make reload options, as they will end up inserting <u>all</u> V4L-DVB device drivers into memory, and that may introduce instability, or complicate testing.
</div>
|}
Regardless of which approach you take to remove the old modules and to insert the new ones, the end result should be the same. In addition, upon future starts of your system, your device should "automagically" be detected and will have the appropriate driver modules loaded into memory.

===If the Modules load correctly:===
Provided that the modules were loaded correctly into system memory:

'''1. They should be listed in ''/proc/modules''''': you can use either <code>cat /proc/modules</code> or, even better, <code>lsmod</code> to see this content.

Which modules should you be looking for? Well, the answer to that question depends entirely upon the chipsets used by your device -- see the relevant wiki article for your device for a listing of such components and required drivers (or search the web if such information does not exist. '''Note''': Please add any information missing from the wiki!)

'''2. They should provide some indication within your system log''': you can consult the output from the "<code>dmesg</code>" command or directly review your system log file (typically housed within the ''/var/log'' directory) for indication that they have been successfully loaded and that the device is now correctly configured for operation. Examples of successful module loads are provided by users under the "Sample kernel output" section in many device articles witin the wiki.

'''3. The device manager [[Wikipedia:udev|udev]] will "automagically" create appropriate [[Device nodes and character devices|device nodes]] on ''/dev''''': <br>
'''(a) For a DVB device''', you should now have a non-empty ''/dev/dvb'' directory. You can check on whether this is true for you with the following command:
: <code>ls -l /dev/dvb/</code>
(alternatively, you can browse your directory structure with the graphical file manager of your choice). If you have a single DVB device installed in your system, then the output of the above command should reveal that /dev/dvb/ is populated by adapter0. Digging further,
: <code>ls -l /dev/dvb/adapter0 </code>
reveals the [[Device_nodes_and_character_devices#DVB_character_devices|character devices]] associated with adapter0 for which the drivers have control. If you have more then one DVB device, you can see the same for all with
: <code>ls -l /dev/dvb/adapter* </code>

'''(b) For a V4L device''', you should now have a non-empty ''/dev/v4l'' directory. You can check on whether this is true for you with the following command:
: <code>ls -l /dev/v4l</code>
Digging further,
: <code>ls -l /dev/v4l/by-path </code>
reveals the symbolic links to the [[Device_nodes_and_character_devices#V4L_character_devices|character devices]] associated with your V4L adapter for which the drivers have control. The most typical of which is ''/dev/video0''. If you have more then one V4L device, you can see the same for all with
: <code>ls -l /dev/video* </code>

===If the Modules did not load correctly or the device is still not configured correctly for use:===
There could be several reasons why you may have encountered a module loading error or, absent such an error, why the device is still not configured correctly for use, even after having correctly followed the steps from the above procedure. If either of these cases applies, the very first thing you should do is [[Supported Hardware|check whether your device is actually supported]] by the driver (see the very first note at the top of this page). Next, provided your device is supposed to be supported, check within your system log/dmesg for any messages that may give indication as to the problem. The following points address a few common trouble spots:

'''Module Load Order Can Matter'''
* in cases where loading more then one module is necessary, the order in which you load the modules can matter!

'''Sometimes Automagic just isn't Automagic'''
* If a module was, for whatever reason, not loaded, you can try manually loading it with the appropriate ''modprobe'' command.

'''Unresolved Symbols'''
* if you tried the second method ("make unload" followed by an appropriate modprobe command) but encountered errors in relation to unresolved symbols, e.g. using the saa7134 module as an example:
sudo modprobe saa7134
FATAL: Error inserting saa7134 (/lib/modules/''[your kernel version]''/kernel/drivers/media/video/saa7134/saa7134.ko):\
Unknown symbol in module, or unknown parameter (see dmesg)
please try a system reboot before filing an [[Bug Report|error report]]. Irregardless of what caused the unresolved symbols errors, usually, after performing the reboot, you will find that the install was actually successful and the drivers will work as intended.

* Special case: If your system uses compressed kernel modules, after running the "make install" command of the V4L-DVB installation process, you could end up with a mixture of new modules (*.ko) and their older compressed version (*.ko.gz) installed. If the system attempts to concurrently load both sets into memory, you are bound to run into modprobe insertion errors (eg. unknown symbol or unknown parameter). All conflicting *.ko.gz files must be removed. The following command line can help you locate these conflicting files in all your installed kernels:
for file in `find /lib/modules -name "*.ko"`; do if <nowiki>[[</nowiki> -e $file.gz <nowiki>]]</nowiki>; then echo "$file.gz should be removed"; fi; done
Usually all conflicting module files resulting of v4l-dvb installation will be located in:
/lib/modules/''[your kernel version]''/kernel/drivers/media
Once the conflicting *.ko.gz have been moved elsewhere or renamed (to *.ko.gz.disabled for example), use the v4l-dvb reload command and, to be safe, also add a "depmod" step in order to rebuild modules dependencies):
make reload
depmod -a
Your new modules should now be loaded correctly.

'''A Note on Firmware'''
* You have all the modules active (listed in lsmod) but device nodes are nowhere to be found: The problem may be as simple as the [[Firmware|firmware]] for the device not being loaded; some devices also require a [[Firmware|firmware]], which is uploaded from the host PC to the device, in order to operate.

In some cases, when the device is correctly recognized, the associated drivers provide information as to which firmware file is required -- look in the system log output. For example, for many [[TechnoTrend]] & [[Hauppauge]] (and other similar "premium" cards), if the dvb-ttpci firmware is not available you will observe an error such as:
<pre> dvb-ttpci: could not load firmware, file not found: dvb-ttpci-01.fw
dvb-ttpci: usually this should be in /usr/lib/hotplug/firmware or /lib/firmware
dvb-ttpci: and can be downloaded from http://www.linuxtv.org/download/dvb/firmware/</pre>
Resolving that missing firmware issue should then result in proper detection and configuration of your device.
In other cases, obtaining the correct firmware is not so straightforward a task. The very first thing you need to know is what device you're using; see "[[Supported_Hardware#Determining_the_Device's_Identity|Determining the Device's Identity]]". Once you have established which particular device you are in possession of, you can then move on to [[Firmware#Acquiring the Firmware|obtaining the correct firmware]]. In addition, information in wiki articles (eg. such as [[DVB-T USB Devices]]) will cite the appropriate firmware required. If you're still at a loss, a Google search may shed light on what file you need. Note, however, that not all supported devices have easily available firmware (eg. Hauppauge HVR 1100 & 1300). Firmware for such cards could be loaded via temporary installation in a Mirosoft Windows System with the manufacturer-supplied drivers.

In any regard, once you find and obtain the necessary firmware for your device, copy it into the appropriate directory; the directory location depends upon that used by your distro, but typically it is:
*/lib/firmware
Consult resources for your distro if its preferred location is somewhere otherwise.

==Some Further Documentation==
* See [[Testing your DVB device]] for instructions on testing your newly installed DVB device

[[Category:Software]]
[[Category:Drivers]]

How to Obtain, Build and Install V4L-DVB Device Drivers

2012-04-11T19:01:34Z

Mauro Carvalho Chehab: /* Retrieving and Building/Compiling the Latest V4L-DVB Source Code */

The LinuxTV project hosts the latest set of Linux kernel driver modules for [[What is V4L or DVB?|V4L-DVB devices]]. This page contains information to help an "end user" install these device drivers in a GNU/Linux system.

{{Note|This article assumes that:
* your device is actually supported by the drivers -- Just because your board happens to have a chip on it that corresponds to some existing driver does NOT mean your product is supported. The driver has to be aware that it's related to some hardware (typically through the [[Supported_Hardware#Determining_the_Device's_Identity|subsystem ID from the USB ID or PCI ID]]). If the driver doesn't recognize/bind to your particular hardware, then the module will probably load but then proceed to not do anything. In other words, support for your device would have to be added to the driver.
* you have already physically installed the hardware device into, or connected it to, your system. (Refer to the manufacturer's instructions for such details)}}.

== Software Requirements ==
===Kernel Support===
The LinuxTV V4L-DVB drivers will work only in conjunction with relatively modern 2.6 kernels; specifically,

{{Note|CityK here: I have no clue as to where the current backwards compatibility status stands. Suffice to say, more modern kernels (which I'd define as ~2.6.32 and newer) are much more likely to work with the new media_build snapshots of the git tree. When the situation is more clear, please update this section accordingly.}}

===Additional Software Requrirements===
In order to be able to build the V4L-DVB kernel driver modules, you will need:
* kernel-source or kernel-headers
* (OpenSuSE and fedora only) kernel-devel
* (Debian) libdigest-sha1-perl
* make
* gcc
* git
* patch
* patchutils
* libproc-processtable-perl ("perl-Proc-ProcessTable")
If these packages are not currently installed on your system, you should do so now.

==Retrieving and Building/Compiling the Latest V4L-DVB Source Code==
There are a couple of different methods by which you can obtain and build the latest source code. Regardless of which route you take, all are performed from the command line within a console. The "basic" method is likely appropriate for most end users, though, in some cases, some users will have to use the slightly more "manually intensive" approach. This second approach is effectively, for all intents and purposes, really just the same as the "basic" method, but performing the steps in a piecemeal fashion affords you the opportunity to tailor the source code or the "make"/build process as might be required in your particular situation. Again, before proceeding with either approach, make sure you have installed all the prerequisite software listed above.

{{Note|If you are using Ubuntu, you were previously very likely to run into a fatal compilation error within the v4l-dvb build process when it reaches the firedtv module. The reason for this is because Ubuntu had a bug in their packaging of the kernel headers. <b>This seems to be fixed</b> on a fully updated systtem (5 July 2011) This was a long standing issue, and one of the most frequently reported on the mailing list. <br>
If you still have the problem, you should be able to correct this compilation problem by following the more manual procedure listed below. In particular, before proceeding to build the modules, you will have to edit the file ''v4l/.config'' and change the line for the firedtv driver from <nowiki>"firedtv=m" to "firedtv=n"</nowiki>.}}

{{Note|If you are having build failures like "implicit declaration of function 'mfd_get_data'" try editing v4l/Makefile.media, and just comment out anything related to CONFIG_*_TIMBERALE. [[http://sourceforge.net/mailarchive/message.php?msg_id=27353778 Source]] }}

{| class="wikitable"
|+'''Retreiving the Source Code & Building/Compiling the Modules'''
|-
! "Basic" Approach !! Developer's Approach !! More "Manually Intensive" Approach

|-
| valign=top |
git clone git://linuxtv.org/media_build.git
cd media_build
./build

These commands will download the newest tarball of the source code from linuxtv.org, apply the backport patches to it and then build/compile the source via the included script build.sh.

NB: to add a patch copy the .patch file to the backports directory, and add the patch file as a line to the {kernel-version}_series file in the packports dir.
| valign=top |
~ $ git clone git://linuxtv.org/media_build.git
~ $ cd media_build
~/media_build $./build --main-git
{{Note|'''The build script will clone the entire media-tree.git, with will take some time'''}}

In order to modify a driver foo.c:

~/media_build $ cd media
~/media $ gedit drivers/media/video/foo.c
~/media $ make -C ../v4l
~/media $ make -C ../ install
~/media $ make -C .. rmmod
~/media $ modprobe foo

(some procedure to test the "foo" driver)

To generate a patch, use:

~/media $ git commit -as

Then submit the patch upstream. If your sendmail is propery configured, you can easily send the patch upstream with:

~/media $ git send-email HEAD^1

or, to send a patch series:

~/media $ git send-email ''initial_branch''

Where ''initial_branch'' is the name of a branch of a changeset number for the last patch before your changes.

|
git clone git://linuxtv.org/media_build.git
cd media_build/linux
make tar DIR=<some dir with media -git tree>
make untar
cd ..

If you need to make any sort of change or modification to the source code, now is the time.

<div style="border: solid 1px; border-color: blue; margin: 1em; padding: 1em; background-color: Lavender;">
'''Optional Pre-Compilation Steps'''<br>
These optional command steps are applicable only in certain situations approaching a new build of the driver set, or for experienced users wishing to streamline the build process to consist of only those components they want to install.
* <code>make rminstall</code> ... you would use this to remove the currently installed driver set (located within the relevant ''/lib/modules/["kernel version"]/kernel/drivers/media'' directory to which they were installed)
* <code>make distclean</code> ... cleans up the build configuration environment ... noteworthy is that it will set things up such that a following "make" build process will be against "''/usr/src/[uname -r]''” kernel source
* <code>make menuconfig</code> ... this will open up the ncurses based menu that allows you to select only those components you wish to build and install

The building system offers some other make targets that may be useful for advanced users or developers. For listing the supported targets, please use <code>make help</code>.</div>

Next, build/compile the modules from the source code with the command:
make
{{Note|For multi-core processor systems, the ''make'' command has available options that can be beneficial in terms of the reducing the amount of time required for the process' completion. Specifically, you can run "''make -jN''" (where "''N''" <nowiki>=</nowiki> 1 + the number of cores your cpu has ... i.e. if you have a dual core cpu use: ''make -j3'' )}}

|}
===Information Regarding the Build Process===
Generally, this step will tend to take a while to complete; being dependent upon both the number of modules being built and your system's processing power.

You can monitor the build progress via the console output. You will notice that a ''/v4l'' directory will have been created and within which the completed *.ko module files are written. Some drivers included within the snapshot may have their own requirements in regards to the kernel that you must be running in order for the module to be built; such cases can be found listed at the beginning of the build process' console output.

The entire build process should complete without error. If any errors are encountered, the compilation will be halted and, at this point, you should not attempt to proceed any further (unless you really, really enjoy experiencing the outcome of a preordained failure). Errors that prevent building a particular V4L-DVB snapshot do indeed surface from time to time, but these are usually corrected quickly upon notification from an end user submitted [[Bug Report|bug report]], or upon detection from the daily automated build tests (see note below). If you have run into a build error via the "basic" approach outlined above, you may wish to see if you can remedy the error and attempt a module build via the more "manually intensive" approach also outlined above.

{{Note|'''The Daily Automated Build Tests'''<br>
Hans Verkuil has set up an automated daily build of the V4L-DVB source code upon all supported kernels, as well as testing that very same upon several CPU architectures. A brief synopsis of the results from those tests is published each day on the Linux-Media Mailing List (LMML) under a message subject heading prefix of "''[cron job] v4l-dvb daily build ...''". A link to more detailed results of these tests is also provided within that message or can be found directly from [http://www.xs4all.nl/~hverkuil/logs/ here].}}

If you do run into any problems during the build step, you should:
* first, see whether the issue is already known or not -- consult the results of the daily automated build tests (see note above)
* if it appears that this is a new issue, please [[Bug Report|inform the developers of the bug via the LMML]] (preferred) or thorough one of the irc.freenode.net irc channels (#v4l or #linuxtv or #dvb).
* you may also wish to consult any errata that might be found on this article's talk page

In general, if the source builds correctly, it is likely that the drivers will work, though this is not a guarantee.

== Installing the Compiled Driver Modules ==
The next step is to install the kernel driver modules by executing:
sudo make install
The command above will prompt you for your root password, and will then copy the *.ko module files you built in the above step into the ''/lib/modules/[kernel version]/kernel/drivers/media'' directories.

{{Note|If your distribution doesn't support the sudo command (i.e the command line returns ''"bash: sudo: command not found"''), use the "su" command instead. "su" will prompt you for the root password, and after which entering, you can then proceed with the command. Ex.:
su
make install
}}
<br>
{{Note|In the case where you have more then one kernel installed but have used the pre-compilation option of "make distclean", the new modules will be installed only into the ''/lib/modules/[uname -r]/kernel/drivers/media'' directory}} <br>

== First Use: Out with the Old, In with the New==
{|
| valign=top |
Before trying to use the device with your newly installed driver set, you should remove from system memory any older versions of related modules that may have been loaded by the running kernel; otherwise, you will likely run into various fatal mismatch errors -- typified by an "unknown symbol" or "unknown parameter" -- as a result of your system trying to work from a mixture of old and new modules.

To achieve a [[Wikipedia:Tabula rasa |clean slate]] state, you could either: <br>

'''1. Reboot:''' Perhaps the most straightforward thing to do at this point, particularly for Linux newbies, is to just restart your system; the reboot will, obviously, clear out the old modules loaded into memory and, as an added bonus, create a fresh running environment under which the new modules should have been automagically loaded into system memory.

Or, on the other hand,

'''2. Take care of business yourself:''' More experienced users might prefer to use more eloquent approaches. For example, using
sudo make unload
will essentially (and similar as to manually using "rmmod" commands) remove all older modules for the device that might be currently loaded in memory by the running kernel. After which, one can then load, from the newly installed device driver set, the appropriate modules for the device using relevant
modprobe ''driver_name''
commands.

| valign=top halign=right width=30% |
<div style="border: solid 1px; border-color: blue; margin: 1em; padding: 1em; background-color: Lavender;">
'''For Advanced Users'''<br>
The following information is likely useful only for developers. After building the modules as per usual ("make"), and without needing to install them, you can:
* remove all older modules from memory at once using "make unload" and
* then insert all the newly built modules into memory for the running kernel with "make load"
Alternatively, to perform the previous two commands ("make unload" and "make load") in a single step, you can use "make reload"

Note, however, that it is highly recommended that you avoid using either the make load or make reload options, as they will end up inserting <u>all</u> V4L-DVB device drivers into memory, and that may introduce instability, or complicate testing.
</div>
|}
Regardless of which approach you take to remove the old modules and to insert the new ones, the end result should be the same. In addition, upon future starts of your system, your device should "automagically" be detected and will have the appropriate driver modules loaded into memory.

===If the Modules load correctly:===
Provided that the modules were loaded correctly into system memory:

'''1. They should be listed in ''/proc/modules''''': you can use either <code>cat /proc/modules</code> or, even better, <code>lsmod</code> to see this content.

Which modules should you be looking for? Well, the answer to that question depends entirely upon the chipsets used by your device -- see the relevant wiki article for your device for a listing of such components and required drivers (or search the web if such information does not exist. '''Note''': Please add any information missing from the wiki!)

'''2. They should provide some indication within your system log''': you can consult the output from the "<code>dmesg</code>" command or directly review your system log file (typically housed within the ''/var/log'' directory) for indication that they have been successfully loaded and that the device is now correctly configured for operation. Examples of successful module loads are provided by users under the "Sample kernel output" section in many device articles witin the wiki.

'''3. The device manager [[Wikipedia:udev|udev]] will "automagically" create appropriate [[Device nodes and character devices|device nodes]] on ''/dev''''': <br>
'''(a) For a DVB device''', you should now have a non-empty ''/dev/dvb'' directory. You can check on whether this is true for you with the following command:
: <code>ls -l /dev/dvb/</code>
(alternatively, you can browse your directory structure with the graphical file manager of your choice). If you have a single DVB device installed in your system, then the output of the above command should reveal that /dev/dvb/ is populated by adapter0. Digging further,
: <code>ls -l /dev/dvb/adapter0 </code>
reveals the [[Device_nodes_and_character_devices#DVB_character_devices|character devices]] associated with adapter0 for which the drivers have control. If you have more then one DVB device, you can see the same for all with
: <code>ls -l /dev/dvb/adapter* </code>

'''(b) For a V4L device''', you should now have a non-empty ''/dev/v4l'' directory. You can check on whether this is true for you with the following command:
: <code>ls -l /dev/v4l</code>
Digging further,
: <code>ls -l /dev/v4l/by-path </code>
reveals the symbolic links to the [[Device_nodes_and_character_devices#V4L_character_devices|character devices]] associated with your V4L adapter for which the drivers have control. The most typical of which is ''/dev/video0''. If you have more then one V4L device, you can see the same for all with
: <code>ls -l /dev/video* </code>

===If the Modules did not load correctly or the device is still not configured correctly for use:===
There could be several reasons why you may have encountered a module loading error or, absent such an error, why the device is still not configured correctly for use, even after having correctly followed the steps from the above procedure. If either of these cases applies, the very first thing you should do is [[Supported Hardware|check whether your device is actually supported]] by the driver (see the very first note at the top of this page). Next, provided your device is supposed to be supported, check within your system log/dmesg for any messages that may give indication as to the problem. The following points address a few common trouble spots:

'''Module Load Order Can Matter'''
* in cases where loading more then one module is necessary, the order in which you load the modules can matter!

'''Sometimes Automagic just isn't Automagic'''
* If a module was, for whatever reason, not loaded, you can try manually loading it with the appropriate ''modprobe'' command.

'''Unresolved Symbols'''
* if you tried the second method ("make unload" followed by an appropriate modprobe command) but encountered errors in relation to unresolved symbols, e.g. using the saa7134 module as an example:
sudo modprobe saa7134
FATAL: Error inserting saa7134 (/lib/modules/''[your kernel version]''/kernel/drivers/media/video/saa7134/saa7134.ko):\
Unknown symbol in module, or unknown parameter (see dmesg)
please try a system reboot before filing an [[Bug Report|error report]]. Irregardless of what caused the unresolved symbols errors, usually, after performing the reboot, you will find that the install was actually successful and the drivers will work as intended.

* Special case: If your system uses compressed kernel modules, after running the "make install" command of the V4L-DVB installation process, you could end up with a mixture of new modules (*.ko) and their older compressed version (*.ko.gz) installed. If the system attempts to concurrently load both sets into memory, you are bound to run into modprobe insertion errors (eg. unknown symbol or unknown parameter). All conflicting *.ko.gz files must be removed. The following command line can help you locate these conflicting files in all your installed kernels:
for file in `find /lib/modules -name "*.ko"`; do if <nowiki>[[</nowiki> -e $file.gz <nowiki>]]</nowiki>; then echo "$file.gz should be removed"; fi; done
Usually all conflicting module files resulting of v4l-dvb installation will be located in:
/lib/modules/''[your kernel version]''/kernel/drivers/media
Once the conflicting *.ko.gz have been moved elsewhere or renamed (to *.ko.gz.disabled for example), use the v4l-dvb reload command and, to be safe, also add a "depmod" step in order to rebuild modules dependencies):
make reload
depmod -a
Your new modules should now be loaded correctly.

'''A Note on Firmware'''
* You have all the modules active (listed in lsmod) but device nodes are nowhere to be found: The problem may be as simple as the [[Firmware|firmware]] for the device not being loaded; some devices also require a [[Firmware|firmware]], which is uploaded from the host PC to the device, in order to operate.

In some cases, when the device is correctly recognized, the associated drivers provide information as to which firmware file is required -- look in the system log output. For example, for many [[TechnoTrend]] & [[Hauppauge]] (and other similar "premium" cards), if the dvb-ttpci firmware is not available you will observe an error such as:
<pre> dvb-ttpci: could not load firmware, file not found: dvb-ttpci-01.fw
dvb-ttpci: usually this should be in /usr/lib/hotplug/firmware or /lib/firmware
dvb-ttpci: and can be downloaded from http://www.linuxtv.org/download/dvb/firmware/</pre>
Resolving that missing firmware issue should then result in proper detection and configuration of your device.
In other cases, obtaining the correct firmware is not so straightforward a task. The very first thing you need to know is what device you're using; see "[[Supported_Hardware#Determining_the_Device's_Identity|Determining the Device's Identity]]". Once you have established which particular device you are in possession of, you can then move on to [[Firmware#Acquiring the Firmware|obtaining the correct firmware]]. In addition, information in wiki articles (eg. such as [[DVB-T USB Devices]]) will cite the appropriate firmware required. If you're still at a loss, a Google search may shed light on what file you need. Note, however, that not all supported devices have easily available firmware (eg. Hauppauge HVR 1100 & 1300). Firmware for such cards could be loaded via temporary installation in a Mirosoft Windows System with the manufacturer-supplied drivers.

In any regard, once you find and obtain the necessary firmware for your device, copy it into the appropriate directory; the directory location depends upon that used by your distro, but typically it is:
*/lib/firmware
Consult resources for your distro if its preferred location is somewhere otherwise.

==Some Further Documentation==
* See [[Testing your DVB device]] for instructions on testing your newly installed DVB device

[[Category:Software]]
[[Category:Drivers]]

Development: Submitting Drivers

2011-07-11T00:23:22Z

Mauro Carvalho Chehab: /* Who To Submit Drivers To */

The following content is a copy of the <code>/usr/src/linux/Documentation/SubmittingDrivers</code> file (modified slightly for visual presentation). A current copy can also be found online [http://lxr.linux.no/source/Documentation/SubmittingDrivers here].

<center>'''Submitting Drivers For The Linux Kernel'''</center>

This document is intended to explain how to submit device drivers to the various development trees of the Linux kernel. Note that if you are interested in video card drivers you should probably talk to [http://x.org/ X.Org] and/or [http://www.xfree86.org/ XFree86] instead.

Also read the [[Development: Submitting Patches|Documentation/SubmittingPatches]] document.

== Allocating Device Numbers ==
Major and minor numbers for block and character devices are allocated by the Linux assigned name and number authority (currently better known as H Peter Anvin). The site is http://www.lanana.org/. This also deals with allocating numbers for devices that are not going to be submitted to the mainstream kernel.

If you don't use assigned numbers then when you device is submitted it will get given an assigned number even if that is different from values you may
have shipped to customers before.

== Who To Submit Drivers To ==
;Linux 3.x: Any patches for a media driver (drivers/media) should be submitted to the Linux Media Mailing list <linux-media@vger.kernel.org>
;Linux 2.6: A patch that also applies to an stable kernel should have a "Cc: stable@kernel.org" in the body of the email. Once reached upstream, it will be sent to the Stable maintainer. If there's already a patch for it upstream, you can submit it directly to the stable Mailing list (stable@kernel.org).

== What Criteria Determine Acceptance ==
;Licensing: The code must be released to us under the GNU General Public License. We don't insist on any kind of exclusively GPL licensing, and if you wish the driver to be useful to other communities such as BSD you may well wish to release under multiple licenses.

;Copyright: The copyright owner must agree to use of GPL. It's best if the submitter and copyright owner are the same person/entity. If not, the name of the person/entity authorizing use of GPL should be listed in case it's necessary to verify the will of the copright owner.

:Interfaces: If your driver uses existing interfaces and behaves like other drivers in the same class it will be much more likely to be accepted than if it invents gratuitous new ones. If you need to implement a common API over Linux and NT drivers do it in userspace.

;Code: Please use the Linux style of code formatting as documented in Documentation/CodingStyle. If you have sections of code that need to be in other formats, for example because they are shared with a windows driver kit and you want to maintain them just once separate them out nicely and note this fact.

;Portability: Pointers are not always 32bits, not all computers are little endian, people do not all have floating point and you shouldn't use inline x86 assembler in your driver without careful thought. Pure x86 drivers generally are not popular. If you only have x86 hardware it is hard to test portability but it is easy to make sure the code can easily be made portable.

;Clarity: It helps if anyone can see how to fix the driver. It helps you because you get patches not bug reports. If you submit a driver that intentionally obfuscates how the hardware works it will go in the bitbucket.

;Control: In general if there is active maintainance of a driver by the author then patches will be redirected to them unless they are totally obvious and without need of checking. If you want to be the contact and update point for the driver it is a good idea to state this in the comments, and include an entry in MAINTAINERS for your driver.

== What Criteria Do Not Determine Acceptance ==
;Vendor: Being the hardware vendor and maintaining the driver is often a good thing. If there is a stable working driver from other people already in the tree don't expect 'we are the vendor' to get your driver chosen. Ideally work with the existing driver author to build a single perfect driver.

;Author: It doesn't matter if a large Linux company wrote the driver, or you did. Nobody has any special access to the kernel tree. Anyone who tells you otherwise isn't telling the whole story.

== Resources ==
;Linux kernel master tree: ftp.??.kernel.org:/pub/linux/kernel/...<br> where ?? is your country code, such as "us", "uk", "fr", etc.

;Linux kernel mailing list: linux-kernel@vger.kernel.org <br> [mail majordomo@vger.kernel.org to subscribe]

;Linux Device Drivers, Third Edition (covers 2.6.10): http://lwn.net/Kernel/LDD3/ (free version)

;Kernel traffic [http://www.kerneltraffic.org/kernel-traffic/]: Weekly summary of kernel list activity (much easier to read)

;LWN.net [http://lwn.net/]: Weekly summary of kernel development activity <br> * [http://lwn.net/Articles/2.6-kernel-api/ 2.6 API changes] <br> * [http://lwn.net/Articles/driver-porting/ Porting drivers from prior kernels to 2.6]

;KernelTrap [http://kerneltrap.org/]: Occasional Linux kernel articles and developer interviews

; KernelNewbies [http://kernelnewbies.org/]: Documentation and assistance for new kernel programmers

;Linux USB project [http://sourceforge.net/projects/linux-usb/]: Helpful for the development of USB based device drivers

[[Category:Development]]

Bus snooping/sniffing

2011-03-16T15:04:21Z

Mauro Carvalho Chehab: /* Snooping Procedures: */

Purpose and relevance to development work -- description coming soon

==PCI / PCIe ==
===Snooping Utilities:===
* BTSpy [http://btwincap.sourceforge.net/custom.html] - Windows based snoop for BT8x8 based devices
* Dscaler's RegSpy [http://www.dscaler.com/] - Windows based; contains the ability to snoop the registers of [[Interface chipsets|PCI / PCIe interface chipsets]] ... also see [http://marc.info/?l=linux-dvb&m=122823618002379&w=2 this note]

==USB ==
===Snooping Utilities:===
* [[usbsnoop]] - a Windows based utility for sniffing/monitoring communications traffic for a USB device. Note: In case usbsnoop/SniffUSB doesn't work for you, here are a few time limited apps that should work under Vista:
** [http://www.hhdsoftware.com/Family/usb-monitor.html USB Monitor] - 14-day trial period
** [http://www.usblyzer.com/ USBlyzer] - fully functional evaluation version for 33 days (only 32 bit)
* SnoopyPro - Windows based snoop for USB device communications traffic
* usbsnoop/SniffUSB - Windows based snoop for USB device communications traffic
* usbmon - Linux kernel module which can snoop USB device communications traffic
** [http://git.linuxtv.org/v4l-utils.git?a=blob;f=contrib/parse_tcpdump_log.pl;hb=HEAD parse_tcpdump_log.pl] - a script to directly talk with usbmon, parsing the result into a format feasible for analysis. This is part of the contrib stuff at the [http://git.linuxtv.org/v4l-utils.git v4l-utils tree]. It allows both realtime and offline parsing of usbmon data, and its format output is compatible with other parsers like the [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/em28xx/parse_em28xx.pl;h=master;hb=HEAD em28xx log parser].
** Wireshark - logs usbmon output, via libpcap
** USBMon - logs usbmon output

===Log parsers, format etc===

* [[usbmon2usbsnoop]]
* [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/parse-usbsnoop.php;h=master;hb=HEAD parse-usbsnoop.php]
* [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/parse-sniffusb2.pl;h=master;hb=HEAD parse-sniffusb2.pl]
* [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/em28xx/parse_em28xx.pl;h=master;hb=HEAD em28xx log parser]

===Snooping Procedures:===
* Use a Snopping utility to get the log.
* Group URB transactions into a shorter log by using a parser, like [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/parse-usbsnoop.php;h=master;hb=HEAD parse-usbsnoop.php]
* Identify the URB transactions at the control endpoint. URB transactions look like those:

40 02 00 00 ba 00 03 00 >>> 20 11 00

{| class="wikitable"
|+'''URB fields'''
|-
| Byte || Meaning
|-
| 1 || {| bit 7 = 1 - IN / 0 - OUT
bit 6 = 1 - Vendor Class
|-
| 2 || URB Request
|-
| 3-4 || URB Value in big endian
|-
| 5-6 || URB Index in big endian
|-
| 7-8 || URB message size in big endian
|-
|}

For example, let's analyse the folowing URB's:

{| class="wikitable"
|+'''control URB examples '''
|-
| URB sequence log (URB setup + URB IN or OUT) || Byte 1 || Byte 2 || Bytes 3-4 || Bytes 5-6 || Bytes 7-8 || Message
|-
| 40 00 00 00 08 00 01 00 >>> 3d || USB OUT, Vendor Class || Req = 0x00 || Value = 0x0000 || Index = 0x0008 || Size = 0x0001 || { 0x3d }
|-
| 40 02 00 00 ba 00 03 00 >>> 20 11 00 || USB OUT, Vendor Class || Req = 0x02 || Value = 0x0000 || Index = 0x00ba || Size = 0x0003 ||{ 0x20, 0x11, 0x00 }
|-
| c0 00 00 00 15 00 01 00 <<< 00 || USB IN, Vendor Class || Req = 0x00 || Value = 0x0000 || Index = 0x0015 || Size = 0x0001 || { 0x00 }
|}

After getting the log, you should analyse and understand the meaning of each of URB fields on your device.

For example, in the case of [[Em28xx_devices | em28xx]], Req is used to indicate internal registers or I2C, Value is always 0 and Index indicates what device register is being used.

On em28xx, the [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/em28xx/parse_em28xx.pl;h=master;hb=HEAD em28xx log parser] could be used in order to proccess the URBs and the driver dmesg dumps (in the compact format as shown above) and print them into a more human way, generating C like statements that can be added at em28xx source code (with a few adaptations, in the case of i2c messages):

em28xx_write_reg(dev, EM28XX_R08_GPIO, 0x3d);
i2c_master_send(0xba>>1, { 20 11 00 }, 0x03);
em28xx_read_reg(dev, EM28XX_R15_RGAIN); /* read 0x00 */

If all you want is to check what the em28xx Linux driver is doing, and provided that the usbmon module is loaded (the Kernel should be compiled with CONFIG_USB_MON option), you can just use:

./parse_tcpdump_log.pl --pcap |./parse_em28xx.pl

There are some other parsers for some specific devices at the [http://git.linuxtv.org/v4l-utils.git?a=tree;f=contrib;hb=HEAD contrib directory of the v4l-tools git tree].

===Command Playback Utilities:===
* usb-robot - plays back USB Snoopy capture logs
* usbreplay - plays back usbsnoop capture logs

==i2c==
* i2c Tools: see [http://www.lm-sensors.org/wiki/I2CTools here] and [http://www.lm-sensors.org/wiki/i2cToolsDocumentation here]
* http://en.wikipedia.org/wiki/I2C#Development_Tools
* also see [http://www.spinics.net/lists/linux-dvb/msg16845.html this thread]

==External Links==
* [[Wikipedia:Bus sniffing|Wikipedia's Bus sniffing article]]; note that the [[Wikipedia:Cache coherency|Cache coherency]] article is a probably a little less vague or more enlightening
[[Category:Development]]

Bus snooping/sniffing

2011-03-16T14:54:32Z

Mauro Carvalho Chehab:

Purpose and relevance to development work -- description coming soon

==PCI / PCIe ==
===Snooping Utilities:===
* BTSpy [http://btwincap.sourceforge.net/custom.html] - Windows based snoop for BT8x8 based devices
* Dscaler's RegSpy [http://www.dscaler.com/] - Windows based; contains the ability to snoop the registers of [[Interface chipsets|PCI / PCIe interface chipsets]] ... also see [http://marc.info/?l=linux-dvb&m=122823618002379&w=2 this note]

==USB ==
===Snooping Utilities:===
* [[usbsnoop]] - a Windows based utility for sniffing/monitoring communications traffic for a USB device. Note: In case usbsnoop/SniffUSB doesn't work for you, here are a few time limited apps that should work under Vista:
** [http://www.hhdsoftware.com/Family/usb-monitor.html USB Monitor] - 14-day trial period
** [http://www.usblyzer.com/ USBlyzer] - fully functional evaluation version for 33 days (only 32 bit)
* SnoopyPro - Windows based snoop for USB device communications traffic
* usbsnoop/SniffUSB - Windows based snoop for USB device communications traffic
* usbmon - Linux kernel module which can snoop USB device communications traffic
** [http://git.linuxtv.org/v4l-utils.git?a=blob;f=contrib/parse_tcpdump_log.pl;hb=HEAD parse_tcpdump_log.pl] - a script to directly talk with usbmon, parsing the result into a format feasible for analysis. This is part of the contrib stuff at the [http://git.linuxtv.org/v4l-utils.git v4l-utils tree]. It allows both realtime and offline parsing of usbmon data, and its format output is compatible with other parsers like the [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/em28xx/parse_em28xx.pl;h=master;hb=HEAD em28xx log parser].
** Wireshark - logs usbmon output, via libpcap
** USBMon - logs usbmon output

===Log parsers, format etc===

* [[usbmon2usbsnoop]]
* [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/parse-usbsnoop.php;h=master;hb=HEAD parse-usbsnoop.php]
* [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/parse-sniffusb2.pl;h=master;hb=HEAD parse-sniffusb2.pl]
* [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/em28xx/parse_em28xx.pl;h=master;hb=HEAD em28xx log parser]

===Snooping Procedures:===
* Use a Snopping utility to get the log.
* Group URB transactions into a shorter log by using a parser, like [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/parse-usbsnoop.php;h=master;hb=HEAD parse-usbsnoop.php]
* Identify the URB transactions at the control endpoint. URB transactions look like those:

40 02 00 00 ba 00 03 00 >>> 20 11 00

{| class="wikitable"
|+'''URB fields'''
|-
| Byte || Meaning
|-
| 1 || {| bit 7 = 1 - IN / 0 - OUT
bit 6 = 1 - Vendor Class
|-
| 2 || URB Request
|-
| 3-4 || URB Value in big endian
|-
| 5-6 || URB Index in big endian
|-
| 7-8 || URB message size in big endian
|-
|}

For example, let's analyse the folowing URB's:

{| class="wikitable"
|+'''control URB examples '''
|-
| URB sequence log (URB setup + URB IN or OUT) || Byte 1 || Byte 2 || Bytes 3-4 || Bytes 5-6 || Bytes 7-8 || Message
|-
| 40 00 00 00 08 00 01 00 >>> 3d || USB OUT, Vendor Class || Req = 0x00 || Value = 0x0000 || Index = 0x0008 || Size = 0x0001 || { 0x3d }
|-
| 40 02 00 00 ba 00 03 00 >>> 20 11 00 || USB OUT, Vendor Class || Req = 0x02 || Value = 0x0000 || Index = 0x00ba || Size = 0x0003 ||{ 0x20, 0x11, 0x00 }
|-
| c0 00 00 00 15 00 01 00 <<< 00 || USB IN, Vendor Class || Req = 0x00 || Value = 0x0000 || Index = 0x0015 || Size = 0x0001 || { 0x00 }
|}

After getting the log, you should analyse and understand the meaning of each of URB fields on your device.

For example, in the case of [[Em28xx_devices | em28xx]], Req is used to indicate internal registers or I2C, Value is always 0 and Index indicates what device register is being used.

On em28xx, the [http://git.linuxtv.org/v4l-utils.git?a=blob_plain;f=contrib/em28xx/parse_em28xx.pl;h=master;hb=HEAD em28xx log parser] could be used in order to proccess the URBs and the driver dmesg dumps (in the compact format as shown above) and print them into a more human way, generating C like statements that can be added at em28xx source code (with a few adaptations, in the case of i2c messages):

em28xx_write_reg(dev, EM28XX_R08_GPIO, 0x3d);
i2c_master_send(0xba>>1, { 20 11 00 }, 0x03);
em28xx_read_reg(dev, EM28XX_R15_RGAIN); /* read 0x00 */

===Command Playback Utilities:===
* usb-robot - plays back USB Snoopy capture logs
* usbreplay - plays back usbsnoop capture logs

==i2c==
* i2c Tools: see [http://www.lm-sensors.org/wiki/I2CTools here] and [http://www.lm-sensors.org/wiki/i2cToolsDocumentation here]
* http://en.wikipedia.org/wiki/I2C#Development_Tools
* also see [http://www.spinics.net/lists/linux-dvb/msg16845.html this thread]

==External Links==
* [[Wikipedia:Bus sniffing|Wikipedia's Bus sniffing article]]; note that the [[Wikipedia:Cache coherency|Cache coherency]] article is a probably a little less vague or more enlightening
[[Category:Development]]

Usbmon

2011-03-16T14:48:14Z

Mauro Carvalho Chehab:

{{lowercase|usbmon}}

A Linux kernel module which can snoop and output USB communications traffic. The output produced by usbmon can be examined by using utilities such as '''usbdump''', '''USBMon''' or '''[[Wireshark]].

The [http://git.linuxtv.org/v4l-utils.git v4l-utils tree] provides the [http://git.linuxtv.org/v4l-utils.git?a=blob;f=contrib/parse_tcpdump_log.pl;hb=HEAD parse_tcpdump_log.pl] script to directly talk with usbmon, parsing the result into a format feasible for analysis.

==Also see==
* [[Usbmon2usbsnoop|usbmon2usbsnoop]] - a perl script that convert's usbmon output into [[usbsnoop]] log file format (thereby making the data compatible for use with, for example, [[usbreplay]])

==External Links==
* [http://www.mjmwired.net/kernel/Documentation/usb/usbmon.txt kernel documentation]
* [http://74.125.95.132/search?q=cache:bMh9AGUtqasJ:people.redhat.com/zaitcev/linux/OLS05_zaitcev.pdf+usbmon&hl=en&ct=clnk&cd=4&gl=ca&client=firefox-a The usbmon: USB monitoring framework] article
* [http://www.linux-usb.org/USBMon USBMon] - an old java program that can interface with the output from the usbmon kernel module; unfinished ? see: [http://people.redhat.com/zaitcev/linux/ the notes on this page] and those from [http://www.quietearth.us/articles/2006/10/16/USB-Snoop-in-linux this article] on USB snooping under Linux
* [http://www.wireshark.org/ Wireshark] - a more polished way to interface, via libpcap, with the usbmon kernel module's output; see the Wireshark wiki page's regarding USB: [http://wiki.wireshark.org/USB here] and [http://wiki.wireshark.org/CaptureSetup/USB here]

[[category:software]]

Libv4l Progress

2010-10-24T16:54:44Z

Mauro Carvalho Chehab:

Progress of applications that are in need of libv4l2 conversion.

{| class="wikitable sortable"
|+'''A sortable list of applications that are in need of libv4l2 conversion'''
|-
! application !! upstream !! fedora !! suse !! debian
|-
| v4l-utils (includes libv4l) || - || [https://fedoraproject.org/wiki/Features/BetterWebcamSupportF13 available] || [http://software.opensuse.org/search?q=v4l-utils&baseproject=openSUSE%3A11.3 available] || [http://packages.qa.debian.org/v/v4l-utils.html available]
|-
| [http://gstreamer.net GStreamer] || [http://bugzilla.gnome.org/show_bug.cgi?id=545033 bug] || [https://bugzilla.redhat.com/show_bug.cgi?id=456825 bug] || bug || [http://packages.debian.org/changelogs/pool/main/g/gst-plugins-good0.10/current/changelog#versionversion0.10.11-2 done]
|-
| [http://share.skype.com/site/linux Skype] || [https://developer.skype.com/jira/browse/SCL-403 Skype] || bug || bug || not packaged
|-
| [http://blogs.adobe.com/penguin.swf/ Adobe Flash] || Contacted Mike via email (philips) || bug || bug || not packaged
|-
| [http://dvr.sourceforge.net DVR] || bug || bug || bug || bug
|-
| [http://www.opalvoip.org/wiki/index.php?n=Main.Subversion PTLib/Ekiga] || [http://bugzilla.gnome.org/show_bug.cgi?id=545108 bug] [https://opalvoip.svn.sourceforge.net/svnroot/opalvoip/ptlib/trunk/ ptlib svn] r20635, fixed in ptlib 2.4.2 || [https://bugzilla.redhat.com/show_bug.cgi?id=456868 bug] || bug || bug
|-
| [http://ffmpeg.sourceforge.net/index.php ffmpeg] || bug || bug || bug || bug
|-
| [http://fftv.sourceforge.net fftv] || bug || bug || bug || bug
|-
| [http://xawdecode.sourceforge.net/ XdTV] || bug || bug || bug || bug
|-
| [http://freevo.sourceforge.net Freevo] || bug || bug || bug || bug
|-
| [[MEncoder]] || bug || bug || bug || bug
|-
| [[streamer]] || See xawtv || NA || NA || NA
|-
| [[transcode]] || bug || bug || bug || not packaged
|-
| [http://paginas.terra.com.br/informatica/gleicon/video4linux/videodog.html videodog] || bug || bug || bug || not packaged
|-
| [http://www.kdetv.org kdetv] || bug || bug || bug || bug
|-
| [http://www.mplayerhq.hu MPlayer] || bug || bug || bug || bug
|-
| [http://tvtime.sourceforge.net tvtime] || bug || bug || bug || bug
|-
| [http://www.videolan.org/vlc/ VLC] || [https://trac.videolan.org/vlc/ticket/1804 bug] fixed upstream, version 0.9.5 || bug || bug || bug
|-
| [http://linux.bytesex.org/xawtv/ xawtv and motv] || Upstream is dead, see Fedora bug link || [https://bugzilla.redhat.com/show_bug.cgi?id=457796 bug] || bug || bug
|-
| [http://xinehq.de xine] || bug || bug || bug || bug
|-
| [http://zapping.sourceforge.net zapping] || bug || bug || bug || bug
|-
| [http://www.videolan.org/vlc/streaming.html VideoLan] || bug || bug || bug || bug
|-
| [http://ffmpeg.mplayerhq.hu/ffserver-doc.html ffserver] || bug || bug || bug || bug
|-
| [http://mpeg4ip.sourceforge.net MPEG4IP] || bug || bug || bug || not packaged
|-
| [http://developer.apple.com/darwin/projects/streaming Darwin streaming server] || bug || bug || bug || not packaged
|-
| [http://www.litech.org/spook spook] || bug || bug || bug || not packaged
|-
| [http://www.flumotion.net Flumotion] || see GStreamer || NA || NA || NA
|-
| [[MythTV]] || bug || bug || bug || bug
|-
| camE || bug || [http://cvs.fedoraproject.org/viewvc/devel/camE/camE-1.9-libv4l1.patch?revision=1.1 patch] || bug || [http://bugs.debian.org/569095 bug]
|-
| camstream || bug || [http://cvs.fedoraproject.org/viewvc/devel/camstream/camstream-0.26.3-libv4l.patch?revision=1.1 patch] || bug || [http://bugs.debian.org/569090 bug]
|-
| gyachi || bug || [http://cvs.fedoraproject.org/viewvc/devel/gyachi/gyachi-1.1.46-libv4l.patch?revision=1.1 patch] || bug || not packaged
|-
| sane-v4l || bug || bug || bug || bug
|-
| unicap/ucview || Patch in latest upstream release needs ./configure argument to enable || bug || bug || bug
|-
| amsn || Patch in upstream svn || bug || bug || bug
|-
| [http://www.winehq.org Wine] || [http://bugs.winehq.org/show_bug.cgi?id=16147 Bug 16147] || bug || bug || bug
|}
[[Category:Development]]

Libv4l Progress

2010-10-24T16:35:22Z

Mauro Carvalho Chehab:

Progress of applications that are in need of libv4l2 conversion.

{| class="wikitable sortable"
|+'''A sortable list of applications that are in need of libv4l2 conversion'''
|-
! application !! upstream !! fedora !! suse !! debian
|-
| v4l-utils (includes libv4l) || - || available || [http://software.opensuse.org/search?q=v4l-utils&baseproject=openSUSE%3A11.3 available] || [http://packages.qa.debian.org/v/v4l-utils.html available]
|-
| [http://gstreamer.net GStreamer] || [http://bugzilla.gnome.org/show_bug.cgi?id=545033 bug] || [https://bugzilla.redhat.com/show_bug.cgi?id=456825 bug] || bug || [http://packages.debian.org/changelogs/pool/main/g/gst-plugins-good0.10/current/changelog#versionversion0.10.11-2 done]
|-
| [http://share.skype.com/site/linux Skype] || [https://developer.skype.com/jira/browse/SCL-403 Skype] || bug || bug || not packaged
|-
| [http://blogs.adobe.com/penguin.swf/ Adobe Flash] || Contacted Mike via email (philips) || bug || bug || not packaged
|-
| [http://dvr.sourceforge.net DVR] || bug || bug || bug || bug
|-
| [http://www.opalvoip.org/wiki/index.php?n=Main.Subversion PTLib/Ekiga] || [http://bugzilla.gnome.org/show_bug.cgi?id=545108 bug] [https://opalvoip.svn.sourceforge.net/svnroot/opalvoip/ptlib/trunk/ ptlib svn] r20635, fixed in ptlib 2.4.2 || [https://bugzilla.redhat.com/show_bug.cgi?id=456868 bug] || bug || bug
|-
| [http://ffmpeg.sourceforge.net/index.php ffmpeg] || bug || bug || bug || bug
|-
| [http://fftv.sourceforge.net fftv] || bug || bug || bug || bug
|-
| [http://xawdecode.sourceforge.net/ XdTV] || bug || bug || bug || bug
|-
| [http://freevo.sourceforge.net Freevo] || bug || bug || bug || bug
|-
| [[MEncoder]] || bug || bug || bug || bug
|-
| [[streamer]] || See xawtv || NA || NA || NA
|-
| [[transcode]] || bug || bug || bug || not packaged
|-
| [http://paginas.terra.com.br/informatica/gleicon/video4linux/videodog.html videodog] || bug || bug || bug || not packaged
|-
| [http://www.kdetv.org kdetv] || bug || bug || bug || bug
|-
| [http://www.mplayerhq.hu MPlayer] || bug || bug || bug || bug
|-
| [http://tvtime.sourceforge.net tvtime] || bug || bug || bug || bug
|-
| [http://www.videolan.org/vlc/ VLC] || [https://trac.videolan.org/vlc/ticket/1804 bug] fixed upstream, version 0.9.5 || bug || bug || bug
|-
| [http://linux.bytesex.org/xawtv/ xawtv and motv] || Upstream is dead, see Fedora bug link || [https://bugzilla.redhat.com/show_bug.cgi?id=457796 bug] || bug || bug
|-
| [http://xinehq.de xine] || bug || bug || bug || bug
|-
| [http://zapping.sourceforge.net zapping] || bug || bug || bug || bug
|-
| [http://www.videolan.org/vlc/streaming.html VideoLan] || bug || bug || bug || bug
|-
| [http://ffmpeg.mplayerhq.hu/ffserver-doc.html ffserver] || bug || bug || bug || bug
|-
| [http://mpeg4ip.sourceforge.net MPEG4IP] || bug || bug || bug || not packaged
|-
| [http://developer.apple.com/darwin/projects/streaming Darwin streaming server] || bug || bug || bug || not packaged
|-
| [http://www.litech.org/spook spook] || bug || bug || bug || not packaged
|-
| [http://www.flumotion.net Flumotion] || see GStreamer || NA || NA || NA
|-
| [[MythTV]] || bug || bug || bug || bug
|-
| camE || bug || [http://cvs.fedoraproject.org/viewvc/devel/camE/camE-1.9-libv4l1.patch?revision=1.1 patch] || bug || [http://bugs.debian.org/569095 bug]
|-
| camstream || bug || [http://cvs.fedoraproject.org/viewvc/devel/camstream/camstream-0.26.3-libv4l.patch?revision=1.1 patch] || bug || [http://bugs.debian.org/569090 bug]
|-
| gyachi || bug || [http://cvs.fedoraproject.org/viewvc/devel/gyachi/gyachi-1.1.46-libv4l.patch?revision=1.1 patch] || bug || not packaged
|-
| sane-v4l || bug || bug || bug || bug
|-
| unicap/ucview || Patch in latest upstream release needs ./configure argument to enable || bug || bug || bug
|-
| amsn || Patch in upstream svn || bug || bug || bug
|-
| [http://www.winehq.org Wine] || [http://bugs.winehq.org/show_bug.cgi?id=16147 Bug 16147] || bug || bug || bug
|}
[[Category:Development]]

Libv4l Progress

2010-10-24T16:34:52Z

Mauro Carvalho Chehab:

Progress of applications that are in need of libv4l2 conversion.

{| class="wikitable sortable"
|+'''A sortable list of applications that are in need of libv4l2 conversion'''
|-
! application !! upstream !! fedora !! suse !! debian
|-
| v4l-utils (includes libv4l) || - || available || in factory soon, [http://software.opensuse.org/search?q=v4l-utils&baseproject=openSUSE%3A11.3 available] || [http://packages.qa.debian.org/v/v4l-utils.html available]
|-
| [http://gstreamer.net GStreamer] || [http://bugzilla.gnome.org/show_bug.cgi?id=545033 bug] || [https://bugzilla.redhat.com/show_bug.cgi?id=456825 bug] || bug || [http://packages.debian.org/changelogs/pool/main/g/gst-plugins-good0.10/current/changelog#versionversion0.10.11-2 done]
|-
| [http://share.skype.com/site/linux Skype] || [https://developer.skype.com/jira/browse/SCL-403 Skype] || bug || bug || not packaged
|-
| [http://blogs.adobe.com/penguin.swf/ Adobe Flash] || Contacted Mike via email (philips) || bug || bug || not packaged
|-
| [http://dvr.sourceforge.net DVR] || bug || bug || bug || bug
|-
| [http://www.opalvoip.org/wiki/index.php?n=Main.Subversion PTLib/Ekiga] || [http://bugzilla.gnome.org/show_bug.cgi?id=545108 bug] [https://opalvoip.svn.sourceforge.net/svnroot/opalvoip/ptlib/trunk/ ptlib svn] r20635, fixed in ptlib 2.4.2 || [https://bugzilla.redhat.com/show_bug.cgi?id=456868 bug] || bug || bug
|-
| [http://ffmpeg.sourceforge.net/index.php ffmpeg] || bug || bug || bug || bug
|-
| [http://fftv.sourceforge.net fftv] || bug || bug || bug || bug
|-
| [http://xawdecode.sourceforge.net/ XdTV] || bug || bug || bug || bug
|-
| [http://freevo.sourceforge.net Freevo] || bug || bug || bug || bug
|-
| [[MEncoder]] || bug || bug || bug || bug
|-
| [[streamer]] || See xawtv || NA || NA || NA
|-
| [[transcode]] || bug || bug || bug || not packaged
|-
| [http://paginas.terra.com.br/informatica/gleicon/video4linux/videodog.html videodog] || bug || bug || bug || not packaged
|-
| [http://www.kdetv.org kdetv] || bug || bug || bug || bug
|-
| [http://www.mplayerhq.hu MPlayer] || bug || bug || bug || bug
|-
| [http://tvtime.sourceforge.net tvtime] || bug || bug || bug || bug
|-
| [http://www.videolan.org/vlc/ VLC] || [https://trac.videolan.org/vlc/ticket/1804 bug] fixed upstream, version 0.9.5 || bug || bug || bug
|-
| [http://linux.bytesex.org/xawtv/ xawtv and motv] || Upstream is dead, see Fedora bug link || [https://bugzilla.redhat.com/show_bug.cgi?id=457796 bug] || bug || bug
|-
| [http://xinehq.de xine] || bug || bug || bug || bug
|-
| [http://zapping.sourceforge.net zapping] || bug || bug || bug || bug
|-
| [http://www.videolan.org/vlc/streaming.html VideoLan] || bug || bug || bug || bug
|-
| [http://ffmpeg.mplayerhq.hu/ffserver-doc.html ffserver] || bug || bug || bug || bug
|-
| [http://mpeg4ip.sourceforge.net MPEG4IP] || bug || bug || bug || not packaged
|-
| [http://developer.apple.com/darwin/projects/streaming Darwin streaming server] || bug || bug || bug || not packaged
|-
| [http://www.litech.org/spook spook] || bug || bug || bug || not packaged
|-
| [http://www.flumotion.net Flumotion] || see GStreamer || NA || NA || NA
|-
| [[MythTV]] || bug || bug || bug || bug
|-
| camE || bug || [http://cvs.fedoraproject.org/viewvc/devel/camE/camE-1.9-libv4l1.patch?revision=1.1 patch] || bug || [http://bugs.debian.org/569095 bug]
|-
| camstream || bug || [http://cvs.fedoraproject.org/viewvc/devel/camstream/camstream-0.26.3-libv4l.patch?revision=1.1 patch] || bug || [http://bugs.debian.org/569090 bug]
|-
| gyachi || bug || [http://cvs.fedoraproject.org/viewvc/devel/gyachi/gyachi-1.1.46-libv4l.patch?revision=1.1 patch] || bug || not packaged
|-
| sane-v4l || bug || bug || bug || bug
|-
| unicap/ucview || Patch in latest upstream release needs ./configure argument to enable || bug || bug || bug
|-
| amsn || Patch in upstream svn || bug || bug || bug
|-
| [http://www.winehq.org Wine] || [http://bugs.winehq.org/show_bug.cgi?id=16147 Bug 16147] || bug || bug || bug
|}
[[Category:Development]]

Libv4l Progress

2010-10-24T16:29:34Z

Mauro Carvalho Chehab:

Progress of applications that are in need of libv4l2 conversion.

{| class="wikitable sortable"
|+'''A sortable list of applications that are in need of libv4l2 conversion'''
|-
! application !! upstream !! fedora !! suse !! debian
|-
| libv4l || - || available || in factory soon, [http://software.opensuse.org/search?q=libv4l 1-Clicks] || [http://packages.qa.debian.org/v/v4l-utils.html available]
|-
| [http://gstreamer.net GStreamer] || [http://bugzilla.gnome.org/show_bug.cgi?id=545033 bug] || [https://bugzilla.redhat.com/show_bug.cgi?id=456825 bug] || bug || [http://packages.debian.org/changelogs/pool/main/g/gst-plugins-good0.10/current/changelog#versionversion0.10.11-2 done]
|-
| [http://share.skype.com/site/linux Skype] || [https://developer.skype.com/jira/browse/SCL-403 Skype] || bug || bug || not packaged
|-
| [http://blogs.adobe.com/penguin.swf/ Adobe Flash] || Contacted Mike via email (philips) || bug || bug || not packaged
|-
| [http://dvr.sourceforge.net DVR] || bug || bug || bug || bug
|-
| [http://www.opalvoip.org/wiki/index.php?n=Main.Subversion PTLib/Ekiga] || [http://bugzilla.gnome.org/show_bug.cgi?id=545108 bug] [https://opalvoip.svn.sourceforge.net/svnroot/opalvoip/ptlib/trunk/ ptlib svn] r20635, fixed in ptlib 2.4.2 || [https://bugzilla.redhat.com/show_bug.cgi?id=456868 bug] || bug || bug
|-
| [http://ffmpeg.sourceforge.net/index.php ffmpeg] || bug || bug || bug || bug
|-
| [http://fftv.sourceforge.net fftv] || bug || bug || bug || bug
|-
| [http://xawdecode.sourceforge.net/ XdTV] || bug || bug || bug || bug
|-
| [http://freevo.sourceforge.net Freevo] || bug || bug || bug || bug
|-
| [[MEncoder]] || bug || bug || bug || bug
|-
| [[streamer]] || See xawtv || NA || NA || NA
|-
| [[transcode]] || bug || bug || bug || not packaged
|-
| [http://paginas.terra.com.br/informatica/gleicon/video4linux/videodog.html videodog] || bug || bug || bug || not packaged
|-
| [http://www.kdetv.org kdetv] || bug || bug || bug || bug
|-
| [http://www.mplayerhq.hu MPlayer] || bug || bug || bug || bug
|-
| [http://tvtime.sourceforge.net tvtime] || bug || bug || bug || bug
|-
| [http://www.videolan.org/vlc/ VLC] || [https://trac.videolan.org/vlc/ticket/1804 bug] fixed upstream, version 0.9.5 || bug || bug || bug
|-
| [http://linux.bytesex.org/xawtv/ xawtv and motv] || Upstream is dead, see Fedora bug link || [https://bugzilla.redhat.com/show_bug.cgi?id=457796 bug] || bug || bug
|-
| [http://xinehq.de xine] || bug || bug || bug || bug
|-
| [http://zapping.sourceforge.net zapping] || bug || bug || bug || bug
|-
| [http://www.videolan.org/vlc/streaming.html VideoLan] || bug || bug || bug || bug
|-
| [http://ffmpeg.mplayerhq.hu/ffserver-doc.html ffserver] || bug || bug || bug || bug
|-
| [http://mpeg4ip.sourceforge.net MPEG4IP] || bug || bug || bug || not packaged
|-
| [http://developer.apple.com/darwin/projects/streaming Darwin streaming server] || bug || bug || bug || not packaged
|-
| [http://www.litech.org/spook spook] || bug || bug || bug || not packaged
|-
| [http://www.flumotion.net Flumotion] || see GStreamer || NA || NA || NA
|-
| [[MythTV]] || bug || bug || bug || bug
|-
| camE || bug || [http://cvs.fedoraproject.org/viewvc/devel/camE/camE-1.9-libv4l1.patch?revision=1.1 patch] || bug || [http://bugs.debian.org/569095 bug]
|-
| camstream || bug || [http://cvs.fedoraproject.org/viewvc/devel/camstream/camstream-0.26.3-libv4l.patch?revision=1.1 patch] || bug || [http://bugs.debian.org/569090 bug]
|-
| gyachi || bug || [http://cvs.fedoraproject.org/viewvc/devel/gyachi/gyachi-1.1.46-libv4l.patch?revision=1.1 patch] || bug || not packaged
|-
| sane-v4l || bug || bug || bug || bug
|-
| unicap/ucview || Patch in latest upstream release needs ./configure argument to enable || bug || bug || bug
|-
| amsn || Patch in upstream svn || bug || bug || bug
|-
| [http://www.winehq.org Wine] || [http://bugs.winehq.org/show_bug.cgi?id=16147 Bug 16147] || bug || bug || bug
|}
[[Category:Development]]

Remote Controllers

2010-05-12T18:57:36Z

Mauro Carvalho Chehab: /* Adding support for new IR's */

Currently, most analog and digital devices have an Infrared input for a remote control. Each manufacturer has their own type of control. It is not uncommon for the same manufacturer to ship different types of remote controls, depending on the device.

===Adding support for new IR's===

In order to add support for a new keyboard, you need first to discover how the IR code is sent to the device. There are several possibilities:
* IR sensor is directly connected with a GPIO pin of the PCI/USB bridge. This is a very common case nowadays.
* This is probably the easiest way to add support, provided that the driver has already other similar devices. For an example, please see: [[add IR support for saa7134]].
* Bridge has an IR decoder inside. Some chipsets have already some internal decoder for IR, like dib0700 and em2884;
* There's a small chip that does serial to parallel conversion, outputting the IR code at several GPIO pins.

The way to get the data is hardware specific. Once the driver is able to get an IR scancode, it is generally required to create a new table for it.
NOTE: before adding a new table, please check if the existing ones have already the proper mapping.

The first step to add a new map is to create an alias for it atinclude/media/rc-map.h:

/* Names of the several keytables defined in-kernel */

#define RC_MAP_ADSTECH_DVB_T_PCI "rc-adstech-dvb-t-pci"
...
#define RC_MAP_VIDEOMATE_TV_PVR "rc-videomate-tv-pvr"
#define RC_MAP_WINFAST "rc-winfast"
#define RC_MAP_WINFAST_USBII_DELUXE "rc-winfast-usbii-deluxe"
/*
* Please, do not just append newer Remote Controller names at the end.
* The names should be ordered in alphabetical order
*/

Just add a new line there with the IR name, on alphabetical order:
#define RC_MAP_NAME_OF_MY_NEW_BOARD_MAP "rc-name-of-my-new-board-map"

Then copy one of the existing keymaps, for example, drivers/media/IR/keymaps/rc-empty.c,
replacing the names for the name of your new IR.

Remove all keys at static struct ir_scancode, and add your new keycodes.

For example, assuming that you have a driver with raw decode. By loading ir_core with debug=1, with:
modprobe ir_core debug=1
(be sure that ir_core weren't loaded before)
you'll start to generate lots of logs at the syslog. Use the dmesg command to get those codes:
dmesg |grep scancode

Let's assume that this get you the following results:
for power key:
ir_nec_decode: NEC scancode 0x0300
ir_getkeycode: unknown key for scancode 0x0300
for channel up key:
ir_nec_decode: NEC scancode 0x030c
ir_getkeycode: unknown key for scancode 0x030c
for channel down key:
ir_nec_decode: NEC scancode 0x0310
ir_getkeycode: unknown key for scancode 0x0310

All you need to do is to make sure that those codes are properly mapped at the keycode table, and to specify
the ir_type (in this case, IR_TYPE_NEC). So, to support the above, the main content of the new rc map will be:

static struct ir_scancode name_of_my_new_keyboard[] = {
{ 0x0300, KEY_POWER2 },
{ 0x030c, KEY_CHANNELUP },
{ 0x0310, KEY_CHANNELDOWN },
};
static struct rc_keymap name_of_my_new_keyboard_map = {
.map = {
.scan = name_of_my_new_keyboard,
.size = ARRAY_SIZE(name_of_my_new_keyboard),
.ir_type = IR_TYPE_NEC,
.name = RC_MAP_EMPTY,
}
};

Don't forget to add the new module at drivers/media/IR/keymaps/Makefile, otherwise, it won't be built.

===IR Keycode map used by media devices===

While there has been effort over the years to keep track of the varying IR layouts (documenting them within ir-common.c), unfortunately, there was never any effort to uniform the actual IR keycodes used by the different devices. This lack of uniformity resulted in cases where the same IR keyname was mapped completely different on different IR's. The overall state of confusion that existed is perhaps best demonstrated by viewing what [[ir-common.c]] IR summary looked like as of Aug, 26 2009.

On Aug, 27 2009, having a common mapping for supported IR's became the subject of a [[Development: A proposal for a common IR keycode definition map|proposal]] which would allow userspace applications to make use of common keycode definitions. The table bellow reflects the expected keycode mappings for IR keys.

{| border="1" cellpadding="2"
!Key code
!Meaning
!Key examples on IR
!Notes
|- style= "font-weight: bolder; color: blue"
| Numeric keys
|-
|KEY_0 || Keyboard digit 0 || 0
|-
|KEY_1 || Keyboard digit 1 || 1
|-
|KEY_2 || Keyboard digit 2 || 2
|-
|KEY_3 || Keyboard digit 3 || 3
|-
|KEY_4 || Keyboard digit 4 || 4
|-
|KEY_5 || Keyboard digit 5 || 5
|-
|KEY_6 || Keyboard digit 6 || 6
|-
|KEY_7 || Keyboard digit 7 || 7
|-
|KEY_8 || Keyboard digit 8 || 8
|-
|KEY_9 || Keyboard digit 9 || 9
|- style= "font-weight: bolder; color: blue"
| Movie play control
|-
|KEY_FORWARD || Instantly advance in time || >> / FORWARD
|-
|KEY_BACK || Instantly go back in time || <<< / BACK
|-
|KEY_FASTFORWARD || Play movie faster || >>> / FORWARD
|-
|KEY_REWIND || Play movie back || REWIND / BACKWARD
|-
|KEY_NEXT || Select next chapter / sub-chapter / interval || NEXT / SKIP
|-
|KEY_PREVIOUS || Select previous chapter / sub-chapter / interval || BACK / |<< / PREV / PREVIOUS
|-
|KEY_AGAIN || Repeat the video or a video interval || REPEAT / LOOP / RECALL
|-
|KEY_PAUSE || Pause stream || PAUSE / FREEZE
|-
|KEY_PLAY || Play movie at the normal timeshift || NORMAL TIMESHIFT / LIVE / >
|-
|KEY_PLAYPAUSE || Alternate between play and pause || PLAY / PAUSE
|-
|KEY_STOP || Stop stream || STOP
|-
|KEY_RECORD || Start/stop recording stream || CAPTURE / REC / RECORD/PAUSE
|-
|KEY_CAMERA || Take a picture of the image || CAMERA ICON / CAPTURE / SNAPSHOT
|-
|KEY_SHUFFLE || Enable shuffle mode || SHUFFLE
|-
|KEY_TIME || Activate time shift mode || TIME SHIFT
|-
|KEY_TITLE || Allow changing the chapter || CHAPTER
|-
|KEY_SUBTITLE || Allow changing the subtitle || SUBTITLE
|-
|- style= "font-weight: bolder; color: blue"
| Image control
|-
|KEY_BRIGHTNESSDOWN || Decrease Brightness || BRIGHTNESS DECREASE
|-
|KEY_BRIGHTNESSUP || Increase Brightness || BRIGHTNESS INCREASE
|-
|KEY_ANGLE || Switch video camera angle (on videos with more than one angle stored) || ANGLE / SWAP
|-
|KEY_EPG || Open the Electronic Play Guide (EPG) || EPG / GUIDE
|-
|KEY_TEXT || Activate/change closed caption mode || CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX
|-
|- style= "font-weight: bolder; color: blue"
| Audio control
|-
|KEY_AUDIO || Change audio source || AUDIO SOURCE / AUDIO / MUSIC
|-
|KEY_MUTE || Mute/unmute audio || MUTE / DEMUTE / UNMUTE
|-
|KEY_VOLUMEDOWN || Decrease volume || VOLUME- / VOLUME DOWN
|-
|KEY_VOLUMEUP || Increase volume || VOLUME+ / VOLUME UP
|-
|KEY_MODE || Change sound mode || MONO/STEREO
|-
|KEY_LANGUAGE || Select Language || 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL
|-
|- style= "font-weight: bolder; color: blue"
| Channel control
|-
|KEY_CHANNEL || Go to the next favorite channel || ALT / CHANNEL / CH SURFING / SURF / FAV
|-
|KEY_CHANNELDOWN || Decrease channel sequencially || CHANNEL - / CHANNEL DOWN / DOWN
|-
|KEY_CHANNELUP || Increase channel sequencially || CHANNEL + / CHANNEL UP / UP
|-
|KEY_DIGITS || Use more than one digit for channel || PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit
|-
|KEY_SEARCH || Start channel autoscan || SCAN / AUTOSCAN
|-
|- style= "font-weight: bolder; color: blue"
| Colored keys
|-
|KEY_BLUE || IR “Blue” key
|style= "color: blue" | BLUE
|-
|KEY_GREEN || IR “Green” Key
|style= "color: green" | GREEN
|-
|KEY_RED || IR “Red” key
|style= "color: red" | RED
|-
|KEY_YELLOW || IR “Yellow” key
|style= "color: yellow" | YELLOW
|-
|- style= "font-weight: bolder; color: blue"
| Media selection
|-
|KEY_CD || Change input source to Compact Disc || CD
|-
|KEY_DVD || Change input to DVD || DVD / DVD MENU
|-
|KEY_EJECTCLOSECD || Open/close the CD/DVD player || -> ) / CLOSE / OPEN
|-
|KEY_MEDIA || Turn on/off Media application || PC/TV / TURN ON/OFF APP
|-
|KEY_PC || Selects from TV to PC || PC
|-
|KEY_RADIO || Put into AM/FM radio mode || RADIO / TV/FM / TV/RADIO / FM / FM/RADIO
|-
|KEY_TV || Select tv mode || TV / LIVE TV
|-
|KEY_TV2 || Select Cable mode || AIR/CBL
|-
|KEY_VCR || Select VCR mode || VCR MODE / DTR
|-
|KEY_VIDEO || Alternate between input modes || SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO
|-
|- style= "font-weight: bolder; color: blue"
| Power control
|-
|KEY_POWER || Turn on/off computer || SYSTEM POWER / COMPUTER POWER
|-
|KEY_POWER2 || Turn on/off application || TV ON/OFF / POWER
|-
|KEY_SLEEP || Activate sleep timer || SLEEP / SLEEP TIMER
|-
|KEY_SUSPEND || Put computer into suspend mode || STANDBY / SUSPEND
|-
|- style= "font-weight: bolder; color: blue"
| Window control
|-
|KEY_CLEAR || Stop stream and return to default input video/audio || CLEAR / RESET / BOSS KEY
|-
|KEY_CYCLEWINDOWS || Minimize windows and move to the next one || ALT-TAB / MINIMIZE / DESKTOP
|-
|KEY_FAVORITES || Open the favorites stream window || TV WALL / Favorites
|-
|KEY_MENU || Call application menu || 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL
|-
|KEY_NEW || Open/Close Picture in Picture || PIP
|-
|KEY_OK || Send a confirmation code to application || OK / ENTER / RETURN
|-
|KEY_SCREEN || Select screen aspect ratio || 4:3 16:9 SELECT
|-
|KEY_ZOOM || Put device into zoom/full screen mode || ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH
|-
|- style= "font-weight: bolder; color: blue"
| Navigation keys
|-
|KEY_ESC || Cancel current operation || CANCEL / BACK
|-
|KEY_HELP || Open a Help window || HELP
|-
|KEY_HOMEPAGE || Navigate to Homepage || HOME
|-
|KEY_INFO || Open On Screen Display || DISPLAY INFORMATION / OSD
|-
|KEY_WWW || Open the default browser || WEB
|-
|KEY_UP || Up key || UP || On simpler IR's, without separate channel keys, you need to map UP as KEY_CHANNELUP
|-
|KEY_DOWN || Down key || DOWN || On simpler IR's, without separate channel keys, you need to map DOWN as KEY_CHANNELDOWN
|-
|KEY_LEFT || Left key || LEFT || On simpler IR's, without separate volume keys, you need to map LEFT as KEY_VOLUMEDOWN
|-
|KEY_RIGHT || Right key || RIGHT || On simpler IR's, without separate volume keys, you need to map RIGHT as KEY_VOLUMEUP
|-
|- style= "font-weight: bolder; color: blue"
| Miscelaneous keys
|-
|KEY_DOT || Return a dot || .
|-
|KEY_FN || Select a function || FUNCTION
|}

===Technical details about IR===
http://linuxtv.org/wiki/index.php/Remote_controllers-V4L

[[Category:Hardware]]

Add IR support for saa7134

2010-05-12T18:56:19Z

Mauro Carvalho Chehab: Created page with 'Saa7134 was the first driver to support the new ir core raw input event infrastructure. As such, it is very easy to add there support for any new IR that uses GPIO18 or GPIO16 to...'

Saa7134 was the first driver to support the new ir core raw input event infrastructure. As such, it is very
easy to add there support for any new IR that uses GPIO18 or GPIO16 to receive raw pulse/space events.

In order to add support for a new board called SAA7134_BOARD_FOO, you just need to add:

For GPIO18:
case SAA7134_BOARD_FOO:
ir_codes = RC_MAP_FOO;
mask_keydown = 0x0040000;
mask_keyup = 0x0040000;
mask_keycode = 0xffff;
raw_decode = 1;
break;

For GPIO16, the mask_kewdown and mask_keyup should be 0x10000. However, a small trivial 2 line change at
saa7134_hw_enable2() is required, in order to enable both positive and negative IRQ transitions.
This change weren't done yet, since we lack the need for it currently.

Remote Controllers

2010-05-12T18:46:45Z

Mauro Carvalho Chehab: /* Adding support for new IR's */

Currently, most analog and digital devices have an Infrared input for a remote control. Each manufacturer has their own type of control. It is not uncommon for the same manufacturer to ship different types of remote controls, depending on the device.

===Adding support for new IR's===

In order to add support for a new keyboard, you need first to discover how the IR code is sent to the device. There are several possibilities:
* IR sensor is directly connected with a GPIO pin of the PCI/USB bridge. This is a very common case nowadays.
* This is probably the easiest way to add support, provided that the driver has already other similar devices. For an example, please see: [[add IR support for saa7134]].
* Bridge has an IR decoder inside. Some chipsets have already some internal decoder for IR, like dib0700 and em2884;
* There's a small chip that does serial to parallel conversion, outputting the IR code at several GPIO pins.

The way to get the data is hardware specific. Once the driver is able to get an IR scancode, it is generally required to create a new table for it.
NOTE: before adding a new table, please check if the existing ones have already the proper mapping.

The first step to add a new map is to create an alias for it atinclude/media/rc-map.h:

/* Names of the several keytables defined in-kernel */

#define RC_MAP_ADSTECH_DVB_T_PCI "rc-adstech-dvb-t-pci"
...
#define RC_MAP_VIDEOMATE_TV_PVR "rc-videomate-tv-pvr"
#define RC_MAP_WINFAST "rc-winfast"
#define RC_MAP_WINFAST_USBII_DELUXE "rc-winfast-usbii-deluxe"
/*
* Please, do not just append newer Remote Controller names at the end.
* The names should be ordered in alphabetical order
*/

Just add a new line there with the IR name, on alphabetical order:
#define RC_MAP_NAME_OF_MY_NEW_BOARD_MAP "rc-name-of-my-new-board-map"

Then copy one of the existing keymaps, for example, drivers/media/IR/keymaps/rc-empty.c,
replacing the names for the name of your new IR.

Remove all keys at static struct ir_scancode, and add your new keycodes.

For example, assuming that you have a driver with raw decode. By loading ir_core with debug=1, with:
modprobe ir_core debug=1
(be sure that ir_core weren't loaded before)
you'll start to generate lots of logs at the syslog. Use the dmesg command to get those codes:
dmesg |grep scancode

Let's assume that this get you the following results:
for power key:
ir_nec_decode: NEC scancode 0x0300
ir_getkeycode: unknown key for scancode 0x0300
for channel up key:
ir_nec_decode: NEC scancode 0x030c
ir_getkeycode: unknown key for scancode 0x030c
for channel down key:
ir_nec_decode: NEC scancode 0x0310
ir_getkeycode: unknown key for scancode 0x0310

All you need to do is to make sure that those codes are properly mapped at the keycode table, and to specify
the ir_type (in this case, IR_TYPE_NEC). So, to support the above, the main content of the new rc map will be:

static struct ir_scancode name_of_my_new_keyboard[] = {
{ 0x0300, KEY_POWER2 },
{ 0x030c, KEY_CHANNELUP },
{ 0x0310, KEY_CHANNELDOWN },
};
static struct rc_keymap name_of_my_new_keyboard_map = {
.map = {
.scan = name_of_my_new_keyboard,
.size = ARRAY_SIZE(name_of_my_new_keyboard),
.ir_type = IR_TYPE_NEC,
.name = RC_MAP_EMPTY,
}
};

===IR Keycode map used by media devices===

While there has been effort over the years to keep track of the varying IR layouts (documenting them within ir-common.c), unfortunately, there was never any effort to uniform the actual IR keycodes used by the different devices. This lack of uniformity resulted in cases where the same IR keyname was mapped completely different on different IR's. The overall state of confusion that existed is perhaps best demonstrated by viewing what [[ir-common.c]] IR summary looked like as of Aug, 26 2009.

On Aug, 27 2009, having a common mapping for supported IR's became the subject of a [[Development: A proposal for a common IR keycode definition map|proposal]] which would allow userspace applications to make use of common keycode definitions. The table bellow reflects the expected keycode mappings for IR keys.

{| border="1" cellpadding="2"
!Key code
!Meaning
!Key examples on IR
!Notes
|- style= "font-weight: bolder; color: blue"
| Numeric keys
|-
|KEY_0 || Keyboard digit 0 || 0
|-
|KEY_1 || Keyboard digit 1 || 1
|-
|KEY_2 || Keyboard digit 2 || 2
|-
|KEY_3 || Keyboard digit 3 || 3
|-
|KEY_4 || Keyboard digit 4 || 4
|-
|KEY_5 || Keyboard digit 5 || 5
|-
|KEY_6 || Keyboard digit 6 || 6
|-
|KEY_7 || Keyboard digit 7 || 7
|-
|KEY_8 || Keyboard digit 8 || 8
|-
|KEY_9 || Keyboard digit 9 || 9
|- style= "font-weight: bolder; color: blue"
| Movie play control
|-
|KEY_FORWARD || Instantly advance in time || >> / FORWARD
|-
|KEY_BACK || Instantly go back in time || <<< / BACK
|-
|KEY_FASTFORWARD || Play movie faster || >>> / FORWARD
|-
|KEY_REWIND || Play movie back || REWIND / BACKWARD
|-
|KEY_NEXT || Select next chapter / sub-chapter / interval || NEXT / SKIP
|-
|KEY_PREVIOUS || Select previous chapter / sub-chapter / interval || BACK / |<< / PREV / PREVIOUS
|-
|KEY_AGAIN || Repeat the video or a video interval || REPEAT / LOOP / RECALL
|-
|KEY_PAUSE || Pause stream || PAUSE / FREEZE
|-
|KEY_PLAY || Play movie at the normal timeshift || NORMAL TIMESHIFT / LIVE / >
|-
|KEY_PLAYPAUSE || Alternate between play and pause || PLAY / PAUSE
|-
|KEY_STOP || Stop stream || STOP
|-
|KEY_RECORD || Start/stop recording stream || CAPTURE / REC / RECORD/PAUSE
|-
|KEY_CAMERA || Take a picture of the image || CAMERA ICON / CAPTURE / SNAPSHOT
|-
|KEY_SHUFFLE || Enable shuffle mode || SHUFFLE
|-
|KEY_TIME || Activate time shift mode || TIME SHIFT
|-
|KEY_TITLE || Allow changing the chapter || CHAPTER
|-
|KEY_SUBTITLE || Allow changing the subtitle || SUBTITLE
|-
|- style= "font-weight: bolder; color: blue"
| Image control
|-
|KEY_BRIGHTNESSDOWN || Decrease Brightness || BRIGHTNESS DECREASE
|-
|KEY_BRIGHTNESSUP || Increase Brightness || BRIGHTNESS INCREASE
|-
|KEY_ANGLE || Switch video camera angle (on videos with more than one angle stored) || ANGLE / SWAP
|-
|KEY_EPG || Open the Electronic Play Guide (EPG) || EPG / GUIDE
|-
|KEY_TEXT || Activate/change closed caption mode || CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX
|-
|- style= "font-weight: bolder; color: blue"
| Audio control
|-
|KEY_AUDIO || Change audio source || AUDIO SOURCE / AUDIO / MUSIC
|-
|KEY_MUTE || Mute/unmute audio || MUTE / DEMUTE / UNMUTE
|-
|KEY_VOLUMEDOWN || Decrease volume || VOLUME- / VOLUME DOWN
|-
|KEY_VOLUMEUP || Increase volume || VOLUME+ / VOLUME UP
|-
|KEY_MODE || Change sound mode || MONO/STEREO
|-
|KEY_LANGUAGE || Select Language || 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL
|-
|- style= "font-weight: bolder; color: blue"
| Channel control
|-
|KEY_CHANNEL || Go to the next favorite channel || ALT / CHANNEL / CH SURFING / SURF / FAV
|-
|KEY_CHANNELDOWN || Decrease channel sequencially || CHANNEL - / CHANNEL DOWN / DOWN
|-
|KEY_CHANNELUP || Increase channel sequencially || CHANNEL + / CHANNEL UP / UP
|-
|KEY_DIGITS || Use more than one digit for channel || PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit
|-
|KEY_SEARCH || Start channel autoscan || SCAN / AUTOSCAN
|-
|- style= "font-weight: bolder; color: blue"
| Colored keys
|-
|KEY_BLUE || IR “Blue” key
|style= "color: blue" | BLUE
|-
|KEY_GREEN || IR “Green” Key
|style= "color: green" | GREEN
|-
|KEY_RED || IR “Red” key
|style= "color: red" | RED
|-
|KEY_YELLOW || IR “Yellow” key
|style= "color: yellow" | YELLOW
|-
|- style= "font-weight: bolder; color: blue"
| Media selection
|-
|KEY_CD || Change input source to Compact Disc || CD
|-
|KEY_DVD || Change input to DVD || DVD / DVD MENU
|-
|KEY_EJECTCLOSECD || Open/close the CD/DVD player || -> ) / CLOSE / OPEN
|-
|KEY_MEDIA || Turn on/off Media application || PC/TV / TURN ON/OFF APP
|-
|KEY_PC || Selects from TV to PC || PC
|-
|KEY_RADIO || Put into AM/FM radio mode || RADIO / TV/FM / TV/RADIO / FM / FM/RADIO
|-
|KEY_TV || Select tv mode || TV / LIVE TV
|-
|KEY_TV2 || Select Cable mode || AIR/CBL
|-
|KEY_VCR || Select VCR mode || VCR MODE / DTR
|-
|KEY_VIDEO || Alternate between input modes || SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO
|-
|- style= "font-weight: bolder; color: blue"
| Power control
|-
|KEY_POWER || Turn on/off computer || SYSTEM POWER / COMPUTER POWER
|-
|KEY_POWER2 || Turn on/off application || TV ON/OFF / POWER
|-
|KEY_SLEEP || Activate sleep timer || SLEEP / SLEEP TIMER
|-
|KEY_SUSPEND || Put computer into suspend mode || STANDBY / SUSPEND
|-
|- style= "font-weight: bolder; color: blue"
| Window control
|-
|KEY_CLEAR || Stop stream and return to default input video/audio || CLEAR / RESET / BOSS KEY
|-
|KEY_CYCLEWINDOWS || Minimize windows and move to the next one || ALT-TAB / MINIMIZE / DESKTOP
|-
|KEY_FAVORITES || Open the favorites stream window || TV WALL / Favorites
|-
|KEY_MENU || Call application menu || 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL
|-
|KEY_NEW || Open/Close Picture in Picture || PIP
|-
|KEY_OK || Send a confirmation code to application || OK / ENTER / RETURN
|-
|KEY_SCREEN || Select screen aspect ratio || 4:3 16:9 SELECT
|-
|KEY_ZOOM || Put device into zoom/full screen mode || ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH
|-
|- style= "font-weight: bolder; color: blue"
| Navigation keys
|-
|KEY_ESC || Cancel current operation || CANCEL / BACK
|-
|KEY_HELP || Open a Help window || HELP
|-
|KEY_HOMEPAGE || Navigate to Homepage || HOME
|-
|KEY_INFO || Open On Screen Display || DISPLAY INFORMATION / OSD
|-
|KEY_WWW || Open the default browser || WEB
|-
|KEY_UP || Up key || UP || On simpler IR's, without separate channel keys, you need to map UP as KEY_CHANNELUP
|-
|KEY_DOWN || Down key || DOWN || On simpler IR's, without separate channel keys, you need to map DOWN as KEY_CHANNELDOWN
|-
|KEY_LEFT || Left key || LEFT || On simpler IR's, without separate volume keys, you need to map LEFT as KEY_VOLUMEDOWN
|-
|KEY_RIGHT || Right key || RIGHT || On simpler IR's, without separate volume keys, you need to map RIGHT as KEY_VOLUMEUP
|-
|- style= "font-weight: bolder; color: blue"
| Miscelaneous keys
|-
|KEY_DOT || Return a dot || .
|-
|KEY_FN || Select a function || FUNCTION
|}

===Technical details about IR===
http://linuxtv.org/wiki/index.php/Remote_controllers-V4L

[[Category:Hardware]]

Remote Controllers

2010-05-12T18:45:00Z

Mauro Carvalho Chehab: /* Adding support for new IR's */

Currently, most analog and digital devices have an Infrared input for a remote control. Each manufacturer has their own type of control. It is not uncommon for the same manufacturer to ship different types of remote controls, depending on the device.

===Adding support for new IR's===

In order to add support for a new keyboard, you need first to discover how the IR code is sent to the device. There are several possibilities:
* IR sensor is directly connected with a GPIO pin of the PCI/USB bridge. This is a very common case nowadays.
* This is probably the easiest way to add support, provided that the driver has already other similar devices. For an example, please see: [add IR support for saa7134].
* Bridge has an IR decoder inside. Some chipsets have already some internal decoder for IR, like dib0700 and em2884;
* There's a small chip that does serial to parallel conversion, outputting the IR code at several GPIO pins.

The way to get the data is hardware specific. Once the driver is able to get an IR scancode, it is generally required to create a new table for it.
NOTE: before adding a new table, please check if the existing ones have already the proper mapping.

The first step to add a new map is to create an alias for it atinclude/media/rc-map.h:

/* Names of the several keytables defined in-kernel */

#define RC_MAP_ADSTECH_DVB_T_PCI "rc-adstech-dvb-t-pci"
...
#define RC_MAP_VIDEOMATE_TV_PVR "rc-videomate-tv-pvr"
#define RC_MAP_WINFAST "rc-winfast"
#define RC_MAP_WINFAST_USBII_DELUXE "rc-winfast-usbii-deluxe"
/*
* Please, do not just append newer Remote Controller names at the end.
* The names should be ordered in alphabetical order
*/

Just add a new line there with the IR name, on alphabetical order:
#define RC_MAP_NAME_OF_MY_NEW_BOARD_MAP "rc-name-of-my-new-board-map"

Then copy one of the existing keymaps, for example, drivers/media/IR/keymaps/rc-empty.c,
replacing the names for the name of your new IR.

Remove all keys at static struct ir_scancode, and add your new keycodes.

For example, assuming that you have a driver with raw decode. By loading ir_core with debug=1, with:
modprobe ir_core debug=1
(be sure that ir_core weren't loaded before)
you'll start to generate lots of logs at the syslog. Use the dmesg command to get those codes:
dmesg |grep scancode

Let's assume that this get you the following results:
for power key:
ir_nec_decode: NEC scancode 0x0300
ir_getkeycode: unknown key for scancode 0x0300
for channel up key:
ir_nec_decode: NEC scancode 0x030c
ir_getkeycode: unknown key for scancode 0x030c
for channel down key:
ir_nec_decode: NEC scancode 0x0310
ir_getkeycode: unknown key for scancode 0x0310

All you need to do is to make sure that those codes are properly mapped at the keycode table, and to specify
the ir_type (in this case, IR_TYPE_NEC). So, to support the above, the main content of the new rc map will be:

static struct ir_scancode name_of_my_new_keyboard[] = {
{ 0x300, KEY_POWER2 },
{ 0x30c, KEY_CHANNELUP },
{ 0x310, KEY_CHANNELDOWN },
};
static struct rc_keymap name_of_my_new_keyboard_map = {
.map = {
.scan = name_of_my_new_keyboard,
.size = ARRAY_SIZE(name_of_my_new_keyboard),
.ir_type = IR_TYPE_NEC,
.name = RC_MAP_EMPTY,
}
};

===IR Keycode map used by media devices===

While there has been effort over the years to keep track of the varying IR layouts (documenting them within ir-common.c), unfortunately, there was never any effort to uniform the actual IR keycodes used by the different devices. This lack of uniformity resulted in cases where the same IR keyname was mapped completely different on different IR's. The overall state of confusion that existed is perhaps best demonstrated by viewing what [[ir-common.c]] IR summary looked like as of Aug, 26 2009.

On Aug, 27 2009, having a common mapping for supported IR's became the subject of a [[Development: A proposal for a common IR keycode definition map|proposal]] which would allow userspace applications to make use of common keycode definitions. The table bellow reflects the expected keycode mappings for IR keys.

{| border="1" cellpadding="2"
!Key code
!Meaning
!Key examples on IR
!Notes
|- style= "font-weight: bolder; color: blue"
| Numeric keys
|-
|KEY_0 || Keyboard digit 0 || 0
|-
|KEY_1 || Keyboard digit 1 || 1
|-
|KEY_2 || Keyboard digit 2 || 2
|-
|KEY_3 || Keyboard digit 3 || 3
|-
|KEY_4 || Keyboard digit 4 || 4
|-
|KEY_5 || Keyboard digit 5 || 5
|-
|KEY_6 || Keyboard digit 6 || 6
|-
|KEY_7 || Keyboard digit 7 || 7
|-
|KEY_8 || Keyboard digit 8 || 8
|-
|KEY_9 || Keyboard digit 9 || 9
|- style= "font-weight: bolder; color: blue"
| Movie play control
|-
|KEY_FORWARD || Instantly advance in time || >> / FORWARD
|-
|KEY_BACK || Instantly go back in time || <<< / BACK
|-
|KEY_FASTFORWARD || Play movie faster || >>> / FORWARD
|-
|KEY_REWIND || Play movie back || REWIND / BACKWARD
|-
|KEY_NEXT || Select next chapter / sub-chapter / interval || NEXT / SKIP
|-
|KEY_PREVIOUS || Select previous chapter / sub-chapter / interval || BACK / |<< / PREV / PREVIOUS
|-
|KEY_AGAIN || Repeat the video or a video interval || REPEAT / LOOP / RECALL
|-
|KEY_PAUSE || Pause stream || PAUSE / FREEZE
|-
|KEY_PLAY || Play movie at the normal timeshift || NORMAL TIMESHIFT / LIVE / >
|-
|KEY_PLAYPAUSE || Alternate between play and pause || PLAY / PAUSE
|-
|KEY_STOP || Stop stream || STOP
|-
|KEY_RECORD || Start/stop recording stream || CAPTURE / REC / RECORD/PAUSE
|-
|KEY_CAMERA || Take a picture of the image || CAMERA ICON / CAPTURE / SNAPSHOT
|-
|KEY_SHUFFLE || Enable shuffle mode || SHUFFLE
|-
|KEY_TIME || Activate time shift mode || TIME SHIFT
|-
|KEY_TITLE || Allow changing the chapter || CHAPTER
|-
|KEY_SUBTITLE || Allow changing the subtitle || SUBTITLE
|-
|- style= "font-weight: bolder; color: blue"
| Image control
|-
|KEY_BRIGHTNESSDOWN || Decrease Brightness || BRIGHTNESS DECREASE
|-
|KEY_BRIGHTNESSUP || Increase Brightness || BRIGHTNESS INCREASE
|-
|KEY_ANGLE || Switch video camera angle (on videos with more than one angle stored) || ANGLE / SWAP
|-
|KEY_EPG || Open the Electronic Play Guide (EPG) || EPG / GUIDE
|-
|KEY_TEXT || Activate/change closed caption mode || CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX
|-
|- style= "font-weight: bolder; color: blue"
| Audio control
|-
|KEY_AUDIO || Change audio source || AUDIO SOURCE / AUDIO / MUSIC
|-
|KEY_MUTE || Mute/unmute audio || MUTE / DEMUTE / UNMUTE
|-
|KEY_VOLUMEDOWN || Decrease volume || VOLUME- / VOLUME DOWN
|-
|KEY_VOLUMEUP || Increase volume || VOLUME+ / VOLUME UP
|-
|KEY_MODE || Change sound mode || MONO/STEREO
|-
|KEY_LANGUAGE || Select Language || 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL
|-
|- style= "font-weight: bolder; color: blue"
| Channel control
|-
|KEY_CHANNEL || Go to the next favorite channel || ALT / CHANNEL / CH SURFING / SURF / FAV
|-
|KEY_CHANNELDOWN || Decrease channel sequencially || CHANNEL - / CHANNEL DOWN / DOWN
|-
|KEY_CHANNELUP || Increase channel sequencially || CHANNEL + / CHANNEL UP / UP
|-
|KEY_DIGITS || Use more than one digit for channel || PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit
|-
|KEY_SEARCH || Start channel autoscan || SCAN / AUTOSCAN
|-
|- style= "font-weight: bolder; color: blue"
| Colored keys
|-
|KEY_BLUE || IR “Blue” key
|style= "color: blue" | BLUE
|-
|KEY_GREEN || IR “Green” Key
|style= "color: green" | GREEN
|-
|KEY_RED || IR “Red” key
|style= "color: red" | RED
|-
|KEY_YELLOW || IR “Yellow” key
|style= "color: yellow" | YELLOW
|-
|- style= "font-weight: bolder; color: blue"
| Media selection
|-
|KEY_CD || Change input source to Compact Disc || CD
|-
|KEY_DVD || Change input to DVD || DVD / DVD MENU
|-
|KEY_EJECTCLOSECD || Open/close the CD/DVD player || -> ) / CLOSE / OPEN
|-
|KEY_MEDIA || Turn on/off Media application || PC/TV / TURN ON/OFF APP
|-
|KEY_PC || Selects from TV to PC || PC
|-
|KEY_RADIO || Put into AM/FM radio mode || RADIO / TV/FM / TV/RADIO / FM / FM/RADIO
|-
|KEY_TV || Select tv mode || TV / LIVE TV
|-
|KEY_TV2 || Select Cable mode || AIR/CBL
|-
|KEY_VCR || Select VCR mode || VCR MODE / DTR
|-
|KEY_VIDEO || Alternate between input modes || SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO
|-
|- style= "font-weight: bolder; color: blue"
| Power control
|-
|KEY_POWER || Turn on/off computer || SYSTEM POWER / COMPUTER POWER
|-
|KEY_POWER2 || Turn on/off application || TV ON/OFF / POWER
|-
|KEY_SLEEP || Activate sleep timer || SLEEP / SLEEP TIMER
|-
|KEY_SUSPEND || Put computer into suspend mode || STANDBY / SUSPEND
|-
|- style= "font-weight: bolder; color: blue"
| Window control
|-
|KEY_CLEAR || Stop stream and return to default input video/audio || CLEAR / RESET / BOSS KEY
|-
|KEY_CYCLEWINDOWS || Minimize windows and move to the next one || ALT-TAB / MINIMIZE / DESKTOP
|-
|KEY_FAVORITES || Open the favorites stream window || TV WALL / Favorites
|-
|KEY_MENU || Call application menu || 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL
|-
|KEY_NEW || Open/Close Picture in Picture || PIP
|-
|KEY_OK || Send a confirmation code to application || OK / ENTER / RETURN
|-
|KEY_SCREEN || Select screen aspect ratio || 4:3 16:9 SELECT
|-
|KEY_ZOOM || Put device into zoom/full screen mode || ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH
|-
|- style= "font-weight: bolder; color: blue"
| Navigation keys
|-
|KEY_ESC || Cancel current operation || CANCEL / BACK
|-
|KEY_HELP || Open a Help window || HELP
|-
|KEY_HOMEPAGE || Navigate to Homepage || HOME
|-
|KEY_INFO || Open On Screen Display || DISPLAY INFORMATION / OSD
|-
|KEY_WWW || Open the default browser || WEB
|-
|KEY_UP || Up key || UP || On simpler IR's, without separate channel keys, you need to map UP as KEY_CHANNELUP
|-
|KEY_DOWN || Down key || DOWN || On simpler IR's, without separate channel keys, you need to map DOWN as KEY_CHANNELDOWN
|-
|KEY_LEFT || Left key || LEFT || On simpler IR's, without separate volume keys, you need to map LEFT as KEY_VOLUMEDOWN
|-
|KEY_RIGHT || Right key || RIGHT || On simpler IR's, without separate volume keys, you need to map RIGHT as KEY_VOLUMEUP
|-
|- style= "font-weight: bolder; color: blue"
| Miscelaneous keys
|-
|KEY_DOT || Return a dot || .
|-
|KEY_FN || Select a function || FUNCTION
|}

===Technical details about IR===
http://linuxtv.org/wiki/index.php/Remote_controllers-V4L

[[Category:Hardware]]

Remote Controllers

2010-05-12T18:41:24Z

Mauro Carvalho Chehab: /* Adding support for new IR's */

Currently, most analog and digital devices have an Infrared input for a remote control. Each manufacturer has their own type of control. It is not uncommon for the same manufacturer to ship different types of remote controls, depending on the device.

===Adding support for new IR's===

In order to add support for a new keyboard, you need first to discover how the IR code is sent to the device. There are several possibilities:
* IR sensor is directly connected with a GPIO pin of the PCI/USB bridge. This is a very common case nowadays.
* This is probably the easiest way to add support, provided that the driver has already other similar devices. For an example, please see: [add IR support for saa7134].
* Bridge has an IR decoder inside. Some chipsets have already some internal decoder for IR, like dib0700 and em2884;
* There's a small chip that does serial to parallel conversion, outputting the IR code at several GPIO pins.

The way to get the data is hardware specific. Once the driver is able to get an IR scancode, it is generally required to create a new table for it.
NOTE: before adding a new table, please check if the existing ones have already the proper mapping.

The first step to add a new map is to create an alias for it atinclude/media/rc-map.h:

/* Names of the several keytables defined in-kernel */

#define RC_MAP_ADSTECH_DVB_T_PCI "rc-adstech-dvb-t-pci"
...
#define RC_MAP_VIDEOMATE_TV_PVR "rc-videomate-tv-pvr"
#define RC_MAP_WINFAST "rc-winfast"
#define RC_MAP_WINFAST_USBII_DELUXE "rc-winfast-usbii-deluxe"
/*
* Please, do not just append newer Remote Controller names at the end.
* The names should be ordered in alphabetical order
*/

Just add a new line there with the IR name, on alphabetical order:
#define RC_MAP_NAME_OF_MY_NEW_BOARD_MAP "rc-name-of-my-new-board-map"

Then copy one of the existing keymaps, for example, drivers/media/IR/keymaps/rc-empty.c,
replacing the names for the name of your new IR.

Remove all keys at static struct ir_scancode, and add your new keycodes.

For example, assuming that you have a driver with raw decode. By loading ir_core with debug=1, with:
modprobe ir_core debug=1
(be sure that ir_core weren't loaded before)
you'll start to generate lots of logs at the syslog. Use the dmesg command to get those codes:
dmesg |grep scancode

Let's assume that this get you the following results:
for power key:
ir_nec_decode: NEC scancode 0x0300
ir_getkeycode: unknown key for scancode 0x0300
for channel up key:
ir_nec_decode: NEC scancode 0x030c
ir_getkeycode: unknown key for scancode 0x030c
for channel down key:
ir_nec_decode: NEC scancode 0x0310
ir_getkeycode: unknown key for scancode 0x0310

All you need to do is to make sure that those codes are properly mapped at the keycode table:

static struct ir_scancode rc_name_of_my_new_keyboard_map[] = {
{ 0x300, KEY_POWER2 },
{ 0x30c, KEY_CHANNEL_UP },
{ 0x310, KEY_CHANNEL_DOWN },
};

===IR Keycode map used by media devices===

While there has been effort over the years to keep track of the varying IR layouts (documenting them within ir-common.c), unfortunately, there was never any effort to uniform the actual IR keycodes used by the different devices. This lack of uniformity resulted in cases where the same IR keyname was mapped completely different on different IR's. The overall state of confusion that existed is perhaps best demonstrated by viewing what [[ir-common.c]] IR summary looked like as of Aug, 26 2009.

On Aug, 27 2009, having a common mapping for supported IR's became the subject of a [[Development: A proposal for a common IR keycode definition map|proposal]] which would allow userspace applications to make use of common keycode definitions. The table bellow reflects the expected keycode mappings for IR keys.

{| border="1" cellpadding="2"
!Key code
!Meaning
!Key examples on IR
!Notes
|- style= "font-weight: bolder; color: blue"
| Numeric keys
|-
|KEY_0 || Keyboard digit 0 || 0
|-
|KEY_1 || Keyboard digit 1 || 1
|-
|KEY_2 || Keyboard digit 2 || 2
|-
|KEY_3 || Keyboard digit 3 || 3
|-
|KEY_4 || Keyboard digit 4 || 4
|-
|KEY_5 || Keyboard digit 5 || 5
|-
|KEY_6 || Keyboard digit 6 || 6
|-
|KEY_7 || Keyboard digit 7 || 7
|-
|KEY_8 || Keyboard digit 8 || 8
|-
|KEY_9 || Keyboard digit 9 || 9
|- style= "font-weight: bolder; color: blue"
| Movie play control
|-
|KEY_FORWARD || Instantly advance in time || >> / FORWARD
|-
|KEY_BACK || Instantly go back in time || <<< / BACK
|-
|KEY_FASTFORWARD || Play movie faster || >>> / FORWARD
|-
|KEY_REWIND || Play movie back || REWIND / BACKWARD
|-
|KEY_NEXT || Select next chapter / sub-chapter / interval || NEXT / SKIP
|-
|KEY_PREVIOUS || Select previous chapter / sub-chapter / interval || BACK / |<< / PREV / PREVIOUS
|-
|KEY_AGAIN || Repeat the video or a video interval || REPEAT / LOOP / RECALL
|-
|KEY_PAUSE || Pause stream || PAUSE / FREEZE
|-
|KEY_PLAY || Play movie at the normal timeshift || NORMAL TIMESHIFT / LIVE / >
|-
|KEY_PLAYPAUSE || Alternate between play and pause || PLAY / PAUSE
|-
|KEY_STOP || Stop stream || STOP
|-
|KEY_RECORD || Start/stop recording stream || CAPTURE / REC / RECORD/PAUSE
|-
|KEY_CAMERA || Take a picture of the image || CAMERA ICON / CAPTURE / SNAPSHOT
|-
|KEY_SHUFFLE || Enable shuffle mode || SHUFFLE
|-
|KEY_TIME || Activate time shift mode || TIME SHIFT
|-
|KEY_TITLE || Allow changing the chapter || CHAPTER
|-
|KEY_SUBTITLE || Allow changing the subtitle || SUBTITLE
|-
|- style= "font-weight: bolder; color: blue"
| Image control
|-
|KEY_BRIGHTNESSDOWN || Decrease Brightness || BRIGHTNESS DECREASE
|-
|KEY_BRIGHTNESSUP || Increase Brightness || BRIGHTNESS INCREASE
|-
|KEY_ANGLE || Switch video camera angle (on videos with more than one angle stored) || ANGLE / SWAP
|-
|KEY_EPG || Open the Electronic Play Guide (EPG) || EPG / GUIDE
|-
|KEY_TEXT || Activate/change closed caption mode || CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX
|-
|- style= "font-weight: bolder; color: blue"
| Audio control
|-
|KEY_AUDIO || Change audio source || AUDIO SOURCE / AUDIO / MUSIC
|-
|KEY_MUTE || Mute/unmute audio || MUTE / DEMUTE / UNMUTE
|-
|KEY_VOLUMEDOWN || Decrease volume || VOLUME- / VOLUME DOWN
|-
|KEY_VOLUMEUP || Increase volume || VOLUME+ / VOLUME UP
|-
|KEY_MODE || Change sound mode || MONO/STEREO
|-
|KEY_LANGUAGE || Select Language || 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL
|-
|- style= "font-weight: bolder; color: blue"
| Channel control
|-
|KEY_CHANNEL || Go to the next favorite channel || ALT / CHANNEL / CH SURFING / SURF / FAV
|-
|KEY_CHANNELDOWN || Decrease channel sequencially || CHANNEL - / CHANNEL DOWN / DOWN
|-
|KEY_CHANNELUP || Increase channel sequencially || CHANNEL + / CHANNEL UP / UP
|-
|KEY_DIGITS || Use more than one digit for channel || PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit
|-
|KEY_SEARCH || Start channel autoscan || SCAN / AUTOSCAN
|-
|- style= "font-weight: bolder; color: blue"
| Colored keys
|-
|KEY_BLUE || IR “Blue” key
|style= "color: blue" | BLUE
|-
|KEY_GREEN || IR “Green” Key
|style= "color: green" | GREEN
|-
|KEY_RED || IR “Red” key
|style= "color: red" | RED
|-
|KEY_YELLOW || IR “Yellow” key
|style= "color: yellow" | YELLOW
|-
|- style= "font-weight: bolder; color: blue"
| Media selection
|-
|KEY_CD || Change input source to Compact Disc || CD
|-
|KEY_DVD || Change input to DVD || DVD / DVD MENU
|-
|KEY_EJECTCLOSECD || Open/close the CD/DVD player || -> ) / CLOSE / OPEN
|-
|KEY_MEDIA || Turn on/off Media application || PC/TV / TURN ON/OFF APP
|-
|KEY_PC || Selects from TV to PC || PC
|-
|KEY_RADIO || Put into AM/FM radio mode || RADIO / TV/FM / TV/RADIO / FM / FM/RADIO
|-
|KEY_TV || Select tv mode || TV / LIVE TV
|-
|KEY_TV2 || Select Cable mode || AIR/CBL
|-
|KEY_VCR || Select VCR mode || VCR MODE / DTR
|-
|KEY_VIDEO || Alternate between input modes || SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO
|-
|- style= "font-weight: bolder; color: blue"
| Power control
|-
|KEY_POWER || Turn on/off computer || SYSTEM POWER / COMPUTER POWER
|-
|KEY_POWER2 || Turn on/off application || TV ON/OFF / POWER
|-
|KEY_SLEEP || Activate sleep timer || SLEEP / SLEEP TIMER
|-
|KEY_SUSPEND || Put computer into suspend mode || STANDBY / SUSPEND
|-
|- style= "font-weight: bolder; color: blue"
| Window control
|-
|KEY_CLEAR || Stop stream and return to default input video/audio || CLEAR / RESET / BOSS KEY
|-
|KEY_CYCLEWINDOWS || Minimize windows and move to the next one || ALT-TAB / MINIMIZE / DESKTOP
|-
|KEY_FAVORITES || Open the favorites stream window || TV WALL / Favorites
|-
|KEY_MENU || Call application menu || 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL
|-
|KEY_NEW || Open/Close Picture in Picture || PIP
|-
|KEY_OK || Send a confirmation code to application || OK / ENTER / RETURN
|-
|KEY_SCREEN || Select screen aspect ratio || 4:3 16:9 SELECT
|-
|KEY_ZOOM || Put device into zoom/full screen mode || ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH
|-
|- style= "font-weight: bolder; color: blue"
| Navigation keys
|-
|KEY_ESC || Cancel current operation || CANCEL / BACK
|-
|KEY_HELP || Open a Help window || HELP
|-
|KEY_HOMEPAGE || Navigate to Homepage || HOME
|-
|KEY_INFO || Open On Screen Display || DISPLAY INFORMATION / OSD
|-
|KEY_WWW || Open the default browser || WEB
|-
|KEY_UP || Up key || UP || On simpler IR's, without separate channel keys, you need to map UP as KEY_CHANNELUP
|-
|KEY_DOWN || Down key || DOWN || On simpler IR's, without separate channel keys, you need to map DOWN as KEY_CHANNELDOWN
|-
|KEY_LEFT || Left key || LEFT || On simpler IR's, without separate volume keys, you need to map LEFT as KEY_VOLUMEDOWN
|-
|KEY_RIGHT || Right key || RIGHT || On simpler IR's, without separate volume keys, you need to map RIGHT as KEY_VOLUMEUP
|-
|- style= "font-weight: bolder; color: blue"
| Miscelaneous keys
|-
|KEY_DOT || Return a dot || .
|-
|KEY_FN || Select a function || FUNCTION
|}

===Technical details about IR===
http://linuxtv.org/wiki/index.php/Remote_controllers-V4L

[[Category:Hardware]]

Remote Controllers

2010-05-12T18:34:48Z

Mauro Carvalho Chehab: /* Adding support for new IR's */

Currently, most analog and digital devices have an Infrared input for a remote control. Each manufacturer has their own type of control. It is not uncommon for the same manufacturer to ship different types of remote controls, depending on the device.

===Adding support for new IR's===

In order to add support for a new keyboard, you need first to discover how the IR code is sent to the device. There are several possibilities:
* IR sensor is directly connected with a GPIO pin of the PCI/USB bridge. This is a very common case nowadays.
* This is probably the easiest way to add support, provided that the driver has already other similar devices. For an example, please see: [add IR support for saa7134].
* Bridge has an IR decoder inside. Some chipsets have already some internal decoder for IR, like dib0700 and em2884;
* There's a small chip that does serial to parallel conversion, outputting the IR code at several GPIO pins.

The way to get the data is hardware specific. Once the driver is able to get an IR scancode, it is generally required to create a new table for it.
NOTE: before adding a new table, please check if the existing ones have already the proper mapping.

The first step to add a new map is to create an alias for it atinclude/media/rc-map.h:

/* Names of the several keytables defined in-kernel */

#define RC_MAP_ADSTECH_DVB_T_PCI "rc-adstech-dvb-t-pci"
...
#define RC_MAP_VIDEOMATE_TV_PVR "rc-videomate-tv-pvr"
#define RC_MAP_WINFAST "rc-winfast"
#define RC_MAP_WINFAST_USBII_DELUXE "rc-winfast-usbii-deluxe"
/*
* Please, do not just append newer Remote Controller names at the end.
* The names should be ordered in alphabetical order
*/

Just add a new line there with the IR name, on alphabetical order:
#define RC_MAP_NAME_OF_MY_NEW_BOARD_MAP "rc-name-of-my-new-board-map"

Then copy one of the existing keymaps, for example, drivers/media/IR/keymaps/rc-empty.c,
replacing the names for the name of your new IR.

Remove all keys at static struct ir_scancode, and add your new keycodes.

===IR Keycode map used by media devices===

While there has been effort over the years to keep track of the varying IR layouts (documenting them within ir-common.c), unfortunately, there was never any effort to uniform the actual IR keycodes used by the different devices. This lack of uniformity resulted in cases where the same IR keyname was mapped completely different on different IR's. The overall state of confusion that existed is perhaps best demonstrated by viewing what [[ir-common.c]] IR summary looked like as of Aug, 26 2009.

On Aug, 27 2009, having a common mapping for supported IR's became the subject of a [[Development: A proposal for a common IR keycode definition map|proposal]] which would allow userspace applications to make use of common keycode definitions. The table bellow reflects the expected keycode mappings for IR keys.

{| border="1" cellpadding="2"
!Key code
!Meaning
!Key examples on IR
!Notes
|- style= "font-weight: bolder; color: blue"
| Numeric keys
|-
|KEY_0 || Keyboard digit 0 || 0
|-
|KEY_1 || Keyboard digit 1 || 1
|-
|KEY_2 || Keyboard digit 2 || 2
|-
|KEY_3 || Keyboard digit 3 || 3
|-
|KEY_4 || Keyboard digit 4 || 4
|-
|KEY_5 || Keyboard digit 5 || 5
|-
|KEY_6 || Keyboard digit 6 || 6
|-
|KEY_7 || Keyboard digit 7 || 7
|-
|KEY_8 || Keyboard digit 8 || 8
|-
|KEY_9 || Keyboard digit 9 || 9
|- style= "font-weight: bolder; color: blue"
| Movie play control
|-
|KEY_FORWARD || Instantly advance in time || >> / FORWARD
|-
|KEY_BACK || Instantly go back in time || <<< / BACK
|-
|KEY_FASTFORWARD || Play movie faster || >>> / FORWARD
|-
|KEY_REWIND || Play movie back || REWIND / BACKWARD
|-
|KEY_NEXT || Select next chapter / sub-chapter / interval || NEXT / SKIP
|-
|KEY_PREVIOUS || Select previous chapter / sub-chapter / interval || BACK / |<< / PREV / PREVIOUS
|-
|KEY_AGAIN || Repeat the video or a video interval || REPEAT / LOOP / RECALL
|-
|KEY_PAUSE || Pause stream || PAUSE / FREEZE
|-
|KEY_PLAY || Play movie at the normal timeshift || NORMAL TIMESHIFT / LIVE / >
|-
|KEY_PLAYPAUSE || Alternate between play and pause || PLAY / PAUSE
|-
|KEY_STOP || Stop stream || STOP
|-
|KEY_RECORD || Start/stop recording stream || CAPTURE / REC / RECORD/PAUSE
|-
|KEY_CAMERA || Take a picture of the image || CAMERA ICON / CAPTURE / SNAPSHOT
|-
|KEY_SHUFFLE || Enable shuffle mode || SHUFFLE
|-
|KEY_TIME || Activate time shift mode || TIME SHIFT
|-
|KEY_TITLE || Allow changing the chapter || CHAPTER
|-
|KEY_SUBTITLE || Allow changing the subtitle || SUBTITLE
|-
|- style= "font-weight: bolder; color: blue"
| Image control
|-
|KEY_BRIGHTNESSDOWN || Decrease Brightness || BRIGHTNESS DECREASE
|-
|KEY_BRIGHTNESSUP || Increase Brightness || BRIGHTNESS INCREASE
|-
|KEY_ANGLE || Switch video camera angle (on videos with more than one angle stored) || ANGLE / SWAP
|-
|KEY_EPG || Open the Electronic Play Guide (EPG) || EPG / GUIDE
|-
|KEY_TEXT || Activate/change closed caption mode || CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX
|-
|- style= "font-weight: bolder; color: blue"
| Audio control
|-
|KEY_AUDIO || Change audio source || AUDIO SOURCE / AUDIO / MUSIC
|-
|KEY_MUTE || Mute/unmute audio || MUTE / DEMUTE / UNMUTE
|-
|KEY_VOLUMEDOWN || Decrease volume || VOLUME- / VOLUME DOWN
|-
|KEY_VOLUMEUP || Increase volume || VOLUME+ / VOLUME UP
|-
|KEY_MODE || Change sound mode || MONO/STEREO
|-
|KEY_LANGUAGE || Select Language || 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL
|-
|- style= "font-weight: bolder; color: blue"
| Channel control
|-
|KEY_CHANNEL || Go to the next favorite channel || ALT / CHANNEL / CH SURFING / SURF / FAV
|-
|KEY_CHANNELDOWN || Decrease channel sequencially || CHANNEL - / CHANNEL DOWN / DOWN
|-
|KEY_CHANNELUP || Increase channel sequencially || CHANNEL + / CHANNEL UP / UP
|-
|KEY_DIGITS || Use more than one digit for channel || PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit
|-
|KEY_SEARCH || Start channel autoscan || SCAN / AUTOSCAN
|-
|- style= "font-weight: bolder; color: blue"
| Colored keys
|-
|KEY_BLUE || IR “Blue” key
|style= "color: blue" | BLUE
|-
|KEY_GREEN || IR “Green” Key
|style= "color: green" | GREEN
|-
|KEY_RED || IR “Red” key
|style= "color: red" | RED
|-
|KEY_YELLOW || IR “Yellow” key
|style= "color: yellow" | YELLOW
|-
|- style= "font-weight: bolder; color: blue"
| Media selection
|-
|KEY_CD || Change input source to Compact Disc || CD
|-
|KEY_DVD || Change input to DVD || DVD / DVD MENU
|-
|KEY_EJECTCLOSECD || Open/close the CD/DVD player || -> ) / CLOSE / OPEN
|-
|KEY_MEDIA || Turn on/off Media application || PC/TV / TURN ON/OFF APP
|-
|KEY_PC || Selects from TV to PC || PC
|-
|KEY_RADIO || Put into AM/FM radio mode || RADIO / TV/FM / TV/RADIO / FM / FM/RADIO
|-
|KEY_TV || Select tv mode || TV / LIVE TV
|-
|KEY_TV2 || Select Cable mode || AIR/CBL
|-
|KEY_VCR || Select VCR mode || VCR MODE / DTR
|-
|KEY_VIDEO || Alternate between input modes || SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO
|-
|- style= "font-weight: bolder; color: blue"
| Power control
|-
|KEY_POWER || Turn on/off computer || SYSTEM POWER / COMPUTER POWER
|-
|KEY_POWER2 || Turn on/off application || TV ON/OFF / POWER
|-
|KEY_SLEEP || Activate sleep timer || SLEEP / SLEEP TIMER
|-
|KEY_SUSPEND || Put computer into suspend mode || STANDBY / SUSPEND
|-
|- style= "font-weight: bolder; color: blue"
| Window control
|-
|KEY_CLEAR || Stop stream and return to default input video/audio || CLEAR / RESET / BOSS KEY
|-
|KEY_CYCLEWINDOWS || Minimize windows and move to the next one || ALT-TAB / MINIMIZE / DESKTOP
|-
|KEY_FAVORITES || Open the favorites stream window || TV WALL / Favorites
|-
|KEY_MENU || Call application menu || 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL
|-
|KEY_NEW || Open/Close Picture in Picture || PIP
|-
|KEY_OK || Send a confirmation code to application || OK / ENTER / RETURN
|-
|KEY_SCREEN || Select screen aspect ratio || 4:3 16:9 SELECT
|-
|KEY_ZOOM || Put device into zoom/full screen mode || ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH
|-
|- style= "font-weight: bolder; color: blue"
| Navigation keys
|-
|KEY_ESC || Cancel current operation || CANCEL / BACK
|-
|KEY_HELP || Open a Help window || HELP
|-
|KEY_HOMEPAGE || Navigate to Homepage || HOME
|-
|KEY_INFO || Open On Screen Display || DISPLAY INFORMATION / OSD
|-
|KEY_WWW || Open the default browser || WEB
|-
|KEY_UP || Up key || UP || On simpler IR's, without separate channel keys, you need to map UP as KEY_CHANNELUP
|-
|KEY_DOWN || Down key || DOWN || On simpler IR's, without separate channel keys, you need to map DOWN as KEY_CHANNELDOWN
|-
|KEY_LEFT || Left key || LEFT || On simpler IR's, without separate volume keys, you need to map LEFT as KEY_VOLUMEDOWN
|-
|KEY_RIGHT || Right key || RIGHT || On simpler IR's, without separate volume keys, you need to map RIGHT as KEY_VOLUMEUP
|-
|- style= "font-weight: bolder; color: blue"
| Miscelaneous keys
|-
|KEY_DOT || Return a dot || .
|-
|KEY_FN || Select a function || FUNCTION
|}

===Technical details about IR===
http://linuxtv.org/wiki/index.php/Remote_controllers-V4L

[[Category:Hardware]]

Remote Controllers

2010-05-12T18:20:45Z

Mauro Carvalho Chehab:

Currently, most analog and digital devices have an Infrared input for a remote control. Each manufacturer has their own type of control. It is not uncommon for the same manufacturer to ship different types of remote controls, depending on the device.

===Adding support for new IR's===

To do.

===IR Keycode map used by media devices===

While there has been effort over the years to keep track of the varying IR layouts (documenting them within ir-common.c), unfortunately, there was never any effort to uniform the actual IR keycodes used by the different devices. This lack of uniformity resulted in cases where the same IR keyname was mapped completely different on different IR's. The overall state of confusion that existed is perhaps best demonstrated by viewing what [[ir-common.c]] IR summary looked like as of Aug, 26 2009.

On Aug, 27 2009, having a common mapping for supported IR's became the subject of a [[Development: A proposal for a common IR keycode definition map|proposal]] which would allow userspace applications to make use of common keycode definitions. The table bellow reflects the expected keycode mappings for IR keys.

{| border="1" cellpadding="2"
!Key code
!Meaning
!Key examples on IR
!Notes
|- style= "font-weight: bolder; color: blue"
| Numeric keys
|-
|KEY_0 || Keyboard digit 0 || 0
|-
|KEY_1 || Keyboard digit 1 || 1
|-
|KEY_2 || Keyboard digit 2 || 2
|-
|KEY_3 || Keyboard digit 3 || 3
|-
|KEY_4 || Keyboard digit 4 || 4
|-
|KEY_5 || Keyboard digit 5 || 5
|-
|KEY_6 || Keyboard digit 6 || 6
|-
|KEY_7 || Keyboard digit 7 || 7
|-
|KEY_8 || Keyboard digit 8 || 8
|-
|KEY_9 || Keyboard digit 9 || 9
|- style= "font-weight: bolder; color: blue"
| Movie play control
|-
|KEY_FORWARD || Instantly advance in time || >> / FORWARD
|-
|KEY_BACK || Instantly go back in time || <<< / BACK
|-
|KEY_FASTFORWARD || Play movie faster || >>> / FORWARD
|-
|KEY_REWIND || Play movie back || REWIND / BACKWARD
|-
|KEY_NEXT || Select next chapter / sub-chapter / interval || NEXT / SKIP
|-
|KEY_PREVIOUS || Select previous chapter / sub-chapter / interval || BACK / |<< / PREV / PREVIOUS
|-
|KEY_AGAIN || Repeat the video or a video interval || REPEAT / LOOP / RECALL
|-
|KEY_PAUSE || Pause stream || PAUSE / FREEZE
|-
|KEY_PLAY || Play movie at the normal timeshift || NORMAL TIMESHIFT / LIVE / >
|-
|KEY_PLAYPAUSE || Alternate between play and pause || PLAY / PAUSE
|-
|KEY_STOP || Stop stream || STOP
|-
|KEY_RECORD || Start/stop recording stream || CAPTURE / REC / RECORD/PAUSE
|-
|KEY_CAMERA || Take a picture of the image || CAMERA ICON / CAPTURE / SNAPSHOT
|-
|KEY_SHUFFLE || Enable shuffle mode || SHUFFLE
|-
|KEY_TIME || Activate time shift mode || TIME SHIFT
|-
|KEY_TITLE || Allow changing the chapter || CHAPTER
|-
|KEY_SUBTITLE || Allow changing the subtitle || SUBTITLE
|-
|- style= "font-weight: bolder; color: blue"
| Image control
|-
|KEY_BRIGHTNESSDOWN || Decrease Brightness || BRIGHTNESS DECREASE
|-
|KEY_BRIGHTNESSUP || Increase Brightness || BRIGHTNESS INCREASE
|-
|KEY_ANGLE || Switch video camera angle (on videos with more than one angle stored) || ANGLE / SWAP
|-
|KEY_EPG || Open the Electronic Play Guide (EPG) || EPG / GUIDE
|-
|KEY_TEXT || Activate/change closed caption mode || CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX
|-
|- style= "font-weight: bolder; color: blue"
| Audio control
|-
|KEY_AUDIO || Change audio source || AUDIO SOURCE / AUDIO / MUSIC
|-
|KEY_MUTE || Mute/unmute audio || MUTE / DEMUTE / UNMUTE
|-
|KEY_VOLUMEDOWN || Decrease volume || VOLUME- / VOLUME DOWN
|-
|KEY_VOLUMEUP || Increase volume || VOLUME+ / VOLUME UP
|-
|KEY_MODE || Change sound mode || MONO/STEREO
|-
|KEY_LANGUAGE || Select Language || 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL
|-
|- style= "font-weight: bolder; color: blue"
| Channel control
|-
|KEY_CHANNEL || Go to the next favorite channel || ALT / CHANNEL / CH SURFING / SURF / FAV
|-
|KEY_CHANNELDOWN || Decrease channel sequencially || CHANNEL - / CHANNEL DOWN / DOWN
|-
|KEY_CHANNELUP || Increase channel sequencially || CHANNEL + / CHANNEL UP / UP
|-
|KEY_DIGITS || Use more than one digit for channel || PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit
|-
|KEY_SEARCH || Start channel autoscan || SCAN / AUTOSCAN
|-
|- style= "font-weight: bolder; color: blue"
| Colored keys
|-
|KEY_BLUE || IR “Blue” key
|style= "color: blue" | BLUE
|-
|KEY_GREEN || IR “Green” Key
|style= "color: green" | GREEN
|-
|KEY_RED || IR “Red” key
|style= "color: red" | RED
|-
|KEY_YELLOW || IR “Yellow” key
|style= "color: yellow" | YELLOW
|-
|- style= "font-weight: bolder; color: blue"
| Media selection
|-
|KEY_CD || Change input source to Compact Disc || CD
|-
|KEY_DVD || Change input to DVD || DVD / DVD MENU
|-
|KEY_EJECTCLOSECD || Open/close the CD/DVD player || -> ) / CLOSE / OPEN
|-
|KEY_MEDIA || Turn on/off Media application || PC/TV / TURN ON/OFF APP
|-
|KEY_PC || Selects from TV to PC || PC
|-
|KEY_RADIO || Put into AM/FM radio mode || RADIO / TV/FM / TV/RADIO / FM / FM/RADIO
|-
|KEY_TV || Select tv mode || TV / LIVE TV
|-
|KEY_TV2 || Select Cable mode || AIR/CBL
|-
|KEY_VCR || Select VCR mode || VCR MODE / DTR
|-
|KEY_VIDEO || Alternate between input modes || SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO
|-
|- style= "font-weight: bolder; color: blue"
| Power control
|-
|KEY_POWER || Turn on/off computer || SYSTEM POWER / COMPUTER POWER
|-
|KEY_POWER2 || Turn on/off application || TV ON/OFF / POWER
|-
|KEY_SLEEP || Activate sleep timer || SLEEP / SLEEP TIMER
|-
|KEY_SUSPEND || Put computer into suspend mode || STANDBY / SUSPEND
|-
|- style= "font-weight: bolder; color: blue"
| Window control
|-
|KEY_CLEAR || Stop stream and return to default input video/audio || CLEAR / RESET / BOSS KEY
|-
|KEY_CYCLEWINDOWS || Minimize windows and move to the next one || ALT-TAB / MINIMIZE / DESKTOP
|-
|KEY_FAVORITES || Open the favorites stream window || TV WALL / Favorites
|-
|KEY_MENU || Call application menu || 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL
|-
|KEY_NEW || Open/Close Picture in Picture || PIP
|-
|KEY_OK || Send a confirmation code to application || OK / ENTER / RETURN
|-
|KEY_SCREEN || Select screen aspect ratio || 4:3 16:9 SELECT
|-
|KEY_ZOOM || Put device into zoom/full screen mode || ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH
|-
|- style= "font-weight: bolder; color: blue"
| Navigation keys
|-
|KEY_ESC || Cancel current operation || CANCEL / BACK
|-
|KEY_HELP || Open a Help window || HELP
|-
|KEY_HOMEPAGE || Navigate to Homepage || HOME
|-
|KEY_INFO || Open On Screen Display || DISPLAY INFORMATION / OSD
|-
|KEY_WWW || Open the default browser || WEB
|-
|KEY_UP || Up key || UP || On simpler IR's, without separate channel keys, you need to map UP as KEY_CHANNELUP
|-
|KEY_DOWN || Down key || DOWN || On simpler IR's, without separate channel keys, you need to map DOWN as KEY_CHANNELDOWN
|-
|KEY_LEFT || Left key || LEFT || On simpler IR's, without separate volume keys, you need to map LEFT as KEY_VOLUMEDOWN
|-
|KEY_RIGHT || Right key || RIGHT || On simpler IR's, without separate volume keys, you need to map RIGHT as KEY_VOLUMEUP
|-
|- style= "font-weight: bolder; color: blue"
| Miscelaneous keys
|-
|KEY_DOT || Return a dot || .
|-
|KEY_FN || Select a function || FUNCTION
|}

===Technical details about IR===
http://linuxtv.org/wiki/index.php/Remote_controllers-V4L

[[Category:Hardware]]

Using a git driver development tree

2010-04-23T01:00:11Z

Mauro Carvalho Chehab: /* Removing the already loaded modules */

=== Compiling a Git repository ===

The git driver repositories contain the full Linux kernel tree. So, before working with a driver, a full kernel compilation should be done. The easiest way is to run:
$ make oldconfig

This will use your kernel old configuration, asking you only about the new features that have added (or moved), when compared with your original kernel version.

The first build will take some time. In order to do it, just run:
$ make

After having the kernel built (and tested), subsequent compilations can be done by running:
make M=drivers/media/
or, if the driver is currently at staging, by running:
make M=drivers/staging/

With the above commands, only the media (or staging) drivers will be recompiled, if they got changed, saving you some time on testing the new driver features.

NOTE: if you added new files or changed the files dependencies, you may need to do a full make. In this case, just run:
$ make

=== Installing the new kernel ===

If this is the first time you're compiling the drivers, or if kernel version changed from your previous build, you should run a full drivers installation with:
# make modules_install install

Be sure to be root when installing the drivers.

=== Installing the new drivers on your kernel ===

After the first installation, you may just copy the new drivers with this small script:

for i in `find drivers/media -name *.ko`; do
if [ $i -nt /lib/modules/`uname -r`/kernel/$i ]; then
sudo install -m 644 -c -D $i /lib/modules/`uname -r`/kernel/$i || exit -1
fi
done

NOTE:
If your kernel version changed, you'll need to re-build the kernel again, with
$ make olconfig
$ make
In this case, you'll also need to re-install the drivers ans the kernel with:
# make modules_install install

=== Removing the already loaded modules ===

This is probably the trickiest part. You can, of course, just reboot the machine, but this may take some time, so Mauro Carvalho Chehab wrote a script that unloads all kernel modules from the memory. This script were integrated with the mercurial trees.

There's an updated [http://linuxtv.org/downloads/git_tools/rmmod.pl rmmod.pl] version that works with git and with all kernels that put the media drivers at the right location.

In order to remove all V4L/DVB drivers from the memory, all that it is needed is to run. as root:
# ./rmmod.pl unload

PS.: The other options of the script should be working as well, but they weren't really tested, since the only one that
is really useful outside Mecurial tree is the capability of removing the drivers from the memory.

Using a git driver development tree

2010-04-23T00:53:34Z

Mauro Carvalho Chehab: /* Removing the already loaded modules */

=== Compiling a Git repository ===

The git driver repositories contain the full Linux kernel tree. So, before working with a driver, a full kernel compilation should be done. The easiest way is to run:
$ make oldconfig

This will use your kernel old configuration, asking you only about the new features that have added (or moved), when compared with your original kernel version.

The first build will take some time. In order to do it, just run:
$ make

After having the kernel built (and tested), subsequent compilations can be done by running:
make M=drivers/media/
or, if the driver is currently at staging, by running:
make M=drivers/staging/

With the above commands, only the media (or staging) drivers will be recompiled, if they got changed, saving you some time on testing the new driver features.

NOTE: if you added new files or changed the files dependencies, you may need to do a full make. In this case, just run:
$ make

=== Installing the new kernel ===

If this is the first time you're compiling the drivers, or if kernel version changed from your previous build, you should run a full drivers installation with:
# make modules_install install

Be sure to be root when installing the drivers.

=== Installing the new drivers on your kernel ===

After the first installation, you may just copy the new drivers with this small script:

for i in `find drivers/media -name *.ko`; do
if [ $i -nt /lib/modules/`uname -r`/kernel/$i ]; then
sudo install -m 644 -c -D $i /lib/modules/`uname -r`/kernel/$i || exit -1
fi
done

NOTE:
If your kernel version changed, you'll need to re-build the kernel again, with
$ make olconfig
$ make
In this case, you'll also need to re-install the drivers ans the kernel with:
# make modules_install install

=== Removing the already loaded modules ===

This is probably the trickiest part. You can, of course, just reboot the machine, but this may take some time, so Mauro Carvalho Chehab wrote a script that unloads all kernel modules from the memory. This script were integrated with the mercurial trees.

There's an updated [http://linuxtv.org/downloads/git_tools/rmmod.pl rmmod.pl] version that works with git and with all kernels that put the media drivers at the right location.

In order to remove all V4L/DVB drivers from the memory, all that it is needed is to run:
$ ./rmmod.pl unload

PS.: The other options of the script should be working as well, but they weren't really tested, since the only one that
is really useful outside Mecurial tree is the capability of removing the drivers from the memory.

Using a git driver development tree

2010-04-23T00:48:58Z

Mauro Carvalho Chehab: /* Installing the new drivers on your kernel */

=== Compiling a Git repository ===

The git driver repositories contain the full Linux kernel tree. So, before working with a driver, a full kernel compilation should be done. The easiest way is to run:
$ make oldconfig

This will use your kernel old configuration, asking you only about the new features that have added (or moved), when compared with your original kernel version.

The first build will take some time. In order to do it, just run:
$ make

After having the kernel built (and tested), subsequent compilations can be done by running:
make M=drivers/media/
or, if the driver is currently at staging, by running:
make M=drivers/staging/

With the above commands, only the media (or staging) drivers will be recompiled, if they got changed, saving you some time on testing the new driver features.

NOTE: if you added new files or changed the files dependencies, you may need to do a full make. In this case, just run:
$ make

=== Installing the new kernel ===

If this is the first time you're compiling the drivers, or if kernel version changed from your previous build, you should run a full drivers installation with:
# make modules_install install

Be sure to be root when installing the drivers.

=== Installing the new drivers on your kernel ===

After the first installation, you may just copy the new drivers with this small script:

for i in `find drivers/media -name *.ko`; do
if [ $i -nt /lib/modules/`uname -r`/kernel/$i ]; then
sudo install -m 644 -c -D $i /lib/modules/`uname -r`/kernel/$i || exit -1
fi
done

NOTE:
If your kernel version changed, you'll need to re-build the kernel again, with
$ make olconfig
$ make
In this case, you'll also need to re-install the drivers ans the kernel with:
# make modules_install install

=== Removing the already loaded modules ===

This is probably the trickiest part. You can, of course, just reboot the machine, but this may take some time, so Mauro Chehab wrote a script that unloads all kernel modules from the memory. There's a [http://linuxtv.org/downloads/git_tools/rmmod.pl rmmod.pl] version that works with git and with all kernels that put the media drivers at the right location.

In order to remove all V4L/DVB drivers from the memory, all that it is needed is to run:
$ ./rmmod.pl unload

The other options of the script should be working as well, but I didn't test, since the only one I find really useful is the capability of removing the drivers from the memory.

Using a git driver development tree

2010-04-23T00:48:17Z

Mauro Carvalho Chehab: /* Installing the new drivers on your kernel */

=== Compiling a Git repository ===

The git driver repositories contain the full Linux kernel tree. So, before working with a driver, a full kernel compilation should be done. The easiest way is to run:
$ make oldconfig

This will use your kernel old configuration, asking you only about the new features that have added (or moved), when compared with your original kernel version.

The first build will take some time. In order to do it, just run:
$ make

After having the kernel built (and tested), subsequent compilations can be done by running:
make M=drivers/media/
or, if the driver is currently at staging, by running:
make M=drivers/staging/

With the above commands, only the media (or staging) drivers will be recompiled, if they got changed, saving you some time on testing the new driver features.

NOTE: if you added new files or changed the files dependencies, you may need to do a full make. In this case, just run:
$ make

=== Installing the new kernel ===

If this is the first time you're compiling the drivers, or if kernel version changed from your previous build, you should run a full drivers installation with:
# make modules_install install

Be sure to be root when installing the drivers.

=== Installing the new drivers on your kernel ===

After the first installation, you may just copy the new drivers with this small script:

for i in `find drivers/media -name *.ko`; do
if [ $i -nt /lib/modules/`uname -r`/kernel/$i ]; then
sudo install -m 644 -c -D $i /lib/modules/`uname -r`/kernel/$i || exit -1
fi
done

NOTE: if your kernel version changed, you'll need to re-build the kernel again, with
$ make olconfig
$ make
In this case, you'll also need to re-install the drivers an the kernel with:
# make modules_install install

=== Removing the already loaded modules ===

This is probably the trickiest part. You can, of course, just reboot the machine, but this may take some time, so Mauro Chehab wrote a script that unloads all kernel modules from the memory. There's a [http://linuxtv.org/downloads/git_tools/rmmod.pl rmmod.pl] version that works with git and with all kernels that put the media drivers at the right location.

In order to remove all V4L/DVB drivers from the memory, all that it is needed is to run:
$ ./rmmod.pl unload

The other options of the script should be working as well, but I didn't test, since the only one I find really useful is the capability of removing the drivers from the memory.

Using a git driver development tree

2010-04-23T00:38:46Z

Mauro Carvalho Chehab: /* Removing the already loaded modules */

=== Compiling a Git repository ===

The git driver repositories contain the full Linux kernel tree. So, before working with a driver, a full kernel compilation should be done. The easiest way is to run:
$ make oldconfig

This will use your kernel old configuration, asking you only about the new features that have added (or moved), when compared with your original kernel version.

The first build will take some time. In order to do it, just run:
$ make

After having the kernel built (and tested), subsequent compilations can be done by running:
make M=drivers/media/
or, if the driver is currently at staging, by running:
make M=drivers/staging/

With the above commands, only the media (or staging) drivers will be recompiled, if they got changed, saving you some time on testing the new driver features.

NOTE: if you added new files or changed the files dependencies, you may need to do a full make. In this case, just run:
$ make

=== Installing the new kernel ===

If this is the first time you're compiling the drivers, or if kernel version changed from your previous build, you should run a full drivers installation with:
# make modules_install install

Be sure to be root when installing the drivers.

=== Installing the new drivers on your kernel ===

After the first installation, you may just copy the new drivers with this small script:

for i in `find drivers/media -name *.ko`; do
if [ $i -nt /lib/modules/`uname -r`/kernel/$i ]; then
sudo install -m 644 -c -D $i /lib/modules/`uname -r`/kernel/$i || exit -1
fi
done

NOTE: if your kernel version changed, you'll need to re-build the kernel again, with
$ make olconfig
$ make

=== Removing the already loaded modules ===

This is probably the trickiest part. You can, of course, just reboot the machine, but this may take some time, so Mauro Chehab wrote a script that unloads all kernel modules from the memory. There's a [http://linuxtv.org/downloads/git_tools/rmmod.pl rmmod.pl] version that works with git and with all kernels that put the media drivers at the right location.

In order to remove all V4L/DVB drivers from the memory, all that it is needed is to run:
$ ./rmmod.pl unload

The other options of the script should be working as well, but I didn't test, since the only one I find really useful is the capability of removing the drivers from the memory.

Using a git driver development tree

2010-04-23T00:06:47Z

Mauro Carvalho Chehab:

=== Compiling a Git repository ===

The git driver repositories contain the full Linux kernel tree. So, before working with a driver, a full kernel compilation should be done. The easiest way is to run:
$ make oldconfig

This will use your kernel old configuration, asking you only about the new features that have added (or moved), when compared with your original kernel version.

The first build will take some time. In order to do it, just run:
$ make

After having the kernel built (and tested), subsequent compilations can be done by running:
make M=drivers/media/
or, if the driver is currently at staging, by running:
make M=drivers/staging/

With the above commands, only the media (or staging) drivers will be recompiled, if they got changed, saving you some time on testing the new driver features.

NOTE: if you added new files or changed the files dependencies, you may need to do a full make. In this case, just run:
$ make

=== Installing the new kernel ===

If this is the first time you're compiling the drivers, or if kernel version changed from your previous build, you should run a full drivers installation with:
# make modules_install install

Be sure to be root when installing the drivers.

=== Installing the new drivers on your kernel ===

After the first installation, you may just copy the new drivers with this small script:

for i in `find drivers/media -name *.ko`; do
if [ $i -nt /lib/modules/`uname -r`/kernel/$i ]; then
sudo install -m 644 -c -D $i /lib/modules/`uname -r`/kernel/$i || exit -1
fi
done

NOTE: if your kernel version changed, you'll need to re-build the kernel again, with
$ make olconfig
$ make

=== Removing the already loaded modules ===

This is probably the trickiest part. You can, of course, just reboot the machine, but this may take some time, so Mauro Chehab wrote a script that unloads all kernel modules from the memory. There's a [http://linuxtv.org/downloads/git_tools/rmmod.pl rmmod.pl] version that works with git and with all kernels that put the media drivers at the right location.

2010-01-29T22:30:39Z

Mauro Carvalho Chehab: /* Tags that a patch receive after its submission */

== KERNEL DEVELOPMENT PROCEDURES AT THE KERNEL UPSTREAM ==

It is important that people understand how upstream development works.

Kernel development has 2 phases:

*1) a merge window typically with 2 weeks (although Linus is gave some indications that he may reduce it on 2.6.34), starting with the release of a new kernel version;

*2) the -rc period, where the Kernel is tested and receive fixes.

The length of the -rc period depends on the number and relevance of the fixes. Considering the recent history, it ranges from -rc6 to -rc8, where each -rc takes one week.

Those are the latest -rc kernels since 2.6.12:
{| border="1" cellpadding="2"
!kernel !!latest -rc version
|-
|2.6.12 ||align="center" | rc6
|-
|2.6.13 ||align="center" | rc7
|-
|2.6.14 ||align="center" | rc5
|-
|2.6.15 ||align="center" | rc7
|-
|2.6.16 ||align="center" | rc6
|-
|2.6.17 ||align="center" | rc6
|-
|2.6.18 ||align="center" | rc7
|-
|2.6.19 ||align="center" | rc6
|-
|2.6.20 ||align="center" | rc7
|-
|2.6.21 ||align="center" | rc7
|-
|2.6.22 ||align="center" | rc7
|-
|2.6.23 ||align="center" | rc9
|-
|2.6.24 ||align="center" | rc8
|-
|2.6.25 ||align="center" | rc9
|-
|2.6.26 ||align="center" | rc9
|-
|2.6.27 ||align="center" | rc9
|-
|2.6.28 ||align="center" | rc9
|-
|2.6.29 ||align="center" | rc8
|-
|2.6.30 ||align="center" | rc8
|-
|2.6.31 ||align="center" | rc9
|-
|2.6.32 ||align="center" | rc8
|}

In general, the announcement of a new -rc kernel gives some hints when that -rc kernel may be the last one.

====Subsystem procedures for merging patches upstream====

The required procedure on subsystem trees is that:

a) During -rc period (e.g. latest main kernel available is 2.6.x, the latest -rc kernel is 2.6.[x+1]-rc<y>):

* fix patches for the -rc kernel (2.6.[x+1]) should be sent upstream, being a good idea to send them for some time at linux-next tree, allowing other people to test it, and check for potential conflicts with the other arch's;
* patches for 2.6.[x+2] should be sent to linux-next.

b) the release of 2.6.[x+1] kernel:

* closes the -rc period and starts the merge window.

c) During the merge window:

* the patch that were added on linux-next during the -rc period for 2.6.[x+2] should be sent upstream;
* new non-fix patches should be hold until the next -rc period starts, so, they'll be added on 2.6.[x+3];
* fix patches for 2.6.[x+2] should go to linux-next, wait for a few days and then send upstream.

d) the release of 2.6.[x+2]-rc1 kernel:

* the merge window has closed. No new features are allowed.
* the patches with new features that arrived during the merge window will be moved to linux-next

====A practical example====

Considering that, at the time this document were written, the last main release is 2.6.32, and the latest -rc release is 2.6.33-rc5, this means that:

* Stable patches, after adding upstream, are being received for 2.6.32 kernel series;
* Bug fixes are being received for kernel 2.6.33;
* New feature patches are being received for kernel 2.6.34.

After the release of kernel 2.6.33, starts the period for receiving patches for 2.6.35.

In other words, the features being developed are always meant to be included on the next 2 kernels.

In the specific case of new drivers that don't touch on existing features, it could be possible to send it during the -rc period, but it is safer to assume that those drivers should follow the above procedure, as a later submission may be nacked.

====Patches for stable====

Sometimes, a fix patch corrects a problem that happens also on stable kernels (e. g. on kernel 2.6.x or even 2.6.y, where y < x). In this case, the patch should be sent to stable@kernel.org, in order to be added on stable kernels.

In the case of git-submitted patches with fixes, that also need to be send to stable, all the developer needs to do is to add, a the patch description:
CC: stable.kernel.org

At the moment the patch reaches upstream, a copy of the patch will be automatically be sent to the stable maintainer and will be considered for inclusion on the next stable kernel (2.6.x.y).

== KERNEL DEVELOPMENT PROCEDURES FOR V4L/DVB ==

The upsteam procedures should be followed by every kernel subsystem. The subsystems have their own specific procedures detailing how the development patches are handled before arriving upstream. In the case of v4l/dvb, those are the used procedures.

==== Fixes and linux-next patches====

One of the big problems of our model used in the past by the subsystem, based on one Mercurial tree, is that there were just one tree/branch for everything. This makes hard to send some fix patches for 2.6.[x+1], as they may have conflicts with the patches for 2.6.[x+2]. So, when the conflict is simple to solve, the patch is sent as fixes. Otherwise, the patch generally needed to hold to the next cycle.
The fix patches used to get a special tag, added by the developer ("Priority: high", in the body of the description), to give a hint to the subsystem maintainer that the patch should be sent upstream.

Unfortunately, sometimes people mark the driver with the wrong tag. For example, a patch got merged on Jan, 22 2010 that marked with "high". However, that patch didn't apply at the fixes tree, because it fix a regression introduced by a driver that weren't merged upstream yet.

====== How to solve those issues? ======

Well, basically, the subsystem should work with more than one tree (or branch), on upstream submission:
* a tree(branch) with the fix patches;
* a tree(branch) with the new feature patches.

So, the subsystem uses two development -git trees:
* http://linuxtv.org/git//v4l-dvb.git - for patches that will be sent to the [x+2] kernel (and merged at upstream linux-next tree)
* http://linuxtv.org/git//fixes.git - for bug patches that will be sent to the [x+1] kernel (also, patches that need to go to both [x+1] and [x])

While the patches via -hg, due to the merge conflicts its mentioned, the better is that, even those developers that prefer to develop patches use the old way, to send the fix patches via -git. This way, if is there a conflict, he is the one that can better solve it. Also, it avoids the risk of a patch being wrongly tagged.

Also, after having a patch added on one of the above trees, it can't simply remove it, as others will be cloning that tree. So, the only option would be to send a revert patch, causing the patch history to be dirty and could be resulting on some troubles when submitting upstream. I've seen some nacks on receiving patches upstream from dirty git trees. So, we should really avoid this.

==how to submit a -git pull request==

As the same git tree may have more than one branch, and we'll have 2 -git trees for upstream, it is required that people specify what should be done. The internal maintainer's workflow is based on different mail queues for each type of requesting received.

There are some scripts to automate the process, so it is important that everyone that sends -git pull do it at the same way.

So, a pull request to be send with the following email tags:

From: <your real email>
Subject: [GIT FIXES FOR 2.6.33] Fixes for driver cx88
To: linux-media@vger.kernel.org

From: <your real email>
Subject: [GIT PATCHES FOR 2.6.34] Updates for the driver saa7134
To: linux-media@vger.kernel.org

The from line may later be used by the git mailbomb script to send you a copy when the patch were committed, so it should be your real email.

The indication between [] on the subject will be handled by the mailer scripts to put the request at the right queue. So, if tagged wrong, it may not be committed.

Don't send a copy of the pull to the maintainer addresses. The pull will be filtering based on the subject and on the mailing list. If you send a c/c to the maintainer, it will be simply discarded.

NEVER send a copy of any pull request to a subscribers-only mailing list. Everyone is free to answer to the email, reviewing your patches. Don't penalty people that wants to contribute with you with SPAM bouncing emails, produced by subscribers only lists.

When a patch touches on other subsystem codes, please copy the other subsystem maintainers. This is important for patches that touches on arch files, and also for -alsa non-trivial patches.

The email should be generated with the usage of git request-pull:
git request-pull $ORIGIN $URL

where $ORIGIN is the commit hash of the tree before your patches, and $URL is the URL for your repository.

For example, for the patches merged directly from -hg at the -git trees on Jan, 22 2010, the above commands produced:

The following changes since commit 2f52713ab3cb9af2eb0f9354dba1421d1497f3e7:
Abylay Ospan (1):
V4L/DVB: 22-kHz set_tone fix for NetUP Dual DVB-S2-CI card. 22kHz logic controlled by demod

are available in the git repository at:

git://linuxtv.org/v4l-dvb.git master

Andy Walls (4):
V4L/DVB: cx25840, v4l2-subdev, ivtv, pvrusb2: Fix ivtv/cx25840 tinny audio
V4L/DVB: ivtv: Adjust msleep() delays used to prevent tinny audio and PCI bus hang
V4L/DVB: cx18-alsa: Initial non-working cx18-alsa files
V4L/DVB: cx18-alsa: Add non-working cx18-alsa-pcm.[ch] files to avoid data loss

Devin Heitmueller (20):
V4L/DVB: xc3028: fix regression in firmware loading time
V4L/DVB: cx18: rename cx18-alsa.c
V4L/DVB: cx18: make it so cx18-alsa-main.c compiles
V4L/DVB: cx18: export a couple of symbols so they can be shared with cx18-alsa
V4L/DVB: cx18: overhaul ALSA PCM device handling so it works
V4L/DVB: cx18: add cx18-alsa module to Makefile
V4L/DVB: cx18: export more symbols required by cx18-alsa
V4L/DVB: cx18-alsa: remove unneeded debug line
V4L/DVB: cx18: rework cx18-alsa module loading to support automatic loading
V4L/DVB: cx18: cleanup cx18-alsa debug logging
V4L/DVB: cx18-alsa: name alsa device after the actual card
V4L/DVB: cx18-alsa: remove a couple of warnings
V4L/DVB: cx18-alsa: fix memory leak in error condition
V4L/DVB: cx18-alsa: fix codingstyle issue
V4L/DVB: cx18-alsa: codingstyle fixes
V4L/DVB: cx18: codingstyle fixes
V4L/DVB: cx18-alsa: codingstyle cleanup
V4L/DVB: cx18-alsa: codingstyle cleanup
V4L/DVB: cx18: address possible passing of NULL to snd_card_free
V4L/DVB: cx18-alsa: Fix the rates definition and move some buffer freeing code.

Ian Armstrong (1):
V4L/DVB: ivtv: Fix race condition for queued udma transfers

Igor M. Liplianin (4):
V4L/DVB: Add Support for DVBWorld DVB-S2 PCI 2004D card
V4L/DVB: dm1105: connect splitted else-if statements
V4L/DVB: dm1105: use dm1105_dev & dev instead of dm1105dvb
V4L/DVB: dm1105: use macro for read/write registers

JD Louw (1):
V4L/DVB: Compro S350 GPIO change

drivers/media/common/tuners/tuner-xc2028.c | 11 +-
drivers/media/dvb/dm1105/Kconfig | 1 +
drivers/media/dvb/dm1105/dm1105.c | 501 ++++++++++++++-------------
drivers/media/video/cx18/Kconfig | 11 +
drivers/media/video/cx18/Makefile | 2 +
drivers/media/video/cx18/cx18-alsa-main.c | 293 ++++++++++++++++
drivers/media/video/cx18/cx18-alsa-mixer.c | 191 ++++++++++
drivers/media/video/cx18/cx18-alsa-mixer.h | 23 ++
drivers/media/video/cx18/cx18-alsa-pcm.c | 353 +++++++++++++++++++
drivers/media/video/cx18/cx18-alsa-pcm.h | 27 ++
drivers/media/video/cx18/cx18-alsa.h | 59 ++++
drivers/media/video/cx18/cx18-driver.c | 40 ++-
drivers/media/video/cx18/cx18-driver.h | 10 +
drivers/media/video/cx18/cx18-fileops.c | 6 +-
drivers/media/video/cx18/cx18-fileops.h | 3 +
drivers/media/video/cx18/cx18-mailbox.c | 46 +++-
drivers/media/video/cx18/cx18-streams.c | 2 +
drivers/media/video/cx25840/cx25840-core.c | 48 ++-
drivers/media/video/ivtv/ivtv-irq.c | 5 +-
drivers/media/video/ivtv/ivtv-streams.c | 6 +-
drivers/media/video/ivtv/ivtv-udma.c | 1 +
drivers/media/video/pvrusb2/pvrusb2-hdw.c | 1 +
drivers/media/video/saa7134/saa7134-cards.c | 4 +-
include/media/v4l2-subdev.h | 1 +
24 files changed, 1380 insertions(+), 265 deletions(-)
create mode 100644 drivers/media/video/cx18/cx18-alsa-main.c
create mode 100644 drivers/media/video/cx18/cx18-alsa-mixer.c
create mode 100644 drivers/media/video/cx18/cx18-alsa-mixer.h
create mode 100644 drivers/media/video/cx18/cx18-alsa-pcm.c
create mode 100644 drivers/media/video/cx18/cx18-alsa-pcm.h
create mode 100644 drivers/media/video/cx18/cx18-alsa.h

This helps to identify what's expected to be found at the -git tree and to double check if the merge happened fine.

====Tags that a patch receive after its submission====

This is probably the most complex issue to solve.

Signed-off-by/Acked-by/Tested-by/Nacked-by tags may be received after a patch or a -git submission. This can happen even while the patch is being tested at linux-next, from people reporting problems on the existing patches, or reporting that a patch worked fine.

Also, the driver maintainer and the subsystem maintainer that is committing those patches should sign each one, to indicate that he reviewed and has accepted the patch.

Currently, if a new tag is added to a committed patch, its hash will change. There were some discussions at Linux Kernel Mailing List about allowing adding new tags on -git without changing the hash, but I think this weren't implemented (yet?).

The same problem occurs with -hg, but, as -hg doesn't support multiple branches (well, it has a "branch" command, but the concept of branch there is different), it was opted that the -hg trees won't have all the needed SOBs. Instead, those would be added only at the submission tree.

With -git, a better procedure can be used:

The developer may have two separate branches on his tree. For example, let's assume that the developer has the following branches on his tree:
* media-master (associated with "linuxtv" remote)
* fixes
* devel

His development happens on devel branch. When the patches are ready to submission will be copied into a new for_submission branch:
git branch for_submission devel

And a pull request from the branch "for_submission" will be sent.

Eventually, he'll write new patches on his devel branch.

After merged, the developer updates the linuxtv remote and drops the for_submission branch. This way, "media-master" will contain his patches that got a new hash, due to the maintainer's SOB. However, he has some new patches on his devel, that applies over the old hashes.

Fortunately, git has a special command to automatically remove the old objects: git rebase.

All the developer needs to do is to run the commands bellow:
{| border="1" cellpadding="2"
!git command
!notes
|-
| git remote update || to update his remotes, including "linuxtv"
|-
| git checkout devel || move to devel branch
|-
| git pull . media-master || to make a recursive merge from v4l/dvb upstream
|-
| git rebase media-master || to remove the legacy hashes
|}
After this, his development branch will contain only upstream patches + the new ones he added after sending the patches for upstream submission.

==Patches submitted via email==

All valid patches submitted via email to [[mailto:linux-media@vger.kernel.org]] are automatically stored at [[http://patchwork.kernel.org/project/linux-media/list/]]. A patch, to be valid, should be in diff unified format. If you're using a -git tree, the simplest way to generate unified diff patches is to run:
git diff

If you're writing several patches, the better is to create a tag or a branch for the changes you're working. After that, you can use
git format-patch <origin_branch>

to create the patches for email submission.

====Example====

Suppose that the -git tree were created with:

git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git v4l-dvb
cd v4l-dvb
git remote add linuxtv git://linuxtv.org/v4l-dvb.git
git remote update
git checkout -b media-master linuxtv/master

Before start working, you need to create your work branch:

git branch work media-master

And move the working copy to the "work" branch:

git checkout work

Some changes were done at the driver and saved by commit:

git commit -as

When the patches are ready for submission via email, all that is needed is to run:

git format-patch work

The command will create a series of emails bodies, one file per email.

Just send the email with the patch inlined for it to ge caught by patchwork.

BE CAREFULL: several emailers including Thunderdird breaks long lines, causing patch corruption.

In the specific case of Thunderbird, an extension is needed to send the patches: [https://hg.mozilla.org/users/clarkbw_gnome.org/asalted-patches/| Asalted Patches].