Difference between revisions of "Development: How to add support for a device"

From LinuxTVWiki
Jump to: navigation, search
m (bttv-gallery: minor wording)
(Determining the Device's Identity: update bttv-gallery section)
 
(5 intermediate revisions by 2 users not shown)
Line 4: Line 4:
 
The very first thing you should do is find out how your device identifies itself:
 
The very first thing you should do is find out how your device identifies itself:
  
'''For PCI or PCIe devices'''
+
'''For PCI/PCIe devices''' - use the command:
Use the ''lspci'' and '''lspci -vn''' commands.
+
:<code>$ /sbin/lspci -vnn</code>
  
'''For USB based devices'''
+
'''For USB based devices''' - use the command:
Use the ''lsusb'' and ''lsusb -v''
+
:<code>$ /sbin/lsusb -v</code>
  
The above should provide you with the identify of main bridge chip as well as the important piece of infomation known as the device's subsystem ID.
+
The output generated from the above should provide you with the identify of the main bridge chip as well as the important piece of information known as the device's subsystem ID.
  
Next, you should try to identify the component ICs/chips that your device uses. There can be tuner chips, demodulators, or both, hidden in the metallic box connected directly to the antenna input. Often the tuner type is printed under a sticker.
+
Next, you should try to identify the other component ICs/chips that your device uses. In regards to TV tuner devices, often the tuner chip and demodulator(s) are hidden within a metallic box connected directly to the antenna input.   In such cases, this tuner module will usually have an identifying model name/type printed upon it's face, though it is also just as common for this to be obscured underneath a sticker that the device manufacturer has laid over top.  With care, you can usually peel back the manufacturer's device sticker to discover the tuner module's own part identifier label or stamp.  
  
You can find a lot of cards on http://bttv-gallery.de - a very useful resource for cards identification.  
+
Note: You can find a lot of useful device related information:
 +
* here in the wiki
 +
* in the [[Development:_How_to_add_support_for_a_device#bttv-gallery|bttv-gallery]]
 +
* and by having a look at MS-Windows drivers (in particular, the .inf files), as they often contain a lot of particulars about a device's hardware components
  
Another useful place to look is MS-Windows drivers. They often contain a lot of information about cards' hardware.
 
  
 
== Case 1: Development steps for when your device uses components for which drivers already exist==
 
== Case 1: Development steps for when your device uses components for which drivers already exist==
Extending support for your card under such circumstances can range from being a trivial matter to one which requires some patience and discovery through the process of trial & error.
+
Extending support for your device under such circumstances can range from being a trivial matter to one which requires some patience and discovery through the process of trial & error.
  
First off, download the latest V4L-DVB source code from Mercurial and search for a device as similar as your own - something like your device may already be supported but with another name. In such a case, you can copy a similar entry and fill in the values for the new card.  For example:  
+
First off, [[How to Obtain, Build and Install V4L-DVB Device Drivers|download the latest V4L-DVB source code from Git]] and search for a device that is similar to your own - something like your device may already be supported but with another name. In such a case, you can copy a similar entry and fill in the values for the new device.  For example:  
 
* for a bttv chip you add to bttv-cards.c and bttv.h,  
 
* for a bttv chip you add to bttv-cards.c and bttv.h,  
 
* for cx88 chip - cx88-cards.c and cx88.h,  
 
* for cx88 chip - cx88-cards.c and cx88.h,  
Line 27: Line 29:
 
... and so forth.
 
... and so forth.
  
==== Finding the correct tuner ====
+
==== For TV tuner devices: Finding the correct tuner ====
 
In more than 90% of all cases something like.. first test one to your norm specific type with older Philips API, then test LG API and if there are still missing channels in UHF test MK3 API types will succeed. To find the exact takeover and radio config might be further steps, but most likely this can be/is covered by one of the existing types already.  
 
In more than 90% of all cases something like.. first test one to your norm specific type with older Philips API, then test LG API and if there are still missing channels in UHF test MK3 API types will succeed. To find the exact takeover and radio config might be further steps, but most likely this can be/is covered by one of the existing types already.  
 
   
 
   
 
At least it will usually take only three tuners to reach this point and if you find all three API types don't work, then ...
 
At least it will usually take only three tuners to reach this point and if you find all three API types don't work, then ...
 
   
 
   
To check for the tda9887 on MK3 and mt32xx types can be done at once or as a next step. Since also the Philips silicon tuners should be well detected now, we can identify such like the yet unsupported XCeive types quite well. They seem to fail safely upon the initialization sequence with tuner=54 if I got Carsten right. So the really difficult/new ones should show up quickly enough and we can try to prepare a list of typical addresses for new devices like channel decoders, second eeproms, most likely hidden analog demodulators and such.
+
To check for the tda9887 on MK3 and mt32xx types can be done at once or as a next step. Since also the Philips silicon tuners should be well detected now, we can identify such like the yet unsupported Xceive types quite well. They seem to fail safely upon the initialization sequence with tuner=54 if I got Carsten right. So the really difficult/new ones should show up quickly enough and we can try to prepare a list of typical addresses for new devices like channel decoders, second eeproms, most likely hidden analog demodulators and such.
  
 
That the multi and hybrid types can have other issues too, like antenna input/filter/demodulator RF-amplifier switching and the like is above simple analog tuner programming and not yet fully investigated for all new types, but it seems there is some very good progress too.
 
That the multi and hybrid types can have other issues too, like antenna input/filter/demodulator RF-amplifier switching and the like is above simple analog tuner programming and not yet fully investigated for all new types, but it seems there is some very good progress too.
Line 39: Line 41:
  
 
==== Guessing the .gpio values and masks for input ====
 
==== Guessing the .gpio values and masks for input ====
See [[Remote controllers]] and [[GPIO pins]].
+
For some guidance on programming for these aspects, see:
 
+
* the programming section of the [[GPIO pins]] article and
A guide about how to add a remote can be found in the section [[Remote_controllers]]. Before writing the patch please double-check if there are no such keys in v4l sources already.
+
* the [[Remote controllers-V4L|Remote controllers]] article. Note: before writing the patch please double-check that there are no such keys in V4L-DVB source code already.
  
 
==== Test your code====
 
==== Test your code====
If the card works - that's cool! Congradulations! You are now ready to send a patch to video4linux mailing list.
+
If the device works - that's cool! Congratulations! You are now ready to [[Development: How to submit patches|send a patch to the mailing list]].
  
 
==Case 2: Development steps for when your device uses components for which drivers do not currently exist==
 
==Case 2: Development steps for when your device uses components for which drivers do not currently exist==
Line 50: Line 52:
 
Unfortunately, development of a new chipset driver is generally not an easy task. For starters, you're going to have to be capable and/or ambitious enough to produce the code or, at the very least, inspire an existing developer to do such (and there is by no means any guarantee that anyone will be interested...even if you cry and beg and/or throw bags of money).  Either way, you should first search and/or inquire on the mailing list as to whether or not someone is already undertaking such development.
 
Unfortunately, development of a new chipset driver is generally not an easy task. For starters, you're going to have to be capable and/or ambitious enough to produce the code or, at the very least, inspire an existing developer to do such (and there is by no means any guarantee that anyone will be interested...even if you cry and beg and/or throw bags of money).  Either way, you should first search and/or inquire on the mailing list as to whether or not someone is already undertaking such development.
  
If you're going to work on a driver for a chip you should try to find documentation for it online.  In the end, you may require getting information directly from the manufacturer (in the case where no information can be found in the "wild" or those where publicly available infomation is incomplete or lacking).  
+
If you're going to work on a driver for a chip you should try to find documentation for it online.  In the end, you may require getting information directly from the manufacturer (in the case where no information can be found in the "wild" or those where publicly available information is incomplete or lacking).
 +
 
 +
* For general references on how to develop a Linux kernel driver module, take a look at the [http://jungla.dit.upm.es/%7Ejmseyas/linux/kernel/hackers-docs.html Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel].
  
* For general references on how to develop a Linux kernel driver module, take a look at [http://jungla.dit.upm.es/%7Ejmseyas/linux/kernel/hackers-docs.html Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel].
 
 
* USB based devices; Also see:  
 
* USB based devices; Also see:  
 
** [[Development: How to develop drivers for USB based devices|How to develop drivers for USB based devices]]
 
** [[Development: How to develop drivers for USB based devices|How to develop drivers for USB based devices]]
Line 58: Line 61:
  
 
==== A Word on Non-Disclosure Agreements ====
 
==== A Word on Non-Disclosure Agreements ====
Companies frequently allow developers to see detailed chip specifications or even Linux source code under a Non-disclosure agreement (NDA). For instance, during the development of the [[em28xx devices|em28xx]] driver, Markus Rechberger signed a NDA for chip information from EMPIA Technologies, and in 2006 Philips offered source code supporting their new [[saa7162 devices|saa7162]] encoder reference board under an NDA.
+
Companies frequently allow developers to see detailed chip specifications or even Linux source code under a Non-disclosure agreement (NDA).
  
A NDA isn't necessarily a barrier to writing a GPL'd driver; it just depends on what it says. If you receive such a document, read it carefully. If the NDA merely stops you from disclosing the specifications, you should be fine. This does not prevent you from writing and distributing a driver under a free software license. Also note that, in some cases, signing a NDA may even go so far as restricting you from even mentioning to others that you've signed a NDA -- in otherwords, you can't talk about or even mention the development of the new driver until the terms of the NDA lift.  Also make sure to check that you're allowed to be the copyright holder of your driver. If not, they might redistribute your code under another license, and thus close the code.  
+
A NDA isn't necessarily a barrier to writing a GPL'd driver; it just depends on what it says. While there are some movements at the Open Source community for open datasheets, unfortunately several vendors still prefer to keep the Intelectual Property (IP) of their documents protected, under the terms of an NDA.
 +
 
 +
If you are required to sign an NDA, read it carefully. If the NDA merely stops you from disclosing the specifications, you should be fine. This does not prevent you from writing and distributing a driver under a free software license. Also note that, in some cases, signing a NDA may even go so far as restricting you from even mentioning to others that you've signed a NDA -- in other words, you can't talk about or even mention the development of the new driver until the terms of the NDA lift.  Also make sure to check that you're allowed to be the copyright holder of your driver. If not, they might redistribute your code under another license, and thus close the code. It is wise to ask to a lawyer to analyze the NDA clauses or to use [[http://www.linuxfoundation.org/en/NDA_program Linux Foundation NDA program]] to be sure if the terms you're signing will allow you to release an open source code.
  
 
Chip and board manufacturers have an incentive to be helpful to free software developers, as the drivers will help move their product. And as long as the NDA gives you the necessary freedom to publish your code, the information supplied can be extremely helpful in writing the driver.
 
Chip and board manufacturers have an incentive to be helpful to free software developers, as the drivers will help move their product. And as long as the NDA gives you the necessary freedom to publish your code, the information supplied can be extremely helpful in writing the driver.
  
 
====After you've finished the driver(s) for the previously unsupported components====
 
====After you've finished the driver(s) for the previously unsupported components====
Its time to return to the steps outlined in "Case 1", where you link together the necessary pieces in the drivers that will bring about support for your device (i.e. adding all the glue code).
+
Its time to return to the steps outlined in "Case 1", where you link together the necessary pieces in the drivers that will bring about support for your device (i.e. adding all the glue code).
 
+
  
 
== Don't forget to send info to the Wiki !==  
 
== Don't forget to send info to the Wiki !==  
 
* upload non-proprietary picture(s) of the device  (i.e. those that you took, and not ones taken from the vendor's website without express permission to do so!)  Note: Please use a descriptive filename, as opposed to "image1.jpg" or the generic/cryptic filename that your digital camera gave to it when it was created.
 
* upload non-proprietary picture(s) of the device  (i.e. those that you took, and not ones taken from the vendor's website without express permission to do so!)  Note: Please use a descriptive filename, as opposed to "image1.jpg" or the generic/cryptic filename that your digital camera gave to it when it was created.
* create a device article outlining what type of device it is, features, support information (drivers, firmware, remote), identification, kernel output messages etc etc (as a guide or template for an article's format, [http://www.linuxtv.org/wiki/index.php/Temporary:_New_Device_Copy_%26_Paste_Template see here]).
+
* create a device article outlining what type of device it is, features, support information (drivers, firmware, remote), identification, kernel output messages etc., etc., (see the [[Wiki - New Device Copy & Paste Template|New Device Copy & Paste Template]] as a guide for an article's format).
 
+
===bttv-gallery ===
+
In addition, if your card is missing on bttv-gallery, you may wish to consider also sending the following info to Gunther Mayer <gunther.mayer () gmx ! net>.
+
 
+
{{Note|in the early stages of V4L history, well before a wiki was even dreamt of, the bttv-gallery was initiated by Gunther Mayer, a leading tuner/hardware developer with the project.  The bttv-gallery essentially served as the official hardware resource centre for V4L, whereby it documented a great deal of the insights (such as tuner components, GPIO settings, EEPROM detection etc., etc.,) that were conveyed on the mailing list, and also provided a visual library for devices.  Though it seems, unfortunately, that it has fallen into stasis, it still remains an excellent reference source that is easily searchable for many hard to find facts/items.}}
+
 
+
Your contribution will help to improve open source support!
+
Because there are many cards and variations by different
+
vendors, the developers need _your_ help to get it all supported.
+
 
+
1st priority:
+
* picture of the card, the card backside (high resolution pics if feasible)
+
* lspci -vn
+
 
+
further information:
+
# picture of remote control (if applicable) and of original package
+
# list of chips
+
# list of input connectors
+
# printings on PCB, printings on stickers on the card
+
# lspci -v  and  lspci -vn
+
# "dmesg" when loading the modules
+
# if feasible "eeprom" output (from bttv tools)
+
# if feasible "*.INF" files from the Windows Driver CD
+
# exact tuner type (possibly this is hidden under the vendor sticker)
+
# exact model name and model number from package
+
# in which country do you live/ in which country this card was bought
+
# which application(s) did you use to test your setup ?
+
# If some parts of your card seem to work, describe exactly what you did and what you see/hear now.
+
 
+
Even parts of this info will be very helpful!
+
  
 +
===bttv-gallery ===
 +
{{Note|in the early stages of V4L history, well before a wiki was even dreamt of, the bttv-gallery was initiated by Gunther Mayer, a leading tuner/hardware developer with the project.  The bttv-gallery essentially served as the official hardware resource centre for V4L, whereby it documented a great deal of the insights (such as tuner components, GPIO settings, EEPROM detection etc., etc.,) that were conveyed on the mailing list, as well as from user submissions, and also provided a visual library of the devices.  Over time, a great many analogue and DVB devices were documented. Even after the site feel into a state of stasis, it remained an excellent reference source that was easily searchable for many hard to find facts/items, as well as for purposes of device identification.  Unfortunately, it appears that the bttv-gallery webpage no longer exits, though access to its resources can be made through the last available snapshot on the wayback machine: http://wayback.archive.org/web/*/http://www.bttv-gallery.de}}
  
 
[[Category:Development]]
 
[[Category:Development]]

Latest revision as of 18:56, 8 October 2012

This article is meant to serve as an introduction to the task of developing driver support for a device.

Getting Started

The very first thing you should do is find out how your device identifies itself:

For PCI/PCIe devices - use the command:

$ /sbin/lspci -vnn

For USB based devices - use the command:

$ /sbin/lsusb -v

The output generated from the above should provide you with the identify of the main bridge chip as well as the important piece of information known as the device's subsystem ID.

Next, you should try to identify the other component ICs/chips that your device uses. In regards to TV tuner devices, often the tuner chip and demodulator(s) are hidden within a metallic box connected directly to the antenna input. In such cases, this tuner module will usually have an identifying model name/type printed upon it's face, though it is also just as common for this to be obscured underneath a sticker that the device manufacturer has laid over top. With care, you can usually peel back the manufacturer's device sticker to discover the tuner module's own part identifier label or stamp.

Note: You can find a lot of useful device related information:

  • here in the wiki
  • in the bttv-gallery
  • and by having a look at MS-Windows drivers (in particular, the .inf files), as they often contain a lot of particulars about a device's hardware components


Case 1: Development steps for when your device uses components for which drivers already exist

Extending support for your device under such circumstances can range from being a trivial matter to one which requires some patience and discovery through the process of trial & error.

First off, download the latest V4L-DVB source code from Git and search for a device that is similar to your own - something like your device may already be supported but with another name. In such a case, you can copy a similar entry and fill in the values for the new device. For example:

  • for a bttv chip you add to bttv-cards.c and bttv.h,
  • for cx88 chip - cx88-cards.c and cx88.h,
  • for saa713x chip saa7134-cards.c and saa7134.h

... and so forth.

For TV tuner devices: Finding the correct tuner

In more than 90% of all cases something like.. first test one to your norm specific type with older Philips API, then test LG API and if there are still missing channels in UHF test MK3 API types will succeed. To find the exact takeover and radio config might be further steps, but most likely this can be/is covered by one of the existing types already.

At least it will usually take only three tuners to reach this point and if you find all three API types don't work, then ...

To check for the tda9887 on MK3 and mt32xx types can be done at once or as a next step. Since also the Philips silicon tuners should be well detected now, we can identify such like the yet unsupported Xceive types quite well. They seem to fail safely upon the initialization sequence with tuner=54 if I got Carsten right. So the really difficult/new ones should show up quickly enough and we can try to prepare a list of typical addresses for new devices like channel decoders, second eeproms, most likely hidden analog demodulators and such.

That the multi and hybrid types can have other issues too, like antenna input/filter/demodulator RF-amplifier switching and the like is above simple analog tuner programming and not yet fully investigated for all new types, but it seems there is some very good progress too.

The takeover suggestions in most datasheets on switch between VHF and UHF aren't related closely to technical specifications and precise measurements. They simply take it from _known_ channels currently in use and select those which are closest from both sides! Most obvious for NTSC-M tuners. If one is missing in the gap, to go right into the middle seems to be still reasonable for me as a next step in such cases, but to finally make the decision on what is empirically reported to work best is legal in lack of further documentation.

Guessing the .gpio values and masks for input

For some guidance on programming for these aspects, see:

  • the programming section of the GPIO pins article and
  • the Remote controllers article. Note: before writing the patch please double-check that there are no such keys in V4L-DVB source code already.

Test your code

If the device works - that's cool! Congratulations! You are now ready to send a patch to the mailing list.

Case 2: Development steps for when your device uses components for which drivers do not currently exist

Unfortunately, development of a new chipset driver is generally not an easy task. For starters, you're going to have to be capable and/or ambitious enough to produce the code or, at the very least, inspire an existing developer to do such (and there is by no means any guarantee that anyone will be interested...even if you cry and beg and/or throw bags of money). Either way, you should first search and/or inquire on the mailing list as to whether or not someone is already undertaking such development.

If you're going to work on a driver for a chip you should try to find documentation for it online. In the end, you may require getting information directly from the manufacturer (in the case where no information can be found in the "wild" or those where publicly available information is incomplete or lacking).

A Word on Non-Disclosure Agreements

Companies frequently allow developers to see detailed chip specifications or even Linux source code under a Non-disclosure agreement (NDA).

A NDA isn't necessarily a barrier to writing a GPL'd driver; it just depends on what it says. While there are some movements at the Open Source community for open datasheets, unfortunately several vendors still prefer to keep the Intelectual Property (IP) of their documents protected, under the terms of an NDA.

If you are required to sign an NDA, read it carefully. If the NDA merely stops you from disclosing the specifications, you should be fine. This does not prevent you from writing and distributing a driver under a free software license. Also note that, in some cases, signing a NDA may even go so far as restricting you from even mentioning to others that you've signed a NDA -- in other words, you can't talk about or even mention the development of the new driver until the terms of the NDA lift. Also make sure to check that you're allowed to be the copyright holder of your driver. If not, they might redistribute your code under another license, and thus close the code. It is wise to ask to a lawyer to analyze the NDA clauses or to use [Linux Foundation NDA program] to be sure if the terms you're signing will allow you to release an open source code.

Chip and board manufacturers have an incentive to be helpful to free software developers, as the drivers will help move their product. And as long as the NDA gives you the necessary freedom to publish your code, the information supplied can be extremely helpful in writing the driver.

After you've finished the driver(s) for the previously unsupported components

Its time to return to the steps outlined in "Case 1", where you link together the necessary pieces in the drivers that will bring about support for your device (i.e. adding all the glue code).

Don't forget to send info to the Wiki !

  • upload non-proprietary picture(s) of the device (i.e. those that you took, and not ones taken from the vendor's website without express permission to do so!) Note: Please use a descriptive filename, as opposed to "image1.jpg" or the generic/cryptic filename that your digital camera gave to it when it was created.
  • create a device article outlining what type of device it is, features, support information (drivers, firmware, remote), identification, kernel output messages etc., etc., (see the New Device Copy & Paste Template as a guide for an article's format).

bttv-gallery

Note: in the early stages of V4L history, well before a wiki was even dreamt of, the bttv-gallery was initiated by Gunther Mayer, a leading tuner/hardware developer with the project. The bttv-gallery essentially served as the official hardware resource centre for V4L, whereby it documented a great deal of the insights (such as tuner components, GPIO settings, EEPROM detection etc., etc.,) that were conveyed on the mailing list, as well as from user submissions, and also provided a visual library of the devices. Over time, a great many analogue and DVB devices were documented. Even after the site feel into a state of stasis, it remained an excellent reference source that was easily searchable for many hard to find facts/items, as well as for purposes of device identification. Unfortunately, it appears that the bttv-gallery webpage no longer exits, though access to its resources can be made through the last available snapshot on the wayback machine: http://wayback.archive.org/web/*/http://www.bttv-gallery.de