.\"	$NetBSD: radio.4,v 1.16 2022/07/08 16:50:10 nia Exp $
.\"	$RuOBSD: radio.4,v 1.4 2001/10/26 05:38:43 form Exp $
.\"	$OpenBSD: radio.4,v 1.3 2001/12/05 10:58:54 mickey Exp $
.\"
.\" Copyright (c) 2001 Vladimir Popov
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
.\" ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd October 20, 2001
.Dt RADIO 4
.Os
.Sh NAME
.Nm radio
.Nd device-independent radio driver layer
.Sh SYNOPSIS
.Cd "radio* at az?"
.Cd "radio* at bktr?"
.Cd "radio* at gtp?"
.Cd "radio* at rt?"
.Cd "radio* at rtii?"
.Cd "radio* at sf2r?"
.Cd "radio* at slurm?"
.Cd "radio* at udsbr?"
.Pp
.In sys/types.h
.In sys/ioctl.h
.In sys/radioio.h
.Sh DESCRIPTION
The
.Nm
driver provides support for various FM radio cards.
It provides an uniform programming interface layer above different underlying
radio hardware drivers.
.Pp
For radio tuner controlling there is a single device file available:
.Pa /dev/radio .
.Pp
The following
.Xr ioctl 2
commands are supported:
.Pp
.Bl -tag -width indent -compact
.It Dv RIOCSSRCH (int)
This command assumes that a signal search is required and gives direction
of search to the driver \- 0 to search down and any non-zero value to search up.
.It Dv RIOCGINFO (struct radio_info)
.It Dv RIOCSINFO (struct radio_info)
Get or set the current hardware device information into the struct radio_info
structure.
.Bd -literal
struct radio_info {
	int	mute;
	int	volume;
	int	stereo;
	int	rfreq;	/* reference frequency */
	int	lock;	/* locking field strength */
	uint32_t	freq;	/* in kHz */
	uint32_t	caps;	/* card capabilities */
#define RADIO_CAPS_DETECT_STEREO	(1<<0)
#define RADIO_CAPS_DETECT_SIGNAL	(1<<1)
#define RADIO_CAPS_SET_MONO		(1<<2)
#define RADIO_CAPS_HW_SEARCH		(1<<3)
#define RADIO_CAPS_HW_AFC		(1<<4)
#define RADIO_CAPS_REFERENCE_FREQ	(1<<5)
#define RADIO_CAPS_LOCK_SENSITIVITY	(1<<6)
#define RADIO_CARD_TYPE			(0xFF<<16)
	uint32_t	info;
#define RADIO_INFO_STEREO		(1<<0)
#define RADIO_INFO_SIGNAL		(1<<1)
};
.Ed
.Pp
The
.Va mute
field is a boolean.
.Pp
The
.Va volume
field holds the card volume information and can be at most 255.
.Pp
The
.Va stereo
field is a boolean.
.Pp
The
.Va rfreq
holds information about the card reference frequency (not all cards support
this feature).
.Pp
The
.Va lock
field holds information about the card locking field strength during
an automatic search for cards that support this feature.
.Pp
The
.Va freq
field is the frequency in kHz the card is tuned to.
.Pp
The
.Va caps
field is read-only and describes the card capabilities.
The capabilities can have following values:
.Bl -tag -width indent -compact
.It Dv RADIO_CAPS_DETECT_STEREO
The device can determine is it tuned to a stereo signal.
.It Dv RADIO_CAPS_DETECT_SIGNAL
The device can determine is it tuned or not.
.It Dv RADIO_CAPS_SET_MONO
The device capable to forcible set its output to mono.
.It Dv RADIO_CAPS_HW_SEARCH
The device can do hardware search.
.It Dv RADIO_CAPS_HW_AFC
The device has an internal hardware automatic frequency control.
.It Dv RADIO_CAPS_REFERENCE_FREQ
The device allow to change the reference frequency of a received signal.
.It Dv RADIO_CAPS_LOCK_SENSITIVITY
The device allow to change the station lock sensitivity used during search
operation.
.It Dv RADIO_CARD_TYPE
Some cards have several different incarnations.
This allow to determine the variant of the card.
Currently not used.
.El
.Pp
The
.Va info
field is read-only and describes the current state of the card \-
tuned/not tuned, stereo signal/mono signal.
.Bl -tag -width indent -compact
.It Dv RADIO_INFO_STEREO
Informs whether the device receives a stereo or mono signal.
.It Dv RADIO_INFO_SIGNAL
Informs whether the device receives a valid signal or noise.
.El
.El
.Sh FILES
.Bl -tag -width /dev/radio -compact
.It Pa /dev/radio
.El
.Sh SEE ALSO
.Xr radioctl 1 ,
.Xr ioctl 2 ,
.Xr az 4 ,
.Xr bktr 4 ,
.Xr gtp 4 ,
.Xr rt 4 ,
.Xr rtii 4 ,
.Xr sf2r 4 ,
.Xr slurm 4 ,
.Xr udsbr 4
.Sh HISTORY
The
.Nm
device driver appeared in
.Ox 3.0
and
.Nx 1.6 .
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was written by
.An Vladimir Popov
and
.An Maxim Tsyplakov
for
.Ox
and ported to
.Nx
by
.An Lennart Augustsson .
The man page was written by Vladimir Popov.