BKTR(4) | Device Drivers Manual | BKTR(4)

# NAME

`bktr` — Brooktree Bt848/849/878/879 PCI TV tuners and video capture boards

# SYNOPSIS

`bktr* at pci?`
`radio* at bktr?`

`#include <dev/ic/bt8xx.h>`

`option BKTR_ALLOC_PAGES=nnn`
`option BKTR_SYSTEM_DEFAULT=XXX`
`option BKTR_OVERRIDE_CARD=nnn`
`option BKTR_OVERRIDE_MSP=n`
`option BKTR_OVERRIDE_TUNER=nnn`

# DESCRIPTION

The `bktr` driver provides support for PCI video capture and VBI capture on low cost, high performance boards. This should support most video cards based on the Brooktree Bt848/849/878/879 Video Capture Chip. The driver also supports FM Radio if the Tuner supports it.

Specifically, the following cards are known to work:

    Animation Technologies FlyVideo
    AOpen VA1000
    Askey/Dynalink Magic TView
    ATI TV-Wonder and Wonder/VE
    AverMedia cards
    Hauppauge Wincast TV and WinTV/PCI
    IMS TV Turbo
    Intel Smart Video Recorder III
    I/O DATA GV-BCTV2/PCI
    I/O DATA GV-BCTV3/PCI
    KISS TV/FM PCI
    Leadtek Winfast TV 2000
    Leadtek Winfast TV 2000 XP
    Miro PC TV
    MMAC Osprey
    NEC PK-UG-X017
    STB TV PCI Television Tuner
    Terratec TerraTVplus
    Video Highway XTreme
    VideoLogic Captivator PCI
    Zoltrix TV and Genie TV/FM

The driver currently supports the following features:

    PCI to PCI DMA transfer
    clipping
    yuv
    rgb16
    rgb24
    rgb32

On these cards, tuners and other components are interconnected with an I2C bus. The Brooktree848 chips act as a master device on the bus to control them.

# VIDEO CAPTURE INTERFACE

The video capture interface to `bktr` is accessed through /dev/bktrN devices. The following ioctl(2) commands are supported on the Brooktree848 video capture interface:

`METEORSFMT` unsigned long *
  This command sets the video format, also sometimes referred to as the video norm. The supported formats are:

  `METEOR_FMT_NTSC`
    NTSC
  `METEOR_FMT_PAL`
    PAL
  `METEOR_FMT_SECAM`
    SECAM
  `METEOR_FMT_AUTOMODE`
    hardware default
`METEORGFMT` unsigned long *
  This command retrieves the current video format to the unsigned long * argument.
`METEORSETGEO` struct meteor_geomet *
  This command sets the video properties that affect the bit size of a frame through the meteor_geomet * argument.

      struct meteor_geomet {
      	u_short		rows;	 /* height in pixels*/
      	u_short		columns; /* width in pixels */
      	u_short		frames;
      	u_long		oformat;
      }

  The frames field is the number of frames to buffer. Currently only 1 frame is supported for most operations.

  The oformat field is a bit-field describing the output pixel format type and which video fields to capture. The following are supported pixel format types:

  `METEOR_GEO_RGB16`
    16-bit RGB
  `METEOR_GEO_RGB24`
    24-bit RGB in 32 bits
  `METEOR_GEO_YUV_PACKED`
    16-bit 4:2:2 YUV
  `METEOR_GEO_YUV_PLANAR`
    16-bit 4:2:2 YUV
  `METEOR_GEO_YUV_UNSIGNED`
    unsigned UV
  `METEOR_GEO_YUV_422`
  `METEOR_GEO_YUV_12`
  `METEOR_GEO_YUV_9`

  The following are supported field capture modes:

  `METEOR_GEO_ODD_ONLY`
    only odd fields
  `METEOR_GEO_EVEN_ONLY`
    only even fields

  By default, frames will consist of both the odd and even fields.

`METEORGSUPPIXFMT` struct meteor_pixfmt *
  This command is used iteratively to fetch descriptions of supported output pixel formats into the meteor_pixfmt * argument.

      struct meteor_pixfmt {
      	u_int          index;
      	METEOR_PIXTYPE type;
      	u_int          Bpp;		/* bytes per pixel */
      	u_long         masks[3];	/* YUV bit masks */
      	unsigned       swap_bytes :1;
      	unsigned       swap_shorts:1;
      };

  To query all the supported formats, start with an index field of 0 and continue with successive encodings (1, 2, ...) until the command returns an error.

