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