BKTR(4)                   OpenBSD Programmer's 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 de-
     vices.  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 for-
             mat 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 sup-
             ported 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 in-
             to 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 complet-
             ed.  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.  Genera-
             tion of signals is terminated with the METEOR_SIG_MODE_MASK argu-
             ment.

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 initial-
             ization.

     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 chan-
             nelset 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 suc-
               cessfully 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 for-
               mat 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 Fly-
                                                Video
               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 au-
               todetection).

     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                    Apls TSCH5 NTSC
               ALPS_TSBH1                    Apls 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.

OpenBSD 4.7                    October 25, 2009                              5
