docs/how-to-build.md: use proper markup for directory names
[unleashed/tickless.git] / include / sys / kbtrans.h
blobe7c0d80cdda19c5cb442d76c44b6bcea1e1eec76
1 /*
2 * CDDL HEADER START
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.
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.
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]
19 * CDDL HEADER END
23 * Copyright 2009 Sun Microsystems, Inc. All rights reserved.
24 * Use is subject to license terms.
27 #ifndef _SYS_KBTRANS_H
28 #define _SYS_KBTRANS_H
31 * Interface between hardware keyboard driver and generic keyboard
32 * translation module.
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
39 #include <sys/consdev.h>
42 * The default value (0) indicates that the keyboard layout isn't
43 * configured in kernel.
45 #define KBTRANS_USBKB_DEFAULT_LAYOUT 0
48 * Maximum of keys in a keyboard
50 #define KBTRANS_KEYNUMS_MAX 255
53 * Do not expose the internals of these structures to kbtrans clients
55 struct kbtrans_hardware;
57 struct kbtrans;
59 enum kbtrans_message_response {
60 KBTRANS_MESSAGE_HANDLED = 0,
61 KBTRANS_MESSAGE_NOT_HANDLED = 1
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;
74 * Callbacks registered by the hardware specific driver/module
76 struct kbtrans_callbacks {
78 /* Routine to set the LED's in non-polled mode */
79 void (*kbtrans_streams_setled)(struct kbtrans_hardware *, int);
81 /* Routine to set the LED's in polled mode */
82 void (*kbtrans_polled_setled)(struct kbtrans_hardware *, int);
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 *);
90 * kbtrans_streams_init():
92 * Initializes the generic keyboard translation module. Must be
93 * called from the hardware module's open(9e) routine.
95 * Arguments:
96 * - queue_t *q
97 * The read queue.
99 * - int sflag
100 * sflag from the streams open routine
102 * - struct kbtrans_hardware *hw
103 * hardware-specific data, passed to hardware callbacks
105 * - struct kbtrans_callbacks *hw_callbacks
106 * hardware support callbacks (see below)
108 * - struct kbtrans **kbtrans
109 * returned state structure pointer
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.
120 extern int kbtrans_streams_init(queue_t *, int, struct kbtrans_hardware *,
121 struct kbtrans_callbacks *, struct kbtrans **, int, int);
124 * kbtrans_streams_fini():
126 * Shuts down the generic translation module. Must be called from
127 * the hardware module's close(9e) routine.
129 extern int kbtrans_streams_fini(struct kbtrans *);
132 * kbtrans_streams_message():
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.
143 * Must be called from the hardware module's write put(9e) or srv(9e)
144 * routine.
146 extern enum kbtrans_message_response kbtrans_streams_message(struct kbtrans *,
147 mblk_t *);
150 * kbtrans_streams_key():
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.
158 extern void kbtrans_streams_key(struct kbtrans *, kbtrans_key_t key,
159 enum keystate state);
162 * kbtrans_streams_set_keyboard():
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.
169 extern void kbtrans_streams_set_keyboard(struct kbtrans *, int,
170 struct keyboard *);
173 * kbtrans_streams_has_reset():
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.
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.
185 extern void kbtrans_streams_has_reset(struct kbtrans *);
188 * kbtrans_ischar():
189 * kbtrans_getchar():
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.
195 * May only be called from single-threaded code, e.g. kmdb.
197 extern boolean_t kbtrans_ischar(struct kbtrans *);
198 extern int kbtrans_getchar(struct kbtrans *);
201 * kbtrans_streams_enable():
202 * Routine to be called from the hardware specific module when
203 * the stream is ready to take messages.
205 extern void kbtrans_streams_enable(struct kbtrans *);
208 * kbtrans_streams_setled():
209 * Routine to be called to only update the led state in kbtrans.
211 extern void kbtrans_streams_setled(struct kbtrans *, int);
214 * kbtrans_streams_releaseall():
215 * Release all the keys that are held down.
217 extern void kbtrans_streams_releaseall(struct kbtrans *);
220 * kbtrans_streams_set_queue():
221 * Change the queue above the device, to support multiplexors.
223 extern void kbtrans_streams_set_queue(struct kbtrans *, queue_t *);
226 * kbtrans_streams_get_queue():
227 * Retrieve the current queue above the device.
229 extern queue_t *kbtrans_streams_get_queue(struct kbtrans *);
232 * kbtrans_streams_untimeout():
233 * Clear timeout
235 extern void kbtrans_streams_untimeout(struct kbtrans *);
237 #ifdef __cplusplus
239 #endif
241 #endif /* _SYS_KBTRANS_H */