`METEORSACTPIXFMT` int *
  This command sets the active pixel format. The int * argument is the index of the pixel format as returned by `METEORGSUPPIXFMT`.
`METEORGACTPIXFMT` int *
  This command fetches the active pixel format index into the int * argument.
`METEORSINPUT` unsigned long *
  This command sets the input port of the Brooktree848 device. The following are supported input ports:

  `METEOR_INPUT_DEV0`
    composite (RCA)
  `METEOR_INPUT_DEV1`
    tuner
  `METEOR_INPUT_DEV2`
    composite S-video
  `METEOR_INPUT_DEV3`
    mystery device
  `METEOR_INPUT_DEV_RGB`
    rgb meteor
  `METEOR_INPUT_DEV_SVIDEO`
    S-Video

  Not all devices built with Brooktree848 chips support the full list of input ports.

`METEORGINPUT` unsigned long *
  This command retrieves the current input port to the unsigned long * argument.
`METEORSFPS` unsigned short *
  This command sets the number of frames to grab each second. Valid frame rates are integers from 0 to 30.
`METEORGFPS` unsigned short *
  This command fetches the number of frames to grab each second into the unsigned short * argument.
`METEORCAPTUR` int *
  This command controls capturing of video data. The following are valid arguments:

  `METEOR_CAP_SINGLE`
    capture one frame
  `METEOR_CAP_CONTINOUS`
    continuously capture
  `METEOR_CAP_STOP_CONT`
    stop continuous capture
`METEORSSIGNAL` unsigned int *
  This command controls the signal emission properties of `bktr`. If the unsigned int * argument is a valid signal, then that signal will be emitted when either a frame or field capture has completed. To select between frame or field signalling, the following arguments are used:

  `METEOR_SIG_FRAME`
    signal every frame
  `METEOR_SIG_FIELD`
    signal every field

  By default, signals will be generated for every frame. Generation of signals is terminated with the `METEOR_SIG_MODE_MASK` argument.

# TUNER INTERFACE

Most cards supported by this driver feature a hardware television tuner on the I2C bus. The tuner interface to `bktr` is accessed through /dev/tunerN devices. The following ioctl(2) commands are supported on the tuner interface:

`TVTUNER_SETTYPE` unsigned int *
  This command sets the tuner's TV channel set, also sometimes called the TV channel band. This setting is used to calculate the proper tuning frequencies. The desired channel set must be selected before attempting to set the tuner channel or frequency. The following is a list of valid channel sets:

  `CHNLSET_NABCST`
    North America broadcast
  `CHNLSET_CABLEIRC`
    North America IRC cable
  `CHNLSET_CABLEHRC`
    North America HRC cable
  `CHNLSET_WEUROPE`
    Western Europe
  `CHNLSET_JPNBCST`
    Japan broadcast
  `CHNLSET_JPNCABLE`
    Japan cable
  `CHNLSET_XUSSR`
    Russia
  `CHNLSET_AUSTRALIA`
    Australia
  `CHNLSET_FRANCE`
    France
`TVTUNER_GETTYPE` unsigned int *
  This command fetches the tuner's current channel set to the unsigned int * argument.
`TVTUNER_SETCHNL` unsigned int *
  This command sets the tuner's frequency to a specified channel in the current channel set.
`TVTUNER_GETCHNL` unsigned int *
  This command fetches the last selected channel. Note that it is not necessarily the current channel. In particular, changing the tuner's frequency by a command other than `TVTUNER_SETCHNL` will not update this setting, and it defaults to 0 on driver initialization.
`TVTUNER_SETFREQ` unsigned int *
  This command sets the tuner's frequency to 1/16th the value of the unsigned int * argument, in MHz. Note that the current channelset is used to determine frequency offsets when this command is executed.
`TVTUNER_GETFREQ` unsigned int *
  This command fetches the tuner's current frequency to the unsigned int * argument. Note that this value is 16 times the actual tuner frequency, in MHz.
