bttv-devel.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3The bttv driver
  4===============
  5
  6bttv and sound mini howto
  7-------------------------
  8
  9There are a lot of different bt848/849/878/879 based boards available.
 10Making video work often is not a big deal, because this is handled
 11completely by the bt8xx chip, which is common on all boards.  But
 12sound is handled in slightly different ways on each board.
 13
 14To handle the grabber boards correctly, there is a array tvcards[] in
 15bttv-cards.c, which holds the information required for each board.
 16Sound will work only, if the correct entry is used (for video it often
 17makes no difference).  The bttv driver prints a line to the kernel
 18log, telling which card type is used.  Like this one::
 19
 20	bttv0: model: BT848(Hauppauge old) [autodetected]
 21
 22You should verify this is correct.  If it isn't, you have to pass the
 23correct board type as insmod argument, ``insmod bttv card=2`` for
 24example.  The file Documentation/admin-guide/media/bttv-cardlist.rst has a list
 25of valid arguments for card.
 26
 27If your card isn't listed there, you might check the source code for
 28new entries which are not listed yet.  If there isn't one for your
 29card, you can check if one of the existing entries does work for you
 30(just trial and error...).
 31
 32Some boards have an extra processor for sound to do stereo decoding
 33and other nice features.  The msp34xx chips are used by Hauppauge for
 34example.  If your board has one, you might have to load a helper
 35module like ``msp3400`` to make sound work.  If there isn't one for the
 36chip used on your board:  Bad luck.  Start writing a new one.  Well,
 37you might want to check the video4linux mailing list archive first...
 38
 39Of course you need a correctly installed soundcard unless you have the
 40speakers connected directly to the grabber board.  Hint: check the
 41mixer settings too.  ALSA for example has everything muted by default.
 42
 43
 44How sound works in detail
 45~~~~~~~~~~~~~~~~~~~~~~~~~
 46
 47Still doesn't work?  Looks like some driver hacking is required.
 48Below is a do-it-yourself description for you.
 49
 50The bt8xx chips have 32 general purpose pins, and registers to control
 51these pins.  One register is the output enable register
 52(``BT848_GPIO_OUT_EN``), it says which pins are actively driven by the
 53bt848 chip.  Another one is the data register (``BT848_GPIO_DATA``), where
 54you can get/set the status if these pins.  They can be used for input
 55and output.
 56
 57Most grabber board vendors use these pins to control an external chip
 58which does the sound routing.  But every board is a little different.
 59These pins are also used by some companies to drive remote control
 60receiver chips.  Some boards use the i2c bus instead of the gpio pins
 61to connect the mux chip.
 62
 63As mentioned above, there is a array which holds the required
 64information for each known board.  You basically have to create a new
 65line for your board.  The important fields are these two::
 66
 67  struct tvcard
 68  {
 69	[ ... ]
 70	u32 gpiomask;
 71	u32 audiomux[6]; /* Tuner, Radio, external, internal, mute, stereo */
 72  };
 73
 74gpiomask specifies which pins are used to control the audio mux chip.
 75The corresponding bits in the output enable register
 76(``BT848_GPIO_OUT_EN``) will be set as these pins must be driven by the
 77bt848 chip.
 78
 79The ``audiomux[]`` array holds the data values for the different inputs
 80(i.e. which pins must be high/low for tuner/mute/...).  This will be
 81written to the data register (``BT848_GPIO_DATA``) to switch the audio
 82mux.
 83
 84
 85What you have to do is figure out the correct values for gpiomask and
 86the audiomux array.  If you have Windows and the drivers four your
 87card installed, you might to check out if you can read these registers
 88values used by the windows driver.  A tool to do this is available
 89from http://btwincap.sourceforge.net/download.html.
 90
 91You might also dig around in the ``*.ini`` files of the Windows applications.
 92You can have a look at the board to see which of the gpio pins are
 93connected at all and then start trial-and-error ...
 94
 95
 96Starting with release 0.7.41 bttv has a number of insmod options to
 97make the gpio debugging easier:
 98
 99	=================	==============================================
100	bttv_gpio=0/1		enable/disable gpio debug messages
101	gpiomask=n		set the gpiomask value
102	audiomux=i,j,...	set the values of the audiomux array
103	audioall=a		set the values of the audiomux array (one
104				value for all array elements, useful to check
105				out which effect the particular value has).
106	=================	==============================================
107
108The messages printed with ``bttv_gpio=1`` look like this::
109
110	bttv0: gpio: en=00000027, out=00000024 in=00ffffd8 [audio: off]
111
112	en  =	output _en_able register (BT848_GPIO_OUT_EN)
113	out =	_out_put bits of the data register (BT848_GPIO_DATA),
114		i.e. BT848_GPIO_DATA & BT848_GPIO_OUT_EN
115	in  = 	_in_put bits of the data register,
116		i.e. BT848_GPIO_DATA & ~BT848_GPIO_OUT_EN