How to Obtain, Build and Install V4L-DVB Device Drivers: Difference between revisions

From LinuxTVWiki
Jump to navigation Jump to search
m (How to build from Mercurial moved to How to Obtain, Build and Install V4L-DVB Device Drivers: name; you don't build from Hg, you obtain from Hg. The build process is same whether you grabbed a tarball or used Hg to acquire.)
(removing more shell prompts)
(94 intermediate revisions by 25 users not shown)
Line 1: Line 1:
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.
== Check kernel version ==


{{Note|This article assumes that:
First of all, you need a quite recent kernel.
* 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.
The v4l-dvb tree is backwards compatible with recent vanilla kernels, from 2.6.16 onwards.
* you have already physically installed the hardware device into, or connected it to, your system. (Refer to the manufacturer's instructions for such details)}}.
If you configured the kernel manually, please note that some capabilities should be enabled like EVDEV.
Stock kernels usually have everything required.
You also need to install the kernel-source package to have kernel headers.


== Install Mercurial ==
== Software Requirements ==
===Kernel Support===
The LinuxTV V4L-DVB drivers will work only in conjunction with relatively modern 2.6 kernels; specifically 2.6.31 and up.


===Additional Software Requrirements===
V4L and DVB kernel modules are available via Mercurial.
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 and Ubuntu) libdigest-sha-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==
To acquire the latest sources, you must first have mercurial installed (which requires python 2.3).
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 (either within a console or terminal emulator). The "basic" method is likely appropriate for most end users, though, in particular cases, some users will have to use the slightly more "manually intensive" approach (which is effectively, for all intents and purposes, really just the same as the "basic" method, but performs the steps in a piecemeal fashion which 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 any of the approaches, make sure you have installed all the prerequisite software listed above.
Some Linux distributions already include it. In Debian, just do "apt-get install mercurial".


{{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 your distribution doesn't include it, you can download a
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>.}}
[http://www.selenic.com/mercurial/wiki/index.cgi/BinaryPackages binary package] or [http://www.selenic.com/mercurial/wiki/index.cgi/Download retrieve the source].


{{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]] }}
== Retrieve v4l-dvb sources ==


Now you need to pull the tree from hg.


To retrieve the v4l-dvb source tree:


{| class="wikitable"
hg clone http://linuxtv.org/hg/v4l-dvb
|+'''Retrieving the Source Code & Building/Compiling the Modules'''
|-
! "Basic" Approach !! Developer's Approach !! More "Manually Intensive" Approach


|-
To update the sources later on:
| valign=top |
git clone git://linuxtv.org/media_build.git
''(alternately to get only the latest revision without history)
git clone --depth=1 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.
cd v4l-dvb
hg pull -u http://linuxtv.org/hg/v4l-dvb


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.
To retrieve the dvb-apps source tree:
| valign=top |
git clone git://linuxtv.org/media_build.git
''(or ~ $ git clone --depth=1 git://linuxtv.org/media_build.git)''
cd media_build
./build --main-git
{{Note|'''The build script will clone the entire media-tree.git, which will take some time'''}}
In order to modify a driver foo.c:


cd media
hg clone http://linuxtv.org/hg/dvb-apps
gedit drivers/media/video/foo.c
make -C ../v4l
make -C ../ install
make -C .. rmmod
modprobe foo


(some procedure to test the "foo" driver)
== Build the Modules ==


To generate a patch, use:
Change into the v4l-dvb directory:


git commit -as
cd v4l-dvb


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


git send-email HEAD^1
make


or, to send a patch series:
Then install the modules:


git send-email ''initial_branch''
make install


Where ''initial_branch'' is the name of a branch of a changeset number for the last patch before your changes.
The command above will copy *.ko module files into your /lib/modules kernel directories.


|
== Load and Unload the modules ==
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.
To remove (rmmod) all modules at once from the running kernel (in memory):


<div style="border: solid 1px; border-color: blue; margin: 1em; padding: 1em; background-color: Lavender;">
make unload
'''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>
To insert (insmod) all modules at once into the running kernel, without the need to install them:


Next, build/compile the modules from the source code with the command:
make load
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'' )}}


|}
To perform the two commands above in a single step:
===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.
make reload


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.
Usually correctly installed modules will show some info in dmesg, errors will appear in dmesg also.


{{Note|'''The Daily Automated Build Tests'''<br>
== Errata - Compilation ==
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:
If compilation fails on v4l-dvb/v4l/dvb_net.c with errors (kernel 2.6.17):
* 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.
error: 'struct net_device' has no member named 'xmit_lock'


== Installing the Compiled Driver Modules ==
Then edit the v4l-dvb/v4l/dvb_net.c file, go to the error lines and replace this text:
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.:
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,18)
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==
by this one:
{|
| valign=top |
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,17)
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>
The compilation should now continue.


'''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.
At this point, check to see if your device is working. Usually, the make install will install the modules in the kernel module folder, which will autoload the drivers on boot. I ran the below commands and it locked up my box and caused problems. For example, do...


Or, on the other hand,
<pre>dmesg | grep -i saa
[ 33.089365] saa7133[0]: subsystem: 17de:7350, board: Kworld ATSC110 [card=90,autodetected]
</pre>


'''2. Take care of business yourself:''' More experienced users might prefer to use more eloquent approaches. For example, using
If this comes back with your card name to something other than "UNKNOWN", then you on on the right track and do not have to do what is listed below.
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% |
== Errata - Compilation - Kernels before 2.6.22 ==
<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.
On old kernels (2.6.22 and older) there is a set of device drivers which will not compile as they require later kernel for the devices to be supported, and this will result in compilation errors. These can be fixed by disabling the compilation of unneeded (ones that require newer kernel) modules
<pre>
</div>
|}
make allmodconfig
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.
</pre>


===If the Modules load correctly:===
Still it seems that for kernels older than 2.6.20 the compatibility may have been broken. ( If you figure out a way to compile on 2.6.17 put it here. I updated my kernel to 2.6.20 after trying a while)
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.
== Errata - Loading Modules ==


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!)
After running the "make install" command, you might end up with *.ko files and their older compressed version *.ko.gz in the same directory. In this case, the modprobe command might fail (example with the saa7134 module):


'''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.
sudo modprobe saa7134
FATAL: Error inserting saa7134 (/lib/modules/2.6.17-8mdv/kernel/drivers/media/video/saa7134/saa7134.ko):\
Unknown symbol in module, or unknown parameter (see dmesg)


'''3. The device manager [[Wikipedia:udev|udev]] will "automagically" create appropriate [[Device nodes and character devices|device nodes]] on ''/dev''''': <br>
The dmesg then returns a list of 'unknown symbol' error messages because of compatiblity issues between the new *.ko module files and the old *.ko.gz ones:
'''(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:
Unknown symbol ir_codes_pinnacle_color
: <code>ls -l /dev/v4l</code>
Unknown symbol ir_codes_encore_enltv
Digging further,
Unknown symbol ir_codes_proteus_2309
: <code>ls -l /dev/v4l/by-path </code>
Unknown symbol ir_rc5_timer_keyup
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
Unknown symbol ir_codes_asus_pc39
: <code>ls -l /dev/video* </code>
Unknown symbol ir_rc5_timer_end
Unknown symbol ir_codes_pinnacle_grey


===If the Modules did not load correctly or the device is still not configured correctly for use:===
All conflicting *.ko.gz files must be removed. The following command line can help you locate these conflicting files in all your installed kernels:
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'''
for file in `find /lib/modules -name "*.ko"`; do if [[ -e $file.gz ]]; then echo "$file.gz should be removed"; fi; done
* 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'''
Usually all conflicting module files resulting of v4l-dvb installation will be located in:
* If a module was, for whatever reason, not loaded, you can try manually loading it with the appropriate ''modprobe'' command.


'''Unresolved Symbols'''
/lib/modules/[your kernel version]/kernel/drivers/media
* 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
Once the conflicting *.ko.gz have been moved elsewhere or renamed (to *.ko.gz.disabled for example), use the v4l-dvb reload command (I usually add a depmod for safety in order to rebuild modules dependencies):
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
make reload
depmod -a
depmod -a
Your new modules should now be loaded correctly.


'''A Note on Firmware'''
Your modules should now be loaded correctly.
* 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.

== More Errata ==

Comment April 06
A kernel 2.6.12 wouldn't build the modules but 2.6.16 worked well.
I would suggest cd /usr/src/linux before retrieving the mercurial patches - the scripts couldn't find the kernel headers otherwise.

After following the steps above and getting down all needed sources I get the following output does this mean this driver does support 64bit kernels?
root@1[v4l-dvb]# make
make -C /usr/local/src/v4l-dvb/v4l
make[1]: Entering directory `/usr/local/src/v4l-dvb/v4l'
scripts/make_makefile.pl
No version yet.
Updating/Creating .config
File not found: /lib/modules/2.6.15-27-desktop64-smp/build/.config at ./scripts/make_kconfig.pl line 30.
make[1]: Leaving directory `/usr/local/src/v4l-dvb/v4l'
make[1]: Entering directory `/usr/local/src/v4l-dvb/v4l'
Updating/Creating .config
File not found: /lib/modules/2.6.15-27-desktop64-smp/build/.config at ./scripts/make_kconfig.pl line 30.
make[1]: *** No rule to make target `.myconfig', needed by `config-compat.h'. Stop.
make[1]: Leaving directory `/usr/local/src/v4l-dvb/v4l'
make: *** [all] Error 2

or do I move my sources?

First, try this step
cd /var/v4l-dvb (or wherever you put the download)
make distclean
make clean

Another reason for this issue is because your symbolic link for /lib/modules/<kernel-version>/build is broken. Before running make, remove the link and create a new pointing to the right location.


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:
For your example above,
<pre> dvb-ttpci: could not load firmware, file not found: dvb-ttpci-01.fw
rm /lib/modules/2.6.15-27-desktop64-smp/build
dvb-ttpci: usually this should be in /usr/lib/hotplug/firmware or /lib/firmware
ln -s /usr/src/kernels/2.6.15-27-desktop64-smp/build /lib/modules/2.6.15-27-desktop64-smp/build
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:
and then, the remaining steps should work fine.
*/lib/firmware
Consult resources for your distro if its preferred location is somewhere otherwise.


==Some Further Documentation==
'''Note: On Ubuntu 8.04 (Hardy Heron),''' installation had the same error as above but was solved somewhat differently.
* See [[Testing your DVB device]] for instructions on testing your newly installed DVB device
First you must install the linux-headers and the linux kernel source. To do so, type the following (and those are back ticks, not single quotes, people!)
sudo apt-get install linux-headers-`uname -r` linux-source
You'll notice that the source code is installed as a tar file in the /usr/src directory. This is not particularly useful. Let's untar it, do so by typing:
sudo tar xjf /usr/src/linux-source-`uname -r`.tar.bz2 -C /usr/src
And then create a symbolic link to the source (if there isn't already one) by typing:
cd /usr/src
sudo rm linux
sudo ln -s /usr/src/linux-source-`uname -r` linux
'''Finally, let's make sure we have the /lib/modules/`uname -r`/build directory pointing to THE HEADERS... NOT THE KERNEL SOURCE.''' This is the million dollar hurdle, and it bears repeating. The /lib/modules/<your kernel version>/build should point to the correct linux-headers, not the source code of the kernel. (Yes, weird, I know)
Type:
cd /lib/modules/`uname -r`
sudo rm build
sudo ln -s /usr/src/linux-headers-`uname -r` build
Now you can go to your v4l source directory that you downloaded using hg, and do a
rm v4l/.version
make
and all should be good with the world. This was a supreme PITA, so I am hopeful that this will save somebody their sanity.


If you are having problems with a module not compiling, and it is not important to you, do a
find . -name my_bad_module_name.c -print


[[Category:Software]]
Then go to the directory that contains it. You will find a Makefile. Edit it and put a # at the start of the line that has the module name.
[[Category:Drivers]]

Revision as of 21:44, 20 December 2015

The LinuxTV project hosts the latest set of Linux kernel driver modules for 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 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 2.6.31 and up.

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 and Ubuntu) libdigest-sha-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 (either within a console or terminal emulator). The "basic" method is likely appropriate for most end users, though, in particular cases, some users will have to use the slightly more "manually intensive" approach (which is effectively, for all intents and purposes, really just the same as the "basic" method, but performs the steps in a piecemeal fashion which 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 any of the approaches, 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. This seems to be fixed 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.
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 "firedtv=m" to "firedtv=n".
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. [Source]


Retrieving the Source Code & Building/Compiling the Modules
"Basic" Approach Developer's Approach More "Manually Intensive" Approach
git clone git://linuxtv.org/media_build.git
(alternately to get only the latest revision without history)
git clone --depth=1 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.

git clone git://linuxtv.org/media_build.git 
(or ~ $ git clone --depth=1 git://linuxtv.org/media_build.git)
cd media_build 
./build --main-git
Note: The build script will clone the entire media-tree.git, which will take some time

In order to modify a driver foo.c:

cd media
gedit drivers/media/video/foo.c
make -C ../v4l
make -C ../ install
make -C .. rmmod
modprobe foo
(some procedure to test the "foo" driver)

To generate a patch, use:

git commit -as

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

git send-email HEAD^1

or, to send a patch series:

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.

Optional Pre-Compilation Steps
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.

  • make rminstall ... 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)
  • make distclean ... 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
  • make menuconfig ... 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 make help.

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


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


First Use: Out with the Old, In with the New

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 clean slate state, you could either:

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.

For Advanced Users
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 all V4L-DVB device drivers into memory, and that may introduce instability, or complicate testing.

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 cat /proc/modules or, even better, lsmod 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 "dmesg" 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 udev will "automagically" create appropriate device nodes on /dev:
(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:

ls -l /dev/dvb/

(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,

ls -l /dev/dvb/adapter0

reveals the 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

ls -l /dev/dvb/adapter*

(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:

ls -l /dev/v4l

Digging further,

ls -l /dev/v4l/by-path

reveals the symbolic links to the 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

ls -l /dev/video*

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 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 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 [[ -e $file.gz ]]; 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 for the device not being loaded; some devices also require a 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:

  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/

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 "Determining the Device's Identity". Once you have established which particular device you are in possession of, you can then move on to 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