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

From LinuxTVWiki
Jump to navigation Jump to search
(→‎If the Modules load correctly:: update links and round out discussion)
Line 128: Line 128:
'''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.
'''2. They should provide some indication within your system log''': you can consult the output from the "<code>dmesg</code>" command or directly review your system log file (typically housed within the ''/var/log'' directory) for indication that they have been successfully loaded and that the device is now correctly configured for operation. Examples of successful module loads are provided by users under the "Sample kernel output" section in many device articles witin the wiki.


'''3. The device manager [[Wikipedia:udev|udev]] will "automagically" create [[device nodes]] on ''/dev''''': <br>
'''3. The device manager [[Wikipedia:udev|udev]] will "automagically" create appropriate [[Device nodes and character devices|device nodes]] on ''/dev''''': <br>
'''(a) For a DVB device''', you should now have a non-empty ''/dev/dvb'' directory. You can check on whether this is true for you with the following command:
'''(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>
: <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,
(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>
: <code>ls -l /dev/dvb/adapter0 </code>
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
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>
: <code>ls -l /dev/dvb/adapter* </code>


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


===If the Modules did not load correctly or the device is still not configured correctly for use:===
===If the Modules did not load correctly or the device is still not configured correctly for use:===

Revision as of 03:31, 7 September 2009

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 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, the V4L-DVB tree is currently backwards compatible with vanilla kernels from currently 2.6.16 onwards.

In the past, backwards compatibility meant 2.6.12 and greater, but, as time has progressed, the number of significant (and progressive!) changes introduced within the drivers have made it extremely difficult, if not impossible, to provide as thorough compatibility between the newest V4L-DVB releases and older kernels. Consequently, as mentioned above, in order to install a recent snapshot of the V4L-DVB drivers onto your system, you will need to be utilizing a kernel 2.6.16 or greater.

If you have configured the kernel manually, please note that some capabilities should be enabled like EVDEV. You should also investigate installing the "udev" package (for kernels >= 2.6.15) which automatically populates the /dev directory when devices are found. Stock kernels should have everything required.

Additional Software Requrirements

In order to be able to build the V4L-DVB kernel driver modules, you will need:

  • kernel-source or kernel-headers
  • (fedora only) kernel-devel
  • make
  • gcc

If these packages are not currently installed on your system, you should do so now.

You May Also Wish to Install Mercurial

Using Mercurial (Hg) provides several advantages for the end user:

  • easy to switch between LinuxTV driver snapshots
  • easy upgrading in the future
  • an advanced method (i.e. hg bisect) for finding the source commit that introduces a bug/error into the driver source
  • blah blah blah

Some Linux distributions already include Hg within their package repositories The following provides examples of how to install the Mercurial software package for some distributions (Note that [sudo] means that you only have to specify "sudo" if you aren't root, otherwise omit it.):

  • On Debian-based distributions use the following command to install all required software:
$ [sudo] apt-get install mercurial linux-headers-$(uname -r) build-essential
  • On Gentoo-based distributions use the following command to install mercurial. Other dependencies are installed in main system tree.
$ [sudo] emerge mercurial
  • On Fedora it's just as easy:
$ [sudo] yum install mercurial
$ [sudo] urpmi mercurial

If your distribution doesn't include Mercurial, you can download a binary package or retrieve the source and build it yourself. Note: Mercurial requires python 2.3 or greater.

Retrieving the Latest V4L-DVB Source Code

After installing all required software, download a copy of the latest source code from LinuxTV. You can do that either by:

Tarball

Grabbing a copy available as a compressed Tarball (both bz2 and gz formats), from http://linuxtv.org/repo This is likely the pathway the most end users will take, in particular those who do not anticipate reinstalling the device drivers very often. Note: you will have to uncompress the source code.

Using Mercurial

If you have choosen to install Mercurial, the source code for the V4L-DVB kernel modules is available via an Hg tree on LinuxTV using the following command from a console:

hg clone http://linuxtv.org/hg/v4l-dvb

This creates a directory called v4l-dvb in the current working directory.

Similarly, if you also wish to retrieve the dvb-apps source tree, you can do so with:

hg clone http://linuxtv.org/hg/dvb-apps

To Update the Hg Sources at Some Future Point in Time

Update your local copy of the source code later on with the following command (entered from the previously created v4l-dvb directory; i.e. cd v4l-dvb):

hg pull -u http://linuxtv.org/hg/v4l-dvb

Then, when that job completes, you can get your local copy ready to compile by entering the following command:

 hg update

Build and Installation Instructions

Regardless of the method you used to acquire the V4L-DVB source code, the process of building the driver modules, and then installing them, is the same, and is performed from the command line within a console.

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

Building/Compiling the Modules

Start by changing into the directory that contains the previously downloaded source:

cd v4l-dvb

Build/compile the modules from source with the command:

make

This will create a /v4l directory within which the completed *.ko module files will be written. 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. The build progress can be observed via the console output. 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 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 a bug report. In addition, Hans Verkuil has set up an automated daily build of the V4L-DVB source upon all supported kernels, as well as upon several CPU architectures. A brief synopsis of the results from these tests is published each day on the Linux-media mailing list under a message subject heading prefix of "[cron job]". A link to more detailed results of these tests is also provided within that message. In general, if the source builds correctly, it is likely that the drivers will work, though this is not a guarantee.

If you do run into any problems during the build step, you should:

  • consult the results reported in the [cron job] message on the mailing list, to see if the issue is already known
  • if it is a new issue, please inform the developers either via the mailing list 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 the article's talk page

Installing the 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: 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 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 "Gathering Information About Your Unidentified/Unsupported Device". Once you have established the device's identity, 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