1.\" $NetBSD: wskbd.9,v 1.15 2010/12/02 12:54:13 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd December 20, 2005 31.Dt WSKBD 9 32.Os 33.Sh NAME 34.Nm wskbd , 35.Nm wskbd_input , 36.Nm wskbd_rawinput , 37.Nm wskbd_cnattach , 38.Nm wskbd_cndetach , 39.Nm wskbddevprint 40.Nd wscons keyboard support 41.Sh SYNOPSIS 42.In dev/wscons/wsconsio.h 43.In dev/wscons/wskbdvar.h 44.In dev/wscons/wsksymdef.h 45.In dev/wscons/wsksymvar.h 46.Ft void 47.Fn wskbd_input "struct device *kbddev" "u_int type" "int value" 48.Ft void 49.Fn wskbd_rawinput "struct device *kbddev" "u_char *buf" "int len" 50.Ft void 51.Fn wskbd_cnattach "const struct wskbd_consops *consops" "void *conscookie" \ 52"const struct wskbd_mapdata *mapdata" 53.Ft void 54.Fn wskbd_cndetach "" 55.Ft int 56.Fn wskbddevprint "void *aux" "const char *pnp" 57.Sh DESCRIPTION 58The 59.Nm 60module is a component of the 61.Xr wscons 9 62framework to provide machine-independent keyboard support. 63Most of the support is provided by the 64.Xr wskbd 4 65device driver, which must be a child of the hardware device driver. 66.Sh DATA TYPES 67Keyboard drivers providing support for wscons keyboards will make use 68of the following data types: 69.Bl -tag -width compact 70.It Fa kbd_t 71An opaque type describing keyboard properties. 72.It Fa keysym_t 73The wscons keyboard-independent symbolic representation of the keypress. 74.It Fa struct wskbd_accessops 75A structure used to specify the keyboard access functions. 76All keyboards must provide this structure and pass it to the 77.Xr wskbd 4 78child device. 79It has the following members: 80.Bd -literal 81 int (*enable)(void *, int); 82 void (*set_leds)(void *, int); 83 int (*ioctl)(void *v, u_long cmd, void *data, 84 int flag, struct lwp *l); 85.Ed 86.Pp 87The 88.Fa enable 89member defines the function to be called to enable keypress passing to 90wscons. 91The 92.Fa set_leds 93member defined the function to be called to set the LEDs on the 94keyboard. 95The 96.Fa ioctl 97member defines the function to be called to perform keyboard-specific 98ioctl calls. 99.Pp 100There is a 101.Fa void * 102cookie provided by the keyboard driver associated with these 103functions, which is passed to them when they are invoked. 104.It Fa struct wskbd_consops 105A structure used to specify the keyboard console operations. 106All keyboards which can operate as a console must provide this structure 107and pass it to the 108.Xr wskbd 4 109child device. 110If the keyboard cannot be a console, it is not 111necessary to specify this structure. 112It has the following members: 113.Bd -literal 114 void (*getc)(void *, u_int *, int *); 115 void (*pollc)(void *, int); 116 void (*bell)(void *, u_int, u_int, u_int); 117.Ed 118.Pp 119There is a 120.Fa void * 121cookie provided by the keyboard driver associated with these 122functions, which is passed to them when they are invoked. 123.It Fa struct wscons_keydesc 124A structure used to describe a keyboard mapping table to convert 125keyboard-specific keycodes to wscons keysyms. 126It has the 127following members: 128.Bd -literal 129 kbd_t name; /* name of this map */ 130 kbd_t base; /* map this one is based on */ 131 int map_size; /* size of map */ 132 const keysym_t *map; /* the map itself */ 133.Ed 134.It Fa struct wskbd_mapdata 135A structure used to describe the keyboard layout and operation to 136interpret the keyboard layout. 137it contains the following members: 138.Bd -literal 139 const struct wscons_keydesc *keydesc; 140 kbd_t layout; 141.Ed 142.It Fa struct wskbddev_attach_args 143A structure used to attach the 144.Xr wskbd 4 145child device. 146It has the following members: 147.Bd -literal 148 int console; 149 const struct wskbd_mapdata *keymap; 150 const struct wskbd_accessops *accessops; 151 void *accesscookie; 152.Ed 153.El 154.Ss Keymaps 155Keymaps are a dense stream of 156.Fa keysym_t . 157A declaration has the following fields: 158.Pp 159.Ar pos 160.Op Ar cmd 161.Ar normal 162.Op Ar shift 163.Op Ar altgr 164.Op Ar shift-altgr 165.Pp 166The fields have the following meanings: 167.Pp 168.Bl -tag -offset indent -width SHIFT-ALTGR -compact 169.It Ar pos 170Always specified as 171.Ns KC( Ns Ar pos ) 172and starts the description of key 173.Ar pos . 174.It Ar cmd 175If the command modifier (KS_Cmd_XXX) is active, the optional command 176.Ar cmd 177is invoked. 178.It Ar normal 179The keysym if no modifiers are active. 180.It Ar shift 181The keysym if the shift modifier is active. 182.It Ar altgr 183The keysym if the alt-gr modifier is active. 184.It Ar shift-altgr 185The keysym if the shift-alt-gr modifier is active. 186.El 187.Pp 188If the keysym after 189.Ar pos 190is not KS_Cmd_XXX, then 191.Ar cmd 192is empty. 193The 194.Ar shift , 195.Ar altgr 196and 197.Ar shift-altgr 198fields are determined from previous fields if they are not specified. 199Therefore, there are four valid keysym declarations: 200.Pp 201.Ar pos 202.Op Ar cmd 203.Ar normal 204.Pp 205.Ar pos 206.Op Ar cmd 207.Ar normal Ar shift 208.Pp 209.Ar pos 210.Op Ar cmd 211.Ar normal Ar shift Ar altgr 212.Pp 213.Ar pos 214.Op Ar cmd 215.Ar normal Ar shift Ar altgr Ar shift-altgr 216.Sh FUNCTIONS 217.Bl -tag -width compact 218.It Fn wskbd_input "kbddev" "type" "value" 219Pass the keypress of value 220.Fa value 221and type 222.Fa type 223to wscons keyboard driver. 224Valid values of 225.Fa type 226are: 227.Bl -tag -width compact 228.It WSCONS_EVENT_KEY_UP 229Key released. 230.It WSCONS_EVENT_KEY_DOWN 231Key pressed. 232.El 233.It Fn wskbd_rawinput "kbddev" "buf" "len" 234Pass the raw keypress in the buffer 235.Fa buf 236to the wscons keyboard driver. 237The buffer is 238.Fa len 239bytes long. 240This function should only be called if the kernel option 241.Em WSDISPLAY_COMPAT_RAWKBD 242is enabled. 243.It Fn wskbd_cnattach "consops" "conscookie" "mapdata" 244Attach this keyboard as the console input by specifying the console 245operations 246.Fa consops 247and the keyboard mapping table information in 248.Fa mapdata . 249The functions specified in 250.Fa consops 251will be called with 252.Fa conscookie 253as the first argument. 254.It Fn wskbd_cndetach "" 255Detach this keyboard as the console input. 256.It Fn wskbddevprint "aux" "pnp" 257The default wskbd printing routine used by 258.Fn config_found . 259(see 260.Xr autoconf 9 ) . 261.El 262.Sh AUTOCONFIGURATION 263Keyboard drivers which want to use the wskbd module must be a 264parent to the 265.Xr wskbd 4 266device and provide an attachment interface. 267To attach the 268.Xr wskbd 4 269device, the keyboard driver must allocate and populate a 270.Fa wskbddev_attach_args 271structure with the supported operations and callbacks and call 272.Fn config_found 273to perform the attach (see 274.Xr autoconf 9 ) . 275The 276.Fa keymap 277member points to the 278.Em wskbd_mapdata 279structure which describes the keycode mapping operations. 280The 281.Fa accessops 282member points to the 283.Em wskbd_accessops 284structure which describes the keyboard access operations. 285The 286.Fa console 287member is a boolean to indicate to wscons whether this keyboard will 288be used for console input. 289.Sh OPERATION 290If the keyboard belongs to the system console, it must register the 291.Fa wskbd_consops 292structure specifying the console operations via 293.Fn wskbd_cnattach 294at console attach time. 295.Pp 296When a keypress arrives from the keyboard, the keyboard driver must 297perform any necessary character decoding to wscons events and pass the 298events to wscons via 299.Fn wskbd_input . 300If the kernel is compiled with the option 301.Em WSDISPLAY_COMPAT_RAWKBD , 302then the keyboard driver must also pass the raw keyboard data to 303wscons via 304.Fn wskbd_rawinput . 305.Pp 306The wscons framework calls back into the hardware driver by invoking 307the functions that are specified in the 308.Em accessops 309structure. 310The 311.Fn enable 312and 313.Fn set_leds 314functions are relatively simple and self-explanatory. 315The 316.Fn ioctl 317function is called by the wscons interface to perform 318keyboard-specific ioctl operations (see 319.Xr ioctl 2 ) . 320The argument 321.Fa cmd 322to the 323.Fn ioctl 324function specifies the specific command to perform using the data 325.Fa data . 326Valid commands are listed in 327.Pa sys/dev/wscons/wsconsio.h . 328.Sh CODE REFERENCES 329The wscons subsystem is implemented within the directory 330.Pa sys/dev/wscons . 331The 332.Nm 333module itself is implement within the files 334.Pa sys/dev/wscons/wskbd.c 335and 336.Pa sys/dev/wscons/wskbdutil.c . 337.Xr ioctl 2 338operations are listed in 339.Pa sys/dev/wscons/wsconsio.h . 340.Sh SEE ALSO 341.Xr ioctl 2 , 342.Xr autoconf 9 , 343.Xr driver 9 , 344.Xr intro 9 , 345.Xr wsdisplay 9 , 346.Xr wsmouse 9 347