include/sys/kbtrans.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License (the "License").
   6  * You may not use this file except in compliance with the License.
   7  *
   8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9  * or http://www.opensolaris.org/os/licensing.
  10  * See the License for the specific language governing permissions
  11  * and limitations under the License.
  12  *
  13  * When distributing Covered Code, include this CDDL HEADER in each
  14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15  * If applicable, add the following below this CDDL HEADER, with the
  16  * fields enclosed by brackets "[]" replaced with your own identifying
  17  * information: Portions Copyright [yyyy] [name of copyright owner]
  18  *
  19  * CDDL HEADER END
  20  */
  21
  22 /*
  23  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
  24  * Use is subject to license terms.
  25  */
  26
  27 #ifndef _SYS_KBTRANS_H
  28 #define _SYS_KBTRANS_H
  29
  30 /*
  31  * Interface between hardware keyboard driver and generic keyboard
  32  * translation module.
  33  */
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 #include <sys/consdev.h>
  40
  41 /*
  42  * The default value (0) indicates that the keyboard layout isn't
  43  * configured in kernel.
  44  */
  45 #define KBTRANS_USBKB_DEFAULT_LAYOUT    0
  46
  47 /*
  48  * Maximum of keys in a keyboard
  49  */
  50 #define KBTRANS_KEYNUMS_MAX             255
  51
  52 /*
  53  * Do not expose the internals of these structures to kbtrans clients
  54  */
  55 struct kbtrans_hardware;
  56
  57 struct kbtrans;
  58
  59 enum kbtrans_message_response {
  60         KBTRANS_MESSAGE_HANDLED = 0,
  61         KBTRANS_MESSAGE_NOT_HANDLED = 1
  62 };
  63
  64 typedef boolean_t (*polled_keycode_func)(struct kbtrans_hardware *,
  65                         kbtrans_key_t *, enum keystate *);
  66 struct hw_polledio {
  67         void *polled_argument;
  68         polled_keycode_func *polled_keycode;
  69 };
  70
  71
  72
  73 /*
  74  * Callbacks registered by the hardware specific driver/module
  75  */
  76 struct kbtrans_callbacks {
  77
  78         /* Routine to set the LED's in non-polled mode */
  79         void (*kbtrans_streams_setled)(struct kbtrans_hardware *, int);
  80
  81         /* Routine to set the LED's in polled mode */
  82         void (*kbtrans_polled_setled)(struct kbtrans_hardware *, int);
  83
  84         /* Routine to indicate that a scande is available in polled mode */
  85         boolean_t (*kbtrans_polled_keycheck)(struct kbtrans_hardware *,
  86                 kbtrans_key_t *, enum keystate *);
  87 };
  88
  89 /*
  90  * kbtrans_streams_init():
  91  *
  92  * Initializes the generic keyboard translation module.  Must be
  93  * called from the hardware module's open(9e) routine.
  94  *
  95  * Arguments:
  96  *      - queue_t *q
  97  *              The read queue.
  98  *
  99  *      - int sflag
 100  *              sflag from the streams open routine
 101  *
 102  *      - struct kbtrans_hardware *hw
 103  *              hardware-specific data, passed to hardware callbacks
 104  *
 105  *      - struct kbtrans_callbacks *hw_callbacks
 106  *              hardware support callbacks (see below)
 107  *
 108  *      - struct kbtrans **kbtrans
 109  *              returned state structure pointer
 110  *
 111  *      - int initial_leds
 112  *      - int initial_led_mask
 113  *              Provides state information (if available) about the current
 114  *              keyboard state, in the form of LED state.  initial_leds shows
 115  *              which LEDs are lit; initial_led_mask shows which bits in
 116  *              initial_leds are valid.  This mechanism exists primarily to
 117  *              retain the existing state of NumLock across the transition
 118  *              from firmware to the OS.
 119  */
 120 extern int kbtrans_streams_init(queue_t *, int, struct kbtrans_hardware *,
 121         struct kbtrans_callbacks *, struct kbtrans **, int, int);
 122
 123 /*
 124  * kbtrans_streams_fini():
 125  *
 126  * Shuts down the generic translation module.  Must be called from
 127  * the hardware module's close(9e) routine.
 128  */
 129 extern int kbtrans_streams_fini(struct kbtrans *);
 130
 131 /*
 132  * kbtrans_streams_message():
 133  *
 134  * The hardware module should pass all streams messages received from
 135  * above to this routine.  The generic translation module will process
 136  * most of them, returning KBTRANS_MESSAGE_HANDLED for the ones that
 137  * it has handled and KBTRANS_MESSAGE_NOT_HANDLED for the ones that
 138  * it did not handle.  For KBTRANS_MESSAGE_HANDLED, the hardware module
 139  * should take no further action on the message.  For
 140  * KBTRANS_MESSAGE_NOT_HANDLED, the hardware module is responsible for
 141  * any action, including returning an appropriate error.
 142  *
 143  * Must be called from the hardware module's write put(9e) or srv(9e)
 144  * routine.
 145  */
 146 extern enum kbtrans_message_response kbtrans_streams_message(struct kbtrans *,
 147         mblk_t *);
 148
 149 /*
 150  * kbtrans_streams_key():
 151  *
 152  * When a key is pressed or released, the hardware module should
 153  * call kbtrans, passing the key number and its new
 154  * state.  kbtrans is responsible for autorepeat handling;
 155  * the hardware module should report only actual press/release
 156  * events, suppressing any hardware-generated autorepeat.
 157  */
 158 extern void kbtrans_streams_key(struct kbtrans *, kbtrans_key_t key,
 159         enum keystate state);
 160
 161 /*
 162  * kbtrans_streams_set_keyboard():
 163  *
 164  * At any time after calling kbtrans_streams_init, the hardware
 165  * module should make this call to report the type of keyboard
 166  * attached.  "type" is the keyboard type, typically KB_SUN4,
 167  * KB_PC, or KB_USB.
 168  */
 169 extern void kbtrans_streams_set_keyboard(struct kbtrans *, int,
 170         struct keyboard *);
 171
 172 /*
 173  * kbtrans_streams_has_reset():
 174  *
 175  * At any time between kbtrans_streams_init and kbtrans_streams_fini,
 176  * the hardware module can call this routine to report that the
 177  * keyboard has been reset, e.g. by being unplugged and reattached.
 178  *
 179  * This function is for use by keyboard devices that do not formally
 180  * support hotplug.  If the keyboard hardware spontaneously resets
 181  * itself in a case other than hotplug, this routine is called to
 182  * report the rest.
 183  *
 184  */
 185 extern void kbtrans_streams_has_reset(struct kbtrans *);
 186
 187 /*
 188  * kbtrans_ischar():
 189  * kbtrans_getchar():
 190  *
 191  * These routines are used for polled input, e.g. for kmdb or PROM
 192  * input.  Note that, with suitable casting, these routines are usable
 193  * as CONSOPENPOLLEDIO routines.
 194  *
 195  * May only be called from single-threaded code, e.g. kmdb.
 196  */
 197 extern boolean_t kbtrans_ischar(struct kbtrans *);
 198 extern int kbtrans_getchar(struct kbtrans *);
 199
 200 /*
 201  * kbtrans_streams_enable():
 202  *      Routine to be called from the hardware specific module when
 203  *      the stream is ready to take messages.
 204  */
 205 extern void kbtrans_streams_enable(struct kbtrans *);
 206
 207 /*
 208  * kbtrans_streams_setled():
 209  *      Routine to be called to only update the led state in kbtrans.
 210  */
 211 extern void kbtrans_streams_setled(struct kbtrans *, int);
 212
 213 /*
 214  * kbtrans_streams_releaseall():
 215  *      Release all the keys that are held down.
 216  */
 217 extern void kbtrans_streams_releaseall(struct kbtrans *);
 218
 219 /*
 220  * kbtrans_streams_set_queue():
 221  *      Change the queue above the device, to support multiplexors.
 222  */
 223 extern void kbtrans_streams_set_queue(struct kbtrans *, queue_t *);
 224
 225 /*
 226  * kbtrans_streams_get_queue():
 227  * Retrieve the current queue above the device.
 228  */
 229 extern queue_t *kbtrans_streams_get_queue(struct kbtrans *);
 230
 231 /*
 232  * kbtrans_streams_untimeout():
 233  * Clear timeout
 234  */
 235 extern void kbtrans_streams_untimeout(struct kbtrans *);
 236
 237 #ifdef __cplusplus
 238 }
 239 #endif
 240
 241 #endif /* _SYS_KBTRANS_H */