xref: /openbsd-src/share/man/man4/bktr.4 (revision f2da64fbbbf1b03f09f390ab01267c93dfd77c4c) 
1.\"
2.\" Copyright (c) 1998 Amancio Hasty and Roger Hardiman
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\"
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\"    must display the following acknowledgement:
16.\"	This product includes software developed by Amancio Hasty and
17.\"	Roger Hardiman.
18.\" 4. The name of the author may not be used to endorse or promote products
19.\"    derived from this software without specific prior written permission.
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31.\"
32.\" $OpenBSD: bktr.4,v 1.29 2015/09/14 17:09:26 schwarze Exp $
33.\" $FreeBSD: /c/ncvs/src/share/man/man4/bktr.4,v 1.9.2.5 2001/03/06 19:08:09 ru Exp $
34.\"
35.Dd $Mdocdate: September 14 2015 $
36.Dt BKTR 4
37.Os
38.Sh NAME
39.Nm bktr
40.Nd Brooktree Bt848/849/878/879 PCI TV tuners and video capture boards
41.Sh SYNOPSIS
42.Cd "bktr* at pci?"
43.Cd "radio* at bktr?"
44.Pp
45.In dev/ic/bt8xx.h
46.Pp
47.Cd "option BKTR_ALLOC_PAGES=nnn"
48.Cd "option BKTR_SYSTEM_DEFAULT=XXX"
49.Cd "option BKTR_OVERRIDE_CARD=nnn"
50.Cd "option BKTR_OVERRIDE_MSP=n"
51.Cd "option BKTR_OVERRIDE_TUNER=nnn"
52.Sh DESCRIPTION
53The
54.Nm
55driver provides support for PCI video capture and VBI capture on low cost,
56high performance boards.
57This should support most video cards based on the
58Brooktree Bt848/849/878/879 Video Capture Chip.
59The driver also supports FM Radio if the Tuner supports it.
60.Pp
61Specifically, the following cards are known to work:
62.Bd -unfilled -offset indent
63Animation Technologies FlyVideo
64AOpen VA1000
65Askey/Dynalink Magic TView
66ATI TV-Wonder and Wonder/VE
67AverMedia cards
68Hauppauge Wincast TV and WinTV/PCI
69IMS TV Turbo
70Intel Smart Video Recorder III
71I/O DATA GV-BCTV2/PCI
72I/O DATA GV-BCTV3/PCI
73KISS TV/FM PCI
74Leadtek Winfast TV 2000
75Leadtek Winfast TV 2000 XP
76Miro PC TV
77MMAC Osprey
78NEC PK-UG-X017
79STB TV PCI Television Tuner
80Terratec TerraTVplus
81Video Highway XTreme
82VideoLogic Captivator PCI
83Zoltrix TV and Genie TV/FM
84.Ed
85.Pp
86The driver currently supports the following features:
87.Bd -unfilled -offset indent
88PCI to PCI DMA transfer
89clipping
90yuv
91rgb16
92rgb24
93rgb32
94.Ed
95.Pp
96On these cards, tuners and other components are interconnected with an I2C bus.
97The Brooktree848 chips act as a master device on the bus to control them.
98.Sh VIDEO CAPTURE INTERFACE
99The video capture interface to
100.Nm
101is accessed through
102.Pa /dev/bktrN
103devices.
104The following
105.Xr ioctl 2
106commands are supported on the Brooktree848 video capture interface:
107.Bl -tag -width Ds
108.It Dv METEORSFMT Fa "unsigned long *"
109This command sets the video format, also sometimes referred to as the
110video norm.
111The supported formats are:
112.Pp
113.Bl -tag -compact -width 28n
114.It Dv METEOR_FMT_NTSC
115NTSC
116.It Dv METEOR_FMT_PAL
117PAL
118.It Dv METEOR_FMT_SECAM
119SECAM
120.It Dv METEOR_FMT_AUTOMODE
121hardware default
122.El
123.It Dv METEORGFMT Fa "unsigned long *"
124This command retrieves the current video format to the
125.Vt unsigned long *
126argument.
127.It Dv METEORSETGEO Fa "struct meteor_geomet *"
128This command sets the video properties that affect the bit size of
129a frame through the
130.Vt meteor_geomet *
131argument.
132.Bd -literal
133struct meteor_geomet {
134	u_short		rows;	 /* height in pixels*/
135	u_short		columns; /* width in pixels */
136	u_short		frames;
137	u_long		oformat;
138}
139.Ed
140.Pp
141The
142.Va frames
143field is the number of frames to buffer.
144Currently only 1 frame is supported for most operations.
145.Pp
146The
147.Va oformat
148field is a bit-field describing the output pixel format
149type and which video fields to capture.
150The following are supported pixel format types:
151.Pp
152.Bl -tag -compact -width 28n
153.It Dv METEOR_GEO_RGB16
15416-bit RGB
155.It Dv METEOR_GEO_RGB24
15624-bit RGB in 32 bits
157.It Dv METEOR_GEO_YUV_PACKED
15816-bit 4:2:2 YUV
159.It Dv METEOR_GEO_YUV_PLANAR
16016-bit 4:2:2 YUV
161.It Dv METEOR_GEO_YUV_UNSIGNED
162unsigned UV
163.It Dv METEOR_GEO_YUV_422
164.It Dv METEOR_GEO_YUV_12
165.It Dv METEOR_GEO_YUV_9
166.El
167.Pp
168The following are supported field capture modes:
169.Pp
170.Bl -tag -compact -width 28n
171.It Dv METEOR_GEO_ODD_ONLY
172only odd fields
173.It Dv METEOR_GEO_EVEN_ONLY
174only even fields
175.El
176.Pp
177By default, frames will consist of both the odd and even fields.
178.It Dv METEORGSUPPIXFMT Fa "struct meteor_pixfmt *"
179This command is used iteratively to fetch descriptions of supported
180output pixel formats into the
181.Vt meteor_pixfmt *
182argument.
183.Bd -literal
184struct meteor_pixfmt {
185	u_int          index;
186	METEOR_PIXTYPE type;
187	u_int          Bpp;		/* bytes per pixel */
188	u_long         masks[3];	/* YUV bit masks */
189	unsigned       swap_bytes :1;
190	unsigned       swap_shorts:1;
191};
192.Ed
193.Pp
194To query all the supported formats, start with an index field of 0 and
195continue with successive encodings (1, 2, ...) until the command returns
196an error.
197.It Dv METEORSACTPIXFMT Fa "int *"
198This command sets the active pixel format.
199The
200.Vt int *
201argument is the index of the pixel format as returned by
202.Dv METEORGSUPPIXFMT .
203.It Dv METEORGACTPIXFMT Fa "int *"
204This command fetches the active pixel format index into the
205.Vt int *
206argument.
207.It Dv METEORSINPUT Fa "unsigned long *"
208This command sets the input port of the Brooktree848 device.
209The following are supported input ports:
210.Pp
211.Bl -tag -compact -width 28n
212.It Dv METEOR_INPUT_DEV0
213composite (RCA)
214.It Dv METEOR_INPUT_DEV1
215tuner
216.It Dv METEOR_INPUT_DEV2
217composite S-video
218.It Dv METEOR_INPUT_DEV3
219mystery device
220.It Dv METEOR_INPUT_DEV_RGB
221rgb meteor
222.It Dv METEOR_INPUT_DEV_SVIDEO
223S-Video
224.El
225.Pp
226Not all devices built with Brooktree848 chips support the
227full list of input ports.
228.It Dv METEORGINPUT Fa "unsigned long *"
229This command retrieves the current input port to the
230.Vt unsigned long *
231argument.
232.It Dv METEORSFPS Fa "unsigned short *"
233This command sets the number of frames to grab each second.
234Valid frame rates are integers from 0 to 30.
235.It Dv METEORGFPS Fa "unsigned short *"
236This command fetches the number of frames to grab each second into the
237.Vt unsigned short *
238argument.
239.It Dv METEORCAPTUR Fa "int *"
240This command controls capturing of video data.
241The following are valid arguments:
242.Pp
243.Bl -tag -compact -width 28n
244.It Dv METEOR_CAP_SINGLE
245capture one frame
246.It Dv METEOR_CAP_CONTINOUS
247continuously capture
248.It Dv METEOR_CAP_STOP_CONT
249stop continuous capture
250.El
251.It Dv METEORSSIGNAL Fa "unsigned int *"
252This command controls the signal emission properties of
253.Nm .
254If the
255.Vt unsigned int *
256argument is a valid signal, then that signal will be emitted
257when either a frame or field capture has completed.
258To select between frame or field signalling, the following arguments
259are used:
260.Pp
261.Bl -tag -compact -width 28n
262.It Dv METEOR_SIG_FRAME
263signal every frame
264.It Dv METEOR_SIG_FIELD
265signal every field
266.El
267.Pp
268By default, signals will be generated for every frame.
269Generation of signals is terminated with the
270.Dv METEOR_SIG_MODE_MASK
271argument.
272.El
273.Sh TUNER INTERFACE
274Most cards supported by this driver feature a hardware television tuner
275on the I2C bus.
276The tuner interface to
277.Nm
278is accessed through
279.Pa /dev/tunerN
280devices.
281The following
282.Xr ioctl 2
283commands are supported on the tuner interface:
284.Bl -tag -width Ds
285.It Dv TVTUNER_SETTYPE Fa "unsigned int *"
286This command sets the tuner's TV channel set, also sometimes called the TV
287channel band.
288This setting is used to calculate the proper tuning frequencies.
289The desired channel set must be selected before attempting to set the tuner
290channel or frequency.
291The following is a list of valid channel sets:
292.Pp
293.Bl -tag -compact -width 28n
294.It Dv CHNLSET_NABCST
295North America broadcast
296.It Dv CHNLSET_CABLEIRC
297North America IRC cable
298.It Dv CHNLSET_CABLEHRC
299North America HRC cable
300.It Dv CHNLSET_WEUROPE
301Western Europe
302.It Dv CHNLSET_JPNBCST
303Japan broadcast
304.It Dv CHNLSET_JPNCABLE
305Japan cable
306.It Dv CHNLSET_XUSSR
307Russia
308.It Dv CHNLSET_AUSTRALIA
309Australia
310.It Dv CHNLSET_FRANCE
311France
312.El
313.It Dv TVTUNER_GETTYPE Fa "unsigned int *"
314This command fetches the tuner's current channel set to the
315.Vt unsigned int *
316argument.
317.It Dv TVTUNER_SETCHNL Fa "unsigned int *"
318This command sets the tuner's frequency to a specified channel in the
319current channel set.
320.It Dv TVTUNER_GETCHNL Fa "unsigned int *"
321This command fetches the last selected channel.
322Note that it is not necessarily the current channel.
323In particular, changing the tuner's frequency by a command other than
324.Dv TVTUNER_SETCHNL
325will not update this setting, and it defaults to 0 on driver
326initialization.
327.It Dv TVTUNER_SETFREQ Fa "unsigned int *"
328This command sets the tuner's frequency to 1/16th the value of the
329.Vt unsigned int *
330argument, in MHz.
331Note that the current channelset is used to determine frequency
332offsets when this command is executed.
333.It Dv TVTUNER_GETFREQ Fa "unsigned int *"
334This command fetches the tuner's current frequency to the
335.Vt unsigned int *
336argument.
337Note that this value is 16 times the actual tuner frequency, in MHz.
338.It Dv BT848_SAUDIO Fa "int *"
339This command controls the audio input port and mute state.
340The following is a list of valid arguments:
341.Pp
342.Bl -tag -compact -width 18n
343.It Dv AUDIO_TUNER
344tuner audio port
345.It Dv AUDIO_EXTERN
346external audio port
347.It Dv AUDIO_INTERN
348internal audio port
349.It Dv AUDIO_MUTE
350mute audio
351.It Dv AUDIO_UNMUTE
352unmute audio
353.El
354.It Dv BT848_GAUDIO Fa "int *"
355This command fetches the audio input and mute state bits to the
356.Vt int *
357argument.
358.El
359.Sh KERNEL OPTIONS
360The following kernel configuration options are available:
361.Bl -tag -width xxxxxxxx
362.It Cd option BKTR_ALLOC_PAGES=nnn
363Specifies the number of contiguous pages to allocate when successfully
364probed.
365The default number of pages allocated by the kernel is 216.
366This means that there are (216*4096) bytes available for use.
367.It Cd option BKTR_SYSTEM_DEFAULT="(BROOKTREE_PAL | BROOKTREE_NTSC)"
368One of these options can be used to set the default video format for the driver.
369This fixed random hangs and lockups with the VideoLogic Captivator PCI card.
370.It Cd option BKTR_OVERRIDE_CARD=nnn
371Select a specific card (overrides autodetection).
372`nnn' is set to one of the names listed and explained below.
373.Pp
374.Bl -tag -width "CARD_ASKEY_DYNALINK_MAGIC_TVIEW" -compact
375.It CARD_ASKEY_DYNALINK_MAGIC_TVIEW
376Askey/Dynalink Magic TView
377.It CARD_AVER_MEDIA
378AverMedia
379.It CARD_FLYVIDEO
380Animation Technologies FlyVideo
381.It CARD_AOPEN_VA1000
382AOpen VA1000
383.It CARD_TVWONDER
384ATI TV-Wonder/VE
385.It CARD_HAUPPAUGE
386Hauppauge Wincast TV and WinTV
387.It CARD_IMS_TURBO
388IMS TV Turbo
389.It CARD_INTEL
390Intel Smart Video Recorder III
391.It CARD_IO_GV
392I/O DATA GV-BCTV2/PCI
393.It CARD_IO_BCTV3
394I/O DATA GV-BCTV3/PCI
395.It CARD_KISS
396KISS TV/FM PCI
397.It CARD_LEADTEK
398Leadtek Winfast TV 2000
399.It CARD_LEADTEK_XP
400Leadtek Winfast TV 2000 XP
401.It CARD_MIRO
402Miro PC TV
403.It CARD_OSPREY
404MMAC Osprey
405.It CARD_NEC_PK
406NEC PK-UG-X017
407.It CARD_STB
408STB TV PCI Television Tuner
409.It CARD_TERRATVPLUS
410Terratec TerraTVplus
411.It CARD_VIDEO_HIGHWAY_XTREME
412Video Highway XTreme
413.It CARD_ZOLTRIX
414Zoltrix TV
415.It CARD_ZOLTRIX_GENIE_FM
416Zoltrix Genie TV/FM
417.El
418.It Cd option BKTR_OVERRIDE_MSP=n
419Specifies whether the MSP3400C chip is present (overrides autodetection).
420.It Cd option BKTR_OVERRIDE_TUNER=nnn
421Select a specific tuner (overrides autodetection).
422`nnn' is set to one of the names listed and explained below.
423.Pp
424.Bl -tag -compact -width 28n
425.It TEMIC_NTSC
426Temic 4032FY5
427.It TEMIC_PAL
428Temic 4002FH5
429.It TEMIC_SECAM
430Temic 4002FN5
431.It PHILIPS_NTSC
432Philips FI1236
433.It PHILIPS_PAL
434Philips FM1216
435.It PHILIPS_SECAM
436Philips FI1216MF
437.It TEMIC_PALI
438Temic 4062FY5
439.It PHILIPS_PALI
440Philips FI1246
441.It PHILIPS_FR1236_NTSC
442Philips FR1236 MK2
443.It PHILIPS_FR1216_PAL
444Philips FM1216
445.It PHILIPS_FR1236_SECAM
446Philips FM1216MF
447.It ALPS_TSCH5
448Apls TSCH5 NTSC
449.It ALPS_TSBH1
450Apls TSBH1 NTSC
451.It TIVISION_TVF5533
452Tivision TVF5533-MF NTSC
453.El
454.El
455.Sh SEE ALSO
456.Xr intro 4 ,
457.Xr pci 4 ,
458.Xr radio 4
459.Sh HISTORY
460The
461.Nm
462driver first appeared in
463.Fx 2.2 .
464.Sh AUTHORS
465.An -nosplit
466The
467.Nm
468driver is based on the work of
469.An Jim Lowe Aq Mt james@miller.cs.uwm.edu ,
470.An Mark Tinguely Aq Mt tinguely@plains.nodak.edu ,
471.An Amancio Hasty Aq Mt hasty@star\-gate.com ,
472.An Roger Hardiman Aq Mt roger@FreeBSD.org
473and a bunch of other people.
474.Sh CAVEATS
475On big-endian architectures it is not possible to program the
476card to perform proper byte swapping in 24 bit modes,
477therefore only 16 and 32 bit modes are supported.
478