kbtrans.h revision 10617:ae54b3d31f50 
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
36extern "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 */
55struct kbtrans_hardware;
56
57struct kbtrans;
58
59enum kbtrans_message_response {
60	KBTRANS_MESSAGE_HANDLED = 0,
61	KBTRANS_MESSAGE_NOT_HANDLED = 1
62};
63
64typedef boolean_t (*polled_keycode_func)(struct kbtrans_hardware *,
65			kbtrans_key_t *, enum keystate *);
66struct 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 */
76struct 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 */
120extern 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 */
129extern 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 */
146extern 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 */
158extern 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 */
169extern 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 */
185extern 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 */
197extern boolean_t kbtrans_ischar(struct kbtrans *);
198extern 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 */
205extern 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 */
211extern void kbtrans_streams_setled(struct kbtrans *, int);
212
213/*
214 * kbtrans_streams_releaseall():
215 *	Release all the keys that are held down.
216 */
217extern void kbtrans_streams_releaseall(struct kbtrans *);
218
219/*
220 * kbtrans_streams_set_queue():
221 *      Change the queue above the device, to support multiplexors.
222 */
223extern 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 */
229extern queue_t *kbtrans_streams_get_queue(struct kbtrans *);
230
231/*
232 * kbtrans_streams_untimeout():
233 * Clear timeout
234 */
235extern void kbtrans_streams_untimeout(struct kbtrans *);
236
237#ifdef __cplusplus
238}
239#endif
240
241#endif /* _SYS_KBTRANS_H */
242