1.\" $NetBSD: bktr.4,v 1.17 2009/05/27 19:23:59 snj Exp $ 2.\" 3.\" Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005 Thomas Klausner 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. The name of the author may not be used to endorse or promote products 12.\" derived from this software without specific prior written permission. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 15.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 16.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 17.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 18.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 19.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 20.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 22.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 23.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 24.\" POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd December 6, 2005 27.Dt BKTR 4 28.Os 29.Sh NAME 30.Nm bktr 31.Nd Brooktree 848 compatible TV card driver 32.Sh SYNOPSIS 33.Cd "bktr* at pci? dev ? function ?" 34.Cd radio* at bktr? 35.Pp 36.In dev/ic/bt8xx.h 37.Pp 38.Cd options BKTR_OVERRIDE_CARD=n 39.Cd options BKTR_OVERRIDE_TUNER=n 40.Cd options BKTR_OVERRIDE_DBX=n 41.Cd options BKTR_OVERRIDE_MSP=n 42.Cd options BKTR_SYSTEM_DEFAULT=n 43.Cd options BKTR_USE_PLL 44.Cd options BKTR_GPIO_ACCESS 45.Cd options BKTR_NO_MSP_RESET 46.\" The following options have no effect: 47.\" .Cd options BKTR_430_FX_MODE 48.\" .Cd options BKTR_SIS_VIA_MODE 49.Sh DESCRIPTION 50This driver supports video capture (frame grabber) and TV tuner cards 51based on the 52.Tn Brooktree 53.Tn Bt848 , 54.Tn Bt848A , 55.Tn Bt849A , 56.Tn Bt878 , 57and 58.Tn Bt879 59chips. 60.Pp 61Supported cards include most cards by 62.Tn AVerMedia , 63.Tn Hauppauge , 64.Tn Leadtek , 65.Tn Miro , 66.Tn Pinnacle , 67.Tn Pixelview , 68.Tn Terratec , 69and some other companies, especially all cards based on the 70.Tn Brooktree 71.Tn Bt848 , 72.Tn Bt848A , 73.Tn Bt849A , 74.Tn Bt878 , 75or 76.Tn Bt879 77chips. 78A notable exception are the 79.Tn ATI 80.Tn All-in-Wonder 81cards. 82.Pp 83The following kernel configuration options are available: 84.Bl -ohang 85.It Cd options BKTR_OVERRIDE_CARD=n 86If the card is not recognized correctly by the auto-detection routine, 87it can be overridden by setting this option to the appropriate 88value. 89The following values are allowed: 90.Bl -tag -width 2n -compact 91.It 1 92Pinnacle Systems (Miro) TV, 93.It 2 94Hauppauge WinCast/TV, 95.It 3 96STB TV/PCI, 97.It 4 98Intel Smart Video III and Videologic Captivator PCI, 99.It 5 100IMS TV Turbo, 101.It 6 102AVerMedia TV/FM, 103.It 7 104MMAC Osprey, 105.It 8 106NEC PK-UG-X017, 107.It 9 108I/O DATA GV-BCTV2/PCI, 109.It 10 110Animation Technologies FlyVideo, 111.It 11 112Zoltrix TV, 113.It 12 114KISS TV/FM PCI, 115.It 13 116Video Highway Xtreme, 117.It 14 118Askey/Dynalink Magic TView, 119.It 15 120Leadtek WinFast TV 2000/VC100, 121.It 16 122TerraTec TerraTV+, 123and 124.It 17 125TerraTec TValue. 126.El 127.It Cd options BKTR_OVERRIDE_TUNER=n 128If the TV tuner is not recognized correctly by the auto-detection 129routine, it can be overridden by setting this option to the 130appropriate value. 131Known values are: 132.Bl -tag -width 2n -compact 133.It 1 134Temic NTSC, 135.It 2 136Temic PAL, 137.It 3 138Temic SECAM, 139.It 4 140Philips NTSC, 141.It 5 142Philips PAL, 143.It 6 144Philips SECAM, 145.It 7 146Temic PAL I, 147.It 8 148Philips PAL I, 149.It 9 150Philips FR1236 NTSC FM, 151.It 10 152Philips FR1216 PAL FM, 153.It 11 154Philips FR1236 SECAM FM, 155.It 12 156ALPS TSCH5 NTSC FM, 157and 158.It 13 159ALPS TSBH1 NTSC. 160.El 161.It Cd options BKTR_OVERRIDE_DBX=n 162To override detection of the BTSC (dbx) chip, set this to 163.Em 1 164if you have one, or 165.Em 0 166if not. 167.It Cd options BKTR_OVERRIDE_MSP=n 168To override detection of the MSP 34xx chip, set this to 169.Em 1 170if you have one, or 171.Em 0 172if not. 173.It Cd options BKTR_SYSTEM_DEFAULT=n 174If this option is set to 175.Em BROOKTREE_PAL 176default to PAL, else to NTSC. 177.It Cd options BKTR_USE_PLL 178Default to PLL instead of XTAL. 179.It Cd options BKTR_GPIO_ACCESS 180Use 181.Fn ioctl Ns s 182for direct GPIO access. 183.It Cd options BKTR_NO_MSP_RESET 184Skip the MSP reset. 185This option is handy if you initialize the MSP audio in another 186operating system first and then do a soft reboot. 187.\" The following options have no effect: 188.\" .It Cd options BKTR_430_FX_MODE 189.\" .It Cd options BKTR_SIS_VIA_MODE 190.El 191.Sh VIDEO CAPTURE INTERFACE 192The video capture interface to 193.Nm 194is accessed through the 195.Pa /dev/bktrN 196devices. 197The following 198.Xr ioctl 2 199commands are supported on the Brooktree848 video capture interface: 200.Bl -tag -width Ds 201.It Dv METEORSFMT Fa "unsigned long *" 202This command sets the video format, also sometimes referred to as the 203video norm. 204The supported formats are: 205.Pp 206.Bl -tag -compact -width 28n 207.It Dv METEOR_FMT_NTSC 208NTSC 209.It Dv METEOR_FMT_PAL 210PAL 211.It Dv METEOR_FMT_SECAM 212SECAM 213.It Dv METEOR_FMT_AUTOMODE 214hardware default 215.El 216.It Dv METEORGFMT Fa "unsigned long *" 217This command retrieves the current video format to the 218.Vt unsigned long * 219argument. 220.It Dv METEORSETGEO Fa "struct meteor_geomet *" 221This command sets the video properties that affect the bit size of 222a frame through the 223.Vt meteor_geomet * 224argument. 225.Bd -literal 226struct meteor_geomet { 227 u_short rows; /* height in pixels*/ 228 u_short columns; /* width in pixels */ 229 u_short frames; 230 u_long oformat; 231} 232.Ed 233.Pp 234The 235.Va frames 236field is the number of frames to buffer. 237Currently only 1 frame is supported for most operations. 238.Pp 239The 240.Va oformat 241field is a bit-field describing the output pixel format 242type and which video fields to capture. 243The following are supported pixel format types: 244 .Pp 245.Bl -tag -compact -width 28n 246.It Dv METEOR_GEO_RGB16 24716-bit RGB 248.It Dv METEOR_GEO_RGB24 24924-bit RGB in 32 bits 250.It Dv METEOR_GEO_YUV_PACKED 25116-bit 4:2:2 YUV 252.It Dv METEOR_GEO_YUV_PLANAR 25316-bit 4:2:2 YUV 254.It Dv METEOR_GEO_YUV_UNSIGNED 255unsigned UV 256.It Dv METEOR_GEO_YUV_422 257.It Dv METEOR_GEO_YUV_12 258.It Dv METEOR_GEO_YUV_9 259.El 260.Pp 261The following are supported field capture modes: 262.Pp 263.Bl -tag -compact -width 28n 264.It Dv METEOR_GEO_ODD_ONLY 265only odd fields 266.It Dv METEOR_GEO_EVEN_ONLY 267only even fields 268.El 269.Pp 270By default, frames will consist of both the odd and even fields. 271.It Dv METEORGSUPPIXFMT Fa "struct meteor_pixfmt *" 272This command is used interactively to fetch descriptions of supported 273output pixel formats into the 274.Vt meteor_pixfmt * 275argument. 276.Bd -literal 277struct meteor_pixfmt { 278 u_int index; 279 METEOR_PIXTYPE type; 280 u_int Bpp; /* bytes per pixel */ 281 u_long masks[3]; /* YUV bit masks */ 282 unsigned swap_bytes :1; 283 unsigned swap_shorts:1; 284}; 285.Ed 286.Pp 287To query all the supported formats, start with an index field of 0 and 288continue with successive encodings (1, 2, ...) until the command returns 289an error. 290.It Dv METEORSACTPIXFMT Fa "int *" 291This command sets the active pixel format. 292The 293.Vt int * 294argument is the index of the pixel format as returned by 295.Dv METEORGSUPPIXFMT . 296.It Dv METEORGACTPIXFMT Fa "int *" 297This command fetches the active pixel format index into the 298.Vt int * 299argument. 300.It Dv METEORSINPUT Fa "unsigned long *" 301This command sets the input port of the Brooktree848 device. 302The following are supported input ports: 303.Pp 304.Bl -tag -compact -width 28n 305.It Dv METEOR_INPUT_DEV0 306composite (RCA) 307.It Dv METEOR_INPUT_DEV1 308tuner 309.It Dv METEOR_INPUT_DEV2 310composite S-video 311.It Dv METEOR_INPUT_DEV3 312mystery device 313.It Dv METEOR_INPUT_DEV_RGB 314rgb meteor 315.It Dv METEOR_INPUT_DEV_SVIDEO 316S-Video 317.El 318.Pp 319Not all devices built with Brooktree848 chips support the 320full list of input ports. 321.It Dv METEORGINPUT Fa "unsigned long *" 322This command retrieves the current input port to the 323.Vt unsigned long * 324argument. 325.It Dv METEORSFPS Fa "unsigned short *" 326This command sets the number of frames to grab each second. 327Valid frame rates are integers from 0 to 30. 328.It Dv METEORGFPS Fa "unsigned short *" 329This command fetches the number of frames to grab each second into the 330.Vt unsigned short * 331argument. 332.It Dv METEORCAPTUR Fa "int *" 333This command controls capturing of video data. 334The following are valid arguments: 335.Pp 336.Bl -tag -compact -width 28n 337.It Dv METEOR_CAP_SINGLE 338capture one frame 339.It Dv METEOR_CAP_CONTINOUS 340continuously capture 341.It Dv METEOR_CAP_STOP_CONT 342stop continuous capture 343.El 344.It Dv METEORSSIGNAL Fa "unsigned int *" 345This command controls the signal emission properties of 346.Nm . 347If the 348.Vt unsigned int * 349argument is a valid signal, then that signal will be emitted 350when either a frame or field capture has completed. 351To select between frame or field signalling, the following arguments 352are used: 353.Pp 354.Bl -tag -compact -width 28n 355.It Dv METEOR_SIG_FRAME 356signal every frame 357.It Dv METEOR_SIG_FIELD 358signal every field 359.El 360.Pp 361By default, signals will be generated for every frame. 362Generation of signals is terminated with the 363.Dv METEOR_SIG_MODE_MASK 364argument. 365.El 366.Sh TUNER INTERFACE 367Most cards supported by this driver feature a hardware television tuner 368on the I2C bus. 369The tuner interface to 370.Nm 371is accessed through the 372.Pa /dev/tunerN 373devices. 374The following 375.Xr ioctl 2 376commands are supported on the tuner interface: 377.Bl -tag -width Ds 378.It Dv TVTUNER_SETTYPE Fa "unsigned int *" 379This command sets the tuner's TV channel set, also sometimes called the TV 380channel band. 381This setting is used to calculate the proper tuning frequencies. 382The desired channel set must be selected before attempting to set the tuner 383channel or frequency. 384The following is a list of valid channel sets: 385.Pp 386.Bl -tag -compact -width 28n 387.It Dv CHNLSET_NABCST 388North America broadcast 389.It Dv CHNLSET_CABLEIRC 390North America IRC cable 391.It Dv CHNLSET_CABLEHRC 392North America HRC cable 393.It Dv CHNLSET_WEUROPE 394Western Europe 395.It Dv CHNLSET_JPNBCST 396Japan broadcast 397.It Dv CHNLSET_JPNCABLE 398Japan cable 399.It Dv CHNLSET_XUSSR 400Russia 401.It Dv CHNLSET_AUSTRALIA 402Australia 403.It Dv CHNLSET_FRANCE 404France 405.El 406.It Dv TVTUNER_GETTYPE Fa "unsigned int *" 407This command fetches the tuner's current channel set to the 408.Vt unsigned int * 409argument. 410.It Dv TVTUNER_SETCHNL Fa "unsigned int *" 411This command sets the tuner's frequency to a specified channel in the 412current channel set. 413.It Dv TVTUNER_GETCHNL Fa "unsigned int *" 414This command fetches the last selected channel. 415Note that it is not necessarily the current channel. 416In particular, changing the tuner's frequency by a command other than 417.Dv TVTUNER_SETCHNL 418will not update this setting, and it defaults to 0 on driver 419initialization. 420.It Dv TVTUNER_SETFREQ Fa "unsigned int *" 421This command sets the tuner's frequency to 1/16th the value of the 422.Vt unsigned int * 423argument, in MHz. 424Note that the current channelset is used to determine frequency 425offsets when this command is executed. 426.It Dv TVTUNER_GETFREQ Fa "unsigned int *" 427This command fetches the tuner's current frequency to the 428.Vt unsigned int * 429argument. 430Note that this value is 16 times the actual tuner frequency, in MHz. 431.It Dv BT848_SAUDIO Fa "int *" 432This command controls the audio input port and mute state. 433The following is a list of valid arguments: 434.Pp 435.Bl -tag -compact -width 18n 436.It Dv AUDIO_TUNER 437tuner audio port 438.It Dv AUDIO_EXTERN 439external audio port 440.It Dv AUDIO_INTERN 441internal audio port 442.It Dv AUDIO_MUTE 443mute audio 444.It Dv AUDIO_UNMUTE 445unmute audio 446.El 447.It Dv BT848_GAUDIO Fa "int *" 448This command fetches the audio input and mute state bits to the 449.Vt int * 450argument. 451.El 452.Sh FILES 453.Bl -tag -width /dev/tuner* -compact 454.It Pa /dev/bktr* 455.Nm 456driver interface device 457.It Pa /dev/tuner* 458.Nm 459tuner interface device 460.It Pa /dev/vbi* 461teletext interface device 462.El 463.Sh SEE ALSO 464.Xr options 4 , 465.Xr pci 4 , 466.Xr radio 4 , 467.Pa pkgsrc/audio/xmradio , 468.Pa pkgsrc/multimedia/ffmpeg , 469.Pa pkgsrc/multimedia/fxtv 470.Sh HISTORY 471The 472.Nm 473driver appeared in 474.Fx 2.2 475and 476.Nx 1.5 . 477.Sh AUTHORS 478The 479.Nm 480driver was originally written by Amancio Hasty for 481.Fx 482and is now maintained by Roger Hardiman. 483.Nx 484porting was done by Bernd Ernesti, Berndt Josef Wulf, Matthias 485Scheler, and Thomas Klausner. 486