[src/trunk]: src/share/man/man9 Try to bring this man page up to NetBSD stand...

[rkujawa <rkujawa%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/f731d9dd0402
branches:  trunk
changeset: 833717:f731d9dd0402
user:      rkujawa <rkujawa%NetBSD.org@localhost>
date:      Mon Jul 09 10:36:30 2018 +0000

description:
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.

diffstat:

 share/man/man9/radio.9 |  141 ++++++++++++++++++++++++++++--------------------
 1 files changed, 83 insertions(+), 58 deletions(-)

diffs (166 lines):

diff -r 33d66603090f -r f731d9dd0402 share/man/man9/radio.9
--- a/share/man/man9/radio.9    Mon Jul 09 10:24:44 2018 +0000
+++ b/share/man/man9/radio.9    Mon Jul 09 10:36:30 2018 +0000
@@ -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 <tm%oganer.net@localhost>
@@ -24,19 +24,47 @@
 .\" (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.
+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
+.Fn radio_attach_mi .
+.Pp
+The
+.Fa radio_hw_if
+struct is contains pointers to functions provided by the low level driver.
+The
+.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
+.Fa radio_hw_if
+when the high level driver calls them.
+.Fa dev
+is the device struct for the hardware device.
+.Pp
+The fields of
+.Fa radio_hw_if
+are described in some more detail below.
 .Bd -literal
 struct radio_hw_if {
        int     (*open)(void *, int, int, struct lwp *);
@@ -47,54 +75,51 @@
 };
 .Ed
 .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
-.Pp
-The
-.Va radio_hw_if
-struct is as shown above.
-The
-.Va hdlp
-argument is a handle to some low level data structure.
-It is sent as the first argument to all the functions in
-.Va radio_hw_if
-when the high level driver calls them.
-.Va dev
-is the device struct for the hardware device.
-.Pp
-The fields of
-.Va 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.
-.Ed
+.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 .