1.\" $NetBSD: wskbd.9,v 1.3 2001/11/28 16:49:03 wiz Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd October 7, 2001 38.Dt WSKBD 9 39.Os 40.Sh NAME 41.Nm wskbd , 42.Nm wskbd_input , 43.Nm wskbd_rawinput , 44.Nm wskbd_cnattach , 45.Nm wskbd_cndetach , 46.Nm wskbddevprint 47.Nd wscons keyboard support 48.Sh SYNOPSIS 49.Fd #include <dev/wscons/wsconsio.h> 50.Fd #include <dev/wscons/wskbdvar.h> 51.Fd #include <dev/wscons/wsksymdef.h> 52.Fd #include <dev/wscons/wsksymvar.h> 53.Ft void 54.Fn wskbd_input "struct device *kbddev" "u_int type" "int value" 55.Ft void 56.Fn wskbd_rawinput "struct device *kbddev" "u_char *buf" "int len" 57.Ft void 58.Fn wskbd_cnattach "const struct wskbd_consops *consops" "void *conscookie" \ 59"const struct wskbd_mapdata *mapdata" 60.Ft void 61.Fn wskbd_cndetach "" 62.Ft int 63.Fn wskbddevprint "void *aux" "const char *pnp" 64.Sh DESCRIPTION 65The 66.Nm 67module is a component of the 68.Xr wscons 9 69framework to provide machine-indpendent keyboard support. Most of the 70support is provided by the 71.Xr wskbd 4 72device driver, which must be a child of the hardware device driver. 73.Sh DATA TYPES 74Keyboard drivers providing support for wscons keyboards will make use 75of the following data types: 76.Bl -tag -width compact 77.It Fa kbd_t 78An opaque type describing keyboard properties. 79.It Fa keysym_t 80The wscons keyboard-independent symbolic representation of the keypress. 81.It Fa struct wskbd_accessops 82A structure used to specify the keyboard access functions. All 83keyboards must provide this structure and pass it to the 84.Xr wskbd 4 85child device. It has the following members: 86.Bd -literal 87 int (*enable)(void *, int); 88 void (*set_leds)(void *, int); 89 int (*ioctl)(void *v, u_long cmd, caddr_t data, 90 int flag, struct proc *p); 91.Ed 92.Pp 93The 94.Fa enable 95member defines the function to be called to enable keypress passing to 96wscons. The 97.Fa set_leds 98member defined the function to be called to set the LEDs on the 99keyboard. The 100.Fa ioctl 101member defines the function to be called to perform keyboard-specific 102ioctl calls. 103.Pp 104There is a 105.Fa void * 106cookie provided by the keyboard driver associated with these 107functions, which is passed to them when they are invoked. 108.It Fa struct wskbd_consops 109A structure used to specify the keyboard console operations. All 110keyboards which can operate as a console must provide this structure 111and pass it to the 112.Xr wskbd 4 113child device. If the keyboard cannot be a console, it is not 114necessary to specify this structure. It has the following members: 115.Bd -literal 116 void (*getc)(void *, u_int *, int *); 117 void (*pollc)(void *, int); 118 void (*bell)(void *, u_int, u_int, u_int); 119.Ed 120.Pp 121There is a 122.Fa void * 123cookie provided by the keyboard driver associated with these 124functions, which is passed to them when they are invoked. 125.It Fa struct wscons_keydesc 126A structure used to describe a keyboard mapping table to convert 127keyboard-specific keycodes to wscons keysyms. It has the 128following members: 129.Bd -literal 130 kbd_t name; /* name of this map */ 131 kbd_t base; /* map this one is based on */ 132 int map_size; /* size of map */ 133 const keysym_t *map; /* the map itself */ 134.Ed 135.It Fa struct wskbd_mapdata 136A structure used to describe the keyboard layout and operation to 137interpret the keyboard layout. it contains the following members: 138.Bd -literal 139 const struct wscons_keydesc *keydesc; 140 kbd_t layout; 141.Ed 142.It Fa struct wskbd_attach_args 143A structure used to attach the 144.Xr wskbd 4 145child device. It has the following members: 146.Bd -literal 147 int console; 148 const struct wskbd_mapdata *keymap; 149 const struct wskbd_accessops *accessops; 150 void *accesscookie; 151.Ed 152.El 153.Sh FUNCTIONS 154.Bl -tag -width compact 155.It Fn wskbd_input "kbddev" "type" "value" 156Pass the keypress of value 157.Fa value 158and type 159.Fa type 160to wscons keyboard driver. Valid values of 161.Fa type 162are: 163.Bl -tag -width compact 164.It WSCONS_EVENT_KEY_UP 165Key released. 166.It WSCONS_EVENT_KEY_DOWN 167Key pressed. 168.El 169.It Fn wskbd_rawinput "kbddev" "buf" "len" 170Pass the raw keypress in the buffer 171.Fa buf 172to the wscons keyboard driver. The buffer is 173.Fa len 174bytes long. This function should only be called if the kernel option 175.Em WSDISPLAY_COMPAT_RAWKBD 176is enabled. 177.It Fn wskbd_cnattach "consops" "conscookie" "mapdata" 178Attach this keyboard as the console input by specifying the console 179operations 180.Fa consops 181and the keyboard mapping table information in 182.Fa mapdata . 183The functions specified in 184.Fa consops 185will be called with 186.Fa conscookie 187as the first argument. 188.It Fn wskbd_cndetach "" 189Detach this keyboard as the console input. 190.It Fn wskbddevprint "aux" "pnp" 191The default wskbd printing routine used by 192.Fn config_found . 193(see 194.Xr autoconf 9 ) . 195.El 196.Sh AUTOCONFIGURATION 197Keyboard drivers which want to utilise the wskbd module must be a 198parent to the 199.Xr wskbd 4 200device and provide an attachment interface. To attach the 201.Xr wskbd 4 202device, the keyboard driver must allocate and populate a 203.Fa wskbd_attach_args 204structure with the supported operations and callbacks and call 205.Fn config_found 206to perform the attach (see 207.Xr autoconf 9 ) . 208.\" The 209.\" .Fa keymap 210.\" member points to the 211.\" .Em wskbd_mapdata 212.\" structure which describes the keycode mapping operations. The 213.\" .Fa accessops 214.\" member points to the 215.\" .Em wskbd_accessops 216.\" structure which describes the keyboard access operations. 217The 218.Fa console 219member is a boolean to indicate to wscons whether this keyboard will 220be used for console input. 221.Sh OPERATION 222If the keyboard belongs to the system console, it must register the 223.Fa wskbd_consops 224structure specifying the console operations via 225.Fn wskbd_cnattach 226at console attach time. 227.Pp 228When a keypress arrives from the keyboard, the keyboard driver must 229perform any necessary character decoding to wscons events and pass the 230events to wscons via 231.Fn wskbd_input . 232If the kernel is compiled with the option 233.Em WSDISPLAY_COMPAT_RAWKBD , 234then the keyboard driver must also pass the raw keyboard data to 235wscons via 236.Fn wskbd_rawinput . 237.Pp 238The wscons framework calls back into the hardware driver by invoking 239the functions that are specified in the 240.Em accessops 241structure. The 242.Fn enable 243and 244.Fn set_leds 245functions are relatively simple and self-explanatory. The 246.Fn ioctl 247function is called by the wscons interface to perform 248keyboard-specific ioctl operations (see 249.Xr ioctl 2 ) . 250The argument 251.Fa cmd 252to the 253.Fn ioctl 254function specifies the specific command to perform using the data 255.Fa data . 256Valid commands are listed in 257.Pa sys/dev/wscons/wsconsio.h . 258.Sh CODE REFERENCES 259This section describes places within the 260.Nx 261source tree where actual code implementing or utilising the 262machine-independent wscons subsystem can be found. All pathnames are 263relative to 264.Pa /usr/src . 265.Pp 266The wscons subsystem is implemented within the directory 267.Pa sys/dev/wscons . 268The 269.Nm 270module itself is implement within the files 271.Pa sys/dev/wscons/wskbd.c 272and 273.Pa sys/dev/wscons/wskbdutil.c . 274.Xr ioctl 2 275operations are listed in 276.Pa sys/dev/wscons/wsconsio.h . 277.Sh SEE ALSO 278.Xr ioctl 2 , 279.Xr autoconf 9 , 280.Xr driver 9 , 281.Xr intro 9 , 282.Xr wsdisplay 9 , 283.Xr wsmouse 9 284