]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - sys/dev/usb/input/ukbd.c
Change USB_DEBUG to #ifdef and allow it to be turned off. Previously this had
[FreeBSD/FreeBSD.git] / sys / dev / usb / input / ukbd.c
1 #include <sys/cdefs.h>
2 __FBSDID("$FreeBSD$");
3
4
5 /*-
6  * Copyright (c) 1998 The NetBSD Foundation, Inc.
7  * All rights reserved.
8  *
9  * This code is derived from software contributed to The NetBSD Foundation
10  * by Lennart Augustsson (lennart@augustsson.net) at
11  * Carlstedt Research & Technology.
12  *
13  * Redistribution and use in source and binary forms, with or without
14  * modification, are permitted provided that the following conditions
15  * are met:
16  * 1. Redistributions of source code must retain the above copyright
17  *    notice, this list of conditions and the following disclaimer.
18  * 2. Redistributions in binary form must reproduce the above copyright
19  *    notice, this list of conditions and the following disclaimer in the
20  *    documentation and/or other materials provided with the distribution.
21  *
22  * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
23  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
24  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
25  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
26  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32  * POSSIBILITY OF SUCH DAMAGE.
33  *
34  */
35
36 /*
37  * HID spec: http://www.usb.org/developers/devclass_docs/HID1_11.pdf
38  */
39
40 #include "opt_compat.h"
41 #include "opt_kbd.h"
42 #include "opt_ukbd.h"
43
44 #include <sys/stdint.h>
45 #include <sys/stddef.h>
46 #include <sys/param.h>
47 #include <sys/queue.h>
48 #include <sys/types.h>
49 #include <sys/systm.h>
50 #include <sys/kernel.h>
51 #include <sys/bus.h>
52 #include <sys/linker_set.h>
53 #include <sys/module.h>
54 #include <sys/lock.h>
55 #include <sys/mutex.h>
56 #include <sys/condvar.h>
57 #include <sys/sysctl.h>
58 #include <sys/sx.h>
59 #include <sys/unistd.h>
60 #include <sys/callout.h>
61 #include <sys/malloc.h>
62 #include <sys/priv.h>
63 #include <sys/kdb.h>
64
65 #include <dev/usb/usb.h>
66 #include <dev/usb/usbdi.h>
67 #include <dev/usb/usbdi_util.h>
68 #include <dev/usb/usbhid.h>
69
70 #define USB_DEBUG_VAR ukbd_debug
71 #include <dev/usb/usb_debug.h>
72
73 #include <dev/usb/quirk/usb_quirk.h>
74
75 #include <sys/ioccom.h>
76 #include <sys/filio.h>
77 #include <sys/tty.h>
78 #include <sys/kbio.h>
79
80 #include <dev/kbd/kbdreg.h>
81
82 /* the initial key map, accent map and fkey strings */
83 #if defined(UKBD_DFLT_KEYMAP) && !defined(KLD_MODULE)
84 #define KBD_DFLT_KEYMAP
85 #include "ukbdmap.h"
86 #endif
87
88 /* the following file must be included after "ukbdmap.h" */
89 #include <dev/kbd/kbdtables.h>
90
91 #ifdef USB_DEBUG
92 static int ukbd_debug = 0;
93 static int ukbd_no_leds = 0;
94
95 SYSCTL_NODE(_hw_usb, OID_AUTO, ukbd, CTLFLAG_RW, 0, "USB ukbd");
96 SYSCTL_INT(_hw_usb_ukbd, OID_AUTO, debug, CTLFLAG_RW,
97     &ukbd_debug, 0, "Debug level");
98 SYSCTL_INT(_hw_usb_ukbd, OID_AUTO, no_leds, CTLFLAG_RW,
99     &ukbd_no_leds, 0, "Disables setting of keyboard leds");
100
101 TUNABLE_INT("hw.usb.ukbd.debug", &ukbd_debug);
102 TUNABLE_INT("hw.usb.ukbd.no_leds", &ukbd_no_leds);
103 #endif
104
105 #define UKBD_EMULATE_ATSCANCODE        1
106 #define UKBD_DRIVER_NAME          "ukbd"
107 #define UKBD_NMOD                     8 /* units */
108 #define UKBD_NKEYCODE                 6 /* units */
109 #define UKBD_IN_BUF_SIZE  (2*(UKBD_NMOD + (2*UKBD_NKEYCODE)))   /* bytes */
110 #define UKBD_IN_BUF_FULL  (UKBD_IN_BUF_SIZE / 2)        /* bytes */
111 #define UKBD_NFKEY        (sizeof(fkey_tab)/sizeof(fkey_tab[0]))        /* units */
112
113 struct ukbd_data {
114         uint8_t modifiers;
115 #define MOD_CONTROL_L   0x01
116 #define MOD_CONTROL_R   0x10
117 #define MOD_SHIFT_L     0x02
118 #define MOD_SHIFT_R     0x20
119 #define MOD_ALT_L       0x04
120 #define MOD_ALT_R       0x40
121 #define MOD_WIN_L       0x08
122 #define MOD_WIN_R       0x80
123         uint8_t reserved;
124         uint8_t keycode[UKBD_NKEYCODE];
125         uint8_t exten[8];
126 };
127
128 enum {
129         UKBD_INTR_DT,
130         UKBD_CTRL_LED,
131         UKBD_N_TRANSFER,
132 };
133
134 struct ukbd_softc {
135         keyboard_t sc_kbd;
136         keymap_t sc_keymap;
137         accentmap_t sc_accmap;
138         fkeytab_t sc_fkeymap[UKBD_NFKEY];
139         struct hid_location sc_loc_apple_eject;
140         struct hid_location sc_loc_apple_fn;
141         struct usb_callout sc_callout;
142         struct ukbd_data sc_ndata;
143         struct ukbd_data sc_odata;
144
145         struct thread *sc_poll_thread;
146         struct usb_device *sc_udev;
147         struct usb_interface *sc_iface;
148         struct usb_xfer *sc_xfer[UKBD_N_TRANSFER];
149
150         uint32_t sc_ntime[UKBD_NKEYCODE];
151         uint32_t sc_otime[UKBD_NKEYCODE];
152         uint32_t sc_input[UKBD_IN_BUF_SIZE];    /* input buffer */
153         uint32_t sc_time_ms;
154         uint32_t sc_composed_char;      /* composed char code, if non-zero */
155 #ifdef UKBD_EMULATE_ATSCANCODE
156         uint32_t sc_buffered_char[2];
157 #endif
158         uint32_t sc_flags;              /* flags */
159 #define UKBD_FLAG_COMPOSE       0x0001
160 #define UKBD_FLAG_POLLING       0x0002
161 #define UKBD_FLAG_SET_LEDS      0x0004
162 #define UKBD_FLAG_ATTACHED      0x0010
163 #define UKBD_FLAG_GONE          0x0020
164 #define UKBD_FLAG_APPLE_EJECT   0x0040
165 #define UKBD_FLAG_APPLE_FN      0x0080
166 #define UKBD_FLAG_APPLE_SWAP    0x0100
167 #define UKBD_FLAG_TIMER_RUNNING 0x0200
168
169         int     sc_mode;                /* input mode (K_XLATE,K_RAW,K_CODE) */
170         int     sc_state;               /* shift/lock key state */
171         int     sc_accents;             /* accent key index (> 0) */
172         int     sc_poll_tick_last;
173
174         uint16_t sc_inputs;
175         uint16_t sc_inputhead;
176         uint16_t sc_inputtail;
177
178         uint8_t sc_leds;                /* store for async led requests */
179         uint8_t sc_iface_index;
180         uint8_t sc_iface_no;
181         uint8_t sc_kbd_id;
182         uint8_t sc_led_id;
183         uint8_t sc_poll_detected;
184 };
185
186 #define KEY_ERROR         0x01
187
188 #define KEY_PRESS         0
189 #define KEY_RELEASE       0x400
190 #define KEY_INDEX(c)      ((c) & 0xFF)
191
192 #define SCAN_PRESS        0
193 #define SCAN_RELEASE      0x80
194 #define SCAN_PREFIX_E0    0x100
195 #define SCAN_PREFIX_E1    0x200
196 #define SCAN_PREFIX_CTL   0x400
197 #define SCAN_PREFIX_SHIFT 0x800
198 #define SCAN_PREFIX     (SCAN_PREFIX_E0  | SCAN_PREFIX_E1 | \
199                          SCAN_PREFIX_CTL | SCAN_PREFIX_SHIFT)
200 #define SCAN_CHAR(c)    ((c) & 0x7f)
201
202 struct ukbd_mods {
203         uint32_t mask, key;
204 };
205
206 static const struct ukbd_mods ukbd_mods[UKBD_NMOD] = {
207         {MOD_CONTROL_L, 0xe0},
208         {MOD_CONTROL_R, 0xe4},
209         {MOD_SHIFT_L, 0xe1},
210         {MOD_SHIFT_R, 0xe5},
211         {MOD_ALT_L, 0xe2},
212         {MOD_ALT_R, 0xe6},
213         {MOD_WIN_L, 0xe3},
214         {MOD_WIN_R, 0xe7},
215 };
216
217 #define NN 0                            /* no translation */
218 /*
219  * Translate USB keycodes to AT keyboard scancodes.
220  */
221 /*
222  * FIXME: Mac USB keyboard generates:
223  * 0x53: keypad NumLock/Clear
224  * 0x66: Power
225  * 0x67: keypad =
226  * 0x68: F13
227  * 0x69: F14
228  * 0x6a: F15
229  */
230 static const uint8_t ukbd_trtab[256] = {
231         0, 0, 0, 0, 30, 48, 46, 32,     /* 00 - 07 */
232         18, 33, 34, 35, 23, 36, 37, 38, /* 08 - 0F */
233         50, 49, 24, 25, 16, 19, 31, 20, /* 10 - 17 */
234         22, 47, 17, 45, 21, 44, 2, 3,   /* 18 - 1F */
235         4, 5, 6, 7, 8, 9, 10, 11,       /* 20 - 27 */
236         28, 1, 14, 15, 57, 12, 13, 26,  /* 28 - 2F */
237         27, 43, 43, 39, 40, 41, 51, 52, /* 30 - 37 */
238         53, 58, 59, 60, 61, 62, 63, 64, /* 38 - 3F */
239         65, 66, 67, 68, 87, 88, 92, 70, /* 40 - 47 */
240         104, 102, 94, 96, 103, 99, 101, 98,     /* 48 - 4F */
241         97, 100, 95, 69, 91, 55, 74, 78,/* 50 - 57 */
242         89, 79, 80, 81, 75, 76, 77, 71, /* 58 - 5F */
243         72, 73, 82, 83, 86, 107, 122, NN,       /* 60 - 67 */
244         NN, NN, NN, NN, NN, NN, NN, NN, /* 68 - 6F */
245         NN, NN, NN, NN, 115, 108, 111, 113,     /* 70 - 77 */
246         109, 110, 112, 118, 114, 116, 117, 119, /* 78 - 7F */
247         121, 120, NN, NN, NN, NN, NN, 123,      /* 80 - 87 */
248         124, 125, 126, 127, 128, NN, NN, NN,    /* 88 - 8F */
249         NN, NN, NN, NN, NN, NN, NN, NN, /* 90 - 97 */
250         NN, NN, NN, NN, NN, NN, NN, NN, /* 98 - 9F */
251         NN, NN, NN, NN, NN, NN, NN, NN, /* A0 - A7 */
252         NN, NN, NN, NN, NN, NN, NN, NN, /* A8 - AF */
253         NN, NN, NN, NN, NN, NN, NN, NN, /* B0 - B7 */
254         NN, NN, NN, NN, NN, NN, NN, NN, /* B8 - BF */
255         NN, NN, NN, NN, NN, NN, NN, NN, /* C0 - C7 */
256         NN, NN, NN, NN, NN, NN, NN, NN, /* C8 - CF */
257         NN, NN, NN, NN, NN, NN, NN, NN, /* D0 - D7 */
258         NN, NN, NN, NN, NN, NN, NN, NN, /* D8 - DF */
259         29, 42, 56, 105, 90, 54, 93, 106,       /* E0 - E7 */
260         NN, NN, NN, NN, NN, NN, NN, NN, /* E8 - EF */
261         NN, NN, NN, NN, NN, NN, NN, NN, /* F0 - F7 */
262         NN, NN, NN, NN, NN, NN, NN, NN, /* F8 - FF */
263 };
264
265 /* prototypes */
266 static void     ukbd_timeout(void *);
267 static void     ukbd_set_leds(struct ukbd_softc *, uint8_t);
268 static int      ukbd_set_typematic(keyboard_t *, int);
269 #ifdef UKBD_EMULATE_ATSCANCODE
270 static int      ukbd_key2scan(struct ukbd_softc *, int, int, int);
271 #endif
272 static uint32_t ukbd_read_char(keyboard_t *, int);
273 static void     ukbd_clear_state(keyboard_t *);
274 static int      ukbd_ioctl(keyboard_t *, u_long, caddr_t);
275 static int      ukbd_enable(keyboard_t *);
276 static int      ukbd_disable(keyboard_t *);
277 static void     ukbd_interrupt(struct ukbd_softc *);
278 static int      ukbd_is_polling(struct ukbd_softc *);
279 static int      ukbd_polls_other_thread(struct ukbd_softc *);
280 static void     ukbd_event_keyinput(struct ukbd_softc *);
281
282 static device_probe_t ukbd_probe;
283 static device_attach_t ukbd_attach;
284 static device_detach_t ukbd_detach;
285 static device_resume_t ukbd_resume;
286
287 static uint8_t
288 ukbd_any_key_pressed(struct ukbd_softc *sc)
289 {
290         uint8_t i;
291         uint8_t j;
292
293         for (j = i = 0; i < UKBD_NKEYCODE; i++)
294                 j |= sc->sc_odata.keycode[i];
295
296         return (j ? 1 : 0);
297 }
298
299 static void
300 ukbd_start_timer(struct ukbd_softc *sc)
301 {
302         sc->sc_flags |= UKBD_FLAG_TIMER_RUNNING;
303         usb_callout_reset(&sc->sc_callout, hz / 40, &ukbd_timeout, sc);
304 }
305
306 static void
307 ukbd_put_key(struct ukbd_softc *sc, uint32_t key)
308 {
309         mtx_assert(&Giant, MA_OWNED);
310
311         DPRINTF("0x%02x (%d) %s\n", key, key,
312             (key & KEY_RELEASE) ? "released" : "pressed");
313
314         if (sc->sc_inputs < UKBD_IN_BUF_SIZE) {
315                 sc->sc_input[sc->sc_inputtail] = key;
316                 ++(sc->sc_inputs);
317                 ++(sc->sc_inputtail);
318                 if (sc->sc_inputtail >= UKBD_IN_BUF_SIZE) {
319                         sc->sc_inputtail = 0;
320                 }
321         } else {
322                 DPRINTF("input buffer is full\n");
323         }
324 }
325
326 static void
327 ukbd_do_poll(struct ukbd_softc *sc, uint8_t wait)
328 {
329         DPRINTFN(2, "polling\n");
330
331         /* update stats about last polling event */
332         sc->sc_poll_tick_last = ticks;
333         sc->sc_poll_detected = 1;
334
335         if (kdb_active == 0) {
336                 while (sc->sc_inputs == 0) {
337                         /* make sure the USB code gets a chance to run */
338                         pause("UKBD", 1);
339
340                         /* check if we should wait */
341                         if (!wait)
342                                 break;
343                 }
344                 return;         /* Only poll if KDB is active */
345         }
346
347         while (sc->sc_inputs == 0) {
348
349                 usbd_transfer_poll(sc->sc_xfer, UKBD_N_TRANSFER);
350
351                 /* Delay-optimised support for repetition of keys */
352
353                 if (ukbd_any_key_pressed(sc)) {
354                         /* a key is pressed - need timekeeping */
355                         DELAY(1000);
356
357                         /* 1 millisecond has passed */
358                         sc->sc_time_ms += 1;
359                 }
360
361                 ukbd_interrupt(sc);
362
363                 if (!wait)
364                         break;
365         }
366 }
367
368 static int32_t
369 ukbd_get_key(struct ukbd_softc *sc, uint8_t wait)
370 {
371         int32_t c;
372
373         mtx_assert(&Giant, MA_OWNED);
374
375         if (sc->sc_inputs == 0) {
376                 /* start transfer, if not already started */
377                 usbd_transfer_start(sc->sc_xfer[UKBD_INTR_DT]);
378         }
379
380         if (ukbd_polls_other_thread(sc))
381                 return (-1);
382
383         if (sc->sc_flags & UKBD_FLAG_POLLING)
384                 ukbd_do_poll(sc, wait);
385
386         if (sc->sc_inputs == 0) {
387                 c = -1;
388         } else {
389                 c = sc->sc_input[sc->sc_inputhead];
390                 --(sc->sc_inputs);
391                 ++(sc->sc_inputhead);
392                 if (sc->sc_inputhead >= UKBD_IN_BUF_SIZE) {
393                         sc->sc_inputhead = 0;
394                 }
395         }
396         return (c);
397 }
398
399 static void
400 ukbd_interrupt(struct ukbd_softc *sc)
401 {
402         uint32_t n_mod;
403         uint32_t o_mod;
404         uint32_t now = sc->sc_time_ms;
405         uint32_t dtime;
406         uint8_t key;
407         uint8_t i;
408         uint8_t j;
409
410         if (sc->sc_ndata.keycode[0] == KEY_ERROR)
411                 return;
412
413         n_mod = sc->sc_ndata.modifiers;
414         o_mod = sc->sc_odata.modifiers;
415         if (n_mod != o_mod) {
416                 for (i = 0; i < UKBD_NMOD; i++) {
417                         if ((n_mod & ukbd_mods[i].mask) !=
418                             (o_mod & ukbd_mods[i].mask)) {
419                                 ukbd_put_key(sc, ukbd_mods[i].key |
420                                     ((n_mod & ukbd_mods[i].mask) ?
421                                     KEY_PRESS : KEY_RELEASE));
422                         }
423                 }
424         }
425         /* Check for released keys. */
426         for (i = 0; i < UKBD_NKEYCODE; i++) {
427                 key = sc->sc_odata.keycode[i];
428                 if (key == 0) {
429                         continue;
430                 }
431                 for (j = 0; j < UKBD_NKEYCODE; j++) {
432                         if (sc->sc_ndata.keycode[j] == 0) {
433                                 continue;
434                         }
435                         if (key == sc->sc_ndata.keycode[j]) {
436                                 goto rfound;
437                         }
438                 }
439                 ukbd_put_key(sc, key | KEY_RELEASE);
440 rfound: ;
441         }
442
443         /* Check for pressed keys. */
444         for (i = 0; i < UKBD_NKEYCODE; i++) {
445                 key = sc->sc_ndata.keycode[i];
446                 if (key == 0) {
447                         continue;
448                 }
449                 sc->sc_ntime[i] = now + sc->sc_kbd.kb_delay1;
450                 for (j = 0; j < UKBD_NKEYCODE; j++) {
451                         if (sc->sc_odata.keycode[j] == 0) {
452                                 continue;
453                         }
454                         if (key == sc->sc_odata.keycode[j]) {
455
456                                 /* key is still pressed */
457
458                                 sc->sc_ntime[i] = sc->sc_otime[j];
459                                 dtime = (sc->sc_otime[j] - now);
460
461                                 if (!(dtime & 0x80000000)) {
462                                         /* time has not elapsed */
463                                         goto pfound;
464                                 }
465                                 sc->sc_ntime[i] = now + sc->sc_kbd.kb_delay2;
466                                 break;
467                         }
468                 }
469                 ukbd_put_key(sc, key | KEY_PRESS);
470
471                 /*
472                  * If any other key is presently down, force its repeat to be
473                  * well in the future (100s).  This makes the last key to be
474                  * pressed do the autorepeat.
475                  */
476                 for (j = 0; j != UKBD_NKEYCODE; j++) {
477                         if (j != i)
478                                 sc->sc_ntime[j] = now + (100 * 1000);
479                 }
480 pfound: ;
481         }
482
483         sc->sc_odata = sc->sc_ndata;
484
485         memcpy(sc->sc_otime, sc->sc_ntime, sizeof(sc->sc_otime));
486
487         ukbd_event_keyinput(sc);
488 }
489
490 static void
491 ukbd_event_keyinput(struct ukbd_softc *sc)
492 {
493         int c;
494
495         if (ukbd_is_polling(sc))
496                 return;
497
498         if (sc->sc_inputs == 0)
499                 return;
500
501         if (KBD_IS_ACTIVE(&sc->sc_kbd) &&
502             KBD_IS_BUSY(&sc->sc_kbd)) {
503                 /* let the callback function process the input */
504                 (sc->sc_kbd.kb_callback.kc_func) (&sc->sc_kbd, KBDIO_KEYINPUT,
505                     sc->sc_kbd.kb_callback.kc_arg);
506         } else {
507                 /* read and discard the input, no one is waiting for it */
508                 do {
509                         c = ukbd_read_char(&sc->sc_kbd, 0);
510                 } while (c != NOKEY);
511         }
512 }
513
514 static void
515 ukbd_timeout(void *arg)
516 {
517         struct ukbd_softc *sc = arg;
518
519         mtx_assert(&Giant, MA_OWNED);
520
521         sc->sc_time_ms += 25;   /* milliseconds */
522
523         ukbd_interrupt(sc);
524
525         /* Make sure any leftover key events gets read out */
526         ukbd_event_keyinput(sc);
527
528         if (ukbd_any_key_pressed(sc) || (sc->sc_inputs != 0)) {
529                 ukbd_start_timer(sc);
530         } else {
531                 sc->sc_flags &= ~UKBD_FLAG_TIMER_RUNNING;
532         }
533 }
534
535 static uint8_t
536 ukbd_apple_fn(uint8_t keycode) {
537         switch (keycode) {
538         case 0x28: return 0x49; /* RETURN -> INSERT */
539         case 0x2a: return 0x4c; /* BACKSPACE -> DEL */
540         case 0x50: return 0x4a; /* LEFT ARROW -> HOME */
541         case 0x4f: return 0x4d; /* RIGHT ARROW -> END */
542         case 0x52: return 0x4b; /* UP ARROW -> PGUP */
543         case 0x51: return 0x4e; /* DOWN ARROW -> PGDN */
544         default: return keycode;
545         }
546 }
547
548 static uint8_t
549 ukbd_apple_swap(uint8_t keycode) {
550         switch (keycode) {
551         case 0x35: return 0x64;
552         case 0x64: return 0x35;
553         default: return keycode;
554         }
555 }
556
557 static void
558 ukbd_intr_callback(struct usb_xfer *xfer, usb_error_t error)
559 {
560         struct ukbd_softc *sc = usbd_xfer_softc(xfer);
561         struct usb_page_cache *pc;
562         uint8_t i;
563         uint8_t offset;
564         uint8_t id;
565         uint8_t apple_fn;
566         uint8_t apple_eject;
567         int len;
568
569         usbd_xfer_status(xfer, &len, NULL, NULL, NULL);
570         pc = usbd_xfer_get_frame(xfer, 0);
571
572         switch (USB_GET_STATE(xfer)) {
573         case USB_ST_TRANSFERRED:
574                 DPRINTF("actlen=%d bytes\n", len);
575
576                 if (len == 0) {
577                         DPRINTF("zero length data\n");
578                         goto tr_setup;
579                 }
580
581                 if (sc->sc_kbd_id != 0) {
582                         /* check and remove HID ID byte */
583                         usbd_copy_out(pc, 0, &id, 1);
584                         if (id != sc->sc_kbd_id) {
585                                 DPRINTF("wrong HID ID\n");
586                                 goto tr_setup;
587                         }
588                         offset = 1;
589                         len--;
590                 } else {
591                         offset = 0;
592                 }
593
594                 if (len > sizeof(sc->sc_ndata)) {
595                         len = sizeof(sc->sc_ndata);
596                 }
597
598                 if (len) {
599                         memset(&sc->sc_ndata, 0, sizeof(sc->sc_ndata));
600                         usbd_copy_out(pc, offset, &sc->sc_ndata, len);
601
602                         if ((sc->sc_flags & UKBD_FLAG_APPLE_EJECT) &&
603                             hid_get_data((uint8_t *)&sc->sc_ndata,
604                                 len, &sc->sc_loc_apple_eject))
605                                 apple_eject = 1;
606                         else
607                                 apple_eject = 0;
608
609                         if ((sc->sc_flags & UKBD_FLAG_APPLE_FN) &&
610                             hid_get_data((uint8_t *)&sc->sc_ndata,
611                                 len, &sc->sc_loc_apple_fn))
612                                 apple_fn = 1;
613                         else
614                                 apple_fn = 0;
615 #ifdef USB_DEBUG
616                         DPRINTF("apple_eject=%u apple_fn=%u\n",
617                             apple_eject, apple_fn);
618
619                         if (sc->sc_ndata.modifiers) {
620                                 DPRINTF("mod: 0x%04x\n", sc->sc_ndata.modifiers);
621                         }
622                         for (i = 0; i < UKBD_NKEYCODE; i++) {
623                                 if (sc->sc_ndata.keycode[i]) {
624                                         DPRINTF("[%d] = %d\n", i, sc->sc_ndata.keycode[i]);
625                                 }
626                         }
627 #endif                                  /* USB_DEBUG */
628
629                         if (apple_fn) {
630                                 for (i = 0; i < UKBD_NKEYCODE; i++) {
631                                         sc->sc_ndata.keycode[i] = 
632                                             ukbd_apple_fn(sc->sc_ndata.keycode[i]);
633                                 }
634                         }
635
636                         if (sc->sc_flags & UKBD_FLAG_APPLE_SWAP) {
637                                 for (i = 0; i < UKBD_NKEYCODE; i++) {
638                                         sc->sc_ndata.keycode[i] = 
639                                             ukbd_apple_swap(sc->sc_ndata.keycode[i]);
640                                 }
641                         }
642
643                         ukbd_interrupt(sc);
644
645                         if (!(sc->sc_flags & UKBD_FLAG_TIMER_RUNNING)) {
646                                 if (ukbd_any_key_pressed(sc)) {
647                                         ukbd_start_timer(sc);
648                                 }
649                         }
650                 }
651         case USB_ST_SETUP:
652 tr_setup:
653                 if (sc->sc_inputs < UKBD_IN_BUF_FULL) {
654                         usbd_xfer_set_frame_len(xfer, 0, usbd_xfer_max_len(xfer));
655                         usbd_transfer_submit(xfer);
656                 } else {
657                         DPRINTF("input queue is full!\n");
658                 }
659                 break;
660
661         default:                        /* Error */
662                 DPRINTF("error=%s\n", usbd_errstr(error));
663
664                 if (error != USB_ERR_CANCELLED) {
665                         /* try to clear stall first */
666                         usbd_xfer_set_stall(xfer);
667                         goto tr_setup;
668                 }
669                 break;
670         }
671 }
672
673 static void
674 ukbd_set_leds_callback(struct usb_xfer *xfer, usb_error_t error)
675 {
676         struct usb_device_request req;
677         struct usb_page_cache *pc;
678         uint8_t buf[2];
679         struct ukbd_softc *sc = usbd_xfer_softc(xfer);
680
681 #ifdef USB_DEBUG
682         if (ukbd_no_leds)
683                 return;
684 #endif
685
686         switch (USB_GET_STATE(xfer)) {
687         case USB_ST_TRANSFERRED:
688         case USB_ST_SETUP:
689                 if (sc->sc_flags & UKBD_FLAG_SET_LEDS) {
690                         sc->sc_flags &= ~UKBD_FLAG_SET_LEDS;
691
692                         req.bmRequestType = UT_WRITE_CLASS_INTERFACE;
693                         req.bRequest = UR_SET_REPORT;
694                         USETW2(req.wValue, UHID_OUTPUT_REPORT, 0);
695                         req.wIndex[0] = sc->sc_iface_no;
696                         req.wIndex[1] = 0;
697                         req.wLength[1] = 0;
698
699                         /* check if we need to prefix an ID byte */
700                         if (sc->sc_led_id != 0) {
701                                 req.wLength[0] = 2;
702                                 buf[0] = sc->sc_led_id;
703                                 buf[1] = sc->sc_leds;
704                         } else {
705                                 req.wLength[0] = 1;
706                                 buf[0] = sc->sc_leds;
707                                 buf[1] = 0;
708                         }
709
710                         pc = usbd_xfer_get_frame(xfer, 0);
711                         usbd_copy_in(pc, 0, &req, sizeof(req));
712                         pc = usbd_xfer_get_frame(xfer, 1);
713                         usbd_copy_in(pc, 0, buf, sizeof(buf));
714
715                         usbd_xfer_set_frame_len(xfer, 0, sizeof(req));
716                         usbd_xfer_set_frame_len(xfer, 1, req.wLength[0]);
717                         usbd_xfer_set_frames(xfer, 2);
718                         usbd_transfer_submit(xfer);
719                 }
720                 break;
721
722         default:                        /* Error */
723                 DPRINTFN(0, "error=%s\n", usbd_errstr(error));
724                 break;
725         }
726 }
727
728 static const struct usb_config ukbd_config[UKBD_N_TRANSFER] = {
729
730         [UKBD_INTR_DT] = {
731                 .type = UE_INTERRUPT,
732                 .endpoint = UE_ADDR_ANY,
733                 .direction = UE_DIR_IN,
734                 .flags = {.pipe_bof = 1,.short_xfer_ok = 1,},
735                 .bufsize = 0,   /* use wMaxPacketSize */
736                 .callback = &ukbd_intr_callback,
737         },
738
739         [UKBD_CTRL_LED] = {
740                 .type = UE_CONTROL,
741                 .endpoint = 0x00,       /* Control pipe */
742                 .direction = UE_DIR_ANY,
743                 .bufsize = sizeof(struct usb_device_request) + 8,
744                 .callback = &ukbd_set_leds_callback,
745                 .timeout = 1000,        /* 1 second */
746         },
747 };
748
749 static int
750 ukbd_probe(device_t dev)
751 {
752         keyboard_switch_t *sw = kbd_get_switch(UKBD_DRIVER_NAME);
753         struct usb_attach_arg *uaa = device_get_ivars(dev);
754         void *d_ptr;
755         int error;
756         uint16_t d_len;
757
758         DPRINTFN(11, "\n");
759
760         if (sw == NULL) {
761                 return (ENXIO);
762         }
763         if (uaa->usb_mode != USB_MODE_HOST) {
764                 return (ENXIO);
765         }
766
767         if (uaa->info.bInterfaceClass != UICLASS_HID)
768                 return (ENXIO);
769
770         if ((uaa->info.bInterfaceSubClass == UISUBCLASS_BOOT) &&
771             (uaa->info.bInterfaceProtocol == UIPROTO_BOOT_KEYBOARD)) {
772                 if (usb_test_quirk(uaa, UQ_KBD_IGNORE))
773                         return (ENXIO);
774                 else
775                         return (BUS_PROBE_GENERIC);
776         }
777
778         error = usbd_req_get_hid_desc(uaa->device, NULL,
779             &d_ptr, &d_len, M_TEMP, uaa->info.bIfaceIndex);
780
781         if (error)
782                 return (ENXIO);
783
784         /* 
785          * NOTE: we currently don't support USB mouse and USB keyboard
786          * on the same USB endpoint.
787          */
788         if (hid_is_collection(d_ptr, d_len,
789             HID_USAGE2(HUP_GENERIC_DESKTOP, HUG_MOUSE))) {
790                 /* most likely a mouse */
791                 error = ENXIO;
792         } else if (hid_is_collection(d_ptr, d_len,
793             HID_USAGE2(HUP_GENERIC_DESKTOP, HUG_KEYBOARD))) {
794                 if (usb_test_quirk(uaa, UQ_KBD_IGNORE))
795                         error = ENXIO;
796                 else
797                         error = BUS_PROBE_GENERIC;
798         } else
799                 error = ENXIO;
800
801         free(d_ptr, M_TEMP);
802         return (error);
803 }
804
805 static int
806 ukbd_attach(device_t dev)
807 {
808         struct ukbd_softc *sc = device_get_softc(dev);
809         struct usb_attach_arg *uaa = device_get_ivars(dev);
810         int32_t unit = device_get_unit(dev);
811         keyboard_t *kbd = &sc->sc_kbd;
812         void *hid_ptr = NULL;
813         usb_error_t err;
814         uint32_t flags;
815         uint16_t n;
816         uint16_t hid_len;
817
818         kbd_init_struct(kbd, UKBD_DRIVER_NAME, KB_OTHER, unit, 0, 0, 0);
819
820         kbd->kb_data = (void *)sc;
821
822         device_set_usb_desc(dev);
823
824         sc->sc_udev = uaa->device;
825         sc->sc_iface = uaa->iface;
826         sc->sc_iface_index = uaa->info.bIfaceIndex;
827         sc->sc_iface_no = uaa->info.bIfaceNum;
828         sc->sc_mode = K_XLATE;
829
830         usb_callout_init_mtx(&sc->sc_callout, &Giant, 0);
831
832         err = usbd_transfer_setup(uaa->device,
833             &uaa->info.bIfaceIndex, sc->sc_xfer, ukbd_config,
834             UKBD_N_TRANSFER, sc, &Giant);
835
836         if (err) {
837                 DPRINTF("error=%s\n", usbd_errstr(err));
838                 goto detach;
839         }
840         /* setup default keyboard maps */
841
842         sc->sc_keymap = key_map;
843         sc->sc_accmap = accent_map;
844         for (n = 0; n < UKBD_NFKEY; n++) {
845                 sc->sc_fkeymap[n] = fkey_tab[n];
846         }
847
848         kbd_set_maps(kbd, &sc->sc_keymap, &sc->sc_accmap,
849             sc->sc_fkeymap, UKBD_NFKEY);
850
851         KBD_FOUND_DEVICE(kbd);
852
853         ukbd_clear_state(kbd);
854
855         /*
856          * FIXME: set the initial value for lock keys in "sc_state"
857          * according to the BIOS data?
858          */
859         KBD_PROBE_DONE(kbd);
860
861         /*
862          * Set boot protocol if we need the quirk.
863          */
864         if (usb_test_quirk(uaa, UQ_KBD_BOOTPROTO)) {
865                 err = usbd_req_set_protocol(sc->sc_udev, NULL, 
866                         sc->sc_iface_index, 0);
867                 if (err != USB_ERR_NORMAL_COMPLETION) {
868                         DPRINTF("set protocol error=%s\n", usbd_errstr(err));
869                         goto detach;
870                 }
871         }
872
873         /* figure out if there is an ID byte in the data */
874         err = usbd_req_get_hid_desc(uaa->device, NULL, &hid_ptr,
875             &hid_len, M_TEMP, uaa->info.bIfaceIndex);
876         if (err == 0) {
877                 uint8_t apple_keys = 0;
878                 uint8_t temp_id;
879
880                 /* investigate if this is an Apple Keyboard */
881                 if (hid_locate(hid_ptr, hid_len,
882                     HID_USAGE2(HUP_CONSUMER, HUG_APPLE_EJECT),
883                     hid_input, 0, &sc->sc_loc_apple_eject, &flags,
884                     &temp_id)) {
885                         if (flags & HIO_VARIABLE)
886                                 sc->sc_flags |= UKBD_FLAG_APPLE_EJECT | 
887                                     UKBD_FLAG_APPLE_SWAP;
888                         DPRINTFN(1, "Found Apple eject-key\n");
889                         apple_keys = 1;
890                         sc->sc_kbd_id = temp_id;
891                 }
892                 if (hid_locate(hid_ptr, hid_len,
893                     HID_USAGE2(0xFFFF, 0x0003),
894                     hid_input, 0, &sc->sc_loc_apple_fn, &flags,
895                     &temp_id)) {
896                         if (flags & HIO_VARIABLE)
897                                 sc->sc_flags |= UKBD_FLAG_APPLE_FN;
898                         DPRINTFN(1, "Found Apple FN-key\n");
899                         apple_keys = 1;
900                         sc->sc_kbd_id = temp_id;
901                 }
902                 if (apple_keys == 0) {
903                         /* 
904                          * Assume the first HID ID contains the
905                          * keyboard data
906                          */
907                         hid_report_size(hid_ptr, hid_len,
908                             hid_input, &sc->sc_kbd_id);
909                 }
910
911                 /* investigate if we need an ID-byte for the leds */
912                 hid_report_size(hid_ptr, hid_len, hid_output, &sc->sc_led_id);
913
914                 free(hid_ptr, M_TEMP);
915         }
916
917         /* ignore if SETIDLE fails, hence it is not crucial */
918         err = usbd_req_set_idle(sc->sc_udev, NULL, sc->sc_iface_index, 0, 0);
919
920         mtx_lock(&Giant);
921
922         ukbd_ioctl(kbd, KDSETLED, (caddr_t)&sc->sc_state);
923
924         KBD_INIT_DONE(kbd);
925
926         mtx_unlock(&Giant);
927
928         if (kbd_register(kbd) < 0) {
929                 goto detach;
930         }
931         KBD_CONFIG_DONE(kbd);
932
933         ukbd_enable(kbd);
934
935 #ifdef KBD_INSTALL_CDEV
936         if (kbd_attach(kbd)) {
937                 goto detach;
938         }
939 #endif
940         sc->sc_flags |= UKBD_FLAG_ATTACHED;
941
942         if (bootverbose) {
943                 genkbd_diag(kbd, bootverbose);
944         }
945         /* lock keyboard mutex */
946
947         mtx_lock(&Giant);
948
949         /* start the keyboard */
950
951         usbd_transfer_start(sc->sc_xfer[UKBD_INTR_DT]);
952
953         mtx_unlock(&Giant);
954         return (0);                     /* success */
955
956 detach:
957         ukbd_detach(dev);
958         return (ENXIO);                 /* error */
959 }
960
961 static int
962 ukbd_detach(device_t dev)
963 {
964         struct ukbd_softc *sc = device_get_softc(dev);
965         int error;
966
967         DPRINTF("\n");
968
969         mtx_lock(&Giant);
970
971         sc->sc_flags |= UKBD_FLAG_GONE;
972
973         usb_callout_stop(&sc->sc_callout);
974
975         ukbd_disable(&sc->sc_kbd);
976
977 #ifdef KBD_INSTALL_CDEV
978         if (sc->sc_flags & UKBD_FLAG_ATTACHED) {
979                 error = kbd_detach(&sc->sc_kbd);
980                 if (error) {
981                         /* usb attach cannot return an error */
982                         device_printf(dev, "WARNING: kbd_detach() "
983                             "returned non-zero! (ignored)\n");
984                 }
985         }
986 #endif
987         if (KBD_IS_CONFIGURED(&sc->sc_kbd)) {
988                 error = kbd_unregister(&sc->sc_kbd);
989                 if (error) {
990                         /* usb attach cannot return an error */
991                         device_printf(dev, "WARNING: kbd_unregister() "
992                             "returned non-zero! (ignored)\n");
993                 }
994         }
995         sc->sc_kbd.kb_flags = 0;
996
997         mtx_unlock(&Giant);
998
999         usbd_transfer_unsetup(sc->sc_xfer, UKBD_N_TRANSFER);
1000
1001         usb_callout_drain(&sc->sc_callout);
1002
1003         DPRINTF("%s: disconnected\n",
1004             device_get_nameunit(dev));
1005
1006         return (0);
1007 }
1008
1009 static int
1010 ukbd_resume(device_t dev)
1011 {
1012         struct ukbd_softc *sc = device_get_softc(dev);
1013
1014         mtx_lock(&Giant);
1015
1016         ukbd_clear_state(&sc->sc_kbd);
1017
1018         mtx_unlock(&Giant);
1019
1020         return (0);
1021 }
1022
1023 /* early keyboard probe, not supported */
1024 static int
1025 ukbd_configure(int flags)
1026 {
1027         return (0);
1028 }
1029
1030 /* detect a keyboard, not used */
1031 static int
1032 ukbd__probe(int unit, void *arg, int flags)
1033 {
1034         return (ENXIO);
1035 }
1036
1037 /* reset and initialize the device, not used */
1038 static int
1039 ukbd_init(int unit, keyboard_t **kbdp, void *arg, int flags)
1040 {
1041         return (ENXIO);
1042 }
1043
1044 /* test the interface to the device, not used */
1045 static int
1046 ukbd_test_if(keyboard_t *kbd)
1047 {
1048         return (0);
1049 }
1050
1051 /* finish using this keyboard, not used */
1052 static int
1053 ukbd_term(keyboard_t *kbd)
1054 {
1055         return (ENXIO);
1056 }
1057
1058 /* keyboard interrupt routine, not used */
1059 static int
1060 ukbd_intr(keyboard_t *kbd, void *arg)
1061 {
1062         return (0);
1063 }
1064
1065 /* lock the access to the keyboard, not used */
1066 static int
1067 ukbd_lock(keyboard_t *kbd, int lock)
1068 {
1069         return (1);
1070 }
1071
1072 /*
1073  * Enable the access to the device; until this function is called,
1074  * the client cannot read from the keyboard.
1075  */
1076 static int
1077 ukbd_enable(keyboard_t *kbd)
1078 {
1079         if (!mtx_owned(&Giant)) {
1080                 /* XXX cludge */
1081                 int retval;
1082                 mtx_lock(&Giant);
1083                 retval = ukbd_enable(kbd);
1084                 mtx_unlock(&Giant);
1085                 return (retval);
1086         }
1087         KBD_ACTIVATE(kbd);
1088         return (0);
1089 }
1090
1091 /* disallow the access to the device */
1092 static int
1093 ukbd_disable(keyboard_t *kbd)
1094 {
1095         if (!mtx_owned(&Giant)) {
1096                 /* XXX cludge */
1097                 int retval;
1098                 mtx_lock(&Giant);
1099                 retval = ukbd_disable(kbd);
1100                 mtx_unlock(&Giant);
1101                 return (retval);
1102         }
1103         KBD_DEACTIVATE(kbd);
1104         return (0);
1105 }
1106
1107 /* check if data is waiting */
1108 static int
1109 ukbd_check(keyboard_t *kbd)
1110 {
1111         struct ukbd_softc *sc = kbd->kb_data;
1112
1113         if (!KBD_IS_ACTIVE(kbd))
1114                 return (0);
1115
1116         if (sc->sc_flags & UKBD_FLAG_POLLING) {
1117                 if (!mtx_owned(&Giant)) {
1118                         /* XXX cludge */
1119                         int retval;
1120                         mtx_lock(&Giant);
1121                         retval = ukbd_check(kbd);
1122                         mtx_unlock(&Giant);
1123                         return (retval);
1124                 }
1125         } else {
1126                 /* XXX the keyboard layer requires Giant */
1127                 if (!mtx_owned(&Giant))
1128                         return (0);
1129         }
1130
1131         /* check if key belongs to this thread */
1132         if (ukbd_polls_other_thread(sc))
1133                 return (0);
1134
1135         if (sc->sc_flags & UKBD_FLAG_POLLING)
1136                 ukbd_do_poll(sc, 0);
1137
1138 #ifdef UKBD_EMULATE_ATSCANCODE
1139         if (sc->sc_buffered_char[0]) {
1140                 return (1);
1141         }
1142 #endif
1143         if (sc->sc_inputs > 0) {
1144                 return (1);
1145         }
1146         return (0);
1147 }
1148
1149 /* check if char is waiting */
1150 static int
1151 ukbd_check_char(keyboard_t *kbd)
1152 {
1153         struct ukbd_softc *sc = kbd->kb_data;
1154
1155         if (!KBD_IS_ACTIVE(kbd))
1156                 return (0);
1157
1158         if (sc->sc_flags & UKBD_FLAG_POLLING) {
1159                 if (!mtx_owned(&Giant)) {
1160                         /* XXX cludge */
1161                         int retval;
1162                         mtx_lock(&Giant);
1163                         retval = ukbd_check_char(kbd);
1164                         mtx_unlock(&Giant);
1165                         return (retval);
1166                 }
1167         } else {
1168                 /* XXX the keyboard layer requires Giant */
1169                 if (!mtx_owned(&Giant))
1170                         return (0);
1171         }
1172
1173         /* check if key belongs to this thread */
1174         if (ukbd_polls_other_thread(sc))
1175                 return (0);
1176
1177         if ((sc->sc_composed_char > 0) &&
1178             (!(sc->sc_flags & UKBD_FLAG_COMPOSE))) {
1179                 return (1);
1180         }
1181         return (ukbd_check(kbd));
1182 }
1183
1184
1185 /* read one byte from the keyboard if it's allowed */
1186 static int
1187 ukbd_read(keyboard_t *kbd, int wait)
1188 {
1189         struct ukbd_softc *sc = kbd->kb_data;
1190         int32_t usbcode;
1191
1192 #ifdef UKBD_EMULATE_ATSCANCODE
1193         uint32_t keycode;
1194         uint32_t scancode;
1195
1196 #endif
1197         if (!KBD_IS_ACTIVE(kbd))
1198                 return (-1);
1199
1200         if (sc->sc_flags & UKBD_FLAG_POLLING) {
1201                 if (!mtx_owned(&Giant)) {
1202                         /* XXX cludge */
1203                         int retval;
1204                         mtx_lock(&Giant);
1205                         retval = ukbd_read(kbd, wait);
1206                         mtx_unlock(&Giant);
1207                         return (retval);
1208                 }
1209         } else {
1210                 /* XXX the keyboard layer requires Giant */
1211                 if (!mtx_owned(&Giant))
1212                         return (-1);
1213         }
1214
1215         /* check if key belongs to this thread */
1216         if (ukbd_polls_other_thread(sc))
1217                 return (-1);
1218
1219 #ifdef UKBD_EMULATE_ATSCANCODE
1220         if (sc->sc_buffered_char[0]) {
1221                 scancode = sc->sc_buffered_char[0];
1222                 if (scancode & SCAN_PREFIX) {
1223                         sc->sc_buffered_char[0] &= ~SCAN_PREFIX;
1224                         return ((scancode & SCAN_PREFIX_E0) ? 0xe0 : 0xe1);
1225                 }
1226                 sc->sc_buffered_char[0] = sc->sc_buffered_char[1];
1227                 sc->sc_buffered_char[1] = 0;
1228                 return (scancode);
1229         }
1230 #endif                                  /* UKBD_EMULATE_ATSCANCODE */
1231
1232         /* XXX */
1233         usbcode = ukbd_get_key(sc, (wait == FALSE) ? 0 : 1);
1234         if (!KBD_IS_ACTIVE(kbd) || (usbcode == -1))
1235                 return (-1);
1236
1237         ++(kbd->kb_count);
1238
1239 #ifdef UKBD_EMULATE_ATSCANCODE
1240         keycode = ukbd_trtab[KEY_INDEX(usbcode)];
1241         if (keycode == NN) {
1242                 return -1;
1243         }
1244         return (ukbd_key2scan(sc, keycode, sc->sc_ndata.modifiers,
1245             (usbcode & KEY_RELEASE)));
1246 #else                                   /* !UKBD_EMULATE_ATSCANCODE */
1247         return (usbcode);
1248 #endif                                  /* UKBD_EMULATE_ATSCANCODE */
1249 }
1250
1251 /* read char from the keyboard */
1252 static uint32_t
1253 ukbd_read_char(keyboard_t *kbd, int wait)
1254 {
1255         struct ukbd_softc *sc = kbd->kb_data;
1256         uint32_t action;
1257         uint32_t keycode;
1258         int32_t usbcode;
1259
1260 #ifdef UKBD_EMULATE_ATSCANCODE
1261         uint32_t scancode;
1262
1263 #endif
1264
1265         if (!KBD_IS_ACTIVE(kbd))
1266                 return (NOKEY);
1267
1268         if (sc->sc_flags & UKBD_FLAG_POLLING) {
1269                 if (!mtx_owned(&Giant)) {
1270                         /* XXX cludge */
1271                         int retval;
1272                         mtx_lock(&Giant);
1273                         retval = ukbd_read_char(kbd, wait);
1274                         mtx_unlock(&Giant);
1275                         return (retval);
1276                 }
1277         } else {
1278                 /* XXX the keyboard layer requires Giant */
1279                 if (!mtx_owned(&Giant))
1280                         return (NOKEY);
1281         }
1282
1283         /* check if key belongs to this thread */
1284         if (ukbd_polls_other_thread(sc))
1285                 return (NOKEY);
1286
1287 next_code:
1288
1289         /* do we have a composed char to return ? */
1290
1291         if ((sc->sc_composed_char > 0) &&
1292             (!(sc->sc_flags & UKBD_FLAG_COMPOSE))) {
1293
1294                 action = sc->sc_composed_char;
1295                 sc->sc_composed_char = 0;
1296
1297                 if (action > 0xFF) {
1298                         goto errkey;
1299                 }
1300                 goto done;
1301         }
1302 #ifdef UKBD_EMULATE_ATSCANCODE
1303
1304         /* do we have a pending raw scan code? */
1305
1306         if (sc->sc_mode == K_RAW) {
1307                 scancode = sc->sc_buffered_char[0];
1308                 if (scancode) {
1309                         if (scancode & SCAN_PREFIX) {
1310                                 sc->sc_buffered_char[0] = (scancode & ~SCAN_PREFIX);
1311                                 return ((scancode & SCAN_PREFIX_E0) ? 0xe0 : 0xe1);
1312                         }
1313                         sc->sc_buffered_char[0] = sc->sc_buffered_char[1];
1314                         sc->sc_buffered_char[1] = 0;
1315                         return (scancode);
1316                 }
1317         }
1318 #endif                                  /* UKBD_EMULATE_ATSCANCODE */
1319
1320         /* see if there is something in the keyboard port */
1321         /* XXX */
1322         usbcode = ukbd_get_key(sc, (wait == FALSE) ? 0 : 1);
1323         if (usbcode == -1) {
1324                 return (NOKEY);
1325         }
1326         ++kbd->kb_count;
1327
1328 #ifdef UKBD_EMULATE_ATSCANCODE
1329         /* USB key index -> key code -> AT scan code */
1330         keycode = ukbd_trtab[KEY_INDEX(usbcode)];
1331         if (keycode == NN) {
1332                 return (NOKEY);
1333         }
1334         /* return an AT scan code for the K_RAW mode */
1335         if (sc->sc_mode == K_RAW) {
1336                 return (ukbd_key2scan(sc, keycode, sc->sc_ndata.modifiers,
1337                     (usbcode & KEY_RELEASE)));
1338         }
1339 #else                                   /* !UKBD_EMULATE_ATSCANCODE */
1340
1341         /* return the byte as is for the K_RAW mode */
1342         if (sc->sc_mode == K_RAW) {
1343                 return (usbcode);
1344         }
1345         /* USB key index -> key code */
1346         keycode = ukbd_trtab[KEY_INDEX(usbcode)];
1347         if (keycode == NN) {
1348                 return (NOKEY);
1349         }
1350 #endif                                  /* UKBD_EMULATE_ATSCANCODE */
1351
1352         switch (keycode) {
1353         case 0x38:                      /* left alt (compose key) */
1354                 if (usbcode & KEY_RELEASE) {
1355                         if (sc->sc_flags & UKBD_FLAG_COMPOSE) {
1356                                 sc->sc_flags &= ~UKBD_FLAG_COMPOSE;
1357
1358                                 if (sc->sc_composed_char > 0xFF) {
1359                                         sc->sc_composed_char = 0;
1360                                 }
1361                         }
1362                 } else {
1363                         if (!(sc->sc_flags & UKBD_FLAG_COMPOSE)) {
1364                                 sc->sc_flags |= UKBD_FLAG_COMPOSE;
1365                                 sc->sc_composed_char = 0;
1366                         }
1367                 }
1368                 break;
1369                 /* XXX: I don't like these... */
1370         case 0x5c:                      /* print screen */
1371                 if (sc->sc_flags & ALTS) {
1372                         keycode = 0x54; /* sysrq */
1373                 }
1374                 break;
1375         case 0x68:                      /* pause/break */
1376                 if (sc->sc_flags & CTLS) {
1377                         keycode = 0x6c; /* break */
1378                 }
1379                 break;
1380         }
1381
1382         /* return the key code in the K_CODE mode */
1383         if (usbcode & KEY_RELEASE) {
1384                 keycode |= SCAN_RELEASE;
1385         }
1386         if (sc->sc_mode == K_CODE) {
1387                 return (keycode);
1388         }
1389         /* compose a character code */
1390         if (sc->sc_flags & UKBD_FLAG_COMPOSE) {
1391                 switch (keycode) {
1392                         /* key pressed, process it */
1393                 case 0x47:
1394                 case 0x48:
1395                 case 0x49:              /* keypad 7,8,9 */
1396                         sc->sc_composed_char *= 10;
1397                         sc->sc_composed_char += keycode - 0x40;
1398                         goto check_composed;
1399
1400                 case 0x4B:
1401                 case 0x4C:
1402                 case 0x4D:              /* keypad 4,5,6 */
1403                         sc->sc_composed_char *= 10;
1404                         sc->sc_composed_char += keycode - 0x47;
1405                         goto check_composed;
1406
1407                 case 0x4F:
1408                 case 0x50:
1409                 case 0x51:              /* keypad 1,2,3 */
1410                         sc->sc_composed_char *= 10;
1411                         sc->sc_composed_char += keycode - 0x4E;
1412                         goto check_composed;
1413
1414                 case 0x52:              /* keypad 0 */
1415                         sc->sc_composed_char *= 10;
1416                         goto check_composed;
1417
1418                         /* key released, no interest here */
1419                 case SCAN_RELEASE | 0x47:
1420                 case SCAN_RELEASE | 0x48:
1421                 case SCAN_RELEASE | 0x49:       /* keypad 7,8,9 */
1422                 case SCAN_RELEASE | 0x4B:
1423                 case SCAN_RELEASE | 0x4C:
1424                 case SCAN_RELEASE | 0x4D:       /* keypad 4,5,6 */
1425                 case SCAN_RELEASE | 0x4F:
1426                 case SCAN_RELEASE | 0x50:
1427                 case SCAN_RELEASE | 0x51:       /* keypad 1,2,3 */
1428                 case SCAN_RELEASE | 0x52:       /* keypad 0 */
1429                         goto next_code;
1430
1431                 case 0x38:              /* left alt key */
1432                         break;
1433
1434                 default:
1435                         if (sc->sc_composed_char > 0) {
1436                                 sc->sc_flags &= ~UKBD_FLAG_COMPOSE;
1437                                 sc->sc_composed_char = 0;
1438                                 goto errkey;
1439                         }
1440                         break;
1441                 }
1442         }
1443         /* keycode to key action */
1444         action = genkbd_keyaction(kbd, SCAN_CHAR(keycode),
1445             (keycode & SCAN_RELEASE),
1446             &sc->sc_state, &sc->sc_accents);
1447         if (action == NOKEY) {
1448                 goto next_code;
1449         }
1450 done:
1451         return (action);
1452
1453 check_composed:
1454         if (sc->sc_composed_char <= 0xFF) {
1455                 goto next_code;
1456         }
1457 errkey:
1458         return (ERRKEY);
1459 }
1460
1461 /* some useful control functions */
1462 static int
1463 ukbd_ioctl(keyboard_t *kbd, u_long cmd, caddr_t arg)
1464 {
1465         /* translate LED_XXX bits into the device specific bits */
1466         static const uint8_t ledmap[8] = {
1467                 0, 2, 1, 3, 4, 6, 5, 7,
1468         };
1469         struct ukbd_softc *sc = kbd->kb_data;
1470         int i;
1471
1472 #if defined(COMPAT_FREEBSD6) || defined(COMPAT_FREEBSD5) || \
1473     defined(COMPAT_FREEBSD4) || defined(COMPAT_43)
1474         int ival;
1475
1476 #endif
1477         if (!mtx_owned(&Giant)) {
1478                 /*
1479                  * XXX big problem: If scroll lock is pressed and "printf()"
1480                  * is called, the CPU will get here, to un-scroll lock the
1481                  * keyboard. But if "printf()" acquires the "Giant" lock,
1482                  * there will be a locking order reversal problem, so the
1483                  * keyboard system must get out of "Giant" first, before the
1484                  * CPU can proceed here ...
1485                  */
1486                 switch (cmd) {
1487                 case KDGKBMODE:
1488                 case KDSKBMODE:
1489                         /* workaround for Geli */
1490                         mtx_lock(&Giant);
1491                         i = ukbd_ioctl(kbd, cmd, arg);
1492                         mtx_unlock(&Giant);
1493                         return (i);
1494                 default:
1495                         return (EINVAL);
1496                 }
1497         }
1498
1499         switch (cmd) {
1500         case KDGKBMODE:         /* get keyboard mode */
1501                 *(int *)arg = sc->sc_mode;
1502                 break;
1503 #if defined(COMPAT_FREEBSD6) || defined(COMPAT_FREEBSD5) || \
1504     defined(COMPAT_FREEBSD4) || defined(COMPAT_43)
1505         case _IO('K', 7):
1506                 ival = IOCPARM_IVAL(arg);
1507                 arg = (caddr_t)&ival;
1508                 /* FALLTHROUGH */
1509 #endif
1510         case KDSKBMODE:         /* set keyboard mode */
1511                 switch (*(int *)arg) {
1512                 case K_XLATE:
1513                         if (sc->sc_mode != K_XLATE) {
1514                                 /* make lock key state and LED state match */
1515                                 sc->sc_state &= ~LOCK_MASK;
1516                                 sc->sc_state |= KBD_LED_VAL(kbd);
1517                         }
1518                         /* FALLTHROUGH */
1519                 case K_RAW:
1520                 case K_CODE:
1521                         if (sc->sc_mode != *(int *)arg) {
1522                                 if (ukbd_is_polling(sc) == 0)
1523                                         ukbd_clear_state(kbd);
1524                                 sc->sc_mode = *(int *)arg;
1525                         }
1526                         break;
1527                 default:
1528                         return (EINVAL);
1529                 }
1530                 break;
1531
1532         case KDGETLED:                  /* get keyboard LED */
1533                 *(int *)arg = KBD_LED_VAL(kbd);
1534                 break;
1535 #if defined(COMPAT_FREEBSD6) || defined(COMPAT_FREEBSD5) || \
1536     defined(COMPAT_FREEBSD4) || defined(COMPAT_43)
1537         case _IO('K', 66):
1538                 ival = IOCPARM_IVAL(arg);
1539                 arg = (caddr_t)&ival;
1540                 /* FALLTHROUGH */
1541 #endif
1542         case KDSETLED:                  /* set keyboard LED */
1543                 /* NOTE: lock key state in "sc_state" won't be changed */
1544                 if (*(int *)arg & ~LOCK_MASK) {
1545                         return (EINVAL);
1546                 }
1547                 i = *(int *)arg;
1548                 /* replace CAPS LED with ALTGR LED for ALTGR keyboards */
1549                 if (sc->sc_mode == K_XLATE &&
1550                     kbd->kb_keymap->n_keys > ALTGR_OFFSET) {
1551                         if (i & ALKED)
1552                                 i |= CLKED;
1553                         else
1554                                 i &= ~CLKED;
1555                 }
1556                 if (KBD_HAS_DEVICE(kbd)) {
1557                         ukbd_set_leds(sc, ledmap[i & LED_MASK]);
1558                 }
1559                 KBD_LED_VAL(kbd) = *(int *)arg;
1560                 break;
1561         case KDGKBSTATE:                /* get lock key state */
1562                 *(int *)arg = sc->sc_state & LOCK_MASK;
1563                 break;
1564 #if defined(COMPAT_FREEBSD6) || defined(COMPAT_FREEBSD5) || \
1565     defined(COMPAT_FREEBSD4) || defined(COMPAT_43)
1566         case _IO('K', 20):
1567                 ival = IOCPARM_IVAL(arg);
1568                 arg = (caddr_t)&ival;
1569                 /* FALLTHROUGH */
1570 #endif
1571         case KDSKBSTATE:                /* set lock key state */
1572                 if (*(int *)arg & ~LOCK_MASK) {
1573                         return (EINVAL);
1574                 }
1575                 sc->sc_state &= ~LOCK_MASK;
1576                 sc->sc_state |= *(int *)arg;
1577
1578                 /* set LEDs and quit */
1579                 return (ukbd_ioctl(kbd, KDSETLED, arg));
1580
1581         case KDSETREPEAT:               /* set keyboard repeat rate (new
1582                                          * interface) */
1583                 if (!KBD_HAS_DEVICE(kbd)) {
1584                         return (0);
1585                 }
1586                 if (((int *)arg)[1] < 0) {
1587                         return (EINVAL);
1588                 }
1589                 if (((int *)arg)[0] < 0) {
1590                         return (EINVAL);
1591                 }
1592                 if (((int *)arg)[0] < 200)      /* fastest possible value */
1593                         kbd->kb_delay1 = 200;
1594                 else
1595                         kbd->kb_delay1 = ((int *)arg)[0];
1596                 kbd->kb_delay2 = ((int *)arg)[1];
1597                 return (0);
1598
1599 #if defined(COMPAT_FREEBSD6) || defined(COMPAT_FREEBSD5) || \
1600     defined(COMPAT_FREEBSD4) || defined(COMPAT_43)
1601         case _IO('K', 67):
1602                 ival = IOCPARM_IVAL(arg);
1603                 arg = (caddr_t)&ival;
1604                 /* FALLTHROUGH */
1605 #endif
1606         case KDSETRAD:                  /* set keyboard repeat rate (old
1607                                          * interface) */
1608                 return (ukbd_set_typematic(kbd, *(int *)arg));
1609
1610         case PIO_KEYMAP:                /* set keyboard translation table */
1611         case PIO_KEYMAPENT:             /* set keyboard translation table
1612                                          * entry */
1613         case PIO_DEADKEYMAP:            /* set accent key translation table */
1614                 sc->sc_accents = 0;
1615                 /* FALLTHROUGH */
1616         default:
1617                 return (genkbd_commonioctl(kbd, cmd, arg));
1618         }
1619
1620         return (0);
1621 }
1622
1623 /* clear the internal state of the keyboard */
1624 static void
1625 ukbd_clear_state(keyboard_t *kbd)
1626 {
1627         struct ukbd_softc *sc = kbd->kb_data;
1628
1629         if (!mtx_owned(&Giant)) {
1630                 /* XXX cludge */
1631                 mtx_lock(&Giant);
1632                 ukbd_clear_state(kbd);
1633                 mtx_unlock(&Giant);
1634                 return;
1635         }
1636
1637         sc->sc_flags &= ~(UKBD_FLAG_COMPOSE | UKBD_FLAG_POLLING);
1638         sc->sc_state &= LOCK_MASK;      /* preserve locking key state */
1639         sc->sc_accents = 0;
1640         sc->sc_composed_char = 0;
1641 #ifdef UKBD_EMULATE_ATSCANCODE
1642         sc->sc_buffered_char[0] = 0;
1643         sc->sc_buffered_char[1] = 0;
1644 #endif
1645         memset(&sc->sc_ndata, 0, sizeof(sc->sc_ndata));
1646         memset(&sc->sc_odata, 0, sizeof(sc->sc_odata));
1647         memset(&sc->sc_ntime, 0, sizeof(sc->sc_ntime));
1648         memset(&sc->sc_otime, 0, sizeof(sc->sc_otime));
1649 }
1650
1651 /* save the internal state, not used */
1652 static int
1653 ukbd_get_state(keyboard_t *kbd, void *buf, size_t len)
1654 {
1655         return (len == 0) ? 1 : -1;
1656 }
1657
1658 /* set the internal state, not used */
1659 static int
1660 ukbd_set_state(keyboard_t *kbd, void *buf, size_t len)
1661 {
1662         return (EINVAL);
1663 }
1664
1665 static int
1666 ukbd_is_polling(struct ukbd_softc *sc)
1667 {
1668         int delta;
1669
1670         if (sc->sc_flags & UKBD_FLAG_POLLING)
1671                 return (1);     /* polling */
1672
1673         delta = ticks - sc->sc_poll_tick_last;
1674         if ((delta < 0) || (delta >= hz)) {
1675                 sc->sc_poll_detected = 0;
1676                 return (0);             /* not polling */
1677         }
1678
1679         return (sc->sc_poll_detected);
1680 }
1681
1682 static int
1683 ukbd_polls_other_thread(struct ukbd_softc *sc)
1684 {
1685         return (ukbd_is_polling(sc) &&
1686             (sc->sc_poll_thread != curthread));
1687 }
1688
1689 static int
1690 ukbd_poll(keyboard_t *kbd, int on)
1691 {
1692         struct ukbd_softc *sc = kbd->kb_data;
1693
1694         if (!mtx_owned(&Giant)) {
1695                 /* XXX cludge */
1696                 int retval;
1697                 mtx_lock(&Giant);
1698                 retval = ukbd_poll(kbd, on);
1699                 mtx_unlock(&Giant);
1700                 return (retval);
1701         }
1702
1703         if (on) {
1704                 sc->sc_flags |= UKBD_FLAG_POLLING;
1705                 sc->sc_poll_thread = curthread;
1706         } else {
1707                 sc->sc_flags &= ~UKBD_FLAG_POLLING;
1708                 ukbd_start_timer(sc);   /* start timer */
1709         }
1710         return (0);
1711 }
1712
1713 /* local functions */
1714
1715 static void
1716 ukbd_set_leds(struct ukbd_softc *sc, uint8_t leds)
1717 {
1718         DPRINTF("leds=0x%02x\n", leds);
1719
1720         sc->sc_leds = leds;
1721         sc->sc_flags |= UKBD_FLAG_SET_LEDS;
1722
1723         /* start transfer, if not already started */
1724
1725         usbd_transfer_start(sc->sc_xfer[UKBD_CTRL_LED]);
1726 }
1727
1728 static int
1729 ukbd_set_typematic(keyboard_t *kbd, int code)
1730 {
1731         static const int delays[] = {250, 500, 750, 1000};
1732         static const int rates[] = {34, 38, 42, 46, 50, 55, 59, 63,
1733                 68, 76, 84, 92, 100, 110, 118, 126,
1734                 136, 152, 168, 184, 200, 220, 236, 252,
1735         272, 304, 336, 368, 400, 440, 472, 504};
1736
1737         if (code & ~0x7f) {
1738                 return (EINVAL);
1739         }
1740         kbd->kb_delay1 = delays[(code >> 5) & 3];
1741         kbd->kb_delay2 = rates[code & 0x1f];
1742         return (0);
1743 }
1744
1745 #ifdef UKBD_EMULATE_ATSCANCODE
1746 static int
1747 ukbd_key2scan(struct ukbd_softc *sc, int code, int shift, int up)
1748 {
1749         static const int scan[] = {
1750                 /* 89 */
1751                 0x11c,  /* Enter */
1752                 /* 90-99 */
1753                 0x11d,  /* Ctrl-R */
1754                 0x135,  /* Divide */
1755                 0x137 | SCAN_PREFIX_SHIFT,      /* PrintScreen */
1756                 0x138,  /* Alt-R */
1757                 0x147,  /* Home */
1758                 0x148,  /* Up */
1759                 0x149,  /* PageUp */
1760                 0x14b,  /* Left */
1761                 0x14d,  /* Right */
1762                 0x14f,  /* End */
1763                 /* 100-109 */
1764                 0x150,  /* Down */
1765                 0x151,  /* PageDown */
1766                 0x152,  /* Insert */
1767                 0x153,  /* Delete */
1768                 0x146,  /* XXX Pause/Break */
1769                 0x15b,  /* Win_L(Super_L) */
1770                 0x15c,  /* Win_R(Super_R) */
1771                 0x15d,  /* Application(Menu) */
1772
1773                 /* SUN TYPE 6 USB KEYBOARD */
1774                 0x168,  /* Sun Type 6 Help */
1775                 0x15e,  /* Sun Type 6 Stop */
1776                 /* 110 - 119 */
1777                 0x15f,  /* Sun Type 6 Again */
1778                 0x160,  /* Sun Type 6 Props */
1779                 0x161,  /* Sun Type 6 Undo */
1780                 0x162,  /* Sun Type 6 Front */
1781                 0x163,  /* Sun Type 6 Copy */
1782                 0x164,  /* Sun Type 6 Open */
1783                 0x165,  /* Sun Type 6 Paste */
1784                 0x166,  /* Sun Type 6 Find */
1785                 0x167,  /* Sun Type 6 Cut */
1786                 0x125,  /* Sun Type 6 Mute */
1787                 /* 120 - 128 */
1788                 0x11f,  /* Sun Type 6 VolumeDown */
1789                 0x11e,  /* Sun Type 6 VolumeUp */
1790                 0x120,  /* Sun Type 6 PowerDown */
1791
1792                 /* Japanese 106/109 keyboard */
1793                 0x73,   /* Keyboard Intl' 1 (backslash / underscore) */
1794                 0x70,   /* Keyboard Intl' 2 (Katakana / Hiragana) */
1795                 0x7d,   /* Keyboard Intl' 3 (Yen sign) (Not using in jp106/109) */
1796                 0x79,   /* Keyboard Intl' 4 (Henkan) */
1797                 0x7b,   /* Keyboard Intl' 5 (Muhenkan) */
1798                 0x5c,   /* Keyboard Intl' 6 (Keypad ,) (For PC-9821 layout) */
1799         };
1800
1801         if ((code >= 89) && (code < (89 + (sizeof(scan) / sizeof(scan[0]))))) {
1802                 code = scan[code - 89];
1803         }
1804         /* Pause/Break */
1805         if ((code == 104) && (!(shift & (MOD_CONTROL_L | MOD_CONTROL_R)))) {
1806                 code = (0x45 | SCAN_PREFIX_E1 | SCAN_PREFIX_CTL);
1807         }
1808         if (shift & (MOD_SHIFT_L | MOD_SHIFT_R)) {
1809                 code &= ~SCAN_PREFIX_SHIFT;
1810         }
1811         code |= (up ? SCAN_RELEASE : SCAN_PRESS);
1812
1813         if (code & SCAN_PREFIX) {
1814                 if (code & SCAN_PREFIX_CTL) {
1815                         /* Ctrl */
1816                         sc->sc_buffered_char[0] = (0x1d | (code & SCAN_RELEASE));
1817                         sc->sc_buffered_char[1] = (code & ~SCAN_PREFIX);
1818                 } else if (code & SCAN_PREFIX_SHIFT) {
1819                         /* Shift */
1820                         sc->sc_buffered_char[0] = (0x2a | (code & SCAN_RELEASE));
1821                         sc->sc_buffered_char[1] = (code & ~SCAN_PREFIX_SHIFT);
1822                 } else {
1823                         sc->sc_buffered_char[0] = (code & ~SCAN_PREFIX);
1824                         sc->sc_buffered_char[1] = 0;
1825                 }
1826                 return ((code & SCAN_PREFIX_E0) ? 0xe0 : 0xe1);
1827         }
1828         return (code);
1829
1830 }
1831
1832 #endif                                  /* UKBD_EMULATE_ATSCANCODE */
1833
1834 static keyboard_switch_t ukbdsw = {
1835         .probe = &ukbd__probe,
1836         .init = &ukbd_init,
1837         .term = &ukbd_term,
1838         .intr = &ukbd_intr,
1839         .test_if = &ukbd_test_if,
1840         .enable = &ukbd_enable,
1841         .disable = &ukbd_disable,
1842         .read = &ukbd_read,
1843         .check = &ukbd_check,
1844         .read_char = &ukbd_read_char,
1845         .check_char = &ukbd_check_char,
1846         .ioctl = &ukbd_ioctl,
1847         .lock = &ukbd_lock,
1848         .clear_state = &ukbd_clear_state,
1849         .get_state = &ukbd_get_state,
1850         .set_state = &ukbd_set_state,
1851         .get_fkeystr = &genkbd_get_fkeystr,
1852         .poll = &ukbd_poll,
1853         .diag = &genkbd_diag,
1854 };
1855
1856 KEYBOARD_DRIVER(ukbd, ukbdsw, ukbd_configure);
1857
1858 static int
1859 ukbd_driver_load(module_t mod, int what, void *arg)
1860 {
1861         switch (what) {
1862         case MOD_LOAD:
1863                 kbd_add_driver(&ukbd_kbd_driver);
1864                 break;
1865         case MOD_UNLOAD:
1866                 kbd_delete_driver(&ukbd_kbd_driver);
1867                 break;
1868         }
1869         return (0);
1870 }
1871
1872 static devclass_t ukbd_devclass;
1873
1874 static device_method_t ukbd_methods[] = {
1875         DEVMETHOD(device_probe, ukbd_probe),
1876         DEVMETHOD(device_attach, ukbd_attach),
1877         DEVMETHOD(device_detach, ukbd_detach),
1878         DEVMETHOD(device_resume, ukbd_resume),
1879         {0, 0}
1880 };
1881
1882 static driver_t ukbd_driver = {
1883         .name = "ukbd",
1884         .methods = ukbd_methods,
1885         .size = sizeof(struct ukbd_softc),
1886 };
1887
1888 DRIVER_MODULE(ukbd, uhub, ukbd_driver, ukbd_devclass, ukbd_driver_load, 0);
1889 MODULE_DEPEND(ukbd, usb, 1, 1, 1);