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