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