.\" $NetBSD: wsbell.4,v 1.1 2017/06/13 06:27:10 nat Exp $
.\"
.\" Copyright (c) 2017 Nathanial Sloss <nathanialsloss@yahoo.com.au>
.\" 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