1.\" $NetBSD: wskbd.9,v 1.6 2002/03/19 10:34:50 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 \*[Lt]dev/wscons/wsconsio.h\*[Gt] 50.Fd #include \*[Lt]dev/wscons/wskbdvar.h\*[Gt] 51.Fd #include \*[Lt]dev/wscons/wsksymdef.h\*[Gt] 52.Fd #include \*[Lt]dev/wscons/wsksymvar.h\*[Gt] 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.Ss Keymaps 154Keymaps are a dense stream of 155.Fa keysym_t . 156A declaration has the following fields: 157.Pp 158.Ar pos 159.Op Ar cmd 160.Ar normal 161.Op Ar shift 162.Op Ar altgr 163.Op Ar shift-altgr 164.Pp 165The fields have the following meanings: 166.Pp 167.Bl -tag -offset indent -width SHIFT-ALTGR -compact 168.It Ar pos 169Always specified as 170.Ns KC( Ns Ar pos ) 171and starts the description of key 172.Ar pos . 173.It Ar cmd 174If the command modifier (KS_Cmd_XXX) is active, the optional command 175.Ar cmd 176is invoked. 177.It Ar normal 178The keysym if no modifiers are active. 179.It Ar shift 180The keysym if the shift modifier is active. 181.It Ar altgr 182The keysym if the alt-gr modifier is active. 183.It Ar shift-altgr 184The keysym if the shift-alt-gr modifier is active. 185.El 186.Pp 187If the keysym after 188.Ar pos 189is not KS_Cmd_XXX, then 190.Ar cmd 191is empty. 192The 193.Ar shift , 194.Ar altgr 195and 196.Ar shift-altgr 197fields are determined from previous fields if they are not specified. 198Therefore, there are four valid keysym declarations: 199.Pp 200.Ar pos 201.Op Ar cmd 202.Ar normal 203.Pp 204.Ar pos 205.Op Ar cmd 206.Ar normal Ar shift 207.Pp 208.Ar pos 209.Op Ar cmd 210.Ar normal Ar shift Ar altgr 211.Pp 212.Ar pos 213.Op Ar cmd 214.Ar normal Ar shift Ar altgr Ar shift-altgr 215.Sh FUNCTIONS 216.Bl -tag -width compact 217.It Fn wskbd_input "kbddev" "type" "value" 218Pass the keypress of value 219.Fa value 220and type 221.Fa type 222to wscons keyboard driver. Valid values of 223.Fa type 224are: 225.Bl -tag -width compact 226.It WSCONS_EVENT_KEY_UP 227Key released. 228.It WSCONS_EVENT_KEY_DOWN 229Key pressed. 230.El 231.It Fn wskbd_rawinput "kbddev" "buf" "len" 232Pass the raw keypress in the buffer 233.Fa buf 234to the wscons keyboard driver. The buffer is 235.Fa len 236bytes long. This function should only be called if the kernel option 237.Em WSDISPLAY_COMPAT_RAWKBD 238is enabled. 239.It Fn wskbd_cnattach "consops" "conscookie" "mapdata" 240Attach this keyboard as the console input by specifying the console 241operations 242.Fa consops 243and the keyboard mapping table information in 244.Fa mapdata . 245The functions specified in 246.Fa consops 247will be called with 248.Fa conscookie 249as the first argument. 250.It Fn wskbd_cndetach "" 251Detach this keyboard as the console input. 252.It Fn wskbddevprint "aux" "pnp" 253The default wskbd printing routine used by 254.Fn config_found . 255(see 256.Xr autoconf 9 ) . 257.El 258.Sh AUTOCONFIGURATION 259Keyboard drivers which want to utilise the wskbd module must be a 260parent to the 261.Xr wskbd 4 262device and provide an attachment interface. To attach the 263.Xr wskbd 4 264device, the keyboard driver must allocate and populate a 265.Fa wskbd_attach_args 266structure with the supported operations and callbacks and call 267.Fn config_found 268to perform the attach (see 269.Xr autoconf 9 ) . 270The 271.Fa keymap 272member points to the 273.Em wskbd_mapdata 274structure which describes the keycode mapping operations. The 275.Fa accessops 276member points to the 277.Em wskbd_accessops 278structure which describes the keyboard access operations. 279The 280.Fa console 281member is a boolean to indicate to wscons whether this keyboard will 282be used for console input. 283.Sh OPERATION 284If the keyboard belongs to the system console, it must register the 285.Fa wskbd_consops 286structure specifying the console operations via 287.Fn wskbd_cnattach 288at console attach time. 289.Pp 290When a keypress arrives from the keyboard, the keyboard driver must 291perform any necessary character decoding to wscons events and pass the 292events to wscons via 293.Fn wskbd_input . 294If the kernel is compiled with the option 295.Em WSDISPLAY_COMPAT_RAWKBD , 296then the keyboard driver must also pass the raw keyboard data to 297wscons via 298.Fn wskbd_rawinput . 299.Pp 300The wscons framework calls back into the hardware driver by invoking 301the functions that are specified in the 302.Em accessops 303structure. The 304.Fn enable 305and 306.Fn set_leds 307functions are relatively simple and self-explanatory. The 308.Fn ioctl 309function is called by the wscons interface to perform 310keyboard-specific ioctl operations (see 311.Xr ioctl 2 ) . 312The argument 313.Fa cmd 314to the 315.Fn ioctl 316function specifies the specific command to perform using the data 317.Fa data . 318Valid commands are listed in 319.Pa sys/dev/wscons/wsconsio.h . 320.Sh CODE REFERENCES 321This section describes places within the 322.Nx 323source tree where actual code implementing or utilising the 324machine-independent wscons subsystem can be found. All pathnames are 325relative to 326.Pa /usr/src . 327.Pp 328The wscons subsystem is implemented within the directory 329.Pa sys/dev/wscons . 330The 331.Nm 332module itself is implement within the files 333.Pa sys/dev/wscons/wskbd.c 334and 335.Pa sys/dev/wscons/wskbdutil.c . 336.Xr ioctl 2 337operations are listed in 338.Pa sys/dev/wscons/wsconsio.h . 339.Sh SEE ALSO 340.Xr ioctl 2 , 341.Xr autoconf 9 , 342.Xr driver 9 , 343.Xr intro 9 , 344.Xr wsdisplay 9 , 345.Xr wsmouse 9 346