[src/trunk]: src/share/man Manual pages for wsbell.

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

details:   https://anonhg.NetBSD.org/src/rev/ae4d29c6e83f
branches:  trunk
changeset: 824650:ae4d29c6e83f
user:      nat <nat%NetBSD.org@localhost>
date:      Tue Jun 13 06:27:10 2017 +0000

description:
Manual pages for wsbell.

diffstat:

 share/man/man4/wsbell.4 |  107 +++++++++++++++++++++++++++++++++++++++++++++
 share/man/man9/wsbell.9 |  112 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 219 insertions(+), 0 deletions(-)

diffs (227 lines):

diff -r c4261ca1567d -r ae4d29c6e83f share/man/man4/wsbell.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/wsbell.4   Tue Jun 13 06:27:10 2017 +0000
@@ -0,0 +1,107 @@
+.\" $NetBSD: wsbell.4,v 1.1 2017/06/13 06:27:10 nat Exp $
+.\"
+.\" Copyright (c) 2017 Nathanial Sloss <nathanialsloss%yahoo.com.au@localhost>
+.\" 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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``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 FOUNDATION OR CONTRIBUTORS
+.\" 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 June 13, 2017
+.Dt WSBELL 4
+.Os
+.Sh NAME
+.Nm wsbell
+.Nd generic bell support in wscons
+.Sh SYNOPSIS
+.Cd "wsbell*    at spkr? console?"
+.Sh DESCRIPTION
+The
+.Nm
+driver utilizes the
+.Xr speaker 4
+driver to provide a system bell with or without a keyboard for the
+.Xr wscons 4
+framework.
+When a bell character is received on a
+.Xr wsdisplay 4
+screen,
+.Nm
+sounds the bell.
+.Pp
+The
+.Xr wsconsctl 8
+utility gives access to several configurable parameters that effect the sound
+of the system bell.
+.Ss Ioctls
+The following
+.Xr ioctl 2
+calls are provided by the
+.Nm
+driver.
+Their definitions are found in
+.Pa dev/wscons/wsconsio.h .
+.Bl -tag -width Dv
+.It Dv WSKBDIO_BELL
+Will sound the default bell.
+.It Dv WSKBDIO_GETBELL
+Will return a struct wskbd_bell_data with the current bell parameters.
+.It Dv WSKBDIO_SETBELL
+Takes a struct wskbd_bell_data and uses it to set the bell parameters.
+These are used by the WSKBDIO_BELL
+.Xr ioctl 2
+call.
+.It Dv WSKBDIO_COMPLEXBELL
+Will sound a bell using a supplied struct wskbd_bell_data for its parameters.
+.It Dv WSKBDIO_GETDEFAULTBELL
+Will return a struct wskbd_bell_data with the
+.Em default
+bell parameters.
+.It Dv WSKBDIO_SETDEFAULTBELL
+Takes a struct wskbd_bell_data and uses it to set the
+.Em default
+bell parameters.
+.El
+.Pp
+Ioctls use the following structure:
+.Bd -literal
+struct wskbd_bell_data {
+       u_int   which;                  /* values to get/set */
+#define        WSKBD_BELL_DOPITCH      0x1     /* get/set pitch */
+#define        WSKBD_BELL_DOPERIOD     0x2     /* get/set period */
+#define        WSKBD_BELL_DOVOLUME     0x4     /* get/set volume */
+#define        WSKBD_BELL_DOALL        0x7     /* all of the above */
+       u_int   pitch;                  /* pitch, in Hz */
+       u_int   period;                 /* period, in milliseconds */
+       u_int   volume;                 /* percentage of max volume */
+};
+.Ed
+.Sh FILES
+.Bl -item
+.It
+.Pa /usr/include/dev/wscons/wsconsio.h .
+.El
+.Sh SEE ALSO
+.Xr speaker 4 ,
+.Xr wscons 4 ,
+.Xr wskbd 4 ,
+.Xr wsmux 4 ,
+.Xr wsconsctl 8 ,
+.Xr wsbell 9
diff -r c4261ca1567d -r ae4d29c6e83f share/man/man9/wsbell.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/wsbell.9   Tue Jun 13 06:27:10 2017 +0000
@@ -0,0 +1,112 @@
+.\" $NetBSD: wsbell.9,v 1.1 2017/06/13 06:27:10 nat Exp $
+.\"
+.\" Copyright (c) 2017 Nathanial Sloss <nathanialsloss%yahoo.com.au@localhost>
+.\" 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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``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 FOUNDATION OR CONTRIBUTORS
+.\" 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 June 13, 2017
+.Dt WSBELL 9
+.Os
+.Sh NAME
+.Nm wsbell ,
+.Nm wsbelldevprint
+.Nd wscons system bell support
+.Sh SYNOPSIS
+.In dev/wscons/wsconsio.h
+.In dev/wscons/wsbellvar.h
+.Ft int
+.Fn wsbelldevprint "void *aux" "const char *pnp"
+.Sh DESCRIPTION
+The
+.Nm
+module is a component of the
+.Xr wscons 9
+framework to provide keyboard-independent bell support.
+All of the support is provided by the
+.Xr wsbell 4
+device driver, which must be a child of the hardware device driver.
+The only hardware device drivers that can provide a
+.Nm
+facility are
+.Xr speaker 4
+devices.
+.Sh DATA TYPES
+Speaker drivers providing support for wscons bell devices will make use
+of the following data types:
+.Bl -tag -width compact
+.It Fa struct wsbelldev_attach_args
+A structure used to attach the
+.Xr wsbell 4
+child device.
+It has the following members:
+.Bd -literal
+       void *accesscookie;
+.Ed
+.El
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.It Fn wsbelldevprint "aux" "pnp"
+The default wsbell printing routine used by
+.Fn config_found .
+(see
+.Xr autoconf 9 ) .
+.El
+.Sh AUTOCONFIGURATION
+Speaker drivers which want to use the wsbell module must be a
+parent to the
+.Xr wsbell 4
+device and provide an attachment interface.
+To attach the
+.Xr wsbell 4
+device, the speaker driver must allocate and populate a
+.Fa wsbelldev_attach_args
+structure with a pointer to the parents device structure as an access cookie
+and call
+.Fn config_found
+to perform the attach (see
+.Xr autoconf 9 ) .
+.Sh OPERATION
+When a bell event is recieved on a
+.Xr wsdisplay 4
+device the system bell is sounded.
+.Sh CODE REFERENCES
+The wscons subsystem is implemented within the directory
+.Pa sys/dev/wscons .
+The
+.Nm
+module itself is implement within the file
+.Pa sys/dev/wscons/wsbell.c .
+.Xr ioctl 2
+operations are listed in
+.Pa sys/dev/wscons/wsconsio.h .
+.Sh SEE ALSO
+.Xr ioctl 2 ,
+.Xr wscons 4 ,
+.Xr wsbell 4 ,
+.Xr wskbd 4 ,
+.Xr autoconf 9 ,
+.Xr driver 9 ,
+.Xr intro 9 ,
+.Xr wscons 9 ,
+.Xr wsdisplay 9 ,
+.Xr wskbd 9