xref: /openbsd/share/man/man4/radio.4 (revision 09467b48) 
1.\"	$RuOBSD: radio.4,v 1.4 2001/10/26 05:38:43 form Exp $
2.\"	$OpenBSD: radio.4,v 1.31 2017/09/12 14:57:15 schwarze Exp $
3.\"
4.\" Copyright (c) 2001 Vladimir Popov
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
21.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
22.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
23.\" ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26.\"
27.Dd $Mdocdate: September 12 2017 $
28.Dt RADIO 4
29.Os
30.Sh NAME
31.Nm radio
32.Nd device-independent radio driver layer
33.Sh SYNOPSIS
34.Cd "radio* at bktr?"
35.Cd "radio* at fms?"
36.Cd "radio* at udsbr?"
37.Pp
38.In sys/types.h
39.In sys/ioctl.h
40.In sys/radioio.h
41.Sh DESCRIPTION
42The
43.Nm
44driver provides support for various FM radio cards.
45It provides an uniform programming interface layer above different underlying
46radio hardware drivers.
47.Pp
48For radio tuner controlling there is a single device file available:
49.Pa /dev/radio .
50.Pp
51The following
52.Xr ioctl 2
53commands are supported:
54.Pp
55.Bl -tag -width indent -compact
56.It Dv RIOCSSRCH Fa int
57This command assumes that a signal search is required and gives direction
58of search to the driver \- 0 to search down and any non-zero value to search up.
59.It Dv RIOCGINFO Fa "struct radio_info"
60.It Dv RIOCSINFO Fa "struct radio_info"
61Get or set the current hardware device information into the
62.Fa radio_info
63structure.
64.Bd -literal
65struct radio_info {
66	int	mute;
67	int	volume;
68	int	stereo;
69	int	rfreq;	/* reference frequency */
70	int	lock;	/* locking field strength */
71	u_int32_t	freq;	/* in kHz */
72	u_int32_t	caps;	/* card capabilities */
73#define RADIO_CAPS_DETECT_STEREO	(1<<0)
74#define RADIO_CAPS_DETECT_SIGNAL	(1<<1)
75#define RADIO_CAPS_SET_MONO		(1<<2)
76#define RADIO_CAPS_HW_SEARCH		(1<<3)
77#define RADIO_CAPS_HW_AFC		(1<<4)
78#define RADIO_CAPS_REFERENCE_FREQ	(1<<5)
79#define RADIO_CAPS_LOCK_SENSITIVITY	(1<<6)
80#define RADIO_CARD_TYPE			(0xFF<<16)
81	u_int32_t	info;
82#define RADIO_INFO_STEREO		(1<<0)
83#define RADIO_INFO_SIGNAL		(1<<1)
84	u_int32_t	tuner_mode;
85#define RADIO_TUNER_MODE_RADIO		(1<<0)
86#define RADIO_TUNER_MODE_TV		(1<<1)
87	u_int32_t	chan;
88	u_int32_t	chnlset;
89};
90.Ed
91.Pp
92The
93.Va mute
94field is a boolean.
95.Pp
96The
97.Va volume
98field holds the card volume information and can be at most 255.
99.Pp
100The
101.Va stereo
102field is a boolean.
103.Pp
104The
105.Va rfreq
106holds information about the card reference frequency (not all cards support
107this feature).
108.Pp
109The
110.Va lock
111field holds information about the card locking field strength during
112an automatic search for cards that support this feature.
113.Pp
114The
115.Va freq
116field is the frequency in kHz the card is tuned to.
117.Pp
118The
119.Va tuner_mode
120field is the current tuning mode of the tuner.
121Valid modes are:
122.Pp
123.Bl -tag -width indent -compact
124.It Dv RADIO_TUNER_MODE_RADIO
125The tuner operates in FM radio mode.
126.It Dv RADIO_TUNER_MODE_TV
127The tuner operates in TV mode.
128.El
129.Pp
130The
131.Va caps
132field is read-only and describes the card capabilities.
133The capabilities can have the following values:
134.Pp
135.Bl -tag -width indent -compact
136.It Dv RADIO_CAPS_DETECT_STEREO
137The device can determine if it is tuned to a stereo signal.
138.It Dv RADIO_CAPS_DETECT_SIGNAL
139The device can determine if it is tuned or not.
140.It Dv RADIO_CAPS_SET_MONO
141The device is capable of forcibly setting its output to mono.
142.It Dv RADIO_CAPS_HW_SEARCH
143The device can do hardware search.
144.It Dv RADIO_CAPS_HW_AFC
145The device has an internal hardware automatic frequency control.
146.It Dv RADIO_CAPS_REFERENCE_FREQ
147The device allows changing the reference frequency of a received signal.
148.It Dv RADIO_CAPS_LOCK_SENSITIVITY
149The device allows changing the station lock sensitivity used during search
150operation.
151.It Dv RADIO_CARD_TYPE
152Some cards have several different incarnations.
153This allows the variant of the card to be determined.
154Currently not used.
155.El
156.Pp
157The
158.Va info
159field is read-only and describes the current state of the card \-
160tuned/not tuned, stereo signal/mono signal.
161.Pp
162.Bl -tag -width indent -compact
163.It Dv RADIO_INFO_STEREO
164Informs whether the device receives a stereo or mono signal.
165.It Dv RADIO_INFO_SIGNAL
166Informs whether the device receives a valid signal or noise.
167.El
168.Pp
169The
170.Va chan
171holds the TV channel the card is tuned to.
172.Pp
173The
174.Va chnlset
175specifies the TV channel set currently being used.
176The tuner uses the current channel set to derive the tuning frequency
177from the channel number.
178Western Europe is the default channel set.
179The following is a list of valid channel sets:
180.Pp
181.Bl -tag -width indent -compact
182.It 1
183U.S.A. Broadcast
184.It 2
185U.S.A. Cable IRC
186.It 3
187U.S.A. Cable HRC
188.It 4
189Western Europe
190.It 5
191Japan Broadcast
192.It 6
193Japan Cable
194.It 7
195Former U.S.S.R. and C.I.S. Countries
196.It 8
197Australia
198.It 9
199France
200.El
201.El
202.Pp
203Either
204.Va freq
205or
206.Va chan
207can be used to tune to FM radio stations or TV channels,
208respectively.
209Some devices may not support both functionalities.
210.Sh CHIPSETS
211The TEA5757; TEA5759 is a 44-pin integrated AM/FM stereo radio circuit.
212The radio part is based on the TEA5712.
213The TEA5757 is used in FM-standards in which the local oscillator frequency
214is above the radio frequency (e.g. European and American standards).
215The TEA5759 is the version in which the oscillator frequency is below
216the radio frequency (e.g. Japanese standards).
217To conform with the Japanese standards, it is necessary to set the flags' least
218significant bit to 1.
219The TEA5757; TEA5759 has a 25-bit read-write shift register.
220The TEA5757 chips are used in
221.Xr fms 4
222cards.
223.Sh FILES
224.Bl -tag -width /dev/radio -compact
225.It Pa /dev/radio
226.El
227.Sh SEE ALSO
228.Xr radioctl 1 ,
229.Xr ioctl 2 ,
230.Xr bktr 4 ,
231.Xr fms 4 ,
232.Xr intro 4 ,
233.Xr udsbr 4 ,
234.Xr radio 9
235.Sh HISTORY
236The
237.Nm
238device driver appeared in
239.Ox 3.0 .
240.Sh AUTHORS
241.An -nosplit
242The
243.Nm
244driver was written by
245.An Vladimir Popov Aq Mt jumbo@narod.ru
246and
247.An Maxim Tsyplakov Aq Mt tm@oganer.net .
248The man page was written by
249.An Vladimir Popov Aq Mt jumbo@narod.ru .
250