1.\" $NetBSD: radio.9,v 1.5 2018/07/09 10:36:30 rkujawa 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 file, 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 is 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.Pp 78.Bl -tag -width XXXX 79.It Fn (*open) "sc" "flags" "fmt" "lwp" 80Called when the radio device is opened. 81Optional, if there is no need to call a driver's function when device file is 82opened, NULL should be passed in this field. 83Returns 0 on success, otherwise an error code. 84.It Fn (*close) "sc" "flags" "fmt" "lwp" 85Called when the radio device is closed. 86Optional, if there is no need to call a driver's function when device file is 87closed, NULL should be passed in thie field. 88Returns 0 on success, otherwise an error code. 89.It Fn (*get_info) "sc" "ri" 90Fills the radio_info struct. 91This function is used to obtain the current state of a hardware device. 92It is executed as a result of calling 93.Dv RIOCGINFO 94on a device file managed by the high level driver. 95Returns 0 on success, otherwise an error code. 96.It Fn (*set_info) "sc" "ri" 97Set values from the radio_info struct. 98This function is used to modify the current state of a hardware device 99(enable/disable various modes and parameters). 100It is executed as a result of calling 101.Dv RIOCSINFO 102on a device file managed by the high level driver. 103Returns 0 on success, otherwise an error code. 104.It Fn (*search) "sc" "ri" 105Initiates an automatic search for the radio station. 106It is executed as a result of calling 107.Dv RIOCSSRCH 108on a device file managed by the high level driver. 109Returns 0 on success, otherwise an error code. 110.El 111.Sh SEE ALSO 112.Xr radio 4 113.Sh AUTHORS 114The 115.Nm 116API was written by 117.An Vladimir Popov 118and 119.An Maxim Tsyplakov 120for 121.Ox 122and ported to 123.Nx 124by 125.An Lennart Augustsson . 126