xref: /illumos-gate/usr/src/uts/common/sys/kbtrans.h (revision cd2135d041662c75017487e2d4b9b69b7e0b8349)
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 */
242