xref: /netbsd-src/share/man/man9/radio.9 (revision 7eb04c438cb7adaa6fd27c88ce04c1e3f663daa4)
1.\"	$NetBSD: radio.9,v 1.6 2018/07/18 16:40:30 wiz Exp $
2.\"	$OpenBSD: radio.9,v 1.2 2001/10/08 08:52:50 mpech Exp $
3.\"
4.\" Copyright (c) Maxim Tsyplakov <tm@oganer.net>
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 July 9, 2018
28.Dt RADIO 9
29.Os
30.Sh NAME
31.Nm radio
32.Nd interface between low- and high-level FM radio drivers
33.Sh SYNOPSIS
34.In dev/radio_if.h
35.Ft device_t
36.Fo radio_attach_mi
37.Fa "const struct radio_hw_if *rhwp"
38.Fa "void *hdlp"
39.Fa "device_t dev"
40.Fc
41.Sh DESCRIPTION
42The
43.Nm
44layer provides support for digitally programmable FM radio tuners.
45.Pp
46It is divided into a machine independent, high-level part responsible for
47managing device files, and low-level hardware drivers.
48.Pp
49The high-level radio driver attaches to the low-level driver
50when the latter calls
51.Fn radio_attach_mi .
52.Pp
53The
54.Fa radio_hw_if
55struct contains pointers to functions provided by the low-level driver.
56The
57.Fa hdlp
58argument is a handle to a low-level driver's softc structure.
59It is sent as the first argument to all the functions in
60.Fa radio_hw_if
61when the high-level driver calls them.
62.Fa dev
63is the device struct for the hardware device.
64.Pp
65The fields of
66.Fa radio_hw_if
67are described in some more detail below.
68.Bd -literal
69struct radio_hw_if {
70	int	(*open)(void *, int, int, struct lwp *);
71	int	(*close)(void *, int, int, struct lwp *);
72	int     (*get_info)(void *, struct radio_info *);
73	int     (*set_info)(void *, struct radio_info *);
74	int     (*search)(void *, int);
75};
76.Ed
77.Bl -tag -width XXXX
78.It Fn (*open) "sc" "flags" "fmt" "lwp"
79Called when the radio device is opened.
80Optionally, if there is no need to call a driver's function when the device file is
81opened,
82.Dv NULL
83should be passed in this field.
84Returns 0 on success, otherwise an error code.
85.It Fn (*close) "sc" "flags" "fmt" "lwp"
86Called when the radio device is closed.
87Optionally, if there is no need to call a driver's function when the device file is
88closed,
89.Dv NULL
90should be passed in thie field.
91Returns 0 on success, otherwise an error code.
92.It Fn (*get_info) "sc" "ri"
93Fills the radio_info struct.
94This function is used to obtain the current state of a hardware device.
95It is executed as a result of calling
96.Dv RIOCGINFO
97on a device file managed by the high-level driver.
98Returns 0 on success, otherwise an error code.
99.It Fn (*set_info) "sc" "ri"
100Set values from the radio_info struct.
101This function is used to modify the current state of a hardware device
102(enable/disable various modes and parameters).
103It is executed as a result of calling
104.Dv RIOCSINFO
105on a device file managed by the high-level driver.
106Returns 0 on success, otherwise an error code.
107.It Fn (*search) "sc" "ri"
108Initiates automatic search for the radio station.
109It is executed as a result of calling
110.Dv RIOCSSRCH
111on a device file managed by the high-level driver.
112Returns 0 on success, otherwise an error code.
113.El
114.Sh SEE ALSO
115.Xr radio 4
116.Sh AUTHORS
117.An -nosplit
118The
119.Nm
120API was written by
121.An Vladimir Popov
122and
123.An Maxim Tsyplakov
124for
125.Ox
126and ported to
127.Nx
128by
129.An Lennart Augustsson .
130