Module Name: src
Committed By: rkujawa
Date: Mon Jul 9 10:36:30 UTC 2018
Modified Files:
src/share/man/man9: radio.9
Log Message:
Try to bring this man page up to NetBSD standards.
This page is bad and we should feel bad about it. But perhaps now it is
considerably less bad.
To generate a diff of this commit:
cvs rdiff -u -r1.4 -r1.5 src/share/man/man9/radio.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/radio.9
diff -u src/share/man/man9/radio.9:1.4 src/share/man/man9/radio.9:1.5
--- src/share/man/man9/radio.9:1.4 Tue Dec 20 19:53:15 2005
+++ src/share/man/man9/radio.9 Mon Jul 9 10:36:30 2018
@@ -1,4 +1,4 @@
-.\" $NetBSD: radio.9,v 1.4 2005/12/20 19:53:15 rpaulo Exp $
+.\" $NetBSD: radio.9,v 1.5 2018/07/09 10:36:30 rkujawa Exp $
.\" $OpenBSD: radio.9,v 1.2 2001/10/08 08:52:50 mpech Exp $
.\"
.\" Copyright (c) Maxim Tsyplakov <t...@oganer.net>
@@ -24,77 +24,102 @@
.\" (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 December 20, 2005
+.Dd July 9, 2018
.Dt RADIO 9
.Os
.Sh NAME
.Nm radio
-.Nd interface between low and high level radio drivers
+.Nd interface between low and high level FM radio drivers
+.Sh SYNOPSIS
+.In dev/radio_if.h
+.Ft device_t
+.Fo radio_attach_mi
+.Fa "const struct radio_hw_if *rhwp"
+.Fa "void *hdlp"
+.Fa "device_t dev"
+.Fc
.Sh DESCRIPTION
-The radio device driver is divided into a high level,
-hardware independent layer, and a low level hardware
-dependent layer.
-The interface between these is the
-.Va radio_hw_if
-structure.
-.Bd -literal
-struct radio_hw_if {
- int (*open)(void *, int, int, struct lwp *);
- int (*close)(void *, int, int, struct lwp *);
- int (*get_info)(void *, struct radio_info *);
- int (*set_info)(void *, struct radio_info *);
- int (*search)(void *, int);
-};
-.Ed
+The
+.Nm
+layer provides support for digitally programmable FM radio tuners.
+.Pp
+It is divided into a machine independent, high level part responsible for
+managing device file, and low level hardware drivers.
.Pp
The high level radio driver attaches to the low level driver
when the latter calls
-.Va radio_attach_mi .
-This call should be
-.Bd -literal
- void
- radio_attach_mi(rhwp, hdlp, dev)
- struct radio_hw_if *rhwp;
- void *hdlp;
- struct device *dev;
-.Ed
+.Fn radio_attach_mi .
.Pp
The
-.Va radio_hw_if
-struct is as shown above.
+.Fa radio_hw_if
+struct is contains pointers to functions provided by the low level driver.
The
-.Va hdlp
-argument is a handle to some low level data structure.
+.Fa hdlp
+argument is a handle to a low level driver's softc structure.
It is sent as the first argument to all the functions in
-.Va radio_hw_if
+.Fa radio_hw_if
when the high level driver calls them.
-.Va dev
+.Fa dev
is the device struct for the hardware device.
.Pp
The fields of
-.Va radio_hw_if
+.Fa radio_hw_if
are described in some more detail below.
.Bd -literal
-int open (void *, int flags, int fmt, struct lwp *p);
- Optional.
- Is called when the radio device is opened.
- Returns 0 on success, otherwise an error code.
-
-int close (void *, int flags, int fmt, struct lwp *p);
- Optional.
- Is called when the radio device is closed.
- Returns 0 on success, otherwise an error code.
-
-int get_info (void *, struct radio_info *);
- Fill the radio_info struct.
- Returns 0 on success, otherwise an error code.
-
-int set_info (void *, struct radio_info *);
- Set values from the radio_info struct.
- Returns 0 on success, otherwise an error code.
-
-int search (void *, int);
- Returns 0 on success, otherwise an error code.
+struct radio_hw_if {
+ int (*open)(void *, int, int, struct lwp *);
+ int (*close)(void *, int, int, struct lwp *);
+ int (*get_info)(void *, struct radio_info *);
+ int (*set_info)(void *, struct radio_info *);
+ int (*search)(void *, int);
+};
.Ed
+.Pp
+.Bl -tag -width XXXX
+.It Fn (*open) "sc" "flags" "fmt" "lwp"
+Called when the radio device is opened.
+Optional, if there is no need to call a driver's function when device file is
+opened, NULL should be passed in this field.
+Returns 0 on success, otherwise an error code.
+.It Fn (*close) "sc" "flags" "fmt" "lwp"
+Called when the radio device is closed.
+Optional, if there is no need to call a driver's function when device file is
+closed, NULL should be passed in thie field.
+Returns 0 on success, otherwise an error code.
+.It Fn (*get_info) "sc" "ri"
+Fills the radio_info struct.
+This function is used to obtain the current state of a hardware device.
+It is executed as a result of calling
+.Dv RIOCGINFO
+on a device file managed by the high level driver.
+Returns 0 on success, otherwise an error code.
+.It Fn (*set_info) "sc" "ri"
+Set values from the radio_info struct.
+This function is used to modify the current state of a hardware device
+(enable/disable various modes and parameters).
+It is executed as a result of calling
+.Dv RIOCSINFO
+on a device file managed by the high level driver.
+Returns 0 on success, otherwise an error code.
+.It Fn (*search) "sc" "ri"
+Initiates an automatic search for the radio station.
+It is executed as a result of calling
+.Dv RIOCSSRCH
+on a device file managed by the high level driver.
+Returns 0 on success, otherwise an error code.
+.El
.Sh SEE ALSO
.Xr radio 4
+.Sh AUTHORS
+The
+.Nm
+API was written by
+.An Vladimir Popov
+and
+.An Maxim Tsyplakov
+for
+.Ox
+and ported to
+.Nx
+by
+.An Lennart Augustsson .
