Development: How to add support for a device

Getting Started

First you should find how your card identifies yourself on pci (just lspci and lspci -vn) or usb (lsusb and lsusb -v). This gives you the type of main decoder chip.

Next, you should try to identify tuner chips that your card 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.

You can find a lot of cards on http://bttv-gallery.de - a very useful resource for cards identification.

Another useful place to look is MS-Windows drivers. They often contain a lot of information about cards' hardware.

Development is easy

After that you should download the latest v4l cvs and search for a similar card. Something like your card may already be supported but with another name. You can copy a similar entry and fill in the values for the new card. For a bttv chip you add to bttv-cards.c and bttv.h, for cx88 - cx88-cards.c and cx88.h, for saa - saa7134-cards.c and saa7134.h. If you're ambitious enough to take on a new chip, see section NDA below.

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.

If the card works - that's cool. You are ready to send a patch to video4linux mailing list.

Don't forget to send info to bttv-gallery

If your card is missing on bttv-gallery, please, send the following info to Gunther Mayer <gunther.mayer () gmx ! net>.

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:

1. picture of remote control (if applicable) and of original package
2. list of chips
3. list of input connectors
4. printings on PCB, printings on stickers on the card
5. lspci -v and lspci -vn
6. "dmesg" when loading the modules
7. if feasible "eeprom" output (from bttv tools)
8. if feasible "*.INF" files from the Windows Driver CD
9. exact tuner type (possibly this is hidden under the vendor sticker)
10. exact model name and model number from package
11. in which country do you live/ in which country this card was bought
12. which application(s) did you use to test your setup ?
13. 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!

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

See Remote controllers and GPIO pins.

Non-disclosure agreements

If you're working on a driver for a new type of card, for instance one that uses an unsupported encoder, you should try to get more information from the manufacturer.

Companies frequently allow developers to see detailed chip specifications or even Linux source code under a Non-disclosure agreement (NDA). During the development of the em28xx driver, for instance, Markus Rechberger signed an NDA for chip information from EMPIA Technologies, and in 2006 Philips offered source code supporting their new saa7126 encoder reference board under an NDA.

An NDA isn't necessarily a bar 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 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.

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.