472351e13d
.In header.h instead of .Fd #include \*[Lt]header.h\*[Gt] Much easier to read and write, and supported by groff for ages. Okayed by ross.
361 lines
9.8 KiB
Groff
361 lines
9.8 KiB
Groff
.\" $NetBSD: wskbd.9,v 1.10 2003/04/16 13:35:36 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Gregory McGarry.
|
|
.\"
|
|
.\" 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 October 7, 2001
|
|
.Dt WSKBD 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm wskbd ,
|
|
.Nm wskbd_input ,
|
|
.Nm wskbd_rawinput ,
|
|
.Nm wskbd_cnattach ,
|
|
.Nm wskbd_cndetach ,
|
|
.Nm wskbddevprint
|
|
.Nd wscons keyboard support
|
|
.Sh SYNOPSIS
|
|
.In dev/wscons/wsconsio.h
|
|
.In dev/wscons/wskbdvar.h
|
|
.In dev/wscons/wsksymdef.h
|
|
.In dev/wscons/wsksymvar.h
|
|
.Ft void
|
|
.Fn wskbd_input "struct device *kbddev" "u_int type" "int value"
|
|
.Ft void
|
|
.Fn wskbd_rawinput "struct device *kbddev" "u_char *buf" "int len"
|
|
.Ft void
|
|
.Fn wskbd_cnattach "const struct wskbd_consops *consops" "void *conscookie" \
|
|
"const struct wskbd_mapdata *mapdata"
|
|
.Ft void
|
|
.Fn wskbd_cndetach ""
|
|
.Ft int
|
|
.Fn wskbddevprint "void *aux" "const char *pnp"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
module is a component of the
|
|
.Xr wscons 9
|
|
framework to provide machine-independent keyboard support.
|
|
Most of the support is provided by the
|
|
.Xr wskbd 4
|
|
device driver, which must be a child of the hardware device driver.
|
|
.Sh DATA TYPES
|
|
Keyboard drivers providing support for wscons keyboards will make use
|
|
of the following data types:
|
|
.Bl -tag -width compact
|
|
.It Fa kbd_t
|
|
An opaque type describing keyboard properties.
|
|
.It Fa keysym_t
|
|
The wscons keyboard-independent symbolic representation of the keypress.
|
|
.It Fa struct wskbd_accessops
|
|
A structure used to specify the keyboard access functions.
|
|
All keyboards must provide this structure and pass it to the
|
|
.Xr wskbd 4
|
|
child device.
|
|
It has the following members:
|
|
.Bd -literal
|
|
int (*enable)(void *, int);
|
|
void (*set_leds)(void *, int);
|
|
int (*ioctl)(void *v, u_long cmd, caddr_t data,
|
|
int flag, struct proc *p);
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fa enable
|
|
member defines the function to be called to enable keypress passing to
|
|
wscons.
|
|
The
|
|
.Fa set_leds
|
|
member defined the function to be called to set the LEDs on the
|
|
keyboard.
|
|
The
|
|
.Fa ioctl
|
|
member defines the function to be called to perform keyboard-specific
|
|
ioctl calls.
|
|
.Pp
|
|
There is a
|
|
.Fa void *
|
|
cookie provided by the keyboard driver associated with these
|
|
functions, which is passed to them when they are invoked.
|
|
.It Fa struct wskbd_consops
|
|
A structure used to specify the keyboard console operations.
|
|
All keyboards which can operate as a console must provide this structure
|
|
and pass it to the
|
|
.Xr wskbd 4
|
|
child device.
|
|
If the keyboard cannot be a console, it is not
|
|
necessary to specify this structure.
|
|
It has the following members:
|
|
.Bd -literal
|
|
void (*getc)(void *, u_int *, int *);
|
|
void (*pollc)(void *, int);
|
|
void (*bell)(void *, u_int, u_int, u_int);
|
|
.Ed
|
|
.Pp
|
|
There is a
|
|
.Fa void *
|
|
cookie provided by the keyboard driver associated with these
|
|
functions, which is passed to them when they are invoked.
|
|
.It Fa struct wscons_keydesc
|
|
A structure used to describe a keyboard mapping table to convert
|
|
keyboard-specific keycodes to wscons keysyms.
|
|
It has the
|
|
following members:
|
|
.Bd -literal
|
|
kbd_t name; /* name of this map */
|
|
kbd_t base; /* map this one is based on */
|
|
int map_size; /* size of map */
|
|
const keysym_t *map; /* the map itself */
|
|
.Ed
|
|
.It Fa struct wskbd_mapdata
|
|
A structure used to describe the keyboard layout and operation to
|
|
interpret the keyboard layout.
|
|
it contains the following members:
|
|
.Bd -literal
|
|
const struct wscons_keydesc *keydesc;
|
|
kbd_t layout;
|
|
.Ed
|
|
.It Fa struct wskbd_attach_args
|
|
A structure used to attach the
|
|
.Xr wskbd 4
|
|
child device.
|
|
It has the following members:
|
|
.Bd -literal
|
|
int console;
|
|
const struct wskbd_mapdata *keymap;
|
|
const struct wskbd_accessops *accessops;
|
|
void *accesscookie;
|
|
.Ed
|
|
.El
|
|
.Ss Keymaps
|
|
Keymaps are a dense stream of
|
|
.Fa keysym_t .
|
|
A declaration has the following fields:
|
|
.Pp
|
|
.Ar pos
|
|
.Op Ar cmd
|
|
.Ar normal
|
|
.Op Ar shift
|
|
.Op Ar altgr
|
|
.Op Ar shift-altgr
|
|
.Pp
|
|
The fields have the following meanings:
|
|
.Pp
|
|
.Bl -tag -offset indent -width SHIFT-ALTGR -compact
|
|
.It Ar pos
|
|
Always specified as
|
|
.Ns KC( Ns Ar pos )
|
|
and starts the description of key
|
|
.Ar pos .
|
|
.It Ar cmd
|
|
If the command modifier (KS_Cmd_XXX) is active, the optional command
|
|
.Ar cmd
|
|
is invoked.
|
|
.It Ar normal
|
|
The keysym if no modifiers are active.
|
|
.It Ar shift
|
|
The keysym if the shift modifier is active.
|
|
.It Ar altgr
|
|
The keysym if the alt-gr modifier is active.
|
|
.It Ar shift-altgr
|
|
The keysym if the shift-alt-gr modifier is active.
|
|
.El
|
|
.Pp
|
|
If the keysym after
|
|
.Ar pos
|
|
is not KS_Cmd_XXX, then
|
|
.Ar cmd
|
|
is empty.
|
|
The
|
|
.Ar shift ,
|
|
.Ar altgr
|
|
and
|
|
.Ar shift-altgr
|
|
fields are determined from previous fields if they are not specified.
|
|
Therefore, there are four valid keysym declarations:
|
|
.Pp
|
|
.Ar pos
|
|
.Op Ar cmd
|
|
.Ar normal
|
|
.Pp
|
|
.Ar pos
|
|
.Op Ar cmd
|
|
.Ar normal Ar shift
|
|
.Pp
|
|
.Ar pos
|
|
.Op Ar cmd
|
|
.Ar normal Ar shift Ar altgr
|
|
.Pp
|
|
.Ar pos
|
|
.Op Ar cmd
|
|
.Ar normal Ar shift Ar altgr Ar shift-altgr
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width compact
|
|
.It Fn wskbd_input "kbddev" "type" "value"
|
|
Pass the keypress of value
|
|
.Fa value
|
|
and type
|
|
.Fa type
|
|
to wscons keyboard driver.
|
|
Valid values of
|
|
.Fa type
|
|
are:
|
|
.Bl -tag -width compact
|
|
.It WSCONS_EVENT_KEY_UP
|
|
Key released.
|
|
.It WSCONS_EVENT_KEY_DOWN
|
|
Key pressed.
|
|
.El
|
|
.It Fn wskbd_rawinput "kbddev" "buf" "len"
|
|
Pass the raw keypress in the buffer
|
|
.Fa buf
|
|
to the wscons keyboard driver.
|
|
The buffer is
|
|
.Fa len
|
|
bytes long.
|
|
This function should only be called if the kernel option
|
|
.Em WSDISPLAY_COMPAT_RAWKBD
|
|
is enabled.
|
|
.It Fn wskbd_cnattach "consops" "conscookie" "mapdata"
|
|
Attach this keyboard as the console input by specifying the console
|
|
operations
|
|
.Fa consops
|
|
and the keyboard mapping table information in
|
|
.Fa mapdata .
|
|
The functions specified in
|
|
.Fa consops
|
|
will be called with
|
|
.Fa conscookie
|
|
as the first argument.
|
|
.It Fn wskbd_cndetach ""
|
|
Detach this keyboard as the console input.
|
|
.It Fn wskbddevprint "aux" "pnp"
|
|
The default wskbd printing routine used by
|
|
.Fn config_found .
|
|
(see
|
|
.Xr autoconf 9 ) .
|
|
.El
|
|
.Sh AUTOCONFIGURATION
|
|
Keyboard drivers which want to use the wskbd module must be a
|
|
parent to the
|
|
.Xr wskbd 4
|
|
device and provide an attachment interface.
|
|
To attach the
|
|
.Xr wskbd 4
|
|
device, the keyboard driver must allocate and populate a
|
|
.Fa wskbd_attach_args
|
|
structure with the supported operations and callbacks and call
|
|
.Fn config_found
|
|
to perform the attach (see
|
|
.Xr autoconf 9 ) .
|
|
The
|
|
.Fa keymap
|
|
member points to the
|
|
.Em wskbd_mapdata
|
|
structure which describes the keycode mapping operations.
|
|
The
|
|
.Fa accessops
|
|
member points to the
|
|
.Em wskbd_accessops
|
|
structure which describes the keyboard access operations.
|
|
The
|
|
.Fa console
|
|
member is a boolean to indicate to wscons whether this keyboard will
|
|
be used for console input.
|
|
.Sh OPERATION
|
|
If the keyboard belongs to the system console, it must register the
|
|
.Fa wskbd_consops
|
|
structure specifying the console operations via
|
|
.Fn wskbd_cnattach
|
|
at console attach time.
|
|
.Pp
|
|
When a keypress arrives from the keyboard, the keyboard driver must
|
|
perform any necessary character decoding to wscons events and pass the
|
|
events to wscons via
|
|
.Fn wskbd_input .
|
|
If the kernel is compiled with the option
|
|
.Em WSDISPLAY_COMPAT_RAWKBD ,
|
|
then the keyboard driver must also pass the raw keyboard data to
|
|
wscons via
|
|
.Fn wskbd_rawinput .
|
|
.Pp
|
|
The wscons framework calls back into the hardware driver by invoking
|
|
the functions that are specified in the
|
|
.Em accessops
|
|
structure.
|
|
The
|
|
.Fn enable
|
|
and
|
|
.Fn set_leds
|
|
functions are relatively simple and self-explanatory.
|
|
The
|
|
.Fn ioctl
|
|
function is called by the wscons interface to perform
|
|
keyboard-specific ioctl operations (see
|
|
.Xr ioctl 2 ) .
|
|
The argument
|
|
.Fa cmd
|
|
to the
|
|
.Fn ioctl
|
|
function specifies the specific command to perform using the data
|
|
.Fa data .
|
|
Valid commands are listed in
|
|
.Pa sys/dev/wscons/wsconsio.h .
|
|
.Sh CODE REFERENCES
|
|
This section describes places within the
|
|
.Nx
|
|
source tree where actual code implementing or using the
|
|
machine-independent wscons subsystem can be found.
|
|
All pathnames are relative to
|
|
.Pa /usr/src .
|
|
.Pp
|
|
The wscons subsystem is implemented within the directory
|
|
.Pa sys/dev/wscons .
|
|
The
|
|
.Nm
|
|
module itself is implement within the files
|
|
.Pa sys/dev/wscons/wskbd.c
|
|
and
|
|
.Pa sys/dev/wscons/wskbdutil.c .
|
|
.Xr ioctl 2
|
|
operations are listed in
|
|
.Pa sys/dev/wscons/wsconsio.h .
|
|
.Sh SEE ALSO
|
|
.Xr ioctl 2 ,
|
|
.Xr autoconf 9 ,
|
|
.Xr driver 9 ,
|
|
.Xr intro 9 ,
|
|
.Xr wsdisplay 9 ,
|
|
.Xr wsmouse 9
|