.\" $NetBSD: wsbell.9,v 1.4 2018/02/11 14:17:17 wiz 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 30, 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, providing 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 parent's 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 received 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 wsbell 4 ,
.Xr wscons 4 ,
.Xr wskbd 4 ,
.Xr autoconf 9 ,
.Xr driver 9 ,
.Xr intro 9 ,
.Xr wscons 9 ,
.Xr wsdisplay 9 ,
.Xr wskbd 9