@@ -1,5 +1,5 @@
Mauro Carvalho Chehab <mchehab at infradead dot org>
- Updated on 2009 February 9
+ Updated on 2010 January 30
This file describes the general procedures used by the LinuxTV team (*)
and by the v4l-dvb community.
@@ -13,58 +13,135 @@ TV and radio broadcast AM/FM.
CONTENTS
========
- 1. A brief introduction about patch management
- 2. Git trees' relationships with v4l/dvb development
- 3. Mercurial trees used for v4l/dvb development
- 4. Community best practices
- 5. Knowing about newer patches committed at master hg repository
- 6. Patch handling for kernel submission
- 7. Patch submission from the community
- 8. Identifying regressions with Mercurial
- 9. Creating a newer driver
+ Part I - Patch management on LinuxTV
+ 1. A brief introduction about patch management
+ 2. Git and Mercurial trees hosted on LinuxTV site
+ 3. Git and Mercurial trees' relationships with v4l/dvb development
+ 4. Patch submission process overall
+ 5. Other Git trees used for v4l/dvb development
+ 6. Other Mercurial trees used for v4l/dvb development
+
+ Part II - Git trees
+ 1. Kernel development procedures at the kernel upstream
+ 1.1 Subsystem procedures for merging patches upstream
+ 1.2 A practical example
+ 1.3 Patches for stable
+ 2. Kernel development procedures for V4L/DVB
+ 2.1 Fixes and linux-next patches
+ 2.2 How to solve those issues?
+ 3. How to submit a -git pull request
+ 3.1 Tags that a patch receive after its submission
+ 4. Patches submitted via email
+ 4.1 Example
+
+ Part III - Best Practices
+ 1. Community best practices
+ 2. Mercurial specific procedures
+ 3. Knowing about newer patches committed at the development repositories
+ 4. Patch submission from the community
+ 5. Identifying regressions with Mercurial
+ 6. Identifying regressions with Git
+ 7. Creating a newer driver
+ 7.1. Simple drivers
+ 7.2. Bigger drivers
+
+===================================
+PART I. PATCH MANAGEMENT ON LINUXTV
+===================================
+
1. A brief introduction about patch management
- ==========================================
+ ===========================================
-Current V4L/DVB development is based on a modern SCM system that
-fits better into kernel development model, called Mercurial (aka hg).
+V4L/DVB development is based on modern SCM (Source Code Management) systems
+that fits better into kernel development model.
-Kernel development model is based on a similar SCM, called git. While
-very powerful for distributed development, git usage is not simple for
-final users. That's the reason why hg was selected for V4L/DVB
-development.
+At the beginning, the usage CVS for of a SCM (Source Code Management) were
+choosen on V4L/DVB. Both of the original V4L and DVB trees were developed with
+the help of cvs. On that time, upstream Linux kernel used to have another tree
+(BitKeeper).
-There are some tutorials, FAQs and other valuable information at
-http://selenic.com/mercurial/ about hg usage.
+In 2005, Upstream Kernel development model changed to use git (a SCM tool
+developed by Linus Torvalds, the inventor and main maintainer of the Linux
+Kernel).
-Mercurial is a distributed SCM, which means every developer gets his
-own full copy of the repository (including the complete revision
-history), and can work and commit locally without network connection.
-The resulting changesets can then be exchanged between repositories and
-finally merged into a common repository on linuxtv.org.
+Also in 2005, both V4L and DVB trees got merged into one cvs repository, and
+the community discussed about what would be the better SCM solution. It were
+mainly availed the usage of svn, hg and git. On that time, both hg and git were
+new technologies, based on the concept of a distributed SCM, where there's no
+need to go to the server every time a command is used at the SCM. This speeds
+up the development time, and allows descentralized development.
-A list of current available repositories is available at:
+Mercurial used to be stable and had more projects using, while git were giving
+its first steps, being used almost only by the Linux Kernel, and several distros
+didn't use to package it. Git objects were stored uncompressed, generating very
+large trees. Also, -git tools were complex to use, and some "porcelain" packages
+were needed, in order to be used by a normal user.
+
+So, the decision was made to use Mercurial. However, as time goes by, git got
+much more eyes than any other SCM, having all their weakness solved, and being
+developed really fast. Also, it got adopted by several other projects, due to
+its capability and its number of features.
+
+Technically speaking, -git is currently the most advanced distributed
+open-source SCM application available today.
+
+Yet, Mercurial has been doing a very good job maintaining the V4L/DVB trees,
+and, except for a few points, it does the job.
+
+However, the entire Linux Kernel development happens around -git. Even the ones
+that were adopting other tools (like -alsa, that used to have also Mercurial
+repositories) migrated to -git.
+
+Despite all technical advantages, the rationale for the migration to git is
+quite simple: converting patches between different repositories and SCM tools
+cause development and merge delays, may cause patch mangling and eats lot of
+the time for people that are part of the process.
+
+Also, every time a patch needs to touch on files outside the incomplete tree
+used at the subsystem, an workaround need to be done, in order to avoid troubles
+and to be able to send the patch upstream.
+
+So, it is simpler to just use -git.
+
+2. Git and Mercurial trees hosted on LinuxTV site
+ ==============================================
+
+A list of current available Git repositories used on LinuxTV is available at:
http://linuxtv.org/hg/
-2. Git and Mercurial trees' relationships with v4l/dvb development
+
+A list of current available Mercurial repositories used on LinuxTV is available
+at:
+ http://git.linuxtv.org
+
+3. Git and Mercurial trees' relationships with v4l/dvb development
===============================================================
-The main kernel trees are hosted at http://git.kernel.org. Each tree
-is owned by a maintainer.
+The main subsystem kernel trees are hosted at http://git.kernel.org. Each tree
+is owned by a maintainer. In the case of LinuxTV, the subsystem maintainer is
+Mauro Carvalho Chehab, who owns all sybsystem trees.
-The main kernel trees is owned by Linus Torvalds, being located at:
+The main kernel tree is owned by Linus Torvalds, being located at:
http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git
-The subsystem master tree is owned by the subsystem maintainer (Mauro
-Carvalho Chehab) being located at:
+The subsystem maintainer's master tree is located at:
http://git.kernel.org/?p=linux/kernel/git/mchehab/linux-2.6.git
-A tree with development patches that aren't ready yet for upstream is
-handled at:
- http://git.kernel.org/?p=linux/kernel/git/mchehab/devel.git
+The subsystem maintainer's tree with development patches that aren't ready yet
+for upstream is handled at:
+ http://git.linuxtv.org/git/v4l-dvb.git
+
+The main function of this tree is to merge patches received via email and from
+other Git and Mercurial repositories and to test the entire subsystem with the
+finished patches.
+
+The subsystem maintainer's tree with development patches that will be sent soon
+to upstream is located at:
+ http://git.linuxtv.org/git/fixes.git
There is also an experimental tree, that contains all experimental patches
-from subsystem trees, called linux-next. Its purpose is to check in
+from all subsystem trees, called linux-next. Its purpose is to check in
advance if patches from different trees would conflict. The main tree for
linux-next is owned by Stephen Rothwell and it is located at:
http://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git
@@ -73,41 +150,107 @@ Warning: linux-next is meant to be used
+++++++ patches on several subsystems, it may cause damage if used on
production systems.
-The subsystem linux-next tree is also owned by Mauro Carvalho Chehab, and it is
-located at:
+The subsystem maintainer's linux-next tree is located at:
http://www.kernel.org/git/?p=linux/kernel/git/mchehab/linux-next.git
-Before committing into the master -git tree, the finished patches from
-each maintainers tree are added on a staging tree, owned by the
-subsystem maintainer, at:
- http://linuxtv.org/hg/v4l-dvb/
+In general, it contains a replica of the contents of the development tree.
-The main function of this tree is to merge patches from other
-repositories and to test the entire subsystem with the finished patches.
-This is also the recommended tree for users interested on testing newer V4L/DVB
-patches and drivers.
+Michael Krufky maintains a backport tree, containing a subset of the
+patches from the subsystem tree that are meant to be sent to kernel
+-stable team, at:
+ http://git.kernel.org/http://git.kernel.org/?p=linux/kernel/git/mkrufky/
+v4l-dvb-2.6.x.y.git
+
+In order to allow testing the LinuxTV drivers with older kernels, a backport
+tree is maintained by Douglas Landgraf. The backport tree is at:
+ http://linuxtv.org/hg/v4l-dvb
+
+ Basically, all patches added at -git
+are manually imported on this tree, that also contains some logic to allow
+compilation of the core system since kernel 2.6.16. It should be noticed,
+however, that some drivers may require newer kernels in order to compile.
+
+Also, those backports are developped as best efforts, and are mainly against
+upstream stable kernels, so they may not compile with distro-patched kernels,
+nor they are meant to offer production level of support. So, if you need to
+run any prodution machine, you should really be using a Linux distribution
+that offers support for the drivers you need and has a Quality Assurance
+process when doing backports. You were warned.
Users are welcome to use, test and report any issues via the mailing
lists or via the Kernel Bug Tracker, available at:
http://bugzilla.kernel.org
-Michael Krufky maintains a backport tree, containing a subset of the
-patches from the subsystem tree that are meant to be sent to kernel
--stable team, at:
- http://git.kernel.org/http://git.kernel.org/?p=linux/kernel/git/mkrufky/v4l-dvb-2.6.x.y.git
+4. Patch submission process overall
+ ================================
-3. Other Mercurial trees used for v4l/dvb development
+When a developer believes that there are done to be merged, he sends a request
+for the patches to get merged at the v4l-dvb.git tree, at the linux-media at
+vger.kernel.org (the main mailing list for LinuxTV).
+
+The patches are analyzed and, if they look ok, they got merged into v4l-dvb.git.
+
+Currently, there are thre ways to submit a patch:
+ as an email, with the subject [PATCH];
+ as a hg pull request, with the subject [PULL];
+ as a git pull request, with the subject [GIT FIXES ...] or [GIT UPDATES ...]
+
+If the patch is developed against the Mercurial repositories, it is converted
+to the format git expects and have any backport code removed.
+
+No matter how the patch is received, after being checked and accepted by the maintainer, the patch will receive the maintainer's Certificate of Origin (Signed-off-by, as explained later within this document), and will be added
+at:
+ http://git.linuxtv.org/git/v4l-dvb.git
+
+Later, it will be backported to the -hg tree.
+
+The community also reviews the patches and may send emails informing that the
+patch has problems or were tested/acked. When those reviews happen after the
+patch merge at the tree, the patch is modified before its upstream submission.
+
+Also, the maintainer may need to modify the patch at his trees, in order to
+fix conflicts that may happen with the patch.
+
+The subsystem maintainer, when preparing the kernel patches to be sent
+to mainstream, send the patches first to linux-next tree, and waits for some
+to receive contributions from other upstream developers. If, during that period,
+he notices a problem, he may correct the patch at his upstream submission tree.
+
+5. Other Git trees used for v4l/dvb development
+ ============================================
+
+V4L/DVB Git trees are hosted at
+ git://linuxtv.org.
+
+There are a number of trees there each owned by a developer of the LinuxTV team.
+
+The submission emails are generated via the usage of git request-pull, as
+described on part II.
+
+Git is a distributed SCM, which means every developer gets his
+own full copy of the repository (including the complete revision
+history), and can work and commit locally without network connection.
+The resulting changesets can then be exchanged between repositories and
+finally merged into a common repository on linuxtv.org.
+
+The Git trees used on LinuxTV have the entire Linux Kernel tree and history
+since kernel 2.6.12. So, it generally takes some time to update it at the
+first time.
+
+There are several good documents on how to use -git, including:
+ http://git.or.cz/
+ http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
+ http://www.kernel.org/pub/software/scm/git/docs
+
+6. Other Mercurial trees used for v4l/dvb development
==================================================
-V4L/DVB driver development is hosted at http://linuxtv.org. There are a
-number of trees there each owned by a developer of the LinuxTV team.
+V4L/DVB Mercurial trees are hosted at
+ http://linuxtv.org/hg.
-When a developer believes that he has patches done to be merged, he
-sends a request the developers' mailing list and to the subsystem
-maintainer. The patches are analyzed and, if they look ok, merged into
-the master repository.
+There are a number of trees there each owned by a developer of the LinuxTV team.
-A script called hg-pull-req.pl is included that will generate this
+A script called v4l/scripts/hg-pull-req.pl is included that will generate this
request, providing a list of patches that will be pulled, links to each
patch, and a diffstat of the all patches. It will work best if Hg has
been configured with the correct username (also used by the commit
@@ -118,7 +261,446 @@ It is good practice that each developer
called 'v4l-dvb', which keeps their patches, and periodically update
this tree with the master tree's patches.
-4. Community best practices
+Mercurial is a distributed SCM, which means every developer gets his
+own full copy of the repository (including the complete revision
+history), and can work and commit locally without network connection.
+The resulting changesets can then be exchanged between repositories and
+finally merged into a common repository on linuxtv.org.
+
+There are some tutorials, FAQs and other valuable information at
+ http://selenic.com/mercurial/
+
+
+==================
+PART II. GIT TREES
+==================
+
+
+1. Kernel development procedures at the kernel upstream
+ ====================================================
+
+It is important that people understand how upstream development works.
+
+Kernel development has 2 phases:
+
+a) 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;
+
+b) 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:
+ kernel latest -rc version
+ 2.6.12 rc6
+ 2.6.13 rc7
+ 2.6.14 rc5
+ 2.6.15 rc7
+ 2.6.16 rc6
+ 2.6.17 rc6
+ 2.6.18 rc7
+ 2.6.19 rc6
+ 2.6.20 rc7
+ 2.6.21 rc7
+ 2.6.22 rc7
+ 2.6.23 rc9
+ 2.6.24 rc8
+ 2.6.25 rc9
+ 2.6.26 rc9
+ 2.6.27 rc9
+ 2.6.28 rc9
+ 2.6.29 rc8
+ 2.6.30 rc8
+ 2.6.31 rc9
+ 2.6.32 rc8
+
+In general, the announcement of a new -rc kernel gives some hints when that
+-rc kernel may be the last one.
+
+1.1. 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
+
+1.2. 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.
+
+1.3. 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).
+
+2. 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.
+
+2.1. 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.
+
+2.2. 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.
+
+3. 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.
+
+3.1. 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:
+ 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.
+
+4. Patches submitted via email
+ ===========================
+
+All valid patches submitted via email to linux-media at 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.
+
+4.1. 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 CAREFUL: several emailers including Thunderdird breaks long lines, causing
+ patch corruption.
+ In the specific case of Thunderbird, an extension is needed to send the
+ patches, called Asalted Patches:
+ https://hg.mozilla.org/users/clarkbw_gnome.org/asalted-patches/
+
+
+=========================
+Part III - BEST PRACTICES
+=========================
+
+
+1. Community best practices
========================
From accumulated experience, there are some basic rules that should
@@ -133,8 +715,144 @@ a) Every developer should follow the "ru
Documentation/SubmitChecklist
Documentation/CodingStyle
-b) All commits at Mercurial trees should have a consistent message,
- describing the patch. This is done by using:
+b) All commits at the trees should have a consistent message, describing the
+ patch.
+
+ When a patch is generated against the git tree, the better is to commit it
+ with:
+ git commit -as
+
+ This will automatically add all existing patches that got modified and add
+ your Certificate of Origin (Signed-off-by).
+
+ It will open an editor for you to provide a description of the patch.
+ The first line is a short summary describing why the patch is needed, and
+ the following lines describe what and how the patch does that.
+
+ If you've added new files, don't forget to add them before the commit, with:
+ git add <the name of each file you've created>
+
+ Before committing a patch, you need to check it with checkpatch.pl tool. This
+ is done by running:
+ git diff | ./script/checkpatch.pl -
+
+c) All patches are requested to have their coding style validated by using
+ ./script/checkpatch.pl.
+
+ On Git, the script checks not only the patch against coding style, but
+ also checks for the usage of functions that are marked to be removed
+ from the kernel ABI.
+
+d) All patches shall have a Developer's Certificate of Origin
+ version 1.1 in the commit log or the email description, signed by the
+ patch authors, as postulated in the Linux kernel source at:
+
+ Documentation/SubmittingPatches
+
+ This is done by adding Signed-off-by: fields to the commit message.
+
+ It is not acceptable to use fake signatures, e.g.:
+
+ Signed-off-by: Fake me <me@snakeoilcompany.com>
+
+ The email must be a valid one.
+ The author that is submitting the email should be at the button of
+ the author's signed-off-by (SOB) block. Other SOBs or Acked-by: will be
+ added at the bottom, marking that somebody else reviewed the patch.
+
+ Each person who is in the kernel patch submission chain (driver author
+ and/or driver maintainer, subsystem/core maintainers, etc) will
+ review each patch. If they agree, the patch will be added to their
+ trees and signed. Otherwise, they may comment on the patch, asking
+ for some review.
+
+e) Although not documented at kernel's Documentation/, a common kernel
+ practice is to use Acked-by: and Tested-by: tags.
+
+ An Acked-by: tag usually means that the acked person didn't write the
+ patch, nor is in the chain responsible for sending the patch to
+ kernel, but reviewed the patch and agreed that it was good.
+
+ A Tested-by: tag is a stronger variation of Acked-by. It means that the
+ person not only reviewed the patch, but also successfully tested it.
+
+ The better is that the patch author submitting his patches via git or hg
+ to add any acked-by/tested-by tags he received. When a patch is sent via
+ email, Patchwork tool will automatically include any such tags it receives
+ in reply together with the patch.
+
+ It is also common to receive acks after having a patch inserted at the
+ maintainer's trees. In this case, the ack will be added only at -git tree
+ used to send patches upstream.
+
+f) Another kernel's practice that is agreed to be good is that a
+ patchset should be reviewed/tested by other developers. So, a new
+ tag should be used by testers/reviewers. So, reviewers are welcome.
+ After reviewing a patchset, please send an e-mail indicating that, if
+ possible, with some additional data about the testing, with the tag:
+ Reviewed-by: My Name <myemail@mysite.com>
+ This is particularly important for Kernel to userspace ABI changes.
+
+g) If the patch also affects other parts of kernel (like ALSA
+ or i2c), it is required that, when submitting upstream, the patch
+ also goes to the maintainers of that subsystem. To do this, the
+ developer shall copy the interested parties.
+
+ When submitting a patch via e-mail, it is better to copy all interested
+ parties directly, by adding them as cc's to the email itself.
+
+ Please note that those changes generally require ack from the
+ other subsystem maintainers. So, the best practice is to first ask
+ for their acks, then commit to the development tree or send the
+ patch via email with their Acked-by: already included.
+
+ NOTE: at Mercurial tree, it used to be possible to use the cc: meta tag to
+ warn other users/mailing lists about a patch submission. However, this only
+ works when a patch is merged at the backport tree. So, it's usage is
+ considered obsolete nowadays.
+
+h) If the patch modifies the V4L or DVB API's (for example, modifying
+ include/linux/videodev2.h) file, then it must verify be verified that the
+ V4L2 specification document still builds. Of course, any changes you make
+ to the public V4L2 API must be documented anyway.
+
+ Currently, this can be done only with the Mercurial trees, by running:
+ make spec
+
+ Patches are welcome to migrate this functionality to upstream kernel DocBook
+ makefile rules.
+
+i) By submitting a patch to the subsystem maintainer, either via email
+ or via pull request, the patch author(s) are agreeing that the
+ submitted code will be added on Kernel, and that the submitted code
+ are being released as GPLv2. The author may grant additional licenses
+ to the submitted code (for example, using dual GPL/BSD) or GPLv2 or
+ later. If no specific clause are added, the added code will be
+ assumed as GPLv2 only.
+
+j) "Commit earlier and commit often". This is a common used rule at
+ Kernel. This means that a sooner submission of a patch will mean that
+ a review can happen sooner, and help the develop to address the
+ comments. This helps to reduce the life-cycle for having a changeset
+ committed at kernel at the proper time. It also means that the one
+ changeset should ideally address just one issue. So, mixing different
+ things at the same patch should be avoided.
+
+k) Sometimes, the maintainer may need to slightly modify patches you receive
+ in order to merge them, because the code is not exactly the same in your
+ tree and the submitters'. In order to save time, it may do the changes and
+ add a line before his SOB, as stated on Documentation/SubmittingPatches,
+ describing what he did to merge it. Something like:
+
+ Signed-off-by: Random J Developer <random@developer.example.org>
+ [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
+ Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
+
+2. Mercurial specific procedures
+ =============================
+
+a) With the -hg trees, some scripts are used to generate the patch. This is
+ done by running:
make commit
@@ -166,28 +884,15 @@ b) All commits at Mercurial trees should
From: line shouldn't be omitted, since it will be used for the
patch author when converting to -git.
- Priority: meta-tag will be used as a hint to the subsystem maintainer, to help him to
- identify if the patch is an improvement or board addition ("normal"), that will follow
- the normal lifecycle of a patch (e.g. will be sent upstream on the next merge tree), if
- the patch is a bug fix tree for a while without merging upstream ("low").
-
+ Priority: meta-tag will be used as a hint to the subsystem maintainer, to
+ help him to identify if the patch is an improvement or board addition
+ ("normal"), that will follow the normal lifecycle of a patch (e.g. will be
+ sent upstream on the next merge tree), if the patch is a bug fix tree for a
+ while without merging upstream ("low").
Valid values for "Priority:" are "low", "normal" and "high".
-c) All patches are requested to have their coding style validated by using
- script/checkpatch.pl. This check runs automatically by using "make commit". By default,
- it will try to use the newest version of the script, between the kernel one and a copy
- at v4l-dvb development tree.
-
- It is always a good idea to use in-kernel version, since additional tests
- are performed (like checking for the usage of deprecated API's that are
- about to be removed).
-
- It is possible to override the in-kernel checkpatch.pl location, by using
- the CHECKPATCH shell environment var to something like:
- CHECKPATCH="/usr/src/linux/scripts/checkpatch.pl"
-
-d) For "make commit" to work properly, the HGUSER shell environment var
- should be defined (replacing the names at the left):
+b)For "make commit" to work properly, the HGUSER shell environment var should
+ be defined (replacing the names at the right):
HGUSER="My Name <myemail@mysite.com>"
@@ -213,78 +918,25 @@ d) For "make commit" to work properly, t
It is strongly recommended to have those lines in .bashrc or .profile.
-e) All patches shall have a Developer's Certificate of Origin
- version 1.1 in the commit log or the email description, signed by the
- patch authors, as postulated in the Linux kernel source at:
+b) the CodingStyle compliance check on Mercurial trees are done when
+ "make check" is called. This happens also when "make commit" is done.
- Documentation/SubmittingPatches
+ There's a copy of the kernel tool at the mercurial repository. However,
+ this copy may be outdated. So, by default, it will try to use the newest
+ version of the script, between the one found at the kernel tree and
+ its own copy.
- This is done by adding Signed-off-by: fields to the commit message.
+ It is always a good idea to use in-kernel version, since additional tests
+ are performed when called from the kernel tree. Yet, those tests are
+ dependent of the kernel version, so, the results of checkpatch may not
+ reflect the latest rules/deprecated functions, if you're not using -git.
- It is not acceptable to use fake signatures, e.g.:
+ It is possible to override the in-kernel checkpatch.pl location, by using
+ the CHECKPATCH shell environment var to something like:
+ CHECKPATCH="/usr/src/linux/scripts/checkpatch.pl"
- Signed-off-by: Fake me <me@snakeoilcompany.com>
- The email must be a valid one.
- The author that is submitting the email should be at the button of
- the author's signed-off-by (SOB) block. Other SOBs or Acked-by: will be
- added at the bottom, marking that somebody else reviewed the patch.
-
- Each person who is in the kernel patch submission chain (driver author
- and/or driver maintainer, subsystem/core maintainers, etc) will
- review each patch. If they agree, the patch will be added to their
- trees and signed. Otherwise, they may comment on the patch, asking
- for some review.
-
-f) Although not documented at kernel's Documentation/, a common kernel
- practice is to use Acked-by: tag.
-
- An Acked-by: tag usually means that the acked person didn't write the
- patch, nor is in the chain responsible for sending the patch to
- kernel, but tested or reviewed the patch and agreed that it was good.
-
- A patch acked-by can be added at hg trees, if received by each tree
- maintainer. It is also common to receive acks after having a patch
- inserted at master repository. In this case, the ack will be added
- only at -git tree.
-
-g) Another kernel's practice that is agreed to be good is that a
- patchset should be reviewed/tested by other developers. So, a new
- tag should be used by testers/reviewers. So, reviewers are welcome.
- After reviewing a patchset, please send an e-mail indicating that, if
- possible, with some additional data about the testing, with the tag:
- Reviewed-by: My Name <myemail@mysite.com>
- This is particularly important for Kernel to userspace ABI changes.
-
-h) If the patch also affects other parts of kernel (like ALSA
- or i2c), it is required that, when submitting upstream, the patch
- also goes to the maintainers of that subsystem. To do this, the
- developer shall copy the interested parties.
-
- At Mercurial tree, this can be handled automatically by the LinuxTV
- scripts, by using the cc: meta tag, together with the Signed-off-by
- lines. Something like:
-
- CC: someotherkerneldeveloper@someplace
- Signed-off-by: nowhere <nowhere@noplace.org>
-
- This way, when a patch arrives Mercurial hg tree, a mailbomb script
- will copy the proper interested parties.
-
- When submitting a patch via e-mail, it is better to copy all interested
- parties directly, by adding them as cc's to the email itself.
-
- Please note that those changes generally require ack from the
- other subsystem maintainers. So, the best practice is to first ask
- for their acks, then commit to the development tree or send the
- patch via email with their Acked-by: already included.
-
-i) If the patch modifies the include/linux/videodev2.h file, then you
- must also run 'make spec' to verify that the V4L2 specification
- document still builds. Of course, any changes you make to the public
- V4L2 API must be documented anyway.
-
-j) Sometimes, mainstream changes affect the v4l-dvb tree, and must be
+c) Sometimes, mainstream changes affect the v4l-dvb tree, and must be
backported to the v4l-dvb tree. This kind of commit to the Mercurial
tree should follow the rules above and should also have the line:
@@ -292,7 +944,7 @@ j) Sometimes, mainstream changes affect
Patches with this line will not be submitted upstream.
-k) Sometimes it is necessary to introduce some testing code inside a
+d) Sometimes it is necessary to introduce some testing code inside a
module or remove parts that are not yet finished. Also, compatibility
tests may be required to provide backporting.
@@ -343,7 +995,7 @@ k) Sometimes it is necessary to introduc
See the file v4l/scripts/gentree.pl for a more complete description
of what kind of code will be kept and what kind will be removed.
-l) To import contributed stuff to a developer's, a script is provided.
+e) To import contributed stuff to a developer's, a script is provided.
This allows an easy import of mbox-based patch emails.
This is done with (called from the root tree directory):
@@ -360,46 +1012,20 @@ l) To import contributed stuff to a deve
that can be applied/unapplied for testing. mailimport trusts on it to work,
so, this extension should be enabled for mailimport script to work.
-m) By submitting a patch to the subsystem maintainer, either via email
- or via pull request, the patch author(s) are agreeing that the
- submitted code will be added on Kernel, and that the submitted code
- are being released as GPLv2. The author may grant additional licenses
- to the submitted code (for example, using dual GPL/BSD) or GPLv2 or
- later. If no specific clause are added, the added code will be
- assumed as GPLv2 only.
+3. Knowing about newer patches committed at the development repositories
+ =====================================================================
-n) "Commit earlier and commit often". This is a common used rule at
- Kernel. This means that a sooner submission of a patch will mean that
- a review can happen sooner, and help the develop to address the
- comments. This helps to reduce the life-cycle for having a changeset
- committed at kernel at the proper time. It also means that the one
- changeset should ideally address just one issue. So, mixing different
- things at the same patch should be avoided.
+There are patchbomb scripts at linuxtv.org that will send one copy of
+each patch applied patch to v4l-dvb.git and v4l-dvb trees to announce
+when a patch is received. This announcement goes to the linuxtv-commits mailing list, hosted on linuxtv.org.
-o) Sometimes, the maintainer may need to slightly modify patches you receive
- in order to merge them, because the code is not exactly the same in your
- tree and the submitters'. In order to save time, it may do the changes and
- add a line before his SOB, as stated on Documentation/SubmittingPatches,
- describing what he did to merge it. Something like:
+The Mercurial script also currently sends a copy of the patch to:
- Signed-off-by: Random J Developer <random@developer.example.org>
- [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
- Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
+1) The patch author (as stated on the From: field in the patch comments);
-5. Knowing about newer patches committed at master hg repository
- =============================================================
+2) The patch committer (the "user" at hg metadata);
-There's a patchbomb script at linuxtv.org that will send one copy of
-each patch applied to -hg tree to:
-
-1) The subscribers of the linuxtv-commits mailing list, hosted on
- linuxtv.org;
-
-2) The patch author (as stated on the From: field in the patch comments);
-
-3) The patch committer (the "user" at hg metadata);
-
-4) All people with Signed-off-by:, Acked-by:, or CC: metadata clause
+3) All people with Signed-off-by:, Acked-by:, or CC: metadata clause
in the patch's comment.
If, for some reason, there's no "From:" metatag (or it is on the first
@@ -407,83 +1033,19 @@ line, instead of the second one), someti
filling patch authorship wrongly. So people should take care to properly
commit patches with "From:".
-6. Patch handling for kernel submission
- ====================================
+It is recommended that the developers who submit a pull request via Mercurial
+to not touch on the submission tree, until he receives the notification email,
+since, even after being merged at -git, the backport maintainer will need to
+merge it.
-The subsystem maintainer, when preparing the kernel patches to be sent
-to mainstream (or to -mm series), uses some scripts and a manual
-procedure, based on a quilt-like procedure, where a patch series file is
-generated, and patches can be handled one by one. This means that -git
-patches can be properly fixed, when required, if not already sent to
-mainstream, to fulfill the best practices and resolve conflicts with
-other patches directly merged in mainstream.
-
-There's a delay between updating a patch at master and sending it to
-mainstream. During this period, it is possible to review a patch. The
-common situations are:
-
-1) If a patch at master tree receives a late Acked-by: or a
-Reviewed-by:, this can be added at -git tree;
-
-2) If somebody fully nacks a patch applied at -hg, A reverse patch
-can be applied at -hg, and the original patch can be removed -git;
-
-3) If somebody partially nacks a patch or sends a reviewing patch,
-the -git patch may be a result of the merger of the two patches.
-
-By merging both patches at -git will allow avoiding storing unnecessary
-patch history details at -git and at Mainstream.
-
-Those changes will require some manual sync between -git and -hg, it is
-better to avoid those circumstances.
-
-During the procedure of generating kernel patches, the maintainer uses
-to do a diff between the kernel tree and v4l-dvb Mercurial tree
-(without any backport code there). If there are discrepancies, a
-backport patch from mainstream to v4l-dvb is generally applied by the
-maintainer.
-
-8. Commit windows
- ==============
-
-Kernel development occurs on some cycles, according with the following
-picture:
-
------------- 2 week ------------ --------------- ---------
-| 2.6.(x-1) | ---------> | 2.6.x-rc1 | .. | 2.6.x-rc[n] | --> | 2.6.x |
------------- ------------ --------------- ---------
- Submission
- Window
-
-Once a kernel release is done (for example, 2.6.(x-1) version), a
-submission window for the newer features and board additions to the next
-kernel release should start. This means that the subsystem maintainer
-will use this window to submit the work that were done during 2.6.(x-2)
-time.
-
-For this to happen, patches for 2.6.x should be already at the subsystem
-maintainers -hg tree before the release of 2.6.(x-1), to allow proper
-testing.
-
-After the submission window, only patches with bug fixes should be sent
-to mainstream. This means that the subsystem maintainer will separate
-those patches from the submitted ones for kernel submission during -rc
-cycle. Generally, the stabilization process (rc kernels) takes from 5
-to 7 weeks.
-
-To make life easier for the subsystem maintainer, please add:
-[FIX] at the subject of the submitted emails or at the commit first
-lines.
-
-7. Patch submission from the community
+4. Patch submission from the community
===================================
Patch submission is open to all the Free Software community. The general
procedure to have a patch accepted in the v4l/dvb subsystem and in the
kernel is the following:
-a. Post your patches to the corresponding mailing list for review and
- test by other people, at:
+a. Post your patches to the mailing list for review and test by other people:
linux-media@vger.kernel.org
This mailing list doesn't require subscription, although
@@ -518,7 +1080,10 @@ g. If it is a newer driver (not yet in o
please send the patch to the subsystem maintainer, C/C the proper
mailing lists.
-8. Identifying regressions with Mercurial
+h. Prefer to submit your patches against git, especially if it contains fixes
+ that needs to go upstream.
+
+5. Identifying regressions with Mercurial
======================================
The better way for you to identify regressions with Mercurial is to
@@ -586,7 +1151,22 @@ 8. Identifying regressions with Mercuria
you are, you can do something like:
hg log -r `hg id|cut -d' ' -f 1`
-9. Creating a newer driver
+6. Identifying regressions with Git
+ ================================
+
+ A similar bisect procedure to identify broken patches exist on git, and it
+ is used not only by LinuxTV. So, it is very important that any applied
+ patch at the kernel don't break compilation, to avoid affecting the bisect
+ procedures.
+
+ There are several good texts explaining how to use bisect with git. Some
+ recommended procedures can be seen at:
+
+ http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#using-bisect
+ http://www.kernel.org/pub/software/scm/git/docs/git-bisect.html
+
+
+7. Creating a newer driver
=======================
This quick HOWTO explains how to create a new driver using v4l-dvb
@@ -609,18 +1189,21 @@ 9. Creating a newer driver
| `-- dvb <== DVB userspace API files
`-- media <== V4L internal API files
- 9.1 - simple drivers
- ====================
+ When using Mercurial trees, an additional /linux prefix should be added
+ on all patches
+
+7.1. Simple drivers
+ ==============
For very simple drivers that have only one .c and one .h file, the
recommended way is not to create a newer directory, but keep the
driver into an existing one.
Assuming that the will be V4L+DVB, the better place for it to be is under
- /linux/drivers/media/video. Assuming also that the newer driver
+ /drivers/media/video. Assuming also that the newer driver
will be called as "newdevice", you need to do:
- a) add at /linux/drivers/media/video/Kconfig something like:
+ a) add at /drivers/media/video/Kconfig something like:
config VIDEO_NEWDEVICE
tristate "newdevice driver"
@@ -631,13 +1214,13 @@ config VIDEO_NEWDEVICE
Say Y if you own such a device and want to use it.
- b) add at /linux/drivers/media/video/Makefile something like:
+ b) add at /drivers/media/video/Makefile something like:
obj-$(CONFIG_VIDEO_NEWDEVICE) += newdevice.o
EXTRA_CFLAGS = -Idrivers/media/video
- 9.2 - bigger drivers
- ====================
+7.2. Bigger drivers
+ ==============
In this case, a driver will be splitted into several different source
codes. Ideally, a source file should have up to 1000 source code
@@ -647,8 +1230,8 @@ EXTRA_CFLAGS = -Idrivers/media/video
is called "newdevice", all that is needed to add the newer driver is:
a) create a newer dir with your driver, for example:
- /linux/drivers/media/video/newdevice
- b) create /linux/drivers/media/video/newdevice/Kconfig with something
+ /drivers/media/video/newdevice
+ b) create /drivers/media/video/newdevice/Kconfig with something
like:
config VIDEO_NEWDEVICE
@@ -660,23 +1243,27 @@ config VIDEO_NEWDEVICE
Say Y if you own such a device and want to use it.
- c) create /linux/drivers/media/video/newdevice/Makefile with
+ c) create /drivers/media/video/newdevice/Makefile with
something like:
obj-$(CONFIG_VIDEO_NEWDEVICE) += newdevice.o
EXTRA_CFLAGS = -Idrivers/media/video
- d) Add your driver directory at /linux/drivers/media/Makefile:
+ d) Add your driver directory at /drivers/media/Makefile:
obj-$(CONFIG_VIDEO_NEWDEVICE) += newdevice/
- e) Add your driver directory at /linux/drivers/media/Kconfig:
+ e) Add your driver directory at /drivers/media/Kconfig:
source "drivers/media/video/newdevice/Kconfig"
After that, you will be able to use v4l-dvb Makefile to compile your
- driver. With:
+ driver.
- make help
+ In order to test if your patch is properly compiling, you'll need to
+ enable its compilation by using make menuconfig/make qconfig/make xconfig.
+ After that, you can test if your patch compiles well with:
- you'll see some useful syntax that may help your development.
+ make drivers/media (on git)
+ or
+ make (on hg)