1.\" $NetBSD: wskbd.9,v 1.7 2002/10/14 13:43:38 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. 70Most of the support 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. 83All keyboards must provide this structure and pass it to the 84.Xr wskbd 4 85child device. 86It has the following members: 87.Bd -literal 88 int (*enable)(void *, int); 89 void (*set_leds)(void *, int); 90 int (*ioctl)(void *v, u_long cmd, caddr_t data, 91 int flag, struct proc *p); 92.Ed 93.Pp 94The 95.Fa enable 96member defines the function to be called to enable keypress passing to 97wscons. 98The 99.Fa set_leds 100member defined the function to be called to set the LEDs on the 101keyboard. 102The 103.Fa ioctl 104member defines the function to be called to perform keyboard-specific 105ioctl calls. 106.Pp 107There is a 108.Fa void * 109cookie provided by the keyboard driver associated with these 110functions, which is passed to them when they are invoked. 111.It Fa struct wskbd_consops 112A structure used to specify the keyboard console operations. 113All keyboards which can operate as a console must provide this structure 114and pass it to the 115.Xr wskbd 4 116child device. 117If the keyboard cannot be a console, it is not 118necessary to specify this structure. 119It has the following members: 120.Bd -literal 121 void (*getc)(void *, u_int *, int *); 122 void (*pollc)(void *, int); 123 void (*bell)(void *, u_int, u_int, u_int); 124.Ed 125.Pp 126There is a 127.Fa void * 128cookie provided by the keyboard driver associated with these 129functions, which is passed to them when they are invoked. 130.It Fa struct wscons_keydesc 131A structure used to describe a keyboard mapping table to convert 132keyboard-specific keycodes to wscons keysyms. 133It has the 134following members: 135.Bd -literal 136 kbd_t name; /* name of this map */ 137 kbd_t base; /* map this one is based on */ 138 int map_size; /* size of map */ 139 const keysym_t *map; /* the map itself */ 140.Ed 141.It Fa struct wskbd_mapdata 142A structure used to describe the keyboard layout and operation to 143interpret the keyboard layout. 144it contains the following members: 145.Bd -literal 146 const struct wscons_keydesc *keydesc; 147 kbd_t layout; 148.Ed 149.It Fa struct wskbd_attach_args 150A structure used to attach the 151.Xr wskbd 4 152child device. 153It has the following members: 154.Bd -literal 155 int console; 156 const struct wskbd_mapdata *keymap; 157 const struct wskbd_accessops *accessops; 158 void *accesscookie; 159.Ed 160.El 161.Ss Keymaps 162Keymaps are a dense stream of 163.Fa keysym_t . 164A declaration has the following fields: 165.Pp 166.Ar pos 167.Op Ar cmd 168.Ar normal 169.Op Ar shift 170.Op Ar altgr 171.Op Ar shift-altgr 172.Pp 173The fields have the following meanings: 174.Pp 175.Bl -tag -offset indent -width SHIFT-ALTGR -compact 176.It Ar pos 177Always specified as 178.Ns KC( Ns Ar pos ) 179and starts the description of key 180.Ar pos . 181.It Ar cmd 182If the command modifier (KS_Cmd_XXX) is active, the optional command 183.Ar cmd 184is invoked. 185.It Ar normal 186The keysym if no modifiers are active. 187.It Ar shift 188The keysym if the shift modifier is active. 189.It Ar altgr 190The keysym if the alt-gr modifier is active. 191.It Ar shift-altgr 192The keysym if the shift-alt-gr modifier is active. 193.El 194.Pp 195If the keysym after 196.Ar pos 197is not KS_Cmd_XXX, then 198.Ar cmd 199is empty. 200The 201.Ar shift , 202.Ar altgr 203and 204.Ar shift-altgr 205fields are determined from previous fields if they are not specified. 206Therefore, there are four valid keysym declarations: 207.Pp 208.Ar pos 209.Op Ar cmd 210.Ar normal 211.Pp 212.Ar pos 213.Op Ar cmd 214.Ar normal Ar shift 215.Pp 216.Ar pos 217.Op Ar cmd 218.Ar normal Ar shift Ar altgr 219.Pp 220.Ar pos 221.Op Ar cmd 222.Ar normal Ar shift Ar altgr Ar shift-altgr 223.Sh FUNCTIONS 224.Bl -tag -width compact 225.It Fn wskbd_input "kbddev" "type" "value" 226Pass the keypress of value 227.Fa value 228and type 229.Fa type 230to wscons keyboard driver. 231Valid values of 232.Fa type 233are: 234.Bl -tag -width compact 235.It WSCONS_EVENT_KEY_UP 236Key released. 237.It WSCONS_EVENT_KEY_DOWN 238Key pressed. 239.El 240.It Fn wskbd_rawinput "kbddev" "buf" "len" 241Pass the raw keypress in the buffer 242.Fa buf 243to the wscons keyboard driver. 244The buffer is 245.Fa len 246bytes long. 247This function should only be called if the kernel option 248.Em WSDISPLAY_COMPAT_RAWKBD 249is enabled. 250.It Fn wskbd_cnattach "consops" "conscookie" "mapdata" 251Attach this keyboard as the console input by specifying the console 252operations 253.Fa consops 254and the keyboard mapping table information in 255.Fa mapdata . 256The functions specified in 257.Fa consops 258will be called with 259.Fa conscookie 260as the first argument. 261.It Fn wskbd_cndetach "" 262Detach this keyboard as the console input. 263.It Fn wskbddevprint "aux" "pnp" 264The default wskbd printing routine used by 265.Fn config_found . 266(see 267.Xr autoconf 9 ) . 268.El 269.Sh AUTOCONFIGURATION 270Keyboard drivers which want to utilise the wskbd module must be a 271parent to the 272.Xr wskbd 4 273device and provide an attachment interface. 274To attach the 275.Xr wskbd 4 276device, the keyboard driver must allocate and populate a 277.Fa wskbd_attach_args 278structure with the supported operations and callbacks and call 279.Fn config_found 280to perform the attach (see 281.Xr autoconf 9 ) . 282The 283.Fa keymap 284member points to the 285.Em wskbd_mapdata 286structure which describes the keycode mapping operations. 287The 288.Fa accessops 289member points to the 290.Em wskbd_accessops 291structure which describes the keyboard access operations. 292The 293.Fa console 294member is a boolean to indicate to wscons whether this keyboard will 295be used for console input. 296.Sh OPERATION 297If the keyboard belongs to the system console, it must register the 298.Fa wskbd_consops 299structure specifying the console operations via 300.Fn wskbd_cnattach 301at console attach time. 302.Pp 303When a keypress arrives from the keyboard, the keyboard driver must 304perform any necessary character decoding to wscons events and pass the 305events to wscons via 306.Fn wskbd_input . 307If the kernel is compiled with the option 308.Em WSDISPLAY_COMPAT_RAWKBD , 309then the keyboard driver must also pass the raw keyboard data to 310wscons via 311.Fn wskbd_rawinput . 312.Pp 313The wscons framework calls back into the hardware driver by invoking 314the functions that are specified in the 315.Em accessops 316structure. 317The 318.Fn enable 319and 320.Fn set_leds 321functions are relatively simple and self-explanatory. 322The 323.Fn ioctl 324function is called by the wscons interface to perform 325keyboard-specific ioctl operations (see 326.Xr ioctl 2 ) . 327The argument 328.Fa cmd 329to the 330.Fn ioctl 331function specifies the specific command to perform using the data 332.Fa data . 333Valid commands are listed in 334.Pa sys/dev/wscons/wsconsio.h . 335.Sh CODE REFERENCES 336This section describes places within the 337.Nx 338source tree where actual code implementing or utilising the 339machine-independent wscons subsystem can be found. 340All pathnames are relative to 341.Pa /usr/src . 342.Pp 343The wscons subsystem is implemented within the directory 344.Pa sys/dev/wscons . 345The 346.Nm 347module itself is implement within the files 348.Pa sys/dev/wscons/wskbd.c 349and 350.Pa sys/dev/wscons/wskbdutil.c . 351.Xr ioctl 2 352operations are listed in 353.Pa sys/dev/wscons/wsconsio.h . 354.Sh SEE ALSO 355.Xr ioctl 2 , 356.Xr autoconf 9 , 357.Xr driver 9 , 358.Xr intro 9 , 359.Xr wsdisplay 9 , 360.Xr wsmouse 9 361