`BT848_SAUDIO` int *
  This command controls the audio input port and mute state. The following is a list of valid arguments:

  `AUDIO_TUNER`
    tuner audio port
  `AUDIO_EXTERN`
    external audio port
  `AUDIO_INTERN`
    internal audio port
  `AUDIO_MUTE`
    mute audio
  `AUDIO_UNMUTE`
    unmute audio
`BT848_GAUDIO` int *
  This command fetches the audio input and mute state bits to the int * argument.

# KERNEL OPTIONS

The following kernel configuration options are available:

`option BKTR_ALLOC_PAGES=nnn`
  Specifies the number of contiguous pages to allocate when successfully probed. The default number of pages allocated by the kernel is 216. This means that there are (216*4096) bytes available for use.
`option BKTR_SYSTEM_DEFAULT="(BROOKTREE_PAL` | `BROOKTREE_NTSC)"`
  One of these options can be used to set the default video format for the driver. This fixed random hangs and lockups with the VideoLogic Captivator PCI card.
`option BKTR_OVERRIDE_CARD=nnn`
  Select a specific card (overrides autodetection). `nnn' is set to one of the names listed and explained below.

  CARD_ASKEY_DYNALINK_MAGIC_TVIEW
    Askey/Dynalink Magic TView
  CARD_AVER_MEDIA
    AverMedia
  CARD_FLYVIDEO
    Animation Technologies FlyVideo
  CARD_AOPEN_VA1000
    AOpen VA1000
  CARD_TVWONDER
    ATI TV-Wonder/VE
  CARD_HAUPPAUGE
    Hauppauge Wincast TV and WinTV
  CARD_IMS_TURBO
    IMS TV Turbo
  CARD_INTEL
    Intel Smart Video Recorder III
  CARD_IO_GV
    I/O DATA GV-BCTV2/PCI
  CARD_IO_BCTV3
    I/O DATA GV-BCTV3/PCI
  CARD_KISS
    KISS TV/FM PCI
  CARD_LEADTEK
    Leadtek Winfast TV 2000
  CARD_LEADTEK_XP
    Leadtek Winfast TV 2000 XP
  CARD_MIRO
    Miro PC TV
  CARD_OSPREY
    MMAC Osprey
  CARD_NEC_PK
    NEC PK-UG-X017
  CARD_STB
    STB TV PCI Television Tuner
  CARD_TERRATVPLUS
    Terratec TerraTVplus
  CARD_VIDEO_HIGHWAY_XTREME
    Video Highway XTreme
  CARD_ZOLTRIX
    Zoltrix TV
  CARD_ZOLTRIX_GENIE_FM
    Zoltrix Genie TV/FM
`option BKTR_OVERRIDE_MSP=n`
  Specifies whether the MSP3400C chip is present (overrides autodetection).
`option BKTR_OVERRIDE_TUNER=nnn`
  Select a specific tuner (overrides autodetection). `nnn' is set to one of the names listed and explained below.

  TEMIC_NTSC
    Temic 4032FY5
  TEMIC_PAL
    Temic 4002FH5
  TEMIC_SECAM
    Temic 4002FN5
  PHILIPS_NTSC
    Philips FI1236
  PHILIPS_PAL
    Philips FM1216
  PHILIPS_SECAM
    Philips FI1216MF
  TEMIC_PALI
    Temic 4062FY5
  PHILIPS_PALI
    Philips FI1246
  PHILIPS_FR1236_NTSC
    Philips FR1236 MK2
  PHILIPS_FR1216_PAL
    Philips FM1216
  PHILIPS_FR1236_SECAM
    Philips FM1216MF
  ALPS_TSCH5
    Alps TSCH5 NTSC
  ALPS_TSBH1
    Alps TSBH1 NTSC
  TIVISION_TVF5533
    Tivision TVF5533-MF NTSC

# SEE ALSO

intro(4), pci(4), radio(4)

# HISTORY

The `bktr` driver first appeared in FreeBSD 2.2.

# AUTHORS

The `bktr` driver is based on the work of Jim Lowe <james@miller.cs.uwm.edu>, Mark Tinguely <tinguely@plains.nodak.edu>, Amancio Hasty <hasty@star-gate.com>, Roger Hardiman <roger@FreeBSD.org> and a bunch of other people.

# CAVEATS

On big-endian architectures it is not possible to program the card to perform proper byte swapping in 24 bit modes, therefore only 16 and 32 bit modes are supported.

September 1, 2024 | Debian