| blob | 81a8f46b2a4823fe6c29a72850e6ac923f8e83e1 |
1 .\" $NetBSD: wskbd.9,v 1.13 2007/03/07 00:41:18 dogcow 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
58 The
59 .Nm
60 module is a component of the
61 .Xr wscons 9
62 framework to provide machine-independent keyboard support.
63 Most of the support is provided by the
64 .Xr wskbd 4
65 device driver, which must be a child of the hardware device driver.
66 .Sh DATA TYPES
67 Keyboard drivers providing support for wscons keyboards will make use
68 of the following data types:
69 .Bl -tag -width compact
70 .It Fa kbd_t
71 An opaque type describing keyboard properties.
72 .It Fa keysym_t
73 The wscons keyboard-independent symbolic representation of the keypress.
74 .It Fa struct wskbd_accessops
75 A structure used to specify the keyboard access functions.
76 All keyboards must provide this structure and pass it to the
77 .Xr wskbd 4
78 child device.
79 It 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
87 The
88 .Fa enable
89 member defines the function to be called to enable keypress passing to
90 wscons.
91 The
92 .Fa set_leds
93 member defined the function to be called to set the LEDs on the
94 keyboard.
95 The
96 .Fa ioctl
97 member defines the function to be called to perform keyboard-specific
98 ioctl calls.
99 .Pp
100 There is a
101 .Fa void *
102 cookie provided by the keyboard driver associated with these
103 functions, which is passed to them when they are invoked.
104 .It Fa struct wskbd_consops
105 A structure used to specify the keyboard console operations.
106 All keyboards which can operate as a console must provide this structure
107 and pass it to the
108 .Xr wskbd 4
109 child device.
110 If the keyboard cannot be a console, it is not
111 necessary to specify this structure.
112 It 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
119 There is a
120 .Fa void *
121 cookie provided by the keyboard driver associated with these
122 functions, which is passed to them when they are invoked.
123 .It Fa struct wscons_keydesc
124 A structure used to describe a keyboard mapping table to convert
125 keyboard-specific keycodes to wscons keysyms.
126 It has the
127 following 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
135 A structure used to describe the keyboard layout and operation to
136 interpret the keyboard layout.
137 it 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
143 A structure used to attach the
144 .Xr wskbd 4
145 child device.
146 It 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
155 Keymaps are a dense stream of
156 .Fa keysym_t .
157 A 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
166 The fields have the following meanings:
167 .Pp
168 .Bl -tag -offset indent -width SHIFT-ALTGR -compact
169 .It Ar pos
170 Always specified as
171 .Ns KC( Ns Ar pos )
172 and starts the description of key
173 .Ar pos .
174 .It Ar cmd
175 If the command modifier (KS_Cmd_XXX) is active, the optional command
176 .Ar cmd
177 is invoked.
178 .It Ar normal
179 The keysym if no modifiers are active.
180 .It Ar shift
181 The keysym if the shift modifier is active.
182 .It Ar altgr
183 The keysym if the alt-gr modifier is active.
184 .It Ar shift-altgr
185 The keysym if the shift-alt-gr modifier is active.
186 .El
187 .Pp
188 If the keysym after
189 .Ar pos
190 is not KS_Cmd_XXX, then
191 .Ar cmd
192 is empty.
193 The
194 .Ar shift ,
195 .Ar altgr
196 and
197 .Ar shift-altgr
198 fields are determined from previous fields if they are not specified.
199 Therefore, 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"
219 Pass the keypress of value
220 .Fa value
221 and type
222 .Fa type
223 to wscons keyboard driver.
224 Valid values of
225 .Fa type
226 are:
227 .Bl -tag -width compact
228 .It WSCONS_EVENT_KEY_UP
229 Key released.
230 .It WSCONS_EVENT_KEY_DOWN
231 Key pressed.
232 .El
233 .It Fn wskbd_rawinput "kbddev" "buf" "len"
234 Pass the raw keypress in the buffer
235 .Fa buf
236 to the wscons keyboard driver.
237 The buffer is
238 .Fa len
239 bytes long.
240 This function should only be called if the kernel option
241 .Em WSDISPLAY_COMPAT_RAWKBD
242 is enabled.
243 .It Fn wskbd_cnattach "consops" "conscookie" "mapdata"
244 Attach this keyboard as the console input by specifying the console
245 operations
246 .Fa consops
247 and the keyboard mapping table information in
248 .Fa mapdata .
249 The functions specified in
250 .Fa consops
251 will be called with
252 .Fa conscookie
253 as the first argument.
254 .It Fn wskbd_cndetach ""
255 Detach this keyboard as the console input.
256 .It Fn wskbddevprint "aux" "pnp"
257 The default wskbd printing routine used by
258 .Fn config_found .
259 (see
260 .Xr autoconf 9 ) .
261 .El
262 .Sh AUTOCONFIGURATION
263 Keyboard drivers which want to use the wskbd module must be a
264 parent to the
265 .Xr wskbd 4
266 device and provide an attachment interface.
267 To attach the
268 .Xr wskbd 4
269 device, the keyboard driver must allocate and populate a
270 .Fa wskbddev_attach_args
271 structure with the supported operations and callbacks and call
272 .Fn config_found
273 to perform the attach (see
274 .Xr autoconf 9 ) .
275 The
276 .Fa keymap
277 member points to the
278 .Em wskbd_mapdata
279 structure which describes the keycode mapping operations.
280 The
281 .Fa accessops
282 member points to the
283 .Em wskbd_accessops
284 structure which describes the keyboard access operations.
285 The
286 .Fa console
287 member is a boolean to indicate to wscons whether this keyboard will
288 be used for console input.
289 .Sh OPERATION
290 If the keyboard belongs to the system console, it must register the
291 .Fa wskbd_consops
292 structure specifying the console operations via
293 .Fn wskbd_cnattach
294 at console attach time.
295 .Pp
296 When a keypress arrives from the keyboard, the keyboard driver must
297 perform any necessary character decoding to wscons events and pass the
298 events to wscons via
299 .Fn wskbd_input .
300 If the kernel is compiled with the option
301 .Em WSDISPLAY_COMPAT_RAWKBD ,
302 then the keyboard driver must also pass the raw keyboard data to
303 wscons via
304 .Fn wskbd_rawinput .
305 .Pp
306 The wscons framework calls back into the hardware driver by invoking
307 the functions that are specified in the
308 .Em accessops
309 structure.
310 The
311 .Fn enable
312 and
313 .Fn set_leds
314 functions are relatively simple and self-explanatory.
315 The
316 .Fn ioctl
317 function is called by the wscons interface to perform
318 keyboard-specific ioctl operations (see
319 .Xr ioctl 2 ) .
320 The argument
321 .Fa cmd
322 to the
323 .Fn ioctl
324 function specifies the specific command to perform using the data
325 .Fa data .
326 Valid commands are listed in
327 .Pa sys/dev/wscons/wsconsio.h .
328 .Sh CODE REFERENCES
329 This section describes places within the
330 .Nx
331 source tree where actual code implementing or using the
332 machine-independent wscons subsystem can be found.
333 All pathnames are relative to
334 .Pa /usr/src .
335 .Pp
336 The wscons subsystem is implemented within the directory
337 .Pa sys/dev/wscons .
338 The
339 .Nm
340 module itself is implement within the files
341 .Pa sys/dev/wscons/wskbd.c
342 and
343 .Pa sys/dev/wscons/wskbdutil.c .
344 .Xr ioctl 2
345 operations are listed in
346 .Pa sys/dev/wscons/wsconsio.h .
347 .Sh SEE ALSO
348 .Xr ioctl 2 ,
349 .Xr autoconf 9 ,
350 .Xr driver 9 ,
351 .Xr intro 9 ,
352 .Xr wsdisplay 9 ,
353 .Xr wsmouse